starlarkhelper

package module
v0.2.8 Latest Latest
Warning

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

 Go to latest Published: May 27, 2022 License: MIT Imports: 9 Imported by: 0

README

starlark helper

数据类型

根据数据目标的不同，提供三种数据类型

  • Function 函数，实现了 Callable
  • Struct 结构体，实现了 HasAttrs
  • Module 模块，基于 starlarkstruct.Module 封装

用户也可以定义自己的类型，并实现 CanHelp 接口来提供更多帮助信息

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ELLIPSIS = symbolArg("...")
View Source 
var SLASH = symbolArg("/")
View Source 
var STAR = symbolArg("*")

Functions

func ArgGetInDef 

func ArgGetInDef(a Arg, mode HelpMode) string

func ArgGetOutDef 

func ArgGetOutDef(a Arg) string

func AsEvalError added in v0.1.1 

func AsEvalError(err error) *starlark.EvalError

func CallStack added in v0.1.1 

func CallStack(err error) starlark.CallStack

func CheckArgsContain deprecated 

func CheckArgsContain(kwargs []starlark.Tuple, key ...string) bool

Deprecated: CheckArgsContain

func Equal 

func Equal(one, another starlark.Value) bool

func EqualInt 

func EqualInt(one starlark.Value, another int64) bool

func GetExamplesDoc 

func GetExamplesDoc(examples []Example, mode HelpMode) string

func GetFromArgs deprecated 

func GetFromArgs(kwargs []starlark.Tuple, key string) starlark.Value

Deprecated: GetFromArgs 从传入的 keyword args 中提取出指定 key 对应的值 Kwargs 必须是函数所接收到的，否则会 panic 如果 key 不存在返回 nil

func GetFromArgsBool deprecated 

func GetFromArgsBool(kwargs []starlark.Tuple, key string, defaultValue bool) (bool, error)

Deprecated: GetFromArgsBool 从传入的 keyword args 中提取出指定 key 对应的值 Kwargs 必须是函数所接收到的，否则会 panic

func GetFromArgsInt64 deprecated 

func GetFromArgsInt64(kwargs []starlark.Tuple, key string, defaultValue int64) (int64, error)

Deprecated: GetFromArgsInt64 从传入的 keyword args 中提取出指定 key 对应的值 Kwargs 必须是函数所接收到的，否则会 panic

func GetHelpFor 

func GetHelpFor(v starlark.Value, mode HelpMode) string

func GetHelperHelpFor 

func GetHelperHelpFor(v CanHelp, mode HelpMode) string

func Hash added in v0.1.3 

func Hash(v string, fact uint32) uint32

func IsArgExist added in v0.1.5 

func IsArgExist(err error) bool

func IsArgNotExist added in v0.1.4 

func IsArgNotExist(err error) bool

func IsArgTypeMismatch added in v0.1.4 

func IsArgTypeMismatch(err error) bool

func NewListFromStrings added in v0.2.6 

func NewListFromStrings(elems []string) *starlark.List

func String 

func String(any fmt.Stringer) starlark.String

String convert anything to string

func ToStringDict added in v0.2.0 

func ToStringDict(globalMiddleware Middleware, elements ...map[string]interface{}) starlark.StringDict

ToStringDict convert elements to StringDict any element must be one of - *StarlarkModule - *Module - starlark.Value Panic: any other values will result in panic

func ToStringList added in v0.1.6 

func ToStringList(value starlark.Value) ([]string, error)

func TraverseList added in v0.2.5 

func TraverseList(value starlark.Value, f func(starlark.Value) error) error

func TraverseLists added in v0.2.5 

func TraverseLists(values []starlark.Value, f func(starlark.Value) error) error

Types

type Arg 

type Arg interface {
	Optional() Arg // 将 arg 标记为 optional
	Default(value interface{}) Arg
	Short(s string) Arg
	Long(s string) Arg

	InName() string         // 传入时的参数名
	InType() string         // 传入时展示的参数名
	InDefaultValue() string // 传入时的默认值（空代表无默认值）
	OutType() string        // 返回时展示的参数名（空代表无返回值）

	DocShort() string
	DocLong() string
	// contains filtered or unexported methods
}

func AnyArg 

func AnyArg(name string) Arg

func BoolArg added in v0.1.10 

func BoolArg(name string) Arg

func BytesArg added in v0.1.10 

func BytesArg(name string) Arg

func DictArg 

func DictArg(name string, keyType, valueType Arg) Arg

func FloatArg added in v0.1.10 

func FloatArg(name string) Arg

func FuncArg 

func FuncArg(name string, in Args, out Arg) Arg

func IntArg 

func IntArg(name string) Arg

func ListArg 

func ListArg(name string, innerType Arg) Arg

func NoneArg 

func NoneArg(name string) Arg

NoneArg 标识永远接收/返回 NoneType

func StringArg 

func StringArg(name string) Arg

func StructArg added in v0.1.9 

func StructArg(name string, desc *StructDescription) Arg

func TupleArg 

func TupleArg(name string, a ...Arg) Arg

func UnionArg 

func UnionArg(name string, a ...Arg) Arg

type Args 

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

func M 

func M(a ...Arg) Args

M 标识入参为多个

type Assertable 

type Assertable interface {
	Assert() (pass bool, failReason string)
}

Assertable 为数据提供 assert 的能力

type AssertableBool added in v0.2.2 

type AssertableBool struct {
	starlark.Bool

	Reason string
}

func NewFalseWithReason added in v0.2.2 

func NewFalseWithReason(reason string) AssertableBool

func (AssertableBool) Assert added in v0.2.2 

func (a AssertableBool) Assert() (pass bool, failReason string)

type BasicType 

type BasicType string
const (
	TypeNone   BasicType = "NoneType"
	TypeInt    BasicType = "int"
	TypeFloat  BasicType = "float"
	TypeBool   BasicType = "bool"
	TypeString BasicType = "str"
	TypeBytes  BasicType = "bytes"

	TypeAny BasicType = "any"
)

type BuiltinFunc 

type BuiltinFunc func(ctx context.Context, h *Helper) (starlark.Value, error)

func UnHelp 

func UnHelp(f StandardFunc) BuiltinFunc

UnHelp 将 BuiltinFunc 重新映射为标准 StandardFunc，用于兼容第三方库使用 需要注意的是，兼容方式要求将原 *starlark.Builtin 类型的 fn 改用 *Function 类型

type CanHelp 

type CanHelp interface {
	GetDefDoc(mode HelpMode) string     // 获取声明信息，应当包括名称、类型，不应包括任何用法解释
	GetSimpleDesc(mode HelpMode) string // 获取简单说明信息，应当在一行内完成，不应过长
	GetFullDesc(mode HelpMode) string   // 获取详细说明信息，不应重复包括 GetSimpleDesc 中的内容，用于说明具体的使用方式，换行应使用 LF
}

CanHelp 接口为自定义类型提供了输出帮助信息的能力 内部的 Function Struct Module 已经实现了 CanHelp

type CustomTypeArg 

type CustomTypeArg struct {
	Name string
	Type interface{ Type() string }
}

func (CustomTypeArg) Default 

func (c CustomTypeArg) Default(value interface{}) Arg

func (CustomTypeArg) DocLong 

func (c CustomTypeArg) DocLong() string

func (CustomTypeArg) DocShort 

func (c CustomTypeArg) DocShort() string

func (CustomTypeArg) InDefaultValue 

func (c CustomTypeArg) InDefaultValue() string

func (CustomTypeArg) InName 

func (c CustomTypeArg) InName() string

func (CustomTypeArg) InType 

func (c CustomTypeArg) InType() string

func (CustomTypeArg) Long 

func (c CustomTypeArg) Long(s string) Arg

func (CustomTypeArg) Optional 

func (c CustomTypeArg) Optional() Arg

func (CustomTypeArg) OutType 

