shorthand

README

shorthand

A simple label or macro expander

Example use cases:

• label or abbreviation expansion in Markdown files
• build html templates from markdown files
• compose pages from multiple markdown files

The supported command line options can be listed using the --help options.

    shorthand --help

Source code can be found at github.com/rsdoiel/shorthand

The project website is rsdoiel.github.io/shorthand

Tutorial

Timestamp in Markdown file

If the content of the markdown file testdata/report.md was

    Report Date: @now

    # Topic: The current local time.

    This report highlights the current local time of rendering this document

    The current local time is @now

From the command line you can do something like this

    shorthand -e ':bash: @now date' \
        -e ":import: @report testdata/report.md" \
        -e "@report" \
        -e ':exit:' | pandoc -s > testdata/report.html

What this command does is launch the shorthand interpreter and it replaces all occurrences of "@now" in the markdown document with the output from the Unix program date.

The output (before piping to Pandoc) would look something like

    Report Date: Sat Aug 29 11:25:48 PDT 2015

    # Topic: The current local time.

    This report highlights the current local time of rendering this document

    The current local time is Sat Aug 29 11:25:48 PDT 2015

Notice that both "@now" are replace with the same date information.

embedding shorthand definitions

You could also embed the shorthand definitions command straight in the markdown itself. with something like

    @now :bash: date

    Report Date: @now

    # Topic: The current local time.

    This report highlights the current local time of rendering this document

    The current local time is @now

That makes the command line a little shorter

    shorthand testdata/report.md | pandoc -s > testdata/report.html

Installation

shorthand can be installed with the go get command.

    go get github.com/rsdoiel/shorthand/...

Documentation

• shorthand
• shorthand syntax

Documentation

Overview

Package shorthand provides shorthand definition and expansion.

shorthand.go - A simple definition and expansion notation to use as shorthand when a template language is too much.

@author R. S. Doiel, <rsdoiel@gmail.com> copyright (c) 2019 all rights reserved. Released under the BSD 2-Clause license See: http://opensource.org/licenses/BSD-2-Clause

operators - assign a function with the func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) signature and use RegisterOp (e.g. in the New() function) to add support to Shorthand.

Package shorthand provides shorthand definition and expansion.

shorthand.go - A simple definition and expansion notation to use as shorthand when a template language is too much.

@author R. S. Doiel, <rsdoiel@gmail.com> copyright (c) 2019 all rights reserved. Released under the BSD 2-Clause license See: http://opensource.org/licenses/BSD-2-Clause

Index

• Constants
• Variables
• func FmtHelp(src string, appName string, version string, releaseDate string, ...) string
• type OperatorMap
• type SourceMap
• type SymbolTable
  • func (st *SymbolTable) GetSymbol(sym string) SourceMap
  • func (st *SymbolTable) GetSymbols() []SourceMap
  • func (st *SymbolTable) SetSymbol(sm SourceMap) int
• type VirtualMachine
  • func New() *VirtualMachine
  • func (vm *VirtualMachine) Apply(src []byte) ([]byte, error)
  • func (vm *VirtualMachine) Eval(s string, lineNo int) (string, error)
  • func (vm *VirtualMachine) EvalSymbol(sm SourceMap) error
  • func (vm *VirtualMachine) Expand(text string) string
  • func (vm *VirtualMachine) Parse(s string, lineNo int) SourceMap
  • func (vm *VirtualMachine) RegisterOp(op string, callback func(*VirtualMachine, SourceMap) (SourceMap, error), ...) error
  • func (vm *VirtualMachine) Run(in *bufio.Reader) int
  • func (vm *VirtualMachine) SetPrompt(s string)

Constants

const (
	// Version number of release
	Version = "0.2.2"

	// ReleaseDate, the date version.go was generated
	ReleaseDate = "2024-05-20"

	// ReleaseHash, the Git hash when version.go was generated
	ReleaseHash = "bc9b446"

	LicenseText = `` /* 33747-byte string literal not displayed */

)

Variables

var AssignExpandExpansion = func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) {
	tmp := vm.Expand(sm.Source)
	expanded := vm.Expand(tmp)
	return SourceMap{Label: sm.Label, Op: sm.Op, Source: sm.Source, Expanded: expanded, LineNo: sm.LineNo}, nil
}

AssignExpandExpansion expand an expanded Source and copy to Expanded

