conl

README

CONL is a post-minimal, human-centric configuration language.

This repo contains the Go implementation, documented at https://pkg.go.dev/github.com/ConradIrwin/conl-go.

Documentation

Overview

Package conl implements CONL parsing and serializing.

CONL is a post-modern, human-centric configuration language. It is designed to be a easy to read, easy to edit, and easy to parse, in that order. It uses a JSON-like structure of scalars, maps, and lists; an INI-like type system to defer scalar parsing until runtime; and a (simplified) YAML-like syntax for indentation.

; a basic CONL document
map
  a = b
list
  = a
  = b
scalar = value

Like the builtin json package, CONL can automatically convert between Go types and CONL values.

For example, you could parse the above document into a struct defined in Go as:

type Example struct {
  Map map[string]string `conl:"map"`
  List []string `conl:"list"`
  Scalar string `conl:"scalar"`
}

example := Example{}
conl.Unmarshal(data, &example)

If your type implements the encoding.TextMarshaler and encoding.TextUnmarshaler then CONL will use that to convert between a scalar and your type, otherwise scalars are parsed using the strconv package.

Package conl supports a very similar set of Go types to encoding/json. In particular, any string, number, or boolean value can be serialized; as can any struct, map, array, or slive of such values. On the flip side, channels and functions cannot be serialized. Unlike json, conl allows map keys to be numbers, bools, or arrays or structs of those types in addition to strings.

Index

• Constants
• func Marshal(v any) ([]byte, error)
• func Tokens(input []byte) iter.Seq[Token]
• func Unmarshal(data []byte, v any) error
• type Token
• type TokenKind
  • func (k TokenKind) GoString() string
  • func (k TokenKind) String() string

Constants

const (
	Comment = TokenKind(iota)
	Indent
	Outdent
	MapKey
	ListItem
	Scalar
	NoValue
	MultilineScalar
	MultilineHint
)

These tokens are yielded from Tokens.

Functions

func Marshal

func Marshal(v any) ([]byte, error)

Marshal converts a go value to a CONL document.

It returns an error if the value could not be marshaled (for example if it contains a channel or a func).

func Tokens

func Tokens(input []byte) iter.Seq[Token]

Tokens iterates over tokens in the input string.

The raw tokens are post-processed to maintain the invariants that:

• Indent and Outdent are always paired correctly
• (igoring [Comment]s) after a ListItem or a MapKey, you will always get one of [Value], MultilineHint, NoValue or Indent
• after a MultilineHint you will always get a [MultilineValue]
• within a given section you will only find ListItem or MapKey, not a mix.

Any parse errors are reported in [Token.Error]. The parser is tolerant to errors, though the resulting document may not be what the user intended, so you should handle errors appropriately.

func Unmarshal

func Unmarshal(data []byte, v any) error

Unmarshal updates the value v with the data from the CONL document. v should be a non-nil pointer to a struct, slice, map, interface, array. Unmarshal acts similarly to json.Unmarshal.

For struct fields, CONL will first look for the name in a `conl:"name"` tag, then in a `json:"name"` tag, and finally use the snake_case version of the field name or the field name itself.

When unmarshalling into an interface, CONL maps will be unmarshalled into a map[string]any, lists will be unmarshalled into []any, and scalars will be unmarshalled to string.

If the CONL document is invalid, or doesn't match the type of `v`, then an error will be returned.

Types

type Token

type Token struct {
	Lno     int
	Kind    TokenKind
	Content string
	Error   error
}

type TokenKind

type TokenKind int8

TokenKind represents the possible kinds of token in a CONL document.

func (TokenKind) GoString

func (k TokenKind) GoString() string

func (TokenKind) String

func (k TokenKind) String() string