segment.go

package protopath

import (
	"strings"
	"unicode"
	"unicode/utf8"
)

// EncodingOption option that configures segments encoding.
type EncodingOption interface {
	configure(encodingPreference) encodingPreference
}

type encodingOptionFunc func(encodingPreference) encodingPreference

func (fn encodingOptionFunc) configure(pref encodingPreference) encodingPreference { return fn(pref) }

// PreferSquareBracketsWrapping returns an encoding option that triggers usage of square brackets wrapping while encoding when path segment value contains dot character. By default, without this option, characters escaping is always performed.
//
// This option is conflicting with ForceSquareBracketsWrapping. When it appears after this option will override it.
func PreferSquareBracketsWrapping() EncodingOption {
	return encodingOptionFunc(func(pref encodingPreference) encodingPreference {
		return pref & ^forceWrapping | preferWrapping
	})
}

// ForceSquareBracketsWrapping returns an encoding option forces usage of square brackets wrapping even if no wrapping or escaping is required.
//
// This option is conflicting with PreferSquareBracketsWrapping. When it appears after this option will override it.
func ForceSquareBracketsWrapping() EncodingOption {
	return encodingOptionFunc(func(pref encodingPreference) encodingPreference {
		return pref | forceWrapping
	})
}

// Segment is a single fragment of the path.
type Segment struct {
	encoded string
	isValid bool // invalid segments have no decoded value
	decoded string
}

// NewSegment creates a new segment, by encoding the provided value. Newly created segments belong to a path made of a single segment - the newly created one. Returned segments are always valid - if the provided value contains a rune that is not properly UTF-8 encoded, is out of range, or is not the shortest possible UTF-8 encoding for that rune, the rune will be replaced by the Unicode replacement character. Otherwise, the segment decoded value will match the given value.
func NewSegment(value string, opts ...EncodingOption) Segment {
	pref := encodingPreference(0)
	for _, o := range opts {
		pref = o.configure(pref)
	}
	return encodeSegmentWithPreferences(value, pref)
}

// IsValid informs if the segment is valid. Invalid segments have improperly encoded segment value, that cannot be decoded.
func (s Segment) IsValid() bool {
	return s.isValid
}

// Encoded returns encoded (marshaled) value of the segment (as is appears in proto path).
func (s Segment) Encoded() string {
	return s.encoded
}

// Value returns decoded (unmarshaled) value of the segment (usable value).
func (s Segment) Value() string {
	return s.decoded
}

func (s Segment) Equal(o Segment) bool {
	if s.isValid != o.isValid {
		return false
	}
	if !s.isValid {
		return s.encoded == o.encoded
	}
	return s.decoded == o.decoded
}

func (s Segment) Compare(o Segment) int {
	if !s.isValid {
		if o.isValid {
			return -1
		}
		return strings.Compare(s.encoded, o.encoded)
	}
	if !o.isValid {
		return 1
	}
	return strings.Compare(s.decoded, o.decoded)
}

func decodeFirstPathSegment(path string) Segment {
	copyFrom, wrapped := 0, false
	if next, _ := nextByte(path); next == '[' {
		copyFrom, wrapped = 1, true
	}
	decoded := []byte{}
	for i := copyFrom; i < len(path); {
		if path[i] >= utf8.RuneSelf {
			r, size := utf8.DecodeRuneInString(string(path[i:]))
			if r == utf8.RuneError && size == 1 {
				return Segment{encoded: path, isValid: false} // invalid UTF-8 string
			}
			i += size
			continue
		}
		if isUnescapedAsciiForIdentifier(path[i]) {
			i++
			continue
		}
		if wrapped && path[i] == '.' {
			i++
			continue
		}
		decoded = append(decoded, path[copyFrom:i]...)
		switch {
		case path[i] == '.': // && !wrapped
			return Segment{encoded: path[:i], decoded: string(decoded), isValid: true} // valid identifier segment value
		case !wrapped && path[i] == '[':
			return Segment{encoded: path[:i], decoded: string(decoded), isValid: true} // valid identifier segment value
		case wrapped && path[i] == ']':
			if next, hasNext := nextByte(path[i+1:]); hasNext && next != '[' && next != '.' {
				return Segment{encoded: path, isValid: false} // invalid segment value - invalid data after wrapped segment
			}
			return Segment{encoded: path[:i+1], decoded: string(decoded), isValid: true} // valid wrapped segment value
		case path[i] == '\\':
			r, escapeSize, ok := parseEscaped(path[i+1:])
			if !ok {
				return Segment{encoded: path, isValid: false} // invalid segment value - invalid escaped sequence
			}
			decoded = append(decoded, string(r)...)
			i += escapeSize + 1
		default:
			return Segment{encoded: path, isValid: false} // invalid segment value - invalid ascii value
		}
		copyFrom = i
	}
	if wrapped {
		return Segment{encoded: path, isValid: false} // invalid wrapped segment value - missing closing bracket
	}
	decoded = append(decoded, path[copyFrom:]...)
	return Segment{encoded: path, decoded: string(decoded), isValid: true} // valid identifier segment value - reaches the path end
}

func isUnescapedAsciiForIdentifier(x byte) bool {
	return (x >= 0x20 && x <= 0x21) || // skip 0x22 " double quote
		(x >= 0x23 && x <= 0x26) || // skip 0x27 ' single quote
		(x >= 0x28 && x <= 0x2D) || // skip 0x2E . dot
		(x >= 0x2F && x <= 0x5A) || // skip 0x5B [ opening square bracket; skip 0x5C \ backslash; skip 0x5D ] closing square bracket
		(x >= 0x5E && x <= 0x7F)
}

