accessor.go

// Copyright 2026 Joshua Jones <joshua.jones.software@gmail.com>
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package hl7

import (
	"strconv"
	"unsafe"
)

// Location represents a specific position in an HL7 message hierarchy.
// All indices are 0-based internally. The string representation uses
// 1-based field/component/subcomponent indices for HL7 convention.
type Location struct {
	Segment      string // 3-char segment type, e.g., "PID"
	SegmentIndex int    // 0-based: which occurrence of this segment type
	Field        int    // 1-based field number (0 = segment type)
	Repetition   int    // 0-based repetition index
	Component    int    // 1-based component number (0 = not specified)
	SubComponent int    // 1-based subcomponent number (0 = not specified)
}

// String returns the terser-style string representation of the location.
// This is the inverse of ParseLocation.
//
// Examples:
//
//	Location{Segment: "MSH", Field: 9}.String()                          // "MSH-9"
//	Location{Segment: "PID", Field: 3, Component: 1}.String()            // "PID-3.1"
//	Location{Segment: "OBX", SegmentIndex: 1, Field: 5}.String()         // "OBX(1)-5"
//	Location{Segment: "PID", Field: 3, Repetition: 1}.String()           // "PID-3[1]"
func (loc Location) String() string {
	b := make([]byte, len(loc.Segment), 110)
	copy(b, []byte(loc.Segment))
	if loc.SegmentIndex > 0 {
		b = append(b, '(')
		b = strconv.AppendInt(b, int64(loc.SegmentIndex), 10)
		b = append(b, ')')
	}
	b = append(b, '-')
	b = strconv.AppendInt(b, int64(loc.Field), 10)
	if loc.Repetition > 0 {
		b = append(b, '[')
		b = strconv.AppendInt(b, int64(loc.Repetition), 10)
		b = append(b, ']')
	}
	if loc.Component > 0 {
		b = append(b, '.')
		b = strconv.AppendInt(b, int64(loc.Component), 10)
	}
	if loc.SubComponent > 0 {
		b = append(b, '.')
		b = strconv.AppendInt(b, int64(loc.SubComponent), 10)
	}
	return unsafe.String(unsafe.SliceData(b), len(b))
}

// ParseLocation parses a terser-style location string into a Location.
//
// Supported formats:
//
//	"MSH-9"              segment-field
//	"MSH-9.1"            segment-field.component
//	"MSH-9.1.2"          segment-field.component.subcomponent
//	"OBX(1)-5"           segment(segIndex)-field  (0-based segment index)
//	"PID-3[1]"           segment-field[repIndex]  (0-based repetition index)
//	"PID-3[1].4.2"       full specification
//
// Returns ErrInvalidLocation if the string cannot be parsed.
func ParseLocation(s string) (Location, error) {
	var loc Location
	n := len(s)
	if n == 0 {
		return loc, ErrInvalidLocation
	}

	i := 0

	// Segment type: scan until '(' or '-'.
	start := i
	for i < n && s[i] != '(' && s[i] != '-' {
		i++
	}
	loc.Segment = s[start:i]
	if len(loc.Segment) < 2 || len(loc.Segment) > 3 {
		return loc, ErrInvalidLocation
	}

	// Optional segment index: '(' digits ')'.
	if i < n && s[i] == '(' {
		i++ // skip '('
		start = i
		for i < n && s[i] != ')' {
			i++
		}
		if i >= n || i == start {
			return loc, ErrInvalidLocation
		}
		num, err := strconv.Atoi(s[start:i])
		if err != nil {
			return loc, ErrInvalidLocation
		}
		loc.SegmentIndex = num
		i++ // skip ')'
	}

	// Expect '-'.
	if i >= n || s[i] != '-' {
		return loc, ErrInvalidLocation
	}
	i++ // skip '-'
	if i >= n {
		return loc, ErrInvalidLocation
	}

	// Field number: scan digits.
	start = i
	for i < n && s[i] >= '0' && s[i] <= '9' {
		i++
	}
	if i == start {
		return loc, ErrInvalidLocation
	}
	num, err := strconv.Atoi(s[start:i])
	if err != nil {
		return loc, ErrInvalidLocation
	}
	loc.Field = num
	if i >= n {
		return loc, nil
	}

	// Optional repetition: '[' digits ']'.
	if s[i] == '[' {
		i++ // skip '['
		start = i
		for i < n && s[i] != ']' {
			i++
		}
		if i >= n || i == start {
			return loc, ErrInvalidLocation
		}
		num, err := strconv.Atoi(s[start:i])
		if err != nil {
			return loc, ErrInvalidLocation
		}
		loc.Repetition = num
		i++ // skip ']'
	}
	if i >= n {
		return loc, nil
	}

	// Optional component: '.' digits.
	if s[i] != '.' {
		return loc, ErrInvalidLocation
	}
	i++ // skip '.'
	start = i
	for i < n && s[i] >= '0' && s[i] <= '9' {
		i++
	}
	if i > start {
		num, err := strconv.Atoi(s[start:i])
		if err != nil {
			return loc, ErrInvalidLocation
		}
		loc.Component = num
	}
	if i >= n {
		return loc, nil
	}

	// Optional subcomponent: '.' digits.
	if s[i] != '.' {
		return loc, ErrInvalidLocation
	}
	i++ // skip '.'
	start = i
	for i < n && s[i] >= '0' && s[i] <= '9' {
		i++
	}
	if i > start {
		num, err := strconv.Atoi(s[start:i])
		if err != nil {
			return loc, ErrInvalidLocation
		}
		loc.SubComponent = num
	}

	// Reject trailing characters.
	if i != n {
		return loc, ErrInvalidLocation
	}

	return loc, nil
}

