StructuredIO
StructuredIO resembles Elixir’s IO module. The difference is that whereas IO gives you sequential access to a freeform stream of bytes or lines of data, StructuredIO guarantees that when you read data it conforms to a structure that you specify. Reads are contingent on the data’s conformity to a structure. That is to say, only complete data elements are read, so that your application can more easily handle truncated or streaming 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 write to and read structured data
using the StructuredIO.write
and .read_*
functions. This example depicts
Unicode data, but binary data of any kind can be written and read, too. See the
API documentation for detailed examples.
iex> {:ok, structured_io} = StructuredIO.start_link(:unicode)
Now we have a running StructuredIO process that expects properly encoded Unicode data.
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_between structured_io,
...> "<p>",
...> "</p>"
"bar"
We’ve read one element at a time from the available data in the stream. The read operations demonstrate both seeking and skipping.
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.5.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.