func parseEscaped(value string) (rune, int, bool) {
	if len(value) == 0 {
		return 0, 0, false
	}
	switch value[0] {
	case '"':
		return rune('"'), 1, true
	case '\'':
		return rune('\''), 1, true
	case '.':
		return rune('.'), 1, true
	case '[':
		return rune('['), 1, true
	case ']':
		return rune(']'), 1, true
	case '\\':
		return rune('\\'), 1, true
	case 'b':
		return rune('\b'), 1, true
	case 'f':
		return rune('\f'), 1, true
	case 'n':
		return rune('\n'), 1, true
	case 'r':
		return rune('\r'), 1, true
	case 't':
		return rune('\t'), 1, true
	case 'u':
		r := parseHex4(value[1:])
		return r, 4 + 1, r >= 0
	case 'U':
		r := parseHex8(value[1:])
		return r, 8 + 1, r >= 0
	}
	return 0, 0, false // invalid escape sequence
}

func parseHex4(value string) rune {
	if len(value) < 4 {
		return -1
	}
	r := rune(0)
	for range 4 {
		b := value[0]
		switch {
		case b >= '0' && b <= '9':
			r = r<<4 | rune(b-'0')
		case b >= 'a' && b <= 'f':
			r = r<<4 | rune(b-'a'+10)
		case b >= 'A' && b <= 'F':
			r = r<<4 | rune(b-'A'+10)
		default:
			return -1
		}
		value = value[1:]
	}
	if !utf8.ValidRune(r) {
		r = unicode.ReplacementChar
	}
	return r
}

func parseHex8(value string) rune {
	if len(value) < 8 {
		return -1
	}
	r := rune(0)
	for range 8 {
		b := value[0]
		switch {
		case b >= '0' && b <= '9':
			r = r<<4 | rune(b-'0')
		case b >= 'a' && b <= 'f':
			r = r<<4 | rune(b-'a'+10)
		case b >= 'A' && b <= 'F':
			r = r<<4 | rune(b-'A'+10)
		default:
			return -1
		}
		value = value[1:]
	}
	if !utf8.ValidRune(r) {
		r = unicode.ReplacementChar
	}
	return r
}

func nextByte(value string) (byte, bool) {
	if len(value) == 0 {
		return 0, false
	}
	return value[0], true
}

type encodingPreference uint32

const (
	preferWrapping encodingPreference = iota + 1
	forceWrapping
)

func encodeSegmentWithPreferences(value string, pref encodingPreference) Segment {
	switch pref {
	case preferWrapping:
		return encodeSegment(value, strings.ContainsRune(value, '.'))
	case forceWrapping:
		return encodeSegment(value, true)
	default: // no preferences
		return encodeSegment(value, false)
	}
}

const hexToAscii = "0123456789abcdef"

func encodeSegment(value string, wrap bool) Segment {
	var encoded []byte
	var decoded []byte
	if wrap {
		encoded = append(encoded, '[')
	}
	copyFrom := 0
	for i := 0; i < len(value); {
		if value[i] >= utf8.RuneSelf {
			r, size := utf8.DecodeRuneInString(string(value[i:]))
			if r == utf8.RuneError && size == 1 {
				encoded = append(encoded, value[copyFrom:i]...)
				encoded = append(encoded, `\ufffd`...)
				decoded = append(decoded, value[copyFrom:i]...)
				decoded = append(decoded, "\ufffd"...)
				i += size
				copyFrom = i
				continue
			}
			// Do not treat runes U+2028 (line separator) and U+2029 (paragraph separator) in any special way. See https://en.wikipedia.org/wiki/JSON#Safety for more details.
			// It is expected that proto path will be embedded in a JSON string anyway so "encoding/json" package can handle that.
			i += size
			continue
		}
		if isUnescapedAsciiForIdentifier(value[i]) {
			i++
			continue
		}
		encoded = append(encoded, value[copyFrom:i]...)
		decoded = append(decoded, value[copyFrom:i]...)
		switch value[i] {
		case '"':
			encoded = append(encoded, '\\', '"')
		case '\'':
			encoded = append(encoded, '\\', '\'')
		case '.':
			if wrap {
				encoded = append(encoded, '.')
			} else {
				encoded = append(encoded, '\\', '.')
			}
		case '[':
			encoded = append(encoded, '\\', '[')
		case ']':
			encoded = append(encoded, '\\', ']')
		case '\\':
			encoded = append(encoded, '\\', '\\')
		case '\b':
			encoded = append(encoded, '\\', 'b')
		case '\f':
			encoded = append(encoded, '\\', 'f')
		case '\n':
			encoded = append(encoded, '\\', 'n')
		case '\r':
			encoded = append(encoded, '\\', 'r')
		case '\t':
			encoded = append(encoded, '\\', 't')
		default:
			encoded = append(encoded, '\\', 'u', '0', '0', hexToAscii[value[i]>>4], hexToAscii[value[i]&0x0F])
		}
		decoded = append(decoded, value[i])
		i++
		copyFrom = i
	}
	encoded = append(encoded, value[copyFrom:]...)
	decoded = append(decoded, value[copyFrom:]...)
	if wrap {
		encoded = append(encoded, ']')
	}
	return Segment{encoded: string(encoded), decoded: string(decoded), isValid: true}
}