doc

README

doc

WIP. Abstract document database API, akin to database/sql

Documentation

Index

• Constants
• Variables
• func Close(d *DB) error
• func Drivers() []string
• func ExpandPairs(args StringifyArgs, sb *strings.Builder, pairs ...any) string
• func Option[T any](options Optional) (*T, bool)
• func Register(name string, driver Driver)
• type Allocator
• type DB
  • func Open(driverName, dataSourceName string) (*DB, error)
  • func (d *DB) Close() error
  • func (d *DB) Expr(expr string, v Validator) Expr
  • func (d *DB) Private(a any) error
• type DeleteRequest
  • func (r DeleteRequest[T]) ItemAny() any
• type DeleteRequestAny
• type DeleteResponse
  • func Delete[T any](d *DB, req DeleteRequest[T]) (DeleteResponse, error)
• type DocOption
  • func WithLocal(local Local) DocOption
• type DocOptions
  • func MakeDocOptions(opts ...DocOption) *DocOptions
• type Driver
• type Expr
  • func NewExpr(f Format, tokens ...any) (Expr, error)
• type ExtractBinary
• type Fields
  • func NewFields(names ...string) *Fields
  • func (f *Fields) Names() []string
• type Filter
• type Format
  • func FormatWithDefaults(f Format) Format
• type GetFlags
• type GetOneResponse
  • func GetOne[T any](d *DB, req GetRequest) (GetOneResponse[T], error)
  • func (r GetOneResponse[T]) With(opt any) GetOneResponse[T]
• type GetRequest
  • func (r GetRequest) With(opt any) GetRequest
• type GetResponse
  • func Get[T any](d *DB, req GetRequest) (GetResponse[T], error)
  • func (r GetResponse[T]) With(opt any) GetResponse[T]
• type ItemOpt
• type Local
• type Optional
• type PrivateDriver
• type SetRequest
  • func (r SetRequest[T]) GetFilter() Filter
  • func (r SetRequest[T]) ItemAny() any
  • func (r SetRequest[T]) With(opt any) SetRequest[T]
• type SetRequestAny
• type SetResponse
  • func Set[T any](d *DB, req SetRequest[T]) (SetResponse[T], error)
  • func (r SetResponse[T]) With(opt any) SetResponse[T]
• type StringifyArgs
• type Validator

Constants

const (
	// Expose parser-private data for the drivers.
	AndKeyword    = parser.AndKeyword
	AssignKeyword = parser.AssignKeyword
	ListKeyword   = parser.ListKeyword
	OrKeyword     = parser.OrKeyword
)

const (
	RuleOff        = iota // No rule will be applied in the filter
	RuleSetItem           // The item is being set -- all fields are allowed.
	RuleCreateItem        // The item is being created -- all fields are set except auto-generated ones
)

Variables

var FilterCreateItem = Filter{Rule: RuleCreateItem}

var FilterOff = Filter{}

var FilterSetItem = Filter{Rule: RuleSetItem}

Functions

func Close

func Close(d *DB) error

Close safely closes the DB. Does this function seem ridiculous? It is. But there is SO MUCH error handling in Go, I'm constantly experimenting with little ways to tame it.

func Drivers

func Drivers() []string

Drivers returns a sorted list of the names of the registered drivers.

func ExpandPairs

func ExpandPairs(args StringifyArgs, sb *strings.Builder, pairs ...any) string

ExpandPairs compiles all values in pairs into a single comma-separated string. There must be an even number of pairs, which are treated as key=values. sep is inserted between each pair. String values are quoted with quoteRune. (use rune(0) if you don't want quotes).

func Option

func Option[T any](options Optional) (*T, bool)

func Register

func Register(name string, driver Driver)

Types

type Allocator

type Allocator interface {
	// New answers a new object
	New() any
	// TypeName answers the typename of the object type I create.
	TypeName() string
}

type DB

type DB struct {
	// contains filtered or unexported fields
}

func Open

func Open(driverName, dataSourceName string) (*DB, error)

func (*DB) Close

func (d *DB) Close() error

func (*DB) Expr

func (d *DB) Expr(expr string, v Validator) Expr

Answer a new expression, using the optional validator and the driver's formatting.

func (*DB) Private

func (d *DB) Private(a any) error

Private sends a private data to the driver. This is a debug utility; the specification is entirely driver dependent.

type DeleteRequest

type DeleteRequest[T any] struct {
	Optional
	Item T
}

DeleteRequest

func (DeleteRequest[T]) ItemAny

func (r DeleteRequest[T]) ItemAny() any

type DeleteRequestAny

type DeleteRequestAny interface {
	ItemAny() any
}

DeleteRequestAny provides access to the item of a Delete request.

type DeleteResponse

type DeleteResponse struct {
	Optional
}

func Delete

func Delete[T any](d *DB, req DeleteRequest[T]) (DeleteResponse, error)

type DocOption

type DocOption func(*DocOptions)

func WithLocal

func WithLocal(local Local) DocOption

type DocOptions

type DocOptions struct {
	Local Local
}

func MakeDocOptions

func MakeDocOptions(opts ...DocOption) *DocOptions

type Driver

type Driver interface {
	Open(dataSourceName string) (Driver, error)
	Close() error

	// Format provides driver-specific formatting rules
	// when converting an expression to a string. Return
	// nil for the default rules.
	Format() Format

	// Get performs a query based on the request parameters.
	// The responses are collected in the allocator, and the
	// driver can return any additional data in the first return param.
	Get(req GetRequest, a Allocator) (*Optional, error)

	Set(req SetRequestAny, a Allocator) (*Optional, error)

	Delete(req DeleteRequestAny, a Allocator) (*Optional, error)
}

type Expr

type Expr interface {
	// Compile the expression. No-op for already-compiled expressions.
	// Expressions that are not compiled may need to be compiled whenever
	// you ask for any info.
	Compile() (Expr, error)

	// Format answers the expression as a formatted string.
	Format() (string, error)

	// Extract allows clients to pull structured information from the Expr.
	// The argument should implement one or more of the Extract* interfaces.
	Extract(any) error
}

func NewExpr

func NewExpr(f Format, tokens ...any) (Expr, error)

NewExpr answers a new compiled expression based on the supplied tokens. Tokens will be interpreted as keywords if they exist. This bypasses the parsing stage -- it's an optimization for knowledgeable clients, but also can only handle simple phrases, so in general clients should prefer passing in an expression string.

type ExtractBinary

type ExtractBinary = parser.ExtractBinary

ExtractBinary is passed to Expr.Extract.

type Fields

type Fields struct {
	// contains filtered or unexported fields
}

Fields stores a list of field names.

func NewFields

func NewFields(names ...string) *Fields

func (*Fields) Names

func (f *Fields) Names() []string

type Filter

type Filter struct {
	// Rule provides some predefined rules to determine what fields are
	// allowed. Optional.
	Rule int64
}

Filter determines what fields are allowed during an operation.

type Format

type Format = parser.Format

Expose the parser format to consumers of the doc package without requiring them to import the parser package. Conceptually, parser is completely private.

func FormatWithDefaults

func FormatWithDefaults(f Format) Format

FormatWithDefaults answers the supplied format, adding default behaviour for anything the supplied format leaves unhandled. f can be nil if you just want the default formatting.

type GetFlags

type GetFlags uint64

const (
	GetUnique GetFlags = (1 << iota) // Return only items that have unique values.
)

type GetOneResponse

type GetOneResponse[T any] struct {
	Optional
	Result *T
}

GetOneResponse provides output from a GetOne operation.

func GetOne

func GetOne[T any](d *DB, req GetRequest) (GetOneResponse[T], error)

GetOne returns a single item based on the get condition.

func (GetOneResponse[T]) With

func (r GetOneResponse[T]) With(opt any) GetOneResponse[T]

type GetRequest

type GetRequest struct {
	Optional
	Condition Expr    // Matching condition to accept a record.
	Fields    *Fields // Limit response to these specific fields.
	Limit     int     // Limit to the number of items
	Flags     GetFlags
}

GetRequest provides parameters to a Get operation.

func (GetRequest) With

func (r GetRequest) With(opt any) GetRequest

type GetResponse

type GetResponse[T any] struct {
	Optional
	Results []*T
}

GetResponse provides output from a Get operation.

func Get

func Get[T any](d *DB, req GetRequest) (GetResponse[T], error)

Get returns a list of items based on the get condition.

func (GetResponse[T]) With

func (r GetResponse[T]) With(opt any) GetResponse[T]

type ItemOpt

type ItemOpt[T any] struct {
	Item *T
}

type Local

type Local interface {
}

type Optional

type Optional struct {
	Options []any
}

type PrivateDriver

type PrivateDriver interface {
	Private(any) error
}

type SetRequest

type SetRequest[T any] struct {
	Optional

	// The item to set.
	Item T

	// Filter is used to determine which fields will be set.
	// An empty filter will set all fields.
	Filter Filter
}

SetRequest provides parameters to a Set operation.

func (SetRequest[T]) GetFilter

func (r SetRequest[T]) GetFilter() Filter

func (SetRequest[T]) ItemAny

func (r SetRequest[T]) ItemAny() any

func (SetRequest[T]) With

func (r SetRequest[T]) With(opt any) SetRequest[T]

type SetRequestAny

type SetRequestAny interface {
	ItemAny() any
	GetFilter() Filter
}

SetRequestAny provides access to the item of a Set request.

type SetResponse

type SetResponse[T any] struct {
	Optional
	Item *T
}

SetResponse provides output from a Set operation.

func Set

func Set[T any](d *DB, req SetRequest[T]) (SetResponse[T], error)

func (SetResponse[T]) With

func (r SetResponse[T]) With(opt any) SetResponse[T]

type StringifyArgs

type StringifyArgs struct {
	Separator string
	Quote     rune
}

type Validator

type Validator interface {
	// Return true if the field name is valid.
	AcceptField(name string) bool
}

Validator is used to validate an expression.