editorconfig

README

Editorconfig Core Go

A Editorconfig file parser and manipulator for Go.

Missing features

• escaping comments in values, probably in go-ini/ini

Installing

We recommend the use of Go 1.12+ modules for this package.

Import by the same path. The package name you will use to access it is editorconfig.

import (
    "github.com/editorconfig/editorconfig-core-go/v2"
)

Usage

Parse from file

fp, err := os.Open("path/to/.editorconfig")
if err != nil {
  log.Fatal(err)
}
defer fp.Close()

editorConfig, err := editorconfig.Parse(fp)
if err != nil {
    log.Fatal(err)
}

Parse from slice of bytes

data := []byte("...")
editorConfig, err := editorconfig.ParseBytes(data)
if err != nil {
    log.Fatal(err)
}

Get definition to a given filename

This method builds a definition to a given filename. This definition is a merge of the properties with selectors that matched the given filename. The lasts sections of the file have preference over the priors.

def := editorConfig.GetDefinitionForFilename("my/file.go")

This definition have the following properties:

type Definition struct {
	Selector string

	Charset                string
	IndentStyle            string
	IndentSize             string
	TabWidth               int
	EndOfLine              string
	TrimTrailingWhitespace *bool
	InsertFinalNewline     *bool
	Raw                    map[string]string
}

Automatic search for .editorconfig files

If you want a definition of a file without having to manually parse the .editorconfig files, you can then use the static version of GetDefinitionForFilename:

def, err := editorconfig.GetDefinitionForFilename("foo/bar/baz/my-file.go")

In the example above, the package will automatically search for .editorconfig files on:

• foo/bar/baz/.editorconfig
• foo/baz/.editorconfig
• foo/.editorconfig

Until it reaches a file with root = true or the root of the filesystem.

Generating a .editorconfig file

You can easily convert a Editorconfig struct to a compatible INI file:

// serialize to slice of bytes
data, err := editorConfig.Serialize()
if err != nil {
    log.Fatal(err)
}

// save directly to file
err := editorConfig.Save("path/to/.editorconfig")
if err != nil {
    log.Fatal(err)
}

Contributing

To run the tests:

go test -v ./...

To run the integration tests:

make test-core

Documentation

Index

• Constants
• func FnmatchCase(pattern, name string) (bool, error)
• type CachedParser
  • func NewCachedParser() *CachedParser
  • func (parser *CachedParser) FnmatchCase(selector string, filename string) (bool, error)
  • func (parser *CachedParser) ParseIni(filename string) (*Editorconfig, error)
• type Config
  • func (config *Config) Load(filename string) (*Definition, error)
• type Definition
  • func GetDefinitionForFilename(filename string) (*Definition, error)
  • func GetDefinitionForFilenameWithConfigname(filename string, configname string) (*Definition, error)
  • func NewDefinition(config Config) (*Definition, error)
  • func (d *Definition) InsertToIniFile(iniFile *ini.File)
• type Editorconfig
  • func Parse(r io.Reader) (*Editorconfig, error)
  • func ParseBytes(data []byte) (*Editorconfig, error)
  • func ParseFile(path string) (*Editorconfig, error)
  • func (e *Editorconfig) FnmatchCase(selector string, filename string) (bool, error)
  • func (e *Editorconfig) GetDefinitionForFilename(name string) (*Definition, error)
  • func (e *Editorconfig) Save(filename string) error
  • func (e *Editorconfig) Serialize() ([]byte, error)
  • func (e *Editorconfig) Write(w io.Writer) error
• type Parser
• type SimpleParser
  • func (parser *SimpleParser) FnmatchCase(selector string, filename string) (bool, error)
  • func (parser *SimpleParser) ParseIni(filename string) (*Editorconfig, error)

Constants

const (
	// ConfigNameDefault represents the name of the configuration file
	ConfigNameDefault = ".editorconfig"
	// UnsetValue is the value that unsets a preexisting variable
	UnsetValue = "unset"
)

const (
	IndentStyleTab    = "tab"
	IndentStyleSpaces = "space"
)

IndentStyle possible values

const (
	EndOfLineLf   = "lf"
	EndOfLineCr   = "cr"
	EndOfLineCrLf = "crlf"
)

EndOfLine possible values

const (
	CharsetLatin1  = "latin1"
	CharsetUTF8    = "utf-8"
	CharsetUTF16BE = "utf-16be"
	CharsetUTF16LE = "utf-16le"
	CharsetUTF8BOM = "utf-8 bom"
)

Charset possible values

const (
	MaxPropertyLength = 50
	MaxSectionLength  = 4096
	MaxValueLength    = 255
)

Limits for section name, properties, and values.

Functions

func FnmatchCase

func FnmatchCase(pattern, name string) (bool, error)

FnmatchCase tests whether the name matches the given pattern case included.

Types

type CachedParser

type CachedParser struct {
	// contains filtered or unexported fields
}

CachedParser implements the Parser interface but caches the definition and the regular expressions.

func NewCachedParser

