csgen

README

       
   

CSGen

CSGen is a Golang utility package for simplifying development of code generation tools. It contains abstractions around the standard library AST packages to make using them more intuitive for developers.

Get the Package

go get github.com/cscoding21/csgen

Core Uses

The primary use-case for the library is to get a list of all the structs in a file including details about each field.

import (
    "fmt"
    "github.com/cscoding21/csgen"
)

//---get all of the structs within a file.
structs, err := csgen.GetStructs("test_struct.go")

if err != nil {
    panic("error loading file")
}

for _, s := range structs {
    fmt.Println(s.Name)
    for _, f := range s.Fields {
        fmt.Println("  -- ", f.Name, f.Type)
    }
} 

The struct object contains information about the struct's definition as well as all fields contained within.

Struct Properties

Property	Type	Description
Name	string	The name of the struct
Type	string	The type of the struct
FilePath	string	The path to the file containing the struct
Package	string	The package the struct is contained within
Fields	[]Field	The list of fields contained within the struct

Additionally, a struct has a GetField(name string) method that will return an individual field object by its name.

Field Properties

Property	Type	Description
Name	string	The name of the field
Type	string	The type of the field
TagString	string	The tag string for the field
IsPrimitive	bool	True if the field is a primitive type
IsPointer	bool	True if the field is defined as a pointer to value
IsSlice	bool	True if the field is a slice
IsPublic	bool	True if the field is available outside the package

Additionally, a field has a GetTag(name string) method. This method can be used to extract the value of an individual tag from the tag string. For example, consider the tag string json:"email" csval:"req,email".

s.GetTag("json")    //---returns "email"
s.GetTag("caval")   //---returns "req,email"

Documentation

Index

• func ExecuteTemplate[T any](name string, fileTemplate string, om T) string
• func ExtractPackageName(name string) string
• func GetAST(filePath string) (*ast.File, error)
• func GetDefaultPackageConfig() *packages.Config
• func GetFieldIndicator(source Field, target Field) string
• func GetFile(file ...string) string
• func GetFileName(imp string, path string, name string) string
• func GetImports(filePath string) ([]string, error)
• func GetRawType(t string) string
• func HandleCLA(input string, alt string) string
• func InferPackageFromOutputPath(outPath string) string
• func IsFullyQualifiedPackage(name string) bool
• func IsPrimitive(t string) bool
• func IsPublic(t string) bool
• func IsRefType(t string) bool
• func IsSlice(t string) bool
• func NewCSGenBuilderForFile(name string, pkg string) *strings.Builder
• func NewCSGenBuilderForOneOffFile(name string, pkg string) *strings.Builder
• func ProfileNode(node ast.Node)
• func StripPackageName(name string) string
• func WriteGeneratedGoFile(name string, contents string) error
• type Field
  • func GetVariables(filePath string) ([]Field, error)
  • func (f *Field) GetCleanedType() string
  • func (f *Field) GetTag(name string) string
• type Function
  • func GetFunctions(filePath string) ([]Function, error)
• type Interface
  • func GetInterfaces(filePath string) ([]Interface, error)
• type Module
  • func LoadModule(cfg *packages.Config, pattern ...string) (Module, error)
  • func (m *Module) GetPackage(name string) *Package
• type Package
  • func (p *Package) GetStruct(name string) *Struct
• type Struct
  • func GetStructByName(name string, graph []Struct) *Struct
  • func GetStructs(filePath string) ([]Struct, error)
  • func (s *Struct) AllFields() []Field
  • func (s *Struct) ContainsField(name string) bool
  • func (s *Struct) GetField(name string) *Field

Functions

func ExecuteTemplate

func ExecuteTemplate[T any](name string, fileTemplate string, om T) string

ExecuteTemplate executes a template against a given object and return the output as a string

func ExtractPackageName

func ExtractPackageName(name string) string

ExtractPackageName return the package name from a fully qualified name

func GetAST

func GetAST(filePath string) (*ast.File, error)

GetAST return an AST object from a single file

func GetDefaultPackageConfig

func GetDefaultPackageConfig() *packages.Config

GetDefaultPackageConfig return a default set of values for loading module packages

func GetFieldIndicator

func GetFieldIndicator(source Field, target Field) string

GetFieldIndicator for creating an assignment operations, returns an indicator for the field based on the type of the source and target

func GetFile

func GetFile(file ...string) string

GetFile returns the current file based on the generators env or passed in value

func GetFileName

func GetFileName(imp string, path string, name string) string

GetFileName return a file name suffixed with ".gen.go" to indicate that is was generated

func GetImports

