ident

package
v1.0.4 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2024 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package ident contains types for safely representing SQL identifiers.

Index

Constants

This section is empty.

Variables

View Source 
var Public = New("public")

Public is a commonly-used identifier.

Functions

func Comparator 

func Comparator[I Identifier]() func(I, I) bool

Comparator returns a comparison function.

func Compare 

func Compare(a, b Identifier) int

Compare is similar to strings.Compare. It returns -1, 0, or 1 if a should sort before, equal to, or after b. Nil or empty values sort before any non-nil, non-empty value.

func Equal 

func Equal(a, b Identifier) bool

Equal returns true if the identifiers are equal without considering case.

func Join 

func Join(id Identifier, rep Representation, separator rune) string

Join returns the identifiers as a string with the given separator.

func ParseTableRelative 

func ParseTableRelative(s string, relativeTo Schema) (Table, Qualification, error)

ParseTableRelative parses a table name, relative to a base schema. The string must have no more than the number of name parts in relativeTo, plus one for the table name itself.

Types

type Hinted 

type Hinted[I Identifier] struct {
	Base I
	Hint string
}

Hinted decorates the raw and sql-safe string representations of an Identifier with an extra, target-specific hint string.

func WithHint 

func WithHint[I Identifier](id I, hint string) *Hinted[I]

WithHint wraps the identifier with a target-specific hint. An empty hint string is valid.

func (*Hinted[I]) Raw 

func (h *Hinted[I]) Raw() string

Raw implements Identifier and concatenates the underlying raw representation with the hint.

func (*Hinted[I]) String 

func (h *Hinted[I]) String() string

String implements Identifier and concatenates the underlying sql-safe representation with the hint.

type Ident 

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

An Ident is a quoted SQL identifier, generally a table, column, or database.

func New 

func New(raw string) Ident

New returns a quoted SQL identifier. Prefer using ParseIdent when operating on user-provided input that may already be quoted.

func ParseIdent 

func ParseIdent(s string) (Ident, string, error)

ParseIdent extracts the first, possibly-quoted, Ident from the given string. It returns the parsed Ident and the remainder of the input string. An error is returned if there is an unmatched double-quote character.

func (Ident) Canonical 

func (a Ident) Canonical() Ident

Canonical returns a canonical representation of the enclosed ident. That is, it returns a lower-cased form of the SQL identifier.

func (Ident) Empty 

func (a Ident) Empty() bool

Empty implements Identifier and returns true if the identifier is empty.

func (Ident) Idents 

func (a Ident) Idents(buf []Ident) []Ident

Idents implement Identifier.

func (Ident) MarshalJSON 

func (a Ident) MarshalJSON() ([]byte, error)

MarshalJSON implements Identifier, returning a JSON string.

func (Ident) MarshalText 

func (a Ident) MarshalText() ([]byte, error)

MarshalText returns the Identifier's raw form, allowing the value to be used as a JSON map-key.

func (Ident) Raw 

func (a Ident) Raw() string

Raw implements Identifier and returns the original, raw value.

func (Ident) Split 

func (a Ident) Split() (Ident, Identifier)

Split implements Identifier, returning the atom and an empty ident.

func (Ident) String 

func (a Ident) String() string

String returns the atom in a manner suitable for constructing a query.

func (*Ident) UnmarshalJSON 

func (n *Ident) UnmarshalJSON(data []byte) error

UnmarshalJSON converts a raw json string into an Ident.

func (*Ident) UnmarshalText 

func (n *Ident) UnmarshalText(data []byte) error

UnmarshalText converts a raw string into an Ident.

type Identifier 

