dslengine

Documentation

Index

• func Execute(dsl func(), def Definition) bool
• func FailOnError(err error)
• func IncompatibleDSL()
• func InvalidArgError(expected string, actual interface{})
• func IsTopLevelDefinition() bool
• func PrintFilesOrFail(files []string, err error)
• func Register(r Root)
• func ReportError(fm string, vals ...interface{})
• func Reset()
• func Run() error
• type Definition
  • func CurrentDefinition() Definition
• type DefinitionSet
• type Error
  • func (de *Error) Error() string
• type Finalize
• type MetadataDefinition
• type MultiError
  • func (m MultiError) Error() string
• type Root
  • func SortRoots() ([]Root, error)
• type SetIterator
• type Source
• type TopLevelDefinition
  • func (t *TopLevelDefinition) Context() string
• type TraitDefinition
  • func (t *TraitDefinition) Context() string
  • func (t *TraitDefinition) DSL() func()
• type Validate
• type ValidationDefinition
  • func (v *ValidationDefinition) AddRequired(required []string)
  • func (v *ValidationDefinition) Context() string
  • func (v *ValidationDefinition) Dup() *ValidationDefinition
  • func (v *ValidationDefinition) HasRequiredOnly() bool
  • func (v *ValidationDefinition) Merge(other *ValidationDefinition)
• type ValidationErrors
  • func (verr *ValidationErrors) Add(def Definition, format string, vals ...interface{})
  • func (verr *ValidationErrors) AddError(def Definition, err error)
  • func (verr *ValidationErrors) AsError() *ValidationErrors
  • func (verr *ValidationErrors) Error() string
  • func (verr *ValidationErrors) Merge(err *ValidationErrors)

Functions

func Execute

func Execute(dsl func(), def Definition) bool

Execute runs the given DSL to initialize the given definition. It returns true on success. It returns false and appends to Errors on failure. Note that `Run` takes care of calling `Execute` on all definitions that implement Source. This function is intended for use by definitions that run the DSL at declaration time rather than store the DSL for execution by the dsl engine (usually simple independent definitions). The DSL should use ReportError to record DSL execution errors.

func FailOnError

func FailOnError(err error)

FailOnError will exit with code 1 if `err != nil`. This function will handle properly the MultiError this dslengine provides.

func IncompatibleDSL

func IncompatibleDSL()

IncompatibleDSL should be called by DSL functions when they are invoked in an incorrect context (e.g. "Params" in "Resource").

func InvalidArgError

func InvalidArgError(expected string, actual interface{})

InvalidArgError records an invalid argument error. It is used by DSL functions that take dynamic arguments.

func IsTopLevelDefinition

func IsTopLevelDefinition() bool

IsTopLevelDefinition returns true if the currently evaluated DSL is a root DSL (i.e. is not being run in the context of another definition).

func PrintFilesOrFail

func PrintFilesOrFail(files []string, err error)

PrintFilesOrFail will print the file list. Use it with a generator's `Generate()` function to output the generated list of files or quit on error.

func Register

func Register(r Root)

Register adds a DSL Root to be executed by Run.

func ReportError

func ReportError(fm string, vals ...interface{})

ReportError records a DSL error for reporting post DSL execution.

func Reset

func Reset()

Reset uses the registered RootFuncs to re-initialize the DSL roots. This is useful to tests.

func Run

func Run() error

Run runs the given root definitions. It iterates over the definition sets multiple times to first execute the DSL, the validate the resulting definitions and finally finalize them. The executed DSL may register new roots to have them be executed (last) in the same run.

Types

type Definition

type Definition interface {
	// Context is used to build error messages that refer to the definition.
	Context() string
}

Definition is the common interface implemented by all definitions.

func CurrentDefinition

func CurrentDefinition() Definition

CurrentDefinition returns the definition whose initialization DSL is currently being executed.

type DefinitionSet

type DefinitionSet []Definition

DefinitionSet contains DSL definitions that are executed as one unit. The slice elements may implement the Validate an, Source interfaces to enable the corresponding behaviors during DSL execution.

type Error

type Error struct {
	GoError error
	File    string
	Line    int
}

Error represents an error that occurred while running the API DSL. It contains the name of the file and line number of where the error occurred as well as the original Go error.

func (*Error) Error

func (de *Error) Error() string

Error returns the underlying error message.

type Finalize

type Finalize interface {
	Definition
	// Finalize is run by the DSL runner once the definition DSL has executed and the
	// definition has been validated.
	Finalize()
}

Finalize is the interface implemented by definitions that require an additional pass after the DSL has executed (e.g. to merge generated definitions or initialize default values)

type MetadataDefinition

type MetadataDefinition map[string][]string

MetadataDefinition is a set of key/value pairs

type MultiError

type MultiError []*Error

MultiError collects all DSL errors. It implements error.

var (
	// Errors contains the DSL execution errors if any.
	Errors MultiError
)

func (MultiError) Error

func (m MultiError) Error() string

Error returns the error message.

type Root

