variable

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Mar 14, 2024 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package variable contains utilities for describing and representing environment variables.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultRegistry = &Registry{
	IsDefault: true,
}

DefaultRegistry is the default specification registry.

Functions

func EstablishRelationships 

func EstablishRelationships(relationships ...Relationship)

EstablishRelationships establishes the given relationships.

func InverseRelationships 

func InverseRelationships[T Relationship](s Spec) []T

InverseRelationships returns a list of relationships where s is the object.

func IsDefault 

func IsDefault(s Spec, v Literal) bool

IsDefault returns true if v is the default value of the given spec.

func Relationships 

func Relationships[T Relationship](s Spec) []T

Relationships returns a list of relationships where s is the subject.

func ResetDefaultRegistry 

func ResetDefaultRegistry()

ResetDefaultRegistry removes all variables from DefaultRegistry.

func UnwrapNumericParseError 

func UnwrapNumericParseError[T constraints.Integer | constraints.Float](
	err error,
	format func(T) string,
) error

UnwrapNumericParseError returns a more user-friendly error message for errors returned by strconv.ParseInt(), ParseUint(), and ParseFloat().

Types

type Any 

type Any interface {
	Spec() Spec
	Availability() Availability
	Source() Source
	Value() Value
	Error() Error
}

Any is an interface for an environment variable of any type.

type Availability 

type Availability int

Availability is an enumeration describing why a variable is or is not available. 

const (
	// AvailabilityNone indicates that the variable's value is not available
	// because it has not been explicitly defined in the environment and no
	// default value has been specified.
	AvailabilityNone Availability = iota

	// AvailabilityInvalid indicates that the variable is defined with an
	// invalid value.
	AvailabilityInvalid

	// AvailabilityIgnored indicates that the variable's value valid but it
	// should not be made available to the user.
	AvailabilityIgnored

	// AvailabilityOK indicates that the variable's value is valid and available
	// to the user.
	AvailabilityOK
)

type Binary 

type Binary interface {
	LengthLimited

	// EncodingDescription returns a short (one word, ideally) human-readable
	// description of the encoding scheme.
	EncodingDescription() string
}

Binary is a schema that allows input of binary data.

type Constraint 

type Constraint interface {
	// Description returns a description of the constraint.
	Description() string

	// IsUserDefined returns true if this constraint was defined by the user.
	IsUserDefined() bool
}

A Constraint represents a constraint on the variable value in addition to the schema's requirements.

type ConstraintError 

type ConstraintError interface {
	error
}

ConstraintError indicates that a value does not satisfy a constraint.

type DependsOn 

type DependsOn struct {
	Subject, DependsOn Spec
}

DependsOn is a relationship type that indicates that a variable requires another variable to be "truthy" in order be used.

type Documentation 

type Documentation struct {
	// Summary is a short summary of the documentation.
	//
	// It may be empty. If provided it must be plain text.
	Summary string

	// Paragraphs is a list of paragraphs to show.
	//
	// Simple inline Markdown formatting is allowed, but the value used in
	// contexts where the plain text is shown directly to the user.
	Paragraphs []string

	// IsImportant indicates that the documentation is important and should be
	// made obvious to the user.
	IsImportant bool
}

Documentation is free-form documentation about a variable.

type DocumentationBuilder 

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

DocumentationBuilder is a fluent interface for building a documentation.

func (DocumentationBuilder) Done 

func (b DocumentationBuilder) Done()

Done returns an option that adds the documentation to the variable spec.

func (DocumentationBuilder) Important 

func (b DocumentationBuilder) Important() DocumentationBuilder

Important marks the documentation as important.

func (DocumentationBuilder) Paragraph 

func (b DocumentationBuilder) Paragraph(text ...string) ParagraphFormatter

Paragraph adds a paragraph to the documentation.

text is concatenated together with a space to form the paragraph text. The entire paragraph is a Printf() style format specifier.

func (DocumentationBuilder) Summary 

func (b DocumentationBuilder) Summary(summary string) DocumentationBuilder

Summary sets the summary of the documentation.

type Error 

type Error interface {
	error

	// Name returns the name of the environment variable.
	Name() string
}

