gengo

package
v0.0.4 Latest Latest
Warning

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

 Go to latest Published: Aug 28, 2021 License: MIT Imports: 20 Imported by: 1

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 

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 

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 

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 

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 

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

func Generate 

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 "ldsch.*.gen.go".

Types

type AdjunctCfg 

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 

func (cfg *AdjunctCfg) Comments() bool

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

func (*AdjunctCfg) FieldSymbolLower 

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

func (*AdjunctCfg) FieldSymbolUpper 

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

func (*AdjunctCfg) MaybeUsesPtr 

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

func (*AdjunctCfg) TypeSymbol 

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 

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 

type FieldTuple struct {
	TypeName  schema.TypeName
	FieldName string
}

type NodeBuilderGenerator 

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 

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 

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 

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

func NewBytesReprBytesGenerator 

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

func NewFloatReprFloatGenerator 

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

func NewIntReprIntGenerator 

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

func NewLinkReprLinkGenerator 

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

func NewListReprListGenerator 

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

func NewMapReprMapGenerator 

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

func NewStringReprStringGenerator 

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

func NewStructReprMapGenerator 

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

func NewStructReprStringjoinGenerator 

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

func NewStructReprTupleGenerator 

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

func NewUnionReprKeyedGenerator 

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

func NewUnionReprKindedGenerator 

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

func NewUnionReprStringprefixGenerator 

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.