The trestrul Reference Manual

This is the trestrul Reference Manual, version 0.0.13, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 07:09:17 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 trestrul

Tiny utilities for TREe-STRUctured-List.

Author

SATO Shinichi

Source Control

(GIT git@github.com:hyotang666/trestrul)

Bug Tracker

https://github.com/hyotang666/trestrul/issues

License

Public Domain

Long Description

# TRESTRUL 0.0.6

## What is this?
Tiny utilities for TREe-STRUctured-List.

## Current lisp world
List is very flexible.
It can be represented as tree too.

## Issues
Although CL lacks operators for tree structured list.

IMO: Reason of lackness may it is tough to get consensus about tree operations. In lisp, list is constructed by CONS.
Consider removing 1 from ’(1 . 2).
Additionally, if it is tree, we can represents nested list as node.
If so ’(nil) contains one node? or two node?

## Proposal
TRESTRUL provides it.

## Usage

## From developer

### Product’s goal
merged by other utility libraries such as alexandria
### License
Public Domain

### Tested with
* SBCL/2.1.7
* CCL/1.12.1
* CLISP/2.49
* ECL/21.2.1
* Allegro/10.1
* CMUCL/21D
* ABCL/1.8.0

Version

0.0.13

Source

trestrul.asd.

Child Component

trestrul.lisp (file).


3 Files

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


3.1 Lisp


3.1.1 trestrul/trestrul.asd

Source

trestrul.asd.

Parent Component

trestrul (system).

ASDF Systems

trestrul.


3.1.2 trestrul/trestrul.lisp

Source

trestrul.asd.

Parent Component

trestrul (system).

Packages

trestrul.

Public Interface
Internals

function-designator (type).


4 Packages

Packages are listed by definition order.


4.1 trestrul

Source

trestrul.lisp.

Use List

common-lisp.

Public Interface
Internals

function-designator (type).


5 Definitions

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


5.1 Public Interface


5.1.1 Macros

Macro: dotree ((var tree &optional return) &body body)

# DOTREE

## Description:
iterate body with var bound by each leaf of TREE.

“‘lisp
#?(dotree (l ’(1 2 . 3))
(princ l))
:outputs "123"
“‘

### syntax
(DOTREE (var tree &optional return) &body body)
=> result

## Arguments and Values:
var := symbol which bound by each leaf. otherwise error.

“‘lisp
#?(dotree (0 ’(1 2 . 3))
(princ 0))
:signals error
“‘
tree := tree generate form. Not evaluated.
When the form does not generate tree structured list,
an error is signaled.

“‘lisp
#?(dotree (l ’tree)
(princ l))
:signals invalid-tree
, :ignore-signals
“‘
return := return form which evaluated only once after iteration.

“‘lisp
#?(dotree (l ’(1 2 . 3) :result)
(princ l))
=> :RESULT
, :stream
“‘
body := implicit progn
result := return value of RETURN. The default is nil.

“‘lisp
#?(dotree (l ’(1 2 . 3))
(1+ l))
=> NIL
“‘

## Affected By:
none

## Side-Effects:
none

## Notes:
can declare about VAR at top of BODY.

“‘lisp
#?(dotree (l ’(1 2 . 3))
(declare (type fixnum l))
(princ l))
:outputs "123"
“‘
VAR is able to see from RETURN form,
but VAR is bound NIL in such time.

“‘lisp
#?(dotree (l ’(1 2 . 3) (princ l))
(1+ l))
:outputs "NIL"
“‘
BLOCK named NIL is implicitly established.
So RETURN is able to be used.

“‘lisp
#?(dotree (l ’(1 2 3 4))
(if (= 3 l)
(return)
(princ l)))
:outputs "12"
“‘
When empty tree comes, only return form is evaluated.

“‘lisp
#?(dotree (l () :hoge)
(princ l))
=> :hoge
“‘
When CL:RETURN is called, RETURN form is not evaluated.

“‘lisp
#?(dotree (l ’(1 2 3 4) (princ l))
(if (= l 3)
(return)
(princ l)))
:outputs "12"
“‘
TAGBODY is implicitly established.
So GO is able to be used in body.