Error is an error that indicates a problem parsing or validating an environment variable.

type Example 

type Example struct {
	Canonical   Literal
	Description string
	IsNormative bool
	Source      ExampleSource
}

Example is an example value.

func BestExample 

func BestExample(spec Spec) Example

BestExample returns the heuristically "best" example to use for the given spec.

type ExampleSource 

type ExampleSource int

ExampleSource is an enumeration describing the source of an example. 

const (
	// ExampleSourceUnknown indicates the source of an example is unknown.
	ExampleSourceUnknown ExampleSource = iota

	// ExampleSourceSchema indicates the example was taken from the schema, such
	// as a minimum or maximum value.
	ExampleSourceSchema

	// ExampleSourceSpecBuilder indicates that the examples was supplied to the
	// specification via a SpecBuilder.
	ExampleSourceSpecBuilder

	// ExampleSourceSpecDefault indicates that the example was generated from
	// the default value of the variable.
	ExampleSourceSpecDefault
)

type LengthLimited 

type LengthLimited interface {
	Schema

	// MinLength returns the minimum permitted length of the native value.
	MinLength() (int, bool)

	// MaxLength returns the maximum permitted length of the native value.
	MaxLength() (int, bool)

	// LengthDescription returns a human-readable description of the length that
	// the limit applies to.
	//
	// It must produce a gramatical sentence of the form:
	//  "The value must have <desc> of exactly 5 bytes.
	LengthDescription() string
}

LengthLimited is an interface for a Schema that impose a minimum and/or maximum length on an environment variable value.

type Literal 

type Literal struct {
	String string
}

Literal the string representation of an environment variable value.

func (Literal) Quote 

func (l Literal) Quote() string

Quote returns an escaped string representation of the value that can be used directly in the shell.

type Marshaler 

type Marshaler[T any] interface {
	// Marshal converts a value to its literal representation.
	Marshal(T) (Literal, error)

	// Unmarshal converts a literal value to it's native representation.
	Unmarshal(Literal) (T, error)
}

Marshaler converts values to/from their native/literal representations.

type MaxError 

type MaxError struct {
	Numeric Numeric
}

MaxError indicates that a numeric value was greater than the maximum permitted value.

func (MaxError) AcceptVisitor 

func (e MaxError) AcceptVisitor(v SchemaErrorVisitor)

AcceptVisitor passes the error to the appropriate method of v.

func (MaxError) Error 

func (e MaxError) Error() string

func (MaxError) Schema 

func (e MaxError) Schema() Schema

Schema returns the schema that was violated.

type MaxLengthError 

type MaxLengthError struct {
	ViolatedSchema LengthLimited
}

MaxLengthError indicates that a value was greater than the maximum permitted length.

func (MaxLengthError) AcceptVisitor 

func (e MaxLengthError) AcceptVisitor(v SchemaErrorVisitor)

AcceptVisitor passes the error to the appropriate method of v.

func (MaxLengthError) Error 

func (e MaxLengthError) Error() string

func (MaxLengthError) Schema 

func (e MaxLengthError) Schema() Schema

Schema returns the schema that was violated.

type MinError 

type MinError struct {
	Numeric Numeric
}

MinError indicates that a numeric value was less than the minimum permitted value.

func (MinError) AcceptVisitor 

func (e MinError) AcceptVisitor(v SchemaErrorVisitor)

AcceptVisitor passes the error to the appropriate method of v.

func (MinError) Error 

func (e MinError) Error() string

func (MinError) Schema 

func (e MinError) Schema() Schema

Schema returns the schema that was violated.

type MinLengthError 

type MinLengthError struct {
	ViolatedSchema LengthLimited
}

MinLengthError indicates that a value was shorter than the minimum permitted length.

func (MinLengthError) AcceptVisitor 

func (e MinLengthError) AcceptVisitor(v SchemaErrorVisitor)

AcceptVisitor passes the error to the appropriate method of v.

func (MinLengthError) Error 

func (e MinLengthError) Error() string

func (MinLengthError) Schema 

func (e MinLengthError) Schema() Schema

Schema returns the schema that was violated.

type Numeric 

