editorconfig

README

editorconfig

A small package to parse and use EditorConfig files. Currently passes all of the official test cases, which are run via go test.

props, err := editorconfig.Find("path/to/file.go")
if err != nil { ... }

// Print all the properties
fmt.Println(props)

// Query specific ones
fmt.Println(props.Get("indent_style"))
fmt.Println(props.IndentSize())

Note that an official library exists for Go. This alternative implementation started with a different design:

• Specialised INI parser, for full compatibility with the spec
• Ability to cache parsing files and compiling pattern matches
• Storing and querying all properties equally
• Minimising pointers and maps to store data

Documentation

Overview

Package editorconfig allows parsing and using EditorConfig files, as defined in https://editorconfig.org/.

Example

package main

import (
	"fmt"

	"mvdan.cc/editorconfig"
)

func main() {
	props, err := editorconfig.Find("_sample/subdir/code.go")
	if err != nil {
		panic(err)
	}
	fmt.Println(props)

	fmt.Println(props.Get("indent_style"))
	fmt.Println(props.IndentSize())
	fmt.Println(props.TrimTrailingWhitespace())
	fmt.Println(props.InsertFinalNewline())

}

Output:

indent_style=tab
indent_size=8
end_of_line=lf
insert_final_newline=true

tab
8
false
true

Index

• Constants
• type File
  • func Parse(r io.Reader) (*File, error)
  • func (f *File) Filter(name string, cache map[string]*regexp.Regexp) Section
  • func (f *File) String() string
• type Property
  • func (p Property) String() string
• type Query
  • func (q Query) Find(name string) (Section, error)
• type Section
  • func Find(name string) (Section, error)
  • func (s *Section) Add(properties ...Property)
  • func (s Section) Get(name string) string
  • func (s Section) IndentSize() int
  • func (s Section) InsertFinalNewline() bool
  • func (s Section) Lookup(name string) *Property
  • func (s Section) String() string
  • func (s Section) TabWidth() int
  • func (s Section) TrimTrailingWhitespace() bool

Examples

• Package
• File.Filter
• Parse

Constants

const DefaultName = ".editorconfig"

Types

type File

type File struct {
	Root     bool
	Sections []Section
}

File is an EditorConfig file with a number of sections.

func Parse

func Parse(r io.Reader) (*File, error)

Example

package main

import (
	"fmt"
	"strings"

	"mvdan.cc/editorconfig"
)

func main() {
	config := `
root = true

[*] # match all files
end_of_line = lf
insert_final_newline = true

[*.go] # only match Go
indent_style = tab
indent_size = 8
`
	file, err := editorconfig.Parse(strings.NewReader(config))
	if err != nil {
		panic(err)
	}
	fmt.Println(file)

}

Output:

root=true

[*]
end_of_line=lf
insert_final_newline=true

[*.go]
indent_style=tab
indent_size=8

func (*File) Filter

func (f *File) Filter(name string, cache map[string]*regexp.Regexp) Section

Filter returns a set of properties from a file that apply to a file name. Properties from later sections take precedence. The name should be a path relative to the directory holding the EditorConfig.

If cache is non-nil, the map will be used to reuse patterns translated and compiled to regular expressions.

Note that this function doesn't apply defaults; for that, see Find.

Note that, since the EditorConfig spec doesn't allow backslashes as path separators, backslashes in name are converted to forward slashes.

Example

package main

import (
	"fmt"
	"strings"

	"mvdan.cc/editorconfig"
)

func main() {
	config := `
[*]
end_of_line = lf

[*.go]
indent_style = tab
`
	file, err := editorconfig.Parse(strings.NewReader(config))
	if err != nil {
		panic(err)
	}
	fmt.Println(file.Filter("main.go", nil))

}

Output:

indent_style=tab
end_of_line=lf

func (*File) String

func (f *File) String() string

String turns a file into its INI format.

type Property

type Property struct {
	// Name is always lowercase and allows identifying a property.
	Name string
	// Value holds data for a property.
	Value string
}

Property is a single property with a name and a value, which can be represented as a single line like "indent_size=8".

func (Property) String

func (p Property) String() string

String turns a property into its INI format.

type Query

type Query struct {
	// ConfigName specifies what EditorConfig file name to use when
	// searching for files on disk. If empty, it defaults to DefaultName.
	ConfigName string

	// FileCache keeps track of which directories are known to contain an
	// EditorConfig. Existing entries which are nil mean that the directory
	// is known to not contain an EditorConfig.
	//
	// If nil, no caching takes place.
	FileCache map[string]*File

	// RegexpCache keeps track of patterns which have already been
	// translated to a regular expression and compiled, to save repeating
	// the work.
	//
	// If nil, no caching takes place.
	RegexpCache map[string]*regexp.Regexp

	// Version specifies an EditorConfig version to use when applying its
	// spec. When empty, it defaults to the latest version. This field
	// should generally be left untouched.
	Version string
}

Query allows fine-grained control of how EditorConfig files are found and used. It also attempts to cache and reuse work, which makes its Find method significantly faster when used on many files.

func (Query) Find

func (q Query) Find(name string) (Section, error)

Find figures out the properties that apply to a file name on disk, and returns them as a section. The name doesn't need to be an absolute path.

Any relevant EditorConfig files are parsed and used as necessary. Parsing the files can be cached in Query.

The defaults for supported properties are applied before returning.

type Section

type Section struct {
	// Name is the section's name. Usually, this will be a valid pattern
	// matching string, such as "[*.go]".
	Name string

	// Properties is the list of name-value properties contained by a
	// section. It is kept in increasing order, to allow binary searches.
	Properties []Property
}

Section is a single EditorConfig section, which applies a number of properties to the filenames matching it.

func Find

func Find(name string) (Section, error)

Find figures out the properties that apply to a file name on disk, and returns them as a section. The name doesn't need to be an absolute path.

It is equivalent to Query{}.Find; please note that no caching at all takes place in this mode.

func (*Section) Add

func (s *Section) Add(properties ...Property)

Add introduces a number of properties to the section. Properties that were already part of the section are ignored.

func (Section) Get

func (s Section) Get(name string) string

Get returns the value of a property found by its name. If no such property exists, an empty string is returned.

func (Section) IndentSize

func (s Section) IndentSize() int

IndentSize is a shortcut for Get("indent_size") as an int.

func (Section) InsertFinalNewline

func (s Section) InsertFinalNewline() bool

IndentSize is a shortcut for Get("insert_final_newline") as a bool.

func (Section) Lookup

func (s Section) Lookup(name string) *Property

Lookup finds a property by its name within a section and returns a pointer to it, or nil if no such property exists.

Note that most of the time, Get should be used instead.

func (Section) String

func (s Section) String() string

String turns a section into its INI format.

func (Section) TabWidth

func (s Section) TabWidth() int

IndentSize is similar to Get("indent_size"), but it handles the "tab" default and returns an int. When unset, it returns 0.

func (Section) TrimTrailingWhitespace

func (s Section) TrimTrailingWhitespace() bool

IndentSize is a shortcut for Get("trim_trailing_whitespace") as a bool.