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.
See what’s changed lately by reading the project history.
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,
...> " <p>foo</p"
:ok
We’ve written some markup to the stream. Note that the <p>
element is preceded
by whitespace and is not properly closed.
iex> StructuredIO.read_across structured_io,
...> "<p>",
...> "</p>"
""
No <p>
element is read because the stream doesn’t begin with a <p>
.
iex> StructuredIO.read_to structured_io,
...> "<p>"
" "
iex> StructuredIO.read_across structured_io,
...> "<p>",
...> "</p>"
""
We managed to get past the whitespace, but no <p>
element is read because the
stream doesn’t contain a complete element.
iex> StructuredIO.write structured_io,
...> "><hr /><p>bar</p>"
: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,
...> "<p>",
...> "</p>"
"<p>foo</p>"
iex> StructuredIO.read_through structured_io,
...> "<hr />"
"<hr />"
iex> StructuredIO.read_across structured_io,
...> "<p>",
...> "</p>"
"<p>bar</p>"
We’ve read one element at a time from the available data in the stream.
iex> StructuredIO.read_across structured_io,
...> "<p>",
...> "</p>"
""
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
Install the Hex package by adding :structured_io
to the list of
dependencies in your project’s mix.exs file:
# mix.exs
# ...
def deps do
[
{:structured_io, "~> 0.3.0"}
]
end
# ...
Contributing
To submit a patch to the project:
- Fork the official repository.
- Create your feature branch:
git checkout -b my-new-feature
. - Commit your changes:
git commit -am 'Add some feature'
. - Push to the branch:
git push origin my-new-feature
. - Create a new pull request.
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 build this package, mix hex.build
.
To release a new version:
- Update the project history in History.md, and then commit.
- Update the version number in mix.exs respecting Semantic Versioning, update the “Installation” section of this readme to reference the new version, and then commit.
- Build and publish the Hex package with
mix hex.publish
. - 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.