structured_io

v1.5.0

structured_io v1.5.0 StructuredIO.Scanner View Source

Provides functions for decomposing structured data, such as markup or binary-encoded data.

Link to this section Summary

Types

count()

A measure of size for a measured data element. See unit/0

left()

A binary value which marks the beginning of an enclosed data element

match()

The portion of a binary value matched in a scan

remainder()

The portion of a binary value remaining after the match/0 in a scan

right()

A binary value which marks the end of an enclosed or terminated data element

unit()

The unit of size for a measured data element: either bytes or graphemes. See count/0

Functions

scan(data, unit, count)

Reads from the specified data in the specified quantity. The quantity is measured as a count of a particular unit

scan_across(data, left, right)

Reads from the specified data, beginning with the specified left and ending with the occurrence of the specified right that corresponds to it, inclusive

scan_across_ignoring_overlap(data, left, right)

Reads from the specified data, beginning with the specified left and ending with the first occurrence of the specified right, inclusive

scan_between(data, left, right)

Reads from the specified data, beginning with the specified left and ending with the occurrence of the specified right that corresponds to it, exclusive

scan_between_ignoring_overlap(data, left, right)

Reads from the specified data, beginning with the specified left and ending with the first occurrence of the specified right, exclusive

scan_through(data, right)

Reads from the specified data if and until the specified right is encountered, including right

scan_to(data, right)

Reads from the specified data if and until the specified right is encountered, excluding right

Link to this section Types

Link to this type count() View Source 
count() :: non_neg_integer()

A measure of size for a measured data element. See unit/0.

Link to this type left() View Source 
left() :: binary()

A binary value which marks the beginning of an enclosed data element.

Link to this type match() View Source 
match() :: binary()

The portion of a binary value matched in a scan.

Link to this type remainder() View Source 
remainder() :: binary()

The portion of a binary value remaining after the match/0 in a scan.

Link to this type right() View Source 
right() :: binary()

A binary value which marks the end of an enclosed or terminated data element.

Link to this type unit() View Source 
unit() :: :bytes | :graphemes

The unit of size for a measured data element: either bytes or graphemes. See count/0.

Link to this section Functions

Link to this function scan(data, unit, count) View Source 
scan(binary(), unit(), count()) :: {match(), remainder()} | nil

Reads from the specified data in the specified quantity. The quantity is measured as a count of a particular unit.

If the process does not contain at least the expected quantity of data, the result is nil.

Examples 

iex> StructuredIO.Scanner.scan "\r\nfoo",
...>                           :graphemes,
...>                           5
nil

iex> StructuredIO.Scanner.scan "\r\nfoo\tbar",
...>                           :graphemes,
...>                           5
{"\r\nfoo\t",
 "bar"}

iex> StructuredIO.Scanner.scan <<23, 45>>,
...>                           :bytes,
...>                           3
nil

iex> StructuredIO.Scanner.scan <<23, 45, 67, 89>>,
...>                           :bytes,
...>                           3
{<<23, 45, 67>>,
 <<89>>}
Link to this function scan_across(data, left, right) View Source 
scan_across(binary(), left(), right()) :: {match(), remainder()} | nil

Reads from the specified data, beginning with the specified left and ending with the occurrence of the specified right that corresponds to it, inclusive.

If data does not both begin with left and contain a corresponding right, the result is nil.

Examples 

iex> StructuredIO.Scanner.scan_across "<elem>foo</elem",
...>                                  "<elem>",
...>                                  "</elem>"
nil

iex> StructuredIO.Scanner.scan_across "<elem>foo<elem>bar</elem></elem>baz",
...>                                  "<elem>",
...>                                  "</elem>"
{"<elem>foo<elem>bar</elem></elem>",
 "baz"}

iex> StructuredIO.Scanner.scan_across <<0, 0, 0, 1, 2, 3, 255, 255>>,
...>                                  <<0, 0, 0>>,
...>                                  <<255, 255, 255>>
nil

iex> StructuredIO.Scanner.scan_across <<0, 0, 0, 1, 2, 3, 0, 0, 0, 4, 5, 6, 255, 255, 255, 255, 255, 255, 7, 8, 9>>,
...>                                  <<0, 0, 0>>,
...>                                  <<255, 255, 255>>
{<<0, 0, 0, 1, 2, 3, 0, 0, 0, 4, 5, 6, 255, 255, 255, 255, 255, 255>>,
 <<7, 8, 9>>}
Link to this function scan_across_ignoring_overlap(data, left, right) View Source 
scan_across_ignoring_overlap(binary(), left(), right()) ::
  {match(), remainder()} | nil

Reads from the specified data, beginning with the specified left and ending with the first occurrence of the specified right, inclusive.

If data does not both begin with left and contain right, the result is nil.

Examples 

iex> StructuredIO.Scanner.scan_across_ignoring_overlap "<elem>foo<elem>bar</elem",
...>                                                   "<elem>",
...>                                                   "</elem>"
nil

iex> StructuredIO.Scanner.scan_across_ignoring_overlap "<elem>foo<elem>bar</elem></elem>baz",
...>                                                   "<elem>",
...>                                                   "</elem>"
{"<elem>foo<elem>bar</elem>",
 "</elem>baz"}

iex> StructuredIO.Scanner.scan_across_ignoring_overlap <<0, 0, 0, 1, 2, 3, 0, 0, 0, 4, 5, 6, 255, 255>>,
...>                                                   <<0, 0, 0>>,
...>                                                   <<255, 255, 255>>
nil

iex> StructuredIO.Scanner.scan_across_ignoring_overlap <<0, 0, 0, 1, 2, 3, 0, 0, 0, 4, 5, 6, 255, 255, 255, 255, 255, 255, 7, 8, 9>>,
...>                                                   <<0, 0, 0>>,
...>                                                   <<255, 255, 255>>
{<<0, 0, 0, 1, 2, 3, 0, 0, 0, 4, 5, 6, 255, 255, 255>>,
 <<255, 255, 255, 7, 8, 9>>}
Link to this function scan_between(data, left, right) View Source 
scan_between(binary(), left(), right()) :: {match(), remainder()} | nil

Reads from the specified data, beginning with the specified left and ending with the occurrence of the specified right that corresponds to it, exclusive.

If data does not both begin with left and contain a corresponding right, the result is nil.

Examples 

iex> StructuredIO.Scanner.scan_between "<elem>foo</elem",
...>                                   "<elem>",
...>                                   "</elem>"
nil

iex> StructuredIO.Scanner.scan_between "<elem>foo</elem><elem>bar</elem>",
...>                                   "<elem>",
...>                                   "</elem>"
{"foo",
 "<elem>bar</elem>"}

iex> StructuredIO.Scanner.scan_between "<elem>foo<elem>bar</elem></elem>baz",
...>                                   "<elem>",
...>                                   "</elem>"
{"foo<elem>bar</elem>",
 "baz"}

iex> StructuredIO.Scanner.scan_between <<0, 0, 0, 1, 2, 3, 255, 255>>,
...>                                   <<0, 0, 0>>,
...>                                   <<255, 255, 255>>
nil

iex> StructuredIO.Scanner.scan_between <<0, 0, 0, 1, 2, 3, 255, 255, 255, 0, 0, 0, 4, 5, 6, 255, 255, 255>>,
...>                                   <<0, 0, 0>>,
...>                                   <<255, 255, 255>>
{<<1, 2, 3>>,
 <<0, 0, 0, 4, 5, 6, 255, 255, 255>>}

iex> StructuredIO.Scanner.scan_between <<0, 0, 0, 1, 2, 3, 0, 0, 0, 4, 5, 6, 255, 255, 255, 255, 255, 255, 7, 8, 9>>,
...>                                   <<0, 0, 0>>,
...>                                   <<255, 255, 255>>
{<<1, 2, 3, 0, 0, 0, 4, 5, 6, 255, 255, 255>>,
 <<7, 8, 9>>}
Link to this function scan_between_ignoring_overlap(data, left, right) View Source 
scan_between_ignoring_overlap(binary(), left(), right()) ::
  {match(), remainder()} | nil

Reads from the specified data, beginning with the specified left and ending with the first occurrence of the specified right, exclusive.

If data does not both begin with left and contain right, the result is nil.

Examples 

iex> StructuredIO.Scanner.scan_between_ignoring_overlap "<elem>foo<elem>bar</elem",
...>                                                    "<elem>",
...>                                                    "</elem>"
nil

iex> StructuredIO.Scanner.scan_between_ignoring_overlap "<elem>foo<elem>bar</elem></elem>baz",
...>                                                    "<elem>",
...>                                                    "</elem>"
{"foo<elem>bar",
 "</elem>baz"}

iex> StructuredIO.Scanner.scan_between_ignoring_overlap <<0, 0, 0, 1, 2, 3, 0, 0, 0, 4, 5, 6, 255, 255>>,
...>                                                    <<0, 0, 0>>,
...>                                                    <<255, 255, 255>>
nil

iex> StructuredIO.Scanner.scan_between_ignoring_overlap <<0, 0, 0, 1, 2, 3, 0, 0, 0, 4, 5, 6, 255, 255, 255, 255, 255, 255, 7, 8, 9>>,
...>                                                    <<0, 0, 0>>,
...>                                                    <<255, 255, 255>>
{<<1, 2, 3, 0, 0, 0, 4, 5, 6>>,
 <<255, 255, 255, 7, 8, 9>>}
Link to this function scan_through(data, right) View Source 
scan_through(binary(), right()) :: {match(), remainder()} | nil

Reads from the specified data if and until the specified right is encountered, including right.

If data does not contain right, the result is nil.

Examples 

iex> StructuredIO.Scanner.scan_through "foo<br /",
...>                                   "<br/>"
nil

iex> StructuredIO.Scanner.scan_through "foo<br/>bar<br/>",
...>                                   "<br/>"
{"foo<br/>",
 "bar<br/>"}

iex> StructuredIO.Scanner.scan_through <<1, 2, 3, 255, 255>>,
...>                                   <<255, 255, 255>>
nil

iex> StructuredIO.Scanner.scan_through <<1, 2, 3, 255, 255, 255, 4, 5, 6, 255, 255, 255>>,
...>                                   <<255, 255, 255>>
{<<1, 2, 3, 255, 255, 255>>,
 <<4, 5, 6, 255, 255, 255>>}
Link to this function scan_to(data, right) View Source 
scan_to(binary(), right()) :: {match(), remainder()} | nil

Reads from the specified data if and until the specified right is encountered, excluding right.

If data does not contain right, the result is nil.

Examples 

iex> StructuredIO.Scanner.scan_to "foo<br /",
...>                              "<br/>"
nil

iex> StructuredIO.Scanner.scan_to "foo<br/>bar<br/>",
...>                              "<br/>"
{"foo",
 "<br/>bar<br/>"}

iex> StructuredIO.Scanner.scan_to <<1, 2, 3, 255, 255>>,
...>                              <<255, 255, 255>>
nil

iex> StructuredIO.Scanner.scan_to <<1, 2, 3, 255, 255, 255, 4, 5, 6, 255, 255, 255>>,
...>                              <<255, 255, 255>>
{<<1, 2, 3>>,
 <<255, 255, 255, 4, 5, 6, 255, 255, 255>>}