type Numeric interface {
	Schema

	// Min returns the minimum permitted value as a literal.
	Min() (Literal, bool)

	// Max returns the maximum permitted value as a literal.
	Max() (Literal, bool)

	// Limits returns the range of permitted values.
	//
	// explicit is true if both the minimum and the maximum limits are specified
	// by the application, or false if either of the limits is simply the limit
	// of the underlying type.
	Limits() (min, max Literal, explicit bool)

	// Bits is the number of bits used to store the number.
	Bits() int
}

Numeric is a schema that allows numeric values.

type OfType 

type OfType[T any] struct {
	// contains filtered or unexported fields
}

OfType is an environment variable depicted by type T.

func Register 

func Register[T any](
	registries []*Registry,
	spec *TypedSpec[T],
) *OfType[T]

Register registers a new variable with one or more registries.

If no registries are specified, DefaultRegistry is used.

func (*OfType[T]) Availability 

func (v *OfType[T]) Availability() Availability

Availability returns the variable's availability.

func (*OfType[T]) Error 

func (v *OfType[T]) Error() Error

Error returns an error describing the variable's state.

If the variable's availability is AvailabilityInvalid the error is guaranteed to be a ValueError.

The error is nil if the variable is in a valid state, which occurs when it has an availability of AvailabilityOK, or if it has an availability of AvailabilityNone and v.Spec().IsRequired() is false.

func (*OfType[T]) NativeValue 

func (v *OfType[T]) NativeValue() T

NativeValue returns the variable's value.

If no value is available it returns a zero-value. It is the caller's responsibility to check the variable's availability before using the value.

func (*OfType[T]) Source 

func (v *OfType[T]) Source() Source

Source returns the source of the variable's value.

func (*OfType[T]) Spec 

func (v *OfType[T]) Spec() Spec

Spec returns the variable's specification.

func (*OfType[T]) Value 

func (v *OfType[T]) Value() Value

Value returns the variable's value.

If no value is available it returns a zero-value. It is the caller's responsibility to check the variable's availability before using the value.

type Other 

type Other interface {
	Schema
}

Other is a schema for representing values of arbitrary types.

It should be used as a last resort when no other schema offers a better explanation of the value.

type ParagraphFormatter 

type ParagraphFormatter struct {
	// Format applies the given values to the paragraph template.
	Format func(...any) DocumentationBuilder
}

ParagraphFormatter is a fluent interface for applying values to a paragraph template.

type ProtectedRegistry 

type ProtectedRegistry interface {
	// contains filtered or unexported methods
}

ProtectedRegistry is an interface that allows access to the internals of a Registry.

type RefersTo 

type RefersTo struct {
	Subject, RefersTo Spec
}

RefersTo is a relationship type that indicates that a variable refers to another variable for information/documentation purposes.

type RegisteredVariable 

type RegisteredVariable struct {
	Any
	Registry *Registry
	// contains filtered or unexported fields
}

RegisteredVariable is a variable that is associated with a specific source Registry.

type Registry 

type Registry struct {
	Key, Name string
	URL       *url.URL
	IsDefault bool
	// contains filtered or unexported fields
}

Registry is a collection of environment variable specifications.

func ExposeRegistry 

func ExposeRegistry(r ProtectedRegistry) *Registry

ExposeRegistry returns exposes the underlying registry of r.

func (*Registry) Assign 

func (r *Registry) Assign(reg *Registry)

Assign copies the contents of reg into r.

func (*Registry) Clone 

func (r *Registry) Clone() *Registry

Clone returns a copy of the registry.

func (*Registry) Register 

func (r *Registry) Register(v Any)

Register registers a new variable with the registry.

type RegistrySet 

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

RegistrySet is a set of multiple environment variable registries

func (*RegistrySet) Add 

func (s *RegistrySet) Add(r *Registry)

Add adds r to the set.

It panics if r contains any variables that are already defined in another registry in the set.

Any changes to r after it is added to the set are not reflected in the set.

func (*RegistrySet) IsEmpty 

func (s *RegistrySet) IsEmpty() bool

IsEmpty returns true if the set contains no registries.

func (*RegistrySet) Variables 

func (s *RegistrySet) Variables() []RegisteredVariable

