shortcode

Documentation

Overview

Package tf2 implements an embedded macro system for plain-text documents.

Macros take the following forms:

$cmd
$cmd[arg1 arg2]
$cmd["arg1" "arg2"]
$cmd[name=value key="val"]
$cmd{body}
$cmd[args]{body}

Use $$ to produce a literal $ sign.

Index

• func CSVTable(ctx *Context, args []string, body string) string
• func Entity(_ *Context, args []string, _ string) string
• func ParseNamedArgs(args []string) map[string]string
• type Context
  • func New() *Context
  • func (c *Context) AddError(err error)
  • func (c *Context) Err() error
  • func (c *Context) Errs() []error
  • func (c *Context) Register(name string, fn HandlerFunc)
  • func (c *Context) RegisterNamed(name string, fn NamedFunc, paramNames ...string)
  • func (c *Context) Render(input string) string
  • func (c *Context) RenderDocument(input string) (string, error)
• type HandlerFunc
  • func MakeNamed(fn NamedFunc, paramNames ...string) HandlerFunc
• type NamedFunc
• type PositionError
  • func (e *PositionError) Error() string
  • func (e *PositionError) Unwrap() error

Functions

func CSVTable

func CSVTable(ctx *Context, args []string, body string) string

CSVTable is a HandlerFunc that renders the body as a CSV-formatted table. The first row of the CSV is used as the header. Macro expressions inside cells are parsed before CSV splitting, so macro bodies may safely contain commas and are expanded when each cell is rendered.

Example:

$csvtable{
Name,Score,Note
Alice,100,$b{perfect}
Bob,95,$link[https://example.com]{details}
}

func Entity

func Entity(_ *Context, args []string, _ string) string

Entity is a HandlerFunc that converts its single argument to an HTML entity.

$ent[across]  -->  &across;
$ent[#1245]   -->  ӝ

func ParseNamedArgs

func ParseNamedArgs(args []string) map[string]string

ParseNamedArgs extracts key=value pairs from an args slice into a map. Positional args (no '=') are ignored.

Types

type Context

type Context struct {
	Tags map[string]HandlerFunc
	// contains filtered or unexported fields
}

Context holds registered macro handlers and processes documents.

func New

func New() *Context

New creates a new Context.

func (*Context) AddError

func (c *Context) AddError(err error)

AddError records an error from within a handler, annotated with the line and column of the macro currently being executed. The document continues rendering; errors are retrievable via Err or Errs after the fact.

func (*Context) Err

func (c *Context) Err() error

Err returns the first recorded error, or nil.

func (*Context) Errs

func (c *Context) Errs() []error

Errs returns all recorded errors.

func (*Context) Register

func (c *Context) Register(name string, fn HandlerFunc)

Register adds a handler for the given macro name.

func (*Context) RegisterNamed

func (c *Context) RegisterNamed(name string, fn NamedFunc, paramNames ...string)

RegisterNamed registers a NamedFunc under name, wrapping it with MakeNamed.

func (*Context) Render

func (c *Context) Render(input string) string

Render processes the input text, expanding macros using registered handlers. Unknown macros (valid syntax but unregistered name) are passed through unchanged. $$ produces a literal $.

func (*Context) RenderDocument

func (c *Context) RenderDocument(input string) (string, error)

RenderDocument renders input like Render, but clears any previous errors first and returns the first error (if any) alongside the output. Use this as the top-level entry point; use Render for recursive calls within handlers.

type HandlerFunc

type HandlerFunc func(ctx *Context, args []string, body string) string

HandlerFunc is the signature for macro handler functions.

func MakeNamed

func MakeNamed(fn NamedFunc, paramNames ...string) HandlerFunc

MakeNamed wraps a NamedFunc as a HandlerFunc. paramNames assigns names to positional arguments in order; named arguments (key=value) are passed through directly. Extra positional args beyond len(paramNames) are dropped.

fn := MakeNamed(myFunc, "src", "alt")
// $cmd[photo.jpg "a photo"]  →  {"src":"photo.jpg", "alt":"a photo"}
// $cmd[src=photo.jpg alt="a photo"]  →  same

type NamedFunc

type NamedFunc func(ctx *Context, named map[string]string, body string) string

NamedFunc is a handler that receives args as a name→value map instead of a positional slice. Use MakeNamed or RegisterNamed to adapt it for use with a Context.

type PositionError

type PositionError struct {
	Line int
	Col  int
	Err  error
}

PositionError wraps an error with the line and column of the macro that produced it. Both are 1-based.

func (*PositionError) Error

func (e *PositionError) Error() string

func (*PositionError) Unwrap

func (e *PositionError) Unwrap() error