mod: golang.org/x/mod/modfile Index | Files

package modfile

import "golang.org/x/mod/modfile"

Package modfile implements a parser and formatter for go.mod files.

The go.mod syntax is described in https://golang.org/cmd/go/#hdr-The_go_mod_file.

The Parse and ParseLax functions both parse a go.mod file and return an abstract syntax tree. ParseLax ignores unknown statements and may be used to parse go.mod files that may have been developed with newer versions of Go.

The File struct returned by Parse and ParseLax represent an abstract go.mod file. File has several methods like AddNewRequire and DropReplace that can be used to programmatically edit a file.

The Format function formats a File back to a byte slice which can be written to a file.

Index

Package Files

print.go read.go rule.go

Variables

❖
var GoVersionRE = lazyregexp.New(`^([1-9][0-9]*)\.(0|[1-9][0-9]*)$`)

func AutoQuote Uses

❖
func AutoQuote(s string) string

AutoQuote returns s or, if quoting is required for s to appear in a go.mod, the quotation of s.

func Format Uses

❖
func Format(f *FileSyntax) []byte

Format returns a go.mod file as a byte slice, formatted in standard style.

func IsDirectoryPath Uses

❖
func IsDirectoryPath(ns string) bool

IsDirectoryPath reports whether the given path should be interpreted as a directory path. Just like on the go command line, relative paths and rooted paths are directory paths; the rest are module paths.

func ModulePath Uses

❖
func ModulePath(mod []byte) string

ModulePath returns the module path from the gomod file text. If it cannot find a module path, it returns an empty string. It is tolerant of unrelated problems in the go.mod file.

func MustQuote Uses

❖
func MustQuote(s string) bool

MustQuote reports whether s must be quoted in order to appear as a single token in a go.mod line.

type Comment Uses

❖
type Comment struct {
    Start  Position
    Token  string // without trailing newline
    Suffix bool   // an end of line (not whole line) comment
}

A Comment represents a single // comment.

type CommentBlock Uses

❖
type CommentBlock struct {
    Comments
    Start Position
}

A CommentBlock represents a top-level block of comments separate from any rule.

func (*CommentBlock) Span Uses

❖
func (x *CommentBlock) Span() (start, end Position)

type Comments Uses

❖
type Comments struct {
    Before []Comment // whole-line comments before this expression
    Suffix []Comment // end-of-line comments after this expression

    // For top-level expressions only, After lists whole-line
    // comments following the expression.
    After []Comment
}

Comments collects the comments associated with an expression.

func (*Comments) Comment Uses

❖
func (c *Comments) Comment() *Comments

Comment returns the receiver. This isn't useful by itself, but a Comments struct is embedded into all the expression implementation types, and this gives each of those a Comment method to satisfy the Expr interface.

type Error Uses

❖
type Error struct {
    Filename string
    Pos      Position
    Verb     string
    ModPath  string
    Err      error
}

func (*Error) Error Uses

❖
func (e *Error) Error() string

func (*Error) Unwrap Uses

❖
func (e *Error) Unwrap() error

type ErrorList Uses

❖
type ErrorList []Error

func (ErrorList) Error Uses

❖
func (e ErrorList) Error() string

type Exclude Uses

❖
type Exclude struct {
    Mod    module.Version
    Syntax *Line
}

An Exclude is a single exclude statement.

type Expr Uses

❖
type Expr interface {
    // Span returns the start and end position of the expression,
    // excluding leading or trailing comments.
    Span() (start, end Position)

    // Comment returns the comments attached to the expression.
    // This method would normally be named 'Comments' but that
    // would interfere with embedding a type of the same name.
    Comment() *Comments
}

An Expr represents an input element.

type File Uses

❖
type File struct {
    Module  *Module
    Go      *Go
    Require []*Require
    Exclude []*Exclude
    Replace []*Replace

    Syntax *FileSyntax
}

A File is the parsed, interpreted form of a go.mod file.

func Parse Uses

❖
func Parse(file string, data []byte, fix VersionFixer) (*File, error)

Parse parses the data, reported in errors as being from file, into a File struct. It applies fix, if non-nil, to canonicalize all module versions found.

func ParseLax Uses

❖
func ParseLax(file string, data []byte, fix VersionFixer) (*File, error)

ParseLax is like Parse but ignores unknown statements. It is used when parsing go.mod files other than the main module, under the theory that most statement types we add in the future will only apply in the main module, like exclude and replace, and so we get better gradual deployments if old go commands simply ignore those statements when found in go.mod files in dependencies.

