schema

package
v0.0.0-...-19193a1 Latest Latest
Warning

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

 Go to latest Published: Oct 7, 2022 License: MIT Imports: 6 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	InitializerArgumentAsSingleArg = iota
	InitializerArgumentAsSlice
)

Variables

View Source 
var ByteSliceType = Type(byteslice.Buffer{}).
	ApparentType(`[]byte`).
	AcceptValue(true).
	GetValueMethodName(`Bytes`).
	ZeroVal(`[]byte(nil)`)

ByteSliceType represents a `[]byte` type. Since `sketch` mostly works with JSON, it needs to handle `[]byte` fields being encoded/decoded with base64 encoding transparently. Therefore unless the default behavior for `encoding/json` already work for you, you may need tweaking. The `ByteSliceType` uses `byteslice.Type` internally, which allows the user to specify the base64 encoding.

View Source 
var NativeByteSliceType = Type([]byte(nil)).
	ApparentType(`[]byte`).
	PointerType(`[]byte`).
	RawType(`[]byte`)

Functions

This section is empty.

Types

type Base 

type Base struct {
	// Variables is a storage for various global and default variables
	// used during code generation. While it is a public field, end-users
	// should not be using this variable for any purposes. It is only
	// visible because the sketch utility must be able to assign certain
	// parameters during the generation phase, and therefore the
	// field must be exported.
	//
	// tl;dr: DON'T USE IT (unless you are hacking sketch internals)
	Variables map[string]interface{}
}

Base is the struct that defines all of your schemas. You must include this as an embedded field in your schema object directly: 

package mypkg
type Object struct {
  schema.Base
}

Because sketch reads your schema definitions via Go's package inclusion mechanism, your schema object name must be an exported name (e.g. "MyObject" instead of "myObject")

func (Base) BoolVar 

func (b Base) BoolVar(name string) bool

BoolVar returns the value stored in the Variables field as a bool. If the value does not exist or the value is not of a bool type, then returns false

func (Base) BuilderName 

func (b Base) BuilderName() string

BuilderName returns the name of the Builder object. By default a name comprising of the return value from schema's `Name()` method and `Builder` will be used (e.g. "FooBuilder").

If you are using an unexported name for your schema, you probably want to provide your own `BuilderName()` and `BuilderResultType()` methods, which control the struct name of the builder, and the returning value from calling `Build()` on the builder, respectively

func (Base) BuilderResultType 

func (b Base) BuilderResultType() string

BuilderResultType returns the name of the type that the builder object returns upon calling `Build()`.

If you are using an unexported name for your schema, you probably want to provide your own `BuilderName()` and `BuilderResultType()` methods, which control the struct name of the builder, and the returning value from calling `Build()` on the builder, respectively

func (Base) Comment 

func (Base) Comment() string

Comment returns the comment that should go withh the generated object. The comment should NOT contain the object name, as it would be taken from the return value of `Name` method

func (Base) Fields 

func (Base) Fields() []*FieldSpec

Fields returns the list of fields that should be associated with the schema object. User usually must

func (Base) FilenameBase 

func (b Base) FilenameBase() string

FilenameBase is used to generate the filename when generating files. Normally the name snake-cased version of the schema object (NOT the return value of `Name` method call) is used, but when you provide a value for thie method, the value is used verbatim

func (Base) GenerateSymbol 

func (b Base) GenerateSymbol(s string) bool

GenerateSymbol should return true if the given method is allowed to be generated. The argument consists of a prefix (e.g. "object." or "builder.") followed by the actual method name.

By default all methods are allowed. Users may configure this on a per-object basis by providing their own `GenerateSymbol` method.

func (Base) GetKeyName 

func (b Base) GetKeyName(fieldName string) string

func (Base) Imports 

func (Base) Imports() []string

Imports returns the list of packges to be imported.

func (Base) KeyNamePrefix 

func (b Base) KeyNamePrefix() string

KeyNamePrefix returns the prefix that should be added to key name constants. By default no prefix is added, but if you have multiple objects with same field names, you will have to provide them with a prefix.

