Improved documentation and examples.

    - deprecated NewPosition()
    - added String() to TokenType

Author: denormal

cache.go

@@ -6,15 +6,19 @@ import (
 
 // Cache is the interface for the GitIgnore cache
 type Cache interface {
-	Set(string, GitIgnore)
-	Get(string) GitIgnore
-} // Cache{}
+	// Set stores the GitIgnore ignore against its path.
+	Set(path string, ig GitIgnore)
+
+	// Get attempts to retrieve an GitIgnore instance associated with the given
+	// path. If the path is not known nil is returned.
+	Get(path string) GitIgnore
+}
 
 // cache is the default thread-safe cache implementation
 type cache struct {
 	_i    map[string]GitIgnore
 	_lock sync.Mutex
-} // cache{}
+}
 
 // NewCache returns a Cache instance. This is a thread-safe, in-memory cache
 // for GitIgnore instances.

defn_test.go

@@ -168,26 +168,26 @@ git-sample-3/foo/*
 var (
 	// define the positions of the bad patterns
 	_GITBADPOSITION = []gitignore.Position{
-		gitignore.NewPosition("", 17, 19, 189),
-		gitignore.NewPosition("", 18, 14, 219),
-		gitignore.NewPosition("", 19, 8, 233),
-		gitignore.NewPosition("", 20, 8, 248),
+		gitignore.Position{"", 17, 19, 189},
+		gitignore.Position{"", 18, 14, 219},
+		gitignore.Position{"", 19, 8, 233},
+		gitignore.Position{"", 20, 8, 248},
 	}
 
 	// define the positions of the good patterns
 	_GITPOSITION = []gitignore.Position{
-		gitignore.NewPosition("", 4, 1, 23),
-		gitignore.NewPosition("", 6, 1, 30),
-		gitignore.NewPosition("", 7, 1, 34),
-		gitignore.NewPosition("", 9, 1, 39),
-		gitignore.NewPosition("", 12, 1, 104),
-		gitignore.NewPosition("", 13, 1, 132),
-		gitignore.NewPosition("", 15, 1, 150),
-		gitignore.NewPosition("", 22, 1, 256),
-		gitignore.NewPosition("", 23, 1, 280),
-		gitignore.NewPosition("", 25, 1, 283),
-		gitignore.NewPosition("", 26, 1, 295),
-		gitignore.NewPosition("", 27, 1, 317),
+		gitignore.Position{"", 4, 1, 23},
+		gitignore.Position{"", 6, 1, 30},
+		gitignore.Position{"", 7, 1, 34},
+		gitignore.Position{"", 9, 1, 39},
+		gitignore.Position{"", 12, 1, 104},
+		gitignore.Position{"", 13, 1, 132},
+		gitignore.Position{"", 15, 1, 150},
+		gitignore.Position{"", 22, 1, 256},
+		gitignore.Position{"", 23, 1, 280},
+		gitignore.Position{"", 25, 1, 283},
+		gitignore.Position{"", 26, 1, 295},
+		gitignore.Position{"", 27, 1, 317},
 	}
 
 	// define the token stream for the _GITIGNORE .gitignore
@@ -535,7 +535,7 @@ var (
 	}
 
 	// define the beginning position for the parser & lexer
-	_BEGINNING = gitignore.NewPosition("", 1, 1, 0)
+	_BEGINNING = gitignore.Position{"", 1, 1, 0}
 
 	// define the tokens from the invalid .gitignore above
 	_TOKENSINVALID = []token{

doc.go

@@ -0,0 +1,6 @@
+/*
+Package gitignore provides an interface for parsing .gitignore files, and
+matching paths against the retrieved patterns. gitignore uses fnmatch for
+pattern matching as specified by git (see https://git-scm.com/docs/gitignore).
+*/
+package gitignore

error.go

@@ -2,12 +2,16 @@ package gitignore
 
 type Error interface {
 	error
+
+	// Position returns the position of the error within the .gitignore file
+	// (if any)
 	Position() Position
+
+	// Underlying returns the underlying error, permitting direct comparison
+	// against the wrapped error.
 	Underlying() error
 }
 