“‘lisp
#?(dotree (l ’(1 2 3 4))
(if (= 3 l)
(go 3)
(go :end))
3
(princ l)
:end
(princ l))
:outputs "12334"
“‘

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.


5.1.2 Ordinary functions

Function: ansubst (substituter target tree &key test key)

# ASUBST, ANSUBST

## Description:
Substitute tree with applying substituter.

“‘lisp
#?(op #’princ-to-string 1 ’(1 2 3 1 2 3))
=> ("1" 2 3 "1" 2 3)
, :test
“‘

### syntax
(OP substituter target tree &key (test #’eql) (key #’identity))
=> result

## Arguments and Values:
substituter := function-designator which designates the function which accepts one argument.
If it is not function-designator, an error is signaled.

“‘lisp
#?(op :not-function-designator 1 ’(1 2 3))
:signals (or undefined-function
error ; for ccl
)
“‘
target := any lisp object.
tree := tree structured list, or leaf.

“‘lisp
#?(op #’princ-to-string :leaf :leaf)
=> "LEAF"
, :test
“‘
test := function designator which designates the function which accepts two arguments to test equality.

“‘lisp
#?(op #’parse-integer "0" ’("1" "2" "3" "0")
:test #’equal)
=> ("1" "2" "3" 0)
, :test
“‘
If it is not function designator, an error is signaled.

“‘lisp
#?(op #’identity 0 ’(1 2 3)
:test :not-function-designator)
:signals (or undefined-function
error ; for ccl
)
“‘
key := function designator which designates the function which accepts one argument.

“‘lisp
#?(op (constantly :zero) 0 ’("1" "2" "3" "0")
:key #’(lambda(x)
(if (stringp x)
(parse-integer x)
x)))
=> ("1" "2" "3" :ZERO)
, :test
“‘
result := see below.

## Affected By:
none

## Side-Effects:
none

## Notes:

## Exceptional-Situations:
# ASUBST
result := may newly consed substituted value.

“‘lisp
#?(let ((tree ’(:a :b :c)))
(eq tree (asubst (constantly :hoge)
:a
tree)))
=> NIL
“‘
# ANSUBST
result := may destructively modified substituted value.

“‘lisp
#?(let ((tree ’(:a :b :c)))
(eq tree (ansubst (constantly :hoge)
:a
tree)))
=> T
“‘

Package

trestrul.

Source

trestrul.lisp.

Function: ansubst-if (substituter predicate tree &key key)
Package

trestrul.

Source

trestrul.lisp.

Function: asubst (substituter target tree &key test key)

# ASUBST, ANSUBST

## Description:
Substitute tree with applying substituter.

“‘lisp
#?(op #’princ-to-string 1 ’(1 2 3 1 2 3))
=> ("1" 2 3 "1" 2 3)
, :test
“‘

### syntax
(OP substituter target tree &key (test #’eql) (key #’identity))
=> result

## Arguments and Values:
substituter := function-designator which designates the function which accepts one argument.
If it is not function-designator, an error is signaled.

“‘lisp
#?(op :not-function-designator 1 ’(1 2 3))
:signals (or undefined-function
error ; for ccl
)
“‘
target := any lisp object.
tree := tree structured list, or leaf.

“‘lisp
#?(op #’princ-to-string :leaf :leaf)
=> "LEAF"
, :test
“‘
test := function designator which designates the function which accepts two arguments to test equality.

“‘lisp
#?(op #’parse-integer "0" ’("1" "2" "3" "0")
:test #’equal)
=> ("1" "2" "3" 0)
, :test
“‘
If it is not function designator, an error is signaled.
.
“‘lisp
#?(op #’identity 0 ’(1 2 3)
:test :not-function-designator)
:signals (or undefined-function
error ; for ccl
)
“‘
key := function designator which designates the function which accepts one argument.

“‘lisp
#?(op (constantly :zero) 0 ’("1" "2" "3" "0")
:key #’(lambda(x)
(if (stringp x)
(parse-integer x)
x)))
=> ("1" "2" "3" :ZERO)
, :test
“‘
result := see below.

## Affected By:
none