Variables returns the variables in the registries, sorted by name.

type Relationship 

type Relationship interface {
	// contains filtered or unexported methods
}

Relationship represents a relationship between two variables.

type Schema 

type Schema interface {
	// Type returns the type of the native value.
	Type() reflect.Type

	// Finalize prepares the schema for use.
	//
	// It returns an error if schema is invalid.
	Finalize() error

	// AcceptVisitor passes the schema to the appropriate method of v.
	AcceptVisitor(v SchemaVisitor)
}

Schema describes the valid values of an environment variable value.

type SchemaError 

type SchemaError interface {
	error

	// Schema returns the schema that was violated.
	Schema() Schema

	// AcceptVisitor passes the error to the appropriate method of v.
	AcceptVisitor(v SchemaErrorVisitor)
}

SchemaError indicates that a value is invalid because it violates its schema.

type SchemaErrorVisitor 

type SchemaErrorVisitor interface {
	// Numeric errors ...
	VisitMinError(MinError)
	VisitMaxError(MaxError)

	// Set errors...
	VisitSetMembershipError(SetMembershipError)

	// String errors ...
	VisitMinLengthError(MinLengthError)
	VisitMaxLengthError(MaxLengthError)
}

SchemaErrorVisitor dispatches based on the type of a SchemaError.

type SchemaVisitor 

type SchemaVisitor interface {
	VisitBinary(Binary)
	VisitNumeric(Numeric)
	VisitSet(Set)
	VisitString(String)
	VisitOther(Other)
}

SchemaVisitor dispatches based on a variable's schema.

type Set 

type Set interface {
	Schema

	// Literals returns the members of the set as literals.
	Literals() []Literal
}

Set is a schema that only allows a specific set of static values.

type SetMember 

type SetMember[T any] struct {
	Value       T
	Description string
}

SetMember is a member of a TypedSet.

type SetMembershipError 

type SetMembershipError struct {
	Set Set
}

SetMembershipError is a validation error that indicates a value is not a member of a specific set.

func (SetMembershipError) AcceptVisitor 

func (e SetMembershipError) AcceptVisitor(v SchemaErrorVisitor)

AcceptVisitor passes the error to the appropriate method of v.

func (SetMembershipError) Error 

func (e SetMembershipError) Error() string

func (SetMembershipError) Schema 

func (e SetMembershipError) Schema() Schema

Schema returns the schema that was violated.

type Source 

type Source int

Source is an enumeration of the possible sources of an environment variable's value. 

const (
	// SourceNone indicates that there is no value, and hence no source.
	SourceNone Source = iota

	// SourceDefault indicates that the value is the default value in the
	// variable's specification.
	SourceDefault

	// SourceEnvironment indicates that the value was obtained from the
	// environment.
	SourceEnvironment
)

type Spec 

type Spec interface {
	// Name returns the name of the variable.
	Name() string

	// Description returns a human-readable description of the variable.
	Description() string

	// Schema returns the schema that applies to the variable's value.
	Schema() Schema

	// Zero returns the string representation of the zero value.
	Zero() Literal

	// Default returns the string representation of the default value.
	Default() (Literal, bool)

	// IsRequired returns true if the application MUST have a value for this
	// variable (even if it is fulfilled by a default value).
	IsRequired() bool

	// IsSensitive returns true if the variable's value contains sensitive
	// information.
	IsSensitive() bool

	// IsDeprecated returns true if the variable is deprecated.
	IsDeprecated() bool

	// Constraints returns a list of additional constraints on the variable's
	// value.
	Constraints() []Constraint

	// Examples returns a list of additional examples.
	//
	// The implementation MUST return at least one example.
	Examples() []Example

	// Documentation returns a list of chunks of documentation text.
	Documentation() []Documentation

	// Relationships returns a list of relationships that involve this variable.
	Relationships() []Relationship
	// contains filtered or unexported methods
}

Spec is a specification of a variable.

type SpecBuilder 

type SpecBuilder interface {
	Name(string)
	Description(string)
	MarkRequired()
	MarkDeprecated()
	MarkSensitive()
	Documentation() DocumentationBuilder
	Precondition(func() bool)
	Peek() Spec
}

