StructuredIO
StructuredIO resembles Elixir’s IO module. The difference is that whereas IO can handle a stream of bytes or lines, StructuredIO can handle a stream of structured data, such as markup or other application data.
You may find StructuredIO useful for reassembling application data that arrives in streaming fashion over TCP.
Example usage
Here’s a contrived example that shows how to read structured data from a stream.
This example depicts Unicode data, but binary data of any kind can be read and
written with the binread_across/3
and binwrite/2
functions.
iex> {:ok, structured_io} = StructuredIO.start_link
Now we have a running StructuredIO process.
iex> StructuredIO.write structured_io,
...> "<elem>foo</elem"
:ok
We’ve written some markup to the stream. Note that the <elem>
element is not
properly closed.
iex> StructuredIO.read_across structured_io,
...> "<elem>",
...> "</elem>"
""
No <elem>
element is read because the stream doesn’t contain a complete
element.
iex> StructuredIO.write structured_io,
...> "><elem>bar</elem>"
:ok
Now the first element is properly closed, and a second complete element has been written to the stream.
iex> StructuredIO.read_across structured_io,
...> "<elem>",
...> "</elem>"
"<elem>foo</elem>"
iex> StructuredIO.read_across structured_io,
...> "<elem>",
...> "</elem>"
"<elem>bar</elem>"
We’ve read one element at a time from the available data in the stream.
iex> StructuredIO.read_across structured_io,
...> "<elem>",
...> "</elem>"
""
No more elements can be read unless more data is written to the stream.
iex> StructuredIO.stop structured_io
:ok
Don’t forget to stop the process when you’re finished reading from the stream.
You’ll find more detailed examples in the documentation for the StructuredIO module.
Installation
The package can be installed by adding :structured_io
to the list of
dependencies in your project’s mix.exs file:
def deps do
[
{:structured_io, "~> 0.1.0"}
]
end
Contributing
After cloning the repository, mix deps.get
to install dependencies. Then mix
test
to run the tests. You can also iex
to get an interactive prompt that
will allow you to experiment.
To release a new version:
- Update the project history in History.md, and then commit.
- Update the version number in mix.exs and in all package definitions, respecting Semantic Versioning, and then commit.
- Tag with a name like
vMAJOR.MINOR.PATCH
corresponding to the new version, and then push commits and tags.
License
Released under the MIT License.