Alejandro Mery
1 year ago
1 changed files with 79 additions and 0 deletions
@ -1 +1,80 @@
|
||||
# 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](https://en.wikipedia.org/wiki/Rob_Pike)'s talk on |
||||
[Lexical Scanning in Go](https://go.dev/talks/2011/lex.slide#1) in 2011 which |
||||
you can [watch online](https://www.youtube.com/watch?v=HxaD_trXwRE) to get |
||||
better understanding of the ideas behind **asciigoat**. |
||||
|
||||
**asciigoat** is [MIT](https://opensource.org/license/mit/) licensed. |
||||
|
||||
[godoc]: https://pkg.go.dev/asciigoat.org/core |
||||
[godoc-badge]: https://pkg.go.dev/badge/asciigoat.org/core.svg |
||||
[goreport]: https://goreportcard.com/report/asciigoat.org/core |
||||
[goreport-badge]: https://goreportcard.com/badge/asciigoat.org/core |
||||
|
||||
[godoc-lexer-reader]: https://pkg.go.dev/asciigoat.org/core/lexer#Reader |
||||
[godoc-readcloser]: https://pkg.go.dev/asciigoat.org/core#ReadCloser |
||||
|
||||
## Lexer |
||||
|
||||
### lexer.Reader |
||||
|
||||
The lexer package provides [`lexer.Reader`][godoc-lexer-reader] which is |
||||
actually [`io.RuneScanner`](https://pkg.go.dev/io#RuneScanner) |
||||
that buffers accepted runes until you are ready to |
||||
[emit](https://pkg.go.dev/asciigoat.org/core/lexer#Reader.Emit) or |
||||
[discard](https://pkg.go.dev/asciigoat.org/core/lexer#Reader.Discard). |
||||
|
||||
### lexer.Position |
||||
|
||||
[`lexer.Position`](https://pkg.go.dev/asciigoat.org/core/lexer#Position) |
||||
is a `(Line, Column)` pair with methods to facilitate tracking |
||||
your position on the source [Reader](https://pkg.go.dev/io#Reader). |
||||
... |
||||
|
||||
### lexer.Error |
||||
|
||||
[`lexer.Error`](https://pkg.go.dev/asciigoat.org/core/lexer#Error) |
||||
is an [unwrappable](https://pkg.go.dev/errors#Unwrap) error with a |
||||
token position and hint attached. |
||||
|
||||
### lexer.StateFn |
||||
|
||||
At the heart of **asciigoat** we can _state functions_ as proposed on [Rob Pike's famous talk](https://www.youtube.com/watch?v=HxaD_trXwRE) which return the next _state function_ parsing is done. |
||||
Additionally there is a [`Run()`](https://pkg.go.dev/asciigoat.org/lexer#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](https://pkg.go.dev/unicode). |
||||
|
||||
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](https://pkg.go.dev/io#Closer) to Readers or buffers without on, |
||||
or unearthing one if available so |
||||
[io.ReadCloser](https://pkg.go.dev/io#ReadCloser) can be fulfilled. |
||||
|
||||
## See also |
||||
|
||||
* [asciigoat.org/ini](https://asciigoat.org/ini) |
||||
* [oss.jpi.io](https://oss.jpi.io) |
||||
|
Loading…
Reference in new issue