structured_io v1.5.0 StructuredIO.Enumerator View Source

Provides an Enumerable implementation for StructuredIO. Call StructuredIO.enumerate_with/3or StructuredIO.enumerate_with/4 instead of invoking this module directly.

Note that enumeration is not a purely functional operation; it consumes data elements from the underlying StructuredIO process.

Examples

iex> {:ok,
...>  structured_io} = StructuredIO.start_link(:unicode)
iex> StructuredIO.write structured_io,
...>                    "<elem>foo</elem>"
:ok
iex> StructuredIO.write structured_io,
...>                    "<elem>bar</elem>"
:ok
iex> StructuredIO.write structured_io,
...>                    "<elem>baz</elem>"
:ok
iex> {:ok,
...>  enumerator} = StructuredIO.Enumerator.new(%{process: structured_io,
...>                                              function: :read_between,
...>                                              additional_arguments: ["<elem>",
...>                                                                     "</elem>"]})
iex> Enum.map enumerator, &String.upcase/1
["FOO",
 "BAR",
 "BAZ"]
iex> Enum.map enumerator, &String.upcase/1
[]

iex> {:ok,
...>  structured_io} = StructuredIO.start_link(:unicode)
iex> StructuredIO.write structured_io,
...>                    "<elem>foo</elem>"
:ok
iex> StructuredIO.write structured_io,
...>                    "<elem>bar</elem>"
:ok
iex> StructuredIO.write structured_io,
...>                    "<elem>baz</elem>"
:ok
iex> {:ok,
...>  enumerator} = StructuredIO.Enumerator.new(%{process: structured_io,
...>                                              function: :read_between,
...>                                              additional_arguments: ["<elem>",
...>                                                                     "</elem>"]})
iex> Enum.count enumerator
3
iex> Enum.count enumerator
0

iex> {:ok,
...>  structured_io} = StructuredIO.start_link(:unicode)
iex> StructuredIO.write structured_io,
...>                    "<elem>foo</elem>"
:ok
iex> StructuredIO.write structured_io,
...>                    "<elem>bar</elem>"
:ok
iex> StructuredIO.write structured_io,
...>                    "<elem>baz</elem>"
:ok
iex> {:ok,
...>  enumerator} = StructuredIO.Enumerator.new(%{process: structured_io,
...>                                              function: :read_between,
...>                                              additional_arguments: ["<elem>",
...>                                                                     "</elem>"]})
iex> Enum.member? enumerator, "bar"
true
iex> Enum.member? enumerator, "foo"
false
iex> Enum.member? enumerator, "bar"
false
iex> Enum.member? enumerator, "baz"
false

Link to this section Summary

Types

t()

A StructuredIO.Enumerator struct

Functions

new(enumerator)

Builds a new StructuredIO.Enumerator for the specified StructuredIO process, function, and additional_arguments to that function

timeout(enumerator, timeout)

Sets a timeout for the specified StructuredIO.Enumerator. This value is passed in each call to the StructuredIO.read* function

Link to this section Types

t()

t() :: %StructuredIO.Enumerator{
  additional_arguments: [any()],
  arguments: [any()],
  function: atom(),
  process: GenServer.server(),
  timeout: nil | timeout()
}

A StructuredIO.Enumerator struct.

Link to this section Functions

new(enumerator)

new(%{
  process: GenServer.server(),
  function: atom(),
  additional_arguments: any()
}) :: {:ok, t()} | StructuredIO.error()

Builds a new StructuredIO.Enumerator for the specified StructuredIO process, function, and additional_arguments to that function.

Examples

iex> {:ok,
...>  enumerator} = StructuredIO.Enumerator.new(%{process: :a_process,
...>                                              function: :read_across,
...>                                              additional_arguments: ["<elem>",
...>                                                                     "</elem>"]})
iex> enumerator
%StructuredIO.Enumerator{process: :a_process,
                         function: :read_across,
                         additional_arguments: ["<elem>",
                                                "</elem>"],
                         arguments: [:a_process,
                                     "<elem>",
                                     "</elem>"]}

iex> StructuredIO.Enumerator.new %{function: :read_across,
...>                               additional_arguments: ["<elem>",
...>                                                      "</elem>"]}
{:error,
 "StructuredIO.Enumerator :process field is required"}

iex> StructuredIO.Enumerator.new %{process: :a_process,
...>                               additional_arguments: ["<elem>",
...>                                                      "</elem>"]}
{:error,
 "StructuredIO.Enumerator :function field must be the name of a StructuredIO public function"}

iex> StructuredIO.Enumerator.new %{process: :a_process,
...>                               function: "read_across",
...>                               additional_arguments: ["<elem>",
...>                                                      "</elem>"]}
{:error,
 "StructuredIO.Enumerator :function field must be the name of a StructuredIO public function"}

iex> StructuredIO.Enumerator.new %{process: :a_process,
...>                               function: :not_a_function}
{:error,
 "function StructuredIO.not_a_function/1 is undefined or private"}

iex> StructuredIO.Enumerator.new %{process: :a_process,
...>                               function: :read_across}
{:error,
 "function StructuredIO.read_across/1 is undefined or private"}

iex> StructuredIO.Enumerator.new %{process: :a_process,
...>                               function: :read_across,
...>                               additional_arguments: "too-few-args"}
{:error,
 "function StructuredIO.read_across/2 is undefined or private"}

timeout(enumerator, timeout)

timeout(t(), timeout() | nil) :: t()

Sets a timeout for the specified StructuredIO.Enumerator. This value is passed in each call to the StructuredIO.read* function.

Examples

iex> {:ok,
...>  enumerator} = StructuredIO.Enumerator.new(%{process: :a_process,
...>                                              function: :read_across,
...>                                              additional_arguments: ["<elem>",
...>                                                                     "</elem>"]})
iex> enumerator
%StructuredIO.Enumerator{process: :a_process,
                         function: :read_across,
                         additional_arguments: ["<elem>",
                                                "</elem>"],
                         arguments: [:a_process,
                                     "<elem>",
                                     "</elem>"]}
iex> enumerator_with_timeout = StructuredIO.Enumerator.timeout(enumerator,
...>                                                           1000)
%StructuredIO.Enumerator{process: :a_process,
                         function: :read_across,
                         additional_arguments: ["<elem>",
                                                "</elem>"],
                         arguments: [:a_process,
                                     "<elem>",
                                     "</elem>",
                                     1000],
                         timeout: 1000}
iex> StructuredIO.Enumerator.timeout enumerator_with_timeout,
...>                                 nil
enumerator