SpecBuilder builds a specification for an environment variable.

type SpecError 

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

SpecError represents a problem with a variable specification itself, rather than the variable's value.

func (SpecError) Error 

func (e SpecError) Error() string

func (SpecError) Name 

func (e SpecError) Name() string

Name returns the name of the environment variable.

func (SpecError) Unwrap 

func (e SpecError) Unwrap() error

type String 

type String interface {
	LengthLimited
}

String is a schema that allows arbitrary string input.

type Supersedes 

type Supersedes struct {
	Subject, Supersedes Spec
}

Supersedes is a relationship type that indicates that a variable supersedes another (usually deprecated) variable.

type TypedBinary 

type TypedBinary[T ~[]B, B ~byte] struct {
	Marshaler      Marshaler[T]
	MinLen, MaxLen maybe.Value[int]
	EncodingDesc   string
}

TypedBinary is a string value depicted by type T.

func (TypedBinary[T, B]) AcceptVisitor 

func (s TypedBinary[T, B]) AcceptVisitor(v SchemaVisitor)

AcceptVisitor passes s to the appropriate method of v.

func (TypedBinary[T, B]) EncodingDescription 

func (s TypedBinary[T, B]) EncodingDescription() string

EncodingDescription returns a short (one word, ideally) human-readable description of the encoding scheme.

func (TypedBinary[T, B]) Examples 

func (s TypedBinary[T, B]) Examples(conservative bool) []TypedExample[T]

Examples returns a (possibly empty) set of examples of valid values.

func (TypedBinary[T, B]) Finalize 

func (s TypedBinary[T, B]) Finalize() error

Finalize prepares the schema for use.

It returns an error if schema is invalid.

func (TypedBinary[T, B]) LengthDescription added in v1.3.0 

func (s TypedBinary[T, B]) LengthDescription() string

LengthDescription returns a human-readable description of the length that the limit applies to.

func (TypedBinary[T, B]) Marshal 

func (s TypedBinary[T, B]) Marshal(v T) (Literal, error)

Marshal converts a value to its literal representation.

func (TypedBinary[T, B]) MaxLength 

func (s TypedBinary[T, B]) MaxLength() (int, bool)

MaxLength returns the maximum permitted length of the native value.

func (TypedBinary[T, B]) MinLength 

func (s TypedBinary[T, B]) MinLength() (int, bool)

MinLength returns the minimum permitted length of the native value.

func (TypedBinary[T, B]) Type 

func (s TypedBinary[T, B]) Type() reflect.Type

Type returns the type of the native value.

func (TypedBinary[T, B]) Unmarshal 

func (s TypedBinary[T, B]) Unmarshal(v Literal) (T, error)

Unmarshal converts a literal value to it's native representation.

type TypedConstraint 

type TypedConstraint[T any] interface {
	Constraint

	// Check returns an error if v does not satisfy the constraint.
	Check(T) ConstraintError
}

TypedConstraint places a constraint on the variable value in addition to the schema's requirements.

type TypedExample 

type TypedExample[T any] struct {
	Native      T
	Description string
	IsNormative bool
}

TypedExample is an example value depicted by type T.

type TypedNumeric 

type TypedNumeric[T constraints.Integer | constraints.Float] struct {
	Marshaler            Marshaler[T]
	NativeMin, NativeMax maybe.Value[T]
}

TypedNumeric is a numeric value depicted by type T.

func (TypedNumeric[T]) AcceptVisitor 

func (s TypedNumeric[T]) AcceptVisitor(v SchemaVisitor)

AcceptVisitor passes s to the appropriate method of v.

func (TypedNumeric[T]) Bits 

func (s TypedNumeric[T]) Bits() int

Bits is the number of bits used to store the number.

func (TypedNumeric[T]) Examples 

func (s TypedNumeric[T]) Examples(conservative bool) []TypedExample[T]

Examples returns a (possibly empty) set of examples of valid values.

func (TypedNumeric[T]) Finalize 

func (s TypedNumeric[T]) Finalize() error

Finalize prepares the schema for use.

It returns an error if schema is invalid.

func (TypedNumeric[T]) Limits 

func (s TypedNumeric[T]) Limits() (min, max Literal, explicit bool)