## Side-Effects:
none

## Notes:

## Exceptional-Situations:
# ASUBST
result := may newly consed substituted value.

“‘lisp
#?(let ((tree ’(:a :b :c)))
(eq tree (asubst (constantly :hoge)
:a
tree)))
=> NIL
“‘
# ANSUBST
result := may destructively modified substituted value.

“‘lisp
#?(let ((tree ’(:a :b :c)))
(eq tree (ansubst (constantly :hoge)
:a
tree)))
=> T
“‘

Package

trestrul.

Source

trestrul.lisp.

Function: asubst-if (substituter predicate tree &key key)

# ASUBST-IF

## Description:
substitute leaf which satisfies PREDICATE.

“‘lisp
#?(asubst-if #’princ-to-string
(lambda(x)
(unless (listp x)
(evenp x)))
’(1 2 3 4 5))
=> (1 "2" 3 "4" 5)
, :test
“‘

### syntax
(ASUBST-IF substituter predicate tree &key (key #’identity))
=> result

## Arguments and Values:
substituter := function designator which designates the function which accepts one argument. if it is not function designator, an error is signaled.

“‘lisp
#?(asubst-if :not-function-designator
(lambda(x)
(unless(listp x)
(numberp x)))
’(1 2 3 4 5))
:signals (or undefined-function
error ; for ccl
)
“‘
predicate := function designator which desigates the function which accepts one argument. if it is not funciton designator, an error is signaled.

“‘lisp
#?(asubst-if #’identity :not-function-designator ’(1 2 3))
:signals (or undefined-function
error ; for ccl
)
“‘
tree := leaf or tree structured list.

“‘lisp
#?(asubst-if #’symbol-name #’symbolp :hoge)
=> "HOGE"
, :test
“‘
key := function designator which designates the function which accepts one argument.
if it is not function designator, an error is signaled.

“‘lisp
#?(asubst-if ’string (complement #’symbol-package)
’(hoge :hoge #:hoge "HOGE")
:key #’(lambda(x)
(and (symbolp x)
x)))
=> (hoge :hoge "HOGE" "HOGE")
, :test
“‘

“‘lisp
#?(asubst-if #’string #’null ’(hoge :hoge #:hoge nil)
:key :not-function-designator)
:signals undefined-function
“‘
result := substituted leaf or tree.

## Affected By:
none

## Side-Effects:
none

## Notes:
Top level node (i.e. root) is also tested.

“‘lisp
#?(asubst-if (constantly :hoge) #’listp ’(:a :b :c))
=> :hoge
“‘

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.

Function: collect-node (target tree &key key test recursive-p)

# COLLECT-NODE

## Description:
collect node from TREE.

“‘lisp
#?(collect-node :export ‘(defpackage :hoge (:use :cl)
(:export :a :b :c)
(:export :d :e :f))
:key #’car)
=> ((:export :a :b :c) (:export :d :e :f))
, :test
“‘

### syntax
(COLLECT-NODE target tree &key (key #’identity) (test #’eql) recursive-p)
=> result

## Arguments and Values:
target := T
tree := tree structured list. Otherwise error.

“‘lisp
#?(collect-node :hoge :not-tree)
:signals invalid-tree
“‘
key := function designator which designates the function which accepts one node as argument. The default is CL:IDENTITY.
If it is not function designator, an error is signaled.

“‘lisp
#?(collect-node :use ’((:use :cl) (:export :a :b :c))
:key :not-function-designator)
:signals undefined-function
“‘
test := function designator which designates the function which accepts two arguments. The default is CL:EQL.
if it is not function-designator, an error is signaled.

“‘lisp
#?(collect-node ’(:use :cl) ’((:use :cl) (:export :a :b :c))
:test :not-function-designator)
:signals undefined-function
“‘
recursive-p := boolean which control whether call collect-node recursively or not.

“‘lisp
#?(collect-node :tag ’((:tag recursively (:tag)))
:key #’car)
=> ((:tag recursively (:tag)))
, :test
“‘

“‘lisp
#?(collect-node :tag ’((:tag recursively (:tag second)))
:key #’car
:recursive-p T)
=> ((:tag recursively (:tag second))
(:tag second))
, :test
“‘
result := list which may contains node.

