booklit: github.com/vito/booklit Index | Files | Directories

package booklit

import "github.com/vito/booklit"

Package booklit contains common types for constructing and traversing Booklit content and implementing plugins.

Index

Package Files

append.go aux_.go content.go definitions.go errors.go image.go link.go list.go package.go paragraph.go plugin.go preformatted.go reference.go section.go sequence.go string.go styled.go table.go target.go toc.go version.go

Variables

var Version = "0.0.0-dev"

Version is overridden at build time to set the version printed by the 'booklit --version' command.

func ErrorResponse Uses

func ErrorResponse(w http.ResponseWriter, err error)

ErrorResponse writes the error response page.

If err implements PrettyHTML it can render its own HTML template with additional troubleshooting.

func RegisterPlugin Uses

func RegisterPlugin(name string, factory PluginFactory)

RegisterPlugin registers a PluginFactory under a name. Booklit sections can then use the plugin by calling \use-plugin with the same name.

This is typically called by a plugin package's init() function.

type AmbiguousReferenceError Uses

type AmbiguousReferenceError struct {
    TagName          string
    DefinedLocations []ErrorLocation

    ErrorLocation
}

AmbiguousReferenceError is returned when a referenced tag is defined in multiple places.

func (AmbiguousReferenceError) Error Uses

func (err AmbiguousReferenceError) Error() string

Error returns an 'ambiguous target for tag' error message.

func (AmbiguousReferenceError) PrettyHTML Uses

func (err AmbiguousReferenceError) PrettyHTML(out io.Writer) error

PrettyHTML renders a HTML template containing the error message, a snippet of the source code where the error occurred, and snippets for the definition location of each tag that was found.

func (AmbiguousReferenceError) PrettyPrint Uses

func (err AmbiguousReferenceError) PrettyPrint(out io.Writer)

PrettyPrint prints the error message, a snippet of the source code where the error occurred, and snippets for the definition location of each tag that was found.

type Aux Uses

type Aux struct {
    Content
}

Aux is auxiliary content, typically in section titles, which can be removed in certain contexts such as references or table-of-content lists.

It is primarily used with the `stripAux` template function.

See https://booklit.page/baselit.html#aux for more information.

type Content Uses

type Content interface {
    // String summarizes the content. It is only used for troubleshooting.
    String() string

    // IsFlow must return true if the content is 'flow' content (e.g. anything
    // that fits within a sentence) or false if the content is 'block' content
    // (e.g. a paragraph or table).
    IsFlow() bool

    // Visit calls the VisitX method on Visitor corresponding to the Content's
    // type.
    Visit(Visitor) error
}

Content is arbitrary content (e.g. text, links, paragraphs) created by evaluating a Booklit document or created by a plugin.

func Append Uses

func Append(first Content, rest ...Content) Content

Append joins content together in a sequence.

When appending to a Sequence, the Sequence is extended. Otherwise a new Sequence is created.

func StripAux Uses

func StripAux(content Content) Content

StripAux recurses through Content and removes any Aux content from any nested sequences.

type Definition Uses

type Definition struct {
    Subject    Content
    Definition Content
}

Definition is a subject and its definition.

type Definitions Uses

type Definitions []Definition

Definitions is a list of definitions, e.g. a glossary.

func (Definitions) IsFlow Uses

func (con Definitions) IsFlow() bool

IsFlow returns false.

func (Definitions) String Uses

func (con Definitions) String() string

String summarizes the content for debugging purposes.

func (Definitions) Visit Uses

func (con Definitions) Visit(visitor Visitor) error

Visit calls VisitDefinitions.

type ErrorLocation Uses

type ErrorLocation struct {
    FilePath     string
    NodeLocation ast.Location
    Length       int
}

ErrorLocation is the source location in a Booklit document where an error occurred.

func (ErrorLocation) Annotate Uses

func (loc ErrorLocation) Annotate(msg string, args ...interface{}) string

Annotate prepends the source location to the given message.

func (ErrorLocation) AnnotateLocation Uses

func (loc ErrorLocation) AnnotateLocation(out io.Writer) error

AnnotateLocation writes a plaintext snippet of the location in the Booklit document.