func GetImports(filePath string) ([]string, error)

GetImports returns all of the imports in a given file

func GetRawType

func GetRawType(t string) string

GetRawType return the raw type of a type, removing the pointer, reference and slice indicators

func HandleCLA

func HandleCLA(input string, alt string) string

HandleCLA the packages package has some weird behavior with a magic string called "command-line-arguments". will handle thosee cases here

func InferPackageFromOutputPath

func InferPackageFromOutputPath(outPath string) string

InferPackageFromOutputPath given the output path, return the package name consistent with the deepest directory

func IsFullyQualifiedPackage

func IsFullyQualifiedPackage(name string) bool

IsFullyQualifiedPackage return true if the package name is fully qualified

func IsPrimitive

func IsPrimitive(t string) bool

IsPrimitive return true if the type is a primitive

func IsPublic

func IsPublic(t string) bool

IsPublic return true if the type is public

func IsRefType

func IsRefType(t string) bool

IsRefType return true if the type is a pointer

func IsSlice

func IsSlice(t string) bool

IsSlice return true if the type is a slice

func NewCSGenBuilderForFile

func NewCSGenBuilderForFile(name string, pkg string) *strings.Builder

NewCSGenBuilderForFile returns a string buider with a common header for generated files

func NewCSGenBuilderForOneOffFile

func NewCSGenBuilderForOneOffFile(name string, pkg string) *strings.Builder

NewCSGenBuilderForOneOffFile returns a string buider with a common header for generated files that are indented to be modified

func ProfileNode

func ProfileNode(node ast.Node)

ProfileNode get details about an unknown node based on its actual type

func StripPackageName

func StripPackageName(name string) string

StripPackageName removes the package name from a fully qualified name

func WriteGeneratedGoFile

func WriteGeneratedGoFile(name string, contents string) error

WriteGeneratedGoFile create a text file with the passed in name and contents

Types

type Field

type Field struct {
	Name        string
	Type        string
	TagString   string
	IsPrimitive bool
	IsPointer   bool
	IsSlice     bool
	IsPublic    bool
}

Field a struct that represents a single field within a struct abstraction

func GetVariables

func GetVariables(filePath string) ([]Field, error)

GetVariables returns a list of all variable definitions in a given file

func (*Field) GetCleanedType

func (f *Field) GetCleanedType() string

GetCleanedType return a cleaned version of the type in case it includes a fully qualified namespace

func (*Field) GetTag

func (f *Field) GetTag(name string) string

GetTag returns a single tag value by name based on the standard format rules

type Function

type Function struct {
	Name      string
	Receiver  *string
	Arguments []Field
	Returns   []Field
	IsPublic  bool
}

Function a struct that represents a single function abstraction

func GetFunctions

func GetFunctions(filePath string) ([]Function, error)

GetFunctions returns all of the functions in a given file

type Interface

type Interface struct {
	Name     string
	Methods  []Function
	IsPublic bool
}

Interface a struct that represents a single interface abstraction

func GetInterfaces

func GetInterfaces(filePath string) ([]Interface, error)

GetInterfaces get a list of all declared interfaces in a given file

type Module

type Module struct {
	Name     string
	Path     string
	Packages []Package
}

Module represents an object graph for the entire codebase

func LoadModule

func LoadModule(cfg *packages.Config, pattern ...string) (Module, error)

LoadModule use the "packages" package to load codebase items

func (*Module) GetPackage

func (m *Module) GetPackage(name string) *Package

GetPackage return a package from a module based on its name

type Package

type Package struct {
	ID       string
	Name     string
	FullName string
	Path     string
	Files    []string
	Structs  []Struct
}

Package represents an object graph for an entire package

func (*Package) GetStruct

func (p *Package) GetStruct(name string) *Struct

GetStruct return a struct with the name that matches the argument

type Struct

type Struct struct {
	Name            string
	FilePath        string
	Package         string
	Type            string
	Fields          []Field
	EmbeddedStructs []Struct
}

Struct a struct that abstracts a golang struct

func GetStructByName

func GetStructByName(name string, graph []Struct) *Struct

GetStructByName given a slice of structs, return one if it matches the name

func GetStructs

func GetStructs(filePath string) ([]Struct, error)

GetStructs return a list of all structs in a given file

func (*Struct) AllFields

func (s *Struct) AllFields() []Field

AllFields return all fields and embedded fields

func (*Struct) ContainsField

func (s *Struct) ContainsField(name string) bool

ContainsField returns true if the struct contains a field with the passed in name

func (*Struct) GetField

func (s *Struct) GetField(name string) *Field

GetField return a field object of a struct by its name