@spec chunk_by_lead_segment(t() | [segment()], String.t(), Keyword.t()) :: [
  [segment()]
]

Creates a list of lists in which the specified segment_name is used to get the first segment map of each list. This function helps to do things like grouping OBX segments with their parent OBR segment.

Options:

keep_prefix_segments: true will leave the first set of non-matching segments in the return value.

@spec get(parsed_hl7(), %HL7.Path{
  component: term(),
  data: term(),
  field: term(),
  path: term(),
  repetition: term(),
  segment: term(),
  segment_number: term(),
  subcomponent: term(),
  truncate: term()
}) :: hl7_map_data() | [hl7_map_data()] | String.t() | nil

Finds data within an HL7.t() and from within the data that get/2 returns (segments and repetitions) using an HL7.Path sigil.

Selecting data across multiple segments or repetitions with the wildcard [*] pattern will return a list of results.

Repetition data can be search using a partial path containing ony the component and/or subcomponent with the preceding period, e.g. ~p".2.3".

Examples

iex> import HL7, only: :sigils
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"OBX-5")
"1.80"

iex> import HL7, only: :sigils
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"OBX[*]-5")
["1.80", "79"]

iex> import HL7, only: :sigils
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"OBX[*]-2!")
["N", "NM"]

iex> import HL7, only: :sigils
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"PID-11[*].5")
["35209", "35200"]

iex> import HL7, only: :sigils
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"PID-11[2].1")
"NICKELL’S PICKLES"

iex> import HL7, only: :sigils
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"PID-11[*]")
...> |> HL7.get(~p".1")
["260 GOODWIN CREST DRIVE", "NICKELL’S PICKLES"]

iex> import HL7
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"OBX[*]")
[
  %{
    0 => "OBX",
    1 => "1",
    2 => %{1 => %{1 => "N", 2 => %{1 => "K", 2 => "M"}}},
    3 => %{1 => %{2 => "Body Height"}},
    5 => "1.80",
    6 => %{1 => %{1 => "m", 2 => "Meter", 3 => "ISO+"}},
    11 => "F"
  },
  %{
    0 => "OBX",
    1 => "2",
    2 => "NM",
    3 => %{1 => %{2 => "Body Weight"}},
    5 => "79",
    6 => %{1 => %{1 => "kg", 2 => "Kilogram", 3 => "ISO+"}},
    11 => "F"
  }
]

@spec label(t() | segment(), map()) :: map()

Labels source data (a segment map or list of segment maps) by using HL7.Path sigils in a labeled output template.

One-arity functions placed as output template values will be called with the source data.

Examples

iex> import HL7, only: :sigils
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.label(%{mrn: ~p"PID-3!", name: ~p"PID-5.2"})
%{mrn: "56782445", name: "BARRY"}

@spec new!(hl7_list_data() | String.t() | HL7.Message.t() | [segment()]) :: t()

Creates an HL7 struct from HL7 data (accepting text, lists or the deprecated HL7.Message struct).

@spec open_hl7_file_stream(String.t(), file_type_hl7()) :: Enumerable.t()

Opens an HL7 file stream of either :mllp or :line. If the file_type is not specified it will be inferred from the first three characters of the file contents.

The ~p sigil encodes an HL7 path into a struct at compile-time to guarantee correctness and speed. It is designed to work with data returned by HL7.new!/1.

The full path structure in HL7 is expressed as:

~p"SEGMENT_NAME[SEGMENT_NUMBER]-FIELD[REPETITION].COMPONENT.SUBCOMPONENT

SEGMENT_NAME -- 3 character string SEGMENT_NUMBER -- Positive integer in brackets, defaulting to 1. All segments of the name can be accessed with [*] FIELD -- Positive integer REPETITION -- Positive integer in brackets, defaulting to 1. All repetitions of the field can be accessed with [*] COMPONENT -- Positive integer SUBCOMPONENT -- Positive integer

Example paths:

~p"OBX" refers to the 1st OBX segment in its entirety, the same as ~p"OBX[1]". ~p"OBX-5" means the 1st repetition of the 5th field of the 1st OBX segment. ~p"OBX[1]-5[1]" is equivalent, the numbers in brackets specifying the default repetition and segment number values. ~p"OBX[2]-5" thus means 1st repetition of the 5th field of the 2nd OBX segment. ~p"OBX[*]-5" would get the 1st repetition of the 5th field of every OBX segment, returning a list of results.

Note that repetitions are uncommon in HL7 and the default of a 1st repetition is often just assumed. ~p"PID-3" is equivalent to ~p"PID-3[1]" and is the most standard representation.

All repetitions can be found using a repetition wildcard: ~p"PID-11[*]". A list of lists can be produced by selecting multiple segments and multiple repetitions with ~p"PID[*]-11[*]".

Components and subcomponents can also be accessed with the path structures. h"OBX-2.3.1" would return the 1st subcomponent of the 3rd component of the 2nd field of the 1st OBX.

Additionally, if a path might have additional data such that a string might be found at either ~p"OBX-2" or ~p"OBX-2.1" or even ~p"OBX-2.1.1", there is truncation character (the bang symbol) that will return the first element found in the HL7 text at the target specificity. Thus, ~p"OBX[*]-2!" would get the 1st piece of data in the 2nd field of every OBX whether it is a string or nested map.

Lastly, when accessing data from a specific repetition, the path should begin with .; for example, when working with the Nth OBX segment and using HL7.get/2 to access that segment's second field, first component, use the path ~p".2.1"

Examples

iex> import HL7
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"OBX-5")
"1.80"

iex> import HL7
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"OBX[*]-5")
["1.80", "79"]

iex> import HL7
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"OBX[*]-2!")
["N", "NM"]

iex> import HL7
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"PID-11[*].5")
["35209", "35200"]

iex> import HL7
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"PID[*]-11[*].5")
[["35209", "35200"]]

iex> import HL7
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"PID-11[2].1")
"NICKELL’S PICKLES"

iex> import HL7
iex> HL7.Examples.wikipedia_sample_hl7()
...> |> HL7.new!()
...> |> HL7.get(~p"PID-11[*]")
...> |> List.last()
...> |> HL7.get(~p".1")
"NICKELL’S PICKLES"

@spec to_list(t() | hl7_map_data()) :: hl7_list_data()

Converts a segment map (or lists of segments maps) or HL7 struct into a raw Elixir list.