keyval

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 25, 2023 License: MIT Imports: 1 Imported by: 0

Documentation

Overview

Package keyval contains types representing key-values and related utilities. These types model both queries and the data returned by queries. They can be constructed from query strings using [parser.Parser] but are also designed to be easily constructed directly in Go source code.

Embedded Query Strings

When working with SQL, programmers will often embed SQL strings in the application. This requires extra tooling to catch syntax errors at build time. Instead of using string literals, FDBQ allows the programmer to directly construct the queries using the types in this package, allowing some syntax errors to be caught at build time.

This package does not prevent all kinds of syntax errors, only "structural" ones. For instance, the type system ensures tuples only contain valid elements and limits what kinds of objects can be used as the value of a key-value. In spite of this, invalid queries can still be constructed (see package class).

Operations (Visitor Pattern)

The Directory, Tuple, & Value types would be best represented by tagged unions. While Go does not natively support tagged unions, this codebase implements equivalent functionality using the visitor pattern. See package [operation] which generates the boilerplate code associated with this. See DirectoryOperation, TupleOperation, or ValueOperation as examples of the generated code.

Primitive Types

There are a special group of types defined in this package named the "primitive" types. These include Nil, Int, Uint, Bool, Float, String, UUID, and Bytes. All of these types can be used as a TupElement or as a Value. When used as a TupElement, they are serialized by FDB tuple packing. When used as a Value, they are known as a "primitive" values and are serialized by FDBQ.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Bool 

type Bool bool

Bool is a "primitive" type implementing a bool as either a TupElement or Value. When used as a Value, it's serialized as a single byte (0 for false, 1 for true).

func (Bool) Eq 

func (x Bool) Eq(e interface{}) bool

func (Bool) TupElement 

func (x Bool) TupElement(op TupleOperation)

func (Bool) Value 

func (x Bool) Value(op ValueOperation)

type Bytes 

type Bytes []byte

Bytes is a "primitive" type implementing a byte string as either a TupElement or Value. When used as a Value, it's serialized as is.

func (Bytes) Eq 

func (x Bytes) Eq(e interface{}) bool

func (Bytes) TupElement 

func (x Bytes) TupElement(op TupleOperation)

func (Bytes) Value 

func (x Bytes) Value(op ValueOperation)

type Clear 

type Clear struct{}

Clear is a special kind of Value which designates a KeyValue as a clear query. When executed, the provided key is cleared from the DB. Clear may not be used in a query containing Variable.

func (Clear) Eq 

func (x Clear) Eq(e interface{}) bool

func (Clear) Value 

func (x Clear) Value(op ValueOperation)

type DirElement 

type DirElement interface {
	// DirElement executes the given DirectoryOperation on this DirElement.
	DirElement(DirectoryOperation)

	// Eq returns true if the given value is equal to this DirElement.
	Eq(interface{}) bool
}

type Directory 

type Directory []DirElement

Directory can be passed to [engine.Engine] as a directory query. These kinds of queries define a directory path schema. When executed, all directories matching the schema are returned.

func (Directory) Eq 

func (x Directory) Eq(e interface{}) bool

func (Directory) Query 

func (x Directory) Query(op QueryOperation)

type DirectoryOperation 

type DirectoryOperation interface {
	// ForString performs the DirectoryOperation if the given DirElement is of type String.
	ForString(String)
	// ForVariable performs the DirectoryOperation if the given DirElement is of type Variable.
	ForVariable(Variable)
}

type Float 

type Float float64

Float is a "primitive" type implementing a float64 as either a TupElement or Value. When used as a Value, it's serialized as an 8-byte array in accordance with IEEE 754. Endianness depends on how the [engine.Engine] is configured.

func (Float) Eq 

func (x Float) Eq(e interface{}) bool

func (Float) TupElement 

func (x Float) TupElement(op TupleOperation)

func (Float) Value 

func (x Float) Value(op ValueOperation)

type Int 

type Int int64

Int is a "primitive" type implementing an int64 as either a TupElement or Value. When used as a Value, it's serialized as a 2-compliment 8-byte string. Endianness depends on how the [engine.Engine] is configured.

func (Int) Eq 

func (x Int) Eq(e interface{}) bool

func (Int) TupElement 

func (x Int) TupElement(op TupleOperation)

func (Int) Value 

func (x Int) Value(op ValueOperation)

type Key 

