pkgdmp

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2023 License: MIT Imports: 10 Imported by: 0

README

pkgdmp - Go code analysis tool

Screenshot of pkgdmp analyzing its own code


pkgdmp is a simple command-line tool for analyzing directories containing Go code. It provides an overview of functions, structs, methods, function types, and interfaces defined in the packages within those directories.

Note Please be aware that this project is a work in progress, and it may contain bugs or unexpected behavior. Additionally, both the CLI and the package API can get breaking changes while the version is below 1.0.0

Features:

  • Customizable output options
  • Entity filtering using patterns
  • Multiple syntax highlighting themes
  • JSON output generation

Todo:

  • Implement parsing and printing of const.
  • Implement parsing and printing of var.

Usage

user@example:~$ pkgdmp -help

pkgdmp v0.2.0

USAGE:

  pkgdmp [FLAGS] DIRECTORY [DIRECTORY2] ...

FLAGS:

  -exclude string
        comma-separated list of symbol types to exclude [$PKGDMP_EXCLUDE]
  -exclude-matching string
        exclude symbols with names matching regular expression [$PKGDMP_EXCLUDE_MATCHING]
  -exclude-packages string
        comma-separated list of package names to exclude [$PKGDMP_EXCLUDE_PACKAGES]
  -full-docs
        include full doc comments instead of synopsis [$PKGDMP_FULL_DOCS]
  -json
        output as JSON [$PKGDMP_JSON]
  -matching string
        only include symbol with names matching regular expression [$PKGDMP_MATCHING]
  -no-docs
        exclude doc comments [$PKGDMP_NO_DOCS]
  -no-env
        skip loading of configuration from 'PKGDMP_*' environment variables
  -only string
        comma-separated list of symbol types to include [$PKGDMP_ONLY]
  -only-packages string
        comma-separated list of package names to include [$PKGDMP_ONLY_PACKAGES]
  -theme string
        syntax highlighting theme to use - see https://xyproto.github.io/splash/docs/ [$PKGDMP_THEME] (default "swapoff")
  -unexported
        include unexported entities [$PKGDMP_UNEXPORTED]
  -version
        print version information and exit

SYMBOL TYPES:

  arrayType, chanType, const, func, funcType, identType, interface, mapType, struct

Examples

Analyze the contents of the myproject directory and display all exported entities:

user@example:~$ pkgdmp myproject
package mypackage

// An ugly const declaration group to check that parser handles different
// scenarios correctly.
const (
        MyStringConst, MyUint32Const, MyIntConst         = "hello", uint32(123), 42
        MyFloatConst                                     = 1.234
        MyFloat32Const                           float32 = 4.321
)

const MyInitConst int

// MySingleConst checks that parser handles a single const declaration
// correctly.
const MySingleConst = "example"

// Check that parser handles this common const declaration method correctly.
const (
        MyFatal MyLogLevel = iota
        MyError
        MyWarn
        MyInfo
        MyDebug
)
. . .

Analyze the myproject directory, excluding entities matching pattern and displaying full documentation comments in JSON format:

user@example:~$ pkgdmp -exclude-matching "^My.*Function$" -full-docs -json myproject
[
  {
    "name": "mypackage",
    "consts": [
      {
        "doc": "An ugly const declaration group to check that parser handles different\nscenarios correctly.",
        "consts": [
          {
            "names": [
              "MyStringConst",
              "MyUint32Const",
              "MyIntConst"
            ],
            "values": [
              {
                "value": "\"hello\"",
                "type": "string"
              },
              {
                "value": "123",
                "type": "uint32",
                "specific": true
              },
              {
                "value": "42",
                "type": "int"
              }
            ]
          },
          {
            "names": [
              "MyFloatConst"
. . .

Installation

Grab a pre-compiled version from the release page or install the latest version with Go:

user@example:~$ go install github.com/michenriksen/pkgdmp@latest

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Const added in v0.2.0 

type Const struct {
	Doc    string   `json:"doc,omitempty"`
	Names  []string `json:"names"`
	Values []Value  `json:"values"`
	// contains filtered or unexported fields
}

Const represents a single const declaration.

func (Const) Ident added in v0.2.0 

func (c Const) Ident() string

Ident returns the first name.

func (Const) IsExported added in v0.2.0 

func (c Const) IsExported() bool

IsExported returns true if the first name is exported.

func (Const) Print added in v0.2.0 

func (c Const) Print(w io.Writer)

Print writes the unformatted const declaration code fragment to writer.

func (Const) String added in v0.2.0 

func (c Const) String() string

String returns the unformatted const declaration code fragment.

func (Const) SymbolType added in v0.2.0 

func (Const) SymbolType() SymbolType

SymbolType returns SymbolConst.

type ConstGroup added in v0.2.0 

type ConstGroup struct {
	Doc    string  `json:"doc,omitempty"`
	Consts []Const `json:"consts"`
}

ConstGroup represents one or more const declarations.

func (ConstGroup) Print added in v0.2.0 

func (cg ConstGroup) Print(w io.Writer)

Print writes unformatted const declaration code to writer.

func (ConstGroup) String added in v0.2.0 

func (cg ConstGroup) String() string

String returns the unformatted const declaration code.

type Field added in v0.1.1 

type Field struct {
	Type    string     `json:"type"`
	Doc     string     `json:"doc,omitempty"`
	Comment string     `json:"comment,omitempty"`
	Names   []string   `json:"names,omitempty"`
	Tags    []FieldTag `json:"tags,omitempty"`
	// contains filtered or unexported fields
}

Field represents a function parameter, result, or struct field.

func (Field) Ident added in v0.1.1 

func (sf Field) Ident() string

Ident returns the name of the field.

func (Field) IsExported added in v0.1.1 

func (sf Field) IsExported() bool

IsExported returns true if the field is exported.

func (Field) Print added in v0.1.1 

func (sf Field) Print(w io.Writer)

Print writes unformatted field code fragment to writer.

func (Field) String added in v0.1.1 

func (sf Field) String() string

String returns the unformatted field code fragment.

func (Field) SymbolType added in v0.2.0 

func (sf Field) SymbolType() SymbolType

SymbolType returns either SymbolStructField, SymbolParamField, or SymbolResultField.

type FieldTag added in v0.3.0 

type FieldTag struct {
	Name   string
	Values []string
}

FieldTag represents a struct field tag.

func (FieldTag) Print added in v0.3.0 

func (ft FieldTag) Print(w io.Writer)

Print writes the unformatted field tag code fragment to writer.

func (FieldTag) String added in v0.3.0 

func (ft FieldTag) String() string

String returns the unformatted field tag code fragment.

type FilterAction added in v0.2.0 

type FilterAction int

FilterAction configures a [SymbolFilterFn]. 

const (
	Exclude FilterAction = iota // Exclude symbols.
	Include                     // Include symbols.
)

func (FilterAction) GoString added in v0.2.0 

func (fa FilterAction) GoString() string

func (FilterAction) String added in v0.2.0 

func (fa FilterAction) String() string

String returns a string representation of a filter action.

type Func 

type Func struct {
	Receiver *Field  `json:"receiver,omitempty"`
	Name     string  `json:"name"`
	Doc      string  `json:"doc,omitempty"`
	Comment  string  `json:"comment,omitempty"`
	Params   []Field `json:"params,omitempty"`
	Results  []Field `json:"results,omitempty"`
	// contains filtered or unexported fields
}

Func represents a function or a struct method if the Receiver field contains a pointer to a [FuncReceiver].

func (Func) Ident 

func (f Func) Ident() string

Ident returns the function's name.

func (Func) IsExported 

func (f Func) IsExported() bool

IsExported returns true if the function is exported.

func (Func) Print added in v0.1.1 

func (f Func) Print(w io.Writer)

Print writes unformatted function signature code to writer.

func (Func) String 

func (f Func) String() string

String returns the function signature code.

func (Func) SymbolType added in v0.2.0 

func (f Func) SymbolType() SymbolType

SymbolType returns SymbolFunc or SymbolMethod.

type Package 

type Package struct {
	Name   string       `json:"name"`
	Doc    string       `json:"doc,omitempty"`
	Consts []ConstGroup `json:"consts,omitempty"`
	Funcs  []Func       `json:"funcs,omitempty"`
	Types  []TypeDef    `json:"types,omitempty"`
}

Package represents a go package containing functions and types such as structs and interfaces.

func (*Package) Ident added in v0.2.0 

func (p *Package) Ident() string

Ident returns the package name.

func (*Package) IsExported added in v0.2.0 

func (*Package) IsExported() bool

IsExported always returns true for packages.

func (*Package) Print added in v0.1.1 

func (p *Package) Print(w io.Writer)

Print writes unformatted package code to writer.

func (*Package) Source 

func (p *Package) Source() (string, error)

Source returns the formatted package signature source.

func (*Package) String 

func (p *Package) String() string

String returns the unformatted package signature code.

func (*Package) SymbolType added in v0.2.0 

func (*Package) SymbolType() SymbolType

SymbolType returns SymbolPackage.

type Parser 

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

Parser parses go packages to simple structs.

func NewParser 

func NewParser(opts ...ParserOption) (*Parser, error)

NewParser returns a parser configured with options.

func (*Parser) Package 

func (p *Parser) Package(dPkg *doc.Package) (*Package, error)

Package parses dPkg to a simplified Package.

type ParserOption added in v0.2.0 

type ParserOption interface {
	// String should return a string representation of the option.
	//
	// This method is mainly intended for testing purposes.
	String() string
	// contains filtered or unexported methods
}

ParserOption configures a Parser.

func WithFullDocs added in v0.2.0 

func WithFullDocs() ParserOption

WithFullDocs configures a Parser to include full doc comments instead of short synopsis comments.

func WithNoDocs added in v0.2.0 

func WithNoDocs() ParserOption

WithNoDocs configures a Parser to not include any doc comments for symbols.

func WithNoTags added in v0.3.0 

func WithNoTags() ParserOption

WithNoDocs configures a Parser to not include any struct field tags.

func WithSymbolFilters added in v0.2.0 

func WithSymbolFilters(filters ...SymbolFilter) ParserOption

WithSymbolFilters configures a Parser to filter package symbols with provided filter functions.

type Symbol added in v0.2.0 

type Symbol interface {
	Ident() string
	IsExported() bool
	SymbolType() SymbolType
}

Symbol represents a symbol such as a const, type definition, or function.

type SymbolFilter added in v0.2.0 

type SymbolFilter interface {
	// Include should return true if symbol should be included according to
	// the filter's logic and configuration.
	Include(Symbol) bool

	// String should return a string representation of the filter.
	//
	// This method is mainly intended for testing purposes.
	String() string
}

SymbolFilter filters symbols by different conditions.

func FilterMatchingIdents added in v0.2.0 

func FilterMatchingIdents(action FilterAction, p *regexp.Regexp) SymbolFilter

FilterSymbolTypes creates a filter function that determines whether to include or exclude symbols with matching idents.

func FilterSymbolTypes added in v0.2.0 

func FilterSymbolTypes(action FilterAction, types ...SymbolType) SymbolFilter

FilterSymbolTypes creates a filter function that determines whether to include or exclude symbols of different types.

func FilterUnexported added in v0.2.0 

func FilterUnexported(action FilterAction) SymbolFilter

FilterUnexported creates a filter that determines whether to include or exclude unexported symbols.

type SymbolType added in v0.2.0 

type SymbolType int

SymbolType represents a type of package symbol. 

const (
	SymbolUnknown       SymbolType = iota
	SymbolPackage                  // `package mypackage`
	SymbolConst                    // `const myConst = ...`
	SymbolIdentType                // `type MyInt int`
	SymbolFuncType                 // `type MyFunc func(...)`
	SymbolStructType               // `type MyStruct { ... }`
	SymbolInterfaceType            // `type MyInterface { ... }`
	SymbolMapType                  // `type MyMap map[...]...`
	SymbolChanType                 // `type MyChan chan ...`
	SymbolArrayType                // `type MyArray []string`
	SymbolFunc                     // `func MyFunc(...) { ... }`
	SymbolMethod                   // `func (...) MyMethod(...) { ... }`
	SymbolStructField              // Struct field.
	SymbolParamField               // Function parameter field.
	SymbolResultField              // Function result field.
	SymbolReceiverField            // Function Receiver field.
)

func (SymbolType) GoString added in v0.2.0 

func (st SymbolType) GoString() string

func (SymbolType) String added in v0.2.0 

func (st SymbolType) String() string

String returns a string representation of a symbol type.

type TypeDef added in v0.1.1 

type TypeDef struct {
	Type    string  `json:"type"`
	Name    string  `json:"name"`
	Doc     string  `json:"doc,omitempty"`
	Key     string  `json:"key,omitempty"`
	Value   string  `json:"value,omitempty"`
	Dir     string  `json:"dir,omitempty"`
	Elt     string  `json:"elt,omitempty"`
	Len     string  `json:"len,omitempty"`
	Params  []Field `json:"params,omitempty"`
	Results []Field `json:"results,omitempty"`
	Fields  []Field `json:"fields,omitempty"`
	Methods []Func  `json:"methods,omitempty"`
}

TypeDef represents a type definition.

func (TypeDef) Ident added in v0.1.1 

func (td TypeDef) Ident() string

Ident returns the type definition's name.

func (TypeDef) IsExported added in v0.1.1 

func (td TypeDef) IsExported() bool

IsExported returns true if the type definition is exported.

func (TypeDef) Print added in v0.1.1 

func (td TypeDef) Print(w io.Writer)

Print writes unformatted type definition code to writer.

func (TypeDef) String added in v0.1.1 

func (td TypeDef) String() string

String returns the type definition code.

func (TypeDef) SymbolType added in v0.2.0 

func (td TypeDef) SymbolType() SymbolType

SymbolType returns the type definition's symbol type.

type Value added in v0.2.0 

type Value struct {
	Value    string `json:"value,omitempty"`
	Type     string `json:"type"`
	Specific bool   `json:"specific,omitempty"`
}

Value represents a value in a Const declaration.

Source Files

View all Source files

Directories

Path Synopsis
cmd
pkgdmp
internal
cli

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.