structured_io v0.3.0 StructuredIO View Source
A process for performing I/O of structured data, such as markup or binary-encoded data.
Encoding
The process operates in either binary mode or Unicode mode, depending
on the functions you call. The functions named .binwrite
and .binread_*
put the process in binary mode. The functions named .write
and .read_*
put
the process in Unicode mode. Mixing the use of binary-mode functions and
Unicode-mode functions results in an error/0
.
When calling the .binread_*
functions, the result is a binary, regardless of
whether the data read is String.valid?/1
. In contrast, the .read_*
functions return an error/0
if the data read is not properly encoded
Unicode data.
Link to this section Summary
Functions
Reads data from the specified structured_io
beginning with the specified
from
and ending with the specified through
, using the specified timeout
(defaults to 5,000 milliseconds)
Reads data from the specified structured_io
if and until the specified
through
is encountered, including through
, using the specified timeout
(defaults to 5,000 milliseconds)
Reads data from the specified structured_io
if and until the specified to
is encountered, excluding to
, using the specified timeout
(defaults to
5,000 milliseconds)
Asynchronously writes the specified iodata
as a binary to the specified
structured_io
Reads data from the specified structured_io
beginning with the specified
from
and ending with the specified through
, using the specified timeout
(defaults to 5,000 milliseconds)
Reads data from the specified structured_io
if and until the specified
through
is encountered, including through
, using the specified timeout
(defaults to 5,000 milliseconds)
Reads data from the specified structured_io
if and until the specified to
is encountered, excluding to
, using the specified timeout
(defaults to
5,000 milliseconds)
Starts a StructuredIO
process without links (outside a
supervision tree) with the specified options
Starts a StructuredIO
process linked to the current process with
the specified options
Synchronously stops the specified structured_io
process with the specified
reason
(defaults to :normal
) and timeout
(defaults to infinity)
Asynchronously writes the specified chardata
as a binary to the specified
structured_io
Link to this section Types
An error result.
Link to this section Functions
binread_across(GenServer.server(), binary(), binary(), timeout()) :: binary() | error()
Reads data from the specified structured_io
beginning with the specified
from
and ending with the specified through
, using the specified timeout
(defaults to 5,000 milliseconds).
If the data read does not begin with from
, the result is an empty binary
(""
). Likewise, if through
is not encountered, the result is an empty
binary.
Examples
iex> {:ok, structured_io} = StructuredIO.start_link
iex> StructuredIO.binwrite structured_io,
...> <<0, 0, 0, 1, 2, 3, 255, 255>>
:ok
iex> StructuredIO.binread_across structured_io,
...> <<0, 0, 0>>,
...> <<255, 255, 255>>
""
iex> StructuredIO.binwrite structured_io,
...> <<255, 0, 0, 0, 4, 5, 6, 255, 255, 255>>
:ok
iex> StructuredIO.binread_across structured_io,
...> <<0, 0, 0>>,
...> <<255, 255, 255>>
<<0, 0, 0, 1, 2, 3, 255, 255, 255>>
iex> StructuredIO.binread_across structured_io,
...> <<0, 0, 0>>,
...> <<255, 255, 255>>
<<0, 0, 0, 4, 5, 6, 255, 255, 255>>
iex> StructuredIO.binread_across structured_io,
...> <<0, 0, 0>>,
...> <<255, 255, 255>>
""
iex> {:ok, structured_io} = StructuredIO.start_link
iex> StructuredIO.binwrite structured_io,
...> "<elem>"
:ok
iex> <<fragment1::binary-size(3), fragment2::binary>> = "😕"
iex> StructuredIO.binwrite structured_io,
...> fragment1
:ok
iex> StructuredIO.binread_across structured_io,
...> "<elem>",
...> "</elem>"
""
iex> StructuredIO.binwrite structured_io,
...> fragment2
:ok
iex> StructuredIO.binwrite structured_io,
...> "</elem>"
:ok
iex> StructuredIO.binread_across structured_io,
...> "<elem>",
...> "</elem>"
"<elem>😕</elem>"
iex> StructuredIO.binread_across structured_io,
...> "<elem>",
...> "</elem>"
""
binread_through(GenServer.server(), binary(), timeout()) :: binary() | error()
Reads data from the specified structured_io
if and until the specified
through
is encountered, including through
, using the specified timeout
(defaults to 5,000 milliseconds).
If through
is not encountered, the result is an empty binary (""
).
Examples
iex> {:ok, structured_io} = StructuredIO.start_link
iex> StructuredIO.binwrite structured_io,
...> <<1, 2, 3, 255, 255>>
:ok
iex> StructuredIO.binread_through structured_io,
...> <<255, 255, 255>>
""
iex> StructuredIO.binwrite structured_io,
...> <<255, 4, 5, 6, 255, 255, 255>>
:ok
iex> StructuredIO.binread_through structured_io,
...> <<255, 255, 255>>
<<1, 2, 3, 255, 255, 255>>
iex> StructuredIO.binread_through structured_io,
...> <<255, 255, 255>>
<<4, 5, 6, 255, 255, 255>>
iex> StructuredIO.binread_through structured_io,
...> <<255, 255, 255>>
""
iex> {:ok, structured_io} = StructuredIO.start_link
iex> <<fragment1::binary-size(3), fragment2::binary>> = "😕"
iex> StructuredIO.binwrite structured_io,
...> fragment1
:ok
iex> StructuredIO.binread_through structured_io,
...> "<br />"
""
iex> StructuredIO.binwrite structured_io,
...> fragment2
:ok
iex> StructuredIO.binwrite structured_io,
...> "<br />"
:ok
iex> StructuredIO.binread_through structured_io,
...> "<br />"
"😕<br />"
iex> StructuredIO.binread_through structured_io,
...> "<br />"
""
binread_to(GenServer.server(), binary(), timeout()) :: binary() | error()
Reads data from the specified structured_io
if and until the specified to
is encountered, excluding to
, using the specified timeout
(defaults to
5,000 milliseconds).
If to
is not encountered, the result is an empty binary (""
).
Examples
iex> {:ok, structured_io} = StructuredIO.start_link
iex> StructuredIO.binwrite structured_io,
...> <<1, 2, 3, 255, 255>>
:ok
iex> StructuredIO.binread_to structured_io,
...> <<255, 255, 255>>
""
iex> StructuredIO.binwrite structured_io,
...> <<255, 4, 5, 6, 255, 255, 255>>
:ok
iex> StructuredIO.binread_to structured_io,
...> <<255, 255, 255>>
<<1, 2, 3>>
iex> StructuredIO.binread_through structured_io,
...> <<255, 255, 255>>
<<255, 255, 255>>
iex> StructuredIO.binread_to structured_io,
...> <<255, 255, 255>>
<<4, 5, 6>>
iex> StructuredIO.binread_to structured_io,
...> <<255, 255, 255>>
""
iex> {:ok, structured_io} = StructuredIO.start_link
iex> <<fragment1::binary-size(3), fragment2::binary>> = "😕"
iex> StructuredIO.binwrite structured_io,
...> fragment1
:ok
iex> StructuredIO.binread_to structured_io,
...> "<br />"
""
iex> StructuredIO.binwrite structured_io,
...> fragment2
:ok
iex> StructuredIO.binwrite structured_io,
...> "<br />"
:ok
iex> StructuredIO.binread_to structured_io,
...> "<br />"
"😕"
iex> StructuredIO.binread_to structured_io,
...> "<br />"
""
binwrite(GenServer.server(), iodata()) :: :ok | error()
Asynchronously writes the specified iodata
as a binary to the specified
structured_io
.
See StructuredIO.binread_across/3
,
StructuredIO.binread_through/2
, and
StructuredIO.binread_to/2
for examples.
read_across(GenServer.server(), binary(), binary(), timeout()) :: binary() | error()
Reads data from the specified structured_io
beginning with the specified
from
and ending with the specified through
, using the specified timeout
(defaults to 5,000 milliseconds).
If the data read does not begin with from
, the result is an empty binary
(""
). Likewise, if through
is not encountered, the result is an empty
binary.
Examples
iex> {:ok, structured_io} = StructuredIO.start_link
iex> StructuredIO.write structured_io,
...> "<elem>foo</elem"
:ok
iex> StructuredIO.read_across structured_io,
...> "<elem>",
...> "</elem>"
""
iex> StructuredIO.write structured_io,
...> "><elem>bar</elem>"
:ok
iex> StructuredIO.read_across structured_io,
...> "<elem>",
...> "</elem>"
"<elem>foo</elem>"
iex> StructuredIO.read_across structured_io,
...> "<elem>",
...> "</elem>"
"<elem>bar</elem>"
iex> StructuredIO.read_across structured_io,
...> "<elem>",
...> "</elem>"
""
iex> {:ok, structured_io} = StructuredIO.start_link
iex> StructuredIO.write structured_io,
...> "<elem>"
:ok
iex> <<fragment1::binary-size(3), fragment2::binary>> = "😕"
iex> StructuredIO.write structured_io,
...> fragment1
:ok
iex> StructuredIO.read_across structured_io,
...> "<elem>",
...> "</elem>"
{:error,
"UnicodeConversionError: incomplete encoding starting at <<240, 159, 152>>"}
iex> StructuredIO.write structured_io,
...> fragment2
:ok
iex> StructuredIO.write structured_io,
...> "</elem>"
:ok
iex> StructuredIO.read_across structured_io,
...> "<elem>",
...> "</elem>"
"<elem>😕</elem>"
iex> StructuredIO.read_across structured_io,
...> "<elem>",
...> "</elem>"
""
read_through(GenServer.server(), binary(), timeout()) :: binary() | error()
Reads data from the specified structured_io
if and until the specified
through
is encountered, including through
, using the specified timeout
(defaults to 5,000 milliseconds).
If through
is not encountered, the result is an empty binary (""
).
Examples
iex> {:ok, structured_io} = StructuredIO.start_link
iex> StructuredIO.write structured_io,
...> "foo<br /"
:ok
iex> StructuredIO.read_through structured_io,
...> "<br />"
""
iex> StructuredIO.write structured_io,
...> ">bar<br />"
:ok
iex> StructuredIO.read_through structured_io,
...> "<br />"
"foo<br />"
iex> StructuredIO.read_through structured_io,
...> "<br />"
"bar<br />"
iex> StructuredIO.read_through structured_io,
...> "<br />"
""
iex> {:ok, structured_io} = StructuredIO.start_link
iex> <<fragment1::binary-size(3), fragment2::binary>> = "😕"
iex> StructuredIO.write structured_io,
...> fragment1
:ok
iex> StructuredIO.read_through structured_io,
...> "<br />"
{:error,
"UnicodeConversionError: incomplete encoding starting at <<240, 159, 152>>"}
iex> StructuredIO.write structured_io,
...> fragment2
:ok
iex> StructuredIO.write structured_io,
...> "<br />"
:ok
iex> StructuredIO.read_through structured_io,
...> "<br />"
"😕<br />"
iex> StructuredIO.read_through structured_io,
...> "<br />"
""
read_to(GenServer.server(), binary(), timeout()) :: binary() | error()
Reads data from the specified structured_io
if and until the specified to
is encountered, excluding to
, using the specified timeout
(defaults to
5,000 milliseconds).
If to
is not encountered, the result is an empty binary (""
).
Examples
iex> {:ok, structured_io} = StructuredIO.start_link
iex> StructuredIO.write structured_io,
...> "foo<br /"
:ok
iex> StructuredIO.read_to structured_io,
...> "<br />"
""
iex> StructuredIO.write structured_io,
...> ">bar<br />"
:ok
iex> StructuredIO.read_to structured_io,
...> "<br />"
"foo"
iex> StructuredIO.read_through structured_io,
...> "<br />"
"<br />"
iex> StructuredIO.read_to structured_io,
...> "<br />"
"bar"
iex> StructuredIO.read_to structured_io,
...> "<br />"
""
iex> {:ok, structured_io} = StructuredIO.start_link
iex> <<fragment1::binary-size(3), fragment2::binary>> = "😕"
iex> StructuredIO.write structured_io,
...> fragment1
:ok
iex> StructuredIO.read_to structured_io,
...> "<br />"
{:error,
"UnicodeConversionError: incomplete encoding starting at <<240, 159, 152>>"}
iex> StructuredIO.write structured_io,
...> fragment2
:ok
iex> StructuredIO.write structured_io,
...> "<br />"
:ok
iex> StructuredIO.read_to structured_io,
...> "<br />"
"😕"
iex> StructuredIO.read_to structured_io,
...> "<br />"
""
start(GenServer.options()) :: GenServer.on_start()
Starts a StructuredIO
process without links (outside a
supervision tree) with the specified options
.
See StructuredIO.start_link/2
.
start_link(GenServer.options()) :: GenServer.on_start()
Starts a StructuredIO
process linked to the current process with
the specified options
.
See StructuredIO.binread_across/3
,
StructuredIO.binread_through/2
,
StructuredIO.binread_to/2
, StructuredIO.read_across/3
,
StructuredIO.read_through/2
, and StructuredIO.read_to/2
for examples.
stop(GenServer.server(), term(), timeout()) :: :ok
Synchronously stops the specified structured_io
process with the specified
reason
(defaults to :normal
) and timeout
(defaults to infinity).
write(GenServer.server(), IO.chardata() | String.Chars.t()) :: :ok | error()
Asynchronously writes the specified chardata
as a binary to the specified
structured_io
.
See StructuredIO.read_across/3
,
StructuredIO.read_through/2
, and StructuredIO.read_to/2
for examples.