Limits returns the range of permitted values.

explicit is true if both the minimum and the maximum limits are specified by the application, or false if either of the limits is simply the limit of the underlying type.

func (TypedNumeric[T]) Marshal 

func (s TypedNumeric[T]) Marshal(v T) (Literal, error)

Marshal converts a value to its literal representation.

func (TypedNumeric[T]) Max 

func (s TypedNumeric[T]) Max() (Literal, bool)

Max returns the maximum permitted value as a literal.

func (TypedNumeric[T]) Min 

func (s TypedNumeric[T]) Min() (Literal, bool)

Min returns the minimum permitted value as a literal.

func (TypedNumeric[T]) Type 

func (s TypedNumeric[T]) Type() reflect.Type

Type returns the type of the native value.

func (TypedNumeric[T]) Unmarshal 

func (s TypedNumeric[T]) Unmarshal(v Literal) (T, error)

Unmarshal converts a literal value to it's native representation.

type TypedOther 

type TypedOther[T any] struct {
	Marshaler Marshaler[T]
}

TypedOther is a schema for representing values of arbitrary types.

It should be used as a last resort when no other schema offers a better explanation of the value.

func (TypedOther[T]) AcceptVisitor 

func (s TypedOther[T]) AcceptVisitor(v SchemaVisitor)

AcceptVisitor passes s to the appropriate method of v.

func (TypedOther[T]) Examples 

func (s TypedOther[T]) Examples(bool) []TypedExample[T]

Examples returns a (possibly empty) set of examples of valid values.

func (TypedOther[T]) Finalize 

func (s TypedOther[T]) Finalize() error

Finalize prepares the schema for use.

It returns an error if schema is invalid.

func (TypedOther[T]) Marshal 

func (s TypedOther[T]) Marshal(v T) (Literal, error)

Marshal converts a value to its literal representation.

func (TypedOther[T]) Type 

func (s TypedOther[T]) Type() reflect.Type

Type returns the type of the native value.

func (TypedOther[T]) Unmarshal 

func (s TypedOther[T]) Unmarshal(v Literal) (T, error)

Unmarshal converts a literal value to it's native representation.

type TypedSchema 

type TypedSchema[T any] interface {
	Schema
	Marshaler[T]

	// Examples returns a (possibly empty) set of examples of valid values.
	//
	// If conservative is true, the schema should only return examples that
	// are fairly likely to be meaningful to the application.
	//
	// If conservative is false, the schema should return as many examples
	// as possible, even if they are not very likely to be meaningful.
	Examples(conservative bool) []TypedExample[T]
}

TypedSchema describes the valid values of an environment varible value depicted by type T.

type TypedSet 

type TypedSet[T any] struct {
	Members   []SetMember[T]
	ToLiteral func(T) Literal
}

TypedSet is a Set containing values of type T.

func (TypedSet[T]) AcceptVisitor 

func (s TypedSet[T]) AcceptVisitor(v SchemaVisitor)

AcceptVisitor passes s to the appropriate method of v.

func (TypedSet[T]) Examples 

func (s TypedSet[T]) Examples(bool) []TypedExample[T]

Examples returns a (possibly empty) set of examples of valid values.

func (TypedSet[T]) Finalize 

func (s TypedSet[T]) Finalize() error

Finalize prepares the schema for use.

It returns an error if schema is invalid.

func (TypedSet[T]) Literals 

func (s TypedSet[T]) Literals() []Literal

Literals returns the members of the set as literals.

func (TypedSet[T]) Marshal 

func (s TypedSet[T]) Marshal(v T) (Literal, error)

Marshal converts a value to its literal representation.

func (TypedSet[T]) Type 

func (s TypedSet[T]) Type() reflect.Type

Type returns the type of the native value.

func (TypedSet[T]) Unmarshal 

func (s TypedSet[T]) Unmarshal(v Literal) (T, error)

Unmarshal converts a literal value to it's native representation.

type TypedSpec 

type TypedSpec[T any] struct {
	// contains filtered or unexported fields
}

TypedSpec builds a specification for a variable depicted by type T.

func (*TypedSpec[T]) CheckConstraints 

