form

Documentation

Overview

Package form is an API for working with S-Expression objects.

Index

• type Comment
• type Form
  • func Subforms(f List) []Form
• type List
• type Number
• type SourcePosition
• type String
• type Symbol
• type Valueless
• type Whitespace

Types

type Comment

type Comment interface {
	Valueless

	// Comment returns the comment literal including delimiters.
	//
	// Note that multiple Comments may comprise a single logical comment block
	// separated by whitespace, as the whitespace forms will be parsed
	// separately.
	CommentLiteral() string
}

Comment is an interface for a form with an underlying comment literal.

type Form

type Form interface {
	SourcePosition() SourcePosition
	Value() interface{}
}

Form is a value that may have a corresponding textual representation in a source code file. Forms parsed by this package have an S-expression syntax unless the reader is customized.

A Form has an underlying value, obtainable by calling Value(). For example, the s-expression `"abc"` has an underlying value that is the string "abc".

This package does not define any implementations of Form. FormReader allows a custom FormProvider to be specified that will create a Form for a given underlying value and Sourcespan.

func Subforms

func Subforms(f List) []Form

Subforms returns the ordered list of forms that comprise the list.

The list of forms should be substantive.

type List

type List interface {
	Form

	// Len returns the length of the list. It is equivalent to len(Subforms())
	// but may be more efficient.
	Len() int

	// Nth returns Subforms()[n]. It may panic if the length of the list is
	// <= n.
	Nth(n int) Form
}

List implements Form for a form comprised of an ordered list of subforms.

The s-expression `("abc" xyz)` would be expected to be read as a List with two subforms.

type Number

type Number interface {
	Form

	// Number returns the number using go's constant package. The
	// value should be one of `int64, *big.Int, *big.Float, *big.Rat`.
	Number() constant.Value
}

Number is an interface for a form with an underlying number literal.

A Number is roughly equivalent to an untyped number const in Go.

type SourcePosition

type SourcePosition interface {
	Range() *textpos.Range

	// String returns a human readable representation of the source position.
	String() string
}

SourcePosition is a continuous interval of positions within a text file.

type String

type String interface {
	Form

	// StringValue returns the value of the form as a string literal.
	StringValue() string
}

String is an interface for a form with an underlying string literal representation.

This method should not be implemented by other types of forms, even if they can be represented as a string. For example, a number should implemented Number and not String.

type Symbol

type Symbol interface {
	Form

	// SymbolLiteral returns the symbol as a string. This may be different from the
	// symbol as it appeared in the source text if the reader changes the
	// literal form using some sort of normalization.
	SymbolLiteral() string
}

Symbol is an interface for a form with an underlying Symbol literal.

A Symbol is roughly equivalent to an untyped Symbol const in Go.

type Valueless

type Valueless interface {
	Form

	// The Valueless function indicates that this form should be ignored
	// when read in most contexts. Examples of valueless forms are
	Valueless()
}

Valueless is a form that should be ignored in most contexts. Examples of valueless forms are comments and whitespace.

type Whitespace

type Whitespace interface {
	Valueless

	// Whitespace returns the whiespace literal.
	Whitespace() string
}

Whitespace is an interface for a form with an underlying string literal representation.