api

Documentation

Index

• Constants
• type Module
• type ModuleManager
• type Pipe
• type PipeBuildError
  • func (pe PipeBuildError) Error() string
• type PipeBuilder
• type Pipeline
• type Preprocessor
• type State
• type Worker

Constants

const (
	// VERSION of current PUG api
	//
	// Main contributors(alphabetical order):
	// - KAASsS (API Design)
	// - Seraph Jack (API Design)
	// - Yesterday17 (API Design & Develop)
	VERSION = "1.0.11"
)

Types

type Module

type Module interface {
	// Name should be the UNIQUE name of a module
	// It is used to identify different modules
	// It MUST NOT contain ':' or '/' character
	Name() string

	// Description is used to describe what the whole module does
	Description() string

	// Author shows the author(s) of a module
	Author() []string

	// Usage tells users the basic usage of the whole module
	// And usage of all pipes in the module
	Usage() string

	// Preprocessor is used to preprocess input data and generate initial state
	Preprocessor() Preprocessor

	// Pipe is used to get PipeConstructors by Pipe Id.
	// Pipe Id only need to be unique in module, and should not contain strange characters.
	// If the constructor is not found, it returns nil PipeConstructor and false
	Pipe(pid string) (PipeBuilder, bool)

	// Pipes is used to get name of all available pipes
	Pipes() []string
}

type ModuleManager

type ModuleManager interface {
	// Exist validates whether a module named mid exists
	Exist(mid string) bool

	// ExistPipe validates whether a module named mid contains pipe named pid
	// It both checks mid and pid
	ExistPipe(mid, pid string) bool

	// Add a module to the manager
	// Then the module can be queried by the manager
	// If the name of this pipe is used, it will return an error
	Add(m Module) error

	// Module gets module named mid
	// If the module does not exist, it returns nil
	Module(mid string) Module

	// Modules get all mid of modules
	Modules() []string

	// Pipe gets constructor of pipe named pid in module named mid
	// If the module or pipe does not exist, it returns nil
	Pipe(mid, pid string) PipeBuilder

	// Preprocessors among all the modules loaded
	Preprocessors() []Preprocessor
}

type Pipe

type Pipe interface {
	// Validate returns a map with string key and reflect.Kind Type
	// If a string begins with '+', it would be ADDED to work state
	// If a string begins with '-', it would be REMOVED from work state
	// If a string begins with '!', it is needed by this pipe
	// If a string begins with '?', it is optional to this pipe
	//
	// If a string begins with '+', then it **should** NOT exist in the previous state
	// THE 'SHOULD' MIGHT BE CHANGED TO MUST IN FURTHER VERSION
	//
	// If a string begins with '-' or '!', it MUST exist in the previous state
	//
	// If the function returns nil, it means type validation SHOULD be skipped
	Validate() map[string]reflect.Kind

	// Execute a pipe
	// Only pipes pass the validation can be executed
	// After execution, the State would be changed as Validate describes
	Execute(work State) error

	// Clone a pipe
	Clone() Pipe
}

Pipe is the minimal reuse unit in the project. Keep it simple, stupid

type PipeBuildError

type PipeBuildError int

const (
	PipeNoError PipeBuildError = iota
	PipeArgumentMissing
	PipeArgumentTypeMismatch
	PipeArgumentInvalid
)

func (PipeBuildError) Error

func (pe PipeBuildError) Error() string

type PipeBuilder

type PipeBuilder interface {
	// Build works as the original PipeConstructor
	// It is a function used to build up a new Pipe.
	// It returns a Pipe if arguments given are sufficient
	// Or it should returns nil Pipe and an error
	Build(map[string]interface{}) (Pipe, PipeBuildError)

	// Accept can be used to determine whether an argument is necessary
	Accept(key string, t reflect.Kind) bool

	// Must returns a MUST map of arguments
	Must() map[string]reflect.Kind

	// Optional returns an OPTIONAL map of arguments
	Optional() map[string]reflect.Kind
}

PipeBuilder is designed to replace the old PipeConstructor It can be used to build pipe with given arguments Or determine what arguments are necessary

type Pipeline

type Pipeline interface {
	// Pipeline is also a pipe, which means you can assemble pipeline with pipe
	// However, we don't recommend doing so, as it may make the configuration more complex
	Pipe

	// Append can add Pipe to the end of a pipeline
	Append(p ...Pipe)
}

Pipeline is a line of pipes linked together It's a medium reuse unit, which often finishes a whole task Keep it simple, stupid too

type Preprocessor

type Preprocessor interface {
	// Match determines whether current input meets rule now
	// If true is returned, the Worker will select it as Preprocessor, ignoring other choices
	Match(input string) bool

	// Execute tries to build up the initial state of a work
	// It accepts env as environmental variables and a string as input
	Execute(env map[string]interface{}, input string) (State, error)
}

Preprocessor is executed before worker works It modifies user input, and create the initial State of a work If it meets an error, the worker will not work

type State

type State interface {
	Has(key string) bool

	Get(key string) (interface{}, error)
	GetInt(key string) (int, error)
	GetBool(key string) (bool, error)
	GetString(key string) (string, error)
	GetFloat(key string) (float32, error)

	Set(key string, value interface{})
	Delete(key string)

	Range(func(key string, value interface{}) bool)
}

State is interface of a simple State Manager

type Worker

type Worker interface {
	// Start accepts a string as input
	// It returns an error if no preprocessor is selected
	Start(input string) error

	// Pause pauses a work at current pipeline
	// Work before current pipe is kept
	Pause() error

	// Cancel destroys the current work and empties the worker
	Cancel() error

	// Clone creates a new worker with the same workflow as the copied one
	Clone() Worker

	// Clean empties a worker to make it available for other works
	Clean()
}

Worker holds state itself, so it doesn't return anything other than error