func (ErrorLocation) AnnotatedHTML Uses

func (loc ErrorLocation) AnnotatedHTML(out io.Writer) error

AnnotatedHTML renders a HTML snippet of the error location in the Booklit document.

type FailedFunctionError Uses

type FailedFunctionError struct {
    Function string
    Err      error

    ErrorLocation
}

FailedFunctionError is returned when a plugin function called by a Booklit document returns an error.

func (FailedFunctionError) Error Uses

func (err FailedFunctionError) Error() string

Error returns a 'function \... returned an error' message specifying the function name and the error it returned.

func (FailedFunctionError) PrettyHTML Uses

func (err FailedFunctionError) PrettyHTML(out io.Writer) error

PrettyHTML renders an HTML template containing the error message followed by a snippet of the source location where the error occurred.

If the error returned by the function is a PrettyError, PrettyHTML will be called within the template to embed the error recursively.

func (FailedFunctionError) PrettyPrint Uses

func (err FailedFunctionError) PrettyPrint(out io.Writer)

PrettyPrint prints the error message and a snippet of the source code where the error occurred.

If the error returned by the function is a PrettyError, PrettyPrint is called and its output is indented.

Otherwise, the error is printed normally.

type Image Uses

type Image struct {
    // File path or URL.
    Path string

    // Description of the image.
    Description string
}

Image embeds an image as flow content.

func (Image) IsFlow Uses

func (con Image) IsFlow() bool

IsFlow returns true.

func (Image) String Uses

func (con Image) String() string

String summarizes the content for debugging purposes.

func (Image) Visit Uses

func (con Image) Visit(visitor Visitor) error

Visit calls VisitImage.

type Link struct {
    // Content to display as the link.
    Content

    // Target (e.g. a URL) that the link points to.
    Target string
}

Link is flow content that references something typically external to the Booklit content, such as another website.

func (Link) Visit Uses

func (con Link) Visit(visitor Visitor) error

Visit calls VisitLink.

type List Uses

type List struct {
    // The items in the list.
    Items []Content

    // Whether the list is ordered.
    Ordered bool
}

List is a block content containing a list of content, either ordered or unordered.

func (List) IsFlow Uses

func (con List) IsFlow() bool

IsFlow returns false.

func (List) String Uses

func (con List) String() string

String summarizes the content for debugging purposes.

func (List) Visit Uses

func (con List) Visit(visitor Visitor) error

Visit calls VisitList.

type Paragraph Uses

type Paragraph []Content

Paragraph is block content containing flow content as sentences.

When rendered, the sentences are joined by a single space in between and a blank line following the paragraph.

func (Paragraph) IsFlow Uses

func (con Paragraph) IsFlow() bool

IsFlow returns true.

func (Paragraph) String Uses

func (con Paragraph) String() string

String summarizes the content for debugging purposes.

func (Paragraph) Visit Uses

func (con Paragraph) Visit(visitor Visitor) error

Visit calls VisitParagraph.

type ParseError Uses

type ParseError struct {
    Err error

    ErrorLocation
}

ParseError is returned when a Booklit document fails to parse.

func (ParseError) Error Uses

func (err ParseError) Error() string

Error returns a 'parse error' error message.

func (ParseError) PrettyHTML Uses

func (err ParseError) PrettyHTML(out io.Writer) error

PrettyHTML renders an HTML template containing the error message followed by a snippet of the source location where the error occurred.

func (ParseError) PrettyPrint Uses

func (err ParseError) PrettyPrint(out io.Writer)

PrettyPrint prints the error message followed by a snippet of the source location where the error occurred.

type Partials Uses

type Partials map[string]Content

Partials is a map of named snippets of content. By convention, partial names are camel-cased like FooBar.

type Plugin Uses

type Plugin interface {
}

Plugin is an arbitrary object which is initialized with the Section that is using the plugin.

Methods on the plugin object will be invoked during the "evaluation" stage by function calling syntax in Booklit documents.

See https://booklit.page/plugins.html for more information.

type PluginFactory Uses

type PluginFactory func(*Section) Plugin

