Browse Source

Merge pull request 'README: add initial description of the package' (#11)

Reviewed-on: #11
pull/13/head v0.3.7
Alejandro Mery 1 year ago
parent
commit
c31cfb9244
  1. 77
      README.md

77
README.md

@ -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](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 an [`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 have _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…
Cancel
Save