type Identifier interface {
	encoding.TextMarshaler
	json.Marshaler

	// Empty returns true if the Identifier is blank.
	Empty() bool

	// Idents appends the components of the Identifier to the buffer and
	// returns it. It is valid to pass a nil value for the buffer.
	Idents(buf []Ident) []Ident

	// Raw returns an unquoted representation of the Identifier.
	Raw() string

	// Split returns the first part of a qualified identifier and the
	// remainder.
	//
	// Splitting an unqualified (single-part) identifier returns the
	// identifier and an empty remainder.
	//
	// Splitting an empty Identifier returns two empty Identifiers.
	Split() (first Ident, remainder Identifier)

	// String returns a quoted, concatenation-safe representation of the
	// Identifier that is suitable for use when building queries.
	String() string
}

Identifier represents some, possibly-compound, name in an external system.

type IdentifierMap 

type IdentifierMap[I Identifier, V any] struct {
	// contains filtered or unexported fields
}

IdentifierMap implements a case-preserving, but case-insensitive mapping of Identifier instances to values. Prefer using the specialized types instead.

Usage notes:

  • The zero value of an IdentifierMap is safe to use.
  • An IdentifierMap can be serialized to and from a JSON representation.
  • An IdentifierMap is not internally synchronized.

func (*IdentifierMap[I, V]) CopyInto 

func (m *IdentifierMap[I, V]) CopyInto(dest cmap.Map[I, V])

CopyInto implements cmap.Map.

func (*IdentifierMap[I, V]) Delete 

func (m *IdentifierMap[I, V]) Delete(key I)

Delete implements cmap.Map.

func (*IdentifierMap[I, V]) Entries 

func (m *IdentifierMap[I, V]) Entries() []cmap.Entry[I, V]

Entries implements cmap.Map. This will sort the returned slice to ensure stable iteration order.

func (*IdentifierMap[I, V]) Get 

func (m *IdentifierMap[I, V]) Get(key I) (_ V, ok bool)

Get implements cmap.Map.

func (*IdentifierMap[I, V]) GetZero 

func (m *IdentifierMap[I, V]) GetZero(key I) V

GetZero implements cmap.Map.

func (*IdentifierMap[I, V]) Len 

func (m *IdentifierMap[I, V]) Len() int

Len implements cmap.Map.

func (*IdentifierMap[I, V]) MarshalJSON 

func (m *IdentifierMap[I, V]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*IdentifierMap[I, V]) Match 

func (m *IdentifierMap[I, V]) Match(key I) (_ I, _ V, ok bool)

Match implements cmap.Map.

func (*IdentifierMap[I, V]) Put 

func (m *IdentifierMap[I, V]) Put(key I, value V)

Put implements cmap.Map

func (*IdentifierMap[I, V]) Range 

func (m *IdentifierMap[I, V]) Range(fn func(k I, v V) error) error

Range implements cmap.Map.

func (*IdentifierMap[I, V]) UnmarshalJSON 

