analysis

package
v0.0.0-...-1b88873 Latest Latest
Warning

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

 Go to latest Published: Jan 14, 2025 License: BSD-3-Clause, Unlicense Imports: 9 Imported by: 0

Documentation

Overview

Package analysis uses go/types and go/packages to extract information about the structures to convert to binary form.

Index

Constants

View Source 
const (
	Current     OffsetRelative = iota
	Parent                     = 1 << 0
	GrandParent                = 1 << 1
)

Variables

This section is empty.

Functions

func ImportSource 

func ImportSource(path string) (*packages.Package, string, error)

ImportSource loads the source go file with go/packages, also returning the absolute path.

Types

type Analyser 

type Analyser struct {
	// Source is the path of the origin go source file.
	Source string

	// Tables contains the resolved struct definitions, coming from the
	// go source file [Source] and its dependencies.
	Tables map[*types.Named]Struct

	// StandaloneUnions returns the union with an implicit union tag scheme,
	// for which standalone parsing/writing function should be generated
	StandaloneUnions map[*types.Named]Union

	// ChildTypes contains types that are used in other types.
	// For instance, top-level tables have a [false] value.
	ChildTypes map[*types.Named]bool
	// contains filtered or unexported fields
}

Analyser provides information about types, shared by the parser and writer code generator

func NewAnalyser 

func NewAnalyser(path string) (Analyser, error)

NewAnalyser load the package of `path` and analyze the defined structs, filling the fields [Source] and [Tables].

func NewAnalyserFromPkg 

func NewAnalyserFromPkg(pkg *packages.Package, sourcePath, sourceAbsPath string) Analyser

NewAnalyserFromPkg uses [pkg] to analyse the tables defined in [sourcePath].

func (*Analyser) ByName 

func (an *Analyser) ByName(name string) *types.Named

ByName returns the type with name [name], or panic if it does not exist

func (*Analyser) PackageName 

func (an *Analyser) PackageName() string

type Argument 

type Argument struct {
	VariableName string
	TypeName     string
}

type Array 

type Array struct {

	// Len is the length of elements in the array
	Len int

	// Elem is the type of the element
	Elem Type
	// contains filtered or unexported fields
}

Array is a fixed length array.

func (Array) IsFixedSize 

func (ar Array) IsFixedSize() (BinarySize, bool)

func (Array) Origin 

func (t Array) Origin() types.Type

type ArrayCount 

type ArrayCount uint8

ArrayCount defines how the number of elements in an array is defined 

const (
	// The length must be provided by the context and is not found in the binary
	NoLength ArrayCount = iota

	// The length is written at the start of the array, as an uint16
	FirstUint16
	// The length is written at the start of the array, as an uint32
	FirstUint32

	// The length is deduced from an other field, parsed previously,
	// or computed by a method or an expression
	ComputedField

	// For raw data, that is slice of bytes, this special value
	// indicates that the data must be copied until the end of the
	// given slice
	ToEnd

	// For raw data, that is slice of bytes, this special value
	// indicates that the data must be copied until the offset (not the length)
	// given by an other field, parsed previously,
	// or computed by a method or an expression
	ToComputedField
)

func (ArrayCount) Size 

func (c ArrayCount) Size() BinarySize

Size returns the binary size occupied by the count field, or zero if it is specified externally

type Basic 

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

Basic is a fixed size type, directly convertible from and to uintXX

func (Basic) IsFixedSize 

func (ba Basic) IsFixedSize() (BinarySize, bool)

func (Basic) Origin 

func (t Basic) Origin() types.Type

type BinarySize 

type BinarySize int

BinarySize indicates how many bytes are needed to store a value 

const (
	Byte BinarySize = 1 << iota
	Uint16
	Uint32
	Uint64
)

type DerivedFromBasic 

type DerivedFromBasic struct {

	// For aliases, it is the Name of the defined (not the "underlying" type)
	// For named types, the Name of the defined type
	// Otherwise, it is the string representation
	Name string

	// Size is the size as read and written in binary files
	Size BinarySize
	// contains filtered or unexported fields
}

DerivedFromBasic is stored as a an uintXX, but uses custom constructor to perform the convertion : <typeString>FromUintXX ; <typeString>ToUintXX

func (DerivedFromBasic) IsFixedSize 

func (de DerivedFromBasic) IsFixedSize() (BinarySize, bool)

func (DerivedFromBasic) Origin 

func (t DerivedFromBasic) Origin() types.Type

type Field 

type Field struct {
	Type Type
	Name string

	// name of other fields which will be provided
	// to parsing/writing functions
	ArgumentsProvidedByFields []ProvidedArgument

	// Non empty for fields indicating the kind of union
	// (usually the first field)
	UnionTag constant.Value

	// Non zero if the offset must be resolved into
	// the parent (or grand-parent) slice
	OffsetRelativeTo OffsetRelative
}

Field is a struct field. Embeded fields are not resolved.

type Offset 

type Offset struct {
	// Target if the type the offset is pointing at
	Target Type

	// Size if the size of the offset field
	Size BinarySize

	// IsPointer is true if the target type is actually
	// a pointer. In this case, [Target] is a [Struct].
	IsPointer bool
}

Offset is a fixed size integer pointing to an other type, which has never a fixed size.

func (Offset) IsFixedSize 

func (of Offset) IsFixedSize() (BinarySize, bool)

IsFixedSize returns [Size], `false`, since, even if the offset itself has a fixed size, the whole data has not and requires additional length check.

