core/README.md

# 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)