PluginFactory constructs a Plugin for a given Section.

func LookupPlugin Uses

func LookupPlugin(name string) (PluginFactory, bool)

LookupPlugin looks up the given plugin factory.

type Preformatted Uses

type Preformatted []Content

Preformatted is block content representing preformatted text, e.g. a code block.

func (Preformatted) IsFlow Uses

func (con Preformatted) IsFlow() bool

IsFlow returns false.

func (Preformatted) String Uses

func (con Preformatted) String() string

String summarizes the content for debugging purposes.

func (Preformatted) Visit Uses

func (con Preformatted) Visit(visitor Visitor) error

Visit calls VisitPreformatted.

type PrettyError Uses

type PrettyError interface {
    error

    // PrettyPrint is called by the booklit CLI to print an error message to
    // stderr.
    PrettyPrint(io.Writer)

    // PrettyHTML is called by the error page template to render HTML within the
    // error page.
    PrettyHTML(io.Writer) error
}

PrettyError is an interface for providing friendly error messages.

type Reference Uses

type Reference struct {
    // The tag to link to.
    TagName string

    // Optional content to display for the reference. If not present, the tag's
    // own display content will be used.
    Content Content

    // The tag that the name resolved to in the "resolving" phase.
    Tag *Tag

    // If set to true and resolving the tag does not succeed, display Content
    // instead of displaying a link.
    Optional bool

    // The original source location of the reference. Used when generating error
    // messages.
    Location ast.Location
}

Reference is flow content linking to a tag defined elsewhere.

func (*Reference) Display Uses

func (con *Reference) Display() Content

Display returns the content to display for the reference. If Content is set, it is returned, otherwise the resolved tag's Title is returned.

func (*Reference) IsFlow Uses

func (con *Reference) IsFlow() bool

IsFlow returns true.

func (*Reference) String Uses

func (con *Reference) String() string

String summarizes the content for debugging purposes.

func (*Reference) Visit Uses

func (con *Reference) Visit(visitor Visitor) error

Visit calls VisitReference.

type Section Uses

type Section struct {
    // The file path that the section was loaded from.
    Path string

    // The section title and body.
    Title Content
    Body  Content

    // The the file source location where the title was set.
    TitleLocation ast.Location

    // The primary tag and additional tags for the section.
    PrimaryTag Tag
    Tags       []Tag

    // The section's parent and child sections, if any.
    Parent   *Section
    Children []*Section

    // The section's style. Used at the rendering stage to e.g. use different
    // templates.
    //
    // Set with \style{foo}.
    Style string

    // Arbitrary named content.
    //
    // Partials are typically rendered in templates via {{.Partial "Foo" | render}}.
    //
    // Set with \set-partial{name}{content}.
    Partials Partials

    // Instructs the renderer to render child sections on their own pages.
    //
    // Set with \split-sections.
    SplitSections bool

    // Instructs the renderer to never render child sections on their own pages,
    // even if they set SplitSections.
    //
    // Typically used to have a single-page view or printout of the content.
    //
    // Set with \single-page.
    PreventSplitSections bool

    // Instructs .PageDepth to pretend the section is the lowest point.
    //
    // Set with \split-sections, even if PreventSplitSections is true, to ensure
    // section numbers remain consistent.
    ResetDepth bool

    // Omit child sections from table-of-contents lists.
    //
    // Set with \omit-children-from-table-of-contents.
    OmitChildrenFromTableOfContents bool

    // Plugins used by the section.
    PluginFactories []PluginFactory
    Plugins         []Plugin

    // Location is the source location where the section was defined, if it was
    // defined as an inline section.
    Location ast.Location

    // InvokeLocation is set prior to each function call so that the plugin's
    // method can assign it on content that it produces, e.g. Reference and
    // Target, so that error messages can be annotated with the source of the
    // error.
    //
    // XXX: make this an optional argument instead?
    InvokeLocation ast.Location

    // Processor is used for evaluating additional child sections.
    Processor SectionProcessor
}

Section is a Booklit document, typically loaded from a .lit file.

func (*Section) AnchorTags Uses

func (con *Section) AnchorTags() []Tag