func NewCachedParser() *CachedParser

NewCachedParser initializes the CachedParser.

func (*CachedParser) FnmatchCase

func (parser *CachedParser) FnmatchCase(selector string, filename string) (bool, error)

FnmatchCase calls the module's FnmatchCase and caches the parsed selector.

func (*CachedParser) ParseIni

func (parser *CachedParser) ParseIni(filename string) (*Editorconfig, error)

ParseIni parses the given filename to a Definition and caches the result.

type Config

type Config struct {
	Path    string
	Name    string
	Version string
	Parser  Parser
}

Config holds the configuration

func (*Config) Load

func (config *Config) Load(filename string) (*Definition, error)

Load loads definition of a given file.

type Definition

type Definition struct {
	Selector string `ini:"-" json:"-"`

	Charset                string            `ini:"charset" json:"charset,omitempty"`
	IndentStyle            string            `ini:"indent_style" json:"indent_style,omitempty"`
	IndentSize             string            `ini:"indent_size" json:"indent_size,omitempty"`
	TabWidth               int               `ini:"-" json:"-"`
	EndOfLine              string            `ini:"end_of_line" json:"end_of_line,omitempty"`
	TrimTrailingWhitespace *bool             `ini:"-" json:"-"`
	InsertFinalNewline     *bool             `ini:"-" json:"-"`
	Raw                    map[string]string `ini:"-" json:"-"`
	// contains filtered or unexported fields
}

Definition represents a definition inside the .editorconfig file. E.g. a section of the file. The definition is composed of the selector ("*", "*.go", "*.{js.css}", etc), plus the properties of the selected files.

func GetDefinitionForFilename

func GetDefinitionForFilename(filename string) (*Definition, error)

GetDefinitionForFilename given a filename, searches for .editorconfig files, starting from the file folder, walking through the previous folders, until it reaches a folder with `root = true`, and returns the right editorconfig definition for the given file.

func GetDefinitionForFilenameWithConfigname

func GetDefinitionForFilenameWithConfigname(filename string, configname string) (*Definition, error)

GetDefinitionForFilenameWithConfigname given a filename and a configname, searches for configname files, starting from the file folder, walking through the previous folders, until it reaches a folder with `root = true`, and returns the right editorconfig definition for the given file.

func NewDefinition

func NewDefinition(config Config) (*Definition, error)

NewDefinition builds a definition from a given config.

func (*Definition) InsertToIniFile

func (d *Definition) InsertToIniFile(iniFile *ini.File)

InsertToIniFile writes the definition into a ini file.

type Editorconfig

type Editorconfig struct {
	Root        bool
	Definitions []*Definition
	// contains filtered or unexported fields
}

Editorconfig represents a .editorconfig file.

It is composed by a "root" property, plus the definitions defined in the file.

func Parse

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

Parse parses from a reader.

func ParseBytes

func ParseBytes(data []byte) (*Editorconfig, error)

ParseBytes parses from a slice of bytes.

Deprecated: use Parse instead.

func ParseFile

func ParseFile(path string) (*Editorconfig, error)

ParseFile parses from a file.

Deprecated: use Parse instead.

func (*Editorconfig) FnmatchCase

func (e *Editorconfig) FnmatchCase(selector string, filename string) (bool, error)

FnmatchCase calls the matcher from the config's parser or the vanilla's.

func (*Editorconfig) GetDefinitionForFilename

func (e *Editorconfig) GetDefinitionForFilename(name string) (*Definition, error)

GetDefinitionForFilename returns a definition for the given filename.

The result is a merge of the selectors that matched the file. The last section has preference over the priors.

func (*Editorconfig) Save

func (e *Editorconfig) Save(filename string) error

Save saves the Editorconfig to a compatible INI file.

func (*Editorconfig) Serialize

func (e *Editorconfig) Serialize() ([]byte, error)

Serialize converts the Editorconfig to a slice of bytes, containing the content of the file in the INI format.

func (*Editorconfig) Write

func (e *Editorconfig) Write(w io.Writer) error

Write writes the Editorconfig to the Writer in a compatible INI file.

type Parser

type Parser interface {
	// ParseIni takes one .editorconfig (ini format) filename and returns its
	// Editorconfig definition.
	ParseIni(filename string) (*Editorconfig, error)

	// FnmatchCase takes a pattern, a filename, and tells wether the given filename
	// matches the globbing pattern.
	FnmatchCase(pattern string, filename string) (bool, error)
}

Parser interface is responsible for the parsing of the ini file and the globbing patterns.

type SimpleParser

type SimpleParser struct{}

SimpleParser implements the Parser interface but without doing any caching.

func (*SimpleParser) FnmatchCase

func (parser *SimpleParser) FnmatchCase(selector string, filename string) (bool, error)

FnmatchCase calls the module's FnmatchCase.

func (*SimpleParser) ParseIni

func (parser *SimpleParser) ParseIni(filename string) (*Editorconfig, error)

ParseIni calls go-ini's Load on the file.