func (m *IdentifierMap[I, V]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Idents 

type Idents []Ident

Idents is a slice of Ident.

func (Idents) Equal 

func (n Idents) Equal(o Idents) bool

Equal returns true if the two slices contain equivalent identifiers.

func (Idents) Len 

func (n Idents) Len() int

Len implements sort.Interface.

func (Idents) Less 

func (n Idents) Less(i, j int) bool

Less implements sort.Interface.

func (Idents) Swap 

func (n Idents) Swap(i, j int)

Swap implements sort.Interface.

type Map 

type Map[V any] struct {
	IdentifierMap[Ident, V]
}

Map is a case-insensitive mapping of Ident to values.

func MapOf 

func MapOf[V any](args ...any) *Map[V]

MapOf accepts an even number of arguments and constructs a map of identifiers to values. The identifiers may be given as either an Ident or as a string. This function panics if there is invalid input, so its use should be limited to testing.

func (*Map[V]) Equal 

func (m *Map[V]) Equal(o *Map[V], comparator func(V, V) bool) bool

Equal returns true if the other map is equivalent under identifier case-equivalency. This method exists to reduce the amount of generics syntax needed to call cmap.Equal.

type Qualification 

type Qualification int

Qualification is a return value from ParseTableRelative, indicating how many name parts were present in the initial input. 

const (
	TableOnly Qualification = iota + 1
	PartialSchema
	FullyQualified
)

Various levels of table-identifier qualification.

func (Qualification) String 

func (i Qualification) String() string

type Representation 

type Representation bool

Representation selects from a quoted string or a raw string. 

const (
	// Raw expresses an Identifier as its original text.
	Raw Representation = true
	// Quoted expresses an Identifier as a quoted, escaped string.
	Quoted Representation = false
)

type Schema 

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

A Schema identifier is a multipart identifier for a Table container. This type is immutable and suitable for use as a map key.

func MustSchema 

func MustSchema(parts ...Ident) Schema

MustSchema calls NewSchema and panics if it returns an error. This is intended for use by tests.

func NewSchema 

func NewSchema(parts ...Ident) (Schema, error)

NewSchema constructs a Schema identifier.

func ParseSchema 

func ParseSchema(s string) (Schema, error)

ParseSchema parses a dot-separated schema name.

func (Schema) Canonical 

func (s Schema) Canonical() Schema

Canonical returns a canonicalized form of the SQL schema name. That is, it returns a lower-cased form of the enclosed SQL identifiers.

func (Schema) Contains 

func (s Schema) Contains(table Table) bool

Contains returns true if the given table is defined within the Schema.

func (Schema) Empty 

func (a Schema) Empty() bool

Empty returns true if the Schema has no name.

func (Schema) Idents 

func (a Schema) Idents(buf []Ident) []Ident

Idents implements HasIdents.

func (Schema) MarshalJSON 

func (a Schema) MarshalJSON() ([]byte, error)

MarshalJSON returns the Schema as an array.

func (Schema) MarshalText 

func (a Schema) MarshalText() ([]byte, error)

MarshalText returns the raw, dotted form of the Schema.

func (Schema) Raw 

func (a Schema) Raw() string

Raw returns the original, raw value.

func (Schema) Relative 

func (s Schema) Relative(parts ...Ident) (Schema, Qualification, error)

Relative returns a new schema, relative to the receiver. For an input of N parts, the trailing N elements of the receiver will be replaced.

func (Schema) Schema 

func (s Schema) Schema() Schema

Schema implements Schematic.

func (Schema) Split 

func (a Schema) Split() (Ident, Identifier)

Split returns the first atom as an Ident and an array for the remainder.

func (Schema) String 

func (a Schema) String() string

String returns the identifier in a manner suitable for constructing a query.

func (*Schema) UnmarshalJSON 

func (s *Schema) UnmarshalJSON(data []byte) error

UnmarshalJSON parses an array of strings.

type SchemaFlag 

type SchemaFlag Schema

SchemaFlag allows Schema fields to be used with the spf13 flags package.

func NewSchemaFlag 

func NewSchemaFlag(id *Schema) *SchemaFlag

NewSchemaFlag wraps the given Schema so that it can be used with the spf13 flags package.

func (*SchemaFlag) Set 

func (v *SchemaFlag) Set(s string) error

Set implements Value.

func (*SchemaFlag) String 

func (v *SchemaFlag) String() string

String returns the raw value of the underlying Ident.

func (*SchemaFlag) Type 

func (v *SchemaFlag) Type() string

Type implements Value.

type SchemaMap 

type SchemaMap[V any] struct {
	IdentifierMap[Schema, V]
}

SchemaMap is a case-insensitive mapping of Schema to values.

type Schematic 

type Schematic interface {
	// Schema returns the (enclosing) Schema.
	Schema() Schema
}

Schematic is anything that is or is enclosed by a Schema.

type StagingSchema 

type StagingSchema Schema

StagingSchema is a type alias for the name of the "_replicator.public" table schema. It serves as an injection point for uniquely naming the staging database in test cases.

func (StagingSchema) Schema 

func (s StagingSchema) Schema() Schema

Schema returns the underying database identifier.

type Table 

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

A Table is an identifier with an enclosing Schema.

func NewTable 

func NewTable(enclosing Schema, name Ident) Table

NewTable constructs a Table identifier.

func ParseTable 

func ParseTable(s string) (Table, error)

ParseTable parses a table name.

func (Table) Canonical 

func (t Table) Canonical() Table

Canonical returns a canonical form of the table identifier. That is, it returns a lower-cased form of the enclosed identifiers.

func (Table) Empty 

func (q Table) Empty() bool

Empty implements Identifier.

func (Table) Idents 

func (q Table) Idents(buf []Ident) []Ident

Idents implements Identifier.

func (Table) MarshalJSON 

func (q Table) MarshalJSON() ([]byte, error)

MarshalJSON returns the ident as an array.

func (Table) MarshalText 

func (q Table) MarshalText() ([]byte, error)

MarshalText returns the raw, dotted form of the Table.

func (Table) Raw 

func (q Table) Raw() string

Raw implements Identifier.

func (Table) Schema 

func (t Table) Schema() Schema

Schema implements Schematic by returning the enclosing Schema.

func (Table) Split 

func (q Table) Split() (Ident, Identifier)

Split implements Identifier. It returns the first element of the namespace and constructs a new array that contains the terminal atom.

func (Table) String 

func (q Table) String() string

String returns the identifier in a manner suitable for constructing a query.

func (Table) Table 

func (t Table) Table() Ident

Table returns the table's identifier.

func (*Table) UnmarshalJSON 

func (t *Table) UnmarshalJSON(data []byte) error

UnmarshalJSON parses a JSON array.

func (*Table) UnmarshalText 

func (t *Table) UnmarshalText(data []byte) error

UnmarshalText initializes the Table from its MarshalText representation.

type TableMap 

type TableMap[V any] struct {
	IdentifierMap[Table, V]
}

TableMap is a case-insensitive mapping of Table to values.

type UDT 

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

A UDT is the name of a user-defined type, such as an enum.

func NewUDT 

func NewUDT(enclosing Schema, name Ident) UDT

NewUDT constructs an identifier for a user-defined type.

func NewUDTArray 

func NewUDTArray(enclosing Schema, name Ident) UDT

NewUDTArray constructs an identifier for a UDT array.

func (UDT) Empty 

func (q UDT) Empty() bool

Empty implements Identifier.

func (UDT) Idents 

func (q UDT) Idents(buf []Ident) []Ident

Idents implements Identifier.

func (UDT) IsArray 

func (t UDT) IsArray() bool

IsArray returns true if the UDT is an array type.

func (UDT) MarshalJSON 

func (t UDT) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*UDT) MarshalText 

func (t *UDT) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (UDT) Name 

func (t UDT) Name() Ident

Name returns the UDT's leaf name identifier.

func (UDT) Raw 

func (t UDT) Raw() string

Raw implements Identifier.

func (UDT) Schema 

func (t UDT) Schema() Schema

Schema returns the schema from the UDT.

func (UDT) Split 

func (q UDT) Split() (Ident, Identifier)

Split implements Identifier. It returns the first element of the namespace and constructs a new array that contains the terminal atom.

func (UDT) String 

func (t UDT) String() string

String returns the quoted form of the UDT, possibly with an array suffix.

func (*UDT) UnmarshalJSON 

func (t *UDT) UnmarshalJSON(data []byte) error

UnmarshalJSON parses a JSON array.

type Value 

type Value Ident

Value allows Idents to be used with the spf13 flags package.

func NewValue 

func NewValue(value string, id *Ident) *Value

NewValue wraps the given Ident so that it can be used with the spf13 flags package.

func (*Value) Set 

func (v *Value) Set(s string) error

Set implements Value.

func (*Value) String 

func (v *Value) String() string

String returns the raw value of the underlying Ident.

func (*Value) Type 

func (v *Value) Type() string

Type implements Value.

Source Files

View all Source files

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.