modfile

Documentation

Overview

Package modfile implements parsing and formatting for go.mod files.

Index

• func AutoQuote(s string) string
• func Format(f *FileSyntax) []byte
• func IsDirectoryPath(ns string) bool
• func ModulePath(mod []byte) string
• func MustQuote(s string) bool
• func ParseGopkgIn(path string) (root, repo, major, subdir string, ok bool)
• type Comment
• type CommentBlock
  • func (x *CommentBlock) Span() (start, end Position)
• type Comments
  • func (c *Comments) Comment() *Comments
• type Exclude
• type Expr
• type File
  • func Parse(file string, data []byte, fix VersionFixer) (*File, error)
  • func ParseLax(file string, data []byte, fix VersionFixer) (*File, error)
  • func (f *File) AddComment(text string)
  • func (f *File) AddExclude(path, vers string) error
  • func (f *File) AddModuleStmt(path string) error
  • func (f *File) AddNewRequire(path, vers string, indirect bool)
  • func (f *File) AddReplace(oldPath, oldVers, newPath, newVers string) error
  • func (f *File) AddRequire(path, vers string) error
  • func (f *File) Cleanup()
  • func (f *File) DropExclude(path, vers string) error
  • func (f *File) DropReplace(oldPath, oldVers string) error
  • func (f *File) DropRequire(path string) error
  • func (f *File) Format() ([]byte, error)
  • func (f *File) SetRequire(req []*Require)
  • func (f *File) SortBlocks()
• type FileSyntax
  • func (x *FileSyntax) Cleanup()
  • func (x *FileSyntax) Span() (start, end Position)
• type Go
• type LParen
  • func (x *LParen) Span() (start, end Position)
• type Line
  • func (x *Line) Span() (start, end Position)
• type LineBlock
  • func (x *LineBlock) Span() (start, end Position)
• type Module
• type Position
• type RParen
  • func (x *RParen) Span() (start, end Position)
• type Replace
• type Require
• type VersionFixer

Functions

func AutoQuote

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

func Format(f *FileSyntax) []byte

func IsDirectoryPath

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

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

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.

func ParseGopkgIn

func ParseGopkgIn(path string) (root, repo, major, subdir string, ok bool)

ParseGopkgIn splits gopkg.in import paths into their constituent parts

Types

type Comment

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

type CommentBlock struct {
	Comments
	Start Position
}

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

func (*CommentBlock) Span

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

type Comments

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

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 Exclude

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

An Exclude is a single exclude statement.

type Expr

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

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

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

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

func (f *File) AddComment(text string)

func (*File) AddExclude

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

func (*File) AddModuleStmt

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

func (*File) AddNewRequire

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

func (*File) AddReplace

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

func (*File) AddRequire

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

func (*File) Cleanup

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

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

func (*File) DropReplace

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

func (*File) DropRequire

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

func (*File) Format

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

func (*File) SetRequire

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

func (*File) SortBlocks

func (f *File) SortBlocks()

type FileSyntax

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

A FileSyntax represents an entire go.mod file.

func (*FileSyntax) Cleanup

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

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

type Go

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

A Go is the go statement.

type LParen

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

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

type Line

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

A Line is a single line of tokens.

func (*Line) Span

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

type LineBlock

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

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

type Module

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

A Module is the module statement.

type Position

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 the position between two bytes of input.

type RParen

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

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

type Replace

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

A Replace is a single replace statement.

type Require

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

A Require is a single require statement.

type VersionFixer

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