builder.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

// MessageBuilder constructs an HL7 message from scratch using terser-style
// field paths. It wraps the same byte-buffer machinery used by Transform,
// seeded with a minimal MSH skeleton instead of a source message.
//
// Example:
//
//	b := NewMessageBuilder()
//	b.Set("MSH-9.1", "ADT")
//	b.Set("MSH-9.2", "A01")
//	b.Set("PID-3.1", "12345")
//	msg, err := b.Build()
type MessageBuilder struct {
	w      workBuf
	delims Delimiters
}

// BuilderOption configures a MessageBuilder.
type BuilderOption func(*MessageBuilder)

// WithDelimiters sets the delimiter characters for the builder.
// By default, NewMessageBuilder uses DefaultDelimiters().
func WithDelimiters(d Delimiters) BuilderOption {
	return func(b *MessageBuilder) {
		b.delims = d
	}
}

// NewMessageBuilder creates a builder with a minimal MSH skeleton.
// Defaults to DefaultDelimiters() if no WithDelimiters option is provided.
func NewMessageBuilder(opts ...BuilderOption) (*MessageBuilder, error) {
	b := &MessageBuilder{delims: DefaultDelimiters()}
	for _, opt := range opts {
		opt(b)
	}
	if err := b.delims.validate(); err != nil {
		return nil, err
	}
	b.w = newEmptyWorkBuf(b.delims)
	return b, nil
}

// Set sets the value at the given terser-style location (e.g. "PID-3.1").
// The value is plain text and will be escaped for the builder's delimiter set.
// Returns ErrInvalidLocation or ErrMSHDelimiterField on invalid input.
func (b *MessageBuilder) Set(location, value string) error {
	loc, err := validateLocation(location)
	if err != nil {
		return err
	}
	escaped := Escape([]byte(value), b.delims)
	applyValueAtLocation(&b.w, b.delims, loc, escaped)
	return nil
}

// SetNull sets the field at location to the HL7 null value ("").
// Returns ErrInvalidLocation or ErrMSHDelimiterField on invalid input.
func (b *MessageBuilder) SetNull(location string) error {
	loc, err := validateLocation(location)
	if err != nil {
		return err
	}
	applyValueAtLocation(&b.w, b.delims, loc, nullValue)
	return nil
}

// Build finalizes the message and returns a parsed *Message.
// The builder remains usable after Build — subsequent Set calls
// modify the builder's state and a new Build produces a new Message.
func (b *MessageBuilder) Build() (*Message, error) {
	return b.w.parse()
}