When --with-key-name-prefix is specified, the default value is set to the name of the object, forcing sketch to generate key name constants in the form of `ObjectName` + `FieldName` + `Key`. You only need to provide your custom `KeyNamePrefix` method when you want to override this default behavior

func (Base) Name 

func (b Base) Name() string

Name returns the name of the object to be generated. By default this value is set to the name of the schema object you created. Users may configure a different name by providing their own `Name` method.

For example, since all schema objects must be exported, you would have to provide a custom `Name` method to tell sketch to generate an unexported object (e.g. `type Object { schema.Base }; func (Object) Name() string { return "object" }`)

func (Base) Package 

func (b Base) Package() string

Package returns the name of the package that a schema belongs to. By default this value is set to the last element of the destination directory. For example, if you are generating files under `/home/lestrrat/foo`, the package name shall be `foo` by default.

Users may configure a different name by providing their own `Package` method -- however,

func (Base) StringVar 

func (b Base) StringVar(name string) string

StringVar returns the value stored in the Variables field as a string. If the value does not exist or the value is not of a string type, then returns the empty string

func (Base) SymbolName 

func (b Base) SymbolName(s string) string

SymbolName takes an internal name like "object.method.Foo" and returns the actual symbol name

type FieldSpec 

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

FieldSpec represents a field that belongs to a particular schema.

func Bool 

func Bool(name string) *FieldSpec

Bool creates a new field with the given name and a bool type

func ByteSlice 

func ByteSlice(name string) *FieldSpec

ByteSlice creates a new field with the given name and a []byte type

func Field 

func Field(name string, typ interface{}) *FieldSpec

func Int 

func Int(name string) *FieldSpec

Int creates a new field with the given name and a int type

func String 

func String(name string) *FieldSpec

String creates a new field with the given name and a string type

func (*FieldSpec) Comment 

func (f *FieldSpec) Comment(s string) *FieldSpec

func (*FieldSpec) ConstantValue 

func (f *FieldSpec) ConstantValue(s string) *FieldSpec

ConstantValue sets the string value that should be used when fetching this field. When ConstantValue is specified, calling `Set` on this field would be a no-op (no error is returned)

func (*FieldSpec) Extra 

func (f *FieldSpec) Extra(name string, value interface{}) *FieldSpec

func (*FieldSpec) GetComment 

func (f *FieldSpec) GetComment() string

func (*FieldSpec) GetConstantValue 

func (f *FieldSpec) GetConstantValue() string

func (*FieldSpec) GetExtra 

func (f *FieldSpec) GetExtra(name string) interface{}

func (*FieldSpec) GetIsConstant 

func (f *FieldSpec) GetIsConstant() bool

func (*FieldSpec) GetIsExtension 

func (f *FieldSpec) GetIsExtension() bool

GetIsExtension returns true if this field is an extension, and not part of the object per se. You will need to declare methods to get/set and/or otherwise work this variable by yourself

func (*FieldSpec) GetJSON 

func (f *FieldSpec) GetJSON() string

func (*FieldSpec) GetKeyName 

func (f *FieldSpec) GetKeyName(object Interface) string

func (*FieldSpec) GetName 

func (f *FieldSpec) GetName() string

func (*FieldSpec) GetRequired 

func (f *FieldSpec) GetRequired() bool

func (*FieldSpec) GetType 

func (f *FieldSpec) GetType() *TypeSpec

func (*FieldSpec) GetUnexportedName 

func (f *FieldSpec) GetUnexportedName() string

func (*FieldSpec) IsExtension 

func (f *FieldSpec) IsExtension(b bool) *FieldSpec

SExtension declares the field as an extension, and not part of the object as defined by the JSON representation. That is to say, this field exist in the Go struct, but not in the JSON structures that it serizlizes to or deserializes from.

Fields defined as extensions are expected to be _internal_ to the object. They are not exposed by either Get/Set, and do not get any sort of accessors.

func (*FieldSpec) JSON 

func (f *FieldSpec) JSON(s string) *FieldSpec

JSON specifies the JSON field name. If unspecified, the unexported name is used.

func (*FieldSpec) Required 