var AssignExpandShell = func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) {
	buf, err := exec.Command("bash", "-c", vm.Expand(sm.Source)).Output()
	if err != nil {
		return sm, err
	}
	expanded := string(buf)
	return SourceMap{Label: sm.Label, Op: sm.Op, Source: sm.Source, Expanded: expanded, LineNo: sm.LineNo}, nil
}

AssignExpandShell expand Source, pass to Bash and assign output to Expanded

var AssignExpansion = func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) {
	expanded := vm.Expand(sm.Source)
	return SourceMap{Label: sm.Label, Op: sm.Op, Source: sm.Source, Expanded: expanded, LineNo: sm.LineNo}, nil
}

AssignExpansion expands Source and copy to Expanded

var AssignInclude = func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) {
	buf, err := ioutil.ReadFile(sm.Source)
	if err != nil {
		return SourceMap{Label: "", Op: ":exit:", Source: "", Expanded: "", LineNo: sm.LineNo},
			fmt.Errorf("Cannot read %s: %s\n", sm.Source, err)
	}
	expanded := string(buf)
	return SourceMap{Label: sm.Label, Op: sm.Op, Source: sm.Source, Expanded: expanded, LineNo: sm.LineNo}, nil
}

AssignInclude read a file using Source as filename and put the results in Expanded

var AssignShell = func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) {
	buf, err := exec.Command("bash", "-c", sm.Source).Output()
	if err != nil {
		return sm, err
	}
	expanded := string(buf)
	return SourceMap{Label: sm.Label, Op: sm.Op, Source: sm.Source, Expanded: expanded, LineNo: sm.LineNo}, nil
}

AssignShell pass Source to bash and copy stdout to Expanded

var AssignString = func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) {
	expanded := sm.Source
	return SourceMap{Label: sm.Label, Op: sm.Op, Source: sm.Source, Expanded: expanded, LineNo: sm.LineNo}, nil
}

AssignString take the Source and copy to Expanded

var ExportAssignment = func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) {
	oSM := vm.Symbols.GetSymbol(sm.Label)
	out := fmt.Sprintf("%s %s %s", oSM.Op, oSM.Label, oSM.Source)
	fname := sm.Source
	err := ioutil.WriteFile(fname, []byte(out), 0666)
	if err != nil {
		return sm, fmt.Errorf("%d Write error %s: %s", sm.LineNo, fname, err)
	}
	return oSM, nil
}

ExportAssignment write the assignment to a file

var ExportAssignments = func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) {
	fp, err := os.Create(sm.Source)
	if err != nil {
		return sm, fmt.Errorf("%d Create error %s: %s", sm.LineNo, sm.Source, err)
	}
	defer fp.Close()
	symbols := vm.Symbols.GetSymbols()
	for _, oSM := range symbols {
		fmt.Fprintf(fp, "%s %s %s\n", oSM.Op, oSM.Label, oSM.Source)
	}
	return sm, nil
}

ExportAssignments write multiple assignments to a file

var (
	HowItWorks = `` /* 7323-byte string literal not displayed */

)

HowItWorks is a help text describing shorthand.

var ImportAssignments = func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) {
	var output []string
	buf, err := ioutil.ReadFile(sm.Source)
	if err != nil {
		return SourceMap{Label: "", Op: ":exit:", Source: "", Expanded: "", LineNo: sm.LineNo}, err
	}
	lineNo := 1
	for _, src := range strings.Split(string(buf), "\n") {
		s, err := vm.Eval(src, lineNo)
		if err != nil {
			return SourceMap{Label: "", Op: ":exit:", Source: "", Expanded: "", LineNo: sm.LineNo},
				fmt.Errorf("ERROR (%s %d): %s", sm.Source, lineNo, err)
		}
		if s != "" {
			output = append(output, s)
		}
	}
	expanded := strings.Join(output, "\n")
	return SourceMap{Label: sm.Label, Op: sm.Op, Source: sm.Source, Expanded: expanded, LineNo: sm.LineNo}, nil
}

ImportAssignments evaluates the file for assignment operations

var IncludeExpansion = func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) {
	buf, err := ioutil.ReadFile(sm.Source)
	if err != nil {
		return sm, err
	}
	expanded := vm.Expand(string(buf))
	return SourceMap{Label: sm.Label, Op: sm.Op, Source: sm.Source, Expanded: expanded, LineNo: sm.LineNo}, nil
}

IncludeExpansion include the filename from Source, expand and copy to Expanded

