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:

  1. Update the project history in History.md, and then commit.
  2. Update the version number in mix.exs and in all package definitions, respecting Semantic Versioning, and then commit.
  3. 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.