func (c CustomTypeArg) OutType() string

func (CustomTypeArg) Short 

func (c CustomTypeArg) Short(s string) Arg

type DataTypeMember 

type DataTypeMember struct {
	Name     string    // 类型名称
	Short    string    // 简介
	Long     string    // 详细帮助信息
	Examples []Example // 示例
}

type DocObject 

type DocObject struct {
	CanHelp
}

func NewDocObject 

func NewDocObject(h CanHelp) DocObject

func (DocObject) Freeze 

func (d DocObject) Freeze()

func (DocObject) Hash 

func (d DocObject) Hash() (uint32, error)

func (DocObject) String 

func (d DocObject) String() string

func (DocObject) Truth 

func (d DocObject) Truth() starlark.Bool

func (DocObject) Type 

func (d DocObject) Type() string

type DocProvider 

type DocProvider interface {
	starlark.Value
	CanHelp
}

DocProvider 标志着一个 starlark 数据类型可以进行 help 执行

type ErrArgExist added in v0.1.5 

type ErrArgExist struct{ ArgName string }

func (ErrArgExist) Error added in v0.1.5 

func (e ErrArgExist) Error() string

type ErrArgNotExist added in v0.1.4 

type ErrArgNotExist struct{ ArgName string }

func (ErrArgNotExist) Error added in v0.1.4 

func (e ErrArgNotExist) Error() string

type ErrArgTypeMismatch added in v0.1.4 

type ErrArgTypeMismatch struct {
	ArgName    string
	ExpectType string
}

func (ErrArgTypeMismatch) Error added in v0.1.4 

func (e ErrArgTypeMismatch) Error() string

type Example 

type Example struct {
	Comment string
	Code    string
}

func (*Example) GetDoc 

func (e *Example) GetDoc(mode HelpMode) string

type Function 

type Function struct {
	Ctx context.Context

	FuncName string // 函数名称
	Short    string // 简介
	Long     string // 详细帮助信息

	Examples []Example // 示例

	Middleware Middleware
	Fn         BuiltinFunc
	ArgsIn     Args
	ArgOut     Arg
	// contains filtered or unexported fields
}

Function 函数类型

func HelpFunc 

func HelpFunc() *Function

HelpFunc 返回帮助查看函数

func NewBuiltinFunction 

func NewBuiltinFunction(name string, f BuiltinFunc) *Function

NewBuiltinFunction 快速创建一个无文档的 Function 示例

func (*Function) ArgsInSplit 

func (f *Function) ArgsInSplit() []Arg

func (*Function) CallInternal 

