Documentation ¶
Overview ¶
Package booklit contains common types for constructing and traversing Booklit content and implementing plugins.
Index ¶
- Variables
- func ErrorResponse(w http.ResponseWriter, err error)
- func RegisterPlugin(name string, factory PluginFactory)
- type AmbiguousReferenceError
- type Aux
- type Content
- type Definition
- type Definitions
- type ErrorLocation
- type FailedFunctionError
- type Image
- type Link
- type List
- type Paragraph
- type ParseError
- type Partials
- type Plugin
- type PluginFactory
- type Preformatted
- type PrettyError
- type Reference
- type Section
- func (con *Section) AnchorTags() []Tag
- func (con *Section) Contains(sub *Section) bool
- func (con *Section) Depth() int
- func (con *Section) FilePath() string
- func (con *Section) FindTag(tagName string) []Tag
- func (con *Section) HasAnchors() bool
- func (con *Section) IsFlow() bool
- func (con *Section) IsOrHasChild(sub *Section) bool
- func (con *Section) Next() *Section
- func (con *Section) NextSibling() *Section
- func (con *Section) Number() string
- func (con *Section) PageDepth() int
- func (con *Section) Partial(name string) Content
- func (con *Section) Prev() *Section
- func (con *Section) SetPartial(name string, value Content)
- func (con *Section) SetTag(name string, title Content, loc ast.Location, optionalAnchor ...string)
- func (con *Section) SetTagAnchored(name string, title Content, loc ast.Location, content Content, anchor string)
- func (con *Section) SetTitle(title Content, loc ast.Location, tags ...string)
- func (con *Section) SimilarTags(tagName string) []Tag
- func (con *Section) SplitSectionsPrevented() bool
- func (con *Section) String() string
- func (con *Section) Top() *Section
- func (con *Section) UsePlugin(pf PluginFactory)
- func (con *Section) Visit(visitor Visitor) error
- type SectionProcessor
- type Sequence
- type String
- type Style
- type Styled
- type Table
- type TableOfContents
- type Tag
- type Target
- type TitleTwiceError
- type UndefinedFunctionError
- type UnknownTagError
- type Visitor
Constants ¶
This section is empty.
Variables ¶
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 ¶ added in v0.12.0
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 ¶ added in v0.11.0
type AmbiguousReferenceError struct { TagName string DefinedLocations []ErrorLocation ErrorLocation }
AmbiguousReferenceError is returned when a referenced tag is defined in multiple places.
func (AmbiguousReferenceError) Error ¶ added in v0.11.0
func (err AmbiguousReferenceError) Error() string
Error returns an 'ambiguous target for tag' error message.
func (AmbiguousReferenceError) PrettyHTML ¶ added in v0.11.0
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 ¶ added in v0.11.0
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 ¶ added in v0.6.0
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.
type Definition ¶ added in v0.6.0
Definition is a subject and its definition.
type Definitions ¶ added in v0.6.0
type Definitions []Definition
Definitions is a list of definitions, e.g. a glossary.
func (Definitions) IsFlow ¶ added in v0.6.0
func (con Definitions) IsFlow() bool
IsFlow returns false.
func (Definitions) String ¶ added in v0.6.0
func (con Definitions) String() string
String summarizes the content for debugging purposes.
func (Definitions) Visit ¶ added in v0.6.0
func (con Definitions) Visit(visitor Visitor) error
Visit calls VisitDefinitions.
type ErrorLocation ¶ added in v0.11.0
ErrorLocation is the source location in a Booklit document where an error occurred.
func (ErrorLocation) Annotate ¶ added in v0.11.0
func (loc ErrorLocation) Annotate(msg string, args ...interface{}) string
Annotate prepends the source location to the given message.
func (ErrorLocation) AnnotateLocation ¶ added in v0.11.0
func (loc ErrorLocation) AnnotateLocation(out io.Writer) error
AnnotateLocation writes a plaintext snippet of the location in the Booklit document.
func (ErrorLocation) AnnotatedHTML ¶ added in v0.11.0
func (loc ErrorLocation) AnnotatedHTML(out io.Writer) error
AnnotatedHTML renders a HTML snippet of the error location in the Booklit document.
type FailedFunctionError ¶ added in v0.11.0
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 ¶ added in v0.11.0
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 ¶ added in v0.11.0
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 ¶ added in v0.11.0
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 ¶ added in v0.6.0
type Image struct { // File path or URL. Path string // Description of the image. Description string }
Image embeds an image as flow content.
type Link ¶
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.
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.
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.
type ParseError ¶ added in v0.11.0
type ParseError struct { Err error ErrorLocation }
ParseError is returned when a Booklit document fails to parse.
func (ParseError) Error ¶ added in v0.11.0
func (err ParseError) Error() string
Error returns a 'parse error' error message.
func (ParseError) PrettyHTML ¶ added in v0.11.0
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 ¶ added in v0.11.0
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 ¶ added in v0.6.0
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 ¶
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 ¶ added in v0.6.0
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 ¶ added in v0.11.0
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 ¶
Display returns the content to display for the reference. If Content is set, it is returned, otherwise the resolved tag's Title is returned.
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 ¶
AnchorTags returns the section's tags which have anchors.
func (*Section) Contains ¶
Contains returns true if the section is sub or if any of the children Contains sub.
func (*Section) HasAnchors ¶
HasAnchors returns true if the section has any anchored tags or if any inline child sections have anchors.
func (*Section) IsOrHasChild ¶ added in v0.6.0
IsOrHasChild returns true if the section is sub or has sub as a direct child.
func (*Section) Next ¶ added in v0.7.0
Next returns the next section, i.e. if SplitSections return the first child, otherwise return the NextSibling.
func (*Section) NextSibling ¶ added in v0.7.0
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 ¶
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 ¶ added in v0.6.0
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 ¶ added in v0.6.0
Partial returns the given partial, or nil if it does not exist.
func (*Section) Prev ¶ added in v0.7.0
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 ¶ added in v0.6.0
SetPartial assigns a partial within the section.
func (*Section) SetTagAnchored ¶ added in v0.6.0
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 ¶
SetTitle sets the section title and tags, setting a default tag based on the title if no tags are specified.
func (*Section) SimilarTags ¶ added in v0.12.0
SimilarTags searches for a given tag name and returns all similar tags, i.e. tags with a levenshtein distance > 0.5.
func (*Section) SplitSectionsPrevented ¶ added in v0.6.0
SplitSectionsPrevented returns true if PreventSplitSections is true or if the parent has SplitSectionsPrevented.
func (*Section) UsePlugin ¶
func (con *Section) UsePlugin(pf PluginFactory)
UsePlugin registers the plugin within the section.
type SectionProcessor ¶ added in v0.8.0
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) IsFlow ¶ added in v0.6.0
IsFlow returns true if the sequence contains only flow content or is empty.
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.
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 ¶ added in v0.6.0
IsFlow returns false if Block is true and otherwise delegates to content.IsFlow.
func (Styled) Partial ¶ added in v0.6.0
Partial returns the given partial by name, or nil if it does not exist.
type Table ¶ added in v0.6.0
type Table struct {
Rows [][]Content
}
Table is block content containing tabular data, i.e. rows and columns.
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 ¶ added in v0.6.0
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 ¶
Target is flow content which creates a tag within the section and renders an anchor element for the tag to target.
type TitleTwiceError ¶ added in v0.12.0
type TitleTwiceError struct { TitleLocation ErrorLocation ErrorLocation }
TitleTwiceError is returned when a section tries to set \title twice.
func (TitleTwiceError) Error ¶ added in v0.12.0
func (err TitleTwiceError) Error() string
Error returns a 'cannot set title twice' message.
func (TitleTwiceError) PrettyHTML ¶ added in v0.12.0
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 ¶ added in v0.12.0
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 ¶ added in v0.11.0
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 ¶ added in v0.11.0
func (err UndefinedFunctionError) Error() string
Error returns an 'undefined function' error message.
func (UndefinedFunctionError) PrettyHTML ¶ added in v0.11.0
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 ¶ added in v0.11.0
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 ¶ added in v0.11.0
type UnknownTagError struct { TagName string SimilarTags []Tag ErrorLocation }
UnknownTagError is returned when a reference is made to an unknown tag.
func (UnknownTagError) Error ¶ added in v0.11.0
func (err UnknownTagError) Error() string
Error returns an 'unknown tag' error message.
func (UnknownTagError) PrettyHTML ¶ added in v0.11.0
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 ¶ added in v0.11.0
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.
Source Files ¶
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
|
|
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:
|
Package stages implements the three stages for processing Booklit documents: |