Documentation

Overview

    Package ast contains functions and types for parsing a Booklit document into a Node.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func Parse

    func Parse(filename string, b []byte, opts ...Option) (interface{}, error)

      Parse parses the data from b using filename as information in the error messages.

      func ParseFile

      func ParseFile(filename string, opts ...Option) (i interface{}, err error)

        ParseFile parses the file identified by filename.

        func ParseReader

        func ParseReader(filename string, r io.Reader, opts ...Option) (interface{}, error)

          ParseReader parses the data from r using filename as information in the error messages.

          Types

          type Cloner

          type Cloner interface {
          	Clone() interface{}
          }

            Cloner is implemented by any value that has a Clone method, which returns a copy of the value. This is mainly used for types which are not passed by value (e.g map, slice, chan) or structs that contain such types.

            This is used in conjunction with the global state feature to create proper copies of the state to allow the parser to properly restore the state in the case of backtracking.

            type Error

            type Error struct {
            	Inner    error
            	Location Location
            }

              Error is a parse error along with its location in the source.

              func UnpackError

              func UnpackError(err error) (*Error, bool)

                UnpackError converts an internal parse error to an *Error.

                type Invoke

                type Invoke struct {
                	Function  string
                	Arguments []Node
                
                	Location Location
                }

                  Invoke is a function call, e.g. \foo{bar}.

                  func (Invoke) Method

                  func (node Invoke) Method() string

                    Method returns a method name by splitting Function on '-' and title-casing each word.

                    func (Invoke) Visit

                    func (node Invoke) Visit(visitor Visitor) error

                      Visit calls VisitInvoke.

                      type Location

                      type Location struct {
                      	Line   int
                      	Col    int
                      	Offset int
                      }

                        Location represents the location of a syntax node within the document.

                        type Node

                        type Node interface {
                        	Visit(Visitor) error
                        }

                          Node is a Booklit syntax tree.

                          type Option

                          type Option func(*parser) Option

                            Option is a function that can set an option on the parser. It returns the previous setting as an Option.

                            func AllowInvalidUTF8

                            func AllowInvalidUTF8(b bool) Option

                              AllowInvalidUTF8 creates an Option to allow invalid UTF-8 bytes. Every invalid UTF-8 byte is treated as a utf8.RuneError (U+FFFD) by character class matchers and is matched by the any matcher. The returned matched value, c.text and c.offset are NOT affected.

                              The default is false.

                              func Debug

                              func Debug(b bool) Option

                                Debug creates an Option to set the debug flag to b. When set to true, debugging information is printed to stdout while parsing.

                                The default is false.

                                func Entrypoint

                                func Entrypoint(ruleName string) Option

                                  Entrypoint creates an Option to set the rule name to use as entrypoint. The rule name must have been specified in the -alternate-entrypoints if generating the parser with the -optimize-grammar flag, otherwise it may have been optimized out. Passing an empty string sets the entrypoint to the first rule in the grammar.

                                  The default is to start parsing at the first rule in the grammar.

                                  func GlobalStore

                                  func GlobalStore(key string, value interface{}) Option

                                    GlobalStore creates an Option to set a key to a certain value in the globalStore.

                                    func InitState

                                    func InitState(key string, value interface{}) Option

                                      InitState creates an Option to set a key to a certain value in the global "state" store.

                                      func MaxExpressions

                                      func MaxExpressions(maxExprCnt uint64) Option

                                        MaxExpressions creates an Option to stop parsing after the provided number of expressions have been parsed, if the value is 0 then the parser will parse for as many steps as needed (possibly an infinite number).

                                        The default for maxExprCnt is 0.

                                        func Memoize

                                        func Memoize(b bool) Option

                                          Memoize creates an Option to set the memoize flag to b. When set to true, the parser will cache all results so each expression is evaluated only once. This guarantees linear parsing time even for pathological cases, at the expense of more memory and slower times for typical cases.

                                          The default is false.

                                          func Recover

                                          func Recover(b bool) Option

                                            Recover creates an Option to set the recover flag to b. When set to true, this causes the parser to recover from panics and convert it to an error. Setting it to false can be useful while debugging to access the full stack trace.

                                            The default is true.

                                            func Statistics

                                            func Statistics(stats *Stats, choiceNoMatch string) Option

                                              Statistics adds a user provided Stats struct to the parser to allow the user to process the results after the parsing has finished. Also the key for the "no match" counter is set.

                                              Example usage:

                                              input := "input"
                                              stats := Stats{}
                                              _, err := Parse("input-file", []byte(input), Statistics(&stats, "no match"))
                                              if err != nil {
                                                  log.Panicln(err)
                                              }
                                              b, err := json.MarshalIndent(stats.ChoiceAltCnt, "", "  ")
                                              if err != nil {
                                                  log.Panicln(err)
                                              }
                                              fmt.Println(string(b))
                                              

                                              type Paragraph

                                              type Paragraph []Sequence

                                                Paragraph is a grouping of lines separated by two linebreaks.

                                                func (Paragraph) Visit

                                                func (node Paragraph) Visit(visitor Visitor) error

                                                  Visit calls VisitParagraph.

                                                  type Preformatted

                                                  type Preformatted []Sequence

                                                    Preformatted is a grouping of lines, typically parsed

                                                    func (Preformatted) Visit

                                                    func (node Preformatted) Visit(visitor Visitor) error

                                                      Visit calls VisitPreformatted.

                                                      type Sequence

                                                      type Sequence []Node

                                                        Sequence represents adjacent nodes typically within a single line.

                                                        func (Sequence) Visit

                                                        func (node Sequence) Visit(visitor Visitor) error

                                                          Visit calls VisitSequence.

                                                          type Stats

                                                          type Stats struct {
                                                          	// ExprCnt counts the number of expressions processed during parsing
                                                          	// This value is compared to the maximum number of expressions allowed
                                                          	// (set by the MaxExpressions option).
                                                          	ExprCnt uint64
                                                          
                                                          	// ChoiceAltCnt is used to count for each ordered choice expression,
                                                          	// which alternative is used how may times.
                                                          	// These numbers allow to optimize the order of the ordered choice expression
                                                          	// to increase the performance of the parser
                                                          	//
                                                          	// The outer key of ChoiceAltCnt is composed of the name of the rule as well
                                                          	// as the line and the column of the ordered choice.
                                                          	// The inner key of ChoiceAltCnt is the number (one-based) of the matching alternative.
                                                          	// For each alternative the number of matches are counted. If an ordered choice does not
                                                          	// match, a special counter is incremented. The name of this counter is set with
                                                          	// the parser option Statistics.
                                                          	// For an alternative to be included in ChoiceAltCnt, it has to match at least once.
                                                          	ChoiceAltCnt map[string]map[string]int
                                                          }

                                                            Stats stores some statistics, gathered during parsing

                                                            type String

                                                            type String string

                                                              String is literal text, not including linebreaks.

                                                              func (String) Visit

                                                              func (node String) Visit(visitor Visitor) error

                                                                Visit calls VisitString.

                                                                type Visitor

                                                                type Visitor interface {
                                                                	VisitString(String) error
                                                                	VisitInvoke(Invoke) error
                                                                	VisitSequence(Sequence) error
                                                                	VisitParagraph(Paragraph) error
                                                                	VisitPreformatted(Preformatted) error
                                                                }

                                                                  Visitor is implemented in order to traverse Node.