// Value holds the raw bytes at a terser-style location, returned by Get.
// It is a lightweight value type (raw []byte + Delimiters), consistent with
// Field, Repetition, Component, and Subcomponent.
//
// A zero Value (nil raw bytes) is returned when the location is invalid or
// the addressed element is not present in the message. A zero Value is empty:
// IsEmpty() returns true, String() returns "", and Bytes() returns nil.
type Value struct {
	raw    []byte
	delims Delimiters
}

// String returns the unescaped string value. Returns an empty string for a
// zero (not-found) Value.
func (v Value) String() string {
	return string(v.Bytes())
}

// Bytes returns the unescaped bytes of this value. Equivalent to calling
// String() and converting, but avoids the string allocation for binary use.
// Returns nil for a zero (not-found) Value.
func (v Value) Bytes() []byte {
	return Unescape(v.raw, v.delims)
}

// Raw returns the raw, possibly-escaped bytes of this value as they appear
// in the HL7 message (before escape processing). Returns nil for a zero Value.
func (v Value) Raw() []byte {
	return v.raw
}

// IsEmpty returns true if the value was not present (nil raw bytes).
func (v Value) IsEmpty() bool {
	return len(v.raw) == 0
}

// IsNull returns true if the value is the HL7 explicit null, represented by
// two double-quote characters ("").
func (v Value) IsNull() bool {
	return len(v.raw) == 2 && v.raw[0] == '"' && v.raw[1] == '"'
}

// HasValue returns true if the value is neither empty nor null.
func (v Value) HasValue() bool {
	return !v.IsEmpty() && !v.IsNull()
}

// Get retrieves the value at the given terser-style location.
//
// Returns a zero Value if the location string is invalid or the addressed
// element is not present — consistent with how Field(n), Rep(n), Component(n),
// and SubComponent(n) return zero values for out-of-range indices.
//
// Examples:
//
//	msg.Get("MSH-9").String()      // Message type field (full value, unescaped)
//	msg.Get("MSH-9.1").String()    // Message code (e.g., "ADT")
//	msg.Get("MSH-9.2").String()    // Trigger event (e.g., "A01")
//	msg.Get("PID-3.1").String()    // Patient ID
//	msg.Get("PID-5.1").String()    // Family name
//	msg.Get("OBX(0)-5").String()   // First OBX segment, field 5
//	msg.Get("PID-3.1").Bytes()     // unescaped bytes
//	msg.Get("PID-3.1").Raw()       // raw bytes without unescaping
func (m *Message) Get(location string) Value {
	loc, err := ParseLocation(location)
	if err != nil {
		return Value{}
	}
	return m.getByLocation(loc)
}

// getByLocation navigates the message hierarchy to the specified location.
func (m *Message) getByLocation(loc Location) Value {
	// Find the matching segment.
	matchIdx := 0
	var seg *Segment
	for i := range m.segments {
		if m.segments[i].Type() == loc.Segment {
			if matchIdx == loc.SegmentIndex {
				seg = &m.segments[i]
				break
			}
			matchIdx++
		}
	}
	if seg == nil {
		return Value{}
	}

	field := seg.Field(loc.Field)
	if field.IsEmpty() {
		return Value{}
	}

	rep := field.Rep(loc.Repetition)
	if rep.IsEmpty() {
		return Value{}
	}

	// If no component specified, return the repetition.
	if loc.Component == 0 {
		return rep.Value
	}

	comp := rep.Component(loc.Component)
	if comp.IsEmpty() && loc.SubComponent == 0 {
		return Value{}
	}

	// If no subcomponent specified, return the component.
	if loc.SubComponent == 0 {
		return comp.Value
	}

	sub := comp.SubComponent(loc.SubComponent)
	return sub.Value
}