-// err extends the standard error to include a Position within the parsed
-// .gitignore file
 type err struct {
 	error
 	_position Position
@@ -18,15 +22,9 @@ func NewError(e error, p Position) Error {
 	return &err{error: e, _position: p}
 } // NewError()
 
-// Position returns the position of the error (i.e. the location within the
-// .gitignore file)
 func (e *err) Position() Position { return e._position }
 
-// Underlying returns the underlying error, permitting direct comparison
-// against the wrapped error.
-func (e *err) Underlying() error {
-	return e.error
-} // Underlying()
+func (e *err) Underlying() error { return e.error }
 
 // ensure err satisfies the Error interface
 var _ Error = &err{}

example_test.go

@@ -0,0 +1,56 @@
+package gitignore_test
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/denormal/go-gitignore"
+)
+
+func ExampleNewFromFile(t *testing.T) {
+	ignore, err := gitignore.NewFromFile("/my/project/.gitignore")
+	if err != nil {
+		panic(err)
+	}
+
+	// attempt to match an absolute path
+	match := ignore.Match("/my/project/src/file.go")
+	if match != nil {
+		if match.Ignore() {
+			fmt.Println("ignore file.go")
+		}
+	}
+
+	// attempt to match a relative path
+	//		- this is equivalent to the call above
+	match = ignore.Relative("src/file.go", false)
+	if match != nil {
+		if match.Include() {
+			fmt.Println("include file.go")
+		}
+	}
+} // ExampleNewFromFile()
+
+func ExampleNewRepository(t *testing.T) {
+	ignore, err := gitignore.NewRepository("/my/project")
+	if err != nil {
+		panic(err)
+	}
+
+	// attempt to match a directory in the repository
+	match := ignore.Relative("src/examples", true)
+	if match != nil {
+		if match.Ignore() {
+			fmt.Printf(
+				"ignore src/examples because of pattern %q at %s",
+				match, match.Position(),
+			)
+		}
+	}
+
+	// if we have an absolute path, or a path relative to the current
+	// working directory we can use the short-hand methods
+	if ignore.Include("/my/project/etc/service.conf") {
+		fmt.Println("include the service configuration")
+	}
+} // ExampleNewRepository()

gitignore.go

@@ -15,14 +15,38 @@ var empty = &ignore{}
 // methods for testing files for matching the .gitignore file, and then
 // determining whether a file should be ignored or included.
 type GitIgnore interface {
+	// Base returns the directory containing the .gitignore file.
 	Base() string
 
-	Match(string) Match
+	// Match attempts to match the path against this GitIgnore, and will
+	// return its Match if successful. Match will invoke the GitIgnore error
+	// handler (if defined) if it is not possible to determine the absolute
+	// path of the given path, or if its not possible to determine if the
+	// path represents a file or a directory. If an error occurs, Match
+	// returns nil and the error handler (if defined via New, NewWithErrors
+	// or NewWithCache) will be invoked.
+	Match(path string) Match
+
+	// Absolute attempts to match an absolute path against this GitIgnore. If
+	// the path is not located under the base directory of this GitIgnore, or
+	// is not matched by this GitIgnore, nil is returned.
 	Absolute(string, bool) Match
-	Relative(string, bool) Match
 
-	Ignore(string) bool
-	Include(string) bool
+	// Relative attempts to match a path relative to the GitIgnore base
+	// directory. isdir is used to indicate whether the path represents a file
+	// or a directory. If the path is not matched by the GitIgnore, nil is
+	// returned.
+	Relative(path string, isdir bool) Match
+
+	// Ignore returns true if the path is ignored by this GitIgnore. Paths
+	// that are not matched by this GitIgnore are not ignored. Internally,
+	// Ignore uses Match, and will return false if Match() returns nil for path.
+	Ignore(path string) bool
+
+	// Include returns true if the path is included by this GitIgnore. Paths
+	// that are not matched by this GitIgnore are always included. Internally,
+	// Include uses Match, and will return true if Match() returns nil for path.
+	Include(path string) bool
 }
 
 // ignore is the implementation of a .gitignore file.
@@ -187,13 +211,13 @@ func (i *ignore) Base() string {
 	return i._base
 } // Base()
 
