gengo

package
v0.16.0 Latest Latest
Warning

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

 Go to latest Published: Mar 9, 2022 License: MIT Imports: 20 Imported by: 8

README

gengo

This package contains a codegenerator for emitting Golang source code for datastructures based on IPLD Schemas.

It is at present a partially complete proof-of-concept. Use at your own risk.

There is not yet a user-facing CLI; you have to write code to use it.

See README_behaviors for notes about the behaviors of the code output by the generator.

Check out the HACKME document for more info about the internals, how they're organized, and how to hack on this package.

aims

gengo aims to:

  • generate native Golang code
  • that faithfully represents the data structuring specified by an IPLD Schema,
  • operating efficiently, both in speed (both creating and inspecting) and memory compactness;
  • producing a better type system for Golang (we've got unions and enums!)
  • that is both powerful and generic (when you need it)
  • and minimalist (when you don't),
  • with immutable data structures,
  • good validation primitives and type-supported safety systems,
  • and is friendly to embellishments of other hand-written Golang code.

Some of these aims should be satisfied.

Some are still a stretch ;) (we definitely don't have "minimalist" outputs, yet. Making this reachable by tuning is a goal, however!)

completeness

Legend:

  • ✔ - supported!
  • ✘ - not currently supported.
  • ⚠ - not currently supported -- and might not be obvious; be careful.
  • - - is not applicable
  • ? - feature definition needed! (applies to many of the "native extras" rows -- often there's partial features, but also room for more.)
  • - table is not finished, please refer to the code and help fix the table :)
feature accessors builders
structs ... ...
... type level ✔ ✔
... native extras ? ?
... map representation ✔ ✔
... ... including optional ✔ ✔
... ... including renames ✔ ✔
... ... including implicits ⚠ ⚠
... tuple representation ✔ ✔
... ... including optional ✔ ✔
... ... including renames - -
... ... including implicits ⚠ ⚠
... stringjoin representation ✔ ✔
... ... including optional - -
... ... including renames - -
... ... including implicits - -
... stringpairs representation ✘ ✘
... ... including optional
... ... including renames
... ... including implicits
... listpairs representation ✘ ✘
... ... including optional
... ... including renames
... ... including implicits
feature accessors builders
lists ... ...
... type level ✔ ✔
... native extras ? ?
... list representation ✔ ✔
feature accessors builders
maps ... ...
... type level ✔ ✔
... native extras ? ?
... map representation ✔ ✔
... stringpairs representation ✘ ✘
... listpairs representation ✘ ✘
feature accessors builders
unions ... ...
... type level ✔ ✔
... keyed representation ✔ ✔
... envelope representation ✘ ✘
... kinded representation ✔ ✔
... inline representation ✘ ✘
... stringprefix representation ✔ ✔
... byteprefix representation ✘ ✘
feature accessors builders
strings ✔ ✔
bytes ✔ ✔
ints ✔ ✔
floats ✔ ✔
bools ✔ ✔
links ✔ ✔
feature accessors builders
enums ... ...
... type level ✘ ✘
... string representation ✘ ✘
... int representation ✘ ✘

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EmitEntireType added in v0.0.2 

func EmitEntireType(tg TypeGenerator, w io.Writer)

EmitEntireType is a helper function calls all methods of TypeGenerator and streams all results into a single writer. (This implies two calls to EmitNode -- one for the type-level and one for the representation-level.)

func EmitFileHeader added in v0.0.2 

func EmitFileHeader(packageName string, w io.Writer)

EmitFileHeader emits a baseline package header that will allow a file with a generated type to compile. (Fortunately, there are no variations in this.)

func EmitInternalEnums added in v0.4.0 

func EmitInternalEnums(packageName string, w io.Writer)

EmitInternalEnums creates a file with enum types used internally. For example, the state machine values used in map and list builders. These always need to exist exactly once in each package created by codegen.

The file header and import statements are included in the output of this function. (The imports in this file are different than most others in codegen output; we gather up any references to other packages in this file in order to simplify the rest of codegen's awareness of imports.)

func EmitNode added in v0.4.0 

func EmitNode(ng NodeGenerator, w io.Writer)

EmitNode is a helper function that calls all methods of NodeGenerator and streams all results into a single writer.

func EmitTypeTable added in v0.4.0 

func EmitTypeTable(pkgName string, ts schema.TypeSystem, adjCfg *AdjunctCfg, w io.Writer)

func Generate added in v0.4.0 

func Generate(pth string, pkgName string, ts schema.TypeSystem, adjCfg *AdjunctCfg)

Generate takes a typesystem and the adjunct config for codegen, and emits generated code in the given path with the given package name.

All of the files produced will match the pattern "ipldsch.*.gen.go".

Types

type AdjunctCfg added in v0.4.0 

type AdjunctCfg struct {
	FieldSymbolLowerOverrides map[FieldTuple]string

	CfgUnionMemlayout map[schema.TypeName]string // "embedAll"|"interface"; maybe more options later, unclear for now.
	// contains filtered or unexported fields
}

func (*AdjunctCfg) Comments added in v0.6.0 

func (cfg *AdjunctCfg) Comments() bool

Comments returns a bool for whether comments should be included in gen output or not.

func (*AdjunctCfg) FieldSymbolLower added in v0.4.0 

func (cfg *AdjunctCfg) FieldSymbolLower(f schema.StructField) string

func (*AdjunctCfg) FieldSymbolUpper added in v0.4.0 

func (cfg *AdjunctCfg) FieldSymbolUpper(f schema.StructField) string

func (*AdjunctCfg) MaybeUsesPtr added in v0.4.0 

func (cfg *AdjunctCfg) MaybeUsesPtr(t schema.Type) bool

func (*AdjunctCfg) TypeSymbol added in v0.4.0 

func (cfg *AdjunctCfg) TypeSymbol(t schema.Type) string

TypeSymbol returns the symbol for a type; by default, it's the same string as its name in the schema, but it can be overriden.

This is the base, unembellished symbol. It's frequently augmented: prefixing an underscore to make it unexported; suffixing "__Something" to make the name of a supporting type; etc. (Most such augmentations are not configurable.)

func (*AdjunctCfg) UnionMemlayout added in v0.6.0 

func (cfg *AdjunctCfg) UnionMemlayout(t schema.Type) string

UnionMemlayout returns a plain string at present; there's a case-switch in the templates that processes it. We validate that it's a known string when this method is called. This should probably be improved in type-safety, and validated more aggressively up front when adjcfg is loaded.

type FieldTuple added in v0.4.0 

type FieldTuple struct {
	TypeName  schema.TypeName
	FieldName string
}

type NodeBuilderGenerator added in v0.4.0 

type NodeBuilderGenerator interface {
	EmitNodeBuilderType(io.Writer)
	EmitNodeBuilderMethods(io.Writer) // not many, so just slung them together.
	EmitNodeAssemblerType(io.Writer)  // you can call this and not EmitNodeBuilderType in some situations.
	EmitNodeAssemblerMethodBeginMap(io.Writer)
	EmitNodeAssemblerMethodBeginList(io.Writer)
	EmitNodeAssemblerMethodAssignNull(io.Writer)
	EmitNodeAssemblerMethodAssignBool(io.Writer)
	EmitNodeAssemblerMethodAssignInt(io.Writer)
	EmitNodeAssemblerMethodAssignFloat(io.Writer)
	EmitNodeAssemblerMethodAssignString(io.Writer)
	EmitNodeAssemblerMethodAssignBytes(io.Writer)
	EmitNodeAssemblerMethodAssignLink(io.Writer)
	EmitNodeAssemblerMethodAssignNode(io.Writer)
	EmitNodeAssemblerMethodPrototype(io.Writer)
	EmitNodeAssemblerOtherBits(io.Writer) // key and value child assemblers are done here.
}

type NodeGenerator added in v0.4.0 

type NodeGenerator interface {
	EmitNodeType(io.Writer)           // usually already covered by EmitNativeType for the primary node, but has a nonzero body for the repr node
	EmitNodeTypeAssertions(io.Writer) // optional to include this content
	EmitNodeMethodKind(io.Writer)
	EmitNodeMethodLookupByString(io.Writer)
	EmitNodeMethodLookupByNode(io.Writer)
	EmitNodeMethodLookupByIndex(io.Writer)
	EmitNodeMethodLookupBySegment(io.Writer)
	EmitNodeMethodMapIterator(io.Writer)  // also iterator itself
	EmitNodeMethodListIterator(io.Writer) // also iterator itself
	EmitNodeMethodLength(io.Writer)
	EmitNodeMethodIsAbsent(io.Writer)
	EmitNodeMethodIsNull(io.Writer)
	EmitNodeMethodAsBool(io.Writer)
	EmitNodeMethodAsInt(io.Writer)
	EmitNodeMethodAsFloat(io.Writer)
	EmitNodeMethodAsString(io.Writer)
	EmitNodeMethodAsBytes(io.Writer)
	EmitNodeMethodAsLink(io.Writer)
	EmitNodeMethodPrototype(io.Writer)
	EmitNodePrototypeType(io.Writer)
	GetNodeBuilderGenerator() NodeBuilderGenerator // assembler features also included inside
}

type TypeGenerator added in v0.4.0 

type TypeGenerator interface {
	EmitNativeType(io.Writer)
	EmitNativeAccessors(io.Writer) // depends on the kind -- field accessors for struct, typed iterators for map, etc.
	EmitNativeBuilder(io.Writer)   // typically emits some kind of struct that has a Build method.
	EmitNativeMaybe(io.Writer)     // a pointer-free 'maybe' mechanism is generated for all types.

	EmitTypeConst(io.Writer)           // these emit dummies for now
	EmitTypedNodeMethodType(io.Writer) // these emit dummies for now

	NodeGenerator

	EmitTypedNodeMethodRepresentation(io.Writer)
	GetRepresentationNodeGen() NodeGenerator // includes transitively the matched NodeBuilderGenerator
}

TypeGenerator gathers all the info for generating all code related to one type in the schema.

func NewBoolReprBoolGenerator added in v0.4.0 

func NewBoolReprBoolGenerator(pkgName string, typ *schema.TypeBool, adjCfg *AdjunctCfg) TypeGenerator

func NewBytesReprBytesGenerator added in v0.4.0 

func NewBytesReprBytesGenerator(pkgName string, typ *schema.TypeBytes, adjCfg *AdjunctCfg) TypeGenerator

func NewFloatReprFloatGenerator added in v0.4.0 

func NewFloatReprFloatGenerator(pkgName string, typ *schema.TypeFloat, adjCfg *AdjunctCfg) TypeGenerator

func NewIntReprIntGenerator added in v0.4.0 

func NewIntReprIntGenerator(pkgName string, typ *schema.TypeInt, adjCfg *AdjunctCfg) TypeGenerator

func NewLinkReprLinkGenerator added in v0.4.0 

func NewLinkReprLinkGenerator(pkgName string, typ *schema.TypeLink, adjCfg *AdjunctCfg) TypeGenerator

func NewListReprListGenerator added in v0.4.0 

func NewListReprListGenerator(pkgName string, typ *schema.TypeList, adjCfg *AdjunctCfg) TypeGenerator

func NewMapReprMapGenerator added in v0.4.0 

func NewMapReprMapGenerator(pkgName string, typ *schema.TypeMap, adjCfg *AdjunctCfg) TypeGenerator

func NewStringReprStringGenerator added in v0.4.0 

func NewStringReprStringGenerator(pkgName string, typ *schema.TypeString, adjCfg *AdjunctCfg) TypeGenerator

func NewStructReprMapGenerator added in v0.4.0 

func NewStructReprMapGenerator(pkgName string, typ *schema.TypeStruct, adjCfg *AdjunctCfg) TypeGenerator

func NewStructReprStringjoinGenerator added in v0.4.0 

func NewStructReprStringjoinGenerator(pkgName string, typ *schema.TypeStruct, adjCfg *AdjunctCfg) TypeGenerator

func NewStructReprTupleGenerator added in v0.6.0 

func NewStructReprTupleGenerator(pkgName string, typ *schema.TypeStruct, adjCfg *AdjunctCfg) TypeGenerator

func NewUnionReprKeyedGenerator added in v0.6.0 

func NewUnionReprKeyedGenerator(pkgName string, typ *schema.TypeUnion, adjCfg *AdjunctCfg) TypeGenerator

func NewUnionReprKindedGenerator added in v0.6.0 

func NewUnionReprKindedGenerator(pkgName string, typ *schema.TypeUnion, adjCfg *AdjunctCfg) TypeGenerator

func NewUnionReprStringprefixGenerator added in v0.9.0 

func NewUnionReprStringprefixGenerator(pkgName string, typ *schema.TypeUnion, adjCfg *AdjunctCfg) TypeGenerator

Source Files

View all Source files

Directories

Path Synopsis

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.