goparser

Documentation

Overview

Package goparser was taken from an open source project (https://github.com/zpatrick/go-parser) by zpatrick. Since it seemed that he had abandon it, I've integrated it into this project (and extended it).

Index

• func GetFilePaths(config ParseConfig, paths ...string) ([]string, error)
• func ParseSingleFileWalker(config ParseConfig, process ParseSingleFileWalkerFunc, paths ...string) error
• func ParseSinglePackageWalker(config ParseConfig, process ParseSinglePackageWalkerFunc, paths ...string) error
• type GoAssignment
• type GoCustomType
• type GoField
• type GoFile
  • func ParseAny(config ParseConfig, paths ...string) ([]*GoFile, error)
  • func ParseFiles(mod *GoModule, paths ...string) ([]*GoFile, error)
  • func ParseInlineFile(mod *GoModule, path, code string) (*GoFile, error)
  • func ParseSingleFile(mod *GoModule, path string) (*GoFile, error)
  • func (g *GoFile) DeclImports() string
  • func (g *GoFile) FindMethodsByReceiver(receiver string) []*GoStructMethod
  • func (g *GoFile) ImportPath() (string, error)
• type GoImport
  • func (g *GoImport) Prefix() string
• type GoInterface
• type GoMethod
• type GoModule
  • func NewModule(path string) (*GoModule, error)
  • func NewModuleFromBuff(path string, buff []byte) (*GoModule, error)
  • func (gm *GoModule) AddUnresolvedDeclaration(u UnresolvedDecl) *GoModule
  • func (gm *GoModule) ResolvePackage(path string) string
• type GoPackage
• type GoStruct
• type GoStructMethod
• type GoTag
  • func (g *GoTag) Get(key string) string
• type GoType
• type ParseConfig
• type ParseSingleFileWalkerFunc
• type ParseSinglePackageWalkerFunc
• type Resolver
  • func NewResolver(config ParseConfig, filepath string) Resolver
• type ResolverImpl
  • func (r *ResolverImpl) LoadAll() error
• type UnresolvedDecl

Functions

func GetFilePaths

func GetFilePaths(config ParseConfig, paths ...string) ([]string, error)

GetFilePaths will iterate directories (recursively) and add explicit files in the paths.

It is possible to use relative paths or fully qualified paths along with '.' for current directory. The paths are stat:ed so it will check if it is a file or directory and do accordingly. If file it will ignore configuration and blindly accept the file.

func ParseSingleFileWalker

func ParseSingleFileWalker(config ParseConfig, process ParseSingleFileWalkerFunc, paths ...string) error

ParseSingleFileWalker is same as ParseAny, except that it will be fed one GoFile at the time and thus consume much less memory.

It uses GetFilePaths and hence, the traversal is in sorted order, directory by directory.

func ParseSinglePackageWalker

func ParseSinglePackageWalker(config ParseConfig, process ParseSinglePackageWalkerFunc, paths ...string) error

ParseSinglePackageWalker is same as ParseAny, except that it will be fed one GoPackage at the time and thus consume much less memory.

It uses GetFilePaths and hence, the traversal is in sorted order, directory by directory. It will bundle all files in same directory and assign those to a GoPackage before invoking ParseSinglePackageWalkerFunc

Types

type GoAssignment

type GoAssignment struct {
	File *GoFile
	Name string
	Doc  string
	// Decl will be the same if multi var assignment on same row e.g. var pelle, lisa = 10, 19
	// then both pelle and list will have 'var pelle, lisa = 10, 19' as Decl
	Decl     string
	FullDecl string
	Exported bool
}

GoAssignment represents a single var assignment e.g. var pelle = 10

type GoCustomType

type GoCustomType struct {
	File     *GoFile
	Name     string
	Doc      string
	Type     string
	Decl     string
	Exported bool
}

GoCustomType is a custom type definition

type GoField

type GoField struct {
	File     *GoFile
	Struct   *GoStruct
	Doc      string
	Decl     string
	Name     string
	Type     string
	Exported bool
	Tag      *GoTag
	Nested   *GoStruct
}

GoField is a field in a file or struct

type GoFile

type GoFile struct {
	Module *GoModule
	// Package is the single package name where as FqPackage is the
	// fully qualified package (if Module) has been set.
	Package string
	// FqPackage is the fully qualified package name (if Module field)
	// is set to calculate the fq package name
	FqPackage        string
	FilePath         string
	Doc              string
	Decl             string
	ImportFullDecl   string
	Structs          []*GoStruct
	Interfaces       []*GoInterface
	Imports          []*GoImport
	StructMethods    []*GoStructMethod
	CustomTypes      []*GoCustomType
	CustomFuncs      []*GoMethod
	VarAssignments   []*GoAssignment
	ConstAssignments []*GoAssignment
}

GoFile represents a complete file

func ParseAny

func ParseAny(config ParseConfig, paths ...string) ([]*GoFile, error)

ParseAny parses one or more directories (recursively) for go files. It is also possible to add files along with directories (or just files).

It is possible to use relative paths or fully qualified paths along with '.' for current directory. The paths are stat:ed so it will check if it is a file or directory and do accordingly. If file it will ignore configuration and blindly accept the file.

The example below parses from current directory down recursively and skips test, internal and underscore directories. Example: ParseAny(ParseConfig{}, ".")

Next example will recursively add go files from src and one single test.go under directory dummy (both relative current directory). Example: ParseAny(ParseConfig{}, "./src", "./dummy/test.go")

func ParseFiles

func ParseFiles(mod *GoModule, paths ...string) ([]*GoFile, error)

ParseFiles parses one or more files

func ParseInlineFile

func ParseInlineFile(mod *GoModule, path, code string) (*GoFile, error)

ParseInlineFile will parse the code provided.

To simulate package names set the path to some level equal to or greater than GoModule.Base. Otherwise just set path "" to ignore.

func ParseSingleFile

func ParseSingleFile(mod *GoModule, path string) (*GoFile, error)

ParseSingleFile parses a single file at the same time

If a module is passed, it will calculate package relative to that

func (*GoFile) DeclImports

func (g *GoFile) DeclImports() string

DeclImports emits the imports

func (*GoFile) FindMethodsByReceiver

func (g *GoFile) FindMethodsByReceiver(receiver string) []*GoStructMethod

FindMethodsByReceiver searches the file / package after struct and custom type receiver methods that matches the _receiver_ name.

func (*GoFile) ImportPath

func (g *GoFile) ImportPath() (string, error)

ImportPath resolves the import path.

type GoImport

type GoImport struct {
	File *GoFile
	Doc  string
	Name string
	Path string
}

GoImport represents a import of a package

func (*GoImport) Prefix

func (g *GoImport) Prefix() string

Prefix is for an import - guess what prefix will be used in type declarations. For examples:

"strings" -> "strings"
"net/http/httptest" -> "httptest"

Libraries where the package name does not match will be mis-identified.

type GoInterface

type GoInterface struct {
	File     *GoFile
	Doc      string
	Decl     string
	FullDecl string
	Name     string
	Exported bool
	Methods  []*GoMethod
}

GoInterface specifies a interface definition

type GoMethod

type GoMethod struct {
	File     *GoFile
	Name     string
	Doc      string
	Decl     string
	FullDecl string
	Exported bool
	Params   []*GoType
	Results  []*GoType
}

GoMethod is a method on a struct, custom type, interface or just plain function

type GoModule

type GoModule struct {
	// File is the actual parsed go.mod file
	File *modfile.File
	// FilePath is the filepath to the go module
	FilePath string
	// Base is where all other packages are relative to.
	//
	// This is usually the directory to the File field since
	// go.mod is usually in root project folder.
	Base string
	// Name of the module e.g. github.com/alanconway/goasciidoc
	Name string
	// Version of this module
	Version string
	// GoVersion specifies the required go version
	GoVersion string
	// UnresolvedDecl contains all unresolved declarations.
	Unresolved []UnresolvedDecl
}

GoModule is a simple representation of a go.mod

func NewModule

func NewModule(path string) (*GoModule, error)

NewModule creates a new module from go.mod pointed out in the in param path parameter.

func NewModuleFromBuff

func NewModuleFromBuff(path string, buff []byte) (*GoModule, error)

NewModuleFromBuff creates a new module from the buff specified in the buff parameter and states that the buff is read from path.

func (*GoModule) AddUnresolvedDeclaration

func (gm *GoModule) AddUnresolvedDeclaration(u UnresolvedDecl) *GoModule

func (*GoModule) ResolvePackage

func (gm *GoModule) ResolvePackage(path string) string

ResolvePackage wil try to resolve the full package path bases on this module and the provided path.

If it fails, it returns an empty string.

type GoPackage

type GoPackage struct {
	GoFile
	// Files are all files in current package.
	Files []*GoFile
}

GoPackage is a aggregation of all GoFiles in a single package for ease of access.

type GoStruct

type GoStruct struct {
	File     *GoFile
	Doc      string
	Decl     string
	FullDecl string
	Name     string
	Exported bool
	Fields   []*GoField
}

GoStruct represents a struct

type GoStructMethod

type GoStructMethod struct {
	GoMethod
	Receivers []string
}

GoStructMethod is a GoMethod but has receivers and is positioned on a struct or custom type.

type GoTag

type GoTag struct {
	File  *GoFile
	Field *GoField
	Value string
}

GoTag is a tag on a struct field

func (*GoTag) Get

func (g *GoTag) Get(key string) string

Get returns a struct tag with the specified name e.g. json

type GoType

type GoType struct {
	File       *GoFile
	Name       string
	Type       string
	Underlying string
	Exported   bool
	Inner      []*GoType
}

GoType represents a go type such as a array, map, custom type etc.

type ParseConfig

type ParseConfig struct {
	// Test denotes if test files (ending with _test.go) should be included or not
	// (default not included)
	Test bool // <1>
	// Internal determines if internal folders are included or not (default not)
	Internal bool
	// UnderScore, when set to true it will include directories beginning with _
	UnderScore bool
	// Optional module to resolve fully qualified package paths
	Module *GoModule // <2>
}

ParseConfig to use when invoking ParseAny, ParseSingleFileWalker, and ParseSinglePackageWalker.

.ParserConfig [source,go] ---- include::${gad:current:fq}[tag=parse-config,indent=0] ---- <1> These are usually excluded since many testcases is not documented anyhow <2> As of _go 1.16_ it is recommended to *only* use module based parsing tag::parse-config[]

type ParseSingleFileWalkerFunc

type ParseSingleFileWalkerFunc func(*GoFile) error

ParseSingleFileWalkerFunc is used in conjunction with ParseSingleFileWalker.

If the ParseSingleFileWalker is returning an error, parsing will immediately stop and the error is returned.

type ParseSinglePackageWalkerFunc

type ParseSinglePackageWalkerFunc func(*GoPackage) error

ParseSinglePackageWalkerFunc is used in conjunction with ParseSinglePackageWalker.

If the ParseSinglePackageWalker is returning an error, parsing will immediately stop and the error is returned.

type Resolver

type Resolver interface {
}

Resolver pure purpose is to resolve `GoFile`, `GoStructMethod` to `GoTag` and all other types in between.

func NewResolver

func NewResolver(config ParseConfig, filepath string) Resolver

NewResolver creates a new `Resolver` from the filepath to the _go.mod_ file or directory where _go.mod_ resides.

type ResolverImpl

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

ResolverImpl is the implementation of a `Resolver` where it operarates on a `GoModule` level.

func (*ResolverImpl) LoadAll

func (r *ResolverImpl) LoadAll() error

type UnresolvedDecl

type UnresolvedDecl struct {
	Expr    ast.Expr
	Message string
}