fastparse

README

fastparse

A fast argument parser for Go designed for situations where you know the maximum amount of memory which a message can use (for example, a Discord or Twitter message). This library is extremely quick since it tries to avoid allocating memory on the fly, instead opting for pre-allocating the memory which the application will need. To use this library, when you initialise your application/library which uses this you will want to create a parser manager:

// Creates the parser manager. This will be used to create child parsers.
// The first parameter is the maximum length of a message. In this example, we are using Discord's limit of 2000 characters.
// The second parameter is the number of pre-allocated pads which will be used.
// Each pre-allocated pad will use roughly the length of a message, but will reduce the chance that a memory allocation needs to be made because all pads are being used.
m := fastparse.NewParserManager(2000, 100)

From here, we can simply create a parser from a thread when we need it. The reader must be a io.ReadSeeker:

parser := m.Parser(reader)

Please note that you should mark your parser as done when complete. This is important since if it's pre-allocated, it will not be re-added to the pool otherwise. You can do this with the Done function:

defer parser.Done()

The parser has the following other functions which you can use:

• Remainder() (string, error): Gets the remainder of a reader.
• GetNextArg() *Argument: GetNextArg is used to get the next argument. If there are no additional arguments, the pointer will be nil. The Argument struct contains the following:
  • Text: The text from the argument as a string.
  • Rewind() error: Rewind is used to rewind the reader to before an argument was read. This is useful for some argument verification situations. Note that if you want to rewind multiple arguments, you need to run it on every argument you parsed AFTER the one you wish to rewind in order of last to first.

Documentation

Index

• type Argument
  • func (a *Argument) Rewind() (err error)
• type Parser
  • func (p *Parser) Done()
  • func (p *Parser) GetNextArg() *Argument
  • func (p *Parser) Remainder() (string, error)
• type ParserManager
  • func NewParserManager(MessageLen, PreAllocatedPads int) *ParserManager
  • func (m *ParserManager) Parser(r io.ReadSeeker) *Parser

Types

type Argument

type Argument struct {
	// The text from the argument.
	Text string
	// contains filtered or unexported fields
}

Argument is used to define an argument.

func (*Argument) Rewind

func (a *Argument) Rewind() (err error)

Rewind is used to rewind the reader to before an argument was read. This is useful for some argument verification situations. Note that if you want to rewind multiple arguments, you need to run it on every argument you parsed AFTER the one you wish to rewind in order of last to first.

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser is used to define an argument parser from the ParserManager. Note this (and functions on provided arguments) are not thread safe.

func (*Parser) Done

func (p *Parser) Done()

Done should be called when you are done with a scratchpad.

func (*Parser) GetNextArg

func (p *Parser) GetNextArg() *Argument

GetNextArg is used to get the next argument. If there are no additional arguments, the pointer will be nil.

func (*Parser) Remainder

func (p *Parser) Remainder() (string, error)

Remainder is used to get the remainder of the reader as a string, ignoring arguments.

type ParserManager

type ParserManager struct {
	// contains filtered or unexported fields
}

ParserManager is used to manage the parsing of arguments.

func NewParserManager

func NewParserManager(MessageLen, PreAllocatedPads int) *ParserManager

NewParserManager is used to create a new parser manager. MessageLen is the maximum length of each message, and PreAllocatedPads are the amount of scratchpads which will be pre-allocated. Each pre-allocated scratchpad uses the amount of bytes which a message would take, but they mean that the memory will not need to be allocated on the fly later.

func (*ParserManager) Parser

func (m *ParserManager) Parser(r io.ReadSeeker) *Parser

Parser is used to get a parser from the manager.