headerspec

Documentation

Overview

Package headerspec parses clang JSON AST output and generates spec YAML.

Index

• func GenerateCapiPackage(manifest *Manifest, decls *Declarations, outDir string) error
• func GenerateSpec(moduleName string, sourcePackage string, decls *Declarations) *specmodel.Spec
• func WriteSpecYAML(spec *specmodel.Spec, path string) error
• type ASTNode
  • func ParseClangAST(jsonData []byte) (*ASTNode, error)
• type Declarations
  • func ApplyRules(decls *Declarations, rules []Rule) *Declarations
  • func ExtractDeclarations(root *ASTNode, targetHeaders []string) *Declarations
• type EnumConstant
• type EnumInfo
• type FieldInfo
• type FlagGroup
• type FuncDecl
• type GeneratorConfig
• type IncluRef
• type Location
• type Manifest
  • func ParseManifest(path string) (*Manifest, error)
• type ParamInfo
• type ParserConfig
• type Range
• type Rule
• type StructInfo
• type TranslatorConfig
• type TypeInfo
• type TypedefInfo

Functions

func GenerateCapiPackage

func GenerateCapiPackage(
	manifest *Manifest,
	decls *Declarations,
	outDir string,
) error

GenerateCapiPackage generates a complete capi/ Go package from the manifest and extracted declarations. It writes doc.go, types.go, const.go, cgo_helpers.go, cgo_helpers.h, and functions.go into outDir.

func GenerateSpec

func GenerateSpec(
	moduleName string,
	sourcePackage string,
	decls *Declarations,
) *specmodel.Spec

GenerateSpec converts filtered declarations into a specmodel.Spec.

func WriteSpecYAML

func WriteSpecYAML(spec *specmodel.Spec, path string) error

WriteSpecYAML marshals a Spec to YAML and writes it to the given path.

Types

type ASTNode

type ASTNode struct {
	ID                  string    `json:"id"`
	Kind                string    `json:"kind"`
	Name                string    `json:"name,omitempty"`
	MangledName         string    `json:"mangledName,omitempty"`
	Type                *TypeInfo `json:"type,omitempty"`
	Inner               []ASTNode `json:"inner,omitempty"`
	Loc                 *Location `json:"loc,omitempty"`
	Range               *Range    `json:"range,omitempty"`
	IsImplicit          bool      `json:"isImplicit,omitempty"`
	IsReferenced        bool      `json:"isReferenced,omitempty"`
	CompleteDefinition  bool      `json:"completeDefinition,omitempty"`
	TagUsed             string    `json:"tagUsed,omitempty"`
	FixedUnderlyingType *TypeInfo `json:"fixedUnderlyingType,omitempty"`
	StorageClass        string    `json:"storageClass,omitempty"`
	Value               string    `json:"value,omitempty"`
	CastKind            string    `json:"castKind,omitempty"`
	CC                  string    `json:"cc,omitempty"`
	OwnedTagDecl        *ASTNode  `json:"ownedTagDecl,omitempty"`
	Decl                *ASTNode  `json:"decl,omitempty"`
	ValueCategory       string    `json:"valueCategory,omitempty"`
}

ASTNode represents a node in clang's JSON AST dump.

func ParseClangAST

func ParseClangAST(jsonData []byte) (*ASTNode, error)

ParseClangAST unmarshals clang's -ast-dump=json output into an ASTNode tree.

type Declarations

type Declarations struct {
	Functions []FuncDecl
	Typedefs  []TypedefInfo
	Enums     []EnumInfo
	Structs   []StructInfo
}

Declarations holds all extracted C declarations from the AST.

func ApplyRules

func ApplyRules(decls *Declarations, rules []Rule) *Declarations

ApplyRules filters declarations using accept/ignore rules from the manifest.

Rules are evaluated in order. For each declaration name:

1. Check all ignore rules first; if any match, the declaration is excluded.
2. Check all accept rules; if any match, the declaration is included.
3. If no rule matches, the declaration is excluded (default deny).

func ExtractDeclarations

func ExtractDeclarations(
	root *ASTNode,
	targetHeaders []string,
) *Declarations

ExtractDeclarations walks the root AST node and extracts all declarations from the specified target header files.

Clang only emits loc.file for the FIRST node from each file; subsequent nodes only have line/col. We track the "current file" while iterating through root.Inner to correctly filter by target headers.

