Browse Source

README: add initial description of the package

and badges

Signed-off-by: Alejandro Mery <>
Alejandro Mery 11 months ago
  1. 77


@ -1 +1,78 @@
# asciigoat's core library
[![Go Reference][godoc-badge]][godoc]
[![Go Report Card][goreport-badge]][goreport]
This package contains the basics for writing simple parsers of
text languages heavily inspired by
[Rob Pike]('s talk on
[Lexical Scanning in Go]( in 2011 which
you can [watch online]( to get
better understanding of the ideas behind **asciigoat**.
**asciigoat** is [MIT]( licensed.
## Lexer
### lexer.Reader
The lexer package provides [`lexer.Reader`][godoc-lexer-reader] which is
actually an [`io.RuneScanner`](
that buffers accepted runes until you are ready to
[emit]( or
### lexer.Position
is a `(Line, Column)` pair with methods to facilitate tracking
your position on the source [Reader](
### lexer.Error
is an [unwrappable]( error with a
token position and hint attached.
### lexer.StateFn
At the heart of **asciigoat** we have _state functions_ as proposed on [Rob Pike's famous talk]( which return the next _state function_ parsing is done.
Additionally there is a [`Run()`]( helper that implements the loop.
### rune checkers
_Rune checkers_ are simple functions that tell if a rune is of a class or it's not.
Fundamental checkers are provided by the [`unicode` package](
Our [`lexer.Reader`][godoc-lexer-reader] uses them on its `Accept()` and `AcceptAll()` methods to
make it easier to consume the _source_ document.
To facilitate the declaration of _rune classes_ in the context of **asciigoat** powered parsers we include
a series of rune checker factories.
* `NewIsIn(string)`
* `NewIsInRunes(...rune)`
* `NewIsNot(checker)`
* `NewIsOneOf(...checker)`
## Others
### ReadCloser
[ReadCloser][godoc-readcloser] assists in providing a
[io.Closer]( to Readers or buffers without on,
or unearthing one if available so
[io.ReadCloser]( can be fulfilled.
## See also
* [](
* [](