# The poler Reference Manual

This is the poler Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Aug 15 06:11:28 2024 GMT+0.

## 2 Systems

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

### 2.1 `poler`

Infix notation macro generator

Author

carrotflakes

LLGPL

Long Description

# poler

Poler can generate macros which convert infix notation to prefix notation.
Poler aims to easily build DSL on Common Lisp.
We call the conversion **polish** in poler.

## Usage

“‘ lisp
;; Define a polish macro named ’arithmetic’.
(poler:define-poler arithmetic
(+ :infixl 1)
(- :infixl 1)
(* :infixl 2)
(/ :infixl 2))

;; Then, we can use ’arithmetic’ macro.
(arithmetic 1 + 2 * 3)
; => 7
(macroexpand ’(arithmetic 1 * 2 / (3 + 4 + 5)))
; => (/ (* 1 2) (+ (+ 3 4) 5))
“‘

## Operator definition
A polish needs operator definitions. An operator definition is represented as following:

(name type precedence [replace-name | format])

‘name‘ is a symbol as the operator name.
‘type‘ is a keyword represents the operator type.
‘precedence‘ is a fixnum over 0 represents the operator precedence. The high precedence of operator is, the more prior association of the operators. ‘replace-name‘ is a symbol. See [Name replacement](#name-replacement).
‘format‘ is a form. See [Format of form](#format-of-form).

### Operator types
Poler supports following operator types.

#### ‘:infixl‘
Left-associative infix operator.

(1 + 2 + 3) => (+ (+ 1 2) 3)

#### ‘:infixr‘
Right-associative infix operator.

(1 + 2 + 3) => (+ 1 (+ 2 3))

#### ‘:infix‘
Non-associative infix operator.

(1 + 2 + 3) => (+ 1 2 3)

#### ‘:prefix-n‘ (‘n‘ is a natural number)
‘n‘ operands prefix operator.

; In the case of :prefix-3.
(+ 1 2 3) => (+ 1 2 3)
(+ 1 2) => Illegal.

#### ‘:prefix-*‘
Variable arity prefix operator.

(+ 1 2 3) => (+ 1 2 3)
(+ 1 2) => (+ 1 2)

#### ‘:postfix‘
Unary postfix operator.

(1 +) => (+ 1)

### Name replacement
If you gave ‘replace-name‘ to an operator, the operator name is replaced by ‘replace-name‘ while polishing.

Example:

“‘ lisp
(poler:define-poler arithmetic
(* :infixl 2 mul))

(macroexpand ’(arithmetic 1 + 2 * 3)) ; => (add 1 (mul 2 3))
“‘

Also, if you gave ‘operator-prefix‘ to the polish macro, the operator name is appended ‘operator-prefix‘.

Example:

“‘ lisp
(poler:define-poler arithmetic
(+ :infixl 1)
(* :infixl 2)
:operator-prefix foo-)

(macroexpand ’(arithmetic 1 + 2 * 3)) ; => (foo-+ 1 (foo-* 2 3))
“‘

### Format of form
Usually a polished form shapes such as ‘(operator operand1 operand2 ...)‘, but we can transform the form to any shape also.
The shape is specified by ‘format‘ in the operator definition.
In form ‘format‘, Symbol ‘\$1‘, ‘\$2‘, ... will be replaced with ‘operand1‘, ‘operand2‘, ...
Symbol ‘\$whole‘ will be replaced with ‘(operand1 operand2 ...)‘.

Example:

“‘ lisp
(poler:define-poler combine-string
(+ :infix 1 (concatenate ’string . \$whole))
(* :infixl 2 (apply #’concatenate ’string (make-list \$2 :initial-element \$1))))

(macroexpand ’(combine-string "Ha" + " ha" * 3))
; => (CONCATENATE ’STRING "Ha" (APPLY #’CONCATENATE ’STRING (MAKE-LIST 3 :INITIAL-ELEMENT " ha")))
“‘

## APIs

### Macro: ‘define-poler‘

(define-poler macro-name [operator-definition ...] &key (recursive t) decorate (operator-prefix nil))

Defines a polish macro.

The keyword parameter ‘:recursive‘ enables recursive application to nested form.
The default is ‘t‘.

“‘ lisp
(poler:define-poler foo
(+ :infixl 1)
:recursive nil)

(macroexpand ’(foo 1 + (2 + 3)))
; => (+ 1 (2 + 3))
“‘

The keyword parameter ‘:decorate‘ takes a symbol, if the symbol is non-nil, a result of the polish is decorated with the symbol.

“‘ lisp
(poler:define-poler foo
(+ :infixl 1)
:decorate quote)

(macroexpand ’(foo 1 + 2))
; => ’(+ 1 2)
; i.e. (quote (+ 1 2))
“‘

The keyword parameter ‘:operator-prefix‘ takes a symbol. See [Name replacement](#name-replacement).

“‘ lisp
(poler:define-poler foo
(+ :infixl 1)
(* :infixl 2 *)
:operator-prefix foo-)

(macroexpand ’(foo 1 + 2 * 3))
; => ’(foo-+ 1 (* 2 3))
“‘

### Macro: ‘polish‘

(polish infix-form [operator-definition ...] &key (recursive t) decorate (operator-prefix nil))

‘polish‘ macro look like ‘define-poler‘, but this macro does not define a polish macro, does polish given infix form once.

“‘ lisp
(poler:polish ’(1 + 2 * 3)
(+ :infixl 1)
(- :infixl 1)
(* :infixl 2)
(/ :infixl 2))
; => (+ 1 (* 2 3))
“‘

### Macro: ‘define-operator‘

(define-operator macro-name operator-name type precedence [replace-name | format])

‘define-operator‘ macro adds an operator into the polish macro which is named ‘macro-name‘.
If ‘type‘ is ‘nil‘, the macro removes operator ‘operator-name‘.

“‘ lisp
(poler:define-poler arithmetic
(+ :infix 1)
(* :infixl 2)
(% :infixl 3))

(poler:define-operator arithmetic - :infixl 1) ; add operator -
(poler:define-operator arithmetic + :infixl 1) ; change operator +
(poler:define-operator arithmetic % nil) ; remove operator %
“‘

## Example

“‘ lisp
(defun fact (n)
(if (< 0 n)
(* n (fact (1- n)))
1))

(poler::define-poler arithmetic
(+ :infix 1)
(- :infix 1)
(* :infix 2)
(/ :infix 2)
(% :infixl 2 mod)
(^ :infixr 3 expt)
(! :postfix 4 fact))

(arithmetic 3 ! ^ 2 / 3 - 2)
; => 10
“‘

## Installation

1. Git clone the repository into ‘~/quicklisp/local-projects/‘

## Author

* carrotflakes (carrotflakes@gmail.com)

Version

0.1

Source
Child Component

`src` (module).

## 3 Modules

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

### 3.1 `poler/src`

Source
Parent Component

`poler` (system).

Child Component

`poler.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 `poler/poler.asd`

Source
Parent Component

`poler` (system).

ASDF Systems
Packages

#### 4.1.2 `poler/src/poler.lisp`

Source
Parent Component

`src` (module).

Packages
Public Interface
Internals

## 5 Packages

Packages are listed by definition order.

### 5.1 `poler`

Source
Use List

`common-lisp`.

Public Interface
Internals

### 5.2 `poler-asd`

Source
Use List
• `asdf/interface`.
• `common-lisp`.

## 6 Definitions

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

### 6.1 Public Interface

#### 6.1.1 Special variables

Special Variable: *format-parameter-prefix*
Package
Source
Special Variable: *format-parameter-whole*
Package
Source

#### 6.1.2 Macros

Macro: define-operator (poler-name operator-name type &optional precedence replace-name-or-format)
Package
Source
Macro: define-poler (name &body args)
Package
Source
Macro: polish (infix-form &body args)
Package
Source

#### 6.1.3 Standalone methods

Method: make-load-form ((self `operator`) &optional environment)
Source
Method: print-object ((object `operator`) stream)
Source

### 6.2 Internals

#### 6.2.1 Special variables

Special Variable: *decorator*
Package
Source
Special Variable: *operators*
Package
Source
Special Variable: *recursive*
Package
Source

#### 6.2.2 Ordinary functions

Function: %%define-operator (*operators* operator-source operator-prefix)
Package
Source
Function: apply-format (operator arguments)
Package
Source
Function: apply-operator (tree)
Package
Source
Function: build (infix-form)
Package
Source
Function: build-tree (part-list precedence)
Package
Source
Function: copy-operator (instance)
Package
Source
Function: left-associate (operator arguments &optional associated)
Package
Source
Function: lookup-operator (name)
Package
Source
Function: make-operator (&key name fix arity precedence replace-name format)
Package
Source
Function: merge-part (part1 part2)
Package
Source
Function: new-operator (name type precedence replace-name-or-format operator-prefix)
Package
Source
Writer: (setf operator-arity) (instance)
Package
Source
Target Slot
Writer: (setf operator-fix) (instance)
Package
Source
Target Slot
Writer: (setf operator-format) (instance)
Package
Source
Target Slot
Writer: (setf operator-name) (instance)
Package
Source
Target Slot
Function: operator-p (object)
Package
Source
Writer: (setf operator-precedence) (instance)
Package
Source
Target Slot
Writer: (setf operator-replace-name) (instance)
Package
Source
Target Slot
Function: parse-arguments (args)
Package
Source
Function: part-associativity (part)
Package
Source
Function: part-closed-p (part)
Package
Source
Function: part-precedence (part)
Package
Source
Function: part-union (part argument)
Package
Source
Function: right-associate (operator arguments)
Package
Source

#### 6.2.3 Generic functions

Generic Function: %define-operator (poler-name operator-source)
Package
Source

#### 6.2.4 Structures

Structure: operator
Package
Source
Direct superclasses

`structure-object`.

Direct methods
Direct slots
Slot: name
Writers
Slot: fix
Writers
Slot: arity
Writers
Slot: precedence
`common-lisp`.