booklit

package module
Version: v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 7, 2021 License: MIT Imports: 15 Imported by: 3

README

booklit

Go Reference CI

documentation

booklit.page

installation

grab the latest release, or build from source:

go get github.com/vito/booklit/cmd/booklit

usage

booklit -i foo.lit -o ./out

example

clone this repo and build the Booklit website:

./scripts/build-docs

then browse the generated docs from ./docs/index.html.

alternatively, run the docs in server mode:

./scripts/build-docs -s 3000

...and then browse to localhost:3000

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

View Source
var Version = "0.0.0-dev"

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

Functions

func ErrorResponse

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

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.

Types

type AmbiguousReferenceError

type AmbiguousReferenceError struct {
	TagName          string
	DefinedLocations []ErrorLocation

	ErrorLocation
}

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

func (AmbiguousReferenceError) Error

func (err AmbiguousReferenceError) Error() string

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

func (AmbiguousReferenceError) PrettyHTML

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

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

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

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

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

func StripAux(content Content) Content

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

type Definition

type Definition struct {
	Subject    Content
	Definition Content
}

Definition is a subject and its definition.

type Definitions

type Definitions []Definition

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

func (Definitions) IsFlow

func (con Definitions) IsFlow() bool

IsFlow returns false.

func (Definitions) String

func (con Definitions) String() string

String summarizes the content for debugging purposes.

func (Definitions) Visit

func (con Definitions) Visit(visitor Visitor) error

Visit calls VisitDefinitions.

type ErrorLocation

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

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

Annotate prepends the source location to the given message.

func (ErrorLocation) AnnotateLocation

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

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

func (ErrorLocation) AnnotatedHTML

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

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

type FailedFunctionError

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

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

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

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

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

func (con Image) IsFlow() bool

IsFlow returns true.

func (Image) String

func (con Image) String() string

String summarizes the content for debugging purposes.

func (Image) Visit

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

func (con Link) Visit(visitor Visitor) error

Visit calls VisitLink.

type List

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

func (con List) IsFlow() bool

IsFlow returns false.

func (List) String

func (con List) String() string

String summarizes the content for debugging purposes.

func (List) Visit

func (con List) Visit(visitor Visitor) error

Visit calls VisitList.

type Paragraph

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

func (con Paragraph) IsFlow() bool

IsFlow returns true.

func (Paragraph) String

func (con Paragraph) String() string

String summarizes the content for debugging purposes.

func (Paragraph) Visit

func (con Paragraph) Visit(visitor Visitor) error

Visit calls VisitParagraph.

type ParseError

type ParseError struct {
	Err error

	ErrorLocation
}

ParseError is returned when a Booklit document fails to parse.

func (ParseError) Error

func (err ParseError) Error() string

Error returns a 'parse error' error message.

func (ParseError) PrettyHTML

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

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

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

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

type PluginFactory func(*Section) Plugin

PluginFactory constructs a Plugin for a given Section.

func LookupPlugin

func LookupPlugin(name string) (PluginFactory, bool)

LookupPlugin looks up the given plugin factory.

type Preformatted

type Preformatted []Content

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

func (Preformatted) IsFlow

func (con Preformatted) IsFlow() bool

IsFlow returns false.

func (Preformatted) String

func (con Preformatted) String() string

String summarizes the content for debugging purposes.

func (Preformatted) Visit

func (con Preformatted) Visit(visitor Visitor) error

Visit calls VisitPreformatted.

type PrettyError

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

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

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

func (con *Reference) IsFlow() bool

IsFlow returns true.

func (*Reference) String

func (con *Reference) String() string

String summarizes the content for debugging purposes.

func (*Reference) Visit

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

Visit calls VisitReference.

type Section

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

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

AnchorTags returns the section's tags which have anchors.

func (*Section) Contains

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

func (con *Section) Depth() int

Depth returns the absolute depth of the section.

func (*Section) FilePath

func (con *Section) FilePath() string

FilePath is the file that the section is contained in.

func (*Section) FindTag

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

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

func (*Section) HasAnchors

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

func (con *Section) IsFlow() bool

IsFlow returns false.

func (*Section) IsOrHasChild

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

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

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

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

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

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

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

func (*Section) Prev

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

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

SetPartial assigns a partial within the section.

func (*Section) SetTag

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

SetTag adds a tag to the section.

func (*Section) SetTagAnchored

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

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

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

func (con *Section) SplitSectionsPrevented() bool

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

func (*Section) String

func (con *Section) String() string

String summarizes the content for debugging purposes.

func (*Section) Top

func (con *Section) Top() *Section