type Key struct {
	Directory Directory
	Tuple     Tuple
}

Key can be passed to [engine.Engine] as a query. When used as a query, it is equivalent to a KeyValue whose Value is an empty Variable.

func (Key) Eq 

func (x Key) Eq(e interface{}) bool

func (Key) Query 

func (x Key) Query(op QueryOperation)

type KeyValue 

type KeyValue struct {
	Key   Key
	Value Value
}

KeyValue can be passed to [engine.Engine] as a query or be returned from [engine.Engine] as a query's result. When returned as a result, KeyValue will not contain a Variable, Clear, or MaybeMore.

func (KeyValue) Eq 

func (x KeyValue) Eq(e interface{}) bool

func (KeyValue) Query 

func (x KeyValue) Query(op QueryOperation)

type MaybeMore 

type MaybeMore struct{}

MaybeMore is a special kind of TupElement. It may only appear as the last element of the Tuple. A Query containing a MaybeMore defines a schema which allows all keys prefixed by the key in the schema. TODO: Implement as a flag on Tuple.

func (MaybeMore) Eq 

func (x MaybeMore) Eq(e interface{}) bool

func (MaybeMore) TupElement 

func (x MaybeMore) TupElement(op TupleOperation)

type Nil 

type Nil struct{}

Nil is a "primitive" type representing an empty element when used as a TupElement. It's equivalent to an empty Bytes when used as a Value. Go's nil value is never allowed in a Key or KeyValue. Instead, use this type.

func (Nil) Eq 

func (x Nil) Eq(e interface{}) bool

func (Nil) TupElement 

func (x Nil) TupElement(op TupleOperation)

func (Nil) Value 

func (x Nil) Value(op ValueOperation)

type Query 

type Query = query

Query is an interface implemented by the types which can be passed to [engine.Engine] as a query. This includes KeyValue, Key, & Directory.

type QueryOperation 

type QueryOperation interface {
	// ForDirectory performs the QueryOperation if the given query is of type Directory.
	ForDirectory(Directory)
	// ForKey performs the QueryOperation if the given query is of type Key.
	ForKey(Key)
	// ForKeyValue performs the QueryOperation if the given query is of type KeyValue.
	ForKeyValue(KeyValue)
}

type String 

type String string

String is a "primitive" type implementing a string as either a TupElement or Value. When used as a Value, it's serialized as a UTF-8 encoded byte string.

func (String) DirElement 

func (x String) DirElement(op DirectoryOperation)

func (String) Eq 

func (x String) Eq(e interface{}) bool

func (String) TupElement 

func (x String) TupElement(op TupleOperation)

func (String) Value 

func (x String) Value(op ValueOperation)

type TupElement 

type TupElement interface {
	// TupElement executes the given TupleOperation on this TupElement.
	TupElement(TupleOperation)

	// Eq returns true if the given value is equal to this TupElement.
	Eq(interface{}) bool
}

type Tuple 

type Tuple []TupElement

Tuple may contain a Tuple, Variable, MaybeMore, or any of the "primitive" types.

func (Tuple) Eq 

func (x Tuple) Eq(e interface{}) bool

func (Tuple) TupElement 

func (x Tuple) TupElement(op TupleOperation)

func (Tuple) Value 

func (x Tuple) Value(op ValueOperation)

type TupleOperation 

type TupleOperation interface {
	// ForTuple performs the TupleOperation if the given TupElement is of type Tuple.
	ForTuple(Tuple)
	// ForNil performs the TupleOperation if the given TupElement is of type Nil.
	ForNil(Nil)
	// ForInt performs the TupleOperation if the given TupElement is of type Int.
	ForInt(Int)
	// ForUint performs the TupleOperation if the given TupElement is of type Uint.
	ForUint(Uint)
	// ForBool performs the TupleOperation if the given TupElement is of type Bool.
	ForBool(Bool)
	// ForFloat performs the TupleOperation if the given TupElement is of type Float.
	ForFloat(Float)
	// ForString performs the TupleOperation if the given TupElement is of type String.
	ForString(String)
	// ForUUID performs the TupleOperation if the given TupElement is of type UUID.
	ForUUID(UUID)
	// ForBytes performs the TupleOperation if the given TupElement is of type Bytes.
	ForBytes(Bytes)
	// ForVariable performs the TupleOperation if the given TupElement is of type Variable.
	ForVariable(Variable)
	// ForMaybeMore performs the TupleOperation if the given TupElement is of type MaybeMore.
	ForMaybeMore(MaybeMore)
}