## Affected By:
none

## Side-Effects:
none

## Notes:
When both :key and :test are not specified,
return form is always nil unless target is nil.

“‘lisp
#?(collect-node :tag ’((:tag 1 (:tag 2))))
=> NIL
“‘

“‘lisp
#?(collect-node nil ’((:tag 1 () (:tag 2 ()))))
=> (NIL NIL NIL NIL NIL)
“‘

#### i.e. ((:tag 1 NIL (:tag 2 NIL . NIL) . NIL) . NIL)

Works fine even if :recirsive-p T is specified (i.e. never infinite loop).

“‘lisp
#?(collect-node nil ’((:tag 1 NIL(:tag 2 NIL)))
:recursive-p T)
=> (NIL NIL NIL NIL NIL)
, :test
“‘

“‘lisp
#?(collect-node nil ’())
=> (NIL)
“‘
remember tree is one kind of node.

“‘lisp
#?(collect-node nil ’() :recursive-p t)
=> (NIL)
, :test
“‘

“‘lisp
#?(collect-node nil ’(NIL))
=> (NIL NIL)
“‘
remember (NIL) is (NIL . NIL)

“‘lisp
#?(collect-node nil ’(NIL) :recursive-p t)
=> (NIL NIL)
, :test
“‘

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.

Function: find-leaf (target tree &key test key)

# FIND-LEAF

## Description:
Find target from tree.

### syntax
(FIND-LEAF target tree &key (test #’eql) (key #’identity))
=> result

“‘lisp
#?(find-leaf 0 ’(1 (2 . 3) ((0))))
=> 0
“‘

## Arguments and Values:
target := T
tree := Tree, otherwise error.

“‘lisp
#?(find-leaf 0 0)
:signals error
“‘
test := Function as ‘(FUNCTION(T T)BOOLEAN)‘, the default is #’EQL. key := Function as ‘(FUNCTION(T)T)‘, the default is #’IDENTITY. result := T

## Affected By:
none

## Side-Effects:
none

## Notes:
Same as ‘CL:FIND‘, ‘FIND-LEAF‘ can not find ‘NIL‘.

“‘lisp
#?(find-leaf nil ’(()))
=> NIL
“‘

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.

Function: find-leaf-if (pred tree &key key)

# FIND-LEAF-IF

## Description:
Find element which satisfies PRED from TREE.

### syntax
(FIND-LEAF-IF pred tree &key (key #’identity))
=> result

“‘lisp
#?(find-leaf-if #’oddp ’(2 (3 . 4) 5))
=> 3
“‘

## Arguments and Values:
pred := function designator as (function(T)T).

“‘lisp
#?(find-leaf-if ’oddp ’(1 2 3))
=> 1
“‘
otherwise error

“‘lisp
#?(find-leaf-if "NOT-FUNCTION" ’(1 2 3))
:signals error
“‘
tree := tree structured list.
atom is not acceptable.

“‘lisp
#?(find-leaf-if #’oddp 1)
:signals error
“‘
key := function designator as (function(T)T).

“‘lisp
#?(find-leaf-if #’oddp ’("1" "2" "3") :key #’parse-integer) => "1"
, :test
“‘

“‘lisp
#?(find-leaf-if #’oddp ’("1" "2" "3") :key ’parse-integer) => "1"
, :test
“‘
otherwise error.

“‘lisp
#?(find-leaf-if #’oddp ’("1" "2" "3") :key "NOT-FUNCTION") :signals error
“‘
result := T

## Affected By:
none

## Side-Effects:
none

## Notes:

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.

Function: find-node-if (pred tree &key count recursive-p)

# FIND-NODE-IF

## Description:
Find node which satisfies ‘PRED‘ from ‘TREE‘.

### syntax
(FIND-NODE-IF pred tree &key (count 1) recursive-p)
=> result

## Arguments and Values:
pred := Function designator as (function (list) boolean), otherwise error.

“‘lisp
#?(find-node-if "not function designator" ’(:dummy))
:signals error
“‘
tree := Tree, which include atom.

“‘lisp
#?(find-node-if #’identity "atom")
=> NIL
“‘
count := (integer 1 *), otherwise error.

“‘lisp
#?(find-node-if #’identity nil :count "not (integer 1 *)")
:signals error
“‘
‘COUNT‘ specify Nth value. The default is 1.

“‘lisp
#?(find-node-if (lambda(x) (typep x ’(cons (eql :a) *)))
’((:a 1) (:a 2) (:a 3)))
=> (:a 1)
, :test
“‘

“‘lisp
#?(find-node-if (lambda(x) (typep x ’(cons (eql :a) *)))
’((:a 1) (:a 2) (:a 3))
:count 2)
=> (:A 2)
, :test
“‘

“‘lisp
#?(find-node-if (lambda(x) (typep x ’(cons (eql :a) *)))
’((:a 1) (:a 2) (:a 3))
:count 3)
=> (:A 3)
, :test
“‘

“‘lisp
#?(find-node-if (lambda(x) (typep x ’(cons (eql :a) *)))
’((:a 1) (:a 2) (:a 3))
:count 4)
=> NIL
“‘
recursive-p := Generalized boolean. The default is ‘NIL‘.

