The mexpr Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The mexpr Reference Manual

This is the mexpr Reference Manual, version 0.2.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 05:19:42 2022 GMT+0.

Table of Contents


1 Introduction

mexpr

Build Status Join the chat at https://gitter.im/tmccombs/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:

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.


Previous: , Up: Systems   [Contents][Index]

2.1 mexpr

Macro for infix math expressions.

Author

Thayne McCombs <bytecurry.software@gmail.com>

License

LLPGL

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 (system).
  • cl-syntax (system).
Source

mexpr.asd.

Child Components

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 mexpr/mexpr.asd

Source

mexpr.asd.

Parent Component

mexpr (system).

ASDF Systems

mexpr.


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.2 mexpr/package.lisp

Source

mexpr.asd.

Parent Component

mexpr (system).

Packages

bytecurry.mexpr.


3.1.3 mexpr/mexpr.lisp

Dependency

package.lisp (file).

Source

mexpr.asd.

Parent Component

mexpr (system).

Public Interface
Internals

Previous: , Up: Lisp   [Contents][Index]

3.1.4 mexpr/operators.lisp

Dependency

mexpr.lisp (file).

Source

mexpr.asd.

Parent Component

mexpr (system).


4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 bytecurry.mexpr

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

Source

package.lisp.

Nickname

mexpr

Use List
  • alexandria.
  • cl-syntax.
  • common-lisp.
Public Interface
Internals

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


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.

Macro: enable-infix-syntax ()

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

Package

bytecurry.mexpr.

Source

mexpr.lisp.

Macro: infix (&rest exprs)

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

Package

bytecurry.mexpr.

Source

mexpr.lisp.


5.1.2 Ordinary functions

Function: infix-reader (stream char narg)

Reader macro function to read infix expressions.

Package

bytecurry.mexpr.

Source

mexpr.lisp.


5.1.3 Generic functions

Generic Reader: syntax-error-type (condition)
Package

bytecurry.mexpr.

Methods
Reader Method: syntax-error-type ((condition syntax-error))
Source

mexpr.lisp.

Target Slot

type.


5.1.4 Conditions

Condition: syntax-error

Error due to invalid syntax in infix expression

Package

bytecurry.mexpr.

Source

mexpr.lisp.

Direct superclasses

error.

Direct methods

syntax-error-type.

Direct slots
Slot: type
Package

common-lisp.

Initargs

:type

Readers

syntax-error-type.

Writers

This slot is read-only.


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *operators*

Hash map of operator symbols to precedence.

Package

bytecurry.mexpr.

Source

mexpr.lisp.


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.2 Ordinary functions

Function: copy-op-state (instance)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: copy-operator (instance)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: do-operation (operator state)

Do the operation for the operands on the stack.

Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: finalize-operations (state)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: get-operator-func (op)

Get the symbol or lambda form for the operator.

Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: get-precedence (op &optional default)

Get the precedence of an operator.

Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: handle-end-group (state)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: handle-expr (state expr)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: make-op-state (&key operands operators)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: make-operator (&key precedence func)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: mexpr-impl (exprs)

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

Package

bytecurry.mexpr.

Source

mexpr.lisp.

Reader: op-state-operands (instance)
Writer: (setf op-state-operands) (instance)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Target Slot

operands.

Reader: op-state-operators (instance)
Writer: (setf op-state-operators) (instance)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Target Slot

operators.

Function: op-state-p (object)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Reader: operator-func (instance)
Writer: (setf operator-func) (instance)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Target Slot

func.

Function: operator-p (object)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Reader: operator-precedence (instance)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Target Slot

precedence.

Function: pop-operand (state)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: pop-operator (state)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: push-operand (op state)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: push-operator (op state)
Package

bytecurry.mexpr.

Source

mexpr.lisp.

Function: reduce-state (state)
Package

bytecurry.mexpr.

Source

mexpr.lisp.


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.3 Structures

Structure: op-state

Structure for state of the operation stacks.

Package

bytecurry.mexpr.

Source

mexpr.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: operands
Type

list

Readers

op-state-operands.

Writers

(setf op-state-operands).

Slot: operators
Type

list

Readers

op-state-operators.

Writers

(setf op-state-operators).

Structure: operator

Struct for information about an operator.

Package

bytecurry.mexpr.

Source

mexpr.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: precedence
Type

integer

Initform

0

Readers

operator-precedence.

Writers

This slot is read-only.

Slot: func
Type

bytecurry.mexpr::form-head

Initform

(quote values)

Readers

operator-func.

Writers

(setf operator-func).


Previous: , Up: Internals   [Contents][Index]

5.2.4 Types

Type: form-head ()

The first subform of a compound form.

Package

bytecurry.mexpr.

Source

mexpr.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
C   D   E   F   G   H   I   M   O   P   R   S  
Index Entry  Section

(
(setf op-state-operands): Private ordinary functions
(setf op-state-operators): Private ordinary functions
(setf operator-func): Private ordinary functions

C
copy-op-state: Private ordinary functions
copy-operator: Private ordinary functions

D
defop: Public macros
do-operation: Private ordinary functions

E
enable-infix-syntax: Public macros

F
finalize-operations: Private ordinary functions
Function, (setf op-state-operands): Private ordinary functions
Function, (setf op-state-operators): Private ordinary functions
Function, (setf operator-func): Private ordinary functions
Function, copy-op-state: Private ordinary functions
Function, copy-operator: Private ordinary functions
Function, do-operation: Private ordinary functions
Function, finalize-operations: Private ordinary functions
Function, get-operator-func: Private ordinary functions
Function, get-precedence: Private ordinary functions
Function, handle-end-group: Private ordinary functions
Function, handle-expr: Private ordinary functions
Function, infix-reader: Public ordinary functions
Function, make-op-state: Private ordinary functions
Function, make-operator: Private ordinary functions
Function, mexpr-impl: Private ordinary functions
Function, op-state-operands: Private ordinary functions
Function, op-state-operators: Private ordinary functions
Function, op-state-p: Private ordinary functions
Function, operator-func: Private ordinary functions
Function, operator-p: Private ordinary functions
Function, operator-precedence: Private ordinary functions
Function, pop-operand: Private ordinary functions
Function, pop-operator: Private ordinary functions
Function, push-operand: Private ordinary functions
Function, push-operator: Private ordinary functions
Function, reduce-state: Private ordinary functions

G
Generic Function, syntax-error-type: Public generic functions
get-operator-func: Private ordinary functions
get-precedence: Private ordinary functions

H
handle-end-group: Private ordinary functions
handle-expr: Private ordinary functions

I
infix: Public macros
infix-reader: Public ordinary functions

M
Macro, defop: Public macros
Macro, enable-infix-syntax: Public macros
Macro, infix: Public macros
make-op-state: Private ordinary functions
make-operator: Private ordinary functions
Method, syntax-error-type: Public generic functions
mexpr-impl: Private ordinary functions

O
op-state-operands: Private ordinary functions
op-state-operators: Private ordinary functions
op-state-p: Private ordinary functions
operator-func: Private ordinary functions
operator-p: Private ordinary functions
operator-precedence: Private ordinary functions

P
pop-operand: Private ordinary functions
pop-operator: Private ordinary functions
push-operand: Private ordinary functions
push-operator: Private ordinary functions

R
reduce-state: Private ordinary functions

S
syntax-error-type: Public generic functions
syntax-error-type: Public generic functions

Jump to:   (  
C   D   E   F   G   H   I   M   O   P   R   S