The polisher Reference Manual

This is the polisher Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 05:53:12 2022 GMT+0.

1 Introduction

Polisher

Infix notation to S-expression (Polish notation) translator for Common Lisp

Overview

Formulae inside the reader macro #i{ ... } are interpreted as infix notation. If you don't want to use it, the macro polish is available instead.

(polisher:activate-infix-syntax)  ; Activate #i{ ... } reader macro

#i{1+2*3}
;=> 7

(polisher:polish "1+2*3") ; Exactly the same as the above one
;=> 7

#i{1 + 2*3} ; Spaces can be inserted anywhere
;=> 7

#i{2*3/4}
;=> 3/2

#i{2**2**3} ; Identical to 2**(2**3), not (2**2)**3
;=> 256

#i{atan(1.0d0, 1.0d0)}
;=> 0.7853981633974483d0

(flet ((add1 (x) (+ x 1)))
  #i{add1(2)+3})
;=> 6

(defparameter *some-global-value* 1.5) ; The symbol containg operator charcters
#i{1 + 2 * "*some-global-value*"}      ; must be double-quoted
;=> 4.0

#i{2*#c(1 2)+3}
;=> #C(5 4)

#i{#b101 +3} ; Some spaces are needed after #b101
;=> 8

Installation

Quicklisp

If you already have Quicklisp client, just run the following:

(ql:quickload :polisher)

It will resolve dependencies automatically.

Github and Quicklisp

Clone or download the latest version from GitHub.
In the cloned directory, run (ql:register-local-projects).
Now you can use (ql:quickload :polisher) anywhere.

ASDF

Clone or download the latest version from GitHub.
Place the directory where your ASDF system can find.
Run (asdf:load-system :polisher).

Requirements

cl-ppcre
1am (Only if you want to run tests)

Default operators

Following operators are defined by default:

| symbol | function | priority | left associative | |--------|----------|----------|------------------| | + | + | 1 | t | | - | - | 1 | t | | * | * | 2 | t | | / | / | 2 | t | | ** | expt | 3 | nil |

Add your own operator

(polisher:add-operator (make-instance 'polisher:operator
                                      :symbol '^
                                      :function 'expt
                                      :priority 3
                                      :left-associative nil))

#i{2^2^3}
;=> 256

Note that if there are left-associative operators and right-associative operators both having the same priority, formulae can't be evaluated correctly. For example, when op1 is left-associative and op2 is right-associative, x op1 y op2 z can be interpreted as either (x op1 y) op2 z and x op1 (y op2 z).

When you add your own operator, be careful of which package its symbol is interned in.

Restrictions

Symbols start with numbers

Symbols which start with numbers must be double-quoted. The following example shows the reason:

(let ((1e 2))
  #i{1e+1+1})
;=> 11.0

(let ((1e 2))
  #i{"1e"+1+1})
;=> 4

No one defines such an odd symbol? Remember the standard functions 1+ and 1-!

Symbols with vertical bars

Symbols whose symbol-name sandwiched in vertical bars (e.g. |ab de|) can't be used. This is because someone may want to use a vertical bar as the logical OR operator.

Double-quoting is necessary?

The infix formula 1+*global-symbol* can be uniquely interpreted as (+ 1 *global-symbol*), so double-quoting may be unnecessary. However in my opinion, the formula seems very weird when it appears in ALGOL-like languages; so I think double-quoting should be used. In addition, many text editors highlight double-quoted things, helping us to distinguish symbol-names from operators.

License

MIT

Author

mrcdr

2 Systems

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

polisher

2.1 `polisher`

Infix notation to S-expression translator

Author

mrcdr

Home Page

https://github.com/mrcdr/polisher

License

MIT

Version

0.1

Dependency

cl-ppcre (system).

Source

polisher.asd.

Child Components

package.lisp (file).
src (module).

3 Modules

Modules are listed depth-first from the system components tree.

polisher/src

3.1 `polisher/src`

Dependency

package.lisp (file).

Source

polisher.asd.

Parent Component

polisher (system).

Child Components

types-svalues.lisp (file).
tokenizer.lisp (file).
transformer.lisp (file).
interface.lisp (file).

4 Files

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

Lisp

4.1.1 `polisher/polisher.asd`

Source: polisher.asd.
Parent Component: polisher (system).
ASDF Systems: polisher.

4.1.2 `polisher/package.lisp`

Source: polisher.asd.
Parent Component: polisher (system).
Packages: polisher.

4.1.3 `polisher/src/types-svalues.lisp`

Source

polisher.asd.

Parent Component

src (module).

Public Interface

add-operator (function).
initialize-instance (method).
operator (class).
print-object (method).

Internals

*left-paren* (special variable).
*max-priority* (special variable).
*operator-list* (special variable).
*right-paren* (special variable).
*separator* (special variable).
readable-string (generic function).
symbol-to-operator (function).

4.1.4 `polisher/src/tokenizer.lisp`

Dependency

types-svalues.lisp (file).

Source

polisher.asd.

Parent Component

src (module).

Internals

acond (macro).
create-operator-regex (function).
match-length (function).
read-safely (function).
tokenize (function).

4.1.5 `polisher/src/transformer.lisp`

Dependency

tokenizer.lisp (file).

Source

polisher.asd.

Parent Component

src (module).

Internals

find-split-point (function).
parse-formula (function).
parse-value-or-function (function).
should-be-peeled (function).
transform-into-sexp (function).

4.1.6 `polisher/src/interface.lisp`

Dependency

transformer.lisp (file).

Source

polisher.asd.

Parent Component

src (module).

Public Interface

activate-infix-syntax (function).
list-operators (function).
polish (macro).

Internals

infix-to-sexp (function).
read-formula (function).

5 Packages

Packages are listed by definition order.

polisher

5.1 `polisher`

Source

package.lisp.

Use List

common-lisp.

Public Interface

activate-infix-syntax (function).
add-operator (function).
list-operators (function).
operator (class).
polish (macro).

Internals

*left-paren* (special variable).
*max-priority* (special variable).
*operator-list* (special variable).
*right-paren* (special variable).
*separator* (special variable).
acond (macro).
create-operator-regex (function).
find-split-point (function).
infix-to-sexp (function).
match-length (function).
parse-formula (function).
parse-value-or-function (function).
read-formula (function).
read-safely (function).
readable-string (generic function).
should-be-peeled (function).
symbol-to-operator (function).
tokenize (function).
transform-into-sexp (function).

6 Definitions

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

Public Interface
Internals

6.1 Public Interface

Macros
Ordinary functions
Standalone methods
Classes

6.1.1 Macros

Macro: polish (formula-str) ¶

Convert given infix-style formula into S-expression, which will be evaluated as usual lisp form.

Package: polisher.
Source: interface.lisp.

6.1.2 Ordinary functions

Function: activate-infix-syntax (&optional activate dispatch-char) ¶

Activate infix reader-macro #i{...} by default. If the argument "activate" is nil,
deactivate (unregister) #i macro (regardless of whether or not it has been registered by this function). The macro character "i" can be changed by the argument "dispatch-char".

Package: polisher.
Source: interface.lisp.

Function: add-operator (op) ¶

Add infix-style operator, which should be a polisher:operator instance.

Package: polisher.
Source: types-svalues.lisp.

Function: list-operators () ¶

Return information of registered operators as string.

Package: polisher.
Source: interface.lisp.

6.1.3 Standalone methods

Method: initialize-instance :after ((this operator) &rest args) ¶

Source: types-svalues.lisp.

Method: print-object ((this operator) stream) ¶

Source: types-svalues.lisp.

6.1.4 Classes

Class: operator ¶

Operator class, whose instance will usually be registered by polisher:add-operator function.

Package

polisher.

Source

types-svalues.lisp.

Direct methods

initialize-instance.
print-object.
readable-string.

Direct slots

Slot: symbol ¶

Symbol used in infix-style.

Package: common-lisp.
Type: (quote symbol)
Initargs: :symbol

Slot: function ¶

Function to be called, which must receive exactly two arguments.

Package: common-lisp.
Initargs: :function

Slot: priority ¶

Operator priority. Operators will be evaluated from ones having larger priority.

Type: (quote number)
Initargs: :priority

Slot: left-associative ¶

If t, this operator will be left associative (e.g. addition operator +). If nil, this operator will be right associative (e.g. power operator **).

Type: (quote boole)
Initform: t
Initargs: :left-associative

6.2 Internals

Special variables
Macros
Ordinary functions
Generic functions

6.2.1 Special variables

Special Variable: *left-paren* ¶

Package: polisher.
Source: types-svalues.lisp.

Special Variable: *max-priority* ¶

Package: polisher.
Source: types-svalues.lisp.

Special Variable: *operator-list* ¶

Package: polisher.
Source: types-svalues.lisp.

Special Variable: *right-paren* ¶

Package: polisher.
Source: types-svalues.lisp.

Special Variable: *separator* ¶

Package: polisher.
Source: types-svalues.lisp.

6.2.2 Macros

Macro: acond (&rest clauses) ¶

Package: polisher.
Source: tokenizer.lisp.

6.2.3 Ordinary functions

Function: create-operator-regex () ¶

Package: polisher.
Source: tokenizer.lisp.

Function: find-split-point (formula begin end) ¶

Package: polisher.
Source: transformer.lisp.

Function: infix-to-sexp (formula-str) ¶

Package: polisher.
Source: interface.lisp.

Function: match-length (regex target-string &optional group-index) ¶

Package: polisher.
Source: tokenizer.lisp.

Function: parse-formula (formula begin end) ¶

Package: polisher.
Source: transformer.lisp.

Function: parse-value-or-function (formula begin end) ¶

Package: polisher.
Source: transformer.lisp.

Function: read-formula (stream end-char) ¶

Package: polisher.
Source: interface.lisp.

Function: read-safely (str) ¶

Package: polisher.
Source: tokenizer.lisp.

Function: should-be-peeled (formula begin end) ¶

Package: polisher.
Source: transformer.lisp.

Function: symbol-to-operator (symbol) ¶

Package: polisher.
Source: types-svalues.lisp.

Function: tokenize (formula-str) ¶

Package: polisher.
Source: tokenizer.lisp.

Function: transform-into-sexp (formula) ¶

Package: polisher.
Source: transformer.lisp.

6.2.4 Generic functions

Generic Function: readable-string (object) ¶

Package

polisher.

Source

types-svalues.lisp.

Methods

Method: readable-string ((object operator)) ¶

Appendix A Indexes

Concepts
Functions
Variables
Data types

A.1 Concepts

A.2 Functions

Jump to:	A C F G I L M P R S T

	Index Entry	Section

A
	`acond`:	Private macros
	`activate-infix-syntax`:	Public ordinary functions
	`add-operator`:	Public ordinary functions

C
	`create-operator-regex`:	Private ordinary functions

F
	`find-split-point`:	Private ordinary functions
	`Function, activate-infix-syntax`:	Public ordinary functions
	`Function, add-operator`:	Public ordinary functions
	`Function, create-operator-regex`:	Private ordinary functions
	`Function, find-split-point`:	Private ordinary functions
	`Function, infix-to-sexp`:	Private ordinary functions
	`Function, list-operators`:	Public ordinary functions
	`Function, match-length`:	Private ordinary functions
	`Function, parse-formula`:	Private ordinary functions
	`Function, parse-value-or-function`:	Private ordinary functions
	`Function, read-formula`:	Private ordinary functions
	`Function, read-safely`:	Private ordinary functions
	`Function, should-be-peeled`:	Private ordinary functions
	`Function, symbol-to-operator`:	Private ordinary functions
	`Function, tokenize`:	Private ordinary functions
	`Function, transform-into-sexp`:	Private ordinary functions

G
	`Generic Function, readable-string`:	Private generic functions

I
	`infix-to-sexp`:	Private ordinary functions
	`initialize-instance`:	Public standalone methods

L
	`list-operators`:	Public ordinary functions

M
	`Macro, acond`:	Private macros
	`Macro, polish`:	Public macros
	`match-length`:	Private ordinary functions
	`Method, initialize-instance`:	Public standalone methods
	`Method, print-object`:	Public standalone methods
	`Method, readable-string`:	Private generic functions

P
	`parse-formula`:	Private ordinary functions
	`parse-value-or-function`:	Private ordinary functions
	`polish`:	Public macros
	`print-object`:	Public standalone methods

R
	`read-formula`:	Private ordinary functions
	`read-safely`:	Private ordinary functions
	`readable-string`:	Private generic functions
	`readable-string`:	Private generic functions

S
	`should-be-peeled`:	Private ordinary functions
	`symbol-to-operator`:	Private ordinary functions

T
	`tokenize`:	Private ordinary functions
	`transform-into-sexp`:	Private ordinary functions

Jump to:	A C F G I L M P R S T

A.3 Variables

Jump to:	* F L P S

	Index Entry	Section

*
	`left-paren`:	Private special variables
	`max-priority`:	Private special variables
	`operator-list`:	Private special variables
	`right-paren`:	Private special variables
	`separator`:	Private special variables

F
	`function`:	Public classes

L
	`left-associative`:	Public classes

P
	`priority`:	Public classes

S
	`Slot, function`:	Public classes
	`Slot, left-associative`:	Public classes
	`Slot, priority`:	Public classes
	`Slot, symbol`:	Public classes
	`Special Variable, left-paren`:	Private special variables
	`Special Variable, max-priority`:	Private special variables
	`Special Variable, operator-list`:	Private special variables
	`Special Variable, right-paren`:	Private special variables
	`Special Variable, separator`:	Private special variables
	`symbol`:	Public classes

Jump to:	* F L P S

A.4 Data types

Jump to:	C F I M O P S T

	Index Entry	Section

C
	`Class, operator`:	Public classes

F
	`File, interface.lisp`:	The polisher/src/interface․lisp file
	`File, package.lisp`:	The polisher/package․lisp file
	`File, polisher.asd`:	The polisher/polisher․asd file
	`File, tokenizer.lisp`:	The polisher/src/tokenizer․lisp file
	`File, transformer.lisp`:	The polisher/src/transformer․lisp file
	`File, types-svalues.lisp`:	The polisher/src/types-svalues․lisp file

I
	`interface.lisp`:	The polisher/src/interface․lisp file

M
	`Module, src`:	The polisher/src module

O
	`operator`:	Public classes

P
	`Package, polisher`:	The polisher package
	`package.lisp`:	The polisher/package․lisp file
	`polisher`:	The polisher system
	`polisher`:	The polisher package
	`polisher.asd`:	The polisher/polisher․asd file

S
	`src`:	The polisher/src module
	`System, polisher`:	The polisher system

T
	`tokenizer.lisp`:	The polisher/src/tokenizer․lisp file
	`transformer.lisp`:	The polisher/src/transformer․lisp file
	`types-svalues.lisp`:	The polisher/src/types-svalues․lisp file

Jump to:	C F I M O P S T

The polisher Reference Manual

The polisher Reference Manual

Table of Contents

1 Introduction

Polisher

Overview

Installation

Quicklisp

Github and Quicklisp

ASDF

Requirements

Default operators

Add your own operator

Restrictions

Symbols start with numbers

Symbols with vertical bars

Double-quoting is necessary?

License

Author

2 Systems

2.1 polisher

3 Modules

3.1 polisher/src

4 Files

4.1 Lisp

4.1.1 polisher/polisher.asd

4.1.2 polisher/package.lisp

4.1.3 polisher/src/types-svalues.lisp

4.1.4 polisher/src/tokenizer.lisp

4.1.5 polisher/src/transformer.lisp

4.1.6 polisher/src/interface.lisp

5 Packages

5.1 polisher

6 Definitions

6.1 Public Interface

6.1.1 Macros

6.1.2 Ordinary functions

6.1.3 Standalone methods

6.1.4 Classes

6.2 Internals

6.2.1 Special variables

6.2.2 Macros

6.2.3 Ordinary functions

6.2.4 Generic functions

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types

2.1 `polisher`

3.1 `polisher/src`

4.1.1 `polisher/polisher.asd`

4.1.2 `polisher/package.lisp`

4.1.3 `polisher/src/types-svalues.lisp`

4.1.4 `polisher/src/tokenizer.lisp`

4.1.5 `polisher/src/transformer.lisp`

4.1.6 `polisher/src/interface.lisp`

5.1 `polisher`