func (s *TypedSpec[T]) CheckConstraints(v T) ConstraintError

CheckConstraints returns an error if v does not satisfy any one of the specification's constraints.

func (*TypedSpec[T]) Constraints 

func (s *TypedSpec[T]) Constraints() []Constraint

Constraints returns a list of additional constraints on the variable's value.

func (*TypedSpec[T]) Default 

func (s *TypedSpec[T]) Default() (Literal, bool)

Default returns the string representation of the default value.

func (*TypedSpec[T]) Description 

func (s *TypedSpec[T]) Description() string

Description returns a human-readable description of the variable.

func (*TypedSpec[T]) Documentation 

func (s *TypedSpec[T]) Documentation() []Documentation

Documentation returns a list of chunks of documentation text.

func (*TypedSpec[T]) Examples 

func (s *TypedSpec[T]) Examples() []Example

Examples returns a list of examples of valid values.

func (*TypedSpec[T]) IsDeprecated 

func (s *TypedSpec[T]) IsDeprecated() bool

IsDeprecated returns true if the variable is deprecated.

func (*TypedSpec[T]) IsRequired 

func (s *TypedSpec[T]) IsRequired() bool

IsRequired returns true if the application MUST have a value for this variable (even if it is fulfilled by a default value).

func (*TypedSpec[T]) IsSensitive 

func (s *TypedSpec[T]) IsSensitive() bool

IsSensitive returns true if the variable's value contains sensitive information.

func (*TypedSpec[T]) Marshal 

func (s *TypedSpec[T]) Marshal(v T) (Literal, error)

Marshal converts a value to its literal representation.

It returns an error if v does not meet the specification's constraints or marshaling fails at the schema level.

func (*TypedSpec[T]) Name 

func (s *TypedSpec[T]) Name() string

Name returns the name of the variable.

func (TypedSpec[T]) Relationships 

func (s TypedSpec[T]) Relationships() []Relationship

Relationships returns a list of relationships that involve this variable.

func (*TypedSpec[T]) Schema 

func (s *TypedSpec[T]) Schema() Schema

Schema returns the schema that applies to the variable's value.

func (*TypedSpec[T]) Unmarshal 

func (s *TypedSpec[T]) Unmarshal(v Literal) (T, Literal, error)

Unmarshal converts a literal value to it's native representation.

It returns an error if v does not meet the specification's constraints or unmarshaling fails at the schema level.

func (*TypedSpec[T]) Zero 

func (s *TypedSpec[T]) Zero() Literal

Zero returns the string representation of the zero value.

type TypedSpecBuilder 

type TypedSpecBuilder[T any] struct {
	// contains filtered or unexported fields
}

TypedSpecBuilder builds a specification for a variable of type T.

func (*TypedSpecBuilder[T]) BuiltInConstraint 

func (b *TypedSpecBuilder[T]) BuiltInConstraint(
	desc string,
	fn func(T) ConstraintError,
)

BuiltInConstraint adds a constraint to the variable's value.

If fn was supplied by the application developer (as opposed to from within Ferrite itself), use UserConstraint() instead.

func (*TypedSpecBuilder[T]) Default 

func (b *TypedSpecBuilder[T]) Default(v T)

Default sets the default value for the variable.

func (*TypedSpecBuilder[T]) Description 

func (b *TypedSpecBuilder[T]) Description(desc string)

Description sets a human-readable description of the environment variable.

func (*TypedSpecBuilder[T]) Documentation 

func (b *TypedSpecBuilder[T]) Documentation() DocumentationBuilder

Documentation adds documentation to the variable.

It returns the DocumentBuilder that can be used to add documentation content .

func (*TypedSpecBuilder[T]) Done 

func (b *TypedSpecBuilder[T]) Done(schema TypedSchema[T]) *TypedSpec[T]

Done builds the specification and registers the variable.

func (*TypedSpecBuilder[T]) MarkDeprecated 

func (b *TypedSpecBuilder[T]) MarkDeprecated()

MarkDeprecated marks the variable as deprecated.

func (*TypedSpecBuilder[T]) MarkRequired 

func (b *TypedSpecBuilder[T]) MarkRequired()

