ex_hl7

v0.4.2

ex_hl7 v0.4.2 HL7.Codec

Functions that decode and encode HL7 fields, repetitions, components and subcomponents.

Each type of item has a canonical representation, that will vary depending on whether the trim option was used when decoding or encoding. If we set trim to true, some trailing optional items and separators will be omitted from the decoded or encoded result, as we can see in the following example:

import HL7.Codec

decode_field("504599^223344&&IIN&^~", separators(), trim: true)

Where the result is:

{"504599", {"223344", "", "IIN"}}

With trim set to false the result would be:

[{"504599", {"223344", "", "IIN", ""}, ""}, ""]

Both representations are correct, given that HL7 allows trailing items that are empty to be omitted. This causes an ambiguity because the same item can be interpreted in several ways when it is the first and only item present.

For example, in the following HL7 segment the item in the third field (504599) might be the same in both cases (i.e. the first component of the second field):

  1. AUT||504599^^||||0000190447|^||
  2. AUT||504599||||0000190447|^||

But for this module it has two different representations:

  1. First component of the second field
  2. Second field

To resolve the ambiguity in the HL7 syntax, the code decoding and encoding HL7 segments using the functions in this module must be aware of this issue and deal with it accordingly when performing lookups or comparisons.

Link to this section Summary

Functions

compile_separators(args)
decode_components(components, separators \\ {124, 94, 38, 126}, trim \\ true)

Decode a binary holding one or more HL7 components into its canonical representation

decode_field(field, separators \\ {124, 94, 38, 126}, trim \\ true)

Decode a binary holding an HL7 field into its canonical representation

decode_subcomponents(component, separators \\ {124, 94, 38, 126}, trim \\ true)

Decode a binary holding one or more HL7 subcomponents into its canonical representation

decode_value(value, type \\ :string)
encode_components(components, separators \\ {124, 94, 38, 126}, trim \\ true)
encode_field(field, separators \\ {124, 94, 38, 126}, trim \\ true)
encode_subcomponents(subcomponents, separators \\ {124, 94, 38, 126}, trim \\ true)
encode_value(value, type \\ :string)
escape(value, separators \\ {124, 94, 38, 126}, escape_char \\ 92)

Escape a string that may contain separators using the HL7 escaping rules

format_date(date)
format_datetime(datetime)
match_separator(char, arg2)
separator(item_type, separators \\ {124, 94, 38, 126})

Return the separator corresponding to an item type

separators()

Return the default separators used to encode HL7 messages in their compiled format. These are

unescape(value, separators \\ {124, 94, 38, 126}, escape_char \\ 92)

Convert an escaped string into its original value

Link to this section Functions

Link to this function compile_separators(args)
Link to this function decode_components(components, separators \\ {124, 94, 38, 126}, trim \\ true)

Decode a binary holding one or more HL7 components into its canonical representation.

Link to this function decode_field(field, separators \\ {124, 94, 38, 126}, trim \\ true) 
decode_field(binary, separators :: binary, trim :: boolean) :: HL7.Type.field

Decode a binary holding an HL7 field into its canonical representation.

Link to this function decode_subcomponents(component, separators \\ {124, 94, 38, 126}, trim \\ true)

Decode a binary holding one or more HL7 subcomponents into its canonical representation.

Link to this function decode_value(value, type \\ :string) 
decode_value(HL7.Type.field, type :: atom) ::
  HL7.Type.value |
  :nomatch
Link to this function encode_components(components, separators \\ {124, 94, 38, 126}, trim \\ true)
Link to this function encode_field(field, separators \\ {124, 94, 38, 126}, trim \\ true)
Link to this function encode_subcomponents(subcomponents, separators \\ {124, 94, 38, 126}, trim \\ true)
Link to this function encode_value(value, type \\ :string) 
encode_value(HL7.Type.value | nil, type :: atom) ::
  binary |
  :nomatch
Link to this function escape(value, separators \\ {124, 94, 38, 126}, escape_char \\ 92)

Escape a string that may contain separators using the HL7 escaping rules.

Arguments

  • value: a string to escape; it may or may not contain separator characters.

  • separators: a binary containing the item separators to be used when generating the message as returned by HL7.Codec.compile_separators/1. Defaults to HL7.Codec.separators.

  • escape_char: character to be used as escape delimiter. Defaults to ?\\.

Examples 

iex> "ABCDEF" = HL7.Codec.escape("ABCDEF")
iex> "ABC\\F\\DEF\\S\\GHI" = HL7.Codec.escape("ABC|DEF^GHI", separators: HL7.Codec.separators(), escape_char: ?\\)
Link to this function format_date(date)
Link to this function format_datetime(datetime)
Link to this function match_separator(char, arg2)
Link to this function separator(item_type, separators \\ {124, 94, 38, 126}) 
separator(HL7.Type.item_type, binary) :: byte

Return the separator corresponding to an item type.

Link to this function separators()

Return the default separators used to encode HL7 messages in their compiled format. These are:

  • |: field separator
  • ^: component separator
  • &: subcomponent separator
  • ~: repetition separator

To use custom separators in a message use HL7.Codec.compile_separators/1 and pass the returned value as argument to the encoding functions.

Link to this function unescape(value, separators \\ {124, 94, 38, 126}, escape_char \\ 92)

Convert an escaped string into its original value.

Arguments

  • value: a string to unescape; it may or may not contain escaped characters.

  • escape_char: character that was used as escape delimiter. Defaults to ?\\.

Examples 

iex> "ABCDEF" = HL7.unescape("ABCDEF")
iex> "ABC|DEF|GHI" = HL7.Codec.unescape("ABC\\F\\DEF\\F\\GHI", ?\\)