“‘lisp
#?(find-node-if (lambda(x) (eq :a (car x)))
’((:a 1 :a 2 :a 3) (:a 4))
:count 2)
=> (:A 4)
, :test
“‘

“‘lisp
#?(find-node-if (lambda(x) (eq :a (car x)))
’((:a 1 :a 2 :a 3) (:a 4))
:count 2
:recursive-p t)
=> (:A 2 :A 3)
, :test
“‘
result := T

## Affected By:
none

## Side-Effects:
none

## Notes:

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.

Function: follow (path tree)

# FOLLOW

## Description:

### syntax
(FOLLOW path tree)
=> result

“‘lisp
#?(let ((tree ’(1 (2 . 3) ((((4) . 5)))))) (follow (path-to 5 tree)
tree))
=> 5
“‘

## Arguments and Values:
path := ((function(list)T)*)
Expects return value of ‘PATH-TO‘.
When null, TREE is returned.

“‘lisp
#?(follow nil :a)
=> :A
“‘

“‘lisp
#?(follow nil ’(:a . :b))
=> (:A . :B)
, :test
“‘
tree := Tree structured list, include atom. i.e. T.

“‘lisp
#?(follow (list #’car) ’(:a . :b))
=> :A
“‘
result := T

## Affected By:

## Side-Effects:

## Notes:

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.

Function: mapleaf (fun tree)

# MAPLEAF, NMAPLEAF

### syntax
(OP fun tree)
=> result

## Description:
Apply FUN to every leaf of TREE.

“‘lisp
#?(op #’1+ ’(1 (2 . 3) . 4))
=> (2 (3 . 4) . 5)
, :test
“‘

## Arguments and Values:
fun := function which accepts one argument. Otherwise error.

“‘lisp
#?(op 0 ’(1 2 3 4))
:signals error
, :lazy
“‘
tree := tree structured list. Otherwise error.

“‘lisp
#?(op #’1+ 1)
:signals error
, :lazy
“‘
result := see below.

## Affected By:
none

## Side-Effects:
none

## Notes:

## Exceptional-Situations:
# MAPLEAF
result := newly consed tree structured list.

