The polisher Reference Manual

Table of Contents

The polisher Reference Manual

This is the polisher Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 05:49:57 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

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

ASDF

1. Clone or download the latest version from GitHub.
2. Place the directory where your ASDF system can find.
3. 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.

2.1 polisher

Author

mrcdr

Home Page

https://github.com/mrcdr/polisher

License

MIT

Description

Infix notation to S-expression translator

Version

0.1

Dependency

cl-ppcre

Source

polisher.asd (file)

Components

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

3 Modules

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

3.1 polisher/src

Dependency

package.lisp (file)

Parent

polisher (system)

Location

src/

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.

4.1 Lisp

4.1.1 polisher.asd

Location

polisher.asd

Systems

polisher (system)

4.1.2 polisher/package.lisp

Parent

polisher (system)

Location

package.lisp

Packages

polisher

4.1.3 polisher/src/types-svalues.lisp

Parent

src (module)

Location

src/types-svalues.lisp

Exported Definitions

• add-operator (function)
• operator (class)

Internal Definitions

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

4.1.4 polisher/src/tokenizer.lisp

Dependency

types-svalues.lisp (file)

Parent

src (module)

Location

src/tokenizer.lisp

Internal Definitions

• 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)

Parent

src (module)

Location

src/transformer.lisp

Internal Definitions

• 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)

Parent

src (module)

Location

src/interface.lisp

Exported Definitions

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

Internal Definitions

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

5 Packages

Packages are listed by definition order.

5.1 polisher

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

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

Internal Definitions

• *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)
• readable-string (method)
• 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.

6.1 Exported definitions

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 (file)

6.1.2 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 (file)

Function: add-operator OP

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

Package

polisher

Source

types-svalues.lisp (file)

Function: list-operators ()

Return information of registered operators as string.

Package

polisher

Source

interface.lisp (file)

6.1.3 Classes

Class: operator ()

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

Package

polisher

Source

types-svalues.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• readable-string (method)
• print-object (method)
• initialize-instance (method)

Direct slots

Slot: symbol

Symbol used in infix-style.

Type

(quote symbol)

Initargs

:symbol

Slot: function

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

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)

Initargs

:left-associative

Initform

t

6.2 Internal definitions

6.2.1 Special variables

Special Variable: *left-paren*

Package

polisher

Source

types-svalues.lisp (file)

Special Variable: *max-priority*

Package

polisher

Source

types-svalues.lisp (file)

Special Variable: *operator-list*

Package

polisher

Source

types-svalues.lisp (file)

Special Variable: *right-paren*

Package

polisher

Source

types-svalues.lisp (file)

Special Variable: *separator*

Package

polisher

Source

types-svalues.lisp (file)

6.2.2 Macros

Macro: acond &rest CLAUSES

Package

polisher

Source

tokenizer.lisp (file)

6.2.3 Functions

Function: create-operator-regex ()

Package

polisher

Source

tokenizer.lisp (file)

Function: find-split-point FORMULA BEGIN END

Package

polisher

Source

transformer.lisp (file)

Function: infix-to-sexp FORMULA-STR

Package

polisher

Source

interface.lisp (file)

Function: match-length REGEX TARGET-STRING &optional GROUP-INDEX

Package

polisher

Source

tokenizer.lisp (file)

Function: parse-formula FORMULA BEGIN END

Package

polisher

Source

transformer.lisp (file)

Function: parse-value-or-function FORMULA BEGIN END

Package

polisher

Source

transformer.lisp (file)

Function: read-formula STREAM END-CHAR

Package

polisher

Source

interface.lisp (file)

Function: read-safely STR

Package

polisher

Source

tokenizer.lisp (file)

Function: should-be-peeled FORMULA BEGIN END

Package

polisher

Source

transformer.lisp (file)

Function: symbol-to-operator SYMBOL

Package

polisher

Source

types-svalues.lisp (file)

Function: tokenize FORMULA-STR

Package

polisher

Source

tokenizer.lisp (file)

Function: transform-into-sexp FORMULA

Package

polisher

Source

transformer.lisp (file)

6.2.4 Generic functions

Generic Function: readable-string OBJECT

Package

polisher

Source

types-svalues.lisp (file)

Methods

Method: readable-string (OBJECT operator)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types