-// Match attempts to match the path against this GitIgnore. If the path is
-// matched by a GitIgnore pattern, its Match will be returned. Match will
-// invoke the error handler (if defined) if its not possible to determine the
-// absolute path of the given path, or if its not possible to determine if the
-// path represents a file or a directory. If an error occurs, Match returns nil
-// and the error handler (if defined via New, NewWithErrors or NewWithCache)
-// will be invoked.
+// Match attempts to match the path against this GitIgnore, and will
+// return its Match if successful. Match will invoke the GitIgnore error
+// handler (if defined) if it is not possible to determine the absolute
+// path of the given path, or if its not possible to determine if the
+// path represents a file or a directory. If an error occurs, Match
+// returns nil and the error handler (if defined via New, NewWithErrors
+// or NewWithCache) will be invoked.
 func (i *ignore) Match(path string) Match {
 	// ensure we have the absolute path for the given file
 	_path, _err := filepath.Abs(path)
@@ -214,9 +238,9 @@ func (i *ignore) Match(path string) Match {
 	return i.Absolute(_path, _isdir)
 } // Match()
 
-// Absolute attempts to match an absolute path against this GitIgnore. If the
-// path is not located under the base directory of this GitIgnore, or is not
-// matched by this GitIgnore, nil is returned.
+// Absolute attempts to match an absolute path against this GitIgnore. If
+// the path is not located under the base directory of this GitIgnore, or
+// is not matched by this GitIgnore, nil is returned.
 func (i *ignore) Absolute(path string, isdir bool) Match {
 	// does the file share the same directory as this ignore file?
 	if !strings.HasPrefix(path, i._base) {
@@ -229,8 +253,10 @@ func (i *ignore) Absolute(path string, isdir bool) Match {
 	return i.Relative(_rel, isdir)
 } // Absolute()
 
-// Relative attempts to match a path relative to the GitIgnore base directory.
-// If the path is not matched by the GitIgnore, nil is returned.
+// Relative attempts to match a path relative to the GitIgnore base
+// directory. isdir is used to indicate whether the path represents a file
+// or a directory. If the path is not matched by the GitIgnore, nil is
+// returned.
 func (i *ignore) Relative(path string, isdir bool) Match {
 	// if we are on Windows, then translate the path to Unix form
 	_rel := path
@@ -251,9 +277,9 @@ func (i *ignore) Relative(path string, isdir bool) Match {
 	return nil
 } // Relative()
 
-// Ignore returns true if the path is ignored by this GitIgnore. Paths that are
-// not matched by this GitIgnore are not ignored. Internally, Ignore uses
-// Match, and will return false if Match() returns nil for path.
+// Ignore returns true if the path is ignored by this GitIgnore. Paths
+// that are not matched by this GitIgnore are not ignored. Internally,
+// Ignore uses Match, and will return false if Match() returns nil for path.
 func (i *ignore) Ignore(path string) bool {
 	_match := i.Match(path)
 	if _match != nil {
@@ -264,9 +290,9 @@ func (i *ignore) Ignore(path string) bool {
 	return false
 } // Ignore()
 
-// Include returns true if the path is included by this GitIgnore. Paths that
-// are not matched by this GitIgnore are always included. Internally, Include
-// uses Match, and will return true if Match() returns nil for path.
+// Include returns true if the path is included by this GitIgnore. Paths
+// that are not matched by this GitIgnore are always included. Internally,
+// Include uses Match, and will return true if Match() returns nil for path.
 func (i *ignore) Include(path string) bool {
 	_match := i.Match(path)
 	if _match != nil {

lexer.go

@@ -21,11 +21,18 @@ type lexer struct {
 
 // Lexer is the interface to the lexical analyser for .gitignore files
 type Lexer interface {
+	// Next returns the next Token from the Lexer reader. If an error is
+	// encountered, it will be returned as an Error instance, detailing the
+	// error and its position within the stream.
 	Next() (*Token, Error)
 
+	// Position returns the current position of the Lexer.
 	Position() Position
+
+	// String returns the string representation of the current position of the
+	// Lexer.
 	String() string
-} // Lexer{}
+}
 
 // NewLexer returns a Lexer instance for the io.Reader r.
 func NewLexer(r io.Reader) Lexer {
@@ -117,7 +124,7 @@ func (l *lexer) Next() (*Token, Error) {
 
 // Position returns the current position of the Lexer.
 func (l *lexer) Position() Position {
-	return NewPosition("", l._line, l._column, l._offset)
+	return Position{"", l._line, l._column, l._offset}
 } // Position()
 
 // String returns the string representation of the current position of the
@@ -424,7 +431,7 @@ func (l *lexer) token(type_ TokenType, word []rune, e Error) (*Token, Error) {
 	_word := len(word)
 	_column := l._column - _word
 	_offset := l._offset - _word
-	position := NewPosition("", l._line, _column, _offset)
+	position := Position{"", l._line, _column, _offset}
 
 	// if this is a newline token, we adjust the line & column counts
 	if type_ == EOL {

lexer_test.go

@@ -136,9 +136,9 @@ func lexer(t *testing.T, lines []string, eol string, tokens []token, e error) {
 			// ensure the token position matches the expected position
 			//		- since we will be testing with different line endings, we
 			//		  have to choose the correct offset
-			_position := gitignore.NewPosition(
+			_position := gitignore.Position{
 				"", _expected.Line, _expected.Column, _expected.NewLine,
-			)
+			}
 			if eol == "\r\n" {
 				_position.Offset = _expected.CarriageReturn
 			}

match.go

@@ -6,8 +6,18 @@ package gitignore
 // pattern), and to extract the position of the pattern within the .gitignore,
 // and a string representation of the pattern.
 type Match interface {
+	// Ignore returns true if the match pattern describes files or paths that
+	// should be ignored.
 	Ignore() bool
+
+	// Include returns true if the match pattern describes files or paths that
+	// should be included.
 	Include() bool
+
+	// String returns a string representation of the matched pattern.
 	String() string
+
+	// Position returns the position in the .gitignore file at which the
+	// matching pattern was defined.
 	Position() Position
-} // Match{}
+}