Top returns the top-level section.

func (*Section) UsePlugin

func (con *Section) UsePlugin(pf PluginFactory)

UsePlugin registers the plugin within the section.

func (*Section) Visit

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

Visit calls VisitSection on visitor.

type SectionProcessor

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

type Sequence []Content

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

func (Sequence) Contents

func (con Sequence) Contents() []Content

Contents returns the content as a slice.

func (Sequence) IsFlow

func (con Sequence) IsFlow() bool

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

func (Sequence) String

func (con Sequence) String() string

String summarizes the content for debugging purposes.

func (Sequence) Visit

func (con Sequence) Visit(visitor Visitor) error

Visit calls VisitSequence.

type String

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

func (str String) IsFlow() bool

IsFlow returns true.

func (String) String

func (str String) String() string

String returns the string value.

func (String) Visit

func (str String) Visit(visitor Visitor) error

Visit calls VisitString.

type Style

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

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

func (con Styled) IsFlow() bool

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

func (Styled) Partial

func (con Styled) Partial(name string) Content

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

func (Styled) String

func (con Styled) String() string

String summarizes the content for debugging purposes.

func (Styled) Visit

func (con Styled) Visit(visitor Visitor) error

Visit calls VisitStyled.

type Table

type Table struct {
	Rows [][]Content
}

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

func (Table) IsFlow

func (con Table) IsFlow() bool

IsFlow returns false.

func (Table) String

func (con Table) String() string

String summarizes the content for debugging purposes.

func (Table) Visit

func (con Table) Visit(visitor Visitor) error

Visit calls VisitTable.

type TableOfContents

type TableOfContents struct {
	Section *Section
}

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

func (TableOfContents) IsFlow

func (con TableOfContents) IsFlow() bool

IsFlow returns false.

func (TableOfContents) String

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

func (con TableOfContents) Visit(visitor Visitor) error

Visit calls VisitTableOfContents.

type Tag

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

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

func (con Target) IsFlow() bool

IsFlow returns true.

func (Target) String

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

func (con Target) Visit(visitor Visitor) error

Visit calls VisitTarget.

type TitleTwiceError

type TitleTwiceError struct {
	TitleLocation ErrorLocation

	ErrorLocation
}

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

func (TitleTwiceError) Error

func (err TitleTwiceError) Error() string

Error returns a 'cannot set title twice' message.

func (TitleTwiceError) PrettyHTML

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

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

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

func (err UndefinedFunctionError) Error() string

Error returns an 'undefined function' error message.

func (UndefinedFunctionError) PrettyHTML

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

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

type UnknownTagError struct {
	TagName string

	SimilarTags []Tag

	ErrorLocation
}

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

func (UnknownTagError) Error

func (err UnknownTagError) Error() string

Error returns an 'unknown tag' error message.

func (UnknownTagError) PrettyHTML

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

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

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

Path Synopsis
Package ast contains functions and types for parsing a Booklit document into a Node.
Package ast contains functions and types for parsing a Booklit document into a Node.
Package baselit provides the base plugin used by all sections by default.
Package baselit provides the base plugin used by all sections by default.
Package chroma provides a basic plugin for implementing syntax highlighting using Chroma (https://github.com/alecthomas/chroma).
Package chroma provides a basic plugin for implementing syntax highlighting using Chroma (https://github.com/alecthomas/chroma).
cmd
docs
go
hello Module
Code generated for package errhtml by go-bindata DO NOT EDIT.
Code generated for package errhtml by go-bindata DO NOT EDIT.
Package load glues everything together to provide a higher-level interfaces for loading Booklit documents into Sections, either from files or from already-parsed nodes (i.e.
Package load glues everything together to provide a higher-level interfaces for loading Booklit documents into Sections, either from files or from already-parsed nodes (i.e.
Package render contains conversions from a processed Booklit section into a rendered format such as plaintext or HTML, either for serving in a browser or for writing to files on disk.
Package render contains conversions from a processed Booklit section into a rendered format such as plaintext or HTML, either for serving in a browser or for writing to files on disk.
html
Code generated for package html by go-bindata DO NOT EDIT.
Code generated for package html by go-bindata DO NOT EDIT.
text
Code generated for package text by go-bindata DO NOT EDIT.
Code generated for package text by go-bindata DO NOT EDIT.
Package stages implements the three stages for processing Booklit documents: The first stage is Evaluate, which interprets a node to generate content while calling plugin functions.
Package stages implements the three stages for processing Booklit documents: The first stage is Evaluate, which interprets a node to generate content while calling plugin functions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto