goutil

package module
v0.0.0-...-dad8208 Latest Latest
Warning

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

 Go to latest Published: Nov 7, 2015 License: BSD-2-Clause Imports: 18 Imported by: 2

README

#goutil GoDoc Package goutil is a collection of utilities for working with the go/* packages and the go tool.

Download:

go get github.com/jimmyfrasche/goutil

Package goutil is a collection of utilities for working with the go/* packages and the go tool.

Goutil makes it easier to find, parse, and analyze Go code. It also enables easy use of the go tool for running generated code and creating executables from it. There are many miscellaneous utilities for easing the use of the go/* packages.

DocParse has been extracted from the go/doc package as this functionality is not exported.

##Importing There are five ways to import packages with goutil: Import, ImportTree, ImportAll, ImportRec, and the ImportDeps method on *Package. The latter are wrappers around Import for common tasks. Import's documentation applies to all of them, unless otherwise specified.

Imported packages are cached with a pointer to its build.Context as part of the key. The same pointer is also stored on each Package. This means you should never modify a build.Context after using it with this library. If the ctx parameter to any Import function is nil, a pointer to the go/build default context is used.

##Packages A *Package always has its go/build Context and Package set. It has methods to parse the files designated by its build.Package with go/ast and go/doc.

With the exception of Import, the other Import functions all return Packages, a []*Package with methods for filter and map applications.

Some methods of Package and Packages require that certain parsing actions be taken first, but these are always documented.

##Gostrap Gostrap is a utility for running the go(1) command in a temporary directory.

#Bugs

  • Tag parser does not handle invalid build tag sequence ,,

Automatically generated by autoreadme on 2015.11.06

Documentation

Overview

Package goutil is a collection of utilities for working with the go/* packages and the go tool.

Goutil makes it easier to find, parse, and analyze Go code. It also enables easy use of the go tool for running generated code and creating executables from it. There are many miscellaneous utilities for easing the use of the go/* packages.

DocParse has been extracted from the go/doc package as this functionality is not exported.

Importing

There are five ways to import packages with goutil: Import, ImportTree, ImportAll, ImportRec, and the ImportDeps method on *Package. The latter are wrappers around Import for common tasks. Import's documentation applies to all of them, unless otherwise specified.

Imported packages are cached with a pointer to its build.Context as part of the key. The same pointer is also stored on each Package. This means you should never modify a build.Context after using it with this library. If the ctx parameter to any Import function is nil, a pointer to the go/build default context is used.

Packages

A *Package always has its go/build Context and Package set. It has methods to parse the files designated by its build.Package with go/ast and go/doc.

With the exception of Import, the other Import functions all return Packages, a []*Package with methods for filter and map applications.

Some methods of Package and Packages require that certain parsing actions be taken first, but these are always documented.

Gostrap

Gostrap is a utility for running the go(1) command in a temporary directory.

Index

Constants

View Source 
const (
	//Para marks a block as a paragraph.
	Para op = iota
	//Head mars a block as a heading.
	Head
	//Pre marks a block as pre-formatted text, ie code.
	Pre
)

Variables

This section is empty.

Functions

func Context 

func Context(tags ...string) *build.Context

Context returns a *build.Context with the appropriate tags.

This does not change GOARCH or GOOS, it only sets additional tags.

If no tags are specified, the default context is returned.

func Install 

func Install(name, location string, file []byte, tags ...string) error

Install calls go install on a single input file, with optional build tags, in a Gostrap that's created on the fly and destroyed after.

func Run 

func Run(file []byte, tags ...string) error

Run calls go run on a single input file, with optional build tags, in a Gostrap that's created on the fly and destroyed after.

func TagsOf 

func TagsOf(c *build.Context) []string

TagsOf returns the complete build tag specification of a build.Context.

func ToImport 

func ToImport(path string) (root, imp string, err error)

ToImport takes an arbitrary path and returns a valid import path using $GOPATH. Returns which $GOPATH and the import path.

ToImport iterates $GOPATH in the order it's defined and always returns the first match.

Works correctly with imports in the Go root.

Does not handle the special glob ... (see ImportTree).

ToImport handles relative paths and "." The empty string is treated the same as "."

func WithGostrap 

func WithGostrap(f func(*Gostrap) error) error

WithGostrap creates a new Gostrap, calls Chdir, and defers calls to PopDir and Destroy, in the appropriate order, before invoking f.

Types

type Block 

type Block struct {
	Kind  op
	Lines []string
}

A Block is a section of documentation parsed in the godoc format. Each block is either a paragraph (Para), a header (Head), or section of pre-formatted text (Pre), most likely code.

func DocParse 

func DocParse(text string) []Block

DocParse takes text blocks from comments (from go/doc) and parses it into an intermediary format so that it may be formatted as desired.

type Decls 

type Decls []ast.Decl

Decls is a list ast.Decls.

func (Decls) Consts 

func (ds Decls) Consts() Decls

Consts returns a Decls filtered to just *ast.GenDecl containing consts.

func (Decls) Funcs 

func (ds Decls) Funcs() (out Decls)

Funcs returns a Decls filtered to just *ast.FuncDecl

func (Decls) Named 

func (ds Decls) Named(m StringMatcher) (out Decls)

Named returns all Decls whose name matches r.

If you haven't called SplitSpecs, a GenDecl will be returned if any of its Spec's match.

func (Decls) SplitSpecs 

func (ds Decls) SplitSpecs() (out Decls)

SplitSpecs goes throught each *ast.GenDecl and duplicates the outer GenDecl for each item in the spec. This destroys information but does make it easier to search, and is required for invoking Named on GenDecls.

Note that SplitSpecs does not, and in general cannot sensibly, split 

var a, b, c = f()

though it does split 

var a, b, c = 1, 2, 3

as one would hope.

func (Decls) Types 

func (ds Decls) Types() Decls

Types returns a Decls filtered to just *ast.GenDecl containing types.

func (Decls) Vars 

func (ds Decls) Vars() Decls

Vars returns a Decls filtered to just *ast.GenDecl containing vars.

type Gostrap 

type Gostrap struct {
	*exec.Cmd
	// contains filtered or unexported fields
}

Gostrap creates a temporary environment to run the go(1) tool in.

It embeds an exec.Cmd configured to run the go tool in this environment.

func NewGostrap 

func NewGostrap() (*Gostrap, error)

NewGostrap creates a new Gostrap.

The embedded exec.Cmd still needs the tool (ie, run, install, etc) and its arguments appended to its Args list. It defaults to using os.Stdout and os.Stderr for the Stdout and Stderr of the Cmd, respectively.

You should investigate Run and Install first, as they are likely what you need, and if not their source, and WithGostrap's, show how Gostrap is used.

func (*Gostrap) AddFile 

func (t *Gostrap) AddFile(name string, contents []byte) error

AddFile creates a file in the temp location.

func (*Gostrap) Chdir 

func (t *Gostrap) Chdir() error

Chdir makes the temp location the current working directory. It saves the current directory so this can be undone with Popdir.

func (*Gostrap) Destroy 

func (t *Gostrap) Destroy()

Destroy the Gostrap and everything in it and everything it loves.

func (*Gostrap) JoinPath 

func (t *Gostrap) JoinPath(path ...string) string

JoinPath joins path to the temp directory.

func (*Gostrap) Popdir 

func (t *Gostrap) Popdir() error

Popdir returns the working directory to what it was before Chdir was called.

type Package 

type Package struct {
	//The context this Package was imported with.
	Context *build.Context
	Build   *build.Package
	AST     *ast.Package
	FileSet *token.FileSet //The FileSet AST was parsed with.
	Doc     *doc.Package
	// contains filtered or unexported fields
}

Package wraps all the common go/* Package types and provides some additional functionality.

All methods of package assume that the Package was created by either Import or ImportAll and hence that Build is nonnil.

func Import 

func Import(ctx *build.Context, path string) (*Package, error)

Import imports a package.

path is run through ToImport.

If ctx is nil, the default context is used.

N.B. we require a pointer to a build.Context for caching. Two build contexts with identical values that are not represented by the same pointer will have all packages imported by them cached separately.

func (*Package) ASTFilesMatching 

func (p *Package) ASTFilesMatching(tags ...string) (files []*ast.File)

ASTFilesMatching calls FilesMatching and looks up the resulting files in p.AST.Files.

It is the callers responsibility to call Parse and ParseTags before invoking this method.

func (*Package) Decls 

func (p *Package) Decls() (ds Decls)

Decls returns every ast.Decl in a package that is not a BadDecl or an IMPORT.

It is up to the caller to call Parse before invoking this method.

func (*Package) FilesMatching 

func (p *Package) FilesMatching(tags ...string) (files []string)

FilesMatching returns the sublist of Build.GoFiles matching the specified build tags.

It is the users responsibility to call ParseTags before invoking this method.

func (*Package) ImportDeps 

func (p *Package) ImportDeps() (pkgs Packages, err error)

ImportDeps imports all dependencies of this package recursively.

It uses the same build.Context this Package was built with.

func (*Package) Parse 

func (p *Package) Parse(parseComments bool) error

Parse the package and set p.AST.

It is not necessary to call with parseComments if you intend to call ParseDocs, as ParseDocs creates its own parse.

func (*Package) ParseDocs 

func (p *Package) ParseDocs(mode doc.Mode) error

ParseDocs parses the Package's documentation with go/doc.

If you do not need a particular doc.Mode call this with 0.

If the package directory contains a file of package documentation (and the package is not itself named documentation), it is parsed and its doc.Package.Doc string replaces the string generated by the package itself.

Note that the go/doc package munges the AST so this method parses the AST again, regardless of the value in p.AST. As a consequence, it is valid to call this even if you have not called the Parse method or if you have called the Parse method and told it not to parse comments.

func (*Package) ParseTags 

func (p *Package) ParseTags() error

ParseTags parses the build tags for each file in Build.GoFiles.

ParseTags uses its own parser so it is not necessary to call Parse before calling ParseTags.

type Packages 

type Packages []*Package

Packages is a list of *Package, with methods for filtering and manipulating en masse.

func ImportAll 

func ImportAll(ctx *build.Context) (pkgs Packages, first error)

ImportAll imports every package from the standard library and every $GOPATH.

If there are any errors, the first is returned and as many packages as can be imported are returned.

func ImportRec 

func ImportRec(ctx *build.Context, path string) (Packages, error)

ImportRec calls Import on path and then ImportDeps and returns all packages with the package described by path as the first element.

func ImportTree 

func ImportTree(ctx *build.Context, root string) (pkgs Packages, first error)

ImportTree imports every package in the directory tree rooted at root. Root need not have a valid package.

If there are any errors, the first is returned and as many packages as can be imported are returned.

func (Packages) Filter 

func (ps Packages) Filter(f func(*Package) bool) (out Packages)

Filter returns a sublist of packages that match the predicate f.

If the predicate requires the Packages to be parsed or have their docs parsed, it is up to the user to ensure that these steps have been done first.

func (Packages) HasFilesMatching 

func (ps Packages) HasFilesMatching(tags ...string) Packages

HasFilesMatching returns all packages that have at least one file matching the specified build tags.

HasFilesMatching requires that ParseTags has been invoked.

func (Packages) Imports 

func (ps Packages) Imports() (out []string)

Imports return the set of imports in the packages, in no particular order.

func (Packages) NoStdlib 

func (ps Packages) NoStdlib() Packages

NoStdlib filters out packages from GOROOT.

This only relies on information in Build, so it is safe to call if the packages have not been parsed.

func (Packages) Parse 

func (ps Packages) Parse(parseComments bool) (err error)

Parse parses each package in turn.

Parse stops and returns the first error it encounters.

func (Packages) ParseDocs 

func (ps Packages) ParseDocs(mode doc.Mode) (err error)

ParseDocs parses each package's documentation in turn.

ParseDocs stops and returns the first error it encounters.

func (Packages) ParseTags 

func (ps Packages) ParseTags() (err error)

ParseTags parses each package's build tags in turn.

ParseTags stops and returns the first error it encounters.

func (Packages) Uniq 

func (ps Packages) Uniq() (out Packages)

Uniq takes a list of Packages and filters out duplicates ONLY by import path.

type PrefixMatcher 

type PrefixMatcher string

PrefixMatcher matches all strings with specified prefix.

func (PrefixMatcher) MatchString 

func (p PrefixMatcher) MatchString(s string) bool

MatchString matches strings with the prefix set

type StringMatcher 

type StringMatcher interface {
	MatchString(string) bool
}

StringMatcher matches strings.

The interface is extracted from regexp.Regexp.

Notes

Bugs

  • Tag parser does not handle invalid build tag sequence ,,

Source Files

View all Source files

Directories

Path Synopsis
Declgrep greps just the declarations, exported and unexported, excluding import declarations, of a given Go package, or set of Go packages, with the standard build tags.
 Declgrep greps just the declarations, exported and unexported, excluding import declarations, of a given Go package, or set of Go packages, with the standard build tags.
Package gocli implements common idioms for handling Go packages in command line programs.
 Package gocli implements common idioms for handling Go packages in command line programs.

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.