# `HL7v2.Access`
[🔗](https://github.com/Balneario-de-Cofrentes/hl7v2/blob/v3.10.1/lib/hl7v2/access.ex#L1)

Path-based access to HL7v2 message fields.

Provides `get/2`, `get/3`, and `fetch/2` for extracting values from typed
messages using path strings like `"PID-5"` or `"MSH-9.1"`.

`get/2` returns nil on any resolution failure (silent). `fetch/2` returns
`{:ok, value}` or `{:error, reason}` for explicit error handling.

## Path Syntax

    "PID"          — first PID segment struct
    "PID-5"        — PID field 5 (patient_name)
    "PID-5.1"      — first component of PID-5
    "PID-3[2]"     — second repetition of PID-3
    "MSH-9.1"      — message code from MSH-9
    "OBX[*]-5"     — field 5 from ALL OBX segments (returns list)
    "OBX[2]-5"     — field 5 from the 2nd OBX segment
    "PID-3[*]"     — ALL repetitions of PID-3 (returns list)

## Examples

    {:ok, msg} = HL7v2.parse(text, mode: :typed)
    patient_name = HL7v2.Access.get(msg, "PID-5")
    mrn = HL7v2.Access.get(msg, "PID-3.1")
    all_obx_values = HL7v2.Access.get(msg, "OBX[*]-5")

# `path`

```elixir
@type path() :: %{
  segment: binary(),
  segment_index: pos_integer() | :all | nil,
  field: pos_integer() | nil,
  component: pos_integer() | nil,
  repetition: pos_integer() | nil
}
```

# `fetch`

```elixir
@spec fetch(HL7v2.TypedMessage.t(), binary() | HL7v2.Path.t()) ::
  {:ok, term()} | {:error, atom()}
```

Fetches a value from a typed message, returning `{:ok, value}` or `{:error, reason}`.

Unlike `get/2`, this function distinguishes between a nil field value and
a resolution failure (unknown segment, invalid path, unknown field).

Accepts both string paths and `%HL7v2.Path{}` structs.

## Examples

    {:ok, pid} = HL7v2.Access.fetch(msg, "PID")
    {:error, :segment_not_found} = HL7v2.Access.fetch(msg, "ZZZ")
    {:error, :invalid_path} = HL7v2.Access.fetch(msg, "not a path")
    {:error, :field_not_found} = HL7v2.Access.fetch(msg, "PID-99")

# `get`

```elixir
@spec get(HL7v2.TypedMessage.t(), binary() | HL7v2.Path.t()) :: term()
```

Gets a value from a typed message using a path string or `%Path{}` struct.

Returns `nil` if the path doesn't resolve.

# `get`

```elixir
@spec get(HL7v2.TypedMessage.t(), binary() | HL7v2.Path.t(), term()) :: term()
```

Gets a value from a typed message with a default.

---

*Consult [api-reference.md](api-reference.md) for complete listing*