-- import "vimagination.zapto.org/bbcode"

Package bbcode implements a bbcode parser and converter

var (
	// HTMLText is a text processor that will HTML encode all text output
	HTMLText htmlText
	// PlainText is a text processor that just outputs all text with no change
	PlainText plainText
)

type AttrFilterFunc func(string) []byte

AttrFilterFunc is a wrapper for a func so that it satisfies the AttrFilterer interface

func (a AttrFilterFunc) AttrFilter(attr string) []byte

AttrFilter satisfies the AttrFilterer interface

type AttrFilterer interface {
	AttrFilter(string) []byte
}

AttrFilterer is used with AttributeTag to provide an attribute filter for the AttributeTag. It is used to process the parsed attribute for writing.

type AttributeTag struct {
}

AttributeTag is a simple Handler that outputs and open tag, with an attribute, and a close tag.

func NewAttributeTag(name string, open, openClose, attrOpen, attrClose, close []byte, filter AttrFilterer) *AttributeTag

NewAttributeTag creates a new Attribute Tag. The open byte slice is used to start the open tag and the openClose is used to close the open tag. The attrOpen and attrClose byte slices are used to surround the filtered attribute, within the open tag. Lastly, the close byte slice is used for the closing tag. The filter is used to modify the attribute, whether to correct formatting errors, or to validate. If a nil slice is returned, then no attribute is outputted. For example the following would create a colour tag for handling font colour:

NewAttributeTag("colour",
	[]byte("<span"),
	[]byte(">"),
	[]byte(" style=\"color: "),
	[]byte("\""),
	[]byte("</span>"),
	colourChecker)

A nil filter means that the attr will be written to the output with HTML encoding

func (a *AttributeTag) Close(p *Processor, attr string)

Close outputs the closing of the tag

func (a *AttributeTag) Handle(p *Processor, attr string)

Handle processes the tag

func (a *AttributeTag) Name() string

Name returns the name of the tag

func (a *AttributeTag) Open(p *Processor, attr string)

Open outputs the opening of the tag

type BBCode struct {
}

BBCode is a fully configured parser

func New(tags ...Handler) *BBCode

New create a new bbCode parser with the default configuration. See NewWithConfig for more information

func NewWithConfig(c Config, tags ...Handler) *BBCode

NewWithConfig creates a bbCode parser with a custom bbCode configuration. The tags are a list of Handlers that will be used to process the tag tokens that are generated by the parser. The first Handler with an empty string for a name with be used to process the text. By default, this is the HTMLText handler.

func (b *BBCode) Convert(w io.Writer, input []byte) error

Convert parses the byte slice and writes the output to the writer. Any error will be from the writing process and not from the parser

func (b *BBCode) ConvertReader(w io.Writer, input io.Reader) error

ConvertReader functions like Convert, but takes a io.Reader

func (b *BBCode) ConvertString(w io.Writer, input string) error

ConvertString functions like Convert, but takes a string

type CloseTag struct {
	Name string
}

CloseTag is a token containing the name of the tag

type Config struct {
	// TagOpen is the character used to open the tags.
	// In the default configuration this is the open bracket '['
	TagOpen rune

	// TagClose is the character used to close the tags.
	// In the default configuration this is the close bracket ']'
	TagClose rune

	// ClosingTag is the character used to define a closing tag, as opposed
	// to an opening tag.
	// In the default configuration, this is the slash '/'
	ClosingTag rune

	// AttributeSep is the character used to separate the tag name from the
	// attribute.
	// In the default configuration this is the equals sign '='
	AttributeSep rune

	// ValidTagName lists the characters that are allowed in the tag names.
	// Neither of the TagClose or AttributeSep characters should be in this
	// list.
	// In the default configuration this is A-Z a-z 0-9 and the asterix
	ValidTagName string
}

Config changes how the syntax of the inteperated bbCode

type FilterTag struct {
	OpenClose
}

FilterTag is a Handler that filters which child nodes are processed

func NewFilterTag(o OpenClose, filter func(string) bool) *FilterTag

NewFilterTag creates a Handler that filters which child nodes are processed. The filter takes the name of the tag and returns a bool determining whether the tag will be processed as a tag or as text. An empty tag name in the filter is used to determine is text is processed.

func (f *FilterTag) Handle(p *Processor, attr string)

Handle processes the tag, using its filter to determine which children are also processed

type Handler interface {
	// Name returns the name of the bbCode tag that this will be used for.
	// Returning an empty string indicates that this Handler should be used
	// for text handling.
	Name() string
	// Handle takes a pointer to the Processor and the attribute to the tag.
	Handle(*Processor, string)
}

Handler is an interface that represents the text and tag processors

type OpenClose interface {
	Name() string
	Open(*Processor, string)
	Close(*Processor, string)
}

OpenClose is an interface for the methods required by FilterTag. Both Tag and AttributeTag implement this interface

type OpenTag struct {
	Name string
	Attr *string
}

OpenTag is a token containing the name of the tag and a possible attribute.

type Processor struct {
}

Processor contains methods necessary for creating custom Handler's

func (p *Processor) Get() interface{}

Get returns the next token. It will be either a Text, OpenTag or a CloseTag

func (p *Processor) GetContents(untilTag string) string

GetContents grabs the raw contents of a tag and returns it as a string

func (p *Processor) Print(t interface{})

Print writes the textual representation of the given token to the output, using the text Handler

func (p *Processor) Process(untilTag string) bool

Process will continue processing the bbCode until it gets to an end tag which matches the tag name given, or until it reaches the end of the input. It returns true if the end tag was found, or false otherwise.

func (p *Processor) ProcessTag(t OpenTag)

ProcessTag will process the given tag as normal

func (p *Processor) Write(b []byte) (int, error)

Write writes to the underlying writer. The error is stored and does not need to be handled

type Tag struct {
}

Tag is a simple Handler that just outputs open and closing tags

func NewTag(name string, open, close []byte) *Tag

NewTag creates a simple Handler that outputs an open and close tag. For example, the following would be used to create a tag for handling bold:

NewTag("b", []byte("<b>"), []("</b>"))

func (t *Tag) Close(p *Processor, attr string)

Close outputs the closing of the tag

func (t *Tag) Handle(p *Processor, attr string)

Handle processes the tag

func (t *Tag) Name() string

Name returns the name of the tag

func (t *Tag) Open(p *Processor, attr string)

Open outputs the opening of the tag

type Text []string

Text is a token containing simple textual data