README
¶
Purposes of Macro Languages
TeX features a powerful macro language. For newcomers to TeX-typesetting its language may look cumbersome—or even ugly or funny—but it is well thought out and surprisingly versatile. It serves a couple of purposes, which we will discuss.
- Configurability
- Adaptability
- Extensibility
Configurability
When formatting your text you want to be able to configure a lot of things: fonts, colors, running headers, etc. Necessary configuration is often done in templates, but plain TeX does not support a templating mechnism. Instead, configuration is provided through a macro file.
Adaptability
TeX is used for all kinds of "documents." Obviously, it has been created for scientific papers and books, possibly heavy on mathematics, but over the year TeX has found usages besides that as well: music notes, chemistry, school books, and others. This testifies the versatility gained by the TeX macro language.
Extensibility
The best software systems usually provide a means of extending their
functionality. TeX does this by providing hooks which may be extended or
overridden by macros. Examples are token registers like everypar or
the page output routine. There is even a generic extension mechanism called
specials, which can be used for all kinds of additional functionality.
Lua
Modern versions of TeX support Lua as an extension language. Embedding Lua in an application is all the rage today, and we will follow this tradition. However, we will employ at least one Domain Specific Language: a derivate of MetaPost, which will be called (working title) "Poor Man's MetaPost" (PMMPost). MetaPost includes a powerful macro-language, which we will not support. Instead, we will make PMMPost extensible via Lua.
Parser Generators
We use ANTLR V4 as our goto-tool for implementing grammars, e.g., for PMMPost. Additionally we will create an experimental GLR parser. It is intended for parsing Markdown, but the idea still needs some working-on.
Documentation
¶
Index ¶
- type Assignable
- type ExprNode
- func NewNumericExpression(p arithm.Polynomial) *ExprNode
- func NewNumericVarExpression(v Symbol) *ExprNode
- func NewOtherExpression(something interface{}) *ExprNode
- func NewPairExpression(xp arithm.Polynomial, yp arithm.Polynomial) *ExprNode
- func NewPairVarExpression(xpart Symbol, ypart Symbol) *ExprNode
- type ExprStack
- func (es *ExprStack) AddTOS2OS() error
- func (es *ExprStack) AnnounceVariable(v Symbol)
- func (es *ExprStack) CheckOperands(n int, op string) error
- func (es *ExprStack) DivideTOS2OS() error
- func (es *ExprStack) Dump()
- func (es *ExprStack) EncapsuleVariable(id int)
- func (es *ExprStack) EquateTOS2OS() error
- func (es *ExprStack) GetVariable(e *ExprNode) Symbol
- func (es *ExprStack) GetVariableName(id int) string
- func (es *ExprStack) Interpolate() (err error)
- func (es *ExprStack) InterpolatePair(n *ExprNode, z1 *ExprNode, z2 *ExprNode) error
- func (es *ExprStack) IsCapsule(id int) bool
- func (es *ExprStack) IsEmpty() bool
- func (es *ExprStack) LengthTOS() error
- func (es *ExprStack) MultiplyTOS2OS() error
- func (es *ExprStack) Pop() (*ExprNode, bool)
- func (es *ExprStack) PopAsNumeric() (dec.Decimal, bool)
- func (es *ExprStack) PopAsOther() (interface{}, bool)
- func (es *ExprStack) PopAsPair() (arithm.Pair, bool)
- func (es *ExprStack) Push(e *ExprNode) *ExprStack
- func (es *ExprStack) PushConstant(c dec.Decimal) *ExprStack
- func (es *ExprStack) PushOtherConstant(o interface{}) *ExprStack
- func (es *ExprStack) PushPairConstant(pc arithm.Pair) *ExprStack
- func (es *ExprStack) PushPairVariable(XPart Symbol, xconst dec.Decimal, YPart Symbol, yconst dec.Decimal) *ExprStack
- func (es *ExprStack) PushVariable(v Symbol, w Symbol) *ExprStack
- func (es *ExprStack) Rotate2OSbyTOS() error
- func (es *ExprStack) SetVariableSolved(id int, val dec.Decimal)
- func (es *ExprStack) Size() int
- func (es *ExprStack) SubtractTOS2OS() error
- func (es *ExprStack) Summary()
- func (es *ExprStack) Top() *ExprNode
- func (es *ExprStack) TraceString(e *ExprNode) string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Assignable ¶
type Assignable interface {
GetValue() interface{}
SetValue(interface{})
IsKnown() bool
}
Some symbols are lvalues, i.e. can be assigned a value
type ExprNode ¶
type ExprNode struct {
XPolyn arithm.Polynomial
YPolyn arithm.Polynomial
IsPair bool
Other interface{}
}
Expressions will contain linear polynomials, possibly with variables of unknown value. Expressions are either of type pair or type numeric. Numeric expressions are modelled as pair values, with the y-part set to 0.
Sometimes it is convenient to push a different type of expression onto the stack (or to complement a numeric expression with additional info), so expressions are allowed to point to 'other' data (GetOther()).
func NewNumericExpression ¶
func NewNumericExpression(p arithm.Polynomial) *ExprNode
Create a new expression node given a polynomial.
func NewNumericVarExpression ¶
func NewNumericVarExpression(v Symbol) *ExprNode
Create a non-constant numeric expression node.
func NewOtherExpression ¶
func NewOtherExpression(something interface{}) *ExprNode
Create an expression node with other information
func NewPairExpression ¶
func NewPairExpression(xp arithm.Polynomial, yp arithm.Polynomial) *ExprNode
Create a new pair expression node. Arguments are x-part and y-part for the pair. If no y-part is supplied, the type of the expression will still be type pair – although an invalid one.
func NewPairVarExpression ¶
func NewPairVarExpression(xpart Symbol, ypart Symbol) *ExprNode
Create a non-constant pair expression node. Arguments are x-part and y-part for the pair.
type ExprStack ¶
type ExprStack struct {
// contains filtered or unexported fields
}
Type ExprStack. This implements a stack of numeric or pair expressions. Various mathematical operations may be performed on the stack values.
The expression stack is connected to a system of linear equations (LEQ). If an equation is constructed from 2 polynomials, it is put into the LEQ. The LEQ operates on generic identifiers and knows nothing of the 'real life' symbols we use in the parser. The expression stack is a bridge between both worlds: It holds a table (VariableResolver) to map LEQ-internal variables to real-life symbols. The variable resolver will receive a message from the LEQ whenever an equation gets solved, i.e. variables become known.
The connection between symbols and LEQ-variables is by symbol-ID: symbol "a" with ID=7 will be x.7 in LEQ.
func NewExprStack ¶
func NewExprStack() *ExprStack
Create a new expression stack. It is fully initialized and empty.
func (*ExprStack) AnnounceVariable ¶
func (es *ExprStack) AnnounceVariable(v Symbol)
Give notice of a new variable used in expressions / polynomials. This will put the variable's symbol into the variable resolver's table.
Example: symbol "a"|ID=7 ⟹ resolver table[7] = "a"
If a variable ID is not known by the resolver, it is assumed to be a "capsule", which is MetaFont's notation for a variable that has fallen out of scope.
func (*ExprStack) CheckOperands ¶
Check the operands on the stack for an arithmetic operation. Currently will panic if operands are invalid or not enough operands (n) on stack.
func (*ExprStack) DivideTOS2OS ¶
Divide 2ndOS by TOS. Divisor must be numeric non-0 constant.
func (*ExprStack) Dump ¶
func (es *ExprStack) Dump()
Internal helper: dump expression stack. This is printed to the trace with level=DEBUG.
func (*ExprStack) EncapsuleVariable ¶
Drop the name of a variable from the variable resolver. The variable itself is not dropped, but rather lives on as an anonymous quantity (i.e., a capsule) as long as it is part of an equation.
func (*ExprStack) EquateTOS2OS ¶
Create an equation of the polynomials of TOS and 2ndOS. Introduces the equation to the solver's linear equation system.
If the polynomials are of type pair polynomial, then there will be 2 equations, one for the x-part and one for the y-part. LEQ will only handle numeric linear equations.
func (*ExprStack) GetVariable ¶
If an expression is a simple variable reference, return the symbol / variable reference. The variable must have been previously announced (see PushVariable(v)).
func (*ExprStack) GetVariableName ¶
Return the name of a variable, given its ID. Will return the string "?nnnn" for capsules.
Interface VariableResolver.
func (*ExprStack) Interpolate ¶
Numeric interpolation operation. Either n must be known or a and b. Calulated as:
n[a,b] ⟹ a - na + nb.
func (*ExprStack) InterpolatePair ¶
Pair interpolation operation. Either n must be known or z1 and z2.
n[z1,z2] ⟹ z1 - n*z1 + n*z2.
func (*ExprStack) IsCapsule ¶
Is a variable (index) a capsule, i.e., has it gone out of scope? The terminus stems from MetaFont (with "whatever" being a prominent example for a capsule).
Interface VariableResolver.
func (*ExprStack) LengthTOS ¶
Length of a pair (i.e., distance from origin). Argument must be a known pair.
func (*ExprStack) MultiplyTOS2OS ¶
Multiply TOS and 2ndOS. One multiplicant must be a known numeric constant.
func (*ExprStack) PopAsNumeric ¶
Convenience method: return TOS as a numeric constant.
func (*ExprStack) PopAsOther ¶
Convenience method: return TOS as interface{}
func (*ExprStack) PopAsPair ¶
Convenience method: return TOS as a pair constant. If TOS is not a known pair, returns (0,0) and false.
func (*ExprStack) PushConstant ¶
Push a numeric constant onto the stack. It will be wrapped into a polynomial p = c. For pair constants use PushPairConstant(c).
func (*ExprStack) PushOtherConstant ¶
Push a typeless constant onto the stack.
func (*ExprStack) PushPairConstant ¶
Push a pair constant onto the stack. It will be wrapped into a polynomial p = c. For numeric constants use PushConstant(c).
func (*ExprStack) PushPairVariable ¶
func (es *ExprStack) PushPairVariable(XPart Symbol, xconst dec.Decimal, YPart Symbol, yconst dec.Decimal) *ExprStack
Push a pair variable onto the stack. The ID of the variable must be > 0 ! It will be wrapped into two polynomials p = 0 + 1 * xpart/ypart(v).
func (*ExprStack) PushVariable ¶
Push a variable onto the stack. The ID of the variable must be > 0 ! It will be wrapped into a polynomial p = 0 + 1 * v. If the variable is of type pair we will push a pair expression.
func (*ExprStack) Rotate2OSbyTOS ¶
Rotate a pair around origin for TOS degrees, counterclockwise. TOS must be a known numeric constant.
func (*ExprStack) SetVariableSolved ¶
Set the value of a variable. If the LEQ solves a variable and it becomes known, the LEQ will send us this message.
Interface VariableResolver.
func (*ExprStack) SubtractTOS2OS ¶
Subtract TOS from 2ndOS. Allowed for known and unknown terms.
func (*ExprStack) Summary ¶
func (es *ExprStack) Summary()
Print a summary of LEQ and stack contents.
func (*ExprStack) TraceString ¶
Pretty print an expression.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package corelang implements core commands for DSLs dealing with arithmetic expressions, pairs and paths.
|
Package corelang implements core commands for DSLs dealing with arithmetic expressions, pairs and paths. |
|
Package pmmpost implements an interpreter for "Poor Man's MetaPost".
|
Package pmmpost implements an interpreter for "Poor Man's MetaPost". |
|
grammar
Package grammar contains generated Go code produced by ANTLR V4.
|
Package grammar contains generated Go code produced by ANTLR V4. |
|
listener
Package listener exposes listener function implementations for ANTLR V4.
|
Package listener exposes listener function implementations for ANTLR V4. |
|
Package runtime implements an interpreter runtime, consisting of scopes, memory frames and symbols (variable declarations and references).
|
Package runtime implements an interpreter runtime, consisting of scopes, memory frames and symbols (variable declarations and references). |
|
Package variables implements variables for programming languages similar to those in MetaFont and MetaPost.
|
Package variables implements variables for programming languages similar to those in MetaFont and MetaPost. |
|
grammar
Package grammar contains generated Go code produced by ANTLR V4.
|
Package grammar contains generated Go code produced by ANTLR V4. |
|
varparse
Package varparse implements a parser to get variable references from strings.
|
Package varparse implements a parser to get variable references from strings. |