func (f *Function) CallInternal(thread *starlark.Thread, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

func (Function) Copy added in v0.2.3 

func (f Function) Copy() *Function

func (*Function) Freeze 

func (f *Function) Freeze()

func (*Function) GetArgOutDef 

func (f *Function) GetArgOutDef() string

GetArgOutDef 获取函数出参文档 返回空或 ` -> TYPE`

func (*Function) GetArgsInDef 

func (f *Function) GetArgsInDef() string

GetArgsInDef 获取函数入参文档

func (*Function) GetDefDoc 

func (f *Function) GetDefDoc(mode HelpMode) string

func (*Function) GetFullDesc 

func (f *Function) GetFullDesc(mode HelpMode) string

func (*Function) GetSimpleDesc 

func (f *Function) GetSimpleDesc(mode HelpMode) string

func (*Function) Hash 

func (f *Function) Hash() (uint32, error)

func (*Function) Name 

func (f *Function) Name() string

Name 为增加了 module 名称的 name

func (*Function) Receiver 

func (f *Function) Receiver() starlark.Value

func (*Function) String 

func (f *Function) String() string

func (*Function) Truth 

func (f *Function) Truth() starlark.Bool

func (*Function) Type 

func (f *Function) Type() string

type HelpMode 

type HelpMode uint8
const (
	HelpModePure     HelpMode = iota // 无格式信息
	HelpModeTerminal                 // 以 terminal 转义 markdown 格式信息
	HelpModeHTML                     // 以 html 转义 markdown 格式信息
)

type Helper 

type Helper struct {
	Name           string
	Thread         *starlark.Thread
	Fn             *Function
	PositionalArgs []starlark.Value
	Kwargs         []starlark.Tuple // original Kwargs
	KeywordArgs    starlark.StringDict

	Err error

	Args starlark.Tuple // Deprecated: please use PositionalArgs
}

func (*Helper) ArgsCount 

func (h *Helper) ArgsCount() int

ArgsCount 返回传入的 args 数量

func (*Helper) CheckContainKeywordArg added in v0.1.5 

func (h *Helper) CheckContainKeywordArg(keys ...string) error

CheckContainKeywordArg will return error if there is any keyword arguments passed in not exist. If there are other keyword arguments, won't error. If you want to check that, maybe you want to use CheckOnlyContainKeywordArg.

func (*Helper) CheckExactArgs 

func (h *Helper) CheckExactArgs(count int) error

CheckExactArgs 检查是否传递了指定数量的参数，如果否则返回 error

func (*Helper) CheckMinArgs 

func (h *Helper) CheckMinArgs(count int) error

CheckMinArgs 检查是否传递了至少指定数量的参数，如果否则返回 error

func (*Helper) CheckOnlyContainKeywordArg added in v0.1.5 

func (h *Helper) CheckOnlyContainKeywordArg(keys ...string) error

CheckOnlyContainKeywordArg will return error if there is any keyword arguments except for passed in keys. If any of keys not exist, won't error. If you want to check that, maybe you want to use CheckContainKeywordArg

func (*Helper) ContainKeywordArg added in v0.1.4 

func (h *Helper) ContainKeywordArg(key string) bool

func (*Helper) GetAllPositionalArgs added in v0.1.4 

func (h *Helper) GetAllPositionalArgs() []starlark.Value

func (*Helper) GetFirstArg 

func (h *Helper) GetFirstArg() (starlark.Value, error)

GetFirstArg 获得第一个参数

func (*Helper) GetKeywordArgs 

func (h *Helper) GetKeywordArgs(key string) starlark.Value

GetKeywordArgs 从 keyword args 中提取出指定 key 对应的值，如果值不存在返回 nil

func (*Helper) GetKeywordArgsBool 

func (h *Helper) GetKeywordArgsBool(key string) (bool, error)

GetKeywordArgsBool 从 keyword args 中提取出指定 key 对应的值并转换为 int64 类型

func (*Helper) GetKeywordArgsBoolWithDefault added in v0.1.4 

func (h *Helper) GetKeywordArgsBoolWithDefault(key string, defaultValue bool) (bool, error)

GetKeywordArgsBoolWithDefault like GetKeywordArgsBool but accept a defaultValue arg

func (*Helper) GetKeywordArgsInt64 added in v0.1.4 

func (h *Helper) GetKeywordArgsInt64(key string) (int64, error)

GetKeywordArgsInt64 从 keyword args 中提取出指定 key 对应的值并转换为 int64 类型

func (*Helper) GetKeywordArgsInt64WithDefault added in v0.1.4 

func (h *Helper) GetKeywordArgsInt64WithDefault(key string, defaultValue int64) (int64, error)

GetKeywordArgsInt64WithDefault like GetKeywordArgsInt64 but accept a defaultValue arg

func (*Helper) GetKeywordArgsString added in v0.1.4 

func (h *Helper) GetKeywordArgsString(key string) (string, error)

GetKeywordArgsString 从 keyword args 中提取出指定 key 对应的值并转换为 string 类型

func (*Helper) GetKeywordArgsStringList added in v0.1.6 

func (h *Helper) GetKeywordArgsStringList(key string) ([]string, error)

GetKeywordArgsStringList 从 keyword args 中提取出指定 key 对应的值并转换为 []string 类型 If type of key is a single string, it's also valid and will return a single element string slice

func (*Helper) GetKeywordArgsStringListWithDefault added in v0.1.6 

func (h *Helper) GetKeywordArgsStringListWithDefault(key string, defaultValue []string) ([]string, error)

GetKeywordArgsStringListWithDefault like GetKeywordArgsStringList but accept a defaultValue arg

func (*Helper) GetKeywordArgsStringWithDefault added in v0.1.4 

func (h *Helper) GetKeywordArgsStringWithDefault(key string, defaultValue string) (string, error)

GetKeywordArgsStringWithDefault like GetKeywordArgsString but accept a defaultValue arg

func (*Helper) GetKeywordArgsUint64 added in v0.1.4 

func (h *Helper) GetKeywordArgsUint64(key string) (uint64, error)

GetKeywordArgsUint64 从 keyword args 中提取出指定 key 对应的值并转换为 uint64 类型

func (*Helper) GetKeywordArgsUint64WithDefault added in v0.1.4 

func (h *Helper) GetKeywordArgsUint64WithDefault(key string, defaultValue uint64) (uint64, error)

GetKeywordArgsUint64WithDefault like GetKeywordArgsUint64 but accept a defaultValue arg

func (*Helper) Print 

func (h *Helper) Print(msg string)

func (*Helper) UnpackArgs 

func (h *Helper) UnpackArgs(pairs ...interface{}) *Helper

func (*Helper) UnpackArgsIgnoreKeyword 

func (h *Helper) UnpackArgsIgnoreKeyword(pairs ...interface{}) *Helper

UnpackArgsIgnoreKeyword 类似于 UnpackArgs，但是忽略命名参数

func (*Helper) UnpackBasicArgs deprecated 

func (h *Helper) UnpackBasicArgs(pairs ...interface{}) *Helper

Deprecated: UnpackBasicArgs please use UnpackArgs directly

func (*Helper) UnpackPositionalArgs 

func (h *Helper) UnpackPositionalArgs(min int, vars ...interface{}) *Helper

type Middleware added in v0.2.0 

type Middleware func(ctx context.Context, h *Helper, do BuiltinFunc) (starlark.Value, error)

func ChainMiddleware added in v0.2.0 

func ChainMiddleware(middlewares ...Middleware) Middleware

type Module 

type Module struct {
	Name string

	Short string // module 功能简介

	SubModules  []*Module
	PreDeclares []*PreDeclaredValue
	Functions   []*Function
	Structs     []*StructDescription

	FuncMiddleware Middleware
}

func (Module) Copy added in v0.2.3 

func (m Module) Copy() *Module

func (Module) Get 

func (m Module) Get() *StarlarkModule

Get 获取 StarlarkModule

type PreDeclaredValue 

type PreDeclaredValue struct {
	Name     string
	Short    string    // 简介
	Long     string    // 详细帮助信息
	Examples []Example // 示例

	Value starlark.Value
}

PreDeclaredValue 为预声明的变量/常量值

func (*PreDeclaredValue) GetDefDoc 

func (m *PreDeclaredValue) GetDefDoc(mode HelpMode) string

func (*PreDeclaredValue) GetFullDesc 

func (m *PreDeclaredValue) GetFullDesc(mode HelpMode) string

func (*PreDeclaredValue) GetSimpleDesc 

func (m *PreDeclaredValue) GetSimpleDesc(mode HelpMode) string

type RawDefaultString 

type RawDefaultString string

type StandardFunc 

type StandardFunc func(thread *starlark.Thread, fn *Function, args starlark.Tuple, kwargs []starlark.Tuple) (v starlark.Value, err error)

type StarlarkModule 

type StarlarkModule struct {
	starlarkstruct.Module
	// contains filtered or unexported fields
}

func (*StarlarkModule) GetDefDoc 

func (m *StarlarkModule) GetDefDoc(mode HelpMode) string

func (*StarlarkModule) GetFullDesc 

func (m *StarlarkModule) GetFullDesc(mode HelpMode) string

func (*StarlarkModule) GetSimpleDesc 

func (m *StarlarkModule) GetSimpleDesc(mode HelpMode) string

type Struct 

type Struct struct {
	Descriptor *StructDescription
	Values     starlark.StringDict
}

func (*Struct) Assert 

func (s *Struct) Assert() (bool, string)

func (*Struct) Attr 

func (s *Struct) Attr(name string) (starlark.Value, error)

func (*Struct) AttrNames 

func (s *Struct) AttrNames() []string

func (*Struct) Description 

func (s *Struct) Description() string

func (*Struct) FieldEqual 

func (s *Struct) FieldEqual(name string, value starlark.Value) bool

func (*Struct) Freeze 

func (s *Struct) Freeze()

func (*Struct) Get 

func (s *Struct) Get(key starlark.Value) (v starlark.Value, found bool, err error)

func (*Struct) GetDefDoc 

func (s *Struct) GetDefDoc(mode HelpMode) string

func (*Struct) GetFullDesc 

func (s *Struct) GetFullDesc(mode HelpMode) string

func (*Struct) GetSimpleDesc 

func (s *Struct) GetSimpleDesc(mode HelpMode) string

func (*Struct) Hash 

func (s *Struct) Hash() (uint32, error)

func (*Struct) Items 

func (s *Struct) Items() []starlark.Tuple

func (*Struct) Iterate 

func (s *Struct) Iterate() starlark.Iterator

func (*Struct) String 

func (s *Struct) String() string

func (*Struct) ToDict 

func (s *Struct) ToDict() *starlark.Dict

func (*Struct) Truth 

func (s *Struct) Truth() starlark.Bool

func (*Struct) Type 

func (s *Struct) Type() string

type StructDescription 

type StructDescription struct {
	Name string // struct 名称

	Short      string
	Long       string
	AssertNote string
	Examples   []Example

	Fields map[string]Arg

	Editable                  bool // TODO 是否允许 field 被修改，需要注意的是如果允许那么需要特别处理 assert
	ReturnNoneForUnExistField bool // 对于不存在的 field 返回 None 而不是错误

	StringProvider func(s *Struct) string
	TruthProvider  func(s *Struct) starlark.Bool
	HashProvider   func(s *Struct) (uint32, error)
	AssertProvider func(s *Struct) (pass bool, failReason string)
	GetProvider    func(s *Struct, key starlark.Value) (v starlark.Value, found bool, err error)
	// contains filtered or unexported fields
}

StructDescription 为一个 struct 的描述信息

func NewStruct 

func NewStruct(name string, args ...Arg) *StructDescription

func (*StructDescription) ConstructAll 

func (d *StructDescription) ConstructAll(dict starlark.StringDict) (*Struct, error)

ConstructAll 传递的 dict 必须与期望的 Fields 相对应 TODO: 类型检测尚未实现

func (*StructDescription) GetDefDoc 

func (d *StructDescription) GetDefDoc(mode HelpMode) string

func (*StructDescription) GetFullDesc 

func (d *StructDescription) GetFullDesc(mode HelpMode) string

func (*StructDescription) GetSimpleDesc 

func (d *StructDescription) GetSimpleDesc(mode HelpMode) string

func (*StructDescription) MustConstructAll 

func (d *StructDescription) MustConstructAll(dict starlark.StringDict) *Struct

MustConstructAll ConstructAll but will panic if error

func (*StructDescription) ProvideDoc 

func (d *StructDescription) ProvideDoc() DocProvider

func (*StructDescription) UnsafeConstruct 

func (d *StructDescription) UnsafeConstruct(dict starlark.StringDict) *Struct

UnsafeConstruct 不做任何检查，创建相应的 struct

func (*StructDescription) WithAssertProvider 

func (d *StructDescription) WithAssertProvider(f func(s *Struct) (pass bool, failReason string)) *StructDescription

type UnpackArgsFunc 

type UnpackArgsFunc func(pairs ...interface{}) 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.