GS1.Formatter (gs1_barcode v0.1.2)

View Source

Formatting utilities for transforming GS1 Data Structures into various representations.

Supports custom layouts for printing labels (e.g., ZPL, HTML, or multi-line displays).

Summary

Types

gs1_opts()

Options for formatting GS1.

hri_opts()

Options for formatting HRI.

Functions

to_gs1(data_structure, opts \\ [])

Constructs GS1 encoded string from the Data Structure. Automatically handles the insertion of GS for var-length AIs.

to_hri(data_structure, opts \\ [])

Formats DataStructure struct into a formatted HRI string. Options allow for filtering specific fields or generating custom printer commands.

Types

gs1_opts()

@type gs1_opts() ::
  {:include, [String.t()] | nil}
  | {:prefix, String.t()}
  | {:group_separator, String.t()}

Options for formatting GS1.

  • :include - list of AIs to include. Default nil (all).
  • :prefix - prefix (e.g., "]d2"). Default is the struct's fnc1_prefix.
  • :group_separator - character or string used to terminate variable length fields. Default is GS1.Consts.gs_symbol/0.

hri_opts()

@type hri_opts() ::
  {:include, [String.t()] | nil}
  | {:before_ai, String.t()}
  | {:after_ai, String.t()}
  | {:joiner, String.t()}

Options for formatting HRI.

  • :include - list of AI strings (e.g., ["01", "10"]). If provided, only these AIs will be included in the output. Default is nil (all present AIs will be included).
  • :before_ai - string to prepend to the (AI) segment. Useful for ZPL commands (^FD) or visual delimiters. Default is "".
  • :after_ai - string to append after the (AI) segment but before the value. Default is "".
  • :joiner - string used to join the distinct segments. Can be a space, a newline (), or a command delimiter. Default is "".

Functions

to_gs1(data_structure, opts \\ [])

@spec to_gs1(GS1.DataStructure.t(), [gs1_opts()]) :: String.t()

Constructs GS1 encoded string from the Data Structure. Automatically handles the insertion of GS for var-length AIs.

Options

See gs1_opts/0 for details.

Logic

  1. Prepends the Symbology Identifier (Prefix).
  2. Iterates through AIs.
  3. If an AI is variable-length (e.g., AI "10" or "21") AND it is not the last element, adds the group_separator.
  4. Fixed-length AIs (e.g., "01" or "11") do not receive a separator.

Examples

iex> ds = %GS1.DataStructure{ais: %{"01" => "09876543210987", "10" => "BATCH123"}, fnc1_prefix: "]d2"}
iex> GS1.Formatter.to_gs1(ds)
"]d2010987654321098710BATCH123"

# Variable length field followed by another field gets a separator:
iex> ds_with_serial = %GS1.DataStructure{ais: %{"01" => "09876543210987", "10" => "BATCH123", "21" => "SERIAL"}, fnc1_prefix: "]d2"}
iex> GS1.Formatter.to_gs1(ds_with_serial)
"]d2010987654321098710BATCH123\x1D21SERIAL"

to_hri(data_structure, opts \\ [])

@spec to_hri(GS1.DataStructure.t(), [hri_opts()]) :: String.t()

Formats DataStructure struct into a formatted HRI string. Options allow for filtering specific fields or generating custom printer commands.

Options

See hri_opts/0 for details.

Examples

1. Standard HRI with default opts

iex> ds = %GS1.DataStructure{ais: %{"01" => "09876543210987", "10" => "BATCH123"}}
iex> GS1.Formatter.to_hri(ds)
"(01)09876543210987(10)BATCH123"

2. Including specific fields Only)

iex> ds = %GS1.DataStructure{ais: %{"01" => "09876543210987", "10" => "LOT-10"}}
iex> GS1.Formatter.to_hri(ds, include: ["01"])
"(01)09876543210987"

3. Visual Spacing

iex> ds = %GS1.DataStructure{ais: %{"01" => "09876543210987", "10" => "BATCH123"}}
iex> GS1.Formatter.to_hri(ds, before_ai: " ", after_ai: ": ")
" (01): 09876543210987 (10): BATCH123"

4. ZPL / Printer Format. Generates a ZPL block where each line is a field

iex> ds = %GS1.DataStructure{ais: %{"01" => "09876543210987", "10" => "BATCH123"}}
iex> GS1.Formatter.to_hri(ds,
...>    before_ai: "^FO50,50^ADN,36,20^FD", # Start Field command
...>    joiner: "^FS\n"                    # Field Separator + Newline
...> )
"^FO50,50^ADN,36,20^FD(01)09876543210987^FS\n^FO50,50^ADN,36,20^FD(10)BATCH123"