The mexpr Reference Manual

Table of Contents

The mexpr Reference Manual

This is the mexpr Reference Manual, version 0.2.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Thu Mar 11 14:12:20 2021 GMT+0.

1 Introduction

mexpr

Macro for Common Lisp to allow infix syntax for mathematical expressions.

The mexpr package contains the infix macro which converts infix expressions into Lisp S-Expressions.

Installation

The easiest way to install mexpr is with quicklisp.

(ql:quickload :mexpr)

Examples

The following are examples of how the infix macro can be used:

CL-USER> (infix 3 + 4)
7
CL-USER> (infix [ 3 + 4 ] * 5)
35
CL-USER (infix 3 + 4 * 5)
23
CL-USER> (let ((x 0))
	   		   (infix [ 4 + (1+ x) ] / (sqrt 4)))
2.5
CL-USER> (infix 4 + 4 < 7 or 2 > 6 / 16)
T
CL-USER> (infix 5 = 6)
NIL
CL-USER> (infix 5 = 5)
T
CL-USER> (infix 2 expt 5)
32

You can use defop to add new operators:

CL-USER> (defop union 10) ; use function name and precedence
CL-USER> (infix '(1 2) union '(2 3))
(2 1 3 4)
CL-USER> (defop ++ 100 append) ; use operator symbol, precedence, and defition symbol
CL-USER> (infix '(1 2) ++ '(3 4))
(1 2 3 4)
CL-USER> (defop p 110 (lambda (a b) (+ (* a a) (* b b)))) ; use lambda for definition
CL-USER> (infix 3 p 4)
25

You can use a reader macro to make it a little simpler:

CL-USER> (enable-infix-syntax) ; equivalent to (cl-syntax:use-syntax :mexpr)
CL-USER> #n(3 + 4 ** 2)
19

Notes:

1. There always needs to be whitespace between operands and operators.
2. Variables and other forms can be used as operands.
3. Operators have an associated precedence. Higher precedence operators are performed first.
4. Operators of equal precedence are evaluated left to right.
5. [ and ] are used for grouping expressions (overriding precedence).

Usage

The mexpr (or more verbose bytecurry.mexpr) package contains two main macros.

The infix macro parses it's arguments as an infix expression and produces the corresponding s-expression. Each argument is evaluated as one of the following forms:

• Grouping: The special forms [ and ] are used for grouping expressions. (Parentheses were already taken.)
• Operator: An operator is a symbol that has been registered using the defop macro. It represents a binary operation.
• Operand: An operand is any form which is not an operator. This means that normal prefix forms can be embedded in the infix expression.

The infix macro can detect some syntax errors, in which case it will create a syntax-error condition. The type of the syntax error can be obtained with syntax-error-type. Unfortunately, at the moment some invalid forms simply produce strange results, such as a transposition of a operator and operand.

The defop macro can be used to define new operators. It takes two parameters, the first is the unquoted symbol of the operator, the second is the desired precedence of the operator (see below for precedence table). The symbol should correspond to a function or macro which can accept exactly two arguments (although it may have more optional arguments).

The function infix-reader is macro dispatch function which is available to the user to use in any reader macro he/she desires. The package also registers the "#n" dispatch with cl-syntax, so you can enable syntax of the form #n(<expr>) with (cl-syntax:use-syntax :mexpr). Alternatively, enable-infix-syntax is a wrapper around cl-syntax:use-syntax.

Precedence

Unlike prefix and postfix notations, infix notation uses operator precedence to determine the order of evaluation. mexpr uses a numeric precedence system, where the precedence of an operator is a positive integer. A higher number corresponds to a higher precedence. The precedence of the default operators is given below:

| Operator | Precedence | Translation of a <op> b |:----------:|-----------:|:-------------------------- | ** | 110 | (expt a b) | expt | 110 | (expt a b) | * | 100 | (* a b) | / | 100 | (/ a b) | % | 100 | (mod a b) | mod | 100 | (mod a b) | rem | 100 | (rem a b) | + | 90 | (+ a b) | - | 90 | (- a b) | ash | 80 | (ash a b) | << | 80 | (ash a b) | >> | 80 | (ash a (- b)) | < | 70 | (< a b) | > | 70 | (> a b) | <= | 70 | (<= a b) | >= | 70 | (>= a b) | = | 60 | (= a b) | /= | 60 | (/= a b) | logand | 50 | (logand a b) | & | 50 | (logand a b) | logxor | 40 | (logxor a b) | ^ | 40 | (logxor a b) | logior | 30 | (logior a b) | \|| 30 | (logior a b) | and | 20 | (and a b) | or | 10 | (or a b)

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 mexpr

Author

Thayne McCombs <bytecurry.software@gmail.com>

License

LLPGL

Description

Macro for infix math expressions.

Long Description

mexpr is a library which contains a macro for
embedding mathematical expressions in lisp code with a more traditional infix syntax. It also contains a reader macro for said syntax, and a macro to extend the syntax with additional operators.

Version

0.2.0

Dependencies

• alexandria
• cl-syntax

Source

mexpr.asd (file)

Components

• package.lisp (file)
• mexpr.lisp (file)
• operators.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 mexpr.asd

Location

mexpr.asd

Systems

mexpr (system)

3.1.2 mexpr/package.lisp

Parent

mexpr (system)

Location

package.lisp

Packages

bytecurry.mexpr

3.1.3 mexpr/mexpr.lisp

Dependency

package.lisp (file)

Parent

mexpr (system)

Location

mexpr.lisp

Exported Definitions