var OutputExpansion = func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) {
	oSM := vm.Symbols.GetSymbol(sm.Label)
	out := oSM.Expanded
	fname := sm.Source
	err := ioutil.WriteFile(fname, []byte(out), 0666)
	if err != nil {
		return sm, fmt.Errorf("%d Write error %s: %s", sm.LineNo, fname, err)
	}
	return oSM, nil
}

OutputExpansion expanded and write content to file

var OutputExpansions = func(vm *VirtualMachine, sm SourceMap) (SourceMap, error) {
	fp, err := os.Create(sm.Source)
	if err != nil {
		return sm, fmt.Errorf("%d Create error %s: %s", sm.LineNo, sm.Source, err)
	}
	defer fp.Close()
	symbols := vm.Symbols.GetSymbols()
	for _, oSM := range symbols {
		fmt.Fprintln(fp, vm.Expand(oSM.Expanded))
	}
	return sm, nil
}

OutputExpansions write the expanded content out

Functions

func FmtHelp

func FmtHelp(src string, appName string, version string, releaseDate string, releaseHash string) string

FmtHelp lets you process a text block with simple curly brace markup.

Types

type OperatorMap

type OperatorMap map[string]func(*VirtualMachine, SourceMap) (SourceMap, error)

OperatorMap is a map of operator testings and their related functions

type SourceMap

type SourceMap struct {
	Label    string // Label is the symbol to be replace based on Op and Source
	Op       string // Op is the type of assignment being made (if is an empty string if not an assignment)
	Source   string // Source is argument to the right of Op
	Expanded string // Expanded is the value calculated based on Label, Op and Source
	LineNo   int
}

SourceMap holds the source and value of an assignment

type SymbolTable

type SymbolTable struct {
	// contains filtered or unexported fields
}

SymbolTable holds the exressions, values and other errata of parsing assignments making expansions

func (*SymbolTable) GetSymbol

func (st *SymbolTable) GetSymbol(sym string) SourceMap

GetSymbol finds the symbol entry and returns the SourceMap

func (*SymbolTable) GetSymbols

func (st *SymbolTable) GetSymbols() []SourceMap

GetSymbols returns a list of all symbols defined by labels as an array of SourceMaps

func (*SymbolTable) SetSymbol

func (st *SymbolTable) SetSymbol(sm SourceMap) int

SetSymbol adds a SourceMap to entries and points the labels at the most recent definition.

type VirtualMachine

type VirtualMachine struct {
	Symbols   *SymbolTable
	Operators OperatorMap
	Ops       []string
	Help      map[string]string
	// contains filtered or unexported fields
}

VirtualMachine defines the structure which holds symbols, operator map, ops and current prompt setting for a shorthand instance.

func New

func New() *VirtualMachine

New returns a VirtualMachine struct and registers all Operators

func (*VirtualMachine) Apply

func (vm *VirtualMachine) Apply(src []byte) ([]byte, error)

Apply takes a byte array, and processes it returning a byte array. It is like Run but for embedded uses of Shorthand.

func (*VirtualMachine) Eval

func (vm *VirtualMachine) Eval(s string, lineNo int) (string, error)

Eval stores a shorthand assignment or expands and writes the content to stdout Returns the expanded and any error

func (*VirtualMachine) EvalSymbol

func (vm *VirtualMachine) EvalSymbol(sm SourceMap) error

EvalSymbol accepts a symbol (i.e. SourceMap), applies a callback and updates the symbol table

func (*VirtualMachine) Expand

func (vm *VirtualMachine) Expand(text string) string

Expand takes some text and expands all labels to their values

func (*VirtualMachine) Parse

func (vm *VirtualMachine) Parse(s string, lineNo int) SourceMap

Parse a string, return a source map. Takes advantage of the internal ops list. If no valid op is found then return a source map with Label and Op set to an empty string while Source is set the the string that was parsed. Expanded should always be an empty string at the parse stage.

func (*VirtualMachine) RegisterOp

func (vm *VirtualMachine) RegisterOp(op string, callback func(*VirtualMachine, SourceMap) (SourceMap, error), help string) error

RegisterOp associate a operation and function

func (*VirtualMachine) Run

func (vm *VirtualMachine) Run(in *bufio.Reader) int

Run takes a reader (e.g. os.Stdin), and two writers (e.g. os.Stdout and os.Stderr) It reads until EOF, :exit:, or :quit: operation is encountered returns the number of lines processed.

func (*VirtualMachine) SetPrompt

func (vm *VirtualMachine) SetPrompt(s string)

SetPrompt sets the string value of the prompt for a VirtualMachine instance