MarkRequired marks the variable as required.

func (*TypedSpecBuilder[T]) MarkSensitive 

func (b *TypedSpecBuilder[T]) MarkSensitive()

MarkSensitive marks the variable's content as sensitive.

func (*TypedSpecBuilder[T]) Name 

func (b *TypedSpecBuilder[T]) Name(name string)

Name sets the name of the environment variable.

func (*TypedSpecBuilder[T]) NonNormativeExample 

func (b *TypedSpecBuilder[T]) NonNormativeExample(v T, desc string)

NonNormativeExample adds a non-normative example to the variable.

A non-normative example is one that may not be meaningful in the context of the variable's use, but is included for illustrative purposes.

For example, a variable that represents a URL may have a non-normative example of "https://example.org/path", even if the actual use-case for the variable requires an "ftp" URL.

func (*TypedSpecBuilder[T]) NormativeExample 

func (b *TypedSpecBuilder[T]) NormativeExample(v T, desc string)

NormativeExample adds a normative example to the variable.

A normative example is one that is meaningful in the context of the variable's use.

func (*TypedSpecBuilder[T]) Peek 

func (b *TypedSpecBuilder[T]) Peek() Spec

Peek returns the (potentially invalid) spec that is being built.

func (*TypedSpecBuilder[T]) Precondition 

func (b *TypedSpecBuilder[T]) Precondition(fn func() bool)

Precondition adds a predicate that must be satisfied in order for the variable's value to be made available.

If any precondition fails the variable is treated as though it were undefined and without a default value.

func (*TypedSpecBuilder[T]) UserConstraint 

func (b *TypedSpecBuilder[T]) UserConstraint(
	desc string,
	fn func(T) bool,
)

UserConstraint adds a user-defined constraint to the variable's value.

type TypedString 

type TypedString[T ~string] struct {
	MinLen, MaxLen maybe.Value[int]
}

TypedString is a string value depicted by type T.

func (TypedString[T]) AcceptVisitor 

func (s TypedString[T]) AcceptVisitor(v SchemaVisitor)

AcceptVisitor passes s to the appropriate method of v.

func (TypedString[T]) Examples 

func (s TypedString[T]) Examples(conservative bool) []TypedExample[T]

Examples returns a (possibly empty) set of examples of valid values.

func (TypedString[T]) Finalize 

func (s TypedString[T]) Finalize() error

Finalize prepares the schema for use.

It returns an error if schema is invalid.

func (TypedString[T]) LengthDescription added in v1.3.0 

func (s TypedString[T]) LengthDescription() string

LengthDescription returns a human-readable description of the length that the limit applies to.

func (TypedString[T]) Marshal 

func (s TypedString[T]) Marshal(v T) (Literal, error)

Marshal converts a value to its literal representation.

func (TypedString[T]) MaxLength 

func (s TypedString[T]) MaxLength() (int, bool)

MaxLength returns the maximum permitted length of the native value.

func (TypedString[T]) MinLength 

func (s TypedString[T]) MinLength() (int, bool)

MinLength returns the minimum permitted length of the native value.

func (TypedString[T]) Type 

func (s TypedString[T]) Type() reflect.Type

Type returns the type of the native value.

func (TypedString[T]) Unmarshal 

func (s TypedString[T]) Unmarshal(v Literal) (T, error)

Unmarshal converts a literal value to it's native representation.

type Value 

type Value interface {
	// Verbatim returns the string representation of the variable as it appears
	// in the environment.
	Verbatim() Literal

	// Canonical returns the canonical string representation of the variable.
	Canonical() Literal
}

Value is the value of an environment variable.

type ValueError 

type ValueError interface {
	Error

	// Literal returns the invalid value.
	Literal() Literal

	// Unwrap returns the underlying cause of the value error.
	Unwrap() error

	// AcceptVisitor passes the error to the appropriate method of v.
	AcceptVisitor(v ValueErrorVisitor)
}

ValueError indicates that there is a problem with a variable's value.

type ValueErrorVisitor 

type ValueErrorVisitor interface {
	SchemaErrorVisitor

	VisitGenericError(error)
}

ValueErrorVisitor dispatches based on the the cause of a value error.

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.