Documentation

Overview

    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

    Constants

    This section is empty.

    Variables

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

    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

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

        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.

              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 Error

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

                      func (*Error) Error

                      func (e *Error) Error() string

                      func (*Error) Unwrap

                      func (e *Error) Unwrap() error

                      type ErrorList

                      type ErrorList []Error

                      func (ErrorList) Error

                      func (e ErrorList) Error() string

                      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
                          	Retract []*Retract
                          
                          	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

                                  AddExclude adds a exclude statement to the mod file. Errors if the provided version is not a canonical version string

                                  func (*File) AddGoStmt

                                  func (f *File) AddGoStmt(version 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) AddRetract

                                  func (f *File) AddRetract(vi VersionInterval, rationale string) error

                                    AddRetract adds a retract statement to the mod file. Errors if the provided version interval does not consist of canonical version strings

                                    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) DropRetract

                                      func (f *File) DropRetract(vi VersionInterval) 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 an arbitrary source position in a file, including the file, line, column, and byte offset.

                                                      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 Retract

                                                            type Retract struct {
                                                            	VersionInterval
                                                            	Rationale string
                                                            	Syntax    *Line
                                                            }

                                                              A Retract is a single retract statement.

                                                              type VersionFixer

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

                                                              type VersionInterval

                                                              type VersionInterval struct {
                                                              	Low, High string
                                                              }

                                                                A VersionInterval represents a range of versions with upper and lower bounds. Intervals are closed: both bounds are included. When Low is equal to High, the interval may refer to a single version ('v1.2.3') or an interval ('[v1.2.3, v1.2.3]'); both have the same representation.