AnchorTags returns the section's tags which have anchors.

func (*Section) Contains Uses

func (con *Section) Contains(sub *Section) bool

Contains returns true if the section is sub or if any of the children Contains sub.

func (*Section) Depth Uses

func (con *Section) Depth() int

Depth returns the absolute depth of the section.

func (*Section) FilePath Uses

func (con *Section) FilePath() string

FilePath is the file that the section is contained in.

func (*Section) FindTag Uses

func (con *Section) FindTag(tagName string) []Tag

FindTag searches for a given tag name and returns all matching tags.

func (*Section) HasAnchors Uses

func (con *Section) HasAnchors() bool

HasAnchors returns true if the section has any anchored tags or if any inline child sections have anchors.

func (*Section) IsFlow Uses

func (con *Section) IsFlow() bool

IsFlow returns false.

func (*Section) IsOrHasChild Uses

func (con *Section) IsOrHasChild(sub *Section) bool

IsOrHasChild returns true if the section is sub or has sub as a direct child.

func (*Section) Next Uses

func (con *Section) Next() *Section

Next returns the next section, i.e. if SplitSections return the first child, otherwise return the NextSibling.

func (*Section) NextSibling Uses

func (con *Section) NextSibling() *Section

NextSibling returns the section after the current section in the parent's children.

If there is no section after this section, the parent's NextSibling is returned.

func (*Section) Number Uses

func (con *Section) Number() string

Number returns a string denoting the section's unique numbering for use in titles and tables of contents, e.g. "3.2".

func (*Section) PageDepth Uses

func (con *Section) PageDepth() int

PageDepth returns the depth within the page that the section will be rendered on, i.e. accounting for ResetDepth being set on the parent section.

func (*Section) Partial Uses

func (con *Section) Partial(name string) Content

Partial returns the given partial, or nil if it does not exist.

func (*Section) Prev Uses

func (con *Section) Prev() *Section

Prev returns the previous section, i.e. the previous sibling section or the parent section if it is the first child.

If the section has no parent, Prev returns nil.

func (*Section) SetPartial Uses

func (con *Section) SetPartial(name string, value Content)

SetPartial assigns a partial within the section.

func (*Section) SetTag Uses

func (con *Section) SetTag(name string, title Content, loc ast.Location, optionalAnchor ...string)

SetTag adds a tag to the section.

func (*Section) SetTagAnchored Uses

func (con *Section) SetTagAnchored(name string, title Content, loc ast.Location, content Content, anchor string)

SetTagAnchored adds an anchored tag to the section, along with content associated to the anchor.

func (*Section) SetTitle Uses

func (con *Section) SetTitle(title Content, loc ast.Location, tags ...string)

SetTitle sets the section title and tags, setting a default tag based on the title if no tags are specified.

func (*Section) SimilarTags Uses

func (con *Section) SimilarTags(tagName string) []Tag

SimilarTags searches for a given tag name and returns all similar tags, i.e. tags with a levenshtein distance > 0.5.

func (*Section) SplitSectionsPrevented Uses

func (con *Section) SplitSectionsPrevented() bool

SplitSectionsPrevented returns true if PreventSplitSections is true or if the parent has SplitSectionsPrevented.

func (*Section) String Uses

func (con *Section) String() string

String summarizes the content for debugging purposes.

func (*Section) Top Uses

func (con *Section) Top() *Section

Top returns the top-level section.

func (*Section) UsePlugin Uses

func (con *Section) UsePlugin(pf PluginFactory)

UsePlugin registers the plugin within the section.

func (*Section) Visit Uses

func (con *Section) Visit(visitor Visitor) error

Visit calls VisitSection on visitor.

type SectionProcessor Uses

type SectionProcessor interface {
    EvaluateFile(*Section, string, []PluginFactory) (*Section, error)
    EvaluateNode(*Section, ast.Node, []PluginFactory) (*Section, error)
}

SectionProcessor evaluates a file or an inline syntax node to produce a child section.

type Sequence Uses

type Sequence []Content

Sequence is a generic slice of content which will be concatenated together upon rendering.

func (Sequence) Contents Uses