func (Offset) Origin 

func (t Offset) Origin() types.Type

type OffsetRelative 

type OffsetRelative uint8

OffsetRelative indicates if the offset is related to the current slice or the one of its parent type (or grand parent)

func ResolveOffsetRelative 

func ResolveOffsetRelative(ty Type) OffsetRelative

ResolveOffsetRelative return the union flag of all the fields.

type OffsetSize 

type OffsetSize uint8

OffsetSize is the size (in bits) of the storage of an offset to a field type, or 0 

const (
	NoOffset OffsetSize = iota
	// The offset is written as uint16
	Offset16
	// The offset is written as uint32
	Offset32
)

type Opaque 

type Opaque struct {

	// ParserReturnsLength is true if the custom parsing
	// function returns the length read.
	ParserReturnsLength bool

	// How should the slice be passed
	SubsliceStart SubsliceStart
	// contains filtered or unexported fields
}

Opaque represents a type with no binary structure. The parsing and writting step will be replaced by placeholder methods.

func (Opaque) IsFixedSize 

func (Opaque) IsFixedSize() (BinarySize, bool)

func (Opaque) Origin 

func (t Opaque) Origin() types.Type

type ProvidedArgument 

type ProvidedArgument struct {
	Value string // a go expression of the value
	For   string // the argument name this value is providing
}

type Scope 

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

Scope defines one step of parsing/writting, which may come from several fields. It is an optimisation to reduce length checks

type SingleField 

type SingleField Field

type Slice 

type Slice struct {

	// Elem is the type of the element
	Elem Type

	// Count indicates how to read/write the length of the array
	Count ArrayCount
	// CountExpr is used when [Count] is [ComputedField] or [ToComputedField]
	CountExpr string

	// SubsliceStart is only used for raw data ([]byte).
	SubsliceStart SubsliceStart
	// contains filtered or unexported fields
}

Slice is a variable size array If Elem is Offset, it represents a slice of (variable sized) elements written in binary as a slice of offsets

func (Slice) IsFixedSize 

func (sl Slice) IsFixedSize() (BinarySize, bool)

IsFixedSize returns false and the length of the fixed size length prefix, if any.

func (Slice) IsRawData 

func (sl Slice) IsRawData() bool

IsRawData returns true for []byte

func (Slice) Origin 

func (t Slice) Origin() types.Type

type StaticSizedFields 

type StaticSizedFields []Field

StaticSizedFields is a list of fields which all have a static size. Slice and Offset may be used to denote the fixed size part item.

func (StaticSizedFields) Size 

func (fs StaticSizedFields) Size() BinarySize

Size return the cumulated size of all fields

type Struct 

type Struct struct {
	Fields []Field

	// Arguments is not empty if the struct parsing/writting function
	// requires data not provided in the input slice
	Arguments []Argument

	// HasParseEnd is non nil if the table has an
	// additional "parseEnd" method which must be called
	// at the end of parsing
	ParseEnd *types.Func
	// contains filtered or unexported fields
}

Struct defines the the binary layout of a struct

func (Struct) IsFixedSize 

func (st Struct) IsFixedSize() (BinarySize, bool)

IsFixedSize returns true if all the fields have fixed size.

func (Struct) Origin 

func (t Struct) Origin() types.Type

func (Struct) Scopes 

func (st Struct) Scopes() (out []Scope)

type SubsliceStart 

type SubsliceStart uint8

SubsliceStart indicates where the start of the subslice given to the field parsing function shall be computed 

const (
	// The current slice is sliced at the current offset for the field
	AtCurrent SubsliceStart = iota
	// The current slice is not resliced
	AtStart
)

type Type 

type Type interface {
	// Origin returns the Go type yielding the type
	Origin() types.Type

	// IsFixedSize returns the number of byte needed to store an element,
	// or false if it is not known at compile time.
	IsFixedSize() (BinarySize, bool)
}

Type is the common interface for struct field types supported by the package, describing the binary layout of a type.

type Union 

type Union struct {

	// Members stores the possible members
	Members []Struct

	UnionTag UnionTagScheme
	// contains filtered or unexported fields
}

Union represents an union of several types, which are identified by constant flags.

func (Union) IsFixedSize 

func (Union) IsFixedSize() (BinarySize, bool)

func (Union) Origin 

func (t Union) Origin() types.Type

type UnionTagExplicit 

type UnionTagExplicit struct {
	// Flags are the possible flag values, in the same order as `Members`
	Flags []*types.Const

	// FlagField is the struct field indicating which
	// member is to be read
	FlagField string
}

UnionTagExplicit uses a field and defined constants. For instance : 

type myStruct struct {
	kind unionTag
	data itf `unionField:"kind"`
}
type unionTag uint16
const (
	unionTag1 = iota +1
	unionTag2
 )

func (UnionTagExplicit) TagsCode 

func (ut UnionTagExplicit) TagsCode() []string

type UnionTagImplicit 

type UnionTagImplicit struct {
	Tag   Type
	Flags []constant.Value // in the same order as `Members`
}

UnionTagImplicit uses a common field and values defined by struct tags

func (UnionTagImplicit) TagsCode 

func (ut UnionTagImplicit) TagsCode() []string

type UnionTagScheme 

type UnionTagScheme interface {
	// TagsCode return the tags go code (like a constant name or a valid constant expression)
	TagsCode() []string
}

UnionTagScheme is a union type for the two schemes supported : UnionTagExplicit or UnionTagImplicit

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.