func (f *FieldSpec) Required(b bool) *FieldSpec

func (*FieldSpec) Unexported 

func (f *FieldSpec) Unexported(s string) *FieldSpec

Unexported specifies the unexported name for this field. If unspecified, the name of the field is automatically converted into a camel-case string with the first phrase being lower cased

type InitializerArgumentStyle 

type InitializerArgumentStyle int

InitializerArgumentStyle is used when you would like to override the default behavior and specify that a pseudo-TypeSpec (those types that are not constructed from actual Go objects)'s Builder methods should take a variadic form vs singular form.

type Interface 

type Interface interface {
	Name() string
	Package() string
	Fields() []*FieldSpec
	Comment() string
	KeyNamePrefix() string
	GetKeyName(string) string
}

Interface exists to provide an abstraction for multiple schema objects that embed schema.Base object in the intermediate program that sketch produces. Users of sketch generally need not worry about this interface.

type TypeSpec 

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

TypeSpec is used to store information about a type, and contains various pieces of hints to generate objects/builders.

One important concept that you need to be aware of is that of Apparent Types and Storage Types. An apparent type refers to the type that the end user sees. The pparent type may or may not match the storage type, which is the type that the generated object stores the data as.

For example, you may want to expose a field as accepting a slice of strings (`[]string`), but store it as an object, maybe something like a custom `StringList` that you created. In this case `[]string` is the apparent type, and `StringList` is the storage type.

The `TypeSpec` object is meant to store the storage type, but you can associate the corresponding apparent type via the `ApparentType` method.

func Type 

func Type(v interface{}) *TypeSpec

Type creates a new TypeSpec from a piece of Go data using reflection. It populates all the required fields by inspecting the structure, which you can override later.

func TypeName 

func TypeName(name string) *TypeSpec

TypeName creates a TypeSpec from a string name.

If you are allowed to include the struct into the schema code, you should not be using this function. Only use this function when you either have to refer to objects that you are about to generate using sketch, or for objects that you cannot import because of cyclic dependency, etc.

Unlike `Type`, this constructor only takes the name of the type and otherwise has no other information. Therefore it assumes many things, and you will have to set many parameers manually.

The defualt zero value is assumed to be `nil`

If the name starts with a `[]`, then `IsSlice()` is automatically set to true If the name starts with a `map[`, then `IsMap()` is automatically set to true

func (*TypeSpec) AcceptValue 

func (ts *TypeSpec) AcceptValue(b bool) *TypeSpec

AcceptValue specifies that this type implements the `AcceptValue` method. The `AcceptValue` method must take a single `interface{}` argument, and set the internal value from the given argument, which could be anything that can either be accepted from JSON source, or from a user attempting to set a value to a field of this type.

For example, if you are storing `time.Time` as `mypkg.EpochTime`, and you want users to set `time.Time` values via the Builder (instead of `mypkg.EpochTime`), you will want to implement a `AcceptValue(interface{}) error` method, and implement it such that the value of given `interface{}` is properly set to the internal representation of `mypkg.EpochTime`.

Similarly, if this `mypkg.EpochTime` field is represented as an integer in the JSON source, you might want to handle that as well.

By default the method name for this method is `AcceptValue`, but you will be able to change it by setting a value with the `AcceptValueMethodName`. Calling `AcceptValue(true)` is equivalent to `AcceptValueMethodName("AcceptValue")`

func (*TypeSpec) AcceptValueMethodName 

func (ts *TypeSpec) AcceptValueMethodName(s string) *TypeSpec

AcceptValueMethodName sets the name of the method that fulfills the `AcceptValue` semantics. Set to the empty string if you would like to indicate that the type does not implement the `AcceptValue` interface.

func (*TypeSpec) ApparentType 

func (ts *TypeSpec) ApparentType(s string) *TypeSpec

func (*TypeSpec) Element 

func (ts *TypeSpec) Element(s string) *TypeSpec

func (*TypeSpec) GetAcceptValueMethodName 

func (ts *TypeSpec) GetAcceptValueMethodName() string

GetAcceptValueMethodName returns the name of the `AcceptValue` method.