“‘lisp
#?(let ((tree ’(1 . 2)))
(eq tree (mapleaf #’identity tree)))
=> NIL
“‘
# NMAPLEAF

## Side-Effects:
argument TREE is destructively modified.

“‘lisp
#?(let ((tree ’(1 2 3)))
(eq tree (nmapleaf #’1+ tree)))
=> T
“‘

Package

trestrul.

Source

trestrul.lisp.

Function: nmapleaf (fun tree)

# MAPLEAF, NMAPLEAF

### syntax
(OP fun tree)
=> result

## Description:
Apply FUN to every leaf of TREE.

“‘lisp
#?(op #’1+ ’(1 (2 . 3) . 4))
=> (2 (3 . 4) . 5)
, :test
“‘

## Arguments and Values:
fun := function which accepts one argument. Otherwise error.

“‘lisp
#?(op 0 ’(1 2 3 4))
:signals error
, :lazy
“‘
tree := tree structured list. Otherwise error.

“‘lisp
#?(op #’1+ 1)
:signals error
, :lazy
“‘
result := see below.

## Affected By:
none

## Side-Effects:
none

## Notes:

## Exceptional-Situations:
# MAPLEAF
result := newly consed tree structured list.

“‘lisp
#?(let ((tree ’(1 . 2)))
(eq tree (mapleaf #’identity tree)))
=> NIL
“‘
# NMAPLEAF

## Side-Effects:
argument TREE is destructively modified.

“‘lisp
#?(let ((tree ’(1 2 3)))
(eq tree (nmapleaf #’1+ tree)))
=> T
“‘

Package

trestrul.

Source

trestrul.lisp.

Function: path-to (item tree &key test)

# PATH-TO

## Description:
Return list of function-names, which guide you to target item in the tree. Secondary value is foundp.

“‘lisp
#?(path-to 1 1)
:values (NIL T)
“‘

“‘lisp
#?(path-to 1 ’(1))
:values ((CAR) T)
“‘

“‘lisp
#?(path-to 1 ’(2))
:values (NIL NIL)
“‘

“‘lisp
#?(path-to 2 ’(1 . 2))
:values ((CDR) T)
“‘

### syntax
(PATH-TO item tree &key (test #’eql))
=> result

## Arguments and Values:
item := T
tree := Tree structured list, include atom. i.e. T.
test := (function(t t)generalized-boolean).
result := (values (function*) boolean)

## Affected By:
none

## Side-Effects:
none

## Notes:

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.

Function: proper-treep (arg)

# PROPER-TREEP

## Description:
Tests arg is proper-tree.

“‘lisp
#?(proper-treep :leaf) => NIL
“‘

“‘lisp
#?(proper-treep ())
=> T
“‘

“‘lisp
#?(proper-treep ’(:a :b)) => T
“‘

“‘lisp
#?(proper-treep ’(:a . :b)) => NIL
“‘

### syntax (PROPER-TREEP arg)
=> result

## Arguments and Values: arg := any lisp object result := boolean

## Affected By:
none

## Side-Effects:
none

## Notes:

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.

Function: remove-leaf (item tree &key test key keep)

# REMOVE-LEAF

## Description:
remove specified LEAF from TREE.

“‘lisp
#?(remove-leaf 4 ’(1 2 3 (4)))
=> (1 2 3 ())
, :test
“‘

### syntax
(REMOVE-LEAF item tree &key (test #’eql) (key #’identity) (keep t))
=> result

## Arguments and Values:
item := non NIL atom, otherwise unspecified.

“‘lisp
#?(remove-leaf () ’(() 1 2))
=> unspecified
“‘
tree := tree structured list, otherwise error.

“‘lisp
#?(remove-leaf 1 1)
:signals invalid-tree
“‘
test := function-designator which designate the function which accepts two arguments. Otherwise error.
The default is CL:EQL.

“‘lisp
#?(remove-leaf (princ-to-string 1) (list "2" "1" "0"))
=> ("2" "1" "0")
, :test
“‘

“‘lisp
#?(remove-leaf "1" ’("2" "1" "0") :test ’string=)
=> ("2" "0")
, :test
“‘

“‘lisp
#?(remove-leaf "1" ’("2" "1" "0") :test :not-function-designator)
:signals undefined-function
“‘
key := function-designator which designates the function which accepts one argument. Otherwise error.
The default is CL:IDENTITY.

“‘lisp
#?(remove-leaf 1 ’("2" "1" "0"))
=> ("2" "1" "0")
, :test
“‘

“‘lisp
#?(remove-leaf 1 ’("2" "1" "0") :key #’parse-integer)
=> ("2" "0")
, :test
“‘

“‘lisp
#?(remove-leaf "1" ’("2" "1" "0") :key :not-function-designator)
:signals undefined-function
“‘
keep := boolean
control flag, whether keep empty node (i.e. NIL) or not.
The default it T.

“‘lisp
#?(remove-leaf 1 ’(1 2 (1) 2))
=> (2 () 2)
, :test
“‘

“‘lisp
#?(remove-leaf 1 ’(1 2 (1) 2) :keep nil)
=> (2 2)
, :test
“‘
result := newly consed tree structured list.

“‘lisp
#?(let ((tree ’(1 2 3 4 5)))
(eq tree (remove-leaf 0 tree)))
=> NIL
“‘

## Affected By:
none

## Side-Effects:
none

## Notes:
TREE must be proper tree. See PROPER-TREE for detail.

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.

Function: remove-leaf-if (function tree &key key keep)

# REMOVE-LEAF-IF

## Description:
Remove leaf which satisfies FUNCTION.

“‘lisp
#?(remove-leaf-if #’evenp ’(1 (2 3) 4))
=> (1 (3))
, :test
“‘

### syntax
(REMOVE-LEAF-IF function tree &key (key #’identity) (keep t))
=> result

## Arguments and Values:
function := function-designator which designates the function which accepts one argument. Otherwise error.

“‘lisp
#?(remove-leaf-if ’oddp ’(1 (2 3) 4))
=> ((2)4)
, :test
“‘

“‘lisp
#?(remove-leaf-if :not-function-designator ’(1 (2 3) 4))
:signals undefined-function
“‘
tree := tree structured list, otherwise error.

“‘lisp
#?(remove-leaf-if #’evenp 0)
:signals (or invalid-tree
type-error ; for sbcl
warning ; for ccl
)
“‘
key := function-desinator which designates the function which accepts one argument.

“‘lisp
#?(remove-if #’evenp ’("1" "2" "3"))
:signals type-error
“‘

“‘lisp
#?(remove-if #’evenp ’("1" "2" "3") :key #’parse-integer)
=> ("1" "3")
, :test
“‘
keep := boolean which control whether keep empty node or not.
The default is T.

“‘lisp
#?(remove-leaf-if #’evenp ’(1 (2) 3))
=> (1 () 3)
, :test
“‘

“‘lisp
#?(remove-leaf-if #’evenp ’(1 (2) 3) :keep nil)
=> (1 3)
, :test
“‘
result := newly consed tree structured list.

“‘lisp
#?(let ((tree ’(1 2 3)))
(eq tree (remove-leaf-if #’evenp tree)))
=> NIL
“‘

## Affected By:
none

## Side-Effects:
none

## Notes:

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.

Function: traverse (function tree)

# TRAVERSE

## Description:
Traverse TREE with doing FUNCTION.
This is ‘MAPC‘ like operator.

### syntax
(TRAVERSE function tree)
=> result

“‘lisp
#?(traverse #’print ’(1 (2 . 3) 4))
:outputs "
(1 (2 . 3) 4)
1
((2 . 3) 4)
(2 . 3)
2
3
(4)
4
NIL "
“‘

## Arguments and Values:
function := Function as (FUNCTION(T)T).
Otherwise error.

“‘lisp
#?(traverse "NOT-FUNCTION" ’(1 2 3))
:signals error
“‘
This function’s return value is discarded.
tree := Tree structured list.
Atom is acceptable.

“‘lisp
#?(traverse #’print :atom)
:outputs "
:ATOM "
“‘
result := NIL

“‘lisp
#?(traverse #’print :atom)
=> NIL
, :stream
“‘

## Affected By:
none

## Side-Effects:
none

## Notes:
‘TRAVERSE‘ dinamically construct ‘CATCH‘ tag named ‘TRAVERSE‘. You can use it to skip traversing.

“‘lisp
#?(traverse (lambda(x)
(if (and (listp x)
(eql 2 (car x)))
(throw ’traverse nil)
(print x)))
’(1 (2 . 3) 4))
:outputs "
(1 (2 . 3) 4)
1
((2 . 3) 4)
(4)
4
NIL "
“‘

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.

Function: treep (arg)

# TREEP

## Description:
Tests arg is tree.

“‘lisp
#?(treep :leaf)
=> NIL
“‘

“‘lisp
#?(treep ())
=> T
“‘

“‘lisp
#?(treep ’(:a :b))
=> T
“‘

“‘lisp
#?(treep ’(:a . :b)) => T
“‘

### syntax
(TREEP arg)
=> result

## Arguments and Values: arg := any lisp object. result := boolean

## Affected By:
none

## Side-Effects:
none

## Notes:

## Exceptional-Situations:

Package

trestrul.

Source

trestrul.lisp.


5.1.3 Conditions

Condition: invalid-tree

# INVALID-TREE

## Description:

## Class Precedence List: (case in SBCL)
invalid-tree simple-type-error simple-condition type-error error serious-condition condition slot-object t

## Effective Slots:
FORMAT-CONTROL [Type] T
[READER] simple-condition-format-control
FORMAT-ARGUMENTS [Type] T
[READER] simple-condition-format-arguments
DATUM [Type] T
[READER] type-error-datum
EXPECTED-TYPE [Type] T
[READER] type-error-expected-type

## Notes:

Package

trestrul.

Source

trestrul.lisp.

Direct superclasses

simple-type-error.


5.1.4 Types

Type: proper-tree ()

# PROPER-TREE

## Description:
Tree structured list but without dotted pair.

“‘lisp
#?(typep () ’proper-tree)
=> T
“‘

“‘lisp
#?(typep ’(:a . :b) ’proper-tree)
=> NIL
“‘

“‘lisp
#?(typep ’(:a :b) ’proper-tree)
=> T
“‘

“‘lisp
#?(typep :atom ’proper-tree)
=> NIL
“‘

“‘lisp
#?(typep ’((:a :b)) ’proper-tree)
=> T
“‘

“‘lisp
#?(typep ’((:a . :b) :c) ’proper-tree)
=> NIL
“‘

## Compound Type Specifier Kind:
none

## Compound Type Specifier Syntax:

## Compound Type Specifier Arguments:

## Compound Type Specifier Description:

Package

trestrul.

Source

trestrul.lisp.

Type: tree ()

# TREE

## Description:
Tree structured list which includes NIL and dotted pair.

“‘lisp
#?(typep nil ’tree)
=> T
“‘

“‘lisp
#?(typep ’(:a . :b) ’tree)
=> T
“‘

“‘lisp
#?(typep :atom ’tree)
=> NIL
“‘

## Compound Type Specifier Kind:
none

## Compound Type Specifier Syntax:

## Compound Type Specifier Arguments:

## Compound Type Specifier Description:

Package

trestrul.

Source

trestrul.lisp.


5.2 Internals


5.2.1 Types

Type: function-designator ()
Package

trestrul.

Source

trestrul.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   C   D   F   M   N   P   R   T  
Index Entry  Section

A
ansubst: Public ordinary functions
ansubst-if: Public ordinary functions
asubst: Public ordinary functions
asubst-if: Public ordinary functions

C
collect-node: Public ordinary functions

D
dotree: Public macros

F
find-leaf: Public ordinary functions
find-leaf-if: Public ordinary functions
find-node-if: Public ordinary functions
follow: Public ordinary functions
Function, ansubst: Public ordinary functions
Function, ansubst-if: Public ordinary functions
Function, asubst: Public ordinary functions
Function, asubst-if: Public ordinary functions
Function, collect-node: Public ordinary functions
Function, find-leaf: Public ordinary functions
Function, find-leaf-if: Public ordinary functions
Function, find-node-if: Public ordinary functions
Function, follow: Public ordinary functions
Function, mapleaf: Public ordinary functions
Function, nmapleaf: Public ordinary functions
Function, path-to: Public ordinary functions
Function, proper-treep: Public ordinary functions
Function, remove-leaf: Public ordinary functions
Function, remove-leaf-if: Public ordinary functions
Function, traverse: Public ordinary functions
Function, treep: Public ordinary functions

M
Macro, dotree: Public macros
mapleaf: Public ordinary functions

N
nmapleaf: Public ordinary functions

P
path-to: Public ordinary functions
proper-treep: Public ordinary functions

R
remove-leaf: Public ordinary functions
remove-leaf-if: Public ordinary functions

T
traverse: Public ordinary functions
treep: Public ordinary functions


A.3 Variables