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 Wed May 15 06:33:09 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 poler

Infix notation macro generator

Author

carrotflakes

License

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 1 add)
(* :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/‘
2. ‘(ql:quickload :poler)‘

## Author

* carrotflakes (carrotflakes@gmail.com)

## Copyright

Copyright (c) 2015 carrotflakes (carrotflakes@gmail.com)

## License

Licensed under the LLGPL License.

Version

0.1

Source

poler.asd.

Child Component

src (module).


3 Modules

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


3.1 poler/src

Source

poler.asd.

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

poler.asd.

Parent Component

poler (system).

ASDF Systems

poler.

Packages

poler-asd.


4.1.2 poler/src/poler.lisp

Source

poler.asd.

Parent Component

src (module).

Packages

poler.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 poler

Source

poler.lisp.

Use List

common-lisp.

Public Interface
Internals

5.2 poler-asd

Source

poler.asd.

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

poler.

Source

poler.lisp.

Special Variable: *format-parameter-whole*
Package

poler.

Source

poler.lisp.


6.1.2 Macros

Macro: define-operator (poler-name operator-name type &optional precedence replace-name-or-format)
Package

poler.

Source

poler.lisp.

Macro: define-poler (name &body args)
Package

poler.

Source

poler.lisp.

Macro: polish (infix-form &body args)
Package

poler.

Source

poler.lisp.


6.1.3 Standalone methods

Method: make-load-form ((self operator) &optional environment)
Source

poler.lisp.

Method: print-object ((object operator) stream)
Source

poler.lisp.


6.2 Internals


6.2.1 Special variables

Special Variable: *decorator*
Package

poler.

Source

poler.lisp.

Special Variable: *operators*
Package

poler.

Source

poler.lisp.

Special Variable: *recursive*
Package

poler.

Source

poler.lisp.


6.2.2 Ordinary functions

Function: %%define-operator (*operators* operator-source operator-prefix)
Package

poler.

Source

poler.lisp.

Function: apply-format (operator arguments)
Package

poler.

Source

poler.lisp.

Function: apply-operator (tree)
Package

poler.

Source

poler.lisp.

Function: build (infix-form)
Package

poler.

Source

poler.lisp.

Function: build-tree (part-list precedence)
Package

poler.

Source

poler.lisp.

Function: copy-operator (instance)
Package

poler.

Source

poler.lisp.

Function: left-associate (operator arguments &optional associated)
Package

poler.

Source

poler.lisp.

Function: lookup-operator (name)
Package

poler.

Source

poler.lisp.

Function: make-operator (&key name fix arity precedence replace-name format)
Package

poler.

Source

poler.lisp.

Function: merge-part (part1 part2)
Package

poler.

Source

poler.lisp.

Function: new-operator (name type precedence replace-name-or-format operator-prefix)
Package

poler.

Source

poler.lisp.

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

poler.

Source

poler.lisp.

Target Slot

arity.

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

poler.

Source

poler.lisp.

Target Slot

fix.

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

poler.

Source

poler.lisp.

Target Slot

format.

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

poler.

Source

poler.lisp.

Target Slot

name.

Function: operator-p (object)
Package

poler.

Source

poler.lisp.

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

poler.

Source

poler.lisp.

Target Slot

precedence.

Reader: operator-replace-name (instance)
Writer: (setf operator-replace-name) (instance)
Package

poler.

Source

poler.lisp.

Target Slot

replace-name.

Function: parse-arguments (args)
Package

poler.

Source

poler.lisp.

Function: part-associativity (part)
Package

poler.

Source

poler.lisp.

Function: part-closed-p (part)
Package

poler.

Source

poler.lisp.

Function: part-precedence (part)
Package

poler.

Source

poler.lisp.

Function: part-union (part argument)
Package

poler.

Source

poler.lisp.

Function: right-associate (operator arguments)
Package

poler.

Source

poler.lisp.


6.2.3 Generic functions

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

poler.

Source

poler.lisp.


6.2.4 Structures

Structure: operator
Package

poler.

Source

poler.lisp.

Direct superclasses

structure-object.

Direct methods
Direct slots
Slot: name
Readers

operator-name.

Writers

(setf operator-name).

Slot: fix
Readers

operator-fix.

Writers

(setf operator-fix).

Slot: arity
Readers

operator-arity.

Writers

(setf operator-arity).

Slot: precedence
Readers

operator-precedence.

Writers

(setf operator-precedence).

Slot: replace-name
Readers

operator-replace-name.

Writers

(setf operator-replace-name).

Slot: format
Package

common-lisp.

Readers

operator-format.

Writers

(setf operator-format).


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
A   B   C   D   F   G   L   M   N   O   P   R  
Index Entry  Section

%
%%define-operator: Private ordinary functions
%define-operator: Private generic functions

(
(setf operator-arity): Private ordinary functions
(setf operator-fix): Private ordinary functions
(setf operator-format): Private ordinary functions
(setf operator-name): Private ordinary functions
(setf operator-precedence): Private ordinary functions
(setf operator-replace-name): Private ordinary functions

A
apply-format: Private ordinary functions
apply-operator: Private ordinary functions

B
build: Private ordinary functions
build-tree: Private ordinary functions

C
copy-operator: Private ordinary functions

D
define-operator: Public macros
define-poler: Public macros

F
Function, %%define-operator: Private ordinary functions
Function, (setf operator-arity): Private ordinary functions
Function, (setf operator-fix): Private ordinary functions
Function, (setf operator-format): Private ordinary functions
Function, (setf operator-name): Private ordinary functions
Function, (setf operator-precedence): Private ordinary functions
Function, (setf operator-replace-name): Private ordinary functions
Function, apply-format: Private ordinary functions
Function, apply-operator: Private ordinary functions
Function, build: Private ordinary functions
Function, build-tree: Private ordinary functions
Function, copy-operator: Private ordinary functions
Function, left-associate: Private ordinary functions
Function, lookup-operator: Private ordinary functions
Function, make-operator: Private ordinary functions
Function, merge-part: Private ordinary functions
Function, new-operator: Private ordinary functions
Function, operator-arity: Private ordinary functions
Function, operator-fix: Private ordinary functions
Function, operator-format: Private ordinary functions
Function, operator-name: Private ordinary functions
Function, operator-p: Private ordinary functions
Function, operator-precedence: Private ordinary functions
Function, operator-replace-name: Private ordinary functions
Function, parse-arguments: Private ordinary functions
Function, part-associativity: Private ordinary functions
Function, part-closed-p: Private ordinary functions
Function, part-precedence: Private ordinary functions
Function, part-union: Private ordinary functions
Function, right-associate: Private ordinary functions

G
Generic Function, %define-operator: Private generic functions

L
left-associate: Private ordinary functions
lookup-operator: Private ordinary functions

M
Macro, define-operator: Public macros
Macro, define-poler: Public macros
Macro, polish: Public macros
make-load-form: Public standalone methods
make-operator: Private ordinary functions
merge-part: Private ordinary functions
Method, make-load-form: Public standalone methods
Method, print-object: Public standalone methods

N
new-operator: Private ordinary functions

O
operator-arity: Private ordinary functions
operator-fix: Private ordinary functions
operator-format: Private ordinary functions
operator-name: Private ordinary functions
operator-p: Private ordinary functions
operator-precedence: Private ordinary functions
operator-replace-name: Private ordinary functions

P
parse-arguments: Private ordinary functions
part-associativity: Private ordinary functions
part-closed-p: Private ordinary functions
part-precedence: Private ordinary functions
part-union: Private ordinary functions
polish: Public macros
print-object: Public standalone methods

R
right-associate: Private ordinary functions