func (*TypeSpec) GetApparentType 

func (ts *TypeSpec) GetApparentType() string

func (*TypeSpec) GetElement 

func (ts *TypeSpec) GetElement() string

func (*TypeSpec) GetGetValueMethodName 

func (ts *TypeSpec) GetGetValueMethodName() string

GetGetValueMethodName returns the name of the `GetValue` method.

func (*TypeSpec) GetInterfaceDecoder 

func (ts *TypeSpec) GetInterfaceDecoder() string

func (*TypeSpec) GetIsInterface 

func (ts *TypeSpec) GetIsInterface() bool

func (*TypeSpec) GetName 

func (ts *TypeSpec) GetName() string

func (*TypeSpec) GetPointerType 

func (ts *TypeSpec) GetPointerType() string

func (*TypeSpec) GetRawType 

func (ts *TypeSpec) GetRawType() string

func (*TypeSpec) GetSupportsLen 

func (ts *TypeSpec) GetSupportsLen() bool

func (*TypeSpec) GetValue 

func (ts *TypeSpec) GetValue(b bool) *TypeSpec

GetValue specifies that this type implements the `GetValue` method. The `GetValue` method must return a single element, which represents the apparent (user-facing) type of the field.

For example, if you are storing `time.Time` as `mypkg.EpochTime`, and you want users to get `time.Time` values from the accessor (instead of `mypkg.EpochTime`), you will want to implement a `GetValue() time.Time` method, and make sure that the TypeSpec recognizes its existance.

By default the method name for this method is `GetValue`, but you will be able to change it by setting a value with the `GetValueMethodName`. Calling `GetValue(true)` is equivalent to `GetValueMethodName("GetValue")`

func (*TypeSpec) GetValueMethodName 

func (ts *TypeSpec) GetValueMethodName(s string) *TypeSpec

GetValueMethodName sets the name of the method that fulfills the `GetValue` semantics. Set to the empty string if you would like to indicate that the type does not implement the `GetValue` interface.

func (*TypeSpec) GetZeroVal 

func (ts *TypeSpec) GetZeroVal() string

func (*TypeSpec) InitializerArgumentStyle 

func (ts *TypeSpec) InitializerArgumentStyle(ias InitializerArgumentStyle) *TypeSpec

func (*TypeSpec) InterfaceDecoder 

func (ts *TypeSpec) InterfaceDecoder(s string) *TypeSpec

InterfaceDecoder should be set to the name of the function that can take a `[]byte` variable and return a value assignable to the type. For example a type specified as below 

schema.Type(`mypkg.Interface`).InterfaceDecoder(`mypkg.Parse`)

may produce code resembling 

var val mypkg.Interface
var err error
val, err = mypkg.Parse(src) // src is []byte

This value is not automatically assigned. Therefore you will laways need to specify this if you are referring to an interface

func (*TypeSpec) IsInterface 

func (ts *TypeSpec) IsInterface(b bool) *TypeSpec

IsInterface should be set to true if the type is an interface. When this is true, the decoding logic generated changes. See also `InterfaceDecoder`

func (*TypeSpec) PointerType 

func (ts *TypeSpec) PointerType(s string) *TypeSpec

PointerType specifies the "indirect" type of a field. The fields are stored as _pointers_ to the actual type, so for most types we simply prepend a `*` to the type. For example for a `string` type, the indirect type would be `*string`, whereas for `*Foo` type, we just use `*Foo` as the indirect type. But for cases when you would like to store an interface, for example, you might want to avoid prepending the `*` by explicitly specifying the name of the indirect type.

func (*TypeSpec) RawType 

func (ts *TypeSpec) RawType(s string) *TypeSpec

func (*TypeSpec) SliceStyleInitializerArgument 

func (ts *TypeSpec) SliceStyleInitializerArgument() bool

func (*TypeSpec) SupportsLen 

func (ts *TypeSpec) SupportsLen(b bool) *TypeSpec

func (*TypeSpec) ZeroVal 

func (ts *TypeSpec) ZeroVal(s string) *TypeSpec

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.