func (con Sequence) Contents() []Content

Contents returns the content as a slice.

func (Sequence) IsFlow Uses

func (con Sequence) IsFlow() bool

IsFlow returns true if the sequence contains only flow content or is empty.

func (Sequence) String Uses

func (con Sequence) String() string

String summarizes the content for debugging purposes.

func (Sequence) Visit Uses

func (con Sequence) Visit(visitor Visitor) error

Visit calls VisitSequence.

type String Uses

type String string

String is flow content containing arbitrary text.

The text should not contain linebreaks.

var Empty String

Empty is an empty String.

func (String) IsFlow Uses

func (str String) IsFlow() bool

IsFlow returns true.

func (String) String Uses

func (str String) String() string

String returns the string value.

func (String) Visit Uses

func (str String) Visit(visitor Visitor) error

Visit calls VisitString.

type Style Uses

type Style string

Style identifies a template name.

const (
    StyleVerbatim    Style = "verbatim"
    StyleItalic      Style = "italic"
    StyleBold        Style = "bold"
    StyleLarger      Style = "larger"
    StyleSmaller     Style = "smaller"
    StyleStrike      Style = "strike"
    StyleSuperscript Style = "superscript"
    StyleSubscript   Style = "subscript"
    StyleInset       Style = "inset"
    StyleAside       Style = "aside"
)

Common styled templated names.

type Styled Uses

type Styled struct {
    // A string identifying the template name.
    Style Style

    // Block may be set to true to force otherwise flow content to be block
    // instead.
    Block bool

    // The content to render with the template.
    Content Content

    // Additional partials to pass to the template.
    Partials Partials
}

Styled allows Content to be rendered with custom templates.

func (Styled) IsFlow Uses

func (con Styled) IsFlow() bool

IsFlow returns false if Block is true and otherwise delegates to content.IsFlow.

func (Styled) Partial Uses

func (con Styled) Partial(name string) Content

Partial returns the given partial by name, or nil if it does not exist.

func (Styled) String Uses

func (con Styled) String() string

String summarizes the content for debugging purposes.

func (Styled) Visit Uses

func (con Styled) Visit(visitor Visitor) error

Visit calls VisitStyled.

type Table Uses

type Table struct {
    Rows [][]Content
}

Table is block content containing tabular data, i.e. rows and columns.

func (Table) IsFlow Uses

func (con Table) IsFlow() bool

IsFlow returns false.

func (Table) String Uses

func (con Table) String() string

String summarizes the content for debugging purposes.

func (Table) Visit Uses

func (con Table) Visit(visitor Visitor) error

Visit calls VisitTable.

type TableOfContents Uses

type TableOfContents struct {
    Section *Section
}

TableOfContents is block content which renders a table of contents for the section and its children.

func (TableOfContents) IsFlow Uses

func (con TableOfContents) IsFlow() bool

IsFlow returns false.

func (TableOfContents) String Uses

func (con TableOfContents) String() string

String returns an empty string.

XXX: maybe this should summarize it, and the search index should use render.TextEngine isntead of String

func (TableOfContents) Visit Uses

func (con TableOfContents) Visit(visitor Visitor) error

Visit calls VisitTableOfContents.

type Tag Uses

type Tag struct {
    // The name of the tag, to be referenced with \reference.
    Name string

    // The title of the tag to display when no display is given by \reference.
    Title Content

    // The section the tag resides in.
    Section *Section

    // An optional anchor for the tag.
    //
    // Anchored tags correspond to page anchors and are typically displayed in
    // the section body, as opposed to tags corresponding to a section.
    Anchor string

    // Content that the tag corresponds to. For example, the section body or the
    // text that an anchored tag is for.
    //
    // Typically used for showing content previews in search results.
    Content Content

    // The source location of the tag's definition.
    Location ast.Location
}

Tag is something which can be referenced (by its name) from elsewhere in the section tree to produce a link.

type Target Uses

type Target struct {
    TagName  string
    Location ast.Location
    Title    Content
    Content  Content
}

Target is flow content which creates a tag within the section and renders an anchor element for the tag to target.

func (Target) IsFlow Uses

func (con Target) IsFlow() bool