• defop (macro)
• enable-infix-syntax (macro)
• infix (macro)
• infix-reader (function)
• syntax-error (condition)
• syntax-error-type (method)

Internal Definitions

• *operators* (special variable)
• copy-op-state (function)
• copy-operator (function)
• do-operation (function)
• finalize-operations (function)
• form-head (type)
• get-operator-func (function)
• get-precedence (function)
• handle-end-group (function)
• handle-expr (function)
• make-op-state (function)
• make-operator (function)
• mexpr-impl (function)
• op-state (structure)
• op-state-operands (function)
• (setf op-state-operands) (function)
• op-state-operators (function)
• (setf op-state-operators) (function)
• op-state-p (function)
• operator (structure)
• operator-func (function)
• (setf operator-func) (function)
• operator-p (function)
• operator-precedence (function)
• pop-operand (function)
• pop-operator (function)
• push-operand (function)
• push-operator (function)
• reduce-state (function)

3.1.4 mexpr/operators.lisp

Dependency

mexpr.lisp (file)

Parent

mexpr (system)

Location

operators.lisp

4 Packages

Packages are listed by definition order.

4.1 bytecurry.mexpr

A library for embedding mathematical expressions in lisp code using traditional infix syntax.

Source

package.lisp (file)

Nickname

mexpr

Use List

• cl-syntax
• alexandria
• common-lisp

Exported Definitions

• defop (macro)
• enable-infix-syntax (macro)
• infix (macro)
• infix-reader (function)
• syntax-error (condition)
• syntax-error-type (generic function)
• syntax-error-type (method)

Internal Definitions

• *operators* (special variable)
• copy-op-state (function)
• copy-operator (function)
• do-operation (function)
• finalize-operations (function)
• form-head (type)
• get-operator-func (function)
• get-precedence (function)
• handle-end-group (function)
• handle-expr (function)
• make-op-state (function)
• make-operator (function)
• mexpr-impl (function)
• op-state (structure)
• op-state-operands (function)
• (setf op-state-operands) (function)
• op-state-operators (function)
• (setf op-state-operators) (function)
• op-state-p (function)
• operator (structure)
• operator-func (function)
• (setf operator-func) (function)
• operator-p (function)
• operator-precedence (function)
• pop-operand (function)
• pop-operator (function)
• push-operand (function)
• push-operator (function)
• reduce-state (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Macros

Macro: defop NAME PRECEDENCE &optional FUNC

Define a new infix operator with the given name and precedence.

NAME is the symbol which will be used as a binary operator in an infix expression PRECEDENCE is a positive integer for the precedence of the operator
FUNC is a symbol or lambda form that the operator will translate into during macro-expansion

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Macro: enable-infix-syntax ()

Enable infix syntax with ’#n’, for example: #n(3 + 4) => 7

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Macro: infix &rest EXPRS

Macro to convert an infix expression, into an s-expression.

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

5.1.2 Functions

Function: infix-reader STREAM CHAR NARG

Reader macro function to read infix expressions.

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

5.1.3 Generic functions

Generic Function: syntax-error-type CONDITION

Package

bytecurry.mexpr

Methods

Method: syntax-error-type (CONDITION syntax-error)

Source

mexpr.lisp (file)

5.1.4 Conditions

Condition: syntax-error ()

Error due to invalid syntax in infix expression

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Direct superclasses

error (condition)

Direct methods

syntax-error-type (method)

Direct slots

Slot: type

Initargs

:type

Readers

syntax-error-type (generic function)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *operators*

Hash map of operator symbols to precedence.

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

5.2.2 Functions

Function: copy-op-state INSTANCE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: copy-operator INSTANCE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: do-operation OPERATOR STATE

Do the operation for the operands on the stack.

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: finalize-operations STATE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: get-operator-func OP

Get the symbol or lambda form for the operator.

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: get-precedence OP &optional DEFAULT

Get the precedence of an operator.

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: handle-end-group STATE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: handle-expr STATE EXPR

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: make-op-state &key (OPERANDS OPERANDS) (OPERATORS OPERATORS)

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: make-operator &key (PRECEDENCE PRECEDENCE) (FUNC FUNC)

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: mexpr-impl EXPRS

Convert an infix expression, into an s-expression –implementation.

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: op-state-operands INSTANCE

Function: (setf op-state-operands) VALUE INSTANCE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: op-state-operators INSTANCE

Function: (setf op-state-operators) VALUE INSTANCE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: op-state-p OBJECT

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: operator-func INSTANCE

Function: (setf operator-func) VALUE INSTANCE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: operator-p OBJECT

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: operator-precedence INSTANCE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: pop-operand STATE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: pop-operator STATE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: push-operand OP STATE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: push-operator OP STATE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Function: reduce-state STATE

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

5.2.3 Structures

Structure: op-state ()

Structure for state of the operation stacks.

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: operands

Type

list

Readers

op-state-operands (function)

Writers

(setf op-state-operands) (function)

Slot: operators

Type

list

Readers

op-state-operators (function)

Writers

(setf op-state-operators) (function)

Structure: operator ()

Struct for information about an operator.

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: precedence

Type

integer

Initform

0

Readers

operator-precedence (function)

Writers

(setf operator-precedence) (function)

Slot: func

Type

bytecurry.mexpr::form-head

Initform

(quote values)

Readers

operator-func (function)

Writers

(setf operator-func) (function)

5.2.4 Types

Type: form-head ()

The first subform of a compound form.

Package

bytecurry.mexpr

Source

mexpr.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types