type EnumConstant

type EnumConstant struct {
	Name  string
	Value int64
}

EnumConstant is one value in an enum.

type EnumInfo

type EnumInfo struct {
	Name        string
	TypedefName string
	FixedType   string
	Constants   []EnumConstant
}

EnumInfo describes an enum declaration with its constants.

type FieldInfo

type FieldInfo struct {
	Name       string
	Type       string
	IsFuncPtr  bool
	FuncParams []ParamInfo
	FuncReturn string
}

FieldInfo describes one field of a struct.

type FlagGroup

type FlagGroup struct {
	Name  string   `yaml:"name"`
	Flags []string `yaml:"flags"`
}

FlagGroup is a named set of compiler/linker flags.

type FuncDecl

type FuncDecl struct {
	Name       string
	ReturnType string
	Params     []ParamInfo
}

FuncDecl represents an extracted C function declaration.

type GeneratorConfig

type GeneratorConfig struct {
	PackageName        string      `yaml:"PackageName"`
	PackageDescription string      `yaml:"PackageDescription"`
	PackageLicense     string      `yaml:"PackageLicense"`
	Includes           []string    `yaml:"Includes"`
	FlagGroups         []FlagGroup `yaml:"FlagGroups"`
}

GeneratorConfig holds package generation settings.

type IncluRef

type IncluRef struct {
	File string `json:"file,omitempty"`
}

IncluRef references the file that included this location.

type Location

type Location struct {
	File         string    `json:"file,omitempty"`
	Line         int       `json:"line,omitempty"`
	Col          int       `json:"col,omitempty"`
	Offset       int       `json:"offset,omitempty"`
	TokLen       int       `json:"tokLen,omitempty"`
	IncludedFrom *IncluRef `json:"includedFrom,omitempty"`
	SpellingLoc  *Location `json:"spellingLoc,omitempty"`
	ExpansionLoc *Location `json:"expansionLoc,omitempty"`
}

Location holds source location information from a clang AST node.

type Manifest

type Manifest struct {
	Generator  GeneratorConfig  `yaml:"GENERATOR"`
	Parser     ParserConfig     `yaml:"PARSER"`
	Translator TranslatorConfig `yaml:"TRANSLATOR"`
}

Manifest is the top-level manifest YAML used by capigen/headerspec.

func ParseManifest

func ParseManifest(path string) (*Manifest, error)

ParseManifest reads and unmarshals a manifest YAML file.

type ParamInfo

type ParamInfo struct {
	Name string
	Type string
}

ParamInfo describes one function/callback parameter.

type ParserConfig

type ParserConfig struct {
	IncludePaths []string `yaml:"IncludePaths"`
	SourcesPaths []string `yaml:"SourcesPaths"`
}

ParserConfig holds parser-specific settings (used by c-for-go, kept for compatibility).

type Range

type Range struct {
	Begin *Location `json:"begin,omitempty"`
	End   *Location `json:"end,omitempty"`
}

Range holds a source range (begin/end locations).

type Rule

type Rule struct {
	Action string `yaml:"action"`
	From   string `yaml:"from"`
	To     string `yaml:"to,omitempty"`
}

Rule is a single accept/ignore rule with a regex pattern.

type StructInfo

type StructInfo struct {
	Name       string
	IsComplete bool
	Fields     []FieldInfo
}

StructInfo describes a struct declaration.

type TranslatorConfig

type TranslatorConfig struct {
	ConstRules map[string]string `yaml:"ConstRules"`
	Rules      map[string][]Rule `yaml:"Rules"`
}

TranslatorConfig holds accept/ignore rules and const evaluation settings.

type TypeInfo

type TypeInfo struct {
	QualType          string `json:"qualType"`
	DesugaredQualType string `json:"desugaredQualType,omitempty"`
	TypeAliasDeclID   string `json:"typeAliasDeclId,omitempty"`
}

TypeInfo holds type qualification data from a clang AST node.

type TypedefInfo

type TypedefInfo struct {
	Name           string
	UnderlyingType string
	DesugaredType  string // desugared qualType from clang (resolves typedef chains)
	IsOpaqueStruct bool
	IsEnumTypedef  bool // true if this typedefs an enum
	IsFuncPtr      bool
	FuncParams     []ParamInfo
	FuncReturn     string
}

TypedefInfo describes a typedef declaration.