IsFlow returns true.

func (Target) String Uses

func (con Target) String() string

String returns an empty string.

XXX: maybe this should summarize it, and the search index should use render.TextEngine isntead of String

func (Target) Visit Uses

func (con Target) Visit(visitor Visitor) error

Visit calls VisitTarget.

type TitleTwiceError Uses

type TitleTwiceError struct {
    TitleLocation ErrorLocation

    ErrorLocation
}

TitleTwiceError is returned when a section tries to set \title twice.

func (TitleTwiceError) Error Uses

func (err TitleTwiceError) Error() string

Error returns a 'cannot set title twice' message.

func (TitleTwiceError) PrettyHTML Uses

func (err TitleTwiceError) PrettyHTML(out io.Writer) error

PrettyHTML renders an HTML template containing the error message followed by a snippet of the source location where the error occurred.

If the error returned by the function is a PrettyError, PrettyHTML will be called within the template to embed the error recursively.

func (TitleTwiceError) PrettyPrint Uses

func (err TitleTwiceError) PrettyPrint(out io.Writer)

PrettyPrint prints the error message and a snippet of the source code where the error occurred.

If the error returned by the function is a PrettyError, PrettyPrint is called and its output is indented.

Otherwise, the error is printed normally.

type UndefinedFunctionError Uses

type UndefinedFunctionError struct {
    Function string

    ErrorLocation
}

UndefinedFunctionError is returned when a Booklit document tries to call a function that is not defined by any plugin.

func (UndefinedFunctionError) Error Uses

func (err UndefinedFunctionError) Error() string

Error returns an 'undefined function' error message.

func (UndefinedFunctionError) PrettyHTML Uses

func (err UndefinedFunctionError) PrettyHTML(out io.Writer) error

PrettyHTML renders an HTML template containing the error message and a snippet of the source code where the error occurred.

func (UndefinedFunctionError) PrettyPrint Uses

func (err UndefinedFunctionError) PrettyPrint(out io.Writer)

PrettyPrint prints the error message and a snippet of the source code where the error occurred.

type UnknownTagError Uses

type UnknownTagError struct {
    TagName string

    SimilarTags []Tag

    ErrorLocation
}

UnknownTagError is returned when a reference is made to an unknown tag.

func (UnknownTagError) Error Uses

func (err UnknownTagError) Error() string

Error returns an 'unknown tag' error message.

func (UnknownTagError) PrettyHTML Uses

func (err UnknownTagError) PrettyHTML(out io.Writer) error

PrettyHTML renders an HTML template containing the error message, a snippet of the source code where the error occurred, and suggests similar tags.

func (UnknownTagError) PrettyPrint Uses

func (err UnknownTagError) PrettyPrint(out io.Writer)

PrettyPrint prints the error message, a snippet of the source code where the error occurred, and suggests similar tags.

type Visitor Uses

type Visitor interface {
    VisitString(String) error
    VisitSequence(Sequence) error
    VisitReference(*Reference) error
    VisitLink(Link) error
    VisitSection(*Section) error
    VisitParagraph(Paragraph) error
    VisitTableOfContents(TableOfContents) error
    VisitPreformatted(Preformatted) error
    VisitStyled(Styled) error
    VisitTarget(Target) error
    VisitImage(Image) error
    VisitList(List) error
    VisitTable(Table) error
    VisitDefinitions(Definitions) error
}

Visitor is implemented in order to traverse Content.

Directories

PathSynopsis
ast
baselit
booklitcmd
chroma
chroma/plugin
errhtmlCode generated for package errhtml by go-bindata DO NOT EDIT.
load
render
render/htmlCode generated for package html by go-bindata DO NOT EDIT.
render/textCode generated for package text by go-bindata DO NOT EDIT.
stages
tests
tests/fixtures/arbitrary-style-plugin
tests/fixtures/erroring-plugin
tests/fixtures/partials-style-plugin
tests/fixtures/set-partials-plugin
tests/fixtures/stringer-plugin

Package booklit imports 15 packages (graph) and is imported by 13 packages. Updated 2021-01-18. Refresh now. Tools for package owners.