func (*File) AddComment Uses

❖
func (f *File) AddComment(text string)

func (*File) AddExclude Uses

❖
func (f *File) AddExclude(path, vers string) error

func (*File) AddGoStmt Uses

❖
func (f *File) AddGoStmt(version string) error

func (*File) AddModuleStmt Uses

❖
func (f *File) AddModuleStmt(path string) error

func (*File) AddNewRequire Uses

❖
func (f *File) AddNewRequire(path, vers string, indirect bool)

func (*File) AddReplace Uses

❖
func (f *File) AddReplace(oldPath, oldVers, newPath, newVers string) error

func (*File) AddRequire Uses

❖
func (f *File) AddRequire(path, vers string) error

func (*File) Cleanup Uses

❖
func (f *File) Cleanup()

Cleanup cleans up the file f after any edit operations. To avoid quadratic behavior, modifications like DropRequire clear the entry but do not remove it from the slice. Cleanup cleans out all the cleared entries.

func (*File) DropExclude Uses

❖
func (f *File) DropExclude(path, vers string) error

func (*File) DropReplace Uses

❖
func (f *File) DropReplace(oldPath, oldVers string) error

func (*File) DropRequire Uses

❖
func (f *File) DropRequire(path string) error

func (*File) Format Uses

❖
func (f *File) Format() ([]byte, error)

func (*File) SetRequire Uses

❖
func (f *File) SetRequire(req []*Require)

func (*File) SortBlocks Uses

❖
func (f *File) SortBlocks()

type FileSyntax Uses

❖
type FileSyntax struct {
    Name string // file path
    Comments
    Stmt []Expr
}

A FileSyntax represents an entire go.mod file.

func (*FileSyntax) Cleanup Uses

❖
func (x *FileSyntax) Cleanup()

Cleanup cleans up the file syntax x after any edit operations. To avoid quadratic behavior, removeLine marks the line as dead by setting line.Token = nil but does not remove it from the slice in which it appears. After edits have all been indicated, calling Cleanup cleans out the dead lines.

func (*FileSyntax) Span Uses

❖
func (x *FileSyntax) Span() (start, end Position)

type Go Uses

❖
type Go struct {
    Version string // "1.23"
    Syntax  *Line
}

A Go is the go statement.

type LParen Uses

❖
type LParen struct {
    Comments
    Pos Position
}

An LParen represents the beginning of a parenthesized line block. It is a place to store suffix comments.

func (*LParen) Span Uses

❖
func (x *LParen) Span() (start, end Position)

type Line Uses

❖
type Line struct {
    Comments
    Start   Position
    Token   []string
    InBlock bool
    End     Position
}

A Line is a single line of tokens.

func (*Line) Span Uses

❖
func (x *Line) Span() (start, end Position)

type LineBlock Uses

❖
type LineBlock struct {
    Comments
    Start  Position
    LParen LParen
    Token  []string
    Line   []*Line
    RParen RParen
}

A LineBlock is a factored block of lines, like 

require (
	"x"
	"y"
)

func (*LineBlock) Span Uses

❖
func (x *LineBlock) Span() (start, end Position)

type Module Uses

❖
type Module struct {
    Mod    module.Version
    Syntax *Line
}

A Module is the module statement.

type Position Uses

❖
type Position struct {
    Line     int // line in input (starting at 1)
    LineRune int // rune in line (starting at 1)
    Byte     int // byte in input (starting at 0)
}

A Position describes an arbitrary source position in a file, including the file, line, column, and byte offset.

type RParen Uses

❖
type RParen struct {
    Comments
    Pos Position
}

An RParen represents the end of a parenthesized line block. It is a place to store whole-line (before) comments.

func (*RParen) Span Uses

❖
func (x *RParen) Span() (start, end Position)

type Replace Uses

❖
type Replace struct {
    Old    module.Version
    New    module.Version
    Syntax *Line
}

A Replace is a single replace statement.

type Require Uses

❖
type Require struct {
    Mod      module.Version
    Indirect bool // has "// indirect" comment
    Syntax   *Line
}

A Require is a single require statement.

type VersionFixer Uses

❖
type VersionFixer func(path, version string) (string, error)

Package modfile imports 12 packages (graph) and is imported by 40 packages. Updated 2020-02-26. Refresh now. Tools for package owners.