type Root interface {
	// DSLName is displayed by the runner upon executing the DSL.
	// Registered DSL roots must have unique names.
	DSLName() string
	// DependsOn returns the list of other DSL roots this root depends on.
	// The DSL engine uses this function to order execution of the DSLs.
	DependsOn() []Root
	// IterateSets implements the visitor pattern: is is called by the engine so the
	// DSL can control the order of execution. IterateSets calls back the engine via
	// the given iterator as many times as needed providing the DSL definitions that
	// must be run for each callback.
	IterateSets(SetIterator)
	// Reset restores the root to pre DSL execution state.
	// This is mainly used by tests.
	Reset()
}

Root is the interface implemented by the DSL root objects. These objects contains all the definition sets created by the DSL and can be passed to the dsl engine for execution.

func SortRoots

func SortRoots() ([]Root, error)

SortRoots orders the DSL roots making sure dependencies are last. It returns an error if there is a dependency cycle.

type SetIterator

type SetIterator func(s DefinitionSet) error

SetIterator is the function signature used to iterate over definition sets with IterateSets.

type Source

type Source interface {
	Definition
	// DSL returns the DSL used to initialize the definition if any.
	DSL() func()
}

Source is the interface implemented by definitions that can be initialized via DSL.

type TopLevelDefinition

type TopLevelDefinition struct{}

TopLevelDefinition represents the top-level file definitions, done with `var _ = `. An instance of this object is returned by `CurrentDefinition()` when at the top-level.

func (*TopLevelDefinition) Context

func (t *TopLevelDefinition) Context() string

Context tells the DSL engine which context we're in when showing errors.

type TraitDefinition

type TraitDefinition struct {
	// Trait name
	Name string
	// Trait DSL
	DSLFunc func()
}

TraitDefinition defines a set of reusable properties.

func (*TraitDefinition) Context

func (t *TraitDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*TraitDefinition) DSL

func (t *TraitDefinition) DSL() func()

DSL returns the initialization DSL.

type Validate

type Validate interface {
	Definition
	// Validate returns nil if the definition contains no validation error.
	// The Validate implementation may take advantage of ValidationErrors to report
	// more than one errors at a time.
	Validate() error
}

Validate is the interface implemented by definitions that can be validated. Validation is done by the DSL dsl post execution.

type ValidationDefinition

type ValidationDefinition struct {
	// Values represents an enum validation as described at
	// http://json-schema.org/latest/json-schema-validation.html#anchor76.
	Values []interface{}
	// Format represents a format validation as described at
	// http://json-schema.org/latest/json-schema-validation.html#anchor104.
	Format string
	// PatternValidationDefinition represents a pattern validation as described at
	// http://json-schema.org/latest/json-schema-validation.html#anchor33
	Pattern string
	// Minimum represents an minimum value validation as described at
	// http://json-schema.org/latest/json-schema-validation.html#anchor21.
	Minimum *float64
	// Maximum represents a maximum value validation as described at
	// http://json-schema.org/latest/json-schema-validation.html#anchor17.
	Maximum *float64
	// MinLength represents an minimum length validation as described at
	// http://json-schema.org/latest/json-schema-validation.html#anchor29.
	MinLength *int
	// MaxLength represents an maximum length validation as described at
	// http://json-schema.org/latest/json-schema-validation.html#anchor26.
	MaxLength *int
	// Required list the required fields of object attributes as described at
	// http://json-schema.org/latest/json-schema-validation.html#anchor61.
	Required []string
}

ValidationDefinition contains validation rules for an attribute.

func (*ValidationDefinition) AddRequired

func (v *ValidationDefinition) AddRequired(required []string)

AddRequired merges the required fields from other into v

func (*ValidationDefinition) Context

func (v *ValidationDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*ValidationDefinition) Dup

func (v *ValidationDefinition) Dup() *ValidationDefinition

Dup makes a shallow dup of the validation.

func (*ValidationDefinition) HasRequiredOnly

func (v *ValidationDefinition) HasRequiredOnly() bool

HasRequiredOnly returns true if the validation only has the Required field with a non-zero value.

func (*ValidationDefinition) Merge

func (v *ValidationDefinition) Merge(other *ValidationDefinition)

Merge merges other into v.

type ValidationErrors

type ValidationErrors struct {
	Errors      []error
	Definitions []Definition
}

ValidationErrors records the errors encountered when running Validate.

func (*ValidationErrors) Add

func (verr *ValidationErrors) Add(def Definition, format string, vals ...interface{})

Add adds a validation error to the target.

func (*ValidationErrors) AddError

func (verr *ValidationErrors) AddError(def Definition, err error)

AddError adds a validation error to the target. AddError "flattens" validation errors so that the recorded errors are never ValidationErrors themselves.

func (*ValidationErrors) AsError

func (verr *ValidationErrors) AsError() *ValidationErrors

AsError returns an error if there are validation errors, nil otherwise.

func (*ValidationErrors) Error

func (verr *ValidationErrors) Error() string

Error implements the error interface.

func (*ValidationErrors) Merge

func (verr *ValidationErrors) Merge(err *ValidationErrors)

Merge merges validation errors into the target.