Added documentation for most core parsers

This commit is contained in:
Brandon Dyck 2024-09-17 11:42:43 -06:00
parent 4dd6885ff6
commit 4fa3c2a466

View File

@ -126,6 +126,8 @@ func (s State[In]) At(pos uint64) State[In] {
type Parser[In, Out any] func(State[In]) (Result[In, Out], error) type Parser[In, Out any] func(State[In]) (Result[In, Out], error)
// Label creates a parser identical to p, except that a failed result will
// include label as an expected parse.
func (p Parser[In, Out]) Label(label string) Parser[In, Out] { func (p Parser[In, Out]) Label(label string) Parser[In, Out] {
return func(input State[In]) (Result[In, Out], error) { return func(input State[In]) (Result[In, Out], error) {
result, err := p(input) result, err := p(input)
@ -140,12 +142,15 @@ func (p Parser[In, Out]) Label(label string) Parser[In, Out] {
} }
} }
// Return creates a parser that always succeeds and returns value without consuming any input.
func Return[In, Out any](value Out) Parser[In, Out] { func Return[In, Out any](value Out) Parser[In, Out] {
return func(state State[In]) (Result[In, Out], error) { return func(state State[In]) (Result[In, Out], error) {
return Succeed(false, value, state, MessageOK(state.Pos())), nil return Succeed(false, value, state, MessageOK(state.Pos())), nil
} }
} }
// Satisfy creates a parser that attempts to read an input value for which pred returns true.
// If Satisfy succeeds, it returns the matched input value.
func Satisfy[T any](pred func(T) bool) Parser[T, T] { func Satisfy[T any](pred func(T) bool) Parser[T, T] {
return func(state State[T]) (Result[T, T], error) { return func(state State[T]) (Result[T, T], error) {
token := make([]T, 1) token := make([]T, 1)
@ -166,6 +171,8 @@ func Satisfy[T any](pred func(T) bool) Parser[T, T] {
} }
} }
// Slice creates a parser that attempts to read the contents of s from the input.
// If Slice succeeds, it returns a copy of the matched input values.
func Slice[T comparable](s []T) Parser[T, []T] { func Slice[T comparable](s []T) Parser[T, []T] {
expected := fmt.Sprint(s) expected := fmt.Sprint(s)
return func(state State[T]) (Result[T, []T], error) { return func(state State[T]) (Result[T, []T], error) {
@ -242,6 +249,7 @@ func Try[In, Out any](p Parser[In, Out]) Parser[In, Out] {
} }
} }
// Map creates a parser that converts the output of p from Out1 to Out2.
func Map[In, Out1, Out2 any](p Parser[In, Out1], f func(Out1) Out2) Parser[In, Out2] { func Map[In, Out1, Out2 any](p Parser[In, Out1], f func(Out1) Out2) Parser[In, Out2] {
return Bind(p, func(out Out1) Parser[In, Out2] { return Bind(p, func(out Out1) Parser[In, Out2] {
return Return[In](f(out)) return Return[In](f(out))
@ -259,6 +267,7 @@ func end[In any](s State[In]) (Result[In, struct{}], error) {
return Fail[In, struct{}](false, MakeMessage(s.Pos(), "", "end of input")), nil return Fail[In, struct{}](false, MakeMessage(s.Pos(), "", "end of input")), nil
} }
// End creates a parser that succeeds at the end of the input and fails otherwise.
func End[In any]() Parser[In, struct{}] { func End[In any]() Parser[In, struct{}] {
return end return end
} }