The poler Reference Manual

Table of Contents

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

The poler Reference Manual

This is the poler Reference Manual, version 0.1, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Apr 08 14:46:54 2019 GMT+0.


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

1 Introduction

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

;; 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.
format is a form. See 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:

(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:

(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:

(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.

(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.

(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.

(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.

(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.

(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

(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

Copyright

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

License

Licensed under the LLGPL License.


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

2 Systems

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


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

2.1 poler

Author

carrotflakes

License

LLGPL

Description

Infix notation macro generator

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

Component

src (module)


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

3 Modules

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


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

3.1 poler/src

Parent

poler (system)

Location

src/

Component

poler.lisp (file)


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

4 Files

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


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

4.1 Lisp


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

4.1.1 poler.asd

Location

poler.asd

Systems

poler (system)

Packages

poler-asd


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

4.1.2 poler/src/poler.lisp

Parent

src (module)

Location

src/poler.lisp

Packages

poler

Exported Definitions
Internal Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 poler-asd

Source

poler.asd

Use List

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

5.2 poler

Source

poler.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Special variables

Special Variable: *format-parameter-prefix*
Package

poler

Source

poler.lisp (file)

Special Variable: *format-parameter-whole*
Package

poler

Source

poler.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Macros

Macro: define-operator POLER-NAME OPERATOR-NAME TYPE &optional PRECEDENCE REPLACE-NAME-OR-FORMAT
Package

poler

Source

poler.lisp (file)

Macro: define-poler NAME &body ARGS
Package

poler

Source

poler.lisp (file)

Macro: polish INFIX-FORM &body ARGS
Package

poler

Source

poler.lisp (file)


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

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Special variables

Special Variable: *decorator*
Package

poler

Source

poler.lisp (file)

Special Variable: *operators*
Package

poler

Source

poler.lisp (file)

Special Variable: *recursive*
Package

poler

Source

poler.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Functions

Function: %%define-operator *OPERATORS* OPERATOR-SOURCE OPERATOR-PREFIX
Package

poler

Source

poler.lisp (file)

Function: apply-format OPERATOR ARGUMENTS
Package

poler

Source

poler.lisp (file)

Function: apply-operator TREE
Package

poler

Source

poler.lisp (file)

Function: build INFIX-FORM
Package

poler

Source

poler.lisp (file)

Function: build-tree PART-LIST PRECEDENCE
Package

poler

Source

poler.lisp (file)

Function: copy-operator INSTANCE
Package

poler

Source

poler.lisp (file)

Function: left-associate OPERATOR ARGUMENTS &optional ASSOCIATED
Package

poler

Source

poler.lisp (file)

Function: lookup-operator NAME
Package

poler

Source

poler.lisp (file)

Function: make-operator &key (NAME NAME) (FIX FIX) (ARITY ARITY) (PRECEDENCE PRECEDENCE) (REPLACE-NAME REPLACE-NAME) (FORMAT FORMAT)
Package

poler

Source

poler.lisp (file)

Function: merge-part PART1 PART2
Package

poler

Source

poler.lisp (file)

Function: new-operator NAME TYPE PRECEDENCE REPLACE-NAME-OR-FORMAT OPERATOR-PREFIX
Package

poler

Source

poler.lisp (file)

Function: operator-arity INSTANCE
Function: (setf operator-arity) VALUE INSTANCE
Package

poler

Source

poler.lisp (file)

Function: operator-fix INSTANCE
Function: (setf operator-fix) VALUE INSTANCE
Package

poler

Source

poler.lisp (file)

Function: operator-format INSTANCE
Function: (setf operator-format) VALUE INSTANCE
Package

poler

Source

poler.lisp (file)

Function: operator-name INSTANCE
Function: (setf operator-name) VALUE INSTANCE
Package

poler

Source

poler.lisp (file)

Function: operator-p OBJECT
Package

poler

Source

poler.lisp (file)

Function: operator-precedence INSTANCE
Function: (setf operator-precedence) VALUE INSTANCE
Package

poler

Source

poler.lisp (file)

Function: operator-replace-name INSTANCE
Function: (setf operator-replace-name) VALUE INSTANCE
Package

poler

Source

poler.lisp (file)

Function: parse-arguments ARGS
Package

poler

Source

poler.lisp (file)

Function: part-associativity PART
Package

poler

Source

poler.lisp (file)

Function: part-closed-p PART
Package

poler

Source

poler.lisp (file)

Function: part-precedence PART
Package

poler

Source

poler.lisp (file)

Function: part-union PART ARGUMENT
Package

poler

Source

poler.lisp (file)

Function: right-associate OPERATOR ARGUMENTS
Package

poler

Source

poler.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Generic functions

Generic Function: %define-operator POLER-NAME OPERATOR-SOURCE
Package

poler

Source

poler.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.4 Structures

Structure: operator ()
Package

poler

Source

poler.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods
  • make-load-form (method)
  • print-object (method)
Direct slots
Slot: name
Readers

operator-name (function)

Writers

(setf operator-name) (function)

Slot: fix
Readers

operator-fix (function)

Writers

(setf operator-fix) (function)

Slot: arity
Readers

operator-arity (function)

Writers

(setf operator-arity) (function)

Slot: precedence
Readers

operator-precedence (function)

Writers

(setf operator-precedence) (function)

Slot: replace-name
Readers

operator-replace-name (function)

Writers

(setf operator-replace-name) (function)

Slot: format
Readers

operator-format (function)

Writers

(setf operator-format) (function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   M   P  
Index Entry  Section

F
File, Lisp, poler.asd: The poler<dot>asd file
File, Lisp, poler/src/poler.lisp: The poler/src/poler<dot>lisp file

L
Lisp File, poler.asd: The poler<dot>asd file
Lisp File, poler/src/poler.lisp: The poler/src/poler<dot>lisp file

M
Module, poler/src: The poler/src module

P
poler.asd: The poler<dot>asd file
poler/src: The poler/src module
poler/src/poler.lisp: The poler/src/poler<dot>lisp file

Jump to:   F   L   M   P  

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

A.2 Functions

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

%
%%define-operator: Internal functions
%define-operator: Internal generic functions

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

A
apply-format: Internal functions
apply-operator: Internal functions

B
build: Internal functions
build-tree: Internal functions

C
copy-operator: Internal functions

D
define-operator: Exported macros
define-poler: Exported macros

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

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

L
left-associate: Internal functions
lookup-operator: Internal functions

M
Macro, define-operator: Exported macros
Macro, define-poler: Exported macros
Macro, polish: Exported macros
make-operator: Internal functions
merge-part: Internal functions

N
new-operator: Internal functions

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

P
parse-arguments: Internal functions
part-associativity: Internal functions
part-closed-p: Internal functions
part-precedence: Internal functions
part-union: Internal functions
polish: Exported macros

R
right-associate: Internal functions

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

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

A.3 Variables

Jump to:   *  
A   F   N   P   R   S  
Index Entry  Section

*
*decorator*: Internal special variables
*format-parameter-prefix*: Exported special variables
*format-parameter-whole*: Exported special variables
*operators*: Internal special variables
*recursive*: Internal special variables

A
arity: Internal structures

F
fix: Internal structures
format: Internal structures

N
name: Internal structures

P
precedence: Internal structures

R
replace-name: Internal structures

S
Slot, arity: Internal structures
Slot, fix: Internal structures
Slot, format: Internal structures
Slot, name: Internal structures
Slot, precedence: Internal structures
Slot, replace-name: Internal structures
Special Variable, *decorator*: Internal special variables
Special Variable, *format-parameter-prefix*: Exported special variables
Special Variable, *format-parameter-whole*: Exported special variables
Special Variable, *operators*: Internal special variables
Special Variable, *recursive*: Internal special variables

Jump to:   *  
A   F   N   P   R   S  

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

A.4 Data types

Jump to:   O   P   S  
Index Entry  Section

O
operator: Internal structures

P
Package, poler: The poler package
Package, poler-asd: The poler-asd package
poler: The poler system
poler: The poler package
poler-asd: The poler-asd package

S
Structure, operator: Internal structures
System, poler: The poler system

Jump to:   O   P   S