HL7.Query (elixir_hl7 v0.8.0) View Source

Queries and modifies HL7 messages using Field and Segment Grammar Notations with a pipeline-friendly API and set-based operations.

Similar to libraries such as jQuery and D3, HL7.Query is designed around the concept of selecting and sub-selecting elements (segments or segment groups) in an HL7 message. The full message context is retained in the HL7.Query struct so that messages can be modified piecemeal and then reconstructed as strings.

In general, use HL7.Query.select/2 with a segment selector (similar to CSS selectors) to select lists of segment groups.

The segment selector is written as a string of ordered segment names. Curly braces surround repeating elements. Square brackets enclose optional elements. These can be nested to create selectors that can select complex groups of segments or validate entire HL7 message layouts.

For example, an ORU_R01 HL7 message's Order Group selector could be written as:

"[ORC] OBR {[NTE]} {[OBX {[NTE]}]}".

Note that this would look for OBRs, optionally preceded by an ORC, possibly followed by one or more NTEs, maybe followed again by one or more OBRs with their own optional NTE sets.

To reference data within segments, there is a field selector format that can access fields, repetitions, components and sub-components across one or more segments. All indices start at one, and the repetition index defaults to one unless specified within brackets after the field number.

Field SelectorDescription
"PID-11[2].4"PID segments, 11th field, 2nd repetition, 4th component
"OBX-2.2.1"OBX segments, 2nd field, 2nd component, 1st sub-component
"1"All segments, 1st field
"3[4].2"All segments, 3rd field, 4th repetition, 2nd component

Link to this section Summary

Functions

Appends a segment or segments to the currently selected segments in each selection.

Returns the current selection count.

Associates data with each selection. This data remains accessible to child selections.

Deletes all selections in the query document.

Filters (deletes) segments within selections by whitelisting one or more segment types. Accepts either a segment name, list of acceptable names, or a function that takes an HL7.Query (containing one sub-selected segment at a time) and returns a boolean filter value.

Returns a flattened list of segment parts from selected segments across all selections using the given field_selector.

Returns a segment part from the first selected segment (of the given name, if specified) across all selections using the given field_selector.

Returns a list containing an associated data map for each selection in the given HL7.Query.

Returns the associated key-value of the first (or only) selection for the given HL7.Query.

Returns the selection index of the first (or only) selection for the given HL7.Query.

Returns a list containing a list of selected segments for each selection.

Returns a flattened list of segment names across all selections.

Returns a flattened list of selected segments across all selections.

Maps across each selection with a fun that accepts an HL7.Query (handling one selection at a time) and returns a results list.

Creates an HL7.Query struct that selects an entire HL7 Message. This step is implicitly carried out by most other functions in this module. As it involves parsing an HL7 message, one should cache this result if invoked repeatedly.

Updates the set numbers in each segment's first field to be their respective selection indices.

Prepends a segment or list of segments to the segments in each of the current selections.

Rejects (deletes) segments within selections by blacklisting one or more segment types. Accepts either a segment name, list of acceptable names, or a function that takes an HL7.Query (containing one sub-selected segment at a time) and returns a boolean reject value.

Rejects (deletes) Z-segments in all selections.

Replaces all segments in each selection. The given fun should accept an HL7.Query (referencing a single selection) and return a list of replacement segments (in parsed list format).

Selects the entire an HL7.Query into an HL7.Message.

Selects or sub-selects segment groups in an HL7 message using a segment selector or filter function.

Checks the format of an hl7 path at compile time and returns an Path

Outputs an ANSI representation of an HL7.Query with corresponding selection indices on the left.

Converts an HL7.Query into an HL7.Message.

Updates segment parts of all selected segments, iterating through each selection. A replacement function accepts an HL7.Query containing one selection with its part property set to the value found using the field_selector.

Link to this section Types

Specs

content_hl7() :: raw_hl7() | parsed_hl7()
Link to this type

content_or_query_hl7()

View Source

Specs

content_or_query_hl7() :: content_hl7() | t()

Specs

parsed_hl7() :: [list()] | HL7.Message.t()

Specs

parsed_or_query_hl7() :: parsed_hl7() | t()

Specs

raw_hl7() :: String.t() | HL7.RawMessage.t()

Specs

t() :: %HL7.Query{invalid_message: term(), part: term(), selections: list()}

Link to this section Functions

Specs

append(t(), list()) :: t()

Appends a segment or segments to the currently selected segments in each selection.

Specs

count(t()) :: non_neg_integer()

Returns the current selection count.

Specs

data(t(), (t() -> map())) :: t()

Associates data with each selection. This data remains accessible to child selections.

Each selection stores a map of data. The supplied fun should accept an HL7.Query and return a map of key-values to be merged into the existing map of data.

Selections automatically include the index of the current selection, i.e., %{index: 5}. For HL7 numbering, the index values begin at 1.

Examples

iex> import HL7.Query
iex> HL7.Examples.nist_immunization_hl7()
...> |> select("ORC RXA RXR {[OBX]}")
...> |> data(fn q -> %{order_num: find_first(q, ~p"ORC-3.1")} end)
...> |> select("OBX")
...> |> update(~p"6", fn q -> get_datum(q, :order_num) end)
...> |> root()
...> |> find_first(~p"OBX-6")
"IZ-783278"

iex> import HL7.Query
iex> HL7.Examples.nist_immunization_hl7()
...> |> select("ORC RXA RXR {[OBX]}")
...> |> data(fn q -> %{group_num: get_index(q)} end)
...> |> select("OBX")
...> |> update(~p"6", fn q -> get_datum(q, :group_num) end)
...> |> root()
...> |> find_all(~p"OBX-6")
[1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2]

Specs

delete(t()) :: t()

Deletes all selections in the query document.

Specs

filter(content_or_query_hl7(), (t() -> as_boolean(term()))) :: t()
filter(content_or_query_hl7(), binary()) :: t()
filter(content_or_query_hl7(), [binary()]) :: t()

Filters (deletes) segments within selections by whitelisting one or more segment types. Accepts either a segment name, list of acceptable names, or a function that takes an HL7.Query (containing one sub-selected segment at a time) and returns a boolean filter value.

Examples

iex> import HL7.Query
iex> HL7.Examples.nist_immunization_hl7()
...> |> filter(["MSH", "PID", "ORC"])
...> |> root()
...> |> get_segment_names()
["MSH", "PID", "ORC", "ORC", "ORC"]
Link to this function

find_all(query, field_path)

View Source (since 0.8.0)

Specs

find_all(content_or_query_hl7(), HL7.Path.t()) :: list()

Returns a flattened list of segment parts from selected segments across all selections using the given field_selector.

PID-3[2].1.2 PID segments, field 3, repetition 2, component 1, subcomponent 2

OBX-5 OBX segments, field 5

2.3 All segments, field 2, component 3

Link to this function

find_first(query, field_path)

View Source (since 0.8.0)

Specs

find_first(content_or_query_hl7(), HL7.Path.t()) :: nil | iodata()

Returns a segment part from the first selected segment (of the given name, if specified) across all selections using the given field_selector.

PID-3[2].1.2 PID segments, field 3, repetition 2, component 1, subcomponent 2

OBX-5 OBX segments, field 5

2.3 All segments, field 2, component 3

Specs

get_data(t()) :: [map()]

Returns a list containing an associated data map for each selection in the given HL7.Query.

Link to this function

get_datum(query, key, default \\ nil)

View Source

Specs

get_datum(t(), any(), any()) :: any()

Returns the associated key-value of the first (or only) selection for the given HL7.Query.

Specs

get_index(t()) :: non_neg_integer()

Returns the selection index of the first (or only) selection for the given HL7.Query.

Examples

iex> import HL7.Query
iex> HL7.Examples.nist_immunization_hl7()
...> |> select("ORC RXA RXR {[OBX]}")
...> |> map(fn q -> get_index(q) end)
[1, 2]

iex> import HL7.Query
iex> HL7.Examples.nist_immunization_hl7()
...> |> select("ORC RXA RXR {[OBX]}")
...> |> select("OBX")
...> |> map(fn q -> get_index(q) end)
[1, 2, 3, 4, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

iex> import HL7.Query
iex> HL7.Examples.nist_immunization_hl7()
...> |> select("OBX")
...> |> map(fn q -> get_index(q) end)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
Link to this function

get_part(query, grammar_string)

View Source
This function is deprecated. use HL7.Query.find_first/2 instead.

Specs

get_part(content_or_query_hl7(), String.t()) :: nil | iodata()
Link to this function

get_parts(query, grammar_string)

View Source
This function is deprecated. use HL7.Query.find_all/2 instead.

Specs

get_parts(content_or_query_hl7(), String.t()) :: list()
Link to this function

get_segment_groups(query)

View Source

Specs

get_segment_groups(t()) :: [list()]

Returns a list containing a list of selected segments for each selection.

Link to this function

get_segment_names(query)

View Source

Specs

get_segment_names(content_or_query_hl7()) :: [String.t()]

Returns a flattened list of segment names across all selections.

Specs

get_segments(t()) :: [list()]

Returns a flattened list of selected segments across all selections.

Specs

map(t(), function()) :: list()

Maps across each selection with a fun that accepts an HL7.Query (handling one selection at a time) and returns a results list.

Examples

iex> import HL7.Query
iex> HL7.Examples.nist_immunization_hl7()
...> |> select("RXA")
...> |> map(fn q -> find_first(q, ~p"5.2") end)
["Influenza", "PCV 13", "DTaP-Hep B-IPV"]

Specs

new(content_or_query_hl7()) :: t()

Creates an HL7.Query struct that selects an entire HL7 Message. This step is implicitly carried out by most other functions in this module. As it involves parsing an HL7 message, one should cache this result if invoked repeatedly.

Specs

number_set_ids(t()) :: t()

Updates the set numbers in each segment's first field to be their respective selection indices.

Link to this function

prepend(query, segment_data)

View Source

Specs

prepend(t(), list()) :: t()

Prepends a segment or list of segments to the segments in each of the current selections.

Specs

reject(t(), binary()) :: t()
reject(content_or_query_hl7(), [binary()]) :: t()
reject(content_or_query_hl7(), (t() -> as_boolean(term()))) :: t()

Rejects (deletes) segments within selections by blacklisting one or more segment types. Accepts either a segment name, list of acceptable names, or a function that takes an HL7.Query (containing one sub-selected segment at a time) and returns a boolean reject value.

Examples

iex> import HL7.Query
iex> HL7.Examples.nist_immunization_hl7()
...> |> reject(["OBX", "RXA", "RXR"])
...> |> root()
...> |> get_segment_names()
["MSH", "PID", "ORC", "ORC", "ORC"]
Link to this function

reject_z_segments(query)

View Source

Rejects (deletes) Z-segments in all selections.

Specs

replace(t(), (t() -> [HL7.Segment.segment_hl7()])) :: t()

Replaces all segments in each selection. The given fun should accept an HL7.Query (referencing a single selection) and return a list of replacement segments (in parsed list format).

Link to this function

replace_parts(query, grammar_string, func_or_value)

View Source
This function is deprecated. use HL7.Query.update/2 instead.

Specs

replace_parts(
  content_or_query_hl7(),
  String.t(),
  function() | String.t() | list()
) :: t()

Specs

root(t()) :: t()

Selects the entire an HL7.Query into an HL7.Message.

Link to this function

select(msg, segment_selector)

View Source

Specs

select(content_or_query_hl7(), binary()) :: t()

Selects or sub-selects segment groups in an HL7 message using a segment selector or filter function.

iex> import HL7.Query
iex> HL7.Examples.nist_immunization_hl7()
...> |> select("OBX")
...> |> select(fn q -> find_first(q, ~p"1") != "1" end)
...> |> delete()
...> |> root()
...> |> get_segment_names()
["MSH", "PID", "ORC", "RXA", "RXR", "OBX", "ORC", "RXA", "ORC", "RXA", "RXR", "OBX"]
Link to this macro

sigil_g(arg, modifiers)

View Source (macro)
This macro is deprecated. use HL7.Query.sigil_p/2 instead.
Link to this macro

sigil_p(arg, modifiers)

View Source (macro)

Checks the format of an hl7 path at compile time and returns an Path

Outputs an ANSI representation of an HL7.Query with corresponding selection indices on the left.

Specs

to_message(t()) :: HL7.Message.t()

Converts an HL7.Query into an HL7.Message.

Link to this function

update(query, field_path, func_or_value)

View Source (since 0.8.0)

Specs

update(
  content_or_query_hl7(),
  HL7.Path.t(),
  (t() -> String.t()) | String.t() | list()
) :: t()

Updates segment parts of all selected segments, iterating through each selection. A replacement function accepts an HL7.Query containing one selection with its part property set to the value found using the field_selector.

Examples

iex> import HL7.Query
iex> HL7.Examples.nist_immunization_hl7()
...> |> update(~p"OBX-3.2", fn q -> "TEST: " <> q.part end)
...> |> find_all(~p"OBX-3.2")
...> |> List.first()
"TEST: Vaccine funding program eligibility category"

iex> import HL7.Query
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> select("PID")
...> |> update(~p"5.2", "UNKNOWN")
...> |> find_first(~p"PID-5.2")
"UNKNOWN"