type UUID 

type UUID [16]byte

UUID is a "primitive" type implementing a 16-byte string as either a TupElement or Value. When used as a Value, it's serialized as is.

func (UUID) Eq 

func (x UUID) Eq(e interface{}) bool

func (UUID) TupElement 

func (x UUID) TupElement(op TupleOperation)

func (UUID) Value 

func (x UUID) Value(op ValueOperation)

type Uint 

type Uint uint64

Uint is a "primitive" type implementing a uint64 as either a TupElement or Value. When used as a Value, it's serialized as an 8-byte array. Endianness depends on how the [engine.Engine] is configured.

func (Uint) Eq 

func (x Uint) Eq(e interface{}) bool

func (Uint) TupElement 

func (x Uint) TupElement(op TupleOperation)

func (Uint) Value 

func (x Uint) Value(op ValueOperation)

type Value 

type Value = value

Value may contain Tuple, Variable, Clear, or any of the "primitive" types.

type ValueOperation 

type ValueOperation interface {
	// ForTuple performs the ValueOperation if the given value is of type Tuple.
	ForTuple(Tuple)
	// ForNil performs the ValueOperation if the given value is of type Nil.
	ForNil(Nil)
	// ForInt performs the ValueOperation if the given value is of type Int.
	ForInt(Int)
	// ForUint performs the ValueOperation if the given value is of type Uint.
	ForUint(Uint)
	// ForBool performs the ValueOperation if the given value is of type Bool.
	ForBool(Bool)
	// ForFloat performs the ValueOperation if the given value is of type Float.
	ForFloat(Float)
	// ForString performs the ValueOperation if the given value is of type String.
	ForString(String)
	// ForUUID performs the ValueOperation if the given value is of type UUID.
	ForUUID(UUID)
	// ForBytes performs the ValueOperation if the given value is of type Bytes.
	ForBytes(Bytes)
	// ForVariable performs the ValueOperation if the given value is of type Variable.
	ForVariable(Variable)
	// ForClear performs the ValueOperation if the given value is of type Clear.
	ForClear(Clear)
}

type ValueType 

type ValueType string

ValueType defines the expected types of a Variable. 

const (
	// AnyType designates a Variable to allow any value.
	// A Variable containing AnyType and an empty Variable
	// are equivalent.
	AnyType ValueType = ""

	// IntType designates a Variable to allow Int values.
	IntType ValueType = "int"

	// UintType designates a Variable to allow Uint values.
	UintType ValueType = "uint"

	// BoolType designates a Variable to allow Bool values.
	BoolType ValueType = "bool"

	// FloatType designates a Variable to allow Float values.
	FloatType ValueType = "float"

	// StringType designates a Variable to allow String values.
	StringType ValueType = "string"

	// BytesType designates a Variable to allow Bytes values.
	BytesType ValueType = "bytes"

	// UUIDType designates a Variable to allow UUID values.
	UUIDType ValueType = "uuid"

	// TupleType designates a Variable to allow Tuple values.
	TupleType ValueType = "tuple"
)

func AllTypes 

func AllTypes() []ValueType

AllTypes returns all valid values for ValueType.

type Variable 

type Variable []ValueType

Variable is a placeholder which implements the DirElement, TupElement, & Value interfaces. A Query containing a Variable defines a schema. When the Query is executed, all key-values (or directories) matching the schema are returned.

func (Variable) DirElement 

func (x Variable) DirElement(op DirectoryOperation)

func (Variable) Eq 

func (x Variable) Eq(e interface{}) bool

func (Variable) TupElement 

func (x Variable) TupElement(op TupleOperation)

func (Variable) Value 

func (x Variable) Value(op ValueOperation)

Source Files

View all Source files

Directories

Path Synopsis
Package class classifies a key-value by the kind of operation it represents.
 Package class classifies a key-value by the kind of operation it represents.
Package compare validates tuples against a schema.
 Package compare validates tuples against a schema.
Package convert converts between FDBQ and FDB types.
 Package convert converts between FDBQ and FDB types.
Operation generates the interfaces and glue-code for the visitor pattern.
 Operation generates the interfaces and glue-code for the visitor pattern.
Package values serializes and deserializes values.
 Package values serializes and deserializes values.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.