(! . exe) -> any
exe is
displayed, and a read-eval-print-loop is entered (with ! as its
prompt character), to evaluate expressions and examine the current program
environment. An empty input line terminates the read-eval-print-loop, the
environment and I/O channels are restored, and the result of exe is
returned. ! is normally inserted into existing programs with the
debug function. See also e, ^ and
*Dbg.
: (de foo (N) (and (println 1) (! println N) (println 2)))
-> foo
: (foo 7)
1 # Executed '(println 1)'
(println N) # Entered breakpoint
! N # Examine the value of 'N'
-> 7
! (e) # Evaluate '^', i.e. (println N)
7
-> 7
! (e @) # Evaluate '@' -> the result of '(println 1)'
-> 1
! # Empty line: continue
7 # Executed '(println N)'
2 # Executed '(println 2)'
-> 2
($ sym|lst lst . prg) -> any
sym|lst is printed
to the console with a proper indentation, followed by a colon :. If
a function is traced, the first argument is the function symbol, else if a
method is traced, it is a cons pair of message and class. The second argument
lst should be a list of symbols, identical to the function's
argument list. The current values of these symbols are printed, followed by a
newline. Then prg is executed, and its return value printed in a
similar way (this time with an equals sign = instead of a colon)
and returned. $ is normally inserted into existing programs with
the trace function.
: (de foo (A B) ($ foo (A B) (* A B)))
-> foo
: (foo 3 4)
foo : 3 4 # Function entry, arguments 3 and 4
foo = 12 # Function exit, return value 12
-> 12
($dat 'sym1 ['sym2]) -> dat
sym1 in ISO format to a date, optionally using a delimiter character
sym2. See also dat$,
$tim, strDat and expDat.
: ($dat "20070601")
-> 733134
: ($dat "2007-06-01" "-")
-> 733134
($tim 'sym) -> tim
time. The
minutes and seconds are optional and default to zero. See also tim$ and $dat.
: (time ($tim "10:57:56"))
-> (10 57 56)
: (time ($tim "10:57"))
-> (10 57 0)
: (time ($tim "10"))
-> (10 0 0)
(% 'num ..) -> num
num
arguments. The sign of the result is that of the first argument. When one of the
arguments evaluates to NIL, it is returned immediately. See also
/ and */ .
: (% 17 5)
-> 2
: (% -17 5) # Sign is that of the first argument
-> -2
: (% 5 2)
-> 1
: (% 15 10)
-> 5
: (% 15 10 2) # (% 15 10) -> 5, then (% 5 2) -> 1
-> 1
(& 'num ..) -> num
AND of all num arguments. When
one of the arguments evaluates to NIL, it is returned immediately.
See also |, x| and bit?.
: (& 6 3)
-> 2
: (& 7 3 1)
-> 1
(* 'num ..) -> num
num arguments. When one of the
arguments evaluates to NIL, it is returned immediately. See also
/, */, + and
-.
: (* 1 2 3)
-> 6
: (* 5 3 2 2)
-> 60
(** 'num1 'num2) -> num
num1 to the power of
num2.
: (** 2 3)
-> 8
: (** 100 100)
-> 10000000000000000000000000000000000000000000000000000000000000000000000000000
00000000000000000000000000000000000000000000000000000000000000000000000000000000
00000000000000000000000000000000000000000000
(*/ 'num1 ['num2 ..] 'num3) -> num
num1 and all following num2
arguments, divided by the num3 argument. The result is rounded to
the nearest integer value. When one of the arguments evaluates to
NIL, it is returned immediately. Note that */ is
especially useful for fixed point arithmetic, by multiplying with (or dividing
by) the scale factor. See also *,
/, +, - and
sqrt.
: (*/ 3 4 2)
-> 6
: (*/ 1234 2 10)
-> 247
: (*/ 100 6)
-> 17
: (scl 2)
-> 2
: (format (*/ 3.0 1.5 1.0) *Scl)
-> "4.50"
(+ 'num ..) -> num
num arguments. When one of the arguments
evaluates to NIL, it is returned immediately. See also inc, -,
*, / and */.
: (+ 1 2 3)
-> 6
(- 'num ..) -> num
num argument and all
following arguments. If only a single argument is given, it is negated. When one
of the arguments evaluates to NIL, it is returned immediately. See
also dec, +, *,
/ and */.
: (- 7)
-> -7
: (- 7 2 1)
-> 4
(-> any [num]) -> any
any (typically a Pilog variable, or an expression of variables) at top
level (or level num) in the current environment. See also prove and unify.
: (? (append (1 2 3) (4 5 6) @X) (^ @ (println 'X '= (-> @X))))
X = (1 2 3 4 5 6)
@X=(1 2 3 4 5 6)
-> NIL
(/ 'num ..) -> num
num argument successively divided by all
following arguments. When one of the arguments evaluates to NIL, it
is returned immediately. See also *,
*/, %, + and
-.
: (/ 12 3)
-> 4
: (/ 60 -3 2 2)
-> -5
(: sym|0 [sym1|cnt ..]) -> any
any from the properties of a symbol, or from a
list, by applying the get algorithm to
This and the following arguments. Used typically in methods or
with bodies. (: ..) is
equivalent to (; This ..). See also ;, =: and
::.
: (put 'X 'a 1)
-> 1
: (with 'X (: a))
-> 1
(:: sym [sym1|cnt .. sym2]) -> var
sym or sym2
from a symbol. That symbol is This (if no other arguments are
given), or a symbol found by applying the get algorithm to This and the
following arguments. The property (the cons pair, not just its value) is
returned, suitable for direct (destructive) manipulations with functions
expecting a var argument. Used typically in methods or with bodies. See also =:, prop and :.
: (with 'X (=: cnt 0) (inc (:: cnt)) (: cnt))
-> 1
(; 'sym1|lst [sym2|cnt ..]) -> any
any from the properties of a symbol, or from a
list, by applying the get algorithm to
sym1|lst and the following arguments. See also :, =: and
::.
: (put 'A 'a 1)
-> 1
: (put 'A 'b 'B)
-> B
: (put 'B 'c 7)
-> 7
: (; 'A a)
-> 1
: (; 'A b c)
-> 7
(< 'any ..) -> flg
T when all arguments any are in strictly
increasing order. See also Comparing.
: (< 3 4)
-> T
: (< 'a 'b 'c)
-> T
: (< 999 'a)
-> T
(<= 'any ..) -> flg
T when all arguments any are in strictly
non-decreasing order. See also Comparing.
: (<= 3 3)
-> T
: (<= 1 2 3)
-> T
: (<= "abc" "abc" "def")
-> T
(<> 'any ..) -> flg
T when not all any arguments are equal
(structure equality). (<> 'any ..) is equivalent to (not (=
'any ..)). See also Comparing.
: (<> 'a 'b)
-> T
: (<> 'a 'b 'b)
-> T
: (<> 'a 'a 'a)
-> NIL
(= 'any ..) -> flg
T when all any arguments are equal
(structure equality). See also Comparing.
: (= 6 (* 1 2 3))
-> T
: (= "a" "a")
-> T
: (== "a" "a")
-> T
: (= (1 (2) 3) (1 (2) 3))
-> T
(=0 'any) -> 0 | NIL
0 when any is a number with value zero.
See also n0, lt0, le0, ge0 and gt0.
: (=0 (- 6 3 2 1))
-> 0
: (=0 'a)
-> NIL
(=: sym|0 [sym1|cnt .. sym2|0] 'any)
any for a property key sym or
sym2 (or in the symbol value for zero) in a symbol. That symbol is
This (if no other arguments are given), or a symbol found by
applying the get algorithm to
This and the following arguments. Used typically in methods or
with bodies. See also put, :
and ::.
: (with 'X (=: a 1) (=: b 2))
-> 2
: (get 'X 'a)
-> 1
: (get 'X 'b)
-> 2
(== 'any ..) -> flg
T when all any arguments are the same
(pointer equality). See also n== and Comparing.
: (== 'a 'a)
-> T
: (== 'NIL NIL (val NIL) (car NIL) (cdr NIL))
-> T
: (== (1 2 3) (1 2 3))
-> NIL
(==== ['sym ..]) -> NIL
sym arguments are (re-)inserted into the transient index.
See also extern and intern.
: (setq S "abc") # Read "abc"
-> "abc"
: (== S "abc") # Read again, get the same symbol
-> T
: (====) # Close scope
-> NIL
: (== S "abc") # Read again, get another symbol
-> NIL
(=T 'any) -> flg
T when any is the symbol T.
(=T X) is equivalent to (== T X). See also nT.
: (=T 0)
-> NIL
: (=T "T")
-> NIL
: (=T T)
-> T
(> 'any ..) -> flg
T when all arguments any are in strictly
decreasing order. See also Comparing.
: (> 4 3)
-> T
: (> 'A 999)
-> T
(>= 'any ..) -> flg
T when all arguments any are in strictly
non-increasing order. See also Comparing.
: (>= 'A 999)
-> T
: (>= 3 2 2 1)
-> T
(>> 'cnt 'num) -> num
num argument by cnt
bit-positions. If cnt is negative, a corresponding left shift is
performed.
: (>> 1 8)
-> 4
: (>> 3 16)
-> 2
: (>> -3 16)
-> 128
: (>> -1 -16)
-> -32
(? [sym ..] [pat 'any ..] . lst) -> flg
? is a non-evaluating front-end to the query function. It displays each result, waits
for console input, and terminates when a non-empty line is entered. If a
preceding list of (non-pattern-) symbols is given, they will be taken as rules
to be traced by prove. The list of
variable/value pairs is passed to goal
for an initial Pilog environment. See also pilog and solve.
: (? (append (a b c) (d e f) @X))
@X=(a b c d e f)
-> NIL
: (? (append @X @Y (a b c)))
@X=NIL @Y=(a b c)
@X=(a) @Y=(b c)
@X=(a b) @Y=(c)
@X=(a b c) @Y=NIL
-> NIL
: (? (append @X @Y (a b c)))
@X=NIL @Y=(a b c). # Stopped
-> NIL
: (? append (append @X @Y (a b c))) # Trace 'append'
1 (append NIL (a b c) (a b c))
@X=NIL @Y=(a b c)
2 (append (a . @X) @Y (a b c))
1 (append NIL (b c) (b c))
@X=(a) @Y=(b c). # Stopped
-> NIL
@
@
Result). When @ is used as a formal parameter in lambda expressions, it denotes a variable number of
evaluated arguments.
@@
@ Result).
@@@
@ Result).
^
debug, !, e and
*Dbg.
: (* (+ 3 4) (/ 7 0))
!? (/ 7 0)
Div/0
? ^
-> (/ 7 0)
(| 'num ..) -> num
OR of all num arguments. When
one of the arguments evaluates to NIL, it is returned immediately.
See also x|, & and bit?.
: (| 1 2)
-> 3
: (| 1 2 4 8)
-> 15
(c) Software Lab. Alexander Burger
The Pilog select/3 predicate is rather complex, and quite different from other predicates. This document tries to explain it in detail, and shows some typical use cases.
select takes at least three arguments:
We will describe these arguments in the following, but demonstrate them first on a concrete example.
The examples in this document will use the demo application in "app/*.l" (see also "A Minimal Complete Application"). To get an interactive prompt, start it as
$ pil app/main.l -main +
:
As ever, you can terminate the interpreter by hitting Ctrl-D.
For a first, typical example, let's write a complete call to solve that returns a list of articles with numbers between 1 and 4, which contain "Part" in their description, and have a price less than 100:
(let (Nr (1 . 4) Nm Part Pr '(NIL . 100.00))
(solve
(quote
@Nr Nr
@Nm Nm
@Pr Pr
(select (@Item)
((nr +Item @Nr) (nm +Item @Nm) (pr +Item @Pr))
(range @Nr @Item nr)
(part @Nm @Item nm)
(range @Pr @Item pr) ) )
@Item ) )
This expression will return, with the default database setup of "app/init.l",
a list of exactly one item ({3-2}), the item with the number 2.
The let statement assigns values to
the search parameters for number Nr, description Nm
and price Pr. The Pilog query (the first argument to
solve) passes these values to the Pilog variables @Nr,
@Nm and @Pr. Ranges of values are always specified by
cons pairs, so (1 . 4) includes the numbers 1 through 4, while
(NIL . 100.00) includes prices from minus infinite up to one
hundred.
The list of unification variables is
(@Item)
The list of generator clauses is
((nr +Item @Nr) (nm +Item @Nm) (pr +Item @Pr))
The filter clauses are
(range @Nr @Item nr)
(part @Nm @Item nm)
(range @Pr @Item pr)
As stated above, the first argument to select should be a list
of variables. These variables communicate values (via unify) from the select
environment to the enclosing Pilog environment.
The first variable in this list (@Item in the above example) is
mandatory, it takes the direct return value of select. Additional
optional variables may be unified by clauses in the body of select,
and return further values.
The second argument to select is a list of "generator clauses".
Each of these clauses specifies some kind of database B-Tree +index, to be traversed by
select, step by step, where each step returns a suitable single
database object. In the simplest case, they consist like here just of a relation
name (e.g. nr), a class (e.g. +Item), an optional hook
specifier (not in this example), and a pattern (values or ranges, e.g. (1 . 4)
or "Part").
The generator clauses are the core of 'select'. In some way, they behave
analog to or/2, as each of them
generates a sequence of values. However, the generator clauses behave different,
as they will not generate an exhaustive set of values upon backtracking, one
after the other, where the next gets its turn when the previous one is
exhausted. Instead, all clauses will generate their values quasi-parallel, with
a built-in optimization so that successful clauses will be called with a higher
probability. "Successful" means that the returned values successfully pass
select's filter clauses.
In its basic form, a generator clause is equivalent to the db/3 predicate, stepping through a single
B-Tree. The clause
(nr +Item @Nr)
generates the same values as would be produced by a stand-alone Pilog clause
(db nr +Item @Nr @Item)
as can be seen in the following two calls:
: (? (db nr +Item (1 . 4) @Item))
@Item={3-1}
@Item={3-2}
@Item={3-3}
@Item={3-4}
-> NIL
: (? (select (@Item) ((nr +Item (1 . 4)))))
@Item={3-1}
@Item={3-2}
@Item={3-3}
@Item={3-4}
-> NIL
select is mostly useful if more than one generator clause is
involved. The tree search parameters of all clauses are meant to form a logical
AND. Only those objects should be returned, for which all search
parameters (and the associated filter clauses) are valid. As soon as one of the
clauses finishes stepping through its database (sub)tree, the whole call to
select will terminate, because further values returned from other
generator clauses cannot be part of the result set.
Therefore, select would find all results most quickly if it
could simply call only the generator clause with the smallest (sub)tree.
Unfortunately, this is usually not known in advance. It depends on the
distribution of the data in the database, and on the search parameters to each
generator clause.
Instead, select single-steps each generator clause in turn, in a
round-robin scheme, applies the filter clauses to each generated object, and
re-arranges the order of generator clauses so that the more successful clauses
will be preferred. This process usually converges quickly and efficiently.
A generator clause can also combine several (similar) indexes into a single one. Then the clause is written actually as a list of clauses.
For example, a generator clause to search for a customer by phone number is
(tel +CuSu @Tel)
((tel +CuSu @Tel mob +CuSu @Tel))
The generator will first traverse all matching entries in the +Ref tree of the tel relation, and
then, when these are exhausted, all matching entries in the mob
index tree.
But generator clauses are not limited to the direct B-Tree interaction of
db/3. They can also traverse trees of
associated objects, and then follow +Link / +Joint relations, or tree relations like
+Ref to arrive at database objects
with a type suitable for return values from select.
To locate appropriate objects from associated objects, the generator clause can contain - in addition to the standard relation/class/pattern specification (see Generator Clauses above) - an arbitrary number of association specifiers. Each association specifier can be
+Link or
+Joint will be followed, or a
+List of those will be traversed to
locate appropriate objects.
+index to be traversed to locate appropriate
objects.
+Ord (order) objects. Orders can
be searched for order number and date, customer name and city, item description
and supplier name:
(select (@@)
((nr +Ord @Nr) (dat +Ord @Dat)
(nm +CuSu @Cus (cus +Ord))
(ort +CuSu @Ort (cus +Ord))
(nm +Item @Item (itm +Pos) ord)
(nm +CuSu @Sup (sup +Item) (itm +Pos) ord) )
While (nr +Ord @Nr) and (dat +Ord @Dat) are direct
index traversals, (nm +CuSu @Cus (cus +Ord)) iterates the
nm (name) index of customers/suppliers +CuSu, and then
follows the +Ref +Link of the cus relation to the
orders. The same applies to the search for city names via ort.
The most complex example is (nm +CuSu @Sup (sup +Item) (itm +Pos)
ord), where the supplier name is searched in the nm tree of
+CuSu, then the +Ref tree
(sup +Item) tree is followed to locate items of that supplier, then
all positions for those items are found using (itm +Pos), and
finally the ord +Joint
is followed to arrive at the order object(s).
In the most general case, a generator clause can be an arbitrary Pilog query.
Often this is a query to a database on a remote machine, using the remote/2 predicate, or some other resource
not accessible via database indexes, like iterating a +List of +Links or +Joints.
Syntactically, such a generator clause is recognized by the fact that its CAR is a Pilog variable to denote the return value.
The second argument is a list of Pilog variables to communicate values (via
unify) from the surrounding
select environment.
The third argument is the actual list of clauses for the nested query.
Finally, an arbitrary number of association specifiers may follow, as described in the Indirect Object Associations section.
We can illustrate this with a somewhat useless (but simple) example, which replaces the standard generators for item number and supplier name
(select (@Item)
(
(nr +Item @Nr)
(nm +CuSu @Sup (sup +Item))
)
...
with the equivalent form
(select (@Item)
(
(@A (@Nr) ((db nr +Item @Nr @A)))
(@B (@Sup) ((db nm +CuSu @Sup @B)) (sup +Item))
)
That is, a query with the db/3 tree
iteration predicate is used to generate appropriate values.
The generator clauses produce - independent from each other - lots of
objects, which match the patterns of individual generator clauses, but not
necessarily the desired result set of the total select call.
Therefore, the filter clauses are needed to retain the good, and throw away the
bad objects. In addition, they give feedback to the generator for optimizing its
traversal priorities (as described in Generator Clauses).
select then collects all objects which passed through the
filters into a unique list, to avoid duplicates which would otherwise appear,
because most objects can be found by more than one generator clause.
Technically, the filters are normal Pilog clauses, which just happen to be
evaluated in the context of select. Arbitrary Pilog predicates can
be used, though there exist some predicates (e.g. isa/2, same/3, bool/3, range/3, head/3, fold/3, part/3 or tolr/3) especially suited for that task.
Assume we want to know how many pieces of item #2 were sold in the year 2007.
Then we must find all +Pos (position) objects referring to that
item and at the same time belonging to orders of the year 2007 (see the class
definition for +Pos in "app/er.l"). The number of sold pieces is
then in the cnt property of the +Pos objects.
As shown in the complete select below, we will hold the item
number in the variable @Nr and the date range for the year in
@Year.
Now, all positions referred by item #2 can be found by the generator clause
(nr +Item @Nr (itm +Pos))
and all positions sold in 2007 can be found by
(dat +Ord @Year pos)
However, the combination of both generator clauses
(select (@Pos)
((nr +Item @Nr (itm +Pos)) (dat +Ord @Year pos)) )
will probably generate too many results, namely all positions with item #3 OR from the year 2007. Thus, we need two filter clauses. With them, the full search expression will be:
(?
@Nr 2 # Item number
@Year (cons (date 2007 1 1) (date 2007 12 31)) # Date range 2007
(select (@Pos)
((nr +Item @Nr (itm +Pos)) (dat +Ord @Year pos)) # Generator clauses
(same @Nr @Pos itm nr) # Filter item number
(range @Year @Pos ord dat) ) ) # Filter order date
For completeness, let's calculate the total count of sold items:
(let Cnt 0 # Counter variable
(pilog
(quote
@Nr 2
@Year (cons (date 2007 1 1) (date 2007 12 31))
(select (@Pos)
((nr +Item @Nr (itm +Pos)) (dat +Ord @Year pos))
(same @Nr @Pos itm nr)
(range @Year @Pos ord dat) ) )
(inc 'Cnt (get @Pos 'cnt)) ) # Increment total count
Cnt ) # Return count
As mentioned under Filter Clauses, some predicates
exists mainly for select filtering.
Some of these predicates are of general use: isa/2 can be used to check for a type,
same/3 checks for a definite vaue,
bool/3 looks if the value is
non-NIL. These predicates are rather independent of the +relation type.
range/3 checks whether a value
is within a given range. This could be used with any +relation type, but typically it will be
used for numeric (+Number) or time
( +Date and +Time) relations.
Other predicates make only sense in the context of a certain +relation type:
head/3 is mainly intended for
(+Key +String) or (+Ref +String)
relations,
fold/3 is useful for (+Fold +Ref +String) relations,
part/3 for (+Fold +Idx +String) relations, and
tolr/3 for (+Sn +Idx +String) relations.
(c) Software Lab. Alexander Burger
This document demonstrates some aspects of the PicoLisp system in detail and example. For a general description of the PicoLisp kernel please look at the PicoLisp Reference.
This is not a Lisp tutorial, as it assumes some basic knowledge of programming, Lisp, and even PicoLisp. Please read these sections before coming back here: Introduction and The PicoLisp Machine. This tutorial concentrates on the specificities of PicoLisp, and its differences with other Lisp dialects.
If not stated otherwise, all examples assume that PicoLisp was started from a global installation (see Installation) from the shell prompt as
$ pil +
:
It loads the PicoLisp base system and the debugging environment, and waits
for you to enter input lines at the interpreter prompt (:). You can
terminate the interpreter and return to the shell at any time, by either hitting
the Ctrl-D key, or by executing the function (bye).
Please note that special handling is done during character input. This one
is incompatible with rlwrap for example but is more powerful.
vi-like command-line editing (typos fixes and history with ESC,
h, j, k and l but not
arrows)," appear).If you prefer to use Emacs, please use the picolisp-mode bundled in the "el/" directory (that is "@lib/el" for a local installation, or some system dependent directory for a global installation).
If you feel that you absolutely have to use an IDE, rlwrap or
another input front-end, please create an empty "~/.pil/editor" file. This
effectively disables the command line editor. Note that in this case, however,
you will not have the TAB symbol completion feature available during command
line editing.
If you are new to PicoLisp, you might want to read the following sections in the given order, as some of them assume knowledge about previous ones. Otherwise just jump anywhere you are interested in.
PicoLisp permanently reads input from the current input channel (i.e. the console in interactive mode), evaluates it, and prints the result to the current output channel. This is called a "read-eval-print-loop" (REPL).
This is the default line editor, as it needs less system resources and works also on dumb terminals. It is similar to - though simpler than - the 'vi' edit modes of the 'korn' and 'bash' shells. For an analog 'emacs' style editor, please see below.
It is very helpful - though not absolutely necessary - when you know how to
use the vi text editor.
To alleviate the task of manual line input, a command line editor is provided
which is similar to (though much simpler than) the readline feature
of the bash shell. Only a subset of the vi mode is
supported, which is restricted to single-key commands (the "real"
vi supports multi-key commands and the modification of most
commands with count prefixes). It is loaded at startup in debug mode, you find
its source in "lib/led.l".
You can enter lines in the normal way, correcting mistypes with the BACKSPACE key, and terminating them with the ENTER key. This is the Insert Mode.
If you hit ESC, you get into Command Mode. Now you can navigate
horizontally in the current input line, or vertically in the history of
previously entered lines, with key commands borrowed from the vi
editor (only h, j, k and l
and not arrows). Note, however, that there is always only a single line visible.
Let's say you did some calculation
: (* (+ 2 3) (- 7 2))
-> 25
:
If you want to repeat a modified version of this command, using
8 instead of 7, you don't have to re-type the
whole command, but type
k to get one line "up"
f and 7 to "find" the character 7
r and 8 to "replace" with 8
Then you hit ENTER to execute the modified line. Instead of jumping to the
7 with the "find" command, you may also type l (move
"right") repeatedly till you reach the correct position.
The key commands in the Command Mode are listed below. Some commands change the mode back to Insert Mode as indicated in parentheses. Deleting or changing a "word" take either the current atom (number or symbol), or a whole expression when the cursor is at a left parenthesis.
k - Go up one line
j - Go down one line
l - Go right one character
h - Go left one character
w - Go right one word
b - Go back (left) one word
0 - Go to the beginning of the line
$ - Go to the end of the line
i - Enter Insert Mode at the cursor position
a - Append (Insert Mode) after the cursor position
A - Append (Insert Mode) at the end of the line
I - Insert (Insert Mode) at the beginning of the line
x - Delete the character at the cursor position
X - Delete the character left of the cursor position
r - Replace the character at the cursor position with the next key
s - Substitute the character at the cursor position (Insert Mode)
S - Substitute the whole line (Insert Mode)
d - Delete the word at the cursor position (Insert Mode)
D - Delete the rest of the line
c - Change the word at the cursor position (Insert Mode)
C - Change the rest of the line (Insert Mode)
f - Find next key in the rest of the current line
p - Paste data deleted with x, X, d or D after the cursor position
P - Paste data deleted with x, X, d or D before the cursor position
/ - Accept an input pattern and search the history for it
n - Search for next occurrence of pattern (as entered with /)
N - Search for previous occurrence of pattern
% - Go to matching parenthesis
~ - Convert character to opposite (lower or upper) case and move right
u - Undo the last change (one level only)
U - Undo all changes of the current line
g - Display current contents of cut buffer (not in vi)
Notes:
d command corresponds to the dw command of the
vi editor, and c corresponds to cw.
@" characters as wildcards.
The following two key-combinations work both in Insert and Command Mode:
Ctrl-D will immediately terminate the current process.
Ctrl-X discards all input, abandons further processing, and
returns to the interpreter's top level (equivalent to invoking quit). This is also useful when the program
stopped at a breakpoint (see single-stepping Debugging), or
after program execution was interrupted with Ctrl-C.
Besides these two keys, in Insert Mode only the following keys have a special meaning:
Ctrl-H) and DEL erase the character to the left
Ctrl-V inserts the next key literally
Ctrl-E lets you edit
the history
You can switch the command line editor to an 'emacs' style, if you call the
function (em) (i.e. without arguments). A single call is enough.
Alternatively, you could invoke PicoLisp at least once with the -em
command line option
$ pil -em +
:
The style will be remembered in a file "~/.pil/editor", and used in all subsequent PicoLisp sessions.
To switch back to 'vi' style, call (vi), use the
-vi command line option, or simply remove "~/.pil/editor".
Please take some time to experiment and to get used to command line editing. It will make life much easier in the future :-)
PicoLisp provides some functionality for inspecting pieces of data and code within the running system.
print,
size
...
But you will appreciate some more powerful tools like:
match, a predicate which
compares S-expressions with bindable wildcards when matching,The most commonly used tool is probably the show function. It takes a symbolic argument,
and shows the symbol's name (if any), followed by its value, and then the
contents of the property list on the following lines (assignment of such things
to a symbol can be done with set,
setq, and put).
: (setq A '(This is the value)) # Set the value of 'A'
-> (This is the value)
: (put 'A 'key1 'val1) # Store property 'key1'
-> val1
: (put 'A 'key2 'val2) # and 'key2'
-> val2
: (show 'A) # Now 'show' the symbol 'A'
A (This is the value)
key2 val2
key1 val1
-> A
show accepts an arbitrary number of arguments which are
processed according to the rules of get, resulting in a symbol which is showed then.
: (put 'B 'a 'A) # Put 'A' under the 'a'-property of 'B'
-> A
: (setq Lst '(A B C)) # Create a list with 'B' as second argument
-> (A B C)
: (show Lst 2 'a) # Show the property 'a of the 2nd element of 'Lst'
A (This is the value) # (which is 'A' again)
key2 val2
key1 val1
-> A
Similar to show is edit. It takes an arbitrary number of symbolic
arguments, writes them to a temporary file in a format similar to
show, and starts the vim editor with that file.
: (edit 'A 'B)
The vim window will look like
A (This is the value)
key1 val1
key2 val2
(********)
B NIL
a A # (This is the value)
(********)
Now you can modify values or properties. You should not touch the
parenthesized asterisks, as they serve as delimiters. If you position the cursor
on the first character of a symbol name and type 'K' ("Keyword
lookup"), the editor will be restarted with that symbol added to the editor
window. 'Q' (for "Quit") will bring you back to the previous view.
edit is also very useful to browse in a database. You can follow
the links between objects with 'K', and even - e.g. for low-level
repairs - modify the data (but only if you are really sure about what you are
doing, and don't forget to commit
when you are done).
The pretty-print function pp
takes a symbol that has a function defined (or two symbols that specify message
and class for a method definition), and displays that definition in a formatted
and indented way.
: (pp 'pretty)
(de pretty (X N . @)
(setq N (abs (space (or N 0))))
(while (args)
(printsp (next)) )
(if (or (atom X) (>= 12 (size X)))
(print X)
(while (== 'quote (car X))
(prin "'")
(pop 'X) )
(let Z X
(prin "(")
(cond
((and (pair (car X)) (> (size @) 12))
(pretty (pop 'X) (- -3 N)) )
((memq (print (pop 'X)) *PP)
(cond
((memq (car Z) *PP1)
(if (and (pair (car X)) (pair (cdar X)))
(when (>= 12 (size (car X)))
(space)
(print (pop 'X)) )
(space)
(print (pop 'X))
(when (or (atom (car X)) (>= 12 (size (car X))))
(space)
(print (pop 'X)) ) ) )
((memq (car Z) *PP2)
(inc 'N 3)
(loop
(prinl)
(pretty (cadr X) N (car X))
(NIL (setq X (cddr X)) (space)) ) )
((or (atom (car X)) (>= 12 (size (car X))))
(space)
(print (pop 'X)) ) ) )
((and (memq (car Z) *PP3) (>= 12 (size (head 2 X))))
(space)
(print (pop 'X) (pop 'X)) ) )
(when X
(loop
(T (== Z X) (prin " ."))
(T (atom X) (prin " . ") (print X))
(prinl)
(pretty (pop 'X) (+ 3 N))
(NIL X) )
(space) )
(prin ")") ) ) )
-> pretty
The style is the same as we use in source files:
size is greater than 12), pretty-print the CAR
on the current line, and each element of the CDR recursively on its own line.
more is a simple tool that displays
the elements of a list one by one. It stops after each element and waits for
input. If you just hit ENTER, more continues with the next element,
otherwise (usually I type a dot (.) followed by ENTER) it
terminates.
: (more (1 2 3 4 5 6))
1 # Hit ENTER
2. # Hit '.' and ENTER
-> T # stopped
Optionally more takes a function as a second argument and
applies that function to each element (instead of the default print). Here, often show or
pp (see below) is used.
: (more '(A B)) # Step through 'A' and 'B'
A
B
-> NIL
: (more '(A B) show) # Step through 'A' and 'B' with 'show'
A (This is the value) # showing 'A'
key2 val2
key1 val1
# Hit ENTER
B NIL # showing 'B'
a A
-> NIL
The what function returns a list of
all internal symbols in the system which match a given pattern (with
'@' wildcard characters).
: (what "prin@")
-> (prin print prinl print> printsp println)
The function who returns "who
contains that", i.e. a list of symbols that contain a given argument
somewhere in their value or property list.
: (who 'print)
-> (query pretty pp msg more "edit" view show (print> . +Date) rules select
(print> . +relation))A dotted pair indicates either a method definition or a property entry. So
(print> . +relation) denotes the print> method of
the +relation class.
who can be conveniently combined with more and
pp:
: (more (who 'print) pp)
(de query ("Q" "Dbg") # Pretty-print these functions one by one
(use "R"
(loop
(NIL (prove "Q" "Dbg"))
(T (=T (setq "R" @)) T)
(for X "R"
(space)
(print (car X))
(print '=)
(print (cdr X))
(flush) )
(T (line)) ) ) )
(de pretty (X N . @)
...
The argument to who may also be a pattern list (see match):
: (who '(print @ (val @)))
-> (show)
: (more (who '(% @ 7)) pp)
(de day (Dat Lst)
(get
(or Lst *DayFmt)
(inc (% (inc Dat) 7)) ) )
(de _week (Dat)
(/ (- Dat (% (inc Dat) 7)) 7) )
The function can returns a list
which indicates which classes can accept a given message. Again, this
list is suitable for iteration with pp:
: (can 'del>) # Which classes accept 'del>' ?
-> ((del> . +List) (del> . +Entity) (del> . +relation))
: (more (can 'del>) pp) # Inspect the methods with 'pp'
(dm (del> . +List) (Obj Old Val)
(and ((<> Old Val) (delete Val Old)) )
(dm (del> . +Entity) (Var Val)
(when
(and
Val
(has> (meta This Var) Val (get This Var)) )
(let Old (get This Var)
(rel>
(meta This Var)
This
Old
(put This Var (del> (meta This Var) This Old @)) )
(when (asoq Var (meta This 'Aux))
(relAux This Var Old (cdr @)) )
(upd> This Var Old) ) ) )
(dm (del> . +relation) (Obj Old Val)
(and ((<> Old Val) Val) )
dep shows the dependencies in a
class hierarchy. That is, for a given class it displays the tree of its
(super)class(es) above it, and the tree of its subclasses below it.
To view the complete hierarchy of input fields, we start with the root class
+relation:
: (dep '+relation)
+relation
+Bag
+Any
+Blob
+Link
+Joint
+Bool
+Symbol
+String
+Number
+Time
+Date
-> +relation
If we are interested in +Link:
: (dep '+Link)
+relation
+Link
+Joint
-> +Link
This says that +Link is a subclass of +relation, and has a single subclass
(+Joint).
Most of the time during programming is spent defining functions (or methods).
In the following we will concentrate on functions, but most will be true for
methods as well except for using dm
instead of de.
The notorious "Hello world" function must be defined:
: (de hello ()
(prinl "Hello world") )
-> hello
The () in the first line indicates a function without arguments.
The body of the function is in the second line, consisting of a single
statement. The last line is the return value of de, which here is
the defined symbol. From now on we will omit the return values of examples when
they are unimportant.
Now you can call this function this way:
: (hello)
Hello world
A function with an argument might be defined this way:
: (de hello (X)
(prinl "Hello " X) )
# hello redefined
-> hello
PicoLisp informs you that you have just redefined the function. This might be a useful warning in case you forgot that a bound symbol with that name already existed.
: (hello "world")
Hello world
: (hello "Alex")
Hello Alex
Normally, PicoLisp evaluates the arguments before it passes them to a function:
: (hello (+ 1 2 3))
Hello 6
: (setq A 1 B 2) # Set 'A' to 1 and 'B' to 2
-> 2
: (de foo (X Y) # 'foo' returns the list of its arguments
(list X Y) )
-> foo
: (foo A B) # Now call 'foo' with 'A' and 'B'
-> (1 2) # -> We get a list of 1 and 2, the values of 'A' and 'B'
In some cases you don't want that. For some functions (setq for example) it is better if the function
gets all arguments unevaluated, and can decide for itself what to do with them.
For such cases you do not define the function with a list of parameters, but give it a single atomic parameter instead. PicoLisp will then bind all (unevaluated) arguments as a list to that parameter.
: (de foo X
(list (car X) (cadr X)) ) # 'foo' lists the first two arguments
: (foo A B) # Now call it again
-> (A B) # -> We don't get '(1 2)', but '(A B)'
: (de foo X
(list (car X) (eval (cadr X))) ) # Now evaluate only the second argument
: (foo A B)
-> (A 2) # -> We get '(A 2)'
As a logical consequence, you can combine these principles. To define a function with 2 evaluated and an arbitrary number of unevaluated arguments:
: (de foo (X Y . Z) # Evaluate only the first two args
(list X Y Z) )
: (foo A B C D E)
-> (1 2 (C D E)) # -> Get the value of 'A' and 'B' and the remaining list
More common, in fact, is the case where you want to pass an arbitrary number
of evaluated arguments to a function. For that, PicoLisp recognizes the
symbol @ as a single atomic parameter and remembers all evaluated
arguments in an internal frame. This frame can then be accessed sequentially
with the args, next, arg and rest functions.
: (de foo @
(list (next) (next)) ) # Get the first two arguments
: (foo A B)
-> (1 2)
Again, this can be combined:
: (de foo (X Y . @)
(list X Y (next) (next)) ) # 'X' and 'Y' are fixed arguments
: (foo A B (+ 3 4) (* 3 4))
-> (1 2 7 12) # All arguments are evaluated
These examples are not very useful, because the advantage of a variable number of arguments is not used. A function that prints all its evaluated numeric arguments, each on a line followed by its squared value:
: (de foo @
(while (args) # Check if there are some args left
(println (next) (* (arg) (arg))) ) ) # Call the last arg (next) returned
: (foo (+ 2 3) (- 7 1) 1234 (* 9 9))
5 25
6 36
1234 1522756
81 6561
-> 6561
This next example shows the behaviour of args and
rest:
: (de foo @
(while (args)
(next)
(println (arg) (args) (rest)) ) )
: (foo 1 2 3)
1 T (2 3)
2 T (3)
3 NIL NIL
Finally, it is possible to pass all these evaluated arguments to another
function, using pass:
: (de foo @
(pass println 9 8 7) # First print all arguments preceded by 9, 8, 7
(pass + 9 8 7) ) # Then add all these values
: (foo (+ 2 3) (- 7 1) 1234 (* 9 9))
9 8 7 5 6 1234 81 # Printing ...
-> 1350 # Return the result
quote will do what you want (see
also this FAQ entry).
: ((quote (X) (* X X)) 9)
-> 81
: (setq f '((X) (* X X))) # This is equivalent to (de f (X) (* X X))
-> ((X) (* X X))
: f
-> ((X) (* X X))
: (f 3)
-> 9
There are two major ways to debug functions (and methods) at runtime: Tracing and single-stepping.
In this section we will use the REPL to explore the debugging facilities, but in the Scripting section, you will learn how to launch PicoLisp scripts with some selected functions debugged:
$ pil app/file1.l -"trace 'foo" -main -"debug 'bar" app/file2.l +
Tracing means letting functions of interest print their name and arguments when they are entered, and their name again and the return value when they are exited.
For demonstration, let's define the unavoidable factorial function (or just
load the file "@doc/fun.l"):
(de fact (N)
(if (=0 N)
1
(* N (fact (dec N))) ) )
With trace we can put it in trace
mode:
: (trace 'fact)
-> fact
Calling fact now will display its execution trace.
: (fact 3)
fact : 3
fact : 2
fact : 1
fact : 0
fact = 1
fact = 1
fact = 2
fact = 6
-> 6
As can be seen here, each level of function call will indent by an additional
space. Upon function entry, the name is separated from the arguments with a
colon (:), and upon function exit with an equals sign
(=) from the return value.
trace works by modifying the function body, so generally it
works only for functions defined as lists (lambda expressions, see Evaluation). Tracing a C-function is possible, however,
when it is a function that evaluates all its arguments.
So let's trace the functions =0 and
*:
: (trace '=0)
-> =0
: (trace '*)
-> *
If we call fact again, we see the additional output:
: (fact 3)
fact : 3
=0 : 3
=0 = NIL
fact : 2
=0 : 2
=0 = NIL
fact : 1
=0 : 1
=0 = NIL
fact : 0
=0 : 0
=0 = 0
fact = 1
* : 1 1
* = 1
fact = 1
* : 2 1
* = 2
fact = 2
* : 3 2
* = 6
fact = 6
-> 6
To reset a function to its untraced state, call untrace:
: (untrace 'fact)
-> fact
: (untrace '=0)
-> =0
: (untrace '*)
-> *
or simply use mapc:
: (mapc untrace '(fact =0 *))
-> *
Single-stepping means to execute a function step by step, giving the
programmer an opportunity to look more closely at what is happening. The
function debug inserts a breakpoint
into each top-level expression of a function. When the function is called, it
stops at each breakpoint, displays the expression it is about to execute next
(this expression is also stored into the global variable ^) and enters a read-eval-loop. The programmer can
then
(d) to recursively debug the
next expression (looping through subexpressions of this expression)
(e) to evaluate the next
expression, to see what will happen without actually advancing on
Thus, in the simplest case, single-stepping consists of just hitting ENTER repeatedly to step through the function.
To try it out, let's look at the stamp system function. You may need to have a
look at
=T (T test),date and time (grab system date and time)
default (conditional
assignments)
pack (kind of concatenation), and
dat$ and tim$ (date and time formats)
: (pp 'stamp)
(de stamp (Dat Tim)
(and (=T Dat) (setq Dat (date T)))
(default Dat (date) Tim (time T))
(pack (dat$ Dat "-") " " (tim$ Tim T)) )
-> stamp
: (debug 'stamp) # Debug it
-> T
: (stamp) # Call it again
(and (=T Dat) (setq Dat (date T))) # stopped at first expression
! # ENTER
(default Dat (date) Tim (time T)) # second expression
! # ENTER
(pack (dat$ Dat "-") " " (tim$ ... # third expression
! Tim # inspect 'Tim' variable
-> 41908
! (time Tim) # convert it
-> (11 38 28)
! # ENTER
-> "2004-10-29 11:38:28" # done, as there are only 3 expressions
Now we execute it again, but this time we want to look at what's happening inside the second expression.
: (stamp) # Call it again
(and (=T Dat) (setq Dat (date T)))
! # ENTER
(default Dat (date) Tim (time T))
! # ENTER
(pack (dat$ Dat "-") " " (tim$ ... # here we want to look closer
! (d) # debug this expression
-> T
! # ENTER
(dat$ Dat "-") # stopped at first subexpression
! (e) # evaluate it
-> "2004-10-29"
! # ENTER
(tim$ Tim T) # stopped at second subexpression
! (e) # evaluate it
-> "11:40:44"
! # ENTER
-> "2004-10-29 11:40:44" # done
The breakpoints still remain in the function body. We can see them when we pretty-print it:
: (pp 'stamp)
(de stamp (Dat Tim)
(! and (=T Dat) (setq Dat (date T)))
(! default Dat (date) Tim (time T))
(! pack
(! dat$ Dat "-")
" "
(! tim$ Tim T) ) )
-> stamp
To reset the function to its normal state, call unbug:
: (unbug 'stamp)
Often, you will not want to single-step a whole function. Just use
edit (see above) to insert a single breakpoint (the exclamation
mark followed by a space) as CAR of an expression, and run your program.
Execution will then stop there as described above; you can inspect the
environment and continue execution with ENTER when you are done.
Input and output in PicoLisp is functional, in the sense that there are not variables assigned to file descriptors, which need then to be passed to I/O functions for reading, writing and closing. Instead, these functions operate on implicit input and output channels, which are created and maintained as dynamic environments.
Standard input and standard output are the default channels. Try reading a single expression:
: (read)
(a b c) # Console input
-> (a b c)
To read from a file, we redirect the input with in. Note that comments and whitespace are
automatically skipped by read:
: (in "@doc/fun.l" (read))
-> (de fact (N) (if (=0 N) 1 (* N (fact (dec N)))))
The skip function can also be used
directly. To get the first non-white character in the file with char:
: (in "@doc/fun.l" (skip "#") (char))
-> "("
from searches through the input
stream for given patterns. Typically, this is not done with Lisp source files
(there are better ways), but for a simple example let's extract all items
immediately following fact in the file,
: (in "@doc/fun.l" (while (from "fact ") (println (read))))
(N)
(dec N)
or the word following "(de " with till:
: (in "@doc/fun.l" (from "(de ") (till " " T)))
-> "fact"
With line, a line of characters is
read, either into a single transient symbol
(the type used by PicoLisp for strings),
: (in "@doc/tut.html" (line T))
-> "<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://..."
or into a list of symbols (characters):
: (in "@doc/tut.html" (line))
-> ("<" "!" "D" "O" "C" "T" "Y" "P" "E" " " "H" "T" "M" "L" ...
line is typically used to read tabular data from a file.
Additional arguments can split the line into fixed-width fields, as described in
the reference manual. If, however, the
data are of variable width, delimited by some special character, the split function can be used to extract the
fields. A typical way to import the contents of such a file is:
(load "@lib/import.l")
(in '("bin/utf2" "importFile.txt") # Pipe: Convert to UTF-8
(until (eof) # Process whole file
(let L (split (line) "^I") # TAB-delimited data
... use 'getStr', 'getNum' etc ... # process them
Some more examples with echo:
(in "a" # Copy the first 40 Bytes
(out "b" # from file "a" to file "b"
(echo 40) ) )
(in "@doc/tut.html" # Show the HTTP-header
(line)
(echo "<body>") )
(out "file.mac" # Convert to Macintosh
(in "file.txt" # from Unix or DOS format:
(while (char)
(prin
(case @
("^M" NIL) # ignore CR
("^J" "^M") # convert CR to LF
(T @) ) ) ) ) ) # otherwise no change
(out "c" # Merge the contents of "a"
(in "b" # and "b" into "c"
(in "a"
(while (read) # Read an item from "a",
(println @ (in -1 (read))) ) ) ) ) # print it with an item from "b"
There are two possibilities to get the PicoLisp interpreter into doing useful work: via command line arguments, or as a stand-alone script.
The command line can specify either files for execution, or arbitrary Lisp
expressions for direct evaluation (see Invocation):
if an argument starts with a hyphen, it is evaluated, otherwise it is loaded as a file. A typical invocation might
look like:
$ pil app/file1.l -main app/file2.l +
It loads the debugging environment, an application source file, calls the main function, and then loads another application source. In a typical development and debugging session, this line is often modified using the shell's history mechanisms, e.g. by inserting debugging statements:
$ pil app/file1.l -"trace 'foo" -main -"debug 'bar" app/file2.l +
Another convenience during debugging and testing is to put things into the command line (shell history) which would otherwise have to be done each time in the application's user interface:
$ pil app/file1.l -main app/file2.l -go -'login "name" "password"' +
The final production release of an application usually includes a shell script, which initializes the environment, does some bookkeeping and cleanup, and calls the application with a proper command line. It is no problem if the command line is long and complicated.
For small utility programs, however, this is overkill. Enter full PicoLisp scripts.
#!", the operating
system kernel will pass this file to an interpreter program whose pathname is
given in the first line (optionally followed by a single argument). This is fast
and efficient, because the overhead of a subshell is avoided.
Let's assume you installed PicoLisp in the directory "/home/foo/picolisp/", and put links to the executable and the installation directory as:
$ ln -s /home/foo/picolisp /usr/lib/picolisp
$ ln -s /usr/lib/picolisp/bin/picolisp /usr/bin/picolisp
#!/usr/bin/picolisp /usr/lib/picolisp/lib.l
(prinl "Hello world!")
(bye)
If you write this into a text file, and use chmod to set it to
"executable", it can be executed like any other command. Note that (because
# is the comment character in PicoLisp) the first line will not be
interpreted, and you can still use that file as a normal command line argument
to PicoLisp (useful during debugging).
The fact that a hyphen causes evaluation of command line arguments can be
used to simulate something like command line options. The following script
defines two functions a and f, and then calls
(load T) to process the rest of the
command line (which otherwise would be ignored because of the (bye) statement):
#!/usr/bin/picolisp /usr/lib/picolisp/lib.l
(de a ()
(println '-a '-> (opt)) )
(de f ()
(println '-f '-> (opt)) )
(load T)
(bye)
opt retrieves the next command line
option)
Calling this script (let's say we named it "testOpts") gives:
$ ./testOpts -f abc
-f -> "abc"
$ ./testOpts -a xxx -f yyy
-a -> "xxx"
-f -> "yyy"
We have to be aware of the fact, however, that the aggregation of arguments like
$ ./testOpts -axxx -fyyy
or
$ ./testOpts -af yyy
cannot be achieved with this simple and general mechanism of command line processing.
Utilities are typically used outside the context of the PicoLisp environment. All examples above assumed that the current working directory is the PicoLisp installation directory, which is usually all right for applications developed in that environment. Command line file arguments like "app/file1.l" will be properly found.
To allow utilities to run in arbitrary places on the host file system, the
concept of home directory substitution was introduced. The interpreter
remembers internally at start-up the pathname of its first argument (usually
"lib.l"), and substitutes any leading "@" character in subsequent
file names with that pathname. Thus, to run the above example in some other
place, simply write:
$ /home/foo/picolisp/pil @app/file1.l -main @app/file2.l +
that is, supply a full path name to the initial command (here 'p'), or put it
into your PATH variable, and prefix each file which has to be
loaded from the PicoLisp home directory with a @ character.
"Normal" files (not prefixed by @) will be opened or created
relative to the current working directory as usual.
Stand-alone scripts will often want to load additional modules from the PicoLisp environment, beyond the "lib.l" we provided in the first line of the hello-world script. Typically, at least a call to
(load "@lib/misc.l")
(note the home directory substitution) will be included near the beginning of the script.
As a more complete example, here is a script which extracts the date, name and size of the latest official PicoLisp release version from the download web site, and prints it to standard output:
#!/usr/bin/picolisp /usr/lib/picolisp/lib.l
(load "@lib/misc.l" "@lib/http.l")
(use (@Date @Name @Size)
(when
(match
'(@Date ~(chop " - <a href=\"") @Name "\"" ">"
@Name ~(chop "</a> (") @Size )
(client "software-lab.de" 80 "down.html"
(from "Release Archive")
(from "<li>")
(till ",") ) )
(prinl @Name)
(prinl @Date " -- " @Size) ) )
(bye)
We recommend that you have a terminal window open, and try the examples by
yourself. You may either type them in, directly to the PicoLisp interpreter, or
edit a separate source file (e.g. "@doc/fun.l") in a second
terminal window and load it into PicoLisp with
: (load "@doc/fun.l")
each time you have modified and saved it.
Once a function is loaded from a source file, you can call 'vim' directly on that function with
: (vi 'fact)
The function 'vi' opens the appropriate source file, and jumps to the right line where 'fact' is defined. When you modify it, you can simply call 'ld' to (re)load that source file
: (ld)
The PicoLisp object model is very simple, yet flexible and powerful. Objects as well as classes are both implemented as symbols. In fact, there is no formal difference between objects and classes; classes are more a conceptual design consideration in the head of the programmer than a physical reality.
Having said this, we declare that normally:
So the main difference between classes and objects is that the former ones
usually are internal symbols. By convention, their names start with a
'+'. Sometimes it makes sense, however, to create named objects (as
global singletons, for example), or even anonymous classes.
Both classes and objects have a list in their value, consisting of method definitions (often empty for objects) and (super)class(es). And both classes and objects have local data in their property lists (often empty for classes). This implies, that any given object (as an instance of a class) may have private (object-local) methods defined.
It is rather difficult to contrive a simple OOP example. We constructed a
hierarchy of geometric shapes, with a base class +Shape and two
subclasses +Rectangle and +Circle.
The source code is included as "@doc/shape.l" in the PicoLisp distribution, so you
don't have to type it in. Just load
the file, or start it from the shell as:
$ pil @doc/shape.l +
Let's look at it piece by piece. Here's the base class:
(class +Shape)
# x y
(dm T (X Y)
(=: x X)
(=: y Y) )
(dm move> (DX DY)
(inc (:: x) DX)
(inc (:: y) DY) )
The first line '(class +Shape)' defines the symbol
+Shape as a class without superclasses. The following method
definitions will go to that class.
The comment '# x y' in the second line is just a convention, to
indicate what instance variables (properties) that class uses. As PicoLisp is a
dynamic language, a class can be extended at runtime with any number of
properties, and there is nothing like a fixed object size or structure. This
comment is a hint of what the programmer thinks to be essential and typical for
that class. In the case of +Shape, x and
y are the coordinates of the shape's origin.
Then we have two method definitions, using the keyword dm for "define method". The first method is
special, in that its name is T. Each time a new object is created,
and a method with that name is found in its class hierarchy, that method will be
executed. Though this looks like a "constructor" in other programming languages,
it should probably better be called "initializer". The T method of
+Shape takes two arguments X and Y, and
stores them in the object's property list.
The second method move> changes the object's origin by adding
the offset values DX and DY to the object's origin.
Now to the first derived class:
(class +Rectangle +Shape)
# dx dy
(dm T (X Y DX DY)
(super X Y)
(=: dx DX)
(=: dy DY) )
(dm area> ()
(* (: dx) (: dy)) )
(dm perimeter> ()
(* 2 (+ (: dx) (: dy))) )
(dm draw> ()
(drawRect (: x) (: y) (: dx) (: dy)) )
+Rectangle is defined as a subclass of +Shape.
The comment '# dx dy' indicates that +Rectangle has a
width and a height in addition to the origin coordinates inherited from
+Shape.
The T method passes the origin coordinates X and
Y to the T method of the superclass
(+Shape), then stores the width and height parameters into
dx and dy.
Next we define the methods area> and
perimeter> which do some obvious calculations, and a method
draw> which is supposed to draw the shape on the screen by
calling some hypothetical function drawRect.
Finally, we define a +Circle class in an analog way, postulating
the hypothetical function drawCircle:
(class +Circle +Shape)
# r
(dm T (X Y R)
(super X Y)
(=: r R) )
(dm area> ()
(*/ (: r) (: r) 31415927 10000000) )
(dm perimeter> ()
(*/ 2 (: r) 31415927 10000000) )
(dm draw> ()
(drawCircle (: x) (: y) (: r)) )
Now we can experiment with geometrical shapes. We create a rectangle at point
(0,0) with a width of 30 and a height of 20, and keep it in the variable
R:
: (setq R (new '(+Rectangle) 0 0 30 20)) # New rectangle
-> $134432824 # returned anonymous symbol
: (show R)
$134432824 (+Rectangle) # Show the rectangle
dy 20
dx 30
y 0
x 0
We see that the symbol $134432824 has a list of classes
'(+Rectangle)' in its value, and the coordinates, width and height
in its property list.
Sending messages to that object
: (area> R) # Calculate area
-> 600
: (perimeter> R) # and perimeter
-> 100
will return the values for area and perimeter, respectively.
Then we move the object's origin:
: (move> R 10 5) # Move 10 right and 5 down
-> 5
: (show R)
$134432824 (+Rectangle)
y 5 # Origin changed (0,0) -> (10,5)
x 10
dy 20
dx 30
Though a method move> wasn't defined for the
+Rectangle class, it is inherited from the +Shape
superclass.
Similarly, we create and use a circle object:
: (setq C (new '(+Circle) 10 10 30)) # New circle
-> $134432607 # returned anonymous symbol
: (show C)
$134432607 (+Circle) # Show the circle
r 30
y 10
x 10
-> $134432607
: (area> C) # Calculate area
-> 2827
: (perimeter> C) # and perimeter
-> 188
: (move> C 10 5) # Move 10 right and 5 down
-> 15
: (show C)
$134432607 (+Circle) # Origin changed (10,10) -> (20,15)
y 15
x 20
r 30
It is also easy to send messages to objects in a list:
: (mapcar 'area> (list R C)) # Get list of areas
-> (600 2827)
: (mapc
'((Shape) (move> Shape 10 10)) # Move all 10 right and down
(list R C) )
-> 25
: (show R)
$134431493 (+Rectangle)
y 15
x 20
dy 20
dx 30
-> $134431493
: (show C)
$134431523 (+Circle)
y 25
x 30
r 30
Assume that we want to extend our shape system. From time to time, we need
shapes that behave exactly like the ones above, but are tied to a fixed
position. That is, they do not change their position even if they receive a
move> message.
One solution would be to modify the move> method in the
+Shape class to a no-operation. But this would require to duplicate
the whole shape hierarchy (e.g. by defining +FixedShape,
+FixedRectangle and +FixedCircle classes).
The PicoLisp Way is the use of Prefix Classes through multiple inheritance. It uses the fact that searching for method definitions is a depth-first, left-to-right search of the class tree. We define a prefix class:
: (class +Fixed)
(dm move> (DX DY)) # A do-nothing method
We can now create a fixed rectangle, and try to move it:
: (setq R (new '(+Fixed +Rectangle) 0 0 30 20)) # '+Fixed' prefix class
-> $134432881
: (move> R 10 5) # Send 'move>' message
-> NIL
: (show R)
$134432881 (+Fixed +Rectangle)
dy 20
dx 30
y 0 # Did not move!
x 0
We see, prefix classes can surgically change the inheritance tree for selected objects or classes.
Alternatively, if fixed rectangles are needed often, it might make sense to
define a new class +FixRect:
: (class +FixRect +Fixed +Rectangle)
-> +FixRect
and then use it directly:
: (setq R (new '(+FixRect) 0 0 30 20))
-> $13455710
PicoLisp has persistent objects built-in as a first class data type. With "first class" we mean not just the ability of being passed around, or returned from functions (that's a matter of course), but that they are a primary data type with their own interpreter tag bits. They are, in fact, a special type of symbolic atoms (called "External Symbols"), that happen to be read from pool file(s) when accessed, and written back automatically when modified.
In all other aspects they are normal symbols. They have a value, a property list and a name.
The name cannot be directly controlled by the programmer, as it is assigned
when the symbol is created. It is an encoded index of the symbol's location in
its database file. In its visual representation (output by the print functions and input by the read functions) it is surrounded by braces.
To make use of external symbols, you need to open a database first:
: (pool "test.db")
If a file with that name did not exist, it got created now. Also created at
the same moment was {1}, the very first symbol in the file. This
symbol is of great importance, and is handled especially by PicoLisp. Therefore
a global constant *DB exists, which
points to that symbol {1}, which should be used exclusively to
access the symbol {1}, and which should never be modified by the
programmer.
: *DB # The value of '*DB'
-> {1} # is '{1}'
: (show *DB)
{1} NIL # Value of '{1}' is NIL, property list empty
Now let's put something into the value and property list of {1}.
: (set *DB "Hello world") # Set value of '{1}' to a transient symbol (string)
-> "Hello world"
: (put *DB 'a 1) # Property 'a' to 1
-> 1
: (put *DB 'b 2) # Property 'b' to 2
-> 2
: (show *DB) # Now show the symbol '{1}'
{1} "Hello world"
b 2
a 1
Note that instead of '(set *DB "Hello world")', we might
also have written '(setq {1} "Hello world")', and instead of
'(put *DB 'a 1)' we might have written '(put '{1} 'a
1)'. This would have the same effect, but as a rule external symbols
should never be be accessed literally in application programs, because the
garbage collector might not be able to free these symbols and all symbols
connected to them (and that might well be the whole database). It is all right,
however, to access external symbols literally during interactive debugging.
Now we can create our first own external symbol. This can be done with
new when a T argument is
supplied:
: (new T)
-> {2} # Got a new symbol
We store it in the database root {1}:
: (put *DB 'newSym '{2}) # Literal '{2}' (ok during debugging)
-> {2}
: (show *DB)
{1} "Hello world"
newSym {2} # '{2}' is now stored in '{1}'
b 2
a 1
Put some property value into '{2}'
: (put *DB 'newSym 'x 777) # Put 777 as 'x'-property of '{2}'
-> 777
: (show *DB 'newSym) # Show '{2}' (indirectly)
{2} NIL
x 777
-> {2}
: (show '{2}) # Show '{2}' (directly)
{2} NIL
x 777
All modifications to - and creations of - external symbols done so far are
not written to the database yet. We could call rollback (or simply exit PicoLisp) to undo
all the changes. But as we want to keep them:
: (commit) # Commit all changes
-> T
: (bye) # Exit picolisp
$ # back to the shell
So, the next time when ..
$ pil + # .. we start PicoLisp
: (pool "test.db") # and open the database file,
-> T
: (show *DB) # our two symbols are there again
{1} "Hello world"
newSym {2}
b 2
a 1
-> {1}
: (show *DB 'newSym)
{2} NIL
x 777
-> {2}
To a database, there is more than just persistence. PicoLisp includes an entity/relation class framework (see also Database) which allows a close mapping of the application data structure to the database.
We provided a simple yet complete database and GUI demo application in
@doc/family.tgz and @doc/family64.tgz. Please unpack the first one if
you use a 32-bit system, and the second one on a 64-bit system. Both contain the
sources in @doc/family.l, and an initial
database in the "family/" subdirectory.
To use it, please unpack it first in your current working directory, then start it up in the following way:
$ pil family.l -main +
:
This loads the source file, initializes the database by calling the
main function, and prompts for user input.
The data model is small and simple. We define a class +Person
and two subclasses +Man and +Woman.
(class +Person +Entity)
+Person is a subclass of the +Entity system class. Usually all objects in
a database are of a direct or indirect subclass of +Entity. We can then define the relations to
other data with the rel function.
(rel nm (+Need +Sn +Idx +String)) # Name
This defines the name property (nm) of a person. The first
argument to rel is always a list of relation classes (subclasses of
+relation), optionally followed
by further arguments, causing relation daemon objects be created and stored in
the class definition. These daemon objects control the entity's behavior later
at runtime.
Relation daemons are a kind of metadata, controlling the interactions between entities, and maintaining database integrity. Like other classes, relation classes can be extended and refined, and in combination with proper prefix classes a fine-grained description of the application's structure can be produced.
Besides primitive relation classes, like +Number,
+String or +Date, there are
+Link (unidirectional link),
+Joint (bidirectional link) or +Hook (object-local
index trees)
+Bag)
+List prefix class
+Blob class for "binary large objects"
+Key (unique
index), +Ref (non-unique index) or +Idx (full text
index)
+Sn (modified soundex algorithm [knuth73]
for tolerant searches)
+Need prefix class, for existence checks
+Dep prefix class controlling dependencies between other
relations
In the case of the person's name (nm) above, the relation object
is of type (+Need +Sn +Idx +String). Thus, the name of each person
in this demo database is a mandatory attribute (+Need), searchable
with the soundex algorithm (+Sn) and a full index
(+Idx) of type +String.
(rel pa (+Joint) kids (+Man)) # Father
(rel ma (+Joint) kids (+Woman)) # Mother
(rel mate (+Joint) mate (+Person)) # Partner
The attributes for father (pa), Mother
(ma) and partner (mate) are all defined as
+Joints. A +Joint is probably the most powerful
relation mechanism in PicoLisp; it establishes a bidirectional link between two
objects.
The above declarations say that the father (pa) attribute
points to an object of type +Man, and is joined with that object's
kids attribute (which is a list of joints back to all his
children).
The consistency of +Joints is maintained automatically by the
relation daemons. These become active whenever a value is stored to a person's
pa, ma, mate or kids
property.
For example, interesting things happen when a person's mate is
changed to a new value. Then the mate property of the old mate's
object is cleared (she has no mate after that). Now when the person pointed to
by the new value already has a mate, then that mate's mate property
gets cleared, and the happy new two mates now get their joints both set
correctly.
The programmer doesn't have to care about all that. He just declares these
relations as +Joints.
The last four attributes of person objects are just static data:
(rel job (+Ref +String)) # Occupation
(rel dat (+Ref +Date)) # Date of birth
(rel fin (+Ref +Date)) # Date of death
(rel txt (+String)) # Info
They are all searchable via a non-unique index (+Ref). Date
values in PicoLisp are just numbers, representing the day number (starting first
of March of the year zero).
A method url> is defined:
(dm url> ()
(list "!person" '*ID This) )
It is needed later in the GUI, to cause a click on a link to switch to that object.
The classes +Man and +Woman are subclasses of
+Person:
(class +Man +Person)
(rel kids (+List +Joint) pa (+Person)) # Children
(class +Woman +Person)
(rel kids (+List +Joint) ma (+Person)) # Children
They inherit everything from +Person, except for the
kids attribute. This attribute joins with the pa or
ma attribute of the child, depending on the parent's gender.
That's the whole data model for our demo database application.
It is followed by a call to dbs
("database sizes"). This call is optional. If it is not present, the whole
database will reside in a single file, with a block size of 256 bytes. If it is
given, it should specify a list of items, each having a number in its CAR, and a
list in its CDR. The CARs taken together will be passed later to pool, causing an individual database file with that
size to be created. The CDRs tell what entity classes (if an item is a symbol)
or index trees (if an item is a list with a class in its CAR and a list of
relations in its CDR) should be placed into that file.
A handful of access functions is provided, that know about database relationships and thus allows higher-level access modes to the external symbols in a database.
For one thing, the B-Trees created and maintained by the index daemons can be used directly. Though this is rarely done in a typical application, they form the base mechanisms of other access modes and should be understood first.
The function tree returns the tree
structure for a given relation. To iterate over the whole tree, the functions
iter and scan can be used:
(iter (tree 'dat '+Person) '((P) (println (datStr (get P 'dat)) (get P 'nm))))
"1770-08-03" "Friedrich Wilhelm III"
"1776-03-10" "Luise Augusta of Mecklenburg-Strelitz"
"1797-03-22" "Wilhelm I"
...
They take a function as the first argument. It will be applied to all objects found in the tree (to show only a part of the tree, an optional begin- and end-value can be supplied), producing a simple kind of report.
More useful is collect; it
returns a list of all objects that fall into a range of index values:
: (collect 'dat '+Person (date 1982 1 1) (date 1988 12 31))
-> ({2-M} {2-L} {2-E})
This returns all persons born between 1982 and 1988. Let's look at them with
show:
: (more (collect 'dat '+Person (date 1982 1 1) (date 1988 12 31)) show)
{2-M} (+Man)
nm "William"
dat 724023
ma {2-K}
pa {2-J}
job "Heir to the throne"
{2-L} (+Man)
nm "Henry"
dat 724840
ma {2-K}
pa {2-J}
job "Prince"
{2-E} (+Woman)
nm "Beatrice"
dat 726263
ma {2-D}
job "Princess"
pa {2-B}
If you are only interested in a certain attribute, e.g. the name, you can return it directly:
: (collect 'dat '+Person (date 1982 1 1) (date 1988 12 31) 'nm)
-> ("William" "Henry" "Beatrice")
To find a single object in the database, the function db is used:
: (db 'nm '+Person "Edward")
-> {2-;}
If the key is not unique, additional arguments may be supplied:
: (db 'nm '+Person "Edward" 'job "Prince" 'dat (date 1964 3 10))
-> {2-;}
The programmer must know which combination of keys will suffice to specify the object uniquely. The tree search is performed using the first value ("Edward"), while all other attributes are used for filtering. Later, in the Pilog section, we will show how more general (and possibly more efficient) searches can be performed.
The only types of GUI supported by the PicoLisp application server framework is either dynamically generated (but static by nature) HTML, or an interactive XHTML/CSS framework with the optional use of JavaScript.
Before we explain the GUI of our demo database application, we present a
minimal example for a plain HTML-GUI in @doc/hello.l. Start the application server as:
$ pil @lib/http.l --server 8080 @doc/hello.l -wait
Now point your browser to the address 'http://localhost:8080'. You should see a
very simple HTML page. You can come back here with the browser's BACK button.
You can call the page repeatedly, or concurrently with many clients if you
like. To terminate the server, you have to send it a TERM signal (e.g.
'killall pil'), or type the Ctrl-C key in the console
window.
In our demo database application, a single function person is
responsible for the whole GUI. Again, please look at @doc/family.l.
To start the database and the application server, call:
$ pil family.l -main -go +
As before, the database is opened with main. The function
go is also defined in @doc/family.l:
(de go ()
(server 8080 "!person") )
It starts the HTTP server listening on TCP port 8080 (we did a similar thing
in our minimal GUI example above directly on the command line). Each connect to
that port will cause the function person to be invoked.
Again, point your browser to the address 'http://localhost:8080'.
You should see a new browser window with an input form created by the
function person. We provided an initial database in "family/[1-4]".
You can navigate through it by clicking on the pencil icons besides the input
fields.
The chart with the children data can be scrolled using the down
(v) and up (^) buttons.
A click on the button "Select" below opens a search dialog. You can scroll through the chart as before. Again, a click on a pencil will jump to that person. You can abort the dialog with a click on the "Cancel"-button.
The search fields in the upper part of the dialog allow a conjunctive search. If you enter "Edward" in the "Name" field and click "Search", you'll see all persons having the string "Edward" in their name. If you also enter "Duke" in the "Occupation" field, the result list will reduce to only two entries.
To create a new person, press the "New Man" or "New Woman" button. A new empty form will be displayed. Please type a name into the first field, and perhaps also an occupation and birth date. Any change of contents should be followed by a press on the "Done" button, though any other button (also Scroll or Select-buttons) will also do.
To assign a father attribute, you can either type a name directly into
the field (if that person already exists in the database and you know the exact
spelling), or use the "Set"-button (->) to the left of that
field to open the search dialog. If you type in the name directly, your input
must exactly match upper and lower case.
Alternatively, you may create a new person and assign a child in the "Children" chart.
On the console where you started PicoLisp, there should a prompt have
appeared just when the browser connected. You can debug the application
interactively while it is running. For example, the global variable
*Top always contains the top level GUI object:
: (show *Top)
To take a look at the first field on the form:
: (show *Top 'gui 1)
A production application would be started in a slightly different way:
$ pil family.l -main -go -wait
In that case, no debug prompt will appear. In both cases, however, two
pil processes will be running now. One is the initial server
process which will continue to run until it is killed. The other is a child
process holding the state of the GUI in the browser. It will terminate some time
after the browser is closed, or when (bye) or a Ctrl-D is entered at the
PicoLisp prompt.
Now back to the explanation of the GUI function person:
(de person ()
(app)
(action
(html 0 (get (default *ID (val *DB)) 'nm) "@lib.css" NIL
(form NIL
(<h2> (<id> (: nm)))
For an in-depth explanation of that startup code, please refer to the guide to PicoLisp Application Development.
All components like fields and buttons are controlled by form.
The function gui creates a single GUI component and takes the type
(a list of classes) and a variable number of arguments depending on the needs of
these classes.
(gui '(+E/R +TextField) '(nm : home obj) 40 "Name")
This creates a +TextField with the label "Name" and a length of
40 characters. The +E/R (: Entity/Relation) prefix class connects
that field to a database object, the nm attribute of a person in
this case, so that the person's name is displayed in that text field, and any
changes entered into that field are propagated to the database automatically.
(gui '(+ClassField) '(: home obj) '(("Male" +Man) ("Female" +Woman)))
A +ClassField displays and changes the class of an object, in
this case the person's sex from +Man to +Woman and
vice versa.
As you see, there is no place where explicit accesses to the database have to
be programmed, no select or update. This is all
encapsulated in the GUI components, mainly in the +E/R prefix
class. The above function person is fully functional as we present
it and allows creation, modification and deletion of person objects in the
database.
The two buttons on the bottom right generate simple reports:
The first one shows all contemporaries of the person that is currently displayed, i.e. all persons who did not die before, or were not born after that person. This is a typical PicoLisp report, in that in addition to the report's HTML page, a temporary file may be generated, suitable for download (and import into a spread sheet), and from which a PDF can be produced for print-out.
In PicoLisp, there is not a real difference between a plain HTML-GUI and a
report. Again, the function html is used to generate the page.
The second report is much simpler. It produces a recursive structure of the family.
In both reports, links to the person objects are created which allow easy navigation through the database.
This sections explains some cases of using Pilog in typical application programming, in combination with persistent objects and databases. Please refer to the Pilog section of the PicoLisp Reference for the basic usage of Pilog.
Again, we use our demo application @doc/family.l that was introduced in the Database Programming section.
Normally, Pilog is used either interactively to query the database during
debugging, or in applications to generate export data and reports. In the
following examples we use the interactive query front-end functions ? and select. An application will use goal and prove directly, or use convenience functions
like pilog or solve.
All Pilog access to external symbols is done via the two predicates db/3 and select/3.
db/3 corresponds to the Lisp-level
functions db and collect, as it derives its data from a
single relation. It can be used for simple database queries.
select/3 provides for
self-optimizing parallel access to an arbitrary number of relations. There is
also a Lisp front-end function select, for convenient calls to the Pilog
select predicate.
A predicate show/1 is pre-defined
for debugging purposes (a simple glue to the Lisp-level function
show, see Browsing). Searching with db/3 for all persons having the string "Edward"
in their name:
: (? (db nm +Person "Edward" @P) (show @P))
{2-;} (+Man)
nm "Edward"
ma {2-:}
pa {2-A}
dat 717346
job "Prince"
@P={2-;}
{2-1B} (+Man)
nm "Albert Edward"
kids ({2-1C} {2-1D} {2-1E} {2-1F} {2-1G} {2-1H} {2-1I} {2-g} {2-a})
job "Prince"
mate {2-f}
fin 680370
dat 664554
@P={2-1B}
... # more results
To search for all persons with "Edward" in their name who are married to somebody with occupation "Queen":
: (? (db nm +Person "Edward" @P) (val "Queen" @P mate job) (show @P))
{2-1B} (+Man)
mate {2-f}
nm "Albert Edward"
kids ({2-1C} {2-1D} {2-1E} {2-1F} {2-1G} {2-1H} {2-1I} {2-g} {2-a})
job "Prince"
fin 680370
dat 664554
@P={2-1B}
-> NIL # only one result
If you are interested in the names of "Albert Edward"'s children:
: (? (db nm +Person "Albert Edward" @P) (lst @K @P kids) (val @Kid @K nm))
@P={2-1B} @K={2-1C} @Kid="Beatrice Mary Victoria"
@P={2-1B} @K={2-1D} @Kid="Leopold George Duncan"
@P={2-1B} @K={2-1E} @Kid="Arthur William Patrick"
@P={2-1B} @K={2-1F} @Kid="Louise Caroline Alberta"
@P={2-1B} @K={2-1G} @Kid="Helena Augusta Victoria"
@P={2-1B} @K={2-1H} @Kid="Alfred Ernest Albert"
@P={2-1B} @K={2-1I} @Kid="Alice Maud Mary"
@P={2-1B} @K={2-g} @Kid="Victoria Adelaide Mary"
@P={2-1B} @K={2-a} @Kid="Edward VII"
-> NIL
db/3 can do a direct index access
only for a single attribute (nm of +Person above). To
search for several criteria at the same time, select/3 has to be used:
: (?
(select (@P)
((nm +Person "Edward") (nm +Person "Augusta" pa)) # Generator clauses
(tolr "Edward" @P nm) # Filter clauses
(tolr "Augusta" @P kids nm) )
(show @P) )
{2-1B} (+Man)
kids ({2-1C} {2-1D} {2-1E} {2-1F} {2-1G} {2-1H} {2-1I} {2-g} {2-a})
mate {2-f}
nm "Albert Edward"
job "Prince"
fin 680370
dat 664554
@P={2-1B}
-> NIL
select/3 takes a list of
generator clauses which are used to retrieve objects from the database, and a
number of normal Pilog filter clauses. In the example above the generators are
(nm +Person "Edward") to generate persons with "Edward" in
their names, and
(nm +Person "Augusta" pa) to find persons with "Augusta"
in their names and generate persons using the pa ("father")
attribute.
All persons generated are possible candidates for our selection. The
nm index tree of +Person is traversed twice in
parallel, optimizing the search in such a way that successful hits get higher
priority in the search, depending on the filter clauses. The process will stop
as soon as any one of the generators is exhausted. Note that this is different
from the standard Prolog search algorithm.
The filter clauses in this example both use the pre-defined predicate
tolr/3 for tolerant string
matches (according either to the soundex algorithm (see the section Database Programming) or to substring matches), and filter
objects that
(tolr "Edward" @P nm), and
(tolr "Augusta" @P
kids nm)
A more typical and extensive example for the usage of select can
be found in the qPerson function in @doc/family.l. It is used in the search dialog of the
demo application, and searches for a person with the name, the parents' and
partner's names, the occupation and a time range for the birth date. The
relevant index trees in the database are searched (actually only those trees
where the user entered a search key in the corresponding dialog field), and a
logical AND of the search attributes is applied to the result.
For example, press the "Select" button, enter "Elizabeth" into the "Mother" search field and "Phil" in the "Partner" search field, meaning to look for all persons whose mother's name is like "Elizabeth" and whose partner's name is like "Phil". As a result, two persons ("Elizabeth II" and "Anne") will show up.
In principle, db/3 can be seen as a
special case of select/3. The
following two queries are equivalent:
: (? (db nm +Person "Edward" @P))
@P={2-;}
@P={2-1B}
@P={2-R}
@P={2-1K}
@P={2-a}
@P={2-T}
-> NIL
: (? (select (@P) ((nm +Person "Edward"))))
@P={2-;}
@P={2-1B}
@P={2-R}
@P={2-1K}
@P={2-a}
@P={2-T}
-> NIL
For convenience, a select Lisp
glue function is provided as a front-end to the select predicate.
Note that this function does not evaluate its arguments (it is intended for
interactive use), and that it supports only a subset of the predicate's
functionality. The syntax resembles SELECT in the SQL language, for example:
# SELECT * FROM Person
: (select +Person) # Step through the whole database
{2-o} (+Man)
nm "Adalbert Ferdinand Berengar Viktor of Prussia"
dat 688253
ma {2-j}
pa {2-h}
fin 711698
{2-1B} (+Man)
nm "Albert Edward"
dat 664554
job "Prince"
mate {2-f}
kids ({2-1C} {2-1D} {2-1E} {2-1F} {2-1G} {2-1H} {2-1I} {2-g} {2-a})
fin 680370
...
# SELECT * FROM Person WHERE nm LIKE "%Edward%"
: (select +Person nm "Edward") # Show all Edwards
{2-;} (+Man)
nm "Edward"
dat 717346
job "Prince"
ma {2-:}
pa {2-A}
{2-1B} (+Man)
nm "Albert Edward"
dat 664554
job "Prince"
kids ({2-1C} {2-1D} {2-1E} {2-1F} {2-1G} {2-1H} {2-1I} {2-g} {2-a})
mate {2-f}
fin 680370
...
# SELECT nm, dat FROM Person WHERE nm LIKE "%Edward%"
: (select nm dat +Person nm "Edward")
"Edward" "1964-03-10" {2-;}
"Albert Edward" "1819-08-26" {2-1B}
"George Edward" NIL {2-R}
"Edward Augustus Hanover" NIL {2-1K}
...
# SELECT dat, fin, p1.nm, p2.nm
# FROM Person p1, Person p2
# WHERE p1.nm LIKE "%Edward%"
# AND p1.job LIKE "King%"
# AND p1.mate = p2.mate -- Actually, in a SQL model we'd need
# -- another table here for the join
: (select dat fin nm (mate nm) +Person nm "Edward" job "King")
"1894-06-23" "1972-05-28" "Edward VIII" "Wallace Simpson" {2-T}
"1841-11-09" NIL "Edward VII" "Alexandra of Denmark" {2-a}
-> NIL
In addition (just to stay with the SQL terminology ;-), there is also an
update function. It is a front-end
to the set!> and put!> transaction methods, and
should be used when single objects in the database have to be modified by hand.
In principle, it would also be possible to use the edit function to modify a database object. This
is not recommended, however, because edit does not know about
relations to other objects (like Links, Joints and index trees) and may easily
cause database corruption.
In the most general case, the value of a property in a database object is
changed with the put!> method. Let's look at "Edward" from the
previous examples:
: (show '{2-;})
{2R} (+Man)
job "Prince"
nm "Edward"
dat 717346
ma {2-:}
pa {20A}
-> {2-;}
We might change the name to "Johnny" with put!>:
: (put!> '{2-;} 'nm "Johnny")
-> "Johnny"
However, an easier and less error-prone prone way - especially when more than
one property has to be changed - is using update. It presents the value (the list of
classes) and then each property on its own line, allowing the user to change it
with the command line editor.
Just hitting ENTER will leave that property unchanged. To modify it, you'll typically hit ESC to get into command mode, and move the cursor to the point of change.
For properties with nested list structures (+List +Bag),
update will recurse into the data structure.
: (update '{2-;})
{2-;} (+Man) # ENTER
nm "Johnny" # Modified the name to "Johnny"
ma {2-:} # ENTER
pa {2-A} # ENTER
dat 1960-03-10 # Modified the year from "1964" to "1960"
job "Prince" # ENTER
-> {2-;}
All changes are committed immediately, observing the rules of database synchronization so that any another user looking at the same object will have his GUI updated correctly.
To abort update, hit Ctrl-X.
If only a single property has to be changed, update can be
called directly for that property:
: (update '{2-;} 'nm)
{2-;} nm "Edward"
...
[knuth73] Donald E. Knuth: ``The Art of Computer Programming'', Vol.3, Addison-Wesley, 1973, p. 392 picolisp-3.1.5.2.orig/doc/utf8 0000644 0000000 0000000 00000001371 12265263724 014530 0 ustar root root UTF-8 Format # Encoding for zero is different from Java # Special character 0xFF (char T) 0000 .. 007F 0xxxxxxx 6 0 0080 .. 07FF 110xxxxx 10xxxxxx A 6 5 0 0800 .. FFFF 1110xxxx 10xxxxxx 10xxxxxx F C B 6 5 0 Umlaute äöüÄÖÜß |Ä| # C3 84 <-> C4 |Ö| # C3 96 <-> D6 |Ü| # C3 9C <-> DC |ä| # C3 A4 <-> E4 |ö| # C3 B6 <-> F6 |ü| # C3 BC <-> FC |ß| # C3 9F <-> DF Paragraph # C2 A7 <-> A7 EUR (8364 "20AC") # E2 82 AC <-> A4 tr -d '\303' |tr '\204\226\234\244\266\274\237' '' (out "Nagoya" (prinl (char (hex "540D")) (char (hex "53E4")) (char (hex "5C4B"))) ) picolisp-3.1.5.2.orig/doc/vim-tsm 0000644 0000000 0000000 00000001447 12265263724 015242 0 ustar root root 26apr10abu (c) Software Lab. Alexander Burger Transient Symbol Markup for 'vim' ================================= 1. Compile 'vim' with Vince Negri's "Conceal" patch: http://vim.wikia.com/wiki/Patch_to_conceal_parts_of_lines patch -p0 < conceal-ownsyntax.diff make distclean ./configure --with-features=huge make VIMRUNTIMEDIR=~/local/vim72/runtime MAKE="make -e" cd ~/bin ln -s ~/local/vim72/src/vim ln vim vi ln vim view 2. Then put into your ".vimrc" or vim syntax file: if has("conceal") set conceallevel=2 syn region picoLispTransient concealends matchgroup=picoLispString start=/"/ skip=/\\\\\|\\"/ end=/"/ hi picoLispTransient gui=underline term=underline cterm=underline hi picoLispString ctermfg=red guifg=red endif picolisp-3.1.5.2.orig/doc/app.html 0000644 0000000 0000000 00000275340 12265263724 015376 0 ustar root root
(c) Software Lab. Alexander Burger
This document presents an introduction to writing browser-based applications in PicoLisp.
It concentrates on the XHTML/CSS GUI-Framework (as opposed to the previous Java-AWT, Java-Swing and Plain-HTML frameworks), which is easier to use, more flexible in layout design, and does not depend on plug-ins, JavaScript, cookies or CSS.
A plain HTTP/HTML GUI has various advantages: It runs on any browser, and can be fully driven by scripts ("@lib/scrape.l").
To be precise: CSS can be used to enhance the layout. And browsers with JavaScript will respond faster and smoother. But this framework works just fine in browsers which do not know anything about CSS or JavaScript. All examples were also tested using the w3m text browser.
For basic informations about the PicoLisp system please look at the PicoLisp Reference and the PicoLisp Tutorial. Knowledge of HTML, and a bit of CSS and HTTP is assumed.
The examples assume that PicoLisp was started from a global installation (see Installation).
You can use PicoLisp to generate static HTML pages. This does not make much sense in itself, because you could directly write HTML code as well, but it forms the base for interactive applications, and allows us to introduce the application server and other fundamental concepts.
To begin with a minimal application, please enter the following two lines into a generic source file named "project.l" in the PicoLisp installation directory.
########################################################################
(html 0 "Hello" "@lib.css" NIL
"Hello World!" )
########################################################################
(We will modify and use this file in all following examples and experiments. Whenever you find such a program snippet between hash ('#') lines, just copy and paste it into your "project.l" file, and press the "reload" button of your browser to view the effects)
Open a second terminal window, and start a PicoLisp application server
$ pil @lib/http.l @lib/xhtml.l @lib/form.l --server 8080 project.l +
No prompt appears. The server just sits, and waits for connections. You can
stop it later by hitting Ctrl-C in that terminal, or by executing
'killall pil' in some other window.
(In the following, we assume that this HTTP server is up and running)
Now open the URL 'http://localhost:8080' with your
browser. You should see an empty page with a single line of text.
The above line loads the debugger (via the '+' switch), the HTTP server code ("@lib/http.l"), the XHTML functions ("@lib/xhtml.l") and the input form framework ("@lib/form.l", it will be needed later for interactive forms).
Then the server function is called with a port number and a
default URL. It will listen on that port for incoming HTTP requests in an
endless loop. Whenever a GET request arrives on port 8080, the file "project.l"
will be (load)ed, causing the
evaluation (= execution) of all its Lisp expressions.
During that execution, all data written to the current output channel is sent directly to to the browser. The code in "project.l" is responsible to produce HTML (or anything else the browser can understand).
The PicoLisp application server uses a slightly specialized syntax when communicating URLs to and from a client. The "path" part of an URL - which remains when
(load)ed. This
is the most common case, and we use it in our example "project.l".
*Mimes, the file is sent to the client with mime-type and
max-age values taken from that table.
An application is free to extend or modify the *Mimes table with
the mime function. For example
(mime "doc" "application/msword" 60)
defines a new mime type with a max-age of one minute.
Argument values in URLs, following the path and the question mark, are encoded in such a way that Lisp data types are preserved:
In that way, high-level data types can be directly passed to functions encoded in the URL, or assigned to global variables before a file is loaded.
It is, of course, a huge security hole that - directly from the URL - any
Lisp source file can be loaded, and any Lisp function can be called. For that
reason, applications must take care to declare exactly which files and functions
are to be allowed in URLs. The server checks a global variable *Allow, and - when its value is
non-NIL - denies access to anything that does not match its
contents.
Normally, *Allow is not manipulated directly, but set with the
allowed and allow functions
(allowed ("app/")
"!start" "!stop" "@lib.css" "!psh" )
This is usually called at the beginning of an application, and allows access to the directory "app/", to the functions 'start', 'stop' and 'psh', and to the file "@lib.css".
Later in the program, *Allow may be dynamically extended with
allow
(allow "!foo")
(allow "newdir/" T)
This adds the function 'foo', and the directory "newdir/", to the set of allowed items.
For a variety of security checks (most notably for using the psh
function, as in some later examples) it is necessary to create a file named
".pw" in the PicoLisp installation directory. This file should contain a single
line of arbitrary data, to be used as a password for identifying local
resources.
The recommeded way to create this file is to call the pw
function, defined in "@lib/http.l"
$ pil @lib/http.l -'pw 12' -bye
Please execute this command.
html FunctionNow back to our "Hello World" example. In principle, you could write "project.l" as a sequence of print statements
########################################################################
(prinl "HTTP/1.0 200 OK^M")
(prinl "Content-Type: text/html; charset=utf-8")
(prinl "^M")
(prinl "<html>")
(prinl "Hello World!")
(prinl "</html>")
########################################################################
but using the html function is much more convenient.
Moreover, html is nothing more than a printing function.
You can see this easily if you connect a PicoLisp Shell (psh) to
the server process (you must have generated a ".pw" file for
this), and enter the html statement
$ /usr/lib/picolisp/bin/psh 8080
: (html 0 "Hello" "@lib.css" NIL "Hello World!")
HTTP/1.0 200 OK
Server: PicoLisp
Date: Fri, 29 Dec 2006 07:28:58 GMT
Cache-Control: max-age=0
Cache-Control: no-cache
Content-Type: text/html; charset=utf-8
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Hello</title>
<base href="http://localhost:8080/"/>
<link rel="stylesheet" type="text/css" href="http://localhost:8080/@lib.css"/>
</head>
<body>Hello World!</body>
</html>
-> </html>
: # (type Ctrl-D here to terminate PicoLisp)
These are the arguments to html:
0: A max-age value for cache-control (in seconds, zero means
"no-cache"). You might pass a higher value for pages that change seldom, or
NIL for no cache-control at all.
"Hello": The page title.
"@lib.css": A CSS-File name. Pass NIL if you do
not want to use any CSS-File, or a list of file names if you want to give more
than one CSS-File.
NIL: A CSS style attribute specification (see the description
of CSS Attributes below). It will be passed to the
body tag.
After these four arguments, an arbitrary number of expressions may follow. They form the body of the resulting page, and are evaluated according to a special rule. This rule is slightly different from the evaluation of normal Lisp expressions:
Therefore, our source file might as well be written as:
########################################################################
(html 0 "Hello" "@lib.css" NIL
(prinl "Hello World!") )
########################################################################
The most typical print statements will be some HTML-tags:
########################################################################
(html 0 "Hello" "@lib.css" NIL
(<h1> NIL "Hello World!")
(<br> "This is some text.")
(ht:Prin "And this is a number: " (+ 1 2 3)) )
########################################################################
<h1> and <br> are tag functions.
<h1> takes a CSS attribute as its first argument.
Note the use of ht:Prin instead of prin.
ht:Prin should be used for all direct printing in HTML pages,
because it takes care to escape special characters.
The html function above, and many of the
HTML tag functions, accept a CSS attribute specification.
This may be either an atom, a cons pair, or a list of cons pairs. We demonstrate
the effects with the <h1> tag function.
An atom (usually a symbol or a string) is taken as a CSS class name
: (<h1> 'foo "Title")
<h1 class="foo">Title</h1>
For a cons pair, the CAR is taken as an attribute name, and the CDR as the attribute's value
: (<h1> '(id . bar) "Title")
<h1 id="bar">Title</h1>
Consequently, a list of cons pairs gives a set of attribute-value pairs
: (<h1> '((id . "abc") (lang . "de")) "Title")
<h1 id="abc" lang="de">Title</h1>
All pre-defined XHTML tag functions can be found in "@lib/xhtml.l". We recommend to look at their sources, and to experiment a bit, by executing them at a PicoLisp prompt, or by pressing the browser's "Reload" button after editing the "project.l" file.
For a suitable PicoLisp prompt, either execute (in a separate terminal
window) the PicoLisp Shell (psh) command (works only if the
application server is running, and you did generate a ".pw"
file)
$ /usr/lib/picolisp/bin/psh 8080
:
or start the interpreter stand-alone, with "@lib/xhtml.l" loaded
$ pil @lib/http.l @lib/xhtml.l +
:
Note that for all these tag functions the above tag body evaluation rule applies.
Most tag functions are simple and straightforward. Some of them just print their arguments
: (<br> "Hello world")
Hello world<br/>
: (<em> "Hello world")
<em>Hello world</em>
while most of them take a CSS attribute specification
as their first argument (like the <h1> tag above)
: (<div> 'main "Hello world")
<div class="main">Hello world</div>
: (<p> NIL "Hello world")
<p>Hello world</p>
: (<p> 'info "Hello world")
<p class="info">Hello world</p>
All of these functions take an arbitrary number of arguments, and may nest to an arbitrary depth (as long as the resulting HTML is legal)
: (<div> 'main
(<h1> NIL "Head")
(<p> NIL
(<br> "Line 1")
"Line"
(<nbsp>)
(+ 1 1) ) )
<div class="main"><h1>Head</h1>
<p>Line 1<br/>
Line 2</p>
</div>
HTML-lists, implemented by the <ol> and
<ul> tags, let you define hierarchical structures. You might
want to paste the following code into your copy of "project.l":
########################################################################
(html 0 "Unordered List" "@lib.css" NIL
(<ul> NIL
(<li> NIL "Item 1")
(<li> NIL
"Sublist 1"
(<ul> NIL
(<li> NIL "Item 1-1")
(<li> NIL "Item 1-2") ) )
(<li> NIL "Item 2")
(<li> NIL
"Sublist 2"
(<ul> NIL
(<li> NIL "Item 2-1")
(<li> NIL "Item 2-2") ) )
(<li> NIL "Item 3") ) )
########################################################################
Here, too, you can put arbitrary code into each node of that tree, including other tag functions.
Like the hierarchical structures with the list functions, you can generate
two-dimensional tables with the <table> and
<row> functions.
The following example prints a table of numbers and their squares:
########################################################################
(html 0 "Table" "@lib.css" NIL
(<table> NIL NIL NIL
(for N 10 # A table with 10 rows
(<row> NIL N (prin (* N N))) ) ) ) # and 2 columns
########################################################################
The first argument to <table> is the usual CSS attribute,
the second an optional title ("caption"), and the third an optional list
specifying the column headers. In that list, you may supply a list for a each
column, with a CSS attribute in its CAR, and a tag body in its CDR for the
contents of the column header.
The body of <table> contains calls to the
<row> function. This function is special in that each
expression in its body will go to a separate column of the table. If both for
the column header and the row function an CSS attribute is given, they will be
combined by a space and passed to the HTML <td> tag. This
permits distinct CSS specifications for each column and row.
As an extension of the above table example, let's pass some attributes for
the table itself (not recommended - better define such styles in a CSS file and
then just pass the class name to <table>), right-align both
columns, and print each row in an alternating red and blue color
########################################################################
(html 0 "Table" "@lib.css" NIL
(<table>
'((width . "200px") (style . "border: dotted 1px;")) # table style
"Square Numbers" # caption
'((align "Number") (align "Square")) # 2 headers
(for N 10 # 10 rows
(<row> (xchg '(red) '(blue)) # red or blue
N # 2 columns
(prin (* N N) ) ) ) ) )
########################################################################
If you wish to concatenate two or more cells in a table, so that a single
cell spans several columns, you can pass the symbol '-' for the
additional cell data to <row>. This will cause the data given
to the left of the '-' symbols to expand to the right.
You can also directly specify table structures with the simple
<th>, <tr> and <td> tag
functions.
If you just need a two-dimensional arrangement of components, the even
simpler <grid> function might be convenient:
########################################################################
(html 0 "Grid" "@lib.css" NIL
(<grid> 3
"A" "B" "C"
123 456 789 ) )
########################################################################
It just takes a specification for the number of columns (here: 3) as its first argument, and then a single expression for each cell. Instead of a number, you can also pass a list of CSS attributes. Then the length of that list will determine the number of columns. You can change the second line in the above example to
(<grid> '(NIL NIL right)
Then the third column will be right aligned.
The two most powerful tag functions are <menu> and
<tab>. Used separately or in combination, they form a
navigation framework with
The following example is not very useful, because the URLs of all items link to the same "project.l" page, but it should suffice to demonstrate the functionality:
########################################################################
(html 0 "Menu+Tab" "@lib.css" NIL
(<div> '(id . menu)
(<menu>
("Item" "project.l") # Top level item
(NIL (<hr>)) # Plain HTML
(T "Submenu 1" # Submenu
("Subitem 1.1" "project.l")
(T "Submenu 1.2"
("Subitem 1.2.1" "project.l")
("Subitem 1.2.2" "project.l")
("Subitem 1.2.3" "project.l") )
("Subitem 1.3" "project.l") )
(T "Submenu 2"
("Subitem 2.1" "project.l")
("Subitem 2.2" "project.l") ) ) )
(<div> '(id . main)
(<h1> NIL "Menu+Tab")
(<tab>
("Tab1"
(<h3> NIL "This is Tab 1") )
("Tab2"
(<h3> NIL "This is Tab 2") )
("Tab3"
(<h3> NIL "This is Tab 3") ) ) ) )
########################################################################
<menu> takes a sequence of menu items. Each menu item is a
list, with its CAR either
NIL: The entry is not an active menu item, and the rest of the
list may consist of arbitrary code (usually HTML tags).
T: The second element is taken as a submenu name, and a click
on that name will open or close the corresponding submenu. The rest of the list
recursively specifies the submenu items (may nest to arbitrary depth).
<tab> takes a list of subpages. Each page is simply a tab
name, followed by arbitrary code (typically HTML tags).
Note that only a single menu and a single tab may be active at the same time.
In HTML, the only possibility for user input is via <form>
and <input> elements, using the HTTP POST method to
communicate with the server.
"@lib/xhtml.l" defines a function called <post>, and a
collection of input tag functions, which allow direct programming of HTML forms.
We will supply only one simple example:
########################################################################
(html 0 "Simple Form" "@lib.css" NIL
(<post> NIL "project.l"
(<field> 10 '*Text)
(<submit> "Save") ) )
########################################################################
This associates a text input field with a global variable *Text.
The field displays the current value of *Text, and pressing the
submit button causes a reload of "project.l" with *Text set to any
string entered by the user.
An application program could then use that variable to do something useful, for example store its value in a database.
The problem with such a straightforward use of forms is that
<hidden> tags.
Though we wrote a few applications in that style, we recommend the GUI framework provided by "@lib/form.l". It does not need any variables for the client/server communication, but implements a class hierarchy of GUI components for the abstraction of application logic, button actions and data linkage.
First of all, we need to establish a persistent environment on the server, to handle each individual session (for each connected client).
Technically, this is just a child process of the server we started above, which does not terminate immediately after it sent its
page to the browser. It is achieved by calling the app function
somewhere in the application's startup code.
########################################################################
(app) # Start a session
(html 0 "Simple Session" "@lib.css" NIL
(<post> NIL "project.l"
(<field> 10 '*Text)
(<submit> "Save") ) )
########################################################################
Nothing else changed from the previous example. However, when you connect your browser and then look at the terminal window where you started the application server, you'll notice a colon, the PicoLisp prompt
$ pil @lib/http.l @lib/xhtml.l @lib/form.l --server 8080 project.l +
:
Tools like the Unix ps utility will tell you that now two
picolisp processes are running, the first being the parent of the
second.
If you enter some text, say "abcdef", into the text field in the browser
window, press the submit button, and inspect the Lisp *Text
variable,
: *Text
-> "abcdef"
you see that we now have a dedicated PicoLisp process, "connected" to the client.
You can terminate this process (like any interactive PicoLisp) by hitting
Ctrl-D on an empty line. Otherwise, it will terminate by itself if
no other browser requests arrive within a default timeout period of 5 minutes.
To start a (non-debug) production version, the server is commonly started
without the '+' flag, and with -wait
$ pil @lib/http.l @lib/xhtml.l @lib/form.l --server 8080 project.l -wait
In that way, no command line prompt appears when a client connects.
Now that we have a persistent session for each client, we can set up an active GUI framework.
This is done by wrapping the call to the html function with
action. Inside the body of html can be - in addition
to all other kinds of tag functions - one or more calls to form
########################################################################
(app) # Start session
(action # Action handler
(html 0 "Form" "@lib.css" NIL # HTTP/HTML protocol
(form NIL # Form
(gui 'a '(+TextField) 10) # Text Field
(gui '(+Button) "Print" # Button
'(msg (val> (: home a))) ) ) ) )
########################################################################
Note that there is no longer a global variable like *Text to
hold the contents of the input field. Instead, we gave a local, symbolic name
'a' to a +TextField component
(gui 'a '(+TextField) 10) # Text Field
Other components can refer to it
'(msg (val> (: home a)))
(: home) is always the form which contains this GUI component.
So (: home a) evaluates to the component 'a' in the
current form. As msg prints its
argument to standard error, and the val> method retrieves the
current contents of a component, we will see on the console the text typed into
the text field when we press the button.
An action without embedded forms - or a
form without a surrounding action - does not make much
sense by itself. Inside html and form, however, calls
to HTML functions (and any other Lisp functions, for that matter) can be freely
mixed.
In general, a typical page may have the form
(action # Action handler
(html .. # HTTP/HTML protocol
(<h1> ..) # HTML tags
(form NIL # Form
(<h3> ..)
(gui ..) # GUI component(s)
(gui ..)
.. )
(<h2> ..)
(form NIL # Another form
(<h3> ..)
(gui ..) # GUI component(s)
.. )
(<br> ..)
.. ) )
gui FunctionThe most prominent function in a form body is gui.
It is the workhorse of GUI construction.
Outside of a form body, gui is undefined.
Otherwise, it takes an optional alias name, a list of classes, and additional
arguments as needed by the constructors of these classes. We saw this example
before
(gui 'a '(+TextField) 10) # Text Field
a' is an alias name for a component of type
(+TextField). The numeric argument 10 is passed to the
text field, specifying its width. See the chapter on GUI
Classes for more examples.
During a GET request, gui is basically a front-end to
new. It builds a component, stores it in the internal structures of
the current form, and initializes it by sending the init>
message to the component. Finally, it sends it the show>
message, to produce HTML code and transmit it to the browser.
During a POST request, gui does not build any new components.
Instead, the existing components are re-used. So gui does not have
much more to do than sending the show> message to a component.
HTTP has only two methods to change a browser window: GET and POST. We employ these two methods in a certain defined, specialized way:
A button's action code can do almost anything: Read and modify the contents of input fields, communicate with the database, display alerts and dialogs, or even fake the POST request to a GET, with the effect of showing a completely different document (See Switching URLs).
GET builds up all GUI components on the server. These components are objects
which encapsulate state and behavior of the HTML page in the browser. Whenever a
button is pressed, the page is reloaded via a POST request. Then - before any
output is sent to the browser - the action function takes control.
It performs error checks on all components, processes possible user input on the
HTML page, and stores the values in correct format (text, number, date, object
etc.) in each component.
The state of a form is preserved over time. When the user returns to a previous page with the browser's BACK button, that state is reactivated, and may be POSTed again.
The following silly example displays two text fields. If you enter some text into the "Source" field, you can copy it in upper or lower case to the "Destination" field by pressing one of the buttons
########################################################################
(app)
(action
(html 0 "Case Conversion" "@lib.css" NIL
(form NIL
(<grid> 2
"Source" (gui 'src '(+TextField) 30)
"Destination" (gui 'dst '(+Lock +TextField) 30) )
(gui '(+JS +Button) "Upper Case"
'(set> (: home dst)
(uppc (val> (: home src))) ) )
(gui '(+JS +Button) "Lower Case"
'(set> (: home dst)
(lowc (val> (: home src))) ) ) ) ) )
########################################################################
The +Lock prefix class in the "Destination" field makes that
field read-only. The only way to get some text into that field is by using one
of the buttons.
Because an action code runs before html has a chance to output
an HTTP header, it can abort the current page and present something different to
the user. This might, of course, be another HTML page, but would not be very
interesting as a normal link would suffice. Instead, it can cause the download
of dynamically generated data.
The next example shows a text area and two buttons. Any text entered into the text area is exported either as a text file via the first button, or a PDF document via the second button
########################################################################
(load "@lib/ps.l")
(app)
(action
(html 0 "Export" "@lib.css" NIL
(form NIL
(gui '(+TextField) 30 8)
(gui '(+Button) "Text"
'(let Txt (tmp "export.txt")
(out Txt (prinl (val> (: home gui 1))))
(url Txt) ) )
(gui '(+Button) "PDF"
'(psOut NIL "foo"
(a4)
(indent 40 40)
(down 60)
(hline 3)
(font (14 . "Times-Roman")
(ps (val> (: home gui 1))) )
(hline 3)
(page) ) ) ) ) )
########################################################################
(a text area is built when you supply two numeric arguments (columns and
rows) to a +TextField class)
The action code of the first button creates a temporary file (i.e. a file
named "export.txt" in the current process's temporary space), prints the value
of the text area (this time we did not bother to give it a name, we simply refer
to it as the form's first gui list element) into that file, and then calls the
url function with the file name.
The second button uses the PostScript library "@lib/ps.l" to create a
temporary file "foo.pdf". Here, the temporary file creation and the call to the
url function is hidden in the internal mechanisms of
psOut. The effect is that the browser receives a PDF document and
displays it.
Alerts and dialogs are not really what they used to be ;-)
They do not "pop up". In this framework, they are just a kind of simple-to-use, pre-fabricated form. They can be invoked by a button's action code, and appear always on the current page, immediately preceding the form which created them.
Let's look at an example which uses two alerts and a dialog. In the beginning, it displays a simple form, with a locked text field, and two buttons
########################################################################
(app)
(action
(html 0 "Alerts and Dialogs" "@lib.css" NIL
(form NIL
(gui '(+Init +Lock +TextField) "Initial Text" 20 "My Text")
(gui '(+Button) "Alert"
'(alert NIL "This is an alert " (okButton)) )
(gui '(+Button) "Dialog"
'(dialog NIL
(<br> "This is a dialog.")
(<br>
"You can change the text here "
(gui '(+Init +TextField) (val> (: top 1 gui 1)) 20) )
(<br> "and then re-submit it to the form.")
(gui '(+Button) "Re-Submit"
'(alert NIL "Are you sure? "
(yesButton
'(set> (: home top 2 gui 1)
(val> (: home top 1 gui 1)) ) )
(noButton) ) )
(cancelButton) ) ) ) ) )
########################################################################
The +Init prefix class initializes the "My Text" field with the
string "Initial Text". As the field is locked, you cannot modify this value
directly.
The first button brings up an alert saying "This is an alert.". You can dispose it by pressing "OK".
The second button brings up a dialog with an editable text field, containing a copy of the value from the form's locked text field. You can modify this value, and send it back to the form, if you press "Re-Submit" and answer "Yes" to the "Are you sure?" alert.
Now let's forget our "project.l" test file for a moment, and move on to a more substantial and practical, stand-alone, example. Using what we have learned so far, we want to build a simple bignum calculator. ("bignum" because PicoLisp can do only bignums)
It uses a single form, a single numeric input field, and lots of buttons. It can be found in the PicoLisp distribution (e.g. under "/usr/share/picolisp/") in "misc/calc.l", together with a directly executable wrapper script "misc/calc".
To use it, change to the PicoLisp installation directory, and start it as
$ misc/calc
or call it with an absolute path, e.g.
$ /usr/share/picolisp/misc/calc
If you like to get a PicoLisp prompt for inspection, start it instead as
$ pil misc/calc.l -main -go +
Then - as before - point your browser to 'http://localhost:8080'.
The code for the calculator logic and the GUI is rather straightforward. The
entry point is the single function calculator. It is called
directly (as described in URL Syntax) as the server's
default URL, and implicitly in all POST requests. No further file access is
needed once the calculator is running.
Note that for a production application, we inserted an allow-statement (as recommended by the Security chapter)
(allowed NIL "!calculator" "@lib.css")
at the beginning of "misc/calc.l". This will restrict external access to that single function.
The calculator uses three global variables, *Init,
*Accu and *Stack. *Init is a boolean flag
set by the operator buttons to indicate that the next digit should initialize
the accumulator to zero. *Accu is the accumulator. It is always
displayed in the numeric input field, accepts user input, and it holds the
results of calculations. *Stack is a push-down stack, holding
postponed calculations (operators, priorities and intermediate results) with
lower-priority operators, while calculations with higher-priority operators are
performed.
The function digit is called by the digit buttons, and adds
another digit to the accumulator.
The function calc does an actual calculation step. It pops the
stack, checks for division by zero, and displays an error alert if necessary.
operand processes an operand button, accepting a function and a
priority as arguments. It compares the priority with that in the top-of-stack
element, and delays the calculation if it is less.
finish is used to calculate the final result.
The calculator function has one numeric input field, with a
width of 60 characters
(gui '(+Var +NumField) '*Accu 60)
The +Var prefix class associates this field with the global
variable *Accu. All changes to the field will show up in that
variable, and modification of that variable's value will appear in the field.
The square root operator button has an
+Able prefix class
(gui '(+Able +JS +Button) '(ge0 *Accu) (char 8730)
'(setq *Accu (sqrt *Accu)) )
with an argument expression which checks that the current value in the accumulator is positive, and disables the button if otherwise.
The rest of the form is just an array (grid) of buttons, encapsulating all
functionality of the calculator. The user can enter numbers into the input
field, either by using the digit buttons, or by directly typing them in, and
perform calculations with the operator buttons. Supported operations are
addition, subtraction, multiplication, division, sign inversion, square root and
power (all in bignum integer arithmetic). The 'C' button just
clears the accumulator, while the 'A' button also clears all
pending calculations.
All that in 53 lines of code!
Charts are virtual components, maintaining the internal representation of two-dimensional data.
Typically, these data are nested lists, database selections, or some kind of dynamically generated tabular information. Charts make it possible to view them in rows and columns (usually in HTML tables), scroll up and down, and associate them with their corresponding visible GUI components.
In fact, the logic to handle charts makes up a substantial part of the whole framework, with large impact on all internal mechanisms. Each GUI component must know whether it is part of a chart or not, to be able to handle its contents properly during updates and user interactions.
Let's assume we want to collect textual and numerical data. We might create a table
########################################################################
(app)
(action
(html 0 "Table" "@lib.css" NIL
(form NIL
(<table> NIL NIL '((NIL "Text") (NIL "Number"))
(do 4
(<row> NIL
(gui '(+TextField) 20)
(gui '(+NumField) 10) ) ) )
(<submit> "Save") ) ) )
########################################################################
with two columns "Text" and "Number", and four rows, each containing a
+TextField and a +NumField.
You can enter text into the first column, and numbers into the second. Pressing the "Save" button stores these values in the components on the server (or produces an error message if a string in the second column is not a legal number).
There are two problems with this solution:
: (val> (get *Top 'gui 2)) # Value in the first row, second column
-> 123
A chart can handle these things:
########################################################################
(app)
(action
(html 0 "Chart" "@lib.css" NIL
(form NIL
(gui '(+Chart) 2) # Inserted a +Chart
(<table> NIL NIL '((NIL "Text") (NIL "Number"))
(do 4
(<row> NIL
(gui 1 '(+TextField) 20) # Inserted '1'
(gui 2 '(+NumField) 10) ) ) ) # Inserted '2'
(<submit> "Save") ) ) )
########################################################################
Note that we inserted a +Chart component before the GUI
components which should be managed by the chart. The argument '2' tells the
chart that it has to expect two columns.
Each component got an index number (here '1' and '2') as the first argument
to gui, indicating the column into which this component should go
within the chart.
Now - if you entered "a", "b" and "c" into the first, and 1, 2, and 3 into
the second column - we can retrieve the chart's complete contents by sending it
the val> message
: (val> (get *Top 'chart 1)) # Retrieve the value of the first chart
-> (("a" 1) ("b" 2) ("c" 3))
BTW, a more convenient function is chart
: (val> (chart)) # Retrieve the value of the current chart
-> (("a" 1) ("b" 2) ("c" 3))
chart can be used instead of the above construct when we want to
access the "current" chart, i.e. the chart most recently processed in the
current form.
To enable scrolling, let's also insert two buttons. We use the pre-defined
classes +UpButton and +DnButton
########################################################################
(app)
(action
(html 0 "Scrollable Chart" "@lib.css" NIL
(form NIL
(gui '(+Chart) 2)
(<table> NIL NIL '((NIL "Text") (NIL "Number"))
(do 4
(<row> NIL
(gui 1 '(+TextField) 20)
(gui 2 '(+NumField) 10) ) ) )
(gui '(+UpButton) 1) # Inserted two buttons
(gui '(+DnButton) 1)
(----)
(<submit> "Save") ) ) )
########################################################################
to scroll down and up a single (argument '1') line at a time.
Now it is possible to enter a few rows of data, scroll down, and continue. It is not necessary (except in the beginning, when the scroll buttons are still disabled) to press the "Save" button, because any button in the form will send changes to the server's internal structures before any action is performed.
As we said, a chart is a virtual component to edit two-dimensional data. Therefore, a chart's native data format is a list of lists: Each sublist represents a single row of data, and each element of a row corresponds to a single GUI component.
In the example above, we saw a row like
("a" 1)
being mapped to
(gui 1 '(+TextField) 20)
(gui 2 '(+NumField) 10)
Quite often, however, such a one-to-one relationship is not desired. The internal data structures may have to be presented in a different form to the user, and user input may need conversion to an internal representation.
For that, a chart accepts - in addition to the "number of columns" argument - two optional function arguments. The first function is invoked to 'put' the internal representation into the GUI components, and the second to 'get' data from the GUI into the internal representation.
A typical example is a chart displaying customers in a database. While the internal representation is a (one-dimensional) list of customer objects, 'put' expands each object to a list with, say, the customer's first and second name, telephone number, address and so on. When the user enters a customer's name, 'get' locates the matching object in the database and stores it in the internal representation. In the following, 'put' will in turn expand it to the GUI.
For now, let's stick with a simpler example: A chart that holds just a list of numbers, but expands in the GUI to show also a textual form of each number (in German).
########################################################################
(app)
(load "@lib/zahlwort.l")
(action
(html 0 "Numerals" "@lib.css" NIL
(form NIL
(gui '(+Init +Chart) (1 5 7) 2
'((N) (list N (zahlwort N)))
car )
(<table> NIL NIL '((NIL "Numeral") (NIL "German"))
(do 4
(<row> NIL
(gui 1 '(+NumField) 9)
(gui 2 '(+Lock +TextField) 90) ) ) )
(gui '(+UpButton) 1)
(gui '(+DnButton) 1)
(----)
(<submit> "Save") ) ) )
########################################################################
"@lib/zahlwort.l" defines the utility function zahlwort, which
is required later by the 'put' function. zahlwort accepts a number
and returns its wording in German.
Now look at the code
(gui '(+Init +Chart) (1 5 7) 2
'((N) (list N (zahlwort N)))
car )
We prefix the +Chart class with +Init, and pass it
a list of numbers (1 5 7) for the initial value of the chart. Then,
following the '2' (the chart has two columns), we pass a 'put' function
'((N) (list N (zahlwort N)))
which takes a number and returns a list of that number and its wording, and a 'get' function
car )
which in turn accepts such a list and returns a number, which happens to be the list's first element.
You can see from this example that 'get' is the inverse function of 'put'. 'get' can be omitted, however, if the chart is read-only (contains no (or only locked) input fields).
The field in the second column
(gui 2 '(+Lock +TextField) 90) ) ) )
is locked, because it displays the text generated by 'put', and is not supposed to accept any user input.
When you start up this form in your browser, you'll see three pre-filled
lines with "1/eins", "5/fünf" and "7/sieben", according to the
+Init argument (1 5 7). Typing a number somewhere into
the first column, and pressing ENTER or one of the buttons, will show a suitable
text in the second column.
In previous chapters we saw examples of GUI classes like
+TextField, +NumField or +Button, often
in combination with prefix classes like +Lock, +Init
or +Able. Now we take a broader look at the whole hierarchy, and
try more examples.
The abstract class +gui is the base of all GUI classes. A live
view of the class hierarchy can be obtained with the dep ("dependencies") function:
: (dep '+gui)
+gui
+JsField
+Button
+UpButton
+PickButton
+DstButton
+ClrButton
+ChoButton
+Choice
+GoButton
+BubbleButton
+DelRowButton
+ShowButton
+DnButton
+Img
+field
+Checkbox
+TextField
+FileField
+ClassField
+numField
+NumField
+FixField
+BlobField
+DateField
+SymField
+UpField
+MailField
+SexField
+AtomField
+PwField
+ListTextField
+LinesField
+TelField
+TimeField
+HttpField
+Radio
-> +gui
We see, for example, that +DnButton is a subclass of
+Button, which in turn is a subclass of +gui.
Inspecting +DnButton directly
: (dep '+DnButton)
+Tiny
+Rid
+JS
+Able
+gui
+Button
+DnButton
-> +DnButton
shows that +DnButton inherits from +Tiny,
+Rid, +Able and +Button. The actual
definition of +DnButton can be found in "@lib/form.l"
(class +DnButton +Tiny +Rid +JS +Able +Button)
...
In general, "@lib/form.l" is the ultimate reference to the framework, and should be freely consulted.
Input fields implement the visual display of application data, and allow - when enabled - input and modification of these data.
On the HTML level, they can take the form of
Except for checkboxes, which are implemented by the Checkbox class, all these HTML representations are
generated by +TextField and its content-specific subclasses like
+NumField, +DateField etc. Their actual appearance (as
one of the above forms) depends on their arguments:
We saw already "normal" text fields. They are created with a single numeric argument. This example creates an editable field with a width of 10 characters:
(gui '(+TextField) 10)
If you supply a second numeric for the line count ('4' in this case), you'll get a text area:
(gui '(+TextField) 10 4)
Supplying a list of values instead of a count yields a drop-down selection (combo box):
(gui '(+TextField) '("Value 1" "Value 2" "Value 3"))
In addition to these arguments, you can pass a string. Then the field is created with a label:
(gui '(+TextField) 10 "Plain")
(gui '(+TextField) 10 4 "Text Area")
(gui '(+TextField) '("Value 1" "Value 2" "Value 3") "Selection")
Finally, without any arguments, the field will appear as a plain HTML text:
(gui '(+TextField))
This makes mainly sense in combination with prefix classes like
+Var and +Obj, to manage the contents of these fields,
and achieve special behavior as HTML links or scrollable chart values.
A +NumField returns a number from its val>
method, and accepts a number for its set> method. It issues an
error message when user input cannot be converted to a number.
Large numbers are shown with a thousands-separator, as determined by the current locale.
########################################################################
(app)
(action
(html 0 "+NumField" "@lib.css" NIL
(form NIL
(gui '(+NumField) 10)
(gui '(+JS +Button) "Print value"
'(msg (val> (: home gui 1))) )
(gui '(+JS +Button) "Set to 123"
'(set> (: home gui 1) 123) ) ) ) )
########################################################################
A +FixField needs an additional scale factor argument, and
accepts/returns scaled fixpoint numbers.
The decimal separator is determined by the current locale.
########################################################################
(app)
(action
(html 0 "+FixField" "@lib.css" NIL
(form NIL
(gui '(+FixField) 3 10)
(gui '(+JS +Button) "Print value"
'(msg (format (val> (: home gui 1)) 3)) )
(gui '(+JS +Button) "Set to 123.456"
'(set> (: home gui 1) 123456) ) ) ) )
########################################################################
A +DateField accepts and returns a date value.
########################################################################
(app)
(action
(html 0 "+DateField" "@lib.css" NIL
(form NIL
(gui '(+DateField) 10)
(gui '(+JS +Button) "Print value"
'(msg (datStr (val> (: home gui 1)))) )
(gui '(+JS +Button) "Set to \"today\""
'(set> (: home gui 1) (date)) ) ) ) )
########################################################################
The format displayed to - and entered by - the user depends on the current
locale (see datStr and expDat). You can change it, for example to
: (locale "DE" "de")
-> NIL
If no locale is set, the format is YYYY-MM-DD. Some pre-defined locales use patterns like DD.MM.YYYY (DE), YYYY/MM/DD (JP), DD/MM/YYYY (UK), or MM/DD/YYYY (US).
An error is issued when user input does not match the current locale's date format.
Independent from the locale setting, a +DateField tries to
expand abbreviated input from the user. A small number is taken as that day of
the current month, larger numbers expand to day and month, or to day, month and
year:
Similar is the +TimeField. It accepts and returns a time value.
########################################################################
(app)
(action
(html 0 "+TimeField" "@lib.css" NIL
(form NIL
(gui '(+TimeField) 8)
(gui '(+JS +Button) "Print value"
'(msg (tim$ (val> (: home gui 1)))) )
(gui '(+JS +Button) "Set to \"now\""
'(set> (: home gui 1) (time)) ) ) ) )
########################################################################
When the field width is '8', like in this example, time is displayed in the
format HH:MM:SS. Another possible value would be '5', causing
+TimeField to display its value as HH:MM.
An error is issued when user input cannot be converted to a time value.
The user may omit the colons. If he inputs just a small number, it should be between '0' and '23', and will be taken as a full hour. '125' expands to "12:05", '124517' to "12:45:17", and so on.
Telephone numbers are represented internally by the country code (without a
leading plus sign or zero) followed by the local phone number (ideally separated
by spaces) and the phone extension (ideally separated by a hyphen). The exact
format of the phone number string is not enforced by the GUI, but further
processing (e.g. database searches) normally uses fold for better reproducibility.
To display a phone number, +TelField replaces the country code
with a single zero if it is the country code of the current locale, or prepends
it with a plus sign if it is a foreign country (see telStr).
For user input, a plus sign or a double zero is simply dropped, while a
single leading zero is replaced with the current locale's country code (see
expTel).
########################################################################
(app)
(locale "DE" "de")
(action
(html 0 "+TelField" "@lib.css" NIL
(form NIL
(gui '(+TelField) 20)
(gui '(+JS +Button) "Print value"
'(msg (val> (: home gui 1))) )
(gui '(+JS +Button) "Set to \"49 1234 5678-0\""
'(set> (: home gui 1) "49 1234 5678-0") ) ) ) )
########################################################################
A +Checkbox is straightforward. User interaction is restricted
to clicking it on and off. It accepts boolean (NIL or
non-NIL) values, and returns T or NIL.
########################################################################
(app)
(action
(html 0 "+Checkbox" "@lib.css" NIL
(form NIL
(gui '(+Checkbox))
(gui '(+JS +Button) "Print value"
'(msg (val> (: home gui 1))) )
(gui '(+JS +Button) "On"
'(set> (: home gui 1) T) )
(gui '(+JS +Button) "Off"
'(set> (: home gui 1) NIL) ) ) ) )
########################################################################
A big part of this framework's power is owed to the combinatorial flexibility of prefix classes for GUI- and DB-objects. They allow to surgically override individual methods in the inheritance tree, and can be combined in various ways to achieve any desired behavior.
Technically, there is nothing special about prefix classes. They are just normal classes. They are called "prefix" because they are intended to be written before other classes in a class's or object's list of superclasses.
Usually they take their own arguments for their T method from
the list of arguments to the gui function.
+Init overrides the init> method for that
component. The init> message is sent to a +gui
component when the page is loaded for the first time (during a GET request).
+Init takes an expression for the initial value of that field.
(gui '(+Init +TextField) "This is the initial text" 30)
Other classes which automatically give a value to a field are
+Var (linking the field to a variable) and +E/R
(linking the field to a database entity/relation).
+Cue can be used, for example in "mandatory" fields, to give a
hint to the user about what he is supposed to enter. It will display the
argument value, in angular brackets, if and only if the field's value is
NIL, and the val> method will return
NIL despite the fact that this value is displayed.
Cause an empty field to display "<Please enter some text here>":
(gui '(+Cue +TextField) "Please enter some text here" 30)
An important feature of an interactive GUI is the context-sensitive disabling and enabling of individual components, or of a whole form.
The +Able prefix class takes an argument expression, and
disables the component if this expression returns NIL. We saw an
example for its usage already in the square root
button of the calculator example. Or, for illustration purposes, imagine a
button which is supposed to be enabled only after Christmas
(gui '(+Able +Button)
'(>= (cdr (date (date))) (12 24))
"Close this year"
'(endOfYearProcessing) )
or a password field that is disabled as long as somebody is logged in
(gui '(+Able +PwField) '(not *Login) 10 "Password")
A special case is the +Lock prefix, which permanently and
unconditionally disables a component. It takes no arguments
(gui '(+Lock +NumField) 10 "Count")
('10' and "Count" are for the +NumField), and creates a
read-only field.
The whole form can be disabled by calling disable with a
non-NIL argument. This affects all components in this form. Staying
with the above example, we can make the form read-only until Christmas
(form NIL
(disable (> (12 24) (cdr (date (date))))) # Disable whole form
(gui ..)
.. )
Even in a completely disabled form, however, it is often necessary to
re-enable certain components, as they are needed for navigation, scrolling, or
other activities which don't affect the contents of the form. This is done by
prefixing these fields with +Rid (i.e. getting "rid" of the lock).
(form NIL
(disable (> (12 24) (cdr (date (date)))))
(gui ..)
..
(gui '(+Rid +Button) ..) # Button is enabled despite the disabled form
.. )
GUI prefix classes allow a fine-grained control of how values are stored in -
and retrieved from - components. As in predefined classes like
+NumField or +DateField, they override the
set> and/or val> methods.
+Set takes an argument function which is called whenever that
field is set to some value. To convert all user input to upper case
(gui '(+Set +TextField) uppc 30)
+Val is the complement to +Set. It takes a function
which is called whenever the field's value is retrieved. To return the square of
a field's value
(gui '(+Val +NumField) '((N) (* N N)) 10)
+Fmt is just a combination of +Set and
+Val, and takes two functional arguments. This example will display
upper case characters, while returning lower case characters internally
(gui '(+Fmt +TextField) uppc lowc 30)
+Map does (like +Fmt) a two-way translation. It
uses a list of cons pairs for a linear lookup, where the CARs represent the
displayed values which are internally mapped to the values in the CDRs. If a
value is not found in this list during set> or
val>, it is passed through unchanged.
Normally, +Map is used in combination with the combo box
incarnation of text fields (see Input Fields). This
example displays "One", "Two" and "Three" to the user, but returns a number 1, 2
or 3 internally
########################################################################
(app)
(action
(html 0 "+Map" "@lib.css" NIL
(form NIL
(gui '(+Map +TextField)
'(("One" . 1) ("Two" . 2) ("Three" . 3))
'("One" "Two" "Three") )
(gui '(+Button) "Print"
'(msg (val> (field -1))) ) ) ) )
########################################################################
Whenever a button is pressed in the GUI, any changes caused by
action in the current environment (e.g. the database or application
state) need to be reflected in the corresponding GUI fields. For that, the
upd> message is sent to all components. Each component then
takes appropriate measures (e.g. refresh from database objects, load values from
variables, or calculate a new value) to update its value.
While the upd> method is mainly used internally, it can be
overridden in existing classes via the +Upd prefix class. Let's
print updated values to standard error
########################################################################
(app)
(default *Number 0)
(action
(html 0 "+Upd" "@lib.css" NIL
(form NIL
(gui '(+Upd +Var +NumField)
'(prog (extra) (msg *Number))
'*Number 8 )
(gui '(+JS +Button) "Increment"
'(inc '*Number) ) ) ) )
########################################################################
To allow automatic validation of user input, the chk> message
is sent to all components at appropriate times. The corresponding method should
return NIL if the value is all right, or a string describing the
error otherwise.
Many of the built-in classes have a chk> method. The
+NumField class checks for legal numeric input, or the
+DateField for a valid calendar date.
An on-the-fly check can be implemented with the +Chk prefix
class. The following code only accepts numbers not bigger than 9: The
or expression first delegates the check to the main
+NumField class, and - if it does not give an error - returns an
error string when the current value is greater than 9.
########################################################################
(app)
(action
(html 0 "+Chk" "@lib.css" NIL
(form NIL
(gui '(+Chk +NumField)
'(or
(extra)
(and (> (val> This) 9) "Number too big") )
12 )
(gui '(+JS +Button) "Print"
'(msg (val> (field -1))) ) ) ) )
########################################################################
A more direct kind of validation is built-in via the +Limit
class. It controls the maxlength attribute of the generated HTML
input field component. Thus, it is impossible to type to more characters than
allowed into the field.
########################################################################
(app)
(action
(html 0 "+Limit" "@lib.css" NIL
(form NIL
(gui '(+Limit +TextField) 4 8)
(gui '(+JS +Button) "Print"
'(msg (val> (field -1))) ) ) ) )
########################################################################
Although set> and val> are the official
methods to get a value in and out of a GUI component, they are not very often
used explicitly. Instead, components are directly linked to internal Lisp data
structures, which are usually either variables or database objects.
The +Var prefix class takes a variable (described as the
var data type - either a symbol or a cons pair - in the Function Reference). In the following example, we
initialize a global variable with the value "abc", and let a
+TextField operate on it. The "Print" button can be used to display
its current value.
########################################################################
(app)
(setq *TextVariable "abc")
(action
(html 0 "+Var" "@lib.css" NIL
(form NIL
(gui '(+Var +TextField) '*TextVariable 8)
(gui '(+JS +Button) "Print"
'(msg *TextVariable) ) ) ) )
########################################################################
+E/R takes an entity/relation specification. This is a cons
pair, with a relation in its CAR (e.g. nm, for an object's name),
and an expression in its CDR (typically (: home obj), the object
stored in the obj property of the current form).
For an isolated, simple example, we create a temporary database, and access
the nr and nm properties of an object stored in a
global variable *Obj.
########################################################################
(when (app) # On start of session
(class +Tst +Entity) # Define data model
(rel nr (+Number)) # with a number
(rel nm (+String)) # and a string
(pool (tmp "db")) # Create temporary DB
(setq *Obj # and a single object
(new! '(+Tst) 'nr 1 'nm "New Object") ) )
(action
(html 0 "+E/R" "@lib.css" NIL
(form NIL
(gui '(+E/R +NumField) '(nr . *Obj) 8) # Linkage to 'nr'
(gui '(+E/R +TextField) '(nm . *Obj) 20) # Linkage to 'nm'
(gui '(+JS +Button) "Show" # Show the object
'(out 2 (show *Obj)) ) ) ) ) # on standard error
########################################################################
Buttons are, as explained in Control Flow, the only way (via POST requests) for an application to communicate with the server.
Basically, a +Button takes
Here is a minimal button, with just a label and an expression:
(gui '(+Button) "Label" '(doSomething))
And this is a button displaying different labels, depending on the state:
(gui '(+Button) "Enabled" "Disabled" '(doSomething))
To show an image instead of plain text, the label(s) must be preceeded by the
T symbol:
(gui '(+Button) T "img/enabled.png" "img/disabled.png" '(doSomething))
The expression will be executed during action handling (see Action Forms), when this button was pressed.
Like other components, buttons can be extended and combined with prefix classes, and a variety of predefined classes and class combinations are available.
Buttons are essential for the handling of alerts and dialogs. Besides buttons for normal functions, like scrolling in charts or other side effects, special buttons exist which can close an alert or dialog in addition to doing their principal job.
Such buttons are usually subclasses of +Close, and most of them
can be called easily with ready-made functions like closeButton,
cancelButton, yesButton or noButton. We
saw a few examples in Alerts and Dialogs.
When a button inherits from the +JS class (and JavaScript is
enabled in the browser), that button will possibly show a much faster response
in its action.
The reason is that the activation of a +JS button will - instead
of doing a normal POST - first try to send only the contents of all GUI
components via an XMLHttpRequest to the server, and receive the updated values
in response. This avoids the flicker caused by reloading and rendering of the
whole page, is much faster, and also does not jump to the beginning of the page
if it is larger than the browser window. The effect is especially noticeable
while scrolling in charts.
Only if this fails, for example because an error message was issued, or a dialog popped up, it will fall back, and the form will be POSTed in the normal way.
Thus it makes no sense to use the +JS prefix for buttons that
cause a change of the HTML code, open a dialog, or jump to another page. In such
cases, overall performance will even be worse, because the XMLHttpRequest is
tried first (but in vain).
When JavaScript is disabled int the browser, the XMLHttpRequest will not be tried at all. The form will be fully usable, though, with identical functionality and behavior, just a bit slower and not so smooth.
The PicoLisp release includes in the "app/" directory a minimal, yet complete reference application. This application is typical, in the sense that it implements many of the techniques described in this document, and it can be easily modified and extended. In fact, we use it as templates for our own production application development.
It is a kind of simplified ERP system, containing customers/suppliers, products (items), orders, and other data. The order input form performs live updates of customer and product selections, price, inventory and totals calculations, and generates on-the-fly PDF documents. Fine-grained access permissions are controlled via users, roles and permissions. It comes localized in six languages (English, Spanish, German, Norwegian, Russian and Japanese), with some initial data and two sample reports.
For a global installation (see Installation), please create a symbolic link to the place where the program files are installed. This is necessary because the application needs read/write access to the current working directory (for the database and other runtime data).
$ ln -s /usr/share/picolisp/app
As ever, you may start up the application in debugging mode
$ pil app/main.l -main -go +
or in (non-debug) production mode
$ pil app/main.l -main -go -wait
and go to 'http://localhost:8080' with your
browser. You can login as user "admin", with password "admin". The demo data
contain several other users, but those are more restricted in their role
permissions.
Another possibility is to try the online version of this application at app.7fach.de.
Before or after you logged in, you can select another language, and click on the "Change" button. This will effect all GUI components (though not text from the database), and also the numeric, date and telephone number formats.
The navigation menu on the left side shows two items "Home" and "logout", and three submenus "Data", "Report" and "System".
Both "Home" and "logout" bring you back to the initial login form. Use "logout" if you want to switch to another user (say, for another set of permissions), and - more important - before you close your browser, to release possible locks and process resources on the server.
The "Data" submenu gives access to application specific data entry and maintenance: Orders, product items, customers and suppliers. The "Report" submenu contains two simple inventory and sales reports. And the "System" submenu leads to role and user administration.
You can open and close each submenu individually. Keeping more than one submenu open at a time lets you switch rapidly between different parts of the application.
The currently active menu item is indicated by a highlighted list style (no matter whether you arrived at this page directly via the menu or by clicking on a link somewhere else).
Each item in the "Data" or "System" submenu opens a search dialog for that class of entities. You can specify a search pattern, press the top right "Search" button (or just ENTER), and scroll through the list of results.
While the "Role" and "User" entities present simple dialogs (searching just by name), other entities can be searched by a variety of criteria. In those cases, a "Reset" button clears the contents of the whole dialog. A new object can be created with bottom right "New" button.
In any case, the first column will contain either a "@"-link (to jump to that object) or a "@"-button (to insert a reference to that object into the current form).
By default, the search will list all database objects with an attribute value greater than or equal to the search criterion. The comparison is done arithmetically for numbers, and alphabetically (case sensitive!) for text. This means, if you type "Free" in the "City" field of the "Customer/Supplier" dialog, the value of "Freetown" will be matched. On the other hand, an entry of "free" or "town" will yield no hits.
Some search fields, however, show a different behavior depending on the application:
Using the bottom left scroll buttons, you can scroll through the result list without limit. Clicking on a link will bring up the corresponding object. Be careful here to select the right column: Some dialogs (those for "Item" and "Order") also provide links for related entities (e.g. "Supplier").
A database object is usually displayed in its own individual form, which is determined by its entity class.
The basic layout should be consistent for all classes: Below the heading (which is usually the same as the invoking menu item) is the object's identifier (name, number, etc.), and then a row with an "Edit" button on the left, and "Delete" button, a "Select" button and two navigation links on the right side.
The form is brought up initially in read-only mode. This is necessary to prevent more than one user from modifying an object at the same time (and contrary to the previous PicoLisp Java frameworks, where this was not a problem because all changes were immediately reflected in the GUIs of other users).
So if you want to modify an object, you have to gain exclusive access by clicking on the "Edit" button. The form will be enabled, and the "Edit" button changes to "Done". Should any other user already have reserved this object, you will see a message telling his name and process ID.
An exception to this are objects that were just created with "New". They will automatically be reserved for you, and the "Edit" button will show up as "Done".
The "Delete" button pops up an alert, asking for confirmation. If the object is indeed deleted, this button changes to "Restore" and allows to undelete the object. Note that objects are never completely deleted from the database as long as there are any references from other objects. When a "deleted" object is shown, its identifier appears in square brackets.
The "Select" button (re-)displays the search dialog for this class of entities. The search criteria are preserved between invocations of each dialog, so that you can conveniently browse objects in this context.
The navigation links, pointing left and right, serve a similar purpose. They let you step sequentially through all objects of this class, in the order of the identifier's index.
Other buttons, depending on the entity, are usually arranged at the bottom of the form. The bottom rightmost one should always be another "Edit" / "Done" button.
As we said in the chapter on Scrolling, any button in the form will save changes to the underlying data model. As a special case, however, the "Done" button releases the object and reverts to "Edit". Besides this, the edit mode will also cease as soon as another object is displayed, be it by clicking on an object link (the pencil icon), the top right navigation links, or a link in a search dialog.
The only way to interact with a HTTP-based application server is to click either on a HTML link, or on a submit button (see also Control Flow). It is essential to understand the different effects of such a click on data entered or modified in the current form.
For that reason the layout design should clearly differentiate between links and buttons. Image buttons are not a good idea when in other places images are used for links. The standard button components should be preferred; they are usually rendered by the browser in a non-ambiguous three-dimensional look and feel.
Note that if JavaScript is enabled in the browser, changes will be automatically committed to the server.
The enabled or disabled state of a button is an integral part of the application logic. It must be indicated to the user with appropriate styles.
The data model for this mini application consists of only six entity classes (see the E/R diagram at the beginning of "app/er.l"):
+CuSu (Customer/Supplier),
+Item (Product Item) and +Ord (Order).
+Pos object is a single position in an order.
+Role and +User objects are needed for
authentication and authorization.
The classes +Role and +User are defined in
"@lib/adm.l". A +Role has a name, a list of permissions, and a list
of users assigned to this role. A +User has a name, a password and
a role.
In "app/er.l", the +Role class is extended to define an
url> method for it. Any object whose class has such a method is
able to display itself in the GUI. In this case, the file "app/role.l" will be
loaded - with the global variable *ID pointing to it - whenever an
HTML link to this role object is activated.
The +User class is also extended. In addition to the login name,
a full name, telephone number and email address is declared. And, of course, the
ubiquitous url> method.
The application logic is centered around orders. An order has a number, a
date, a customer (an instance of +CuSu) and a list of positions
(+Pos objects). The sum> method calculates the
total amount of this order.
Each position has an +Item object, a price and a quantity. The
price in the position overrides the default price from the item.
Each item has a number, a description, a supplier (also an instance of
+CuSu), an inventory count (the number of these items that were
counted at the last inventory taking), and a price. The cnt>
method calculates the current stock of this item as the difference of the
inventory and the sold item counts.
The call to dbs at the end of "app/er.l" configures the physical
database storage. Each of the supplied lists has a number in its CAR which
determines the block size as (64 << N) of the corresponding database file.
The CDR says that the instances of this class (if the element is a class symbol)
or the tree nodes (if the element is a list of a class symbol and a property
name) are to be placed into that file. This allows for some optimizations in the
database layout.
When you are connected to the application (see Getting Started) you might try to do some "real" work with it. Via the "Data" menu (see Navigation) you can create or modify customers, suppliers, items and orders, and produce simple overviews via the "Report" menu.
Source in "app/cusu.l"
The Customer/Supplier search dialog (choCuSu in "app/gui.l")
supports a lot of search criteria. These become necessary when the database
contains a large number of customers, and can filter by zip, by phone number
prefixes, and so on.
In addition to the basic layout (see Editing), the form is divided into four separate tabs. Splitting a form into several tabs helps to reduce traffic, with possibly better GUI response. In this case, four tabs are perhaps overkill, but ok for demonstration purposes, and they leave room for extensions.
Be aware that when data were modified in one of the tabs, the "Done" button has to be pressed before another tab is clicked, because tabs are implemented as HTML links (see Buttons vs. Links).
New customers or suppliers will automatically be assigned the next free number. You can enter another number, but an error will result if you try to use an existing number. The "Name" field is mandatory, you need to overwrite the "<Name>" clue.
Phone and fax numbers in the "Contact" tab must be entered in the correct format, depending on the locale (see Telephone Numbers).
The "Memo" tab contains a single text area. It is no problem to use it for large pieces of text, as it gets stored in a database blob internally.
Source in "app/item.l"
Items also have a unique number, and a mandatory "Description" field.
To assign a supplier, click on the "+" button. The Customer/Supplier search dialog will appear, and you can pick the desired supplier with the "@" button in the first column. Alternatively, if you are sure to know the exact spelling of the supplier's name, you can also enter it directly into the text field.
In the search dialog you may also click on a link, for example to inspect a possible supplier, and then return to the search dialog with the browser's back button. The "Edit" mode will then be lost, however, as another object has been visited (this is described in the last part of Editing).
You can enter an inventory count, the number of items currently in stock. The following field will automatically reflect the remaining pieces after some of these items were sold (i.e. referenced in order positions). It cannot be changed manually.
The price should be entered with the decimal separator according to the current locale. It will be formatted with two places after the decimal separator.
The "Memo" is for an arbitrary info text, like in Customer/Supplier above, stored in a database blob.
Finally, a JPEG picture can be stored in a blob for this item. Choose a file with the browser's file select control, and click on the "Install" button. The picture will appear at the bottom of the page, and the "Install" button changes to "Uninstall", allowing the picture's removal.
Source in "app/ord.l"
Oders are identified by number and date.
The number must be unique. It is assigned when the order is created, and cannot be changed for compliance reasons.
The date is initialized to "today" for a newly created order, but may be changed manually. The date format depends on the locale. It is YYYY-MM-DD (ISO) by default, DD.MM.YYYY in the German and YYYY/MM/DD in the Japanese locale. As described in Time & Date, this field allows input shortcuts, e.g. just enter the day to get the full date in the current month.
To assign a customer to this order, click on the "+" button. The Customer/Supplier search dialog will appear, and you can pick the desired customer with the "@" button in the first column (or enter the name directly into the text field), just as described above for Items.
Now enter order the positions: Choose an item with the "+" button. The "Price" field will be preset with the item's default price, you may change it manually. Then enter a quantity, and click a button (typically the "+" button to select the next item, or a scroll button go down in the chart). The form will be automatically recalculated to show the total prices for this position and the whole order.
Instead of the "+" or scroll buttons, as recommended above, you could of course also press the "Done" button to commit changes. This is all right, but has the disadvantage that the button must be pressed a second time (now "Edit") if you want to continue with the entry of more positions.
The "x" button at the right of each position deletes that position without further confirmation. It has to be used with care!
The "^" button is a "bubble" button. It exchanges a row with the row above it. Therefore, it can be used to rearrange all items in a chart, by "bubbling" them to their desired positions.
The "PDF-Print" button generates and displays a PDF document for this order. The browser should be configured to display downloaded PDF documents in an appropriate viewer. The source for the postscript generating method is in "app/lib.l". It produces one or several A4 sized pages, depending on the number of positions.
Sources in "app/inventory.l and "app/sales.l"
The two reports ("Inventory" and "Sales") come up with a few search fields and a "Show" button.
If no search criteria are entered, the "Show" button will produce a listing of the relevant part of the whole database. This may take a long time and cause a heavy load on the browser if the database is large.
So in the normal case, you will limit the domain by stating a range of item numbers, a description pattern, and/or a supplier for the inventory report, or a range of order dates and/or a customer for the sales report. If a value in a range specification is omitted, the range is considered open in that direction.
At the end of each report appears a "CSV" link. It downloads a file with the
TAB-separated values generated by this report.
picolisp-3.1.5.2.orig/doc/db 0000644 0000000 0000000 00000007005 12265263724 014227 0 ustar root root Max DB-Size: 7 digits -> 2**42 (4 Tera) Blocks
Blocksize 64 -> (2**48 Bytes (256 TB))
Tree
NIL -> (val *DB)
{x} -> (val '{x})
(var . {x}) -> (get '{x} 'var)
(var . +Cls) -> (get *DB '+Cls 'var)
(var +Cls . {x}) -> (get '{x} '+Cls 'var)
B-Tree root:
(cnt . node)
B-Tree node:
(less (key more . value) (key more . value) ..)
(less ((key . value) more) ((key . value) more) ..)
Per node
BEG EXTERN <6> .. NIX
6+1+1+6+1 = 15
Per key
BEG TRANSIENT NIL
(gui '(+E/R +TextField) '(nm : home obj) 40 "Name")
(gui '(+ClassField) '(: home obj) '(("Male" +Man) ("Female" +Woman))) )
( 2 YT[pӝSN0}cb?,/Bӥgp`h nCqq} 9+WkiEu@
N`/@>
#i힕 [QZرzV^Q⟏7`m=l1 { · Mϕ 6ls]ҸVMҥoIOHVD's=A SarLakDYI[B nF
8%}< ^%CPv^ Bp ɡ.u
gﻯ؇g?vf9=+j?yNh;-A\ ݰz&nnbRXv:`eE;pDE p.,ك; x#X?}:( {VDW/v;d>
(d# g<',VBTC=ZJZɮP|lTp# }IKSC Mqcz˩;]w`k#ZeVcO2&JS՞Vⅶ]E'u~߱|?b5&[
WGGZ9B#AԻ}ٗ iMw7nL0>L@q"ϋDCiѠkQ&"=}o
d>esxY
Monk: "If I have nothing in my mind, what shall I do?" (c) Software Lab. Alexander Burger
Because other Lisps are not the way I'd like them to be. They concentrate on
efficient compilation, and lost the one-to-one relationship of language and
virtual machine of an interpreted system, gave up power and flexibility, and
impose unnecessary limitations on the freedom of the programmer. Other reasons
are the case-insensitivity and complexity of current Lisp systems.
PicoLisp is for programmers who want to control their programming
environment, at all levels, from the application domain down to the bare metal.
Who want use a transparent and simple - yet universal - programming model, and
want to know exactly what is going on. This is an aspect influenced by
It does not pretend to be easy to learn. There are already plenty of
languages that do so. It is not for people who don't care what's under the hood,
who just want to get their application running. They are better served with some
standard, "safe" black-box, which may be easier to learn, and which allegedly
better protects them from their own mistakes.
PicoLisp is easy to understand and adapt. There is no compiler enforcing
special rules, and the interpreter is simple and straightforward. There are only
three data types: Numbers, symbols and lists ("LISP" means "List-, Integer- and
Symbol Processing" after all ;-). The memory footprint is minimal, and the
tarball size of the whole system is just a few hundred kilobytes.
Most other systems define the language, and leave it up to the implementation
to follow the specifications. Therefore, language designers try to be as
abstract and general as possible, leaving many questions and ambiguities to the
users of the language.
PicoLisp does the opposite. Initially, only the single-cell data structure
was defined, and then the structure of numbers, symbols and lists as they are
composed of these cells. Everything else in the whole system follows from these
axioms. This is documented in the chapter about the The
PicoLisp Machine in the reference manual.
There is only one symbolic data type, no distinction (confusion) between
symbols, strings, variables, special variables and identifiers.
Most data-manipulation functions operate on the values of symbols as well as
the CARs of cons pairs:
There is only a single functional type, no "special forms". As there is no
compiler, functions can be used instead of macros. No special "syntax"
constructs are needed. This allows a completely orthogonal use of functions. For
example, most other Lisps do not allow calls like
PicoLisp has no such restrictions. It favors the principle of "Least
Astonishment".
The OOP system is very powerful, because it is fully dynamic, yet extremely
simple:
PicoLisp has many practical features not found in other Lisp dialects. Among
them are:
Database objects ("external" symbols) are a primary data type in PicoLisp.
They look like normal symbols to the programmer, but are managed in the database
(fetched from, and stored to) automatically by the system. Symbol manipulation
functions like It is a stand-alone system (it does not depend on external programs like
Apache or MySQL) and it provides a "live" user interface on the client side,
with an application server session for each connected client. The GUI layout and
behavior are described with S-expressions, generated dynamically at runtime, and
interact directly with the database structures.
Internal exclusive and full use of UTF-8 encoding, and self-translating transient symbols (strings), make it easy to
write country- and language-independent applications.
Despite the fact that PicoLisp is an interpreted-only system, the performance
is quite good. Typical Lisp programs operating on list data structures are
executed in (interpreted) PicoLisp at about the same speed as in (compiled)
CMUCL, and about two or three times faster than in CLisp or Scheme48. Programs
with lots of numeric calculations, however, may be slower on a 32-bit system,
due to PicoLisp's somewhat inefficient implementation of numbers. The 64-bit
version improved on that.
But in practice, speed was never a problem, even with the first versions of
PicoLisp in 1988 on a Mac II with a 12 MHz CPU. And certain things are cleaner
and easier to do in plain PicoLisp is very space-effective. Other Lisp systems reserve heap space twice
as much as needed, or use rather large internal structures to store cells and
symbols. Each cell or minimal symbol in PicoLisp consists of only two pointers.
No additional tags are stored, because they are implied in the pointer
encodings. No gaps remain in the heap during allocation, as there are only
objects of a single size. As a result, consing and garbage collection are very
fast, and overall performance benefits from a better cache efficiency. Heap and
stack grow automatically, and are limited only by hardware and operating system
constraints.
It means to directly execute Lisp data as program code. No transformation to
another representation of the code (e.g. compilation), and no structural
modifications of these data, takes place.
Lisp data are the "real" things, like numbers, symbols and lists, which can
be directly handled by the system. They are not the textual
representation of these structures (which is outside the Lisp realm and taken
care of the The following example builds a function and immediately calls it with two
arguments:
Note that no time is wasted to build up a lexical environment. Variable
bindings take place dynamically during interpretation.
A PicoLisp function is able to inspect or modify itself while it is running
(though this is rarely done in application programming). The following function
modifies itself by incrementing the '0' in its body:
Only an interpreted Lisp can fully support such "Equivalence of Code and
Data". If executable pieces of data are used frequently, like in PicoLisp's
dynamically generated GUI, a fast interpreter is preferable over any compiler.
No. That would contradict the idea of PicoLisp's simple virtual machine
structure. A compiler transforms it to another (physical) machine, with the
result that many assumptions about the machine's behavior won't hold any more.
Besides that, PicoLisp primitive functions evaluate their arguments
independently and are not suited for being called from compiled code. Finally,
the gain in execution speed would probably not be worth the effort. Typical
PicoLisp applications often use single-pass code which is loaded, executed and
thrown away; a process that would be considerably slowed down by compilation.
Yes and No. Though we wrote and tested PicoLisp originally only on Linux, it
now also runs on FreeBSD, Mac OS X (Darwin), Cygwin/Win32, and probably other
POSIX systems. The first versions were even fully portable between DOS, SCO-Unix
and Macintosh systems. But today we have Linux. Linux itself is very portable,
and you can get access to a Linux system almost everywhere. So why bother?
The GUI is completely platform independent (Browser), and in the times of
Internet an application server does not really need to be portable.
Not really, but it evolved a great deal into that direction.
Historically it was the other way round: We had a plain X11 GUI for our
applications, and needed something platform independent. The solution was
obvious: Browsers are installed virtually everywhere. So we developed a protocol
which persuades a browser to function as a GUI front-end to our applications.
This is much simpler than to develop a full-blown web server.
Because it isn't there. The reason is that it is redundant; it is equivalent
to the Dynamic binding is very powerful, because there is only one single,
dynamically changing environment active all the time. This makes it possible
(e.g. for program snippets, interspersed with application data and/or passed
over the network) to access the whole application context, freely, yet in a
dynamically controlled manner. And (shallow) dynamic binding is the fastest
method for a Lisp interpreter.
Lexical binding is more limited by definition, because each environment is
deliberately restricted to the visible (textual) static scope within its
establishing form. Therefore, most Lisps with lexical binding introduce "special
variables" to support dynamic binding as well, and constructs like
In PicoLisp, function definitions are normal symbol values. They can be
dynamically rebound like other variables. As a useful real-world example, take
this little gem:
It implements anonymous recursion, by defining Needless to say, the call to You mean the funarg problem, or problems that arise when a variable
might be bound to itself? For that reason we have a convention in
PicoLisp to use transient symbols (instead
of internal symbols)
This is a form of lexical scoping - though we still have dynamic
binding - of symbols, similar to the In fact, these problems are a real threat, and may lead to mysterious bugs
(other Lisps have similar problems, e.g. with symbol capture in macros). They
can be avoided, however, when the above conventions are observed. As an example,
consider a function which doubles the value in a variable:
This works fine, as long as we call it as If Admittedly, there are two disadvantages with this solution:
This is not true. Closures are a matter of scope, not of binding.
For a closure it is necessary to build and maintain a separate environment.
In a system with lexical bindings, this has to be done at each function
call, and for compiled code it is the most efficient strategy anyway, because it
is done once by the compiler, and can then be accessed as stack frames at
runtime.
For an interpreter, however, this is quite an overhead. So it should not be
done automatically at each and every function invocation, but only if needed.
You have several options in PicoLisp. For simple cases, you can take
advantage of the static scope of transient
symbols. For the general case, PicoLisp has built-in functions like Environments are first-class objects in PicoLisp, more flexible than
hard-coded closures, because they can be created and manipulated independently
from the code.
As an example, consider a currying function:
When called, it returns a function-building function which may be applied to
some argument:
or used as:
In other cases, you are free to choose a shorter and faster solution. If (as
in the example above) the curried argument is known to be immutable:
Then the function built above will just be:
In that case, the "environment build-up" is reduced by a simple (lexical)
constant substitution with zero runtime overhead.
Note that the actual Yes, there is a macro mechanism in PicoLisp, to build and immediately execute
a list of expressions. But it is seldom used. Macros are a kludge. Most things
where you need macros in other Lisps are directly expressible as functions in
PicoLisp, which (as opposed to macros) can be applied, passed around, and
debugged.
For example, Common Lisp's Because PicoLisp has something better: Transient symbols. They look and behave like
strings in any respect, but are nevertheless true symbols, with a value and a
property list.
This leads to interesting opportunities. The value, for example, can point to
other data that represent the string's translation. This is used extensively for
localization. When a program calls
then changing the value of the symbol Transient symbols are also quite memory-conservative. As they are stored in
normal heap cells, no additional overhead for memory management is induced. The
cell holds the symbol's value in its CDR, and the tail in its CAR. If the string
is not longer than 7 bytes, it fits (on the 64-bit version) completely into the
tail, and a single cell suffices. Up to 15 bytes take up two cells, 23 bytes
three etc., so that long strings are not very efficient (needing twice the
memory on the average), but this disadvantage is made up by simplicity and
uniformity. And lots of extremely long strings are not the common case, as they
are split up anyway during processing, and stored as plain byte sequences in
external files and databases.
Because transient symbols are temporarily interned (while PicoLisp has no array or vector data type. Instead, lists must be used for
any type of sequentially arranged data.
We believe that arrays are usually overrated. Textbook wisdom tells that they
have a constant access time O(1) when the index is known. Many other operations
like splits or insertions are rather expensive. Access with a known (numeric)
index is not really typical for Lisp, and even then the advantage of an array is
significant only if it is relatively long. Holding lots of data in long arrays,
however, smells quite like a program design error, and we suspect that often
more structured representations like trees or interconnected objects would be
better.
In practice, most arrays are rather short, or the program can be designed in
such a way that long arrays (or at least an indexed access) are avoided.
Using lists, on the other hand, has advantages. We have so many concerted
functions that uniformly operate on lists. There is no separate data type that
has to be handled by the interpreter, garbage collector, I/O, database and so
on. Lists can be made circular. And lists don't cause memory fragmentation.
PicoLisp does not support real floating point numbers. You can do all kinds
of floating point calculations by calling existing library functions via
But PicoLisp has something even (arguably) better: Scaled fixpoint numbers, with unlimited precision.
The reasons for this design decision are manifold. Floating point numbers
smack of imperfection, they don't give "exact" results, have limited precision
and range, and require an extra data type. It is hard to understand what really
goes on (How many digits of precision do we have today? Are perhaps 10-byte
floats used for intermediate results? How does rounding behave?).
For fixpoint support, the system must handle just integer arithmetics, I/O
and string conversions. The rest is under programmer's control and
responsibility (the essence of PicoLisp).
Carefully scaled fixpoint calculations can do anything floating points can
do.
That's not a good idea. The next time that function gets executed within the
dynamic context the system may crash. Therefore we have a convention to use an
upper case first letter for locally bound symbols:
At least it should be interesting. It would be a machine executing list
(tree) structures instead of linear instruction sequences. "Instruction
prefetch" would look down the CAR- and CDR-chains, and perhaps need only a
single cache for both data and instructions.
Primitive functions like Only a single heap and a single stack is needed. They grow towards each
other, and cause garbage collection if they get too close. Heap compaction is
trivial due to the single cell size.
There would be no assembly-language. The lowest level (above the hardware and
microcode levels) are s-expressions: The machine language is Lisp.
It is easy to produce a segfault in PicoLisp. Just set a symbol to a value
which is not a function, and call it:
PicoLisp is a pragmatic language. It doesn't check at runtime for all
possible error conditions which won't occur during normal usage. Such errors are
usually detected quickly at the first test run, and checking for them after that
would just produce runtime overhead.
Catching the segmentation violation and bus fault signals is also not a good
idea, because the Lisp heap is most probably be damaged afterwards, possibly
creating further havoc if execution continues.
It is recommended to inspect the code periodically with The best place is the PicoLisp Mailing
List (see also The Mail
Archive and Gmane.org), or the
IRC #picolisp channel on
FreeNode.net.
picolisp-3.1.5.2.orig/doc/fun.l 0000644 0000000 0000000 00000000210 12265263724 014653 0 ustar root root # 25jun07abu
# (c) Software Lab. Alexander Burger
(de fact (N)
(if (=0 N)
1
(* N (fact (dec N))) ) )
# vi:et:ts=3:sw=3
picolisp-3.1.5.2.orig/doc/hello.l 0000644 0000000 0000000 00000000143 12265263724 015173 0 ustar root root (load "@lib/xhtml.l")
(html 0 "Hello" NIL NIL
( (c) Software Lab. Alexander Burger
This document describes how to call C functions in shared object files
(libraries) from PicoLisp, using the built-in The direct return value of In combination, these three functions can interface PicoLisp to almost any C
function.
The above steps are fully dynamic; The arguments to The simplest form is a call to a function without return value and without
arguments. If we assume a library "lib.so", containing a function with the
prototype
then we can call it as
The first argument to As a special case, a transient symbol If called with a symbolic argument, The same rules applies to the second argument, the function. When called with
a symbol, In most cases a program will call more than one function from a given
library. If we keep the code within the same transient scope (i.e. in the same
source file, and not separated by the After After any one of Warning: It should be avoided to put more than one library into a single
transient scope if there is a chance that two different functions with the same
name will be called in two different libraries. Because of the function pointer
caching, the second call would otherwise (wrongly) go to the first function.
The (optional) third argument to As described in the result specification,
the third argument should consist of a pattern which tells In the simplest case, the result specification is If the result specification is one of the symbols If the result specification is the symbol A specification of If the result specification is a number, it will be used as a scale to
convert a returned Examples for function calls, with their corresponding C prototypes:
If the result specification is a list, it means that the C function returned
a pointer to an array, or an arbitrary memory structure. The specification list
should then consist of either the above primitive specifications (symbols or
numbers), or of cons pairs of a primitive specification and a repeat count, to
denote arrays of the given type.
Examples for function calls, with their corresponding pseudo C prototypes:
If a returned structure has an element which is a pointer to some
other structure (i.e. not an embedded structure like in the last example above),
this pointer must be first obtained with a The (optional) fourth and following arguments to Integer arguments (up to 64 bits, signed or unsigned String arguments can be specified as symbols. Note that the allocated string memory is released after the return
value is extracted. This allows a C function to return the argument string
pointer, perhaps after modifying the data in-place, and receive the new string
as the return value (with the Also note that specifying Floating point arguments are specified as cons pairs, where the value is in
the CAR, and the CDR holds the fixpoint scale. If the scale is positive, the
number is passed as a Composite arguments are specified as nested list structures.
This implies that such an argument can be both an input and an output value
to a C function (pass by reference).
The CAR of the argument specification can be The CADR of the argument specification must be a cons pair with the total
size of the structure in its CAR. The CDR is ignored for input-only arguments,
and should contain a result specification for
the output value to be stored in the variable.
For example, a minimal case is a function that takes an integer reference,
and stores the number '123' in that location:
We call The rest (CDDR) of the argument specification may contain initialization
data, if the C function expects input values in the structure. It should be a
list of initialization items, optionally with a
fill-byte value in the CDR of the last cell.
If there are no initialization items and just the final fill-bye, then
the whole buffer is filled with that byte. For example, to pass a buffer of 20
bytes, initialized to zero:
A buffer of 20 bytes, with the first 4 bytes initialized to 1, 2, 3, and 4,
and the rest filled with zero:
and the same, where the buffer contents are returned as a list of bytes in
the variable For a more extensive example, let's use the following definitions:
We call this function with a structure of 40 bytes, requesting the returned
data in then it will print the integers 7 and 6, and i.e. the original integer values 7 and 6 replaced with 3 and 4.
Note that the allocated structure memory is released after the return
value is extracted. This allows a C function to return the argument structure
pointer, perhaps after modifying the data in-place, and receive the new
structure as the return value - instead of (or even in addition to) to the
direct return via the argument reference.
The preceding Arguments section mentions that
Technically, this mimics automatic variables in C.
For a simple example, let's assume that we want to call The structure argument (Note that we use Instead of a single integer, we might want a list of four bytes to be
returned from The difference is that we wrote Let's see what happens if we extend this example. We'll write the four bytes
to another file descriptor, after reading them from the first one:
Again, This work as expected. i.e. no return variable, a four-byte memory area, filled with the four bytes
(assuming that But: This solution induces quite some overhead. The four-byte buffer is
allocated before the call to If the above operation is to be used more than once, it is better to allocate
the buffer manually, use it for both reading and writing, and then release it.
This also avoids all intermediate list conversions.
For a more typical example, we might call the Fast Fourier Transform using
the library from the FFTW package. With the
example code for calculating Complex One-Dimensional DFTs:
we can build the following equivalent:
This assumes that the argument list The above translation to Lisp is quite straightforward. After the two buffers
are allocated, and a plan is created, If such allocated data (strings, arrays or structures passed to
As we know that the format string If we look at the This pointer will be used by Sometimes it is necessary to do the reverse: Call Lisp code from C code. This
can be done in two ways - with certain limitations.
The first way is actually not a callback
in the strict sense. It just allows to call a Lisp function with a given name.
The limitation is that this function can accept only maximally five numeric
arguments, and returns a number.
The prerequisite is, of course, that you have access to the C source code. To
use it from C, insert the following prototype somewhere before the first call:
Then you can call The first argument should be the name of a Lisp function (built-in, or
defined in Lisp). It is searched for at runtime, so it doesn't need to exist at
the time the C library is compiled or loaded.
Be sure to pass dummy arguments (e.g. zero) if your function expects less
than five arguments, to keep the C compiler happy.
This mechanism can generally be used for any type of argument and return
value (not only This is a true callback
mechanism. It uses the Lisp-level function Callbacks are often used in user interface libraries, to handle key-, mouse-
and other events. Examples can be found in (The global A program using OpenGL may then use so that future clicks into the window will pass the button, state and
coordinates to that function.
picolisp-3.1.5.2.orig/doc/quine 0000644 0000000 0000000 00000000710 12265263724 014757 0 ustar root root With lambda (= 'quote'):
: ('((X) (list (lit X) (lit X))) '((X) (list (lit X) (lit X))))
-> ('((X) (list (lit X) (lit X))) '((X) (list (lit X) (lit X))))
With 'let':
: (let X '(list 'let 'X (lit X) X) (list 'let 'X (lit X) X))
-> (let X '(list 'let 'X (lit X) X) (list 'let 'X (lit X) X))
Cheating:
: (de quine NIL
(pp 'quine) )
-> quine
: (quine)
(de quine NIL
(pp 'quine) )
-> quine
Succinct:
: T
-> T
picolisp-3.1.5.2.orig/doc/ref.html 0000644 0000000 0000000 00000273666 12265263724 015403 0 ustar root root
Perfection is attained (c) Software Lab. Alexander Burger
This document describes the concepts, data types, and kernel functions of the
PicoLisp system.
This is not a Lisp tutorial. For an introduction to Lisp, a
traditional Lisp book like "Lisp" by Winston/Horn (Addison-Wesley 1981) is
recommended. Note, however, that there are significant differences between
PicoLisp and Maclisp (and even greater differences to Common Lisp).
Please take a look at the PicoLisp Tutorial for an
explanation of some aspects of PicoLisp, and scan through the list of Frequently Asked Questions (FAQ).
PicoLisp is the result of a language design study, trying to answer the
question "What is a minimal but useful architecture for a virtual machine?".
Because opinions differ about what is meant by "minimal" and "useful", there are
many answers to that question, and people might consider other solutions more
"minimal" or more "useful". But from a practical point of view, PicoLisp has
proven to be a valuable answer to that question.
First of all, PicoLisp is a virtual machine architecture, and then a
programming language. It was designed in a "bottom up" way, and "bottom up" is
also the most natural way to understand and to use it: Form Follows
Function.
PicoLisp has been used in several commercial and research programming
projects since 1988. Its internal structures are simple enough, allowing an
experienced programmer always to fully understand what's going on under the
hood, and its language features, efficiency and extensibility make it suitable
for almost any practical programming task.
In a nutshell, emphasis was put on four design objectives. The PicoLisp
system should be
An important point in the PicoLisp philosophy is the knowledge about the
architecture and data structures of the internal machinery. The high-level
constructs of the programming language directly map to that machinery, making
the whole system both understandable and predictable.
This is similar to assembly language programming, where the programmer has
complete control over the machine.
The PicoLisp virtual machine is both simpler and more powerful than most
current (hardware) processors. At the lowest level, it is constructed from a
single data structure called "cell":
A cell is a pair of machine words, which traditionally are called CAR and CDR
in the Lisp terminology. These words can represent either a numeric value
(scalar) or the address of another cell (pointer). All higher level data
structures are built out of cells.
The type information of higher level data is contained in the pointers to
these data. Assuming the implementation on a byte-addressed physical machine,
and a pointer size of typically 4 bytes, each cell has a size of 8 bytes.
Therefore, the pointer to a cell must point to an 8-byte boundary, and its
bit-representation will look like:
(the ' In any case, bit(0) - the least significant of these bits - is reserved as a
mark bit for garbage collection.
Initially, all cells in the memory are unused (free), and linked together to
form a "free list". To create higher level data types at runtime, cells are
taken from that free list, and returned by the garbage collector when they are
no longer needed. All memory management is done via that free list; there are no
additional buffers, string spaces or special memory areas, with two exceptions:
On the virtual machine level, PicoLisp supports
They are all built from the single cell data structure, and all runtime data
cannot consist of any other types than these three.
The following diagram shows the complete data type hierarchy, consisting of
the three base types and the symbol variations:
A number can represent a signed integral value of arbitrary size. The CARs of
one or more cells hold the number's "digits" (each in the machine's word size),
to store the number's binary representation.
The first cell holds the least significant digit. The least significant bit
of that digit represents the sign.
The pointer to a number points into the middle of the CAR, with an offset of
2 from the cell's start address. Therefore, the bit pattern of a number will be:
Thus, a number is recognized by the interpreter when bit(1) is non-zero.
A symbol is more complex than a number. Each symbol has a value, and
optionally a name and an arbitrary number of properties. The CDR of a symbol
cell is also called VAL, and the CAR points to the symbol's tail. As a minimum,
a symbol consists of a single cell, and has no name or properties:
That is, the symbol's tail is empty (points to The pointer to a symbol points to the CDR of the cell, with an offset of 4
from the cell's start address. Therefore, the bit pattern of a symbol will be:
Thus, a symbol is recognized by the interpreter when bit(2) is non-zero.
A property is a key-value pair, represented by a cons pair in the symbol's
tail. This is called a "property list". The property list may be terminated by a
number representing the symbol's name. In the following example, a symbol with
the name Each property in a symbol's tail is either a symbol (like the single KEY
above, then it represents the boolean value The name of a symbol is stored as a number at the end of the tail. It
contains the characters of the name in UTF-8 encoding, using between one and
three 8-bit-bytes per character. The first byte of the first character is stored
in the lowest 8 bits of the number.
All symbols have the above structure, but depending on scope and
accessibility there are actually four types of symbols: For that, The reason for that structure is These requirements are fulfilled by the above structure.
Internal Symbols are all those "normal" symbols, as they are used for
function definitions and variable names. They are "interned" into an index
structure, so that it is possible to find an internal symbol by searching for
its name.
There cannot be two different internal symbols with the same name.
Initially, a new internal symbol's VAL is Transient symbols are only interned into a index structure for a certain time
(e.g. while reading the current source file), and are released after that. That
means, a transient symbol cannot be accessed then by its name, and there may be
several transient symbols in the system having the same name.
Transient symbols are used
Initially, a new transient symbol's VAL is that symbol itself.
A transient symbol without a name can be created with the External symbols reside in a database file (or a similar resources, see
The interpreter recognizes external symbols internally by an additional tag
bit in the tail structure.
There cannot be two different external symbols with the same name. External
symbols are maintained in index structures while they are loaded into memory,
and have their external location (disk file and block offset) directly coded
into their names (more details here).
Initially, a new external symbol's VAL is A list is a sequence of one or more cells (cons pairs), holding numbers,
symbols, or cons pairs.
Lists are used in PicoLisp to emulate composite data structures like arrays,
trees, stacks or queues.
In contrast to lists, numbers and symbols are collectively called "Atoms".
Typically, the CDR of each cell in a list points to the following cell,
except for the last cell which points to The PicoLisp interpreter has complete knowledge of all data in the system,
due to the type information associated with every pointer. Therefore, an
efficient garbage collector mechanism can easily be implemented. PicoLisp
employs a simple but fast mark-and-sweep garbage collector.
As the collection process is very fast (in the order of milliseconds per
megabyte), it was not necessary to develop more complicated, time-consuming and
error-prone garbage collection algorithms (e.g. incremental collection). A
compacting garbage collector is also not necessary, because the single cell data
type cannot cause heap fragmentation.
Lisp was chosen as the programming language, because of its clear and simple
structure.
In some previous versions, a Forth-like syntax was also implemented on top of
a similar virtual machine (Lifo). Though that language was more flexible and
expressive, the traditional Lisp syntax proved easier to handle, and the virtual
machine can be kept considerably simpler.
PicoLisp inherits the major advantages of classical Lisp systems like
In the following, some concepts and peculiarities of the PicoLisp language
and environment are described.
PicoLisp supports two installation strategies: Local and Global.
Normally, if you didn't build PicoLisp yourself but installed it with your
operating system's package manager, you will have a global installation. This
allows system-wide access to the executable and library/documentation files.
To get a local installation, you can directly download the PicoLisp tarball,
and follow the instructions in the INSTALL file.
A local installation will not interfere in any way with the world outside its
directory. There is no need to touch any system locations, and you don't have to
be root to install it. Many different versions - or local modifications - of
PicoLisp can co-exist on a single machine.
Note that you are still free to have local installations along with a global
installation, and invoke them explicitly as desired.
Most examples in the following apply to a global installation.
When PicoLisp is invoked from the command line, an arbitrary number of
arguments may follow the command name.
By default, each argument is the name of a file to be executed by the
interpreter. If, however, the argument's first character is a hyphen
' A special case is if the last argument is a single ' As a convention, PicoLisp source files have the extension " Note that the PicoLisp executable itself does not expect or accept any
command line flags or options (except the ' The simplest and shortest invocation of PicoLisp does nothing, and exits
immediately by calling In interactive mode, the PicoLisp interpreter (see To start up the standard PicoLisp environment, several files should be
loaded. The most commonly used things are in "lib.l" and in a bunch of other
files, which are in turn loaded by "ext.l". Thus, a typical call would be:
The recommended way, however, is to call the "pil" shell script, which
includes "lib.l" and "ext.l". Given that your current project is loaded by some
file "myProject.l" and your startup function is For interactive development it is recommended to enable debugging mode, to
get the vi-style line editor, single-stepping, tracing and other debugging
utilities.
This is - in a local installation - equivalent to
In any case, the directory part of the first file name supplied (normally,
the path to "lib.l" as called by 'pil') is remembered internally as the
PicoLisp Home Directory. This path is later automatically substituted for
any leading " Instead of the default vi-style line editor, an emacs-style editor can be
used. It can be switched on permanently by calling the function
A single call is enough, because the style will be remembered in a file
"~/.pil/editor", and used in all subsequent PicoLisp sessions.
To switch back to 'vi' style, call In Lisp, each internal data structure has a well-defined external
representation in human-readable format. All kinds of data can be written to a
file, and restored later to their original form by reading that file.
In normal operation, the PicoLisp interpreter continuously executes an
infinite "read-eval-print loop". It reads one expression at a time, evaluates
it, and prints the result to the console. Any input into the system, like data
structures and function definitions, is done in a consistent way no matter
whether it is entered at the console or read from a file.
Comments can be embedded in the input stream with the hash A comment spanning several lines may be enclosed between Here is the I/O syntax for the individual PicoLisp data types (numbers,
symbols and lists) and for read-macros:
A number consists of an arbitrary number of digits (' Fixpoint numbers can be input by embedding a decimal point ' Thus, fixpoint input simply scales the number to an integer value
corresponding to the number of digits in Formatted output of scaled fixpoint values can be done with the The reader is able to recognize the individual symbol types from their
syntactic form. A symbol name should - of course - not look like a legal number
(see above).
In general, symbol names are case-sensitive. Besides for standard normal form, Output will always appear as Internal symbol names can consist of any printable (non-whitespace)
character, except for the following meta characters:
It is possible, though, to include these special characters into symbol names
by escaping them with a backslash ' The dot ' As a rule, anything not recognized by the reader as another data type will be
returned as an internal symbol.
A transient symbol is anything surrounded by double quotes ' Initially, a transient symbol's value is that symbol itself, so that it does
not need to be quoted for evaluation:
However, care must be taken when assigning a value to a transient symbol.
This may cause unexpected behavior:
The name of a transient symbol can contain any character except the
null-byte. A double quote character can be escaped with a backslash
' A backslash ' The index for transient symbols is cleared automatically before and after
A special case of transient symbols are anonymous symbols. These are
symbols without name (see External symbol names are surrounded by braces (' In both cases, the database file (and possibly the hypen) are omitted for the
first (default) file.
Lists are surrounded by parentheses (' PicoLisp has built-in support for reading and printing simple circular lists.
If the dot in a dotted-pair notation is immediately followed by a closing
parenthesis, it indicates that the CDR of the last cell points back to the
beginning of that list.
A similar result can be achieved with the function Read-macros in PicoLisp are special forms that are recognized by the reader,
and modify its behavior. Note that they take effect immediately while The most prominent read-macro in Lisp is the single quote character
" A comma ( A single backquote character " A tilde character When a tilde character is used to separate two symbol names (without
surrounding whitespace), the first is taken as a namespace to look up the second
(64-bit version only).
Reading Brackets (' Finally, reading the sequence ' PicoLisp tries to evaluate any expression encountered in the read-eval-print
loop. Basically, it does so by applying the following three rules:
For the third rule, however, things get a bit more involved. First - as a
special case - if the CAR of the list is a number, the whole list is returned as
it is:
This is not really a function call but just a convenience to avoid having to
quote simple data lists.
Otherwise, if the CAR is a symbol or a list, PicoLisp tries to obtain an
executable function from that, by either using the symbol's value, or by
evaluating the list.
What is an executable function? Or, said in another way, what can be applied
to a list of arguments, to result in a function call? A legal function in
PicoLisp is
A few examples should help to understand the practical consequences of these
rules. In the most common case, the CAR will be a symbol defined as a function,
like the Inspecting the VAL of The VAL of Other functions in turn are written as Lisp expressions:
The VAL of If the VAL of As we said above, if the CAR of the evaluated expression is not a symbol but
a list, that list is evaluated to obtain an executable function.
Here, the When an executable function is defined in Lisp itself, we call it a lambda expression. A lambda expression always has a
list of executable expressions as its CDR. The CAR, however, must be a either a
list of symbols, or a single symbol, and it controls the evaluation of the
arguments to the executable function according to the following rules:
In all cases, the return value is the result of the last expression in the
body.
Note that these forms can also be combined. For example, to evaluate only the
first two arguments, bind the results to Or, a single argument followed by a variable number of arguments:
In general, if more than the expected number of arguments is supplied to a
function, these extra arguments will be ignored. Missing arguments default to
Coroutines are independent execution contexts. They may have multiple entry
and exit points, and preserve their environment between invocations.
They are available only in the 64-bit version.
A coroutine is identified by a tag. This tag can be passed to other
functions, and (re)invoked as needed. In this regard coroutines are similar to
"continuations" in other languages.
When the tag goes out of scope while it is not actively running, the
coroutine will be garabage collected. In cases where this is desired, using a transient symbol for the tag is recommended.
A coroutine is created by calling When A coroutine is stopped and disposed when
Reentrant coroutines are not supported: A coroutine cannot resume itself
directly or indirectly.
Before using coroutines, make sure you have sufficient stack space, e.g. by
calling
Without that, the stack limit in Linux is typically 8 MB. This gives only
room - with a default coroutine stack segment size
of 1 MB - for the main segment (4 MB) plus four coroutines.
During the evaluation of an expression, the PicoLisp interpreter can be
interrupted at any time by hitting Hitting ENTER at that point will continue evaluation, while Other interrupts may be handled by When a runtime error occurs, execution is stopped and an error handler is
entered.
The error handler resets the I/O channels to the console, and displays the
location (if possible) and the reason of the error, followed by an error
message. That message is also stored in the global Errors can be caught with An arbitrary error can be thrown explicitly with In certain situations, the result of the last evaluation is stored in the VAL
of the symbol This happens in two - only superficially similar - situations:
Functions with controlling expressions are
case,
casq,
prog1,
prog2,
and the bodies of Functions with conditional expressions are
and,
cond,
do,
for,
if,
if2,
ifn,
loop,
nand,
nond,
nor,
not,
or,
state,
unless,
until,
when and
while.
In PicoLisp, it is legal to compare data items of arbitrary type. Any two
items are either
To demonstrate this, See also PicoLisp comes with built-in object oriented extensions. There seems to be a
common agreement upon three criteria for object orientation:
PicoLisp implements both objects and classes with symbols. Object-local data
are stored in the symbol's property list, while the code (methods) and links to
the superclasses are stored in the symbol's VAL (encapsulation).
In fact, there is no formal difference between objects and classes (except
that objects usually are anonymous symbols containing mostly local data, while
classes are named internal symbols with an emphasis on method definitions). At
any time, a class may be assigned its own local data (class variables), and any
object can receive individual method definitions in addition to (or overriding)
those inherited from its (super)classes.
PicoLisp supports multiple inheritance. The VAL of each object is a (possibly
empty) association list of message symbols and method bodies, concatenated with
a list of classes. When a message is sent to an object, it is searched in the
object's own method list, and then (with a left-to-right depth-first search) in
the tree of its classes and superclasses. The first method found is executed and
the search stops. The search may be explicitly continued with the Thus, which method is actually executed when a message is sent to an object
depends on the classes that the object is currently linked to (polymorphism). As
the method search is fully dynamic (late binding), an object's type (i.e. its
classes and method definitions) can be changed even at runtime!
While a method body is being executed, the global variable On the lowest level, a PicoLisp database is just a collection of external symbols. They reside in a database file, and are
dynamically swapped in and out of memory. Only one database can be open at a
time ( In addition, further external symbols can be specified to originate from
arbitrary sources via the Whenever an external symbol's value or property list is accessed, it will be
automatically fetched into memory, and can then be used like any other symbol.
Modifications will be written to disk only when In the typical case there will be multiple processes operating on the same
database. These processes should be all children of the same parent process,
which takes care of synchronizing read/write operations and heap contents. Then
a database transaction is normally initiated by calling A transaction proceeds through five phases:
The symbols in a database can be used to store arbitrary information
structures. In typical use, some symbols represent nodes of search trees, by
holding keys, values, and links to subtrees in their VAL's. Such a search tree
in the database is called index.
For the most part, other symbols in the database are objects derived from the
Entities depend on objects of the Relations are stored as properties in the entity classes, their methods are
invoked as daemons whenever property values in an entity are changed. When
defining an A declarative language is built on top of PicoLisp, that has the semantics of
Prolog, but uses the syntax of Lisp.
For an explanation of Prolog's declarative programming style, an introduction
like "Programming in Prolog" by Clocksin/Mellish (Springer-Verlag 1981) is
recommended.
Facts and rules can be declared with the and a rule ' As in Prolog, the difference between facts and rules is that the latter ones
have conditions, and usually contain variables.
A variable in Pilog is any symbol starting with an at-mark character
(" The cut operator of Prolog (usually written as an exclamation mark
( An interactive query can be done with the This will print all solutions, waiting for user input after each line. If a
non-empty line (not just a ENTER key, but for example a dot ( Pilog can be called from Lisp and vice versa:
It was necessary to introduce - and adhere to - a set of conventions for
PicoLisp symbol names. Because all (internal) symbols have a global scope (there
are no packages or name spaces), and each symbol can only have either a value or
function definition, it would otherwise be very easy to introduce name
conflicts. Besides this, source code readability is increased when the scope of
a symbol is indicated by its name.
These conventions are not hard-coded into the language, but should be so into
the head of the programmer. Here are the most commonly used ones:
For historical reasons, the global constant symbols For example, a local variable could easily overshadow a function definition:
Inside the body of Note that there are also some strict naming rules (as opposed to the
voluntary conventions) that are required by the corresponding kernel
functionalities, like:
With that, the last of the above conventions (local functions start with an
underscore) is not really necessary, because true local scope can be enforced
with transient symbols.
PicoLisp does not try very hard to be compatible with traditional Lisp
systems. If you are used to some other Lisp dialects, you may notice the
following differences:
The names of the symbols However, This section provides a reference manual for the kernel functions, and some
extensions. See the thematically grouped list of indexes below.
Though PicoLisp is a dynamically typed language (resolved at runtime, as
opposed to statically (compile-time) typed languages), many functions can only
accept and/or return a certain set of data types. For each function, the
expected argument types and return values are described with the following
abbreviations:
The primary data types:
Other (derived) data types
Arguments evaluated by the function (depending on the context) are quoted
(prefixed with the single quote character "
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
Other
The In the following example In the following example, the index entry for the item pointing to the
position (and, therefore, to the order) is cleared in case the order is deleted,
or this position is deleted from the order:
The optional hook can be supplied as the third argument. See also Messages to entity objects include
Another typical use case is inserting or removing See also The result specification may either be one of the
atoms
or nested lists of these atoms with size specifications to denote arrays and
structures, e.g.
Arguments can be
The number of fixpoint arguments is limited to six. For NaN or negative
infinity The C function may in turn call a function
which accepts a symbol name as the first argument, and up to 5 numbers.
Messages to relation objects include
'chart NIL
'((btn) (NIL "Name") (NIL "Father") (NIL "Mother") (NIL "Partner") (NIL "Occupation") (NIL "born"))
(do (cho)
(
NIL (
NIL NIL
'(NIL (NIL "Children") (NIL "born") (NIL "Father") (NIL "Mother"))
(do 4
(
NIL (
NIL (ht:Prin "No birth date for " (: obj nm)))
(gui '(+QueryChart) 12
'(goal
(quote
@Obj (: home obj)
@Dat (: home obj dat)
@Beg (- (: home obj dat) 36525)
@Fin (or (: home obj fin) (+ (: home obj dat) 36525))
(db dat +Person (@Beg . @Fin) @@)
(different @@ @Obj)
(^ @ (>= (get (-> @@) 'fin) (-> @Dat)))
(^ @ (<= (get (-> @@) 'dat) (-> @Fin))) ) )
7
'((This)
(list This (: job) (: dat) (: fin) (: pa) (: ma) (: mate)) ) )
(
NIL (pack (datStr (: obj dat)) " - " (datStr (: obj fin)))
(quote
(NIL "Name") (NIL "Occupation") (NIL "born") (NIL "died")
(NIL "Father") (NIL "Mother") (NIL "Partner") )
(do 12
(
NIL "Family Tree View")
(
NIL
(recur (This)
(when (try 'url> This 1)
(
NIL (mapc recurse (: kids))) ) ) ) ) ) )
### RUN ###
(de main ()
(pool "family/" *Dbs)
(unless (val *DB)
(put>
(set *DB (request '(+Man) 'nm "Adam"))
'mate
(request '(+Woman) 'nm "Eve") )
(commit) ) )
(de go ()
(rollback)
(server 8080 "!person") )
# vi:et:ts=3:sw=3
picolisp-3.1.5.2.orig/doc/family.tgz 0000644 0000000 0000000 00000033505 12265263724 015732 0 ustar root root Q =kl ye |_{jwRIߋD_"E( -=c$Fb I8n8 BFZE?
J!:QHGrvޏYrEnFֵ-m\|;bq* T.t bw),[6+Mm5G!V8
%!ؒb&grj+dc-!+,32Nbnh~w0~iϹ :&|;je# ܴ 9۪;5 \aG`lZ?ئr9F\n0{Pu;Tłޜ3Iٮ4>y8|NO b i.Q|%u j)۪ E] CT ә[VTE\;gb|k0.˕je̓M7zOOj#0ܕ#C$qbr_+)R!;[`}l,H-z7 R M-cb*
HV3ܴ0jp-UTMx*,ۇ2;d|2,[kGG#F8 .2hO\Sr Ӛob> ]iUbg`, MӨWeZ xRC.6jAfpEcȬeZ k6'
?F-nnrA qi}N"yAP,< HB: !p0! k! ?(` z=Ua XԍMz5C92l m4I(TpL0mdNō .mvMƲ
8^v
A $fש+"馴;]|Y !H 8my-Do6* O B 1BWtW[q
Œΰ. 6ZP'r9t ˥ BF'ɮ:dcel^l|17ZmqyADa2e 1UX"HA..w 9diKdz\ub(=ue ]BCx)..Π_k "xυ1vw%ܛUW-ppp0\ڙP=p{kxQj/W? Zbْ z[Et㙚(D١*+2W<8}Z qI`yv^Uj!g샀~`{(9>LO~
+}W/*Y|*! H^kPKEm\գ0-n6歶v,V?u|Vpz1=_+ OB0<Y #*(- ާ9?i_ޔF ;' }otH #l +.
k
ďsg}fѳVj"xYu% qe s|z*HYJ>̭|`s]c9l貱
P
wՓp6\U!y04l臿YtwcƀTM zכ[ tP t*ngns"U/{V~B6l@`/zːN
ko?}PQDXli{원 D, &.bPPN[" )
Ş/ˁ]fL1)=1'tpXp$O7p Lt&.t'UiN(V1ny.<Hזɠh~%zי|ثР/BE(;5gbx; tH7h!n4P0b4 QŶa6 bEbحiۥW( 7B>Pm2uZѮհi_fGV,B
bt*%%G0Fh%@ɧaC' f* Ŏ
wG+yPm3eB`2P
뚺UÖ Iƹ}=(>nHm-e2w1W+xO%Dg}S{*+)E(,,֕*еgҬZdȏ46-VDd%'+=Y JNV6]1sp9pL #,Rɚʤ&oJnx5%D̡-do' dѮה1fF{1;$V ]!ϼoFr^JP߇次 b.7d >~q|#UqixG\0C>~&N٥2
KDVZ%r*V |J`Uh㡝iG%MJJzt UfwT06nHK >ѬQEx#pe? !NR^:UB+rI4x"_ TEp uR7Ti|RP[Շ+p% ÕPy
W k$V[j]9P=Rf4E҈)#3F@"g--`Y S7x/<7C 234K,/C Ͳ2S!{T{VȢAwJ7@u`̻1 !_
Ǜ(n* E !߾!UPV9ݯ8O_ :!wmH)o_
ʊ [ _D@J {x`[$ZCtDnSQLZAxcO2必gpT#TCRPL{IǑ4E/E MkN:Mkkdg=*kf@Z*Tm tӦ6
Joshu: "Throw it out."
Monk: "But if there is nothing, how can I throw it out?"
Joshu: "Well, then carry it out."
(Zen koan)
PicoLisp Frequently Asked Questions
Why did you write yet another Lisp?
Who can use PicoLisp?
Forth.
What are the advantages over other Lisp systems?
Simplicity
A Clear Model
Orthogonality
: (let (N 7 L (7 7 7)) (inc 'N) (inc (cdr L)) (cons N L))
-> (8 7 8 7)
: (mapcar if '(T NIL T NIL) '(1 2 3 4) '(5 6 7 8))
-> (1 6 3 8)
Object System
super and extra.
Pragmatism
'(1 2
3) you can just write (1 2 3). This is possible because a
number never makes sense as a function name, and has to be checked at runtime
anyway.
quote function returns all
unevaluated arguments, instead of just the first one. This is both faster
(quote does not have to take the CAR of its argument list) and
smaller (a single cell instead of two). For example, 'A expands to
(quote . A) and '(A B C) expands to (quote A B
C).
@ is automatically
maintained as a local variable, and set implicitly in certain flow- and
logic-functions. This makes it often unnecessary to allocate and assign local
variables.
var locations (i.e. values of symbols and
CARs of cons pairs).
This in combination with the access functions
=:, : and ::.
link, yoke, chain and made functions in the make environment.
(let ((A 1) (B 2) C 3) ..) you write (let (A 1 B 2 C 3)
..), or just (let A 1 ..) if there is only a single
variable.
#) as a comment character is more adequate
today, and allows a clean hash-bang (#!) syntax for stand-alone
scripts.
select can be used in database
queries.
Persistent Symbols
set, put or get, the
garbage collector, and other parts of the interpreter know about them.
Application Server
Localization
How is the performance compared to other Lisp systems?
C or asm anyway. It is very
easy to write C functions in PicoLisp, either in the kernel, as
shared object libraries, or even inline in the Lisp code.
What means "interpreted"?
reading and printing interfaces).
: ((list (list 'X 'Y) (list '* 'X 'Y)) 3 4)
-> 12
(de incMe ()
(do 8
(printsp 0)
(inc (cdadr (cdadr incMe))) ) )
: (incMe)
0 1 2 3 4 5 6 7 -> 8
: (incMe)
8 9 10 11 12 13 14 15 -> 16
Is there (or will be in the future) a compiler available?
Is it portable?
Is PicoLisp a web server?
I cannot find the LAMBDA keyword in PicoLisp
quote function in any aspect, because there's no distinction
between code and data in PicoLisp, and quote returns the whole
(unevaluated) argument list. If you insist on it, you can define your own
lambda:
: (def 'lambda quote)
-> lambda
: ((lambda (X Y) (+ X Y)) 3 4)
-> 7
: (mapcar (lambda (X) (+ 1 X)) '(1 2 3 4 5))
-> (2 3 4 5 6)
Why do you use dynamic variable binding?
labels to extend the scope of variables beyond a single function.
(de recur recurse
(run (cdr recurse)) )
recur statically
and recurse dynamically. Usually it is very cumbersome to think up
a name for a function (like the following one) which is used only in a single
place. But with recur and recurse you can simply
write:
: (mapcar
'((N)
(recur (N)
(if (=0 N)
1
(* N (recurse (- N 1))) ) ) )
(1 2 3 4 5 6 7 8) )
-> (1 2 6 24 120 720 5040 40320)
recurse does not have to reside in
the same function as the corresponding recur. Can you implement
anonymous recursion so elegantly with lexical binding?
Are there no problems caused by dynamic binding?
static keyword in
C.
(de double (Var)
(set Var (* 2 (val Var))) )
(double 'X), but will
break if we call it as (double 'Var). Therefore, the correct
implementation of double should be:
(de double ("Var")
(set "Var" (* 2 (val "Var"))) )
double is defined that way in a separate source file, and/or
isolated via the ==== function, then
the symbol Var is locked into a private lexical context
and cannot conflict with other symbols.
Fortunately, these pitfalls do not occur so very often, and seem more likely in
utilities than in production code, so that they can be easily encapsulated.
But with dynamic binding I cannot implement closures!
bind or job, which dynamically manage statically scoped
environments.
(de curry Args
(list (car Args)
(list 'list
(lit (cadr Args))
(list 'cons ''job
(list 'cons
(list 'lit (list 'env (lit (car Args))))
(lit (cddr Args)) ) ) ) ) )
: ((curry (X) (N) (* X N)) 3)
-> ((N) (job '((X . 3)) (* X N)))
: (((curry (X) (N) (* X N)) 3) 4)
-> 12
(de curry Args
(list
(cadr Args)
(list 'fill
(lit (cons (car Args) (cddr Args)))
(lit (cadr Args)) ) ) )
: ((curry (X) (N) (* X N)) 3)
-> ((X) (* X 3))
curry
function is simpler and more pragmatic. It combines both strategies (to use
job, or to substitute), deciding at runtime what kind of function
to build.
Do you have macros?
DO* macro, written as a function:
(de do* "Args"
(bind (mapcar car (car "Args"))
(for "A" (car "Args")
(set (car "A") (eval (cadr "A"))) )
(until (eval (caadr "Args"))
(run (cddr "Args"))
(for "A" (car "Args")
(and (cddr "A") (set (car "A") (run @))) ) )
(run (cdadr "Args")) ) )
Why are there no strings?
(prinl "Good morning!")
"Good morning!" to its
translation will change the program's output at runtime.
loading the current source file), they are
shared within the same source and occupy that space only once, even if they
occur multiple times within the same file.
What about arrays?
How to do floating point arithmetics?
native, inline-C code, and/or by
loading the "@lib/math.l" library.
What happens when I locally bind a symbol which has a function definition?
;-)
(de findCar (Car List)
(when (member Car (cdr List))
(list Car (car List)) ) )
Would it make sense to build PicoLisp in hardware?
set, val, if
and while, which are written in C or assembly language
now, would be implemented in microcode. Plus a few I/O functions for hardware
access. EVAL itself would be a microcode subroutine.
I get a segfault if I ...
There is another example in the Evaluation section of the reference manual.
: (setq foo 1)
-> 1
: (foo)
Segmentation fault
lint. It will detect many potential errors.
And, most of these errors are avoided by following the PicoLisp naming conventions.
Where can I ask questions?
NIL "Hello world")
"This is PicoLisp" )
picolisp-3.1.5.2.orig/doc/index.html 0000644 0000000 0000000 00000005637 12265263724 015725 0 ustar root root
Native C Calls
native function - possibly with the help of
the struct and lisp functions. It applies only to the 64-bit
version of PicoLisp.
Overview
native calls a C function in a shared library. It tries to
native is the Lisp representation of
the C function's return value. Further values, returned by reference from the C
function, are available in Lisp variables (symbol values).
struct is a helper function, which can be used to manipulate C
data structures in memory. It may take a scalar (a numeric representation of a C
value) to convert it to a Lisp item, or (more typically) a pointer to a memory
area to build and extract data structures. lisp allows you to
install callback functions, callable from C code, written in Lisp.
native doesn't have (and
doesn't require) a priory knowledge about the library, the function or the
involved data. No need to write any glue code, interfaces or include files. All
functions can even be called interactively from the REPL.
Syntax
native are
void fun(void);
(native "lib.so" "fun")
Libraries
native specifies the library. It is either
the name of a library (a symbol), or the handle of a previously
found library (a number).
"@" can be passed for the
library name. It then refers to the current main program (instead of an external
library), and can be used for standard functions like "malloc" or
"printf".
native uses dlopen(3) internally to find and open
the library, and to obtain the handle. If the name contains a slash ('/'), then
it is interpreted as a (relative or absolute) pathname. Otherwise, the dynamic
linker searches for the library according to the system's environment and
directories. See the man page of dlopen(3) for further details.
native automatically caches
the handle of the found library in the value of that symbol. The most natural
way is to pass the library name as a transient
symbol ("lib.so" above): The initial value of a transient symbol is
that symbol itself, so that native receives the library name upon
the first call. After successfully finding and opening the library,
native stores the handle of that library in the value of the passed
symbol ("lib.so"). As native evaluates its arguments
in the normal way, subsequent calls within the same transient scope will receive
the numeric value (the handle), and don't need to open and search the library
again.
Functions
native stores the function pointer in its value, so that
subsequent calls evaluate to that pointer, and native can directly
jump to the function.
native uses dlsym(3) internally to obtain the
function pointer. See the man page of dlsym(3) for further details.
==== function), each library will be opened -
and each function searched - only once.
(native "lib.so" "fun1")
(native "lib.so" "fun2")
(native "lib.so" "fun3")
"fun1" was called, "lib.so" will be open, and
won't be re-opened for "fun2" and "fun3". Consider
the definition of helper functions:
(de fun1 ()
(native "lib.so" "fun1") )
(de fun2 ()
(native "lib.so" "fun2") )
(de fun3 ()
(native "lib.so" "fun3") )
fun1, fun2 or fun3
was called, the symbol "lib.so" will hold the library handle. And
each function function "fun1", "fun2" and
"fun3" will be searched only when called the first time.
Return Value
native specifies the return
value. A C function can return many types of values, like integer or floating
point numbers, string pointers, or pointers to structures which in turn consist
of those types, and even other structures or pointers to structures.
native tries to cover most of them.
native
how to extract the proper value.
Primitive Types
NIL like in
the examples so far. This means that either the C function returns
void, or that we are not interested in the value. The return value
of native will be NIL in that case.
B,
I or N, an integer number is returned, by interpreting
the result as a char (8 bit unsigned byte), int (32
bit signed integer), or long number (64 bit signed integer),
respectively. Other (signed or unsigned numbers, and of different sizes) can be
produced from these types with logical and arithmetic operations if necessary.
C, the result is
interpreted as a 16 bit number, and a single-char transient symbol (string) is
returned.
S tells native to interpret the
result as a pointer to a C string (null terminated), and to return a transient
symbol (string).
double (if the number is positive) or
float (if the number is negative) to a scaled fixpoint number.
(native "lib.so" "fun" 'I) # int fun(void);
(native "lib.so" "fun" 'N) # long fun(void);
(native "lib.so" "fun" 'N) # void *fun(void);
(native "lib.so" "fun" 'S) # char *fun(void);
(native "lib.so" "fun" 1.0) # double fun(void);
Arrays and Structures
(native "lib.so" "fun" '(I . 8)) # int *fun(void); // 8 integers
(native "lib.so" "fun" '(B . 16)) # unsigned char *fun(void); // 16 bytes
(native "lib.so" "fun" '(I I)) # struct {int i; int j;} *fun(void);
(native "lib.so" "fun" '(I . 4)) # struct {int i[4];} *fun(void);
(native "lib.so" "fun" '(I (B . 4))) # struct {
# int i;
# unsigned char c[4];
# } *fun(void);
(native "lib.so" "fun" # struct {
'(((B . 4) I) (S . 12) (N . 8)) ) # struct {unsigned char c[4]; int i;}
# char *names[12];
# long num[8];
# } *fun(void);
N pattern, which can
then be passed to struct for further
extraction.
Arguments
native specify
the arguments to the C function.
Primitive Types
char,
short, int or long) can be passed as they
are: As numbers.
(native "lib.so" "fun" NIL 123) # void fun(int);
(native "lib.so" "fun" NIL 1 2 3) # void fun(int, long, short);
native allocates
memory for each string (with strdup(3)), passes the pointer to the
C function, and releases the memory (with free(3)) when done.
(native "lib.so" "fun" NIL "abc") # void fun(char*);
(native "lib.so" "fun" NIL 3 "def") # void fun(int, char*);
S specification).
(native "lib.so" "fun" 'S "abc") # char *fun(char*);
NIL as an argument passes an empty
string ("", which also reads as NIL in PicoLisp) to the C function.
Physically, this is a pointer to a NULL-byte, and is not a NULL-pointer.
Be sure to pass 0 (the number zero) if a NULL-pointer is desired.
double, otherwise as a float.
(native "lib.so" "fun" NIL # void fun(double, float);
(12.3 . 1.0) (4.56 . -1.0) )
Arrays and Structures
native allocates memory for each array or structure (with
malloc(3)), passes the pointer to the C function, and releases the
memory (with free(3)) when done.
NIL (then it is an
input-only argument). Otherwise, it should be a variable which receives the
returned structure data.
void fun(int *i) {
*i = 123;
}
native with a variable X in the CAR of the
argument specification, a size of 4 (i.e. sizeof(int)), and
I for the result specification. The stored value is then available
in the variable X:
: (native "lib.so" "fun" NIL '(X (4 . I)))
-> NIL
: X
-> 123
: (native "lib.so" "fun" NIL '(NIL (20) . 0))
: (native "lib.so" "fun" NIL '(NIL (20) 1 2 3 4 . 0))
X:
: (native "lib.so" "fun" NIL '(X (20 B . 20) 1 2 3 4 . 0))
typedef struct value {
int x, y;
double a, b, c;
int z;
char nm[4];
} value;
void fun(value *val) {
printf("%d %d\n", val->x, val->y);
val->x = 3;
val->y = 4;
strcpy(val->nm, "OK");
}
V, with two integers (I . 2), three doubles
(100 . 3) with a scale of 2 (1.0 = 100), another integer
I and four characters (C . 2). If the structure gets
initialized with two integers 7 and 6, three doubles 0.11, 0.22 and 0.33, and
another integer 5 while the rest of the 40 bytes is cleared to zero
: (native "lib.so" "fun" NIL
'(V (40 (I . 2) (100 . 3) I (C . 4)) -7 -6 (100 11 22 33) -5 . 0) )
V will contain the
returned list
((3 4) (11 22 33) 5 ("O" "K" NIL NIL))
Memory Management
native implicitly allocates and releases memory for strings, arrays
and structures.
read(2)
directly, to fetch a 4-byte integer from a given file descriptor. This could be
done with the following C function:
int read4bytes(int fd) {
char buf[4];
read(fd, buf, 4);
return *(int*)buf;
}
buf is an automatic variable, allocated on the stack, which
disappears when the function returns. A corresponding native call
would be:
(native "@" "read" 'N Fd '(Buf (4 . I)) 4)
(Buf (4 . I)) says that a space of 4
bytes should be allocated and passed to read, then an integer
I returned in the variable Buf (the return value of
native itself is the number returned by read). The
memory space is released after that.
"@" for the library here, as read
resides in the main program.)
native:
(native "@" "read" 'N Fd '(Buf (4 B . 4)) 4)
(B . 4) (a list of 4 bytes)
instead of I (a single integer) for the result specification (see the Arrays and Structures section).
void copy4bytes(int fd1, int fd2) {
char buf[4];
read(fd1, buf, 4);
write(fd2, buf, 4);
}
buf is an automatic variable. It is passed to both
read and write. A direct translation would be:
(native "@" "read" 'N Fd '(Buf (4 B . 4)) 4)
(native "@" "write" 'N Fd (cons NIL (4) Buf) 4)
read returns a list of four bytes in
Buf. The call to cons builds the structure
(NIL (4) 1 2 3 4)
read returned 1, 2, 3 and 4). Then this structure is
passed to write.
read and released after that, then
allocated and released again for write. Also, the bytes are
converted to a list to be stored in Buf, then that list is extended
for the structure argument to write, and converted again back to
the raw byte array. The data in the list itself are never used.
(let Buf (native "@" "malloc" 'N 4) # Allocate memory
(native "@" "read" 'N Fd Buf 4) # (Possibly repeat this several times)
(native "@" "write" 'N Fd Buf 4)
(native "@" "free" NIL Buf) ) # Release memory
Fast Fourier Transform
#include <fftw3.h>
...
{
fftw_complex *in, *out;
fftw_plan p;
...
in = (fftw_complex*) fftw_malloc(sizeof(fftw_complex) * N);
out = (fftw_complex*) fftw_malloc(sizeof(fftw_complex) * N);
p = fftw_plan_dft_1d(N, in, out, FFTW_FORWARD, FFTW_ESTIMATE);
...
fftw_execute(p); /* repeat as needed */
...
fftw_destroy_plan(p);
fftw_free(in); fftw_free(out);
}
(load "@lib/math.l")
(de FFTW_FORWARD . -1)
(de FFTW_ESTIMATE . 64)
(de fft (Lst)
(let
(Len (length Lst)
In (native "libfftw3.so" "fftw_malloc" 'N (* Len 16))
Out (native "libfftw3.so" "fftw_malloc" 'N (* Len 16))
P (native "libfftw3.so" "fftw_plan_dft_1d" 'N
Len In Out FFTW_FORWARD FFTW_ESTIMATE ) )
(struct In NIL (cons 1.0 (apply append Lst)))
(native "libfftw3.so" "fftw_execute" NIL P)
(prog1 (struct Out (make (do Len (link (1.0 . 2)))))
(native "libfftw3.so" "fftw_destroy_plan" NIL P)
(native "libfftw3.so" "fftw_free" NIL Out)
(native "libfftw3.so" "fftw_free" NIL In) ) ) )
Lst is passed as a list
of complex numbers, each as a list of two numbers for the real and imaginary
part, like
(fft '((1.0 0) (1.0 0) (1.0 0) (1.0 0) (0 0) (0 0) (0 0) (0 0)))
struct is called to store the argument list
in the In structure as a list of double numbers (according to the
1.0 initialization item). Then
fftw_execute is called, and struct is called again to
retrieve the result from Out and return it from fft
via the prog1. Finally, all memory is
released.
Constant Data
native) are constant during the lifetime of a program, it makes
sense to allocate them only once, before their first use. A typical candidate is
the format string of a printf call. Consider a function which
prints a floating point number in scientific notation:
(load "@lib/math.l")
: (de prf (Flt)
(native "@" "printf" NIL "%e^J" (cons Flt 1.0)) )
-> prf
: (prf (exp 12.3))
2.196960e+05
"%e^J" will be converted from
a Lisp symbol to a C string with strdup - and then thrown away - on
each call to prf, we might as well perform a little optimization
and delegate this conversion to the program load time:
: (de prf (Flt)
(native "@" "printf" NIL `(native "@" "strdup" 'N "%e^J") (cons Flt 1.0)) )
-> prf
: (prf (exp 12.3))
2.196960e+05
prf function, we see that it now contains the
pointer to the allocated string memory:
: (pp 'prf)
(de prf (Flt)
(native "@" "printf" NIL 24662032 (cons Flt 1000000)) )
-> prf
printf directly, without any
further conversion or memory management.
Callbacks
Call by Name
long lisp(char*,long,long,long,long,long);
lisp from C:
long n = lisp("myLispFun", a, b, 0, 0, 0);
long). On the C side, appropriate casts or a
adapted prototype should be used. It is then up to the called Lisp function to
prepare and/or extract the proper data with struct and memory management operations.
Function Pointer
lisp (not to confuse with the C-level function
with the same name in the previous section). No C source code access is
required.
lisp returns a function pointer, which can be passed to C
functions via native. When this function pointer is dereferenced
and called from the C code, the corresponding Lisp function is invoked. Here,
too, only five numeric arguments and a numeric return value can be used, and
other data types must be handled by the Lisp function with struct and memory management operations.
"@lib/openGl.l". The
following function mouseFunc takes a Lisp function, installs it
under the tag mouseFunc (any other tag would be all right too) as a
callback, and passes the resulting function pointer to the OpenGL
glutMouseFunc() function, to set it as a callback for the current
window:
(de mouseFunc (Fun)
(native `*GlutLib "glutMouseFunc" NIL (lisp 'mouseFunc Fun)) )
*GlutLib holds the library
"/usr/lib/libglut.so". The backquote (`) is important
here, so that the transient symbol with the library name (and not the global
*GlutLib) is evaluated by native, resulting in the
proper library handle at runtime).
mouseFunc to install a
function
(mouseFunc
'((Btn State X Y)
(do-something-with Btn State X Y) ) )
not when there is nothing left to add
but when there is nothing left to take away
(Antoine de Saint-Exupéry)
The PicoLisp Reference
Introduction
The PicoLisp Machine
The Cell
+-----+-----+
| CAR | CDR |
+-----+-----+
xxxxxxxxxxxxxxxxxxxxxxxxxxxxx000
x' means "don't care"). For the individual data types, the
pointer is adjusted to point to other parts of a cell, in effect setting some of
the lower three bits to non-zero values. These bits are then used by the
interpreter to determine the data type.
Data Types
NIL.
cell
|
+--------+--------+
| | |
Number Symbol Pair
|
|
+--------+--------+--------+
| | | |
NIL Internal Transient External
Numbers
Number
|
V
+-----+-----+
| DIG | | |
+-----+--+--+
|
V
+-----+-----+
| DIG | | |
+-----+--+--+
|
V
...
xxxxxxxxxxxxxxxxxxxxxxxxxxxxx010
Symbols
Symbol
|
V
+-----+-----+
| / | VAL |
+-----+-----+
NIL, as indicated
by the '/' character).
xxxxxxxxxxxxxxxxxxxxxxxxxxxxx100
"abc" has three properties: A KEY/VAL pair, a cell with
only a KEY, and another KEY/VAL pair.
Symbol
|
V
+-----+-----+
| | | VAL |
+--+--+-----+
| tail
|
V name
+-----+-----+ +-----+-----+ +-----+-----+ +-----+-----+
| | | ---+---> | KEY | ---+---> | | | ---+---> |'cba'| / |
+--+--+-----+ +-----+-----+ +--+--+-----+ +-----+-----+
| |
V V
+-----+-----+ +-----+-----+
| VAL | KEY | | VAL | KEY |
+-----+-----+ +-----+-----+
T), or a cons pair with
the property key in its CDR and the property value in its CAR. In both cases,
the key should be a symbol, because searches in the property list are performed
using pointer comparisons.
NIL, internal, transient and external symbols.
NIL
NIL is a special symbol which exists exactly once in the whole
system. It is used
NIL has a special structure:
NIL: /
|
V
+-----+-----+-----+-----+
| / | / | / | / |
+-----+--+--+-----+-----+
NIL's dual nature both as a
symbol and as a list:
NIL for its VAL, and be without
properties
NIL should give NIL both for
its CAR and for its CDR
Internal Symbols
NIL.
Transient Symbols
static identifiers in the C language family)
box or new functions.
External Symbols
*Ext), and are loaded into memory -
and written back to the file - dynamically as needed, and transparently to the
programmer. They are kept in memory ("cached") as long as they are accessible
("referred to") from other parts of the program, or when they were modified but
not yet written to the database file (by commit).
NIL, unless otherwise
specified at creation time.
Lists
|
V
+-----+-----+
| any | | |
+-----+--+--+
|
V
+-----+-----+
| any | | |
+-----+--+--+
|
V
...
NIL. If, however, the CDR of
the last cell points to an atom, that cell is called a "dotted pair" (because of
its I/O syntax with a dot '.' between the two values).
Memory Management
Programming Environment
Installation
Invocation
-', then the rest of that argument is taken as a Lisp function
call (without the surrounding parentheses), and a hyphen by itself as an
argument stops evaluation of the rest of the command line (it may be processed
later using the argv and opt functions). This whole mechanism corresponds
to calling (load T).
+'. This
will switch on debug mode (the *Dbg
global variable) and discard the '+'.
.l".
+', see above). They are
reserved for application programs.
bye:
$ picolisp -bye
$
load) will also exit when Ctrl-D
is entered:
$ picolisp
: $ # Typed Ctrl-D
$ picolisp lib.l ext.l
main, your
invocation would look like:
$ pil myProject.l -main
$ pil myProject.l -main +
$ ./pil myProject.l -main +
@" character in file name arguments to I/O functions
(see path).
(em) (i.e. without arguments), or by passing -em on
the command line:
$ pil -em +
:
(vi), use the
-vi command line option, or simply remove "~/.pil/editor".
Input/Output
#
character. Everything up to the end of that line will be ignored by the reader.
: (* 1 2 3) # This is a comment
-> 6
#{ and
}#.
Numbers
0' through
'9'), optionally preceded by a sign character ('+' or
'-'). Legal number input is:
: 7
-> 7
: -12345678901245678901234567890
-> -12345678901245678901234567890
.',
and setting the global variable *Scl
appropriately:
: *Scl
-> 0
: 123.45
-> 123
: 456.78
-> 457
: (setq *Scl 3)
-> 3
: 123.45
-> 123450
: 456.78
-> 456780
*Scl.
format and round functions:
: (format 1234567890 2)
-> "12345678.90"
: (format 1234567890 2 "." ",")
-> "12,345,678.90"
Symbols
car is not the same
as CAR.
NIL
NIL is also recognized as
(), [] or "".
: NIL
-> NIL
: ()
-> NIL
: ""
-> NIL
NIL.
Internal Symbols
" ' ( ) , [ ] ` ~ { }
\'.
.' has a dual nature. It is a meta character when
standing alone, denoting a dotted pair, but can otherwise
be used in symbol names.
Transient Symbols
"'.
With that, it looks - and can be used - like a string constant in other
languages. However, it is a real symbol, and may be assigned a value or a
function definition, and properties.
: "This is a string"
-> "This is a string"
: (setq "This is a string" 12345)
-> 12345
: "This is a string"
-> 12345
\', and a backslash itself has to be escaped with another
backslash. Control characters can be written with a preceding hat
'^' character.
: "We^Ird\\Str\"ing"
-> "We^Ird\\Str\"ing"
: (chop @)
-> ("W" "e" "^I" "r" "d" "\\" "S" "t" "r" "\"" "i" "n" "g")
\' in a transient symbol name at the end of a line
discards the newline, and continues the name in the next line. In that case, all
leading spaces and tabs in that line are discarded, to allow proper source code
indentation.
: "abc\
def"
-> "abcdef"
loading a source file, or it can be
reset explicitly with the ====
function. With that mechanism, it is possible to create symbols with a local
access scope, not accessible from other parts of the program.
box, box? or new). They print as a dollar sign
($) followed by a decimal digit string (actually their machine
address).
External Symbols
{' and
'}'). The characters of the symbol's name itself identify the
physical location of the external object. This is
0' through '9',
':', ';', 'A' through 'Z'
and 'a' through 'z').
@' is zero,
'A' is 1 and 'O' is 15 (from "alpha" to "omega")),
immediately followed (without a hyphen) the starting block in octal
('0' through '7').
Lists
(' and ')').
(A) is a list consisting of a single cell, with the symbol
A in its CAR, and NIL in its CDR.
(A B C) is a list consisting of three cells, with the symbols
A, B and C respectively in their CAR, and
NIL in the last cell's CDR.
(A . B) is a "dotted pair", a list
consisting of a single cell, with the symbol A in its CAR, and
B in its CDR.
: (let L '(a b c) (conc L L))
-> (a b c .)
: (cdr '(a b c .))
-> (b c a .)
: (cddddr '(a b c .))
-> (b c a .)
circ. Such lists must be used with care,
because many functions won't terminate or will crash when given such a list.
Read-Macros
reading an expression, and are not seen by the
eval in the main loop.
'", which expands to a call of the quote function. Note that the single quote
character is also printed instead of the full function name.
: '(a b c)
-> (a b c)
: '(quote . a)
-> 'a
: (cons 'quote 'a) # (quote . a)
-> 'a
: (list 'quote 'a) # (quote a)
-> '(a)
,) will cause the reader to collect the following data
item into an idx tree in the global
variable *Uni, and to return a
previously inserted equal item if present. This makes it possible to create a
unique list of references to data which do normally not follow the rules of
pointer equality. If the value of *Uni is T, the
comma read macro mechanism is disabled.
`" will cause the reader to
evaluate the following expression, and return the result.
: '(a `(+ 1 2 3) z)
-> (a 6 z)
~ inside a list will cause the reader to
evaluate the following expression, and (destructively) splice the result into
the list.
: '(a b c ~(list 'd 'e 'f) g h i)
-> (a b c d e f g h i)
: 'libA~foo # Look up 'foo' in namespace 'libA'
-> "foo" # "foo" is not interned in the current namespace
libA~foo is equivalent to switching the current
namespace to libA (with symbols), reading the symbol
foo, and then switching back to the original namespace.
[' and ']') can be used as super
parentheses. A closing bracket will match the innermost opening bracket, or all
currently open parentheses.
: '(a (b (c (d]
-> (a (b (c (d))))
: '(a (b [c (d]))
-> (a (b (c (d))))
{}' will result in a new
anonymous symbol with value NIL, equivalent to a call to box without arguments.
: '({} {} {})
-> ($134599965 $134599967 $134599969)
: (mapcar val @)
-> (NIL NIL NIL)
Evaluation
: 1234
-> 1234 # Number evaluates to itself
: *Pid
-> 22972 # Symbol evaluates to its VAL
: (+ 1 2 3)
-> 6 # List is evaluated as a function call
: (1 2 3 4 5 6)
-> (1 2 3 4 5 6)
quote) or evaluate only some of their arguments (e.g.
setq).
* in:
: (* 1 2 3) # Call the function '*'
-> 6
* gives
: * # Get the VAL of the symbol '*'
-> 67318096
* is a number. In fact, it is the numeric
representation of a C-function pointer, i.e. a pointer to executable code. This
is the case for all built-in functions of PicoLisp.
: (de foo (X Y) # Define the function 'foo'
(* (+ X Y) (+ X Y)) )
-> foo
: (foo 2 3) # Call the function 'foo'
-> 25
: foo # Get the VAL of the symbol 'foo'
-> ((X Y) (* (+ X Y) (+ X Y)))
foo is a list. It is the list that was assigned to
foo with the de function. It would be perfectly legal
to use setq instead of de:
: (setq foo '((X Y) (* (+ X Y) (+ X Y))))
-> ((X Y) (* (+ X Y) (+ X Y)))
: (foo 2 3)
-> 25
foo were another symbol, that symbol's VAL would
be used instead to search for an executable function.
: ((intern (pack "c" "a" "r")) (1 2 3))
-> 1
intern function returns the symbol car
whose VAL is used then. It is also legal, though quite dangerous, to use the code-pointer directly:
: *
-> 67318096
: ((* 2 33659048) 1 2 3)
-> 6
: ((quote . 67318096) 1 2 3)
-> 6
: ((quote . 1234) (1 2 3))
Segmentation fault
@
args,
next, arg and rest functions. This allows to define functions
with a variable number of evaluated arguments.
: (de foo (X Y Z) # CAR is a list of symbols
(list X Y Z) ) # Return a list of all arguments
-> foo
: (foo (+ 1 2) (+ 3 4) (+ 5 6))
-> (3 7 11) # all arguments are evaluated
: (de foo X # CAR is a single symbol
X ) # Return the argument
-> foo
: (foo (+ 1 2) (+ 3 4) (+ 5 6))
-> ((+ 1 2) (+ 3 4) (+ 5 6)) # the whole unevaluated list is returned
: (de foo @ # CAR is the symbol '@'
(list (next) (next) (next)) ) # Return the first three arguments
-> foo
: (foo (+ 1 2) (+ 3 4) (+ 5 6))
-> (3 7 11) # all arguments are evaluated
X and Y, and
bind all other arguments (unevaluated) to Z:
: (de foo (X Y . Z) # CAR is a list with a dotted-pair tail
(list X Y Z) ) # Return a list of all arguments
-> foo
: (foo (+ 1 2) (+ 3 4) (+ 5 6))
-> (3 7 ((+ 5 6))) # Only the first two arguments are evaluated
: (de foo (X . @) # CAR is a dotted-pair with '@'
(println X) # print the first evaluated argument
(while (args) # while there are more arguments
(println (next)) ) ) # print the next one
-> foo
: (foo (+ 1 2) (+ 3 4) (+ 5 6))
3 # X
7 # next argument
11 # and the last argument
-> 11
NIL.
Coroutines
co.
Its prg body will be executed, and unless yield is called at some point, the coroutine
will "fall off" at the end and disappear.
yield is called, control is
either transferred back to the caller, or to some other - explicitly specified,
and already running - coroutine.
co with
that tag but without a prg body
throw into another (co)routine
environment is executed
$ ulimit -s unlimited
Interrupt
Ctrl-C. It will then enter the
breakpoint routine, as if ! were called.
(quit) will abort evaluation and return the
interpreter to the top level. See also debug, e, ^ and
*Dbg
alarm, sigio, *Hup and *Sig[12].
Error Handling
*Msg, and the location of the error in ^. If the VAL of the global *Err is non-NIL it is executed as
a prg body. If the standard input is from a terminal, a
read-eval-print loop (with a question mark "?" as prompt) is
entered (the loop is exited when an empty line is input). Then all pending
finally expressions are executed,
all variable bindings restored, and all files closed. If the standard input is
not from a terminal, the interpreter terminates. Otherwise it is reset to its
top-level state.
: (de foo (A B) (badFoo A B)) # 'foo' calls an undefined symbol
-> foo
: (foo 3 4) # Call 'foo'
!? (badFoo A B) # Error handler entered
badFoo -- Undefined
? A # Inspect 'A'
-> 3
? B # Inspect 'B'
-> 4
? # Empty line: Exit
:
catch,
if a list of substrings of possible error messages is supplied for the first
argument. In such a case, the matching substring (or the whole error message if
the substring is NIL) is returned.
quit.
@ Result
@. This can be very convenient, because it often
makes the assignment to temporary variables unnecessary.
load
@@@, @@ and @, in that
order (i.e the latest result is in @).
: (+ 1 2 3)
-> 6
: (/ 128 4)
-> 32
: (- @ @@) # Subtract the last two results
-> 26
NIL results of their conditional expression - in
@.
: (while (read) (println 'got: @))
abc # User input
got: abc # print result
123 # User input
got: 123 # print result
NIL
-> 123
: (setq L (1 2 3 4 5 1 2 3 4 5))
-> (1 2 3 4 5 1 2 3 4 5)
: (and (member 3 L) (member 3 (cdr @)) (set @ 999))
-> 999
: L
-> (1 2 3 4 5 1 2 999 4 5)
*Run tasks.
@ is generally local to functions and methods, its value is
automatically saved upon function entry and restored at exit.
Comparing
NIL is always less than anything else, and T is always
greater than anything else.
sort a list of
mixed data types:
: (sort '("abc" T (d e f) NIL 123 DEF))
-> (NIL 123 DEF "abc" (d e f) T)
max, min, rank, <,
=, > etc.
OO Concepts
extra and super functions.
This is set to the current object, allowing
the use of the short-cut property functions =:, :
and ::.
Database
pool).
*Ext
mechanism.
commit is called. Alternatively, all
modifications since the last call to commit can be discarded by
calling rollback.
Transactions
(dbSync), and closed by calling (commit 'upd). Short transactions, involving
only a single DB operation, are available in functions like new! and methods like put!> (by convention with an
exclamation mark), which implicitly call (dbSync) and (commit
'upd) themselves.
dbSync waits to get a lock on the root object *DB. Other processes continue reading and
writing meanwhile.
dbSync calls sync to synchronize with changes from other
processes. We hold the shared lock, but other processes may continue reading.
put>, set>, lose> etc. We -
and also other processes - can still read the DB.
(commit 'upd).
commit obtains an exclusive lock (no more read operations by other
processes), writes an optional transaction log, and then all modified symbols.
As upd is passed to 'commit', other
processes synchronize with these changes.
Entities / Relations
+Entity class.
+relation class hierarchy.
Relation-objects manage the property values of entities, they define the
application database model and are responsible for the integrity of mutual
object references and index trees.
+Entity class, relations are defined - in addition to
the method definitions of a normal class - with the rel function. Predefined relation classes
include
+Bool
T or NIL
+Any
Pilog (PicoLisp Prolog)
be function. For example, a Prolog fact
'likes(john,mary).' is written in Pilog as:
(be likes (John Mary))
likes(john,X) :- likes(X,wine), likes(X,food).' is
in Pilog:
(be likes (John @X) (likes @X wine) (likes @X food))
@"). The symbol @ itself can be used as an anonymous
variable: It will match during unification, but will not be bound to the matched
values.
!)) is the symbol T in Pilog.
? function:
(? (likes John @X))
.)
followed by ENTER) is typed, it will terminate.
goal (prepare a query from Lisp data) and
prove (return an association list of
successful bindings), and the application level functions pilog and solve.
-> function.
Naming Conventions
*"
_"
+", where the first letter
>"
T and
NIL do not obey these rules, and are written in upper case.
: (de max-speed (car)
(.. (get car 'speeds) ..) )
-> max-speed
max-speed (and all other functions called
during that execution) the kernel function car is redefined to some
other value, and will surely crash if something like (car Lst) is
executed. Instead, it is safe to write:
: (de max-speed (Car) # 'Car' with upper case first letter
(.. (get Car 'speeds) ..) )
-> max-speed
@" (see match
and fill) lib:sym"
Breaking Traditions
CAR and car are different symbols,
which was not the case in traditional Lisp systems.
QUOTE
QUOTE function returns its
first unevaluated argument. In PicoLisp, on the other hand,
quote returns all (unevaluated) argument(s).
LAMBDA
LAMBDA function, in some way at the heart of traditional
Lisp, is completely missing (and quote is used instead).
PROG
PROG function of traditional Lisp, with its GOTO and ENTER
functionality, is also missing. PicoLisp's prog function is just a
simple sequencer (as PROGN in some Lisps).
Bugs
T and NIL violate the naming conventions. They are global symbols, and should
therefore start with an asterisk "*". It is too easy to bind them
to some other value by mistake:
(de foo (R S T)
...
lint will issue a warning
in such a case.
Function Reference
num - Number
sym - Symbol
lst - List
any - Anything: Any primary data type
flg - Flag: Boolean value (NIL or non-NIL)
cnt - A count or a small number
dat - Date: Days, starting first of March of the year 0 A.D.
tim - Time: Seconds since midnight
obj - Object/Class: A symbol with methods and/or classes
var - Variable: Either a symbol or a cons pair
exe - Executable: A list as executable expression (eval)
prg - Prog-Body: A list of executable expressions (run)
fun - Function: Either a number (code-pointer), a symbol (message) or a list (lambda)
msg - Message: A symbol sent to an object (to invoke a method)
cls - Class: A symbol defined as an object's class
typ - Type: A list of cls symbols
pat - Pattern: A symbol whose name starts with an at-mark "@"
pid - Process ID: A number, the ID of a Unix process
tree - Database index tree specification
hook - Database hook object
'").
new
sym
str
char
name
sp?
pat?
fun?
all
symbols
local
import
intern
extern
====
qsym
loc
box?
str?
ext?
touch
zap
length
size
format
chop
pack
glue
pad
align
center
text
wrap
pre?
sub?
low?
upp?
lowc
uppc
fold
val
getd
set
setq
def
de
dm
recur
undef
redef
daemon
patch
xchg
on
off
onOff
zero
one
default
expr
subr
let
let?
use
accu
push
push1
pop
cut
del
queue
fifo
idx
lup
cache
locale
dirname
put
get
prop
;
=:
:
::
putl
getl
wipe
meta
atom
pair
circ?
lst?
num?
sym?
flg?
sp?
pat?
fun?
box?
str?
ext?
bool
not
==
n==
=
<>
=0
=T
n0
nT
<
<=
>
>=
match
+
-
*
/
%
*/
**
inc
dec
>>
lt0
le0
ge0
gt0
abs
bit?
&
|
x|
sqrt
seed
rand
max
min
length
size
accu
format
pad
money
round
bin
oct
hex
hax
fmt64
car
cdr
caar
cadr
cdar
cddr
caaar
caadr
cadar
caddr
cdaar
cdadr
cddar
cdddr
cadddr
cddddr
nth
con
cons
conc
circ
rot
list
need
range
full
make
made
chain
link
yoke
copy
mix
append
delete
delq
replace
insert
remove
place
strip
split
reverse
flip
trim
clip
head
tail
stem
fin
last
member
memq
mmeq
sect
diff
index
offset
prior
assoc
asoq
rank
sort
uniq
group
length
size
bytes
val
set
xchg
push
push1
pop
cut
queue
fifo
idx
balance
get
fill
apply
load
args
next
arg
rest
pass
quote
as
lit
eval
run
macro
curry
def
de
dm
recur
recurse
undef
box
new
type
isa
method
meth
send
try
super
extra
with
bind
job
let
let?
use
and
or
nand
nor
xor
bool
not
nil
t
prog
prog1
prog2
if
if2
ifn
when
unless
cond
nond
case
casq
state
while
until
loop
do
at
for
catch
throw
finally
co
yield
!
e
$
call
tick
ipid
opid
kill
quit
task
fork
pipe
later
timeout
abort
bye
apply
pass
maps
map
mapc
maplist
mapcar
mapcon
mapcan
filter
extract
seek
find
pick
cnt
sum
maxi
mini
fish
by
path
in
out
err
ctl
ipid
opid
pipe
any
sym
str
load
hear
tell
key
poll
peek
char
skip
eol
eof
from
till
line
format
scl
read
print
println
printsp
prin
prinl
msg
space
beep
tab
flush
rewind
rd
pr
wr
wait
sync
echo
info
file
dir
lines
open
close
port
listen
accept
host
connect
udp
script
once
rc
acquire
release
pretty
pp
show
view
here
prEval
mail
*Class
class
dm
rel
var
var:
new
type
isa
method
meth
send
try
object
extend
super
extra
with
This
can
dep
pool
journal
id
seq
lieu
lock
commit
rollback
mark
free
dbck
dbs
dbs+
db:
tree
db
aux
collect
genKey
useKey
+relation
+Any
+Bag
+Bool
+Number
+Date
+Time
+Symbol
+String
+Link
+Joint
+Blob
+Hook
+Hook2
+index
+Key
+Ref
+Ref2
+Idx
+Sn
+Fold
+IdxFold
+Aux
+UB
+Dep
+List
+Need
+Mis
+Alt
+Swap
+Entity
blob
dbSync
new!
set!
put!
inc!
blob!
upd
rel
request
obj
fmt64
root
fetch
store
count
leaf
minKey
maxKey
init
step
scan
iter
ubIter
prune
zapTree
chkTree
db/3
db/4
db/5
val/3
lst/3
map/3
isa/2
same/3
bool/3
range/3
head/3
fold/3
part/3
tolr/3
select/3
remote/2
prove
->
unify
be
clause
repeat
asserta
assertz
retract
rules
goal
fail
pilog
solve
query
?
repeat/0
fail/0
true/0
not/1
call/1
or/2
nil/1
equal/2
different/2
append/3
member/2
delete/3
permute/2
uniq/2
asserta/1
assertz/1
retract/1
clause/2
show/1
db/3
db/4
db/5
val/3
lst/3
map/3
isa/2
same/3
bool/3
range/3
head/3
fold/3
part/3
tolr/3
select/3
remote/2
pretty
pp
show
loc
*Dbg
doc
more
depth
what
who
can
dep
debug
d
unbug
u
vi
em
ld
trace
untrace
traceAll
proc
hd
bench
edit
lint
lintAll
select
update
cmd
argv
opt
version
gc
raw
alarm
protect
heap
stack
adr
env
trail
up
sys
date
time
usec
stamp
dat$
$dat
datSym
datStr
strDat
expDat
day
week
ultimo
tim$
$tim
telStr
expTel
locale
allowed
allow
pwd
cd
chdir
ctty
info
dir
dirname
errno
native
call
tick
kill
quit
task
fork
forked
pipe
timeout
mail
assert
test
bye
NIL
pico
*CPU
*OS
*DB
T
*Solo
*PPid
*Pid
@
@@
@@@
This
*Prompt
*Dbg
*Zap
*Scl
*Class
*Dbs
*Run
*Hup
*Sig1
*Sig2
^
*Err
*Msg
*Uni
*Led
*Tsm
*Adr
*Allow
*Fork
*Bye
Download
PicoLisp system can be downloaded from the PicoLisp Download page.
picolisp-3.1.5.2.orig/doc/refA.html 0000644 0000000 0000000 00000050577 12265263724 015476 0 ustar root root
A
picolisp-3.1.5.2.orig/doc/refB.html 0000644 0000000 0000000 00000031213 12265263724 015461 0 ustar root root
*Adr
listen and accept.
: *Adr
-> "127.0.0.1"
(adr 'var) -> num
(adr 'num) -> var
var (a symbol or a cons
pair) into num (actually an encoded pointer). A symbol will result
in a negative number, and a cons pair in a positive number. The second form
converts a pointer back into the original var.
: (setq X (box 7))
-> $53063416137450
: (adr X)
-> -2961853431592
: (adr @)
-> $53063416137450
: (val @)
-> 7
*Allow
NIL, it should contain a list where the CAR is an idx tree of allowed items, and the CDR a list of
prefix strings. See also allow,
allowed and pre?.
: (allowed ("app/") # Initialize
"!start" "!stop" "lib.css" "!psh" )
-> NIL
: (allow "!myFoo") # additional item
-> "!myFoo"
: (allow "myDir/" T) # additional prefix
-> "myDir/"
: *Allow
-> (("!start" ("!psh" ("!myFoo")) "!stop" NIL "lib.css") "app/" "myDir/")
: (idx *Allow) # items
-> ("!myFoo" "!psh" "!start" "!stop" "lib.css")
: (cdr *Allow) # prefixes
-> ("app/" "myDir/")
+Alt
+relation. This allows indexes or other
side effects to be maintained in a class different from the current one. See
also Database.
(class +EuOrd +Ord) # EU-specific order subclass
(rel nr (+Alt +Key +Number) +XyOrd) # Maintain the key in the +XyOrd index
+Any
+relation. Objects of that class accept
and maintain any type of Lisp data. Used often when there is no other suitable
relation class available. See also Database.
+Any is used simply for the reason that
there is no direct way to specify dotted pairs:
(rel loc (+Any)) # Locale, e.g. ("DE" . "de")
+Aux
+relations, in addition to +Ref or +Idx indexes. Expects a list of auxiliary
attributes of the same object, and combines all keys in that order into a single
index key. See also +UB, aux and Database.
(rel nr (+Ref +Number)) # Normal, non-unique index
(rel nm (+Aux +Ref +String) (nr txt)) # Combined name/number/text index
(rel txt (+Aux +Sn +Idx +String) (nr)) # Text/number plus tolerant text index
(abort 'cnt . prg) -> any
prg if it takes longer than
cnt seconds, and returns NIL. Otherwise, the result of
prg is returned. alarm
is used internally, so care must be taken not to interfer with other calls to
alarm.
: (abort 20 (in Sock (rd))) # Wait maximally 20 seconds for socket data
(abs 'num) -> num
num argument.
: (abs -7)
-> 7
: (abs 7)
-> 7
(accept 'cnt) -> cnt | NIL
cnt (as received by port), and returns the new socket descriptor
cnt. The global variable *Adr is set to the IP address
of the client. See also listen,
connect and *Adr.
: (setq *Socket
(accept (port 6789)) ) # Accept connection at port 6789
-> 4
(accu 'var 'any 'num)
num into a sum, using the key any in
an association list stored in var. See also assoc.
: (off Sum)
-> NIL
: (accu 'Sum 'a 1)
-> (a . 1)
: (accu 'Sum 'a 5)
-> 6
: (accu 'Sum 22 100)
-> (22 . 100)
: Sum
-> ((22 . 100) (a . 6))
(acquire 'sym) -> flg
sym, by
obtaining an exclusive lock on that file with ctl, and then trying to write the PID of the
current process into that file. It fails if the file already holds the PID of
some other existing process. See also release, *Pid and rc.
: (acquire "sema1")
-> 28255
(alarm 'cnt . prg) -> cnt
prg to be executed after
cnt seconds, and returns the number of seconds remaining until any
previously scheduled alarm was due to be delivered. Calling (alarm
0) will cancel an alarm. See also abort, sigio, *Hup and *Sig[12].
: (prinl (tim$ (time) T)) (alarm 10 (prinl (tim$ (time) T)))
16:36:14
-> 0
: 16:36:24
: (alarm 10 (bye 0))
-> 0
$
(align 'cnt 'any) -> sym
(align 'lst 'any ..) -> sym
any arguments packed in an aligned format. In the first form,
any will be left-aligned if cnt ist negative,
otherwise right-aligned. In the second form, all any arguments are
packed according to the numbers in lst. See also tab, center and wrap.
: (align 4 "a")
-> " a"
: (align -4 12)
-> "12 "
: (align (4 4 4) "a" 12 "b")
-> " a 12 b"
(all ['T | '0]) -> lst
NIL). Otherwise
(if the argument is T), all current transient symbols are returned. Else all current
external symbols are returned.
: (all) # All internal symbols
-> (inc> leaf nil inc! accept ...
# Find all symbols starting with an underscore character
: (filter '((X) (= "_" (car (chop X)))) (all))
-> (_put _nacs _oct _lintq _lst _map _iter _dbg2 _getLine _led ...
(allow 'sym ['flg]) -> sym
*Allow. If the value of
*Allow is non-NIL, sym is added to the
idx tree in the CAR of
*Allow (if flg is NIL), or to the list of
prefix strings (if flg is non-NIL). See also allowed.
: *Allow
-> (("!start" ("!psh") "!stop" NIL "lib.css") "app/")
: (allow "!myFoo") # additionally allowed item
-> "!myFoo"
: (allow "myDir/" T) # additionally allowed prefix
-> "myDir/"
(allowed lst [sym ..])
*Allow. lst should
consist of prefix strings (to be checked at runtime with pre?), and the sym arguments
should specify the initially allowed items. See also allow.
: (allowed ("app/") # allowed prefixes
"!start" "!stop" "lib.css" "!psh" ) # allowed items
-> NIL
(and 'any ..) -> any
any are evaluated from left to
right. If NIL is encountered, NIL is returned
immediately. Else the result of the last expression is returned.
: (and (= 3 3) (read))
abc # User input
-> abc
: (and (= 3 4) (read))
-> NIL
(any 'sym) -> any
any from the name of sym. This is the
reverse operation of sym. See also
str.
: (any "(a b # Comment^Jc d)")
-> (a b c d)
: (any "\"A String\"")
-> "A String"
(append 'lst ..) -> lst
conc, insert, delete and remove.
: (append '(a b c) (1 2 3))
-> (a b c 1 2 3)
: (append (1) (2) (3) 4)
-> (1 2 3 . 4)
append/3
append and member/2.
: (? (append @X @Y (a b c)))
@X=NIL @Y=(a b c)
@X=(a) @Y=(b c)
@X=(a b) @Y=(c)
@X=(a b c) @Y=NIL
-> NIL
(apply 'fun 'lst ['any ..]) -> any
fun to lst. If additional any
arguments are given, they are applied as leading elements of lst.
(apply 'fun 'lst 'any1 'any2) is equivalent to (apply 'fun
(cons 'any1 'any2 'lst)).
: (apply + (1 2 3))
-> 6
: (apply * (5 6) 3 4)
-> 360
: (apply '((X Y Z) (* X (+ Y Z))) (3 4 5))
-> 27
: (apply println (3 4) 1 2)
1 2 3 4
-> 4
(arg ['cnt]) -> any
@). If cnt is not given, the value that was returned
from the last call to next) is returned. Otherwise, the
cnt'th remaining argument is returned. See also args, next, rest and pass.
: (de foo @ (println (next) (arg))) # Print argument twice
-> foo
: (foo 123)
123 123
-> 123
: (de foo @
(println (arg 1) (arg 2))
(println (next))
(println (arg 1) (arg 2)) )
-> foo
: (foo 'a 'b 'c)
a b
a
b c
-> c
(args) -> flg
@). Returns T when there are more arguments to be
fetched from the internal list. See also next, arg, rest and pass.
: (de foo @ (println (args))) # Test for arguments
-> foo
: (foo) # No arguments
NIL
-> NIL
: (foo NIL) # One argument
T
-> T
: (foo 123) # One argument
T
-> T
(argv [var ..] [. sym]) -> lst|sym
argv returns a list of strings
containing all remaining command line arguments. Otherwise, the
var/sym arguments are subsequently bound to the command line
arguments. A hyphen "-" can be used to inhibit the automatic
loading further arguments. See also cmd, Invocation and
opt.
$ pil -"println 'OK" - abc 123 +
OK
: (argv)
-> ("abc" "123")
: (argv A B)
-> "123"
: A
-> "abc"
: B
-> "123"
: (argv . Lst)
-> ("abc" "123")
: Lst
-> ("abc" "123")
(as 'any1 . any2) -> any2 | NIL
any2 unevaluated when any1 evaluates to
non-NIL. Otherwise NIL is returned. (as Flg A B
C) is equivalent to (and Flg '(A B C)). See also quote.
: (as (= 3 3) A B C)
-> (A B C)
(asoq 'any 'lst) -> lst
lst with any as its CAR, or NIL if no
match is found. == is used for
comparison (pointer equality). See also assoc, delq, memq, mmeq and Comparing.
: (asoq 999 '((999 1 2 3) (b . 7) ("ok" "Hello")))
-> NIL
: (asoq 'b '((999 1 2 3) (b . 7) ("ok" "Hello")))
-> (b . 7)
(assert exe ..) -> prg | NIL
*Dbg is
non-NIL), assert returns a prg list which
tests all exe conditions, and issues an error via quit if one of the results evaluates to
NIL. Otherwise, NIL is returned. Used typically in
combination with the ~ tilde read-macro to insert the test code only when
in debug mode. See also test.
# Start in debug mode
$ pil +
: (de foo (N)
~(assert (>= 90 N 10))
(bar N) )
-> foo
: (pp 'foo) # Pretty-print 'foo'
(de foo (N)
(unless (>= 90 N 10) # Assertion code exists
(quit "'assert' failed" '(>= 90 N 10)) )
(bar N) )
-> foo
: (foo 7) # Try it
(>= 90 N 10) -- Assertion failed
?
# Start in non-debug mode
$ pil
: (de foo (N)
~(assert (>= 90 N 10))
(bar N) )
-> foo
: (pp 'foo) # Pretty-print 'foo'
(de foo (N)
(bar N) ) # Assertion code does not exist
-> foo
(asserta 'lst) -> lst
be, clause, assertz and retract.
: (be a (2)) # Define two facts
-> a
: (be a (3))
-> a
: (asserta '(a (1))) # Insert new fact in front
-> ((1))
: (? (a @N)) # Query
@N=1
@N=2
@N=3
-> NIL
asserta/1
asserta, assertz/1 and retract/1.
: (? (asserta (a (2))))
-> T
: (? (asserta (a (1))))
-> T
: (rules 'a)
1 (be a (1))
2 (be a (2))
-> a
(assertz 'lst) -> lst
be, clause, asserta and retract.
: (be a (1)) # Define two facts
-> a
: (be a (2))
-> a
: (assertz '(a (3))) # Append new fact at the end
-> ((3))
: (? (a @N)) # Query
@N=1
@N=2
@N=3
-> NIL
assertz/1
assertz, asserta/1 and retract/1.
: (? (assertz (a (1))))
-> T
: (? (assertz (a (2))))
-> T
: (rules 'a)
1 (be a (1))
2 (be a (2))
-> a
(assoc 'any 'lst) -> lst lst with its CAR
equal to any, or NIL if no match is found. See also
asoq.
: (assoc "b" '((999 1 2 3) ("b" . 7) ("ok" "Hello")))
-> ("b" . 7)
: (assoc 999 '((999 1 2 3) ("b" . 7) ("ok" "Hello")))
-> (999 1 2 3)
: (assoc 'u '((999 1 2 3) ("b" . 7) ("ok" "Hello")))
-> NIL
(at '(cnt1 . cnt2|NIL) . prg) -> any
cnt1 (destructively), and returns NIL
when it is less than cnt2. Otherwise, cnt1 is reset to
zero and prg is executed. Returns the result of prg.
If cnt2 is NIL, nothing is done, and NIL
is returned immediately.
: (do 11 (prin ".") (at (0 . 3) (prin "!")))
...!...!...!..-> NIL
(atom 'any) -> flg
T when the argument any is an atom (a
number or a symbol). See also pair.
: (atom 123)
-> T
: (atom 'a)
-> T
: (atom NIL)
-> T
: (atom (123))
-> NIL
(aux 'var 'cls ['hook] 'any ..) -> sym
cls, where the value for
var corresponds to any and the following arguments.
var, cls and hook should specify a
tree for cls or one of
its superclasses, for a relation with auxiliary keys. For multi-key accesses,
aux is simlar to - but faster than - db, because it
can use a single tree access. See also db, collect, fetch, init, step and +Aux.
(class +PS +Entity)
(rel par (+Dep +Joint) (sup) ps (+Part)) # Part
(rel sup (+Aux +Ref +Link) (par) NIL (+Supp)) # Supplier
...
(aux 'sup '+PS # Access PS object
(db 'nr '+Supp 1234)
(db 'nr '+Part 5678) )
B
picolisp-3.1.5.2.orig/doc/refC.html 0000644 0000000 0000000 00000062232 12265263724 015467 0 ustar root root
*Blob
blob.
: *Blob
-> "blob/app/"
*Bye
prg body, to be
executed just before the termination of the PicoLisp interpreter. See also
bye and tmp.
: (push1 '*Bye '(call 'rm "myfile.tmp")) # Remove a temporary file
-> (call 'rm "myfile.tmp")
+Bag
+relation. Objects of that class maintain
a list of heterogeneous relations. Typically used in combination with the
+List prefix class, to maintain small
two-dimensional tables within objects. See also Database.
(rel pos (+List +Bag) # Positions
((+Ref +Link) NIL (+Item)) # Item
((+Number) 2) # Price
((+Number)) # Quantity
((+String)) # Memo text
((+Number) 2) ) # Total amount
+Blob
+relation. Objects of that class maintain
blobs, as stubs in database objects pointing to actual files for arbitrary
(often binary) data. The files themselves reside below the path specified by the
*Blob variable. See also Database.
(rel jpg (+Blob)) # Picture
+relation. Objects of that class expect
either T or NIL as value (though, as always, only
non-NIL will be physically stored in objects). See also Database.
(rel ok (+Ref +Bool)) # Indexed flag
(balance 'var 'lst ['flg])
idx tree
in var, from the sorted list in lst. Normally (if
random or, in the worst case, ordered data) are inserted with idx,
the tree will not be balanced. But if lst is properly sorted, its
contents will be inserted in an optimally balanced way. If flg is
non-NIL, the index tree will be augmented instead of being
overwritten. See also Comparing and
sort.
# Normal idx insert
: (off I)
-> NIL
: (for X (1 4 2 5 3 6 7 9 8) (idx 'I X T))
-> NIL
: (depth I)
-> 7
# Balanced insert
: (balance 'I (sort (1 4 2 5 3 6 7 9 8)))
-> NIL
: (depth I)
-> 4
# Augment
: (balance 'I (sort (10 40 20 50 30 60 70 90 80)) T)
-> NIL
: (idx 'I)
-> (1 2 3 4 5 6 7 8 9 10 20 30 40 50 60 70 80 90)
(basename 'any) -> sym
any. See also dirname and path.
: (basename "a/b/c/d")
-> "d"
(be sym . any) -> sym
sym argument, by concatenating the any argument to the
T property of sym. Groups of declarations are
collected for a given sym. When sym changes, i.e. when
it differs from the one in the previous declaration, the current group is
considered to be complete and a new group is started. Later be
declarations for a previously completed symbol will reset its rules, to allow
repeated reloading of source files.
See also clause, asserta, assertz, retract, rules, goal and prove.
: (be likes (John Mary))
-> likes
: (be likes (John @X) (likes @X wine) (likes @X food))
-> likes
: (get 'likes T)
-> (((John Mary)) ((John @X) (likes @X wine) (likes @X food)))
: (rules 'likes)
1 (be likes (John Mary))
2 (be likes (John @X) (likes @X wine) (likes @X food))
-> likes
: (? (likes John @X))
@X=Mary
-> NIL
(beep) -> any
space, prin and char.
: (beep)
-> "^G"
(bench . prg) -> any
prg, by printing the time it took
to execute, and returns the result. See also usec.
: (bench (wait 2000))
1.996 sec
-> NIL
(bin 'num ['num]) -> sym
(bin 'sym) -> num
num to a binary string, or a binary string
sym to a number. In the first case, if the second argument is
given, the result is separated by spaces into groups of such many digits. See
also oct, hex, fmt64, hax and format.
: (bin 73)
-> "1001001"
: (bin "1001001")
-> 73
: (bin 1234567 4)
-> "100 1011 0101 1010 0001 11"
(bind 'sym|lst . prg) -> any
prg is executed, then the symbols are restored to their original
values. During execution of prg, the values of the symbols can be
temporarily modified. The return value is the result of prg. See
also let, job and use.
: (setq X 123) # X is 123
-> 123
: (bind 'X (setq X "Hello") (println X)) # Set X to "Hello", print it
"Hello"
-> "Hello"
: (bind '((X . 3) (Y . 4)) (println X Y) (* X Y))
3 4
-> 12
: X
-> 123 # X is restored to 123
(bit? 'num ..) -> num | NIL
num argument when all bits which are 1 in the
first argument are also 1 in all following arguments, otherwise
NIL. When one of those arguments evaluates to NIL, it
is returned immediately. See also &,
| and x|.
: (bit? 7 15 255)
-> 7
: (bit? 1 3)
-> 1
: (bit? 1 2)
-> NIL
(blob 'obj 'sym) -> sym
var in obj. See
also *Blob, blob! and pack.
: (show (db 'nr '+Item 1))
{3-1} (+Item)
jpg
pr 29900
inv 100
sup {2-1}
nm "Main Part"
nr 1
-> {3-1}
: (blob '{3-1} 'jpg)
-> "blob/app/3/-/1.jpg"
(blob! 'obj 'sym 'file)
file in a blob. See also put!>.
(blob! *ID 'jpg "picture.jpg")
(bool 'any) -> flg
T when the argument any is
non-NIL. This function is only needed when T is
strictly required for a "true" condition (Usually, any non-NIL
value is considered to be "true"). See also flg?.
: (and 3 4)
-> 4
: (bool (and 3 4))
-> T
bool/3
get algorithm to the following arguments.
Typically used as filter predicate in select/3 database queries. See also
bool, isa/2, same/3, range/3, head/3, fold/3, part/3 and tolr/3.
: (? @OK NIL # Find orders where the 'ok' flag is not set
(db nr +Ord @Ord)
(bool @OK @Ord ok) )
@OK=NIL @Ord={3-7}
-> NIL
(box 'any) -> sym
any argument. See also new
and box?.
: (show (box '(A B C)))
$134425627 (A B C)
-> $134425627
(box? 'any) -> sym | NIL
any when it is an anonymous symbol,
otherwise NIL. See also box, str? and ext?.
: (box? (new))
-> $134563468
: (box? 123)
-> NIL
: (box? 'a)
-> NIL
: (box? NIL)
-> NIL
(by 'fun1 'fun2 'lst ..) -> lst
fun1 to each element of lst. When
additional lst arguments are given, their elements are also passed
to fun1. Each result of fun1 is CONSed with its
corresponding argument form the original lst, and collected into a
list which is passed to fun2. For the list returned from
fun2, the CAR elements returned by fun1 are
(destructively) removed from each element ("decorate-apply-undecorate" idiom).
: (let (A 1 B 2 C 3) (by val sort '(C A B)))
-> (A B C)
: (by '((N) (bit? 1 N)) group (3 11 6 2 9 5 4 10 12 7 8 1))
-> ((3 11 9 5 7 1) (6 2 4 10 12 8))
(bye 'cnt|NIL)
finally
expressions, closes all open files, executes the VAL of the global
variable *Bye (should be a
prg), flushes standard output, and then exits the PicoLisp
interpreter. The process return value is cnt, or 0 if the argument
is missing or NIL.
: (setq *Bye '((println 'OK) (println 'bye)))
-> ((println 'OK) (println 'bye))
: (bye)
OK
bye
$
(bytes 'any) -> cnt
any would occupy in encoded binary
format (as generated by pr). See also
size and length.
: (bytes "abc")
-> 4
: (bytes "äbc")
-> 5
: (bytes 127)
-> 2
: (bytes 128)
-> 3
: (bytes (101 (102) 103))
-> 10
: (bytes (101 102 103 .))
-> 9
C
picolisp-3.1.5.2.orig/doc/refD.html 0000644 0000000 0000000 00000067432 12265263724 015477 0 ustar root root
*CPU
"x86-64",
"ppc64" or "emu". See also *OS.
: *CPU
-> "x86-64"
*Class
class, extend, dm and var and rel.
: (class +Test)
-> +Test
: *Class
-> +Test
(cache 'var 'sym . prg) -> any
idx tree structure. Such an
optimization is sometimes called "memoization". sym must be a
transient symbol representing a unique key for the argument(s) to the
calculation. See also hash.
: (de fibonacci (N)
(cache '(NIL) (pack (char (hash N)) N)
(if (> 2 N)
1
(+
(fibonacci (dec N))
(fibonacci (- N 2)) ) ) ) )
-> fibonacci
: (fibonacci 22)
-> 28657
: (fibonacci 10000)
-> 5443837311356528133873426099375038013538 ... # (2090 digits)
(call 'any ..) -> flg
any arguments specify the
command and its arguments. Returns T if the command was executed
successfully.
: (when (call 'test "-r" "file.l") # Test if file exists and is readable
(load "file.l") # Load it
(call 'rm "file.l") ) # Remove it
call/1
: (be mapcar (@ NIL NIL))
-> mapcar
: (be mapcar (@P (@X . @L) (@Y . @M))
(call @P @X @Y) # Call the given predicate
(mapcar @P @L @M) )
-> mapcar
: (? (mapcar permute ((a b c) (d e f)) @X))
@X=((a b c) (d e f))
@X=((a b c) (d f e))
@X=((a b c) (e d f))
...
@X=((a c b) (d e f))
@X=((a c b) (d f e))
@X=((a c b) (e d f))
...
(can 'msg) -> lst
msg. See also OO Concepts, class, dep, what and who.
: (can 'zap>)
-> ((zap> . +relation) (zap> . +Blob) (zap> . +Entity))
: (more @ pp)
(dm (zap> . +relation) (Obj Val))
(dm (zap> . +Blob) (Obj Val)
(and
Val
(call 'rm "-f" (blob Obj (: var))) ) )
(dm (zap> . +Entity) NIL
(for X (getl This)
(let V (or (atom X) (pop 'X))
(and (meta This X) (zap> @ This V)) ) ) )
-> NIL
(car 'var) -> any
var if it is a symbol, or the
first element if it is a list. See also cdr and c..r.
: (car (1 2 3 4 5 6))
-> 1
(c[ad]*ar 'var) -> any
(c[ad]*dr 'lst) -> any
car and cdr functions, with up to four letters 'a' and
'd'.
: (cdar '((1 . 2) . 3))
-> 2
(case 'any (any1 . prg1) (any2 . prg2) ..) -> any
any is evaluated and compared to the CAR
elements anyN of each clause. If one of them is a list,
any is in turn compared to all elements of that list.
T is a catch-all for any value. If a comparison succeeds,
prgN is executed, and the result returned. Otherwise
NIL is returned. See also casq and state .
: (case (char 66) ("A" (+ 1 2 3)) (("B" "C") "Bambi") ("D" (* 1 2 3)))
-> "Bambi"
: (case 'b (a 1) ("b" 2) (b 3) (c 4))
-> 2
(casq 'any (any1 . prg1) (any2 . prg2) ..) -> any
any is evaluated and compared to the CAR
elements anyN of each clause. == is used for comparison (pointer equality). If
one of them is a list, any is in turn compared to all elements of
that list. T is a catch-all for any value. If a comparison
succeeds, prgN is executed, and the result returned. Otherwise
NIL is returned. See also case and state.
: (casq 'b (a 1) ("b" 2) (b 3) (c 4))
-> 3
: (casq 'b (a 1) ("b" 2) ((a b c) 3) (c 4))
-> 3
(catch 'any . prg) -> any
throw or by a runtime error. If
any is an atom, it is used by throw as a jump label
(with T being a catch-all for any label), and a throw
called during the execution of prg will immediately return the
thrown value. Otherwise, any should be a list of strings, to catch
any error whose message contains one of these strings, and this will immediately
return the matching string. If neither throw nor an error occurs,
the result of prg is returned. See also finally, quit and
Error Handling.
: (catch 'OK (println 1) (throw 'OK 999) (println 2))
1
-> 999
: (catch '("No such file") (in "doesntExist" (foo)))
-> "No such file"
(cd 'any) -> sym
any. The old directory is
returned on success, otherwise NIL. See also chdir, dir and pwd.
: (when (cd "lib")
(println (sum lines (dir)))
(cd @) )
10955
(cdr 'lst) -> any
lst. See also
car and c..r.
: (cdr (1 2 3 4 5 6))
-> (2 3 4 5 6)
(center 'cnt|lst 'any ..) -> sym
any arguments packed in a centered format. Trailing blanks
are omitted. See also align, tab and wrap.
: (center 4 12)
-> " 12"
: (center 4 "a")
-> " a"
: (center 7 "a")
-> " a"
: (center (3 3 3) "a" "b" "c")
-> " a b c"
(chain 'lst ..) -> lst
lst to the end of the list in the current make environment. This operation is efficient
also for long lists, because a pointer to the last element of the result list is
maintained. chain returns the last linked argument. See also
link, yoke and made.
: (make (chain (list 1 2 3) NIL (cons 4)) (chain (list 5 6)))
-> (1 2 3 4 5 6)
(char) -> sym
(char 'cnt) -> sym
(char T) -> sym
(char 'sym) -> cnt
NIL
upon end of file. When called with a number cnt, a character with
the corresponding unicode value is returned. As a special case, T
is accepted to produce a byte value greater than any first byte in a UTF-8
character (used as a top value in comparisons). Otherwise, when called with a
symbol sym, the numeric unicode value of the first character of the
name of that symbol is returned. See also peek, skip, key, line, till and eof.
: (char) # Read character from console
A # (typed 'A' and a space/return)
-> "A"
: (char 100) # Convert unicode to symbol
-> "d"
: (char "d") # Convert symbol to unicode
-> 100
: (char T) # Special case
-> # (not printable)
: (char 0)
-> NIL
: (char NIL)
-> 0
(chdir 'any . prg) -> any
any with cd during the execution of prg. Then
the previous directory will be restored and the result of prg
returned. See also dir and pwd.
: (pwd)
-> "/usr/abu/pico"
: (chdir "src" (pwd))
-> "/usr/abu/pico/src"
: (pwd)
-> "/usr/abu/pico"
(chkTree 'sym ['fun]) -> num
fun is
called with the key and value of each node, and should return NIL
for failure. See also tree and
root.
: (show *DB '+Item)
{C} NIL
sup (7 . {7-3})
nr (7 . {7-1}) # 7 nodes in the 'nr' tree, base node is {7-1}
pr (7 . {7-4})
nm (77 . {7-6})
-> {C}
: (chkTree '{7-1}) # Check that node
-> 7
(chop 'any) -> lst
any as a list of single-character strings. If
any is NIL or a symbol with no name, NIL
is returned. A list argument is returned unchanged.
: (chop 'car)
-> ("c" "a" "r")
: (chop "Hello")
-> ("H" "e" "l" "l" "o")
(circ 'any ..) -> lst
any arguments by consing them to a list and then connecting the
CDR of the last cell to the first cell. See also circ? and list.
: (circ 'a 'b 'c)
-> (a b c .)
(circ? 'any) -> any any is a circular list, else NIL. See
also circ.
: (circ? 'a)
-> NIL
: (circ? (1 2 3))
-> NIL
: (circ? (1 . (2 3 .)))
-> (2 3 .)
(class sym . typ) -> obj
sym as a class with the superclass(es)
typ. As a side effect, the global variable *Class is set to obj. See also
extend, dm, var,
rel, type, isa and object.
: (class +A +B +C +D)
-> +A
: +A
-> (+B +C +D)
: (dm foo> (X) (bar X))
-> foo>
: +A
-> ((foo> (X) (bar X)) +B +C +D)
(clause '(sym . any)) -> sym
sym argument, by concatenating the any argument to the
T property of sym. See also be.
: (clause '(likes (John Mary)))
-> likes
: (clause '(likes (John @X) (likes @X wine) (likes @X food)))
-> likes
: (? (likes @X @Y))
@X=John @Y=Mary
-> NIL
clause/2
: (? (clause append ((NIL @X @X))))
-> T
: (? (clause append @C))
@C=((NIL @X @X))
@C=(((@A . @X) @Y (@A . @Z)) (append @X @Y @Z))
-> NIL
(clip 'lst) -> lst
lst with all whitespace characters or
NIL elements removed from both sides. See also trim.
: (clip '(NIL 1 NIL 2 NIL))
-> (1 NIL 2)
: (clip '(" " a " " b " "))
-> (a " " b)
(close 'cnt) -> cnt | NIL
cnt, and returns it when successful.
Should not be called inside an out body
for that descriptor. See also open,
poll,
listen and connect.
: (close 2) # Close standard error
-> 2
(cmd ['any]) -> sym
any. Setting the name may not work on some operating systems. Note
that the new name must not be longer than the original one. See also argv, file and Invocation.
$ pil +
: (cmd)
-> "/usr/bin/picolisp"
: (cmd "!/bin/picolust")
-> "!/bin/picolust"
: (cmd)
-> "!/bin/picolust"
(cnt 'fun 'lst ..) -> cnt
fun to each element of lst. When
additional lst arguments are given, their elements are also passed
to fun. Returns the count of non-NIL values returned
from fun.
: (cnt cdr '((1 . T) (2) (3 4) (5)))
-> 2
(collect 'var 'cls ['hook] ['any|beg ['end [var ..]]])
cls, where the
values for the var arguments correspond to the any
arguments, or where the values for the var arguments are in the
range beg .. end. var, cls
and hook should specify a tree for cls or one of its
superclasses. If additional var arguments are given, the final
values for the result list are obtained by applying the get algorithm. See also db, aux,
fetch, init and step.
: (collect 'nr '+Item)
-> ({3-1} {3-2} {3-3} {3-4} {3-5} {3-6} {3-8})
: (collect 'nr '+Item 3 6 'nr)
-> (3 4 5 6)
: (collect 'nr '+Item 3 6 'nm)
-> ("Auxiliary Construction" "Enhancement Additive" "Metal Fittings" "Gadget Appliance")
: (collect 'nm '+Item "Main Part")
-> ({3-1})
(commit ['any] [exe1] [exe2]) -> T
any is given, it is implicitly sent (with all modified objects) via
the tell mechanism to all family
members. If exe1 or exe2 are given, they are executed
as pre- or post-expressions while the database is locked and protected. See also rollback.
: (pool "db")
-> T
: (put '{1} 'str "Hello")
-> "Hello"
: (commit)
-> T
(con 'lst 'any) -> any
any to the first cell of lst, by
(destructively) storing any in the CDR of lst. See
also conc.
: (setq C (1 . a))
-> (1 . a)
: (con C '(b c d))
-> (b c d)
: C
-> (1 b c d)
(conc 'lst ..) -> lst
append and con.
: (setq A (1 2 3) B '(a b c))
-> (a b c)
: (conc A B) # Concatenate lists in 'A' and 'B'
-> (1 2 3 a b c)
: A
-> (1 2 3 a b c) # Side effect: List in 'A' is modified!
(cond ('any1 . prg1) ('any2 . prg2) ..) -> any
anyN conditions evaluates
to non-NIL, prgN is executed and the result returned.
Otherwise (all conditions evaluate to NIL), NIL is
returned. See also nond, if, if2
and when.
: (cond
((= 3 4) (println 1))
((= 3 3) (println 2))
(T (println 3)) )
2
-> 2
(connect 'any1 'any2) -> cnt | NIL
any1, port any2. any1 may be either a
hostname or a standard internet address in numbers-and-dots/colons notation
(IPv4/IPv6). any2 may be either a port number or a service name.
Returns a socket descriptor cnt, or NIL if the
connection cannot be established. See also listen and udp.
: (connect "localhost" 4444)
-> 3
: (connect "some.host.org" "http")
-> 4
(cons 'any ['any ..]) -> lst
(cons 'a 'b 'c 'd) is equivalent to (cons
'a (cons 'b (cons 'c 'd))). See also list.
: (cons 1 2)
-> (1 . 2)
: (cons 'a '(b c d))
-> (a b c d)
: (cons '(a b) '(c d))
-> ((a b) c d)
: (cons 'a 'b 'c 'd)
-> (a b c . d)
(copy 'any) -> any
any. For lists, the top level cells are
copied, while atoms are returned unchanged.
: (=T (copy T)) # Atoms are not copied
-> T
: (setq L (1 2 3))
-> (1 2 3)
: (== L L)
-> T
: (== L (copy L)) # The copy is not identical to the original
-> NIL
: (= L (copy L)) # But the copy is equal to the original
-> T
(co 'sym [. prg]) -> any
sym.
If prg is not given, a coroutine with that tag will be stopped.
Otherwise, if a coroutine running with that tag is found (pointer equality is
used for comparison), its execution is resumed. Else a new coroutine with that
tag is initialized and started. prg will be executed until it
either terminates normally, or until yield is called. In the latter case
co returns, or transfers control to some other, already running,
coroutine. A coroutine cannot resume itself directly or indirectly. See also
stack, catch and throw.
: (de pythag (N) # A generator function
(if (=T N)
(co 'rt) # Stop
(co 'rt
(for X N
(for Y (range X N)
(for Z (range Y N)
(when (= (+ (* X X) (* Y Y)) (* Z Z))
(yield (list X Y Z)) ) ) ) ) ) ) )
: (pythag 20)
-> (3 4 5)
: (pythag 20)
-> (5 12 13)
: (pythag 20)
-> (6 8 10)
(count 'tree) -> num
tree and root.
: (count (tree 'nr '+Item))
-> 7
(ctl 'sym . prg) -> any
sym is "+") can be set on the file
sym, then executes prg and releases the lock. If the
files does not exist, it will be created. When sym is
NIL, a shared lock is tried on the current innermost I/O channel,
and when it is T, an exclusive lock is tried instead. See also
in, out, err and pipe.
$ echo 9 >count # Write '9' to file "count"
$ pil +
: (ctl ".ctl" # Exclusive control, using ".ctl"
(in "count"
(let Cnt (read) # Read '9'
(out "count"
(println (dec Cnt)) ) ) ) ) # Write '8'
-> 8
:
$ cat count # Check "count"
8
(ctty 'sym|pid) -> flg
ctty changes the current
TTY device to sym. Otherwise, the local console is prepared for
serving the PicoLisp process with the process ID pid. See also
raw.
: (ctty "/dev/tty")
-> T
(curry lst . fun) -> fun
lst and the functional expression fun. Each member in
lst that is a pat? symbol
is substituted inside fun by its value. All other symbols in
lst are collected into a job environment.
: (de multiplier (@X)
(curry (@X) (N) (* @X N)) )
-> multiplier
: (multiplier 7)
-> ((N) (* 7 N))
: ((multiplier 7) 3))
-> 21
: (def 'fiboCounter
(curry ((N1 . 0) (N2 . 1)) (Cnt)
(do Cnt
(println
(prog1
(+ N1 N2)
(setq N1 N2 N2 @) ) ) ) ) )
-> fiboCounter
: (pp 'fiboCounter)
(de fiboCounter (Cnt)
(job '((N2 . 1) (N1 . 0))
(do Cnt
(println
(prog1 (+ N1 N2) (setq N1 N2 N2 @)) ) ) ) )
-> fiboCounter
: (fiboCounter 5)
1
2
3
5
8
-> 8
: (fiboCounter 5)
13
21
34
55
89
-> 89
(cut 'cnt 'var) -> lst
cnt elements (CAR) from the stack in
var. See also pop and
del.
: (setq S '(1 2 3 4 5 6 7 8))
-> (1 2 3 4 5 6 7 8)
: (cut 3 'S)
-> (1 2 3)
: S
-> (4 5 6 7 8)
D
picolisp-3.1.5.2.orig/doc/refE.html 0000644 0000000 0000000 00000045420 12265263724 015471 0 ustar root root
*DB
{1}, the database root. All transient symbols in a database can
be reached from that root. Except during debugging, any explicit literal access
to symbols in the database should be avoided, because otherwise a memory leak
might occur (The garbage collector temporarily sets *DB to
NIL and restores its value after collection, thus disposing of all
external symbols not currently used in the program).
: (show *DB)
{1} NIL
+City {P}
+Person {3}
-> {1}
: (show '{P})
{P} NIL
nm (566 . {AhDx})
-> {P}
: (show '{3})
{3} NIL
tel (681376 . {Agyl})
nm (1461322 . {2gu7})
-> {3}
*Dbg
+ command line argument (see Invocation). When non-NIL, the $ (tracing) and ! (breakpoint) functions are enabled, and the
current line number and file name will be stored in symbol properties by
de, def and dm. See also debug, trace and lint.
: (de foo (A B) (* A B))
-> foo
: (trace 'foo)
-> foo
: (foo 3 4)
foo : 3 4
foo = 12
-> 12
: (let *Dbg NIL (foo 3 4))
-> 12
*Dbs
pool). It is typically set
by dbs
and dbs+.
: *Dbs
-> (1 2 1 0 2 3 3 3)
+Date
date), a subclass of +Number. See also Database.
(rel dat (+Ref +Date)) # Indexed date
+Dep
+relations. Expects a list of (symbolic)
attributes that depend on this relation. Whenever this relations is cleared
(receives a value of NIL), the dependent relations will also be
cleared, triggering all required side-effects. See also Database.
(class +Pos +Entity) # Position class
(rel ord (+Dep +Joint) # Order of that position
(itm) # 'itm' specifies the dependency
pos (+Ord) ) # Arguments to '+Joint'
(rel itm (+Ref +Link) NIL (+Item)) # Item depends on the order
(d) -> T
!
breakpoints into all subexpressions of the current breakpoint. Typically used
when single-stepping a function or method with debug. See also u and unbug.
! (d) # Debug subexpression(s) at breakpoint
-> T
(daemon 'sym . prg) -> fun
(daemon '(sym . cls) . prg) -> fun
(daemon '(sym sym2 [. cls]) . prg) -> fun
prg in the beginning of the function (first form), the
method body of sym in cls (second form) or in the
class obtained by geting
sym2 from *Class (or
cls if given) (third form). Built-in functions (C-function pointer)
are automatically converted to Lisp expressions. See also trace, expr, patch and redef.
: (de hello () (prinl "Hello world!"))
-> hello
: (daemon 'hello (prinl "# This is the hello world program"))
-> (NIL (prinl "# This is the hello world program") (prinl "Hello world!"))
: (hello)
# This is the hello world program
Hello world!
-> "Hello world!"
: (daemon '* (msg 'Multiplying))
-> (@ (msg 'Multiplying) (pass $134532148))
: *
-> (@ (msg 'Multiplying) (pass $134532148))
: (* 1 2 3)
Multiplying
-> 6
(dat$ 'dat ['sym]) -> sym
date dat in
ISO format, with an optional delimiter character sym. See also
$dat, tim$, datStr and datSym.
: (dat$ (date))
-> "20070601"
: (dat$ (date) "-")
-> "2007-06-01"
(datStr 'dat ['flg]) -> sym
date according to the
current locale. If flg
is non-NIL, the year will be formatted modulo 100. See also
dat$, datSym, strDat, expDat, expTel and day.
: (datStr (date))
-> "2007-06-01"
: (locale "DE" "de")
-> NIL
: (datStr (date))
-> "01.06.2007"
: (datStr (date) T)
-> "01.06.07"
(datSym 'dat) -> sym
date dat in
in symbolic format (DDmmmYY). See also dat$ and datStr.
: (datSym (date))
-> "01jun07"
(date ['T]) -> dat
(date 'dat) -> (y m d)
(date 'y 'm 'd) -> dat | NIL
(date '(y m d)) -> dat | NIL
T argument, the
current Coordinated Universal Time (UTC) is returned. When called with a single
number dat, it is taken as a date and a list with the corresponding
year, month and day is returned. When called with three numbers (or a list of
three numbers) for the year, month and day, the corresponding date is returned
(or NIL if they do not represent a legal date). See also time, stamp, $dat, dat$, datSym, datStr, strDat, expDat, day, week and ultimo.
: (date) # Today
-> 730589
: (date 2000 6 12) # 12-06-2000
-> 730589
: (date 2000 22 5) # Illegal date
-> NIL
: (date (date)) # Today's year, month and day
-> (2000 6 12)
: (- (date) (date 2000 1 1)) # Number of days since first of January
-> 163
(day 'dat ['lst]) -> sym
date dat, in the language of the
current locale. If lst
is given, it should be a list of alternative weekday names. See also week, datStr and strDat.
: (day (date))
-> "Friday"
: (locale "DE" "de")
-> NIL
: (day (date))
-> "Freitag"
: (day (date) '("Mo" "Tu" "We" "Th" "Fr" "Sa" "Su"))
-> "Fr"
(db 'var 'cls ['hook] 'any ['var 'any ..]) -> sym | NIL
cls, where the values for
the var arguments correspond to the any arguments. If
a matching object cannot be found, NIL is returned.
var, cls and hook should specify a
tree for cls or one of
its superclasses. See also aux,
collect, request, fetch, init and step.
: (db 'nr '+Item 1)
-> {3-1}
: (db 'nm '+Item "Main Part")
-> {3-1}
db/3
db/4
db/5
+index. For the key
pattern applies:
+Aux
key combinations
select/3 and remote/2.
: (? (db nr +Item @Item)) # No value given
@Item={3-1}
@Item={3-2}
@Item={3-3}
@Item={3-4}
@Item={3-5}
@Item={3-6}
-> NIL
: (? (db nr +Item 2 @Item)) # Get item no. 2
@Item={3-2}
-> NIL
: (? (db nm +Item Spare @Item) (show @Item)) # Search for "Spare.."
{3-2} (+Item)
pr 1250
inv 100
sup {2-2}
nm "Spare Part"
nr 2
@Item={3-2}
-> NIL
(db: cls ..) -> num
cls argument(s). Needed, for example, for the creation of new objects. See also dbs.
: (db: +Item)
-> 3
(dbSync) -> flg
lock on the database root object *DB, and then calling sync to synchronize with possible changes from
other processes. When all desired modifications to external symbols are done,
(commit 'upd) should be called. See
also Database.
(let? Obj (rd) # Get object?
(dbSync) # Yes: Start transaction
(put> Obj 'nm (rd)) # Update
(put> Obj 'nr (rd))
(put> Obj 'val (rd))
(commit 'upd) ) # Close transaction
(dbck ['cnt] 'flg) -> any
cnt'th)
database file, and returns NIL (or the number of blocks and symbols
if flg is non-NIL) if everything seems correct.
Otherwise, a string indicating an error is returned. As a side effect, possibly
unused blocks (as there might be when a rollback is done before commiting newly allocated (new) external symbols) are appended to the free
list.
: (pool "db")
-> T
: (dbck)
-> NIL
(dbs . lst)
*Dbs. Each element in lst has a
number in its CAR (the block size scale factor of a database file, to be stored
in *Dbs). The CDR elements are either classes (so that objects of
that class are later stored in the corresponding file), or lists with a class in
the CARs and a list of relations in the CDRs (so that index trees for these
relations go into that file). See also dbs+ and pool.
(dbs
(3 +Role +User +Sal) # 512 Prevalent objects
(0 +Pos) # A:64 Tiny objects
(1 +Item +Ord) # B:128 Small objects
(2 +CuSu) # C:256 Normal objects
(2 (+Role nm) (+User nm) (+Sal nm)) # D:256 Small indexes
(4 (+CuSu nr plz tel mob)) # E:1024 Normal indexes
(4 (+CuSu nm)) # F:1024
(4 (+CuSu ort)) # G:1024
(4 (+Item nr sup pr)) # H:1024
(4 (+Item nm)) # I:1024
(4 (+Ord nr dat cus)) # J:1024
(4 (+Pos itm)) ) # K:1024
: *Dbs
-> (1 2 1 0 2 4 4 4 4 4 4 4)
: (get '+Item 'Dbf)
-> (3 . 128)
: (get '+Item 'nr 'dbf)
-> (9 . 1024)
(dbs+ 'num . lst)
*Dbs. num is the initial offset
into the list. See also dbs.
(dbs+ 9
(1 +NewCls) # (9 . 128)
(3 (+NewCls nr nm)) ) # (10 . 512)
(de sym . any) -> sym
sym argument, by setting its
VAL to the any argument. If the symbol has already
another value, a "redefined" message is issued. When the value of the global
variable *Dbg is non-NIL, the current
line number and file name (if any) are stored in the *Dbg property
of sym. de is the standard way to define a function.
See also def, dm and undef.
: (de foo (X Y) (* X (+ X Y))) # Define a function
-> foo
: (foo 3 4)
-> 21
: (de *Var . 123) # Define a variable value
: *Var
-> 123
(debug 'sym) -> T
(debug 'sym 'cls) -> T
(debug '(sym . cls)) -> T
!
breakpoint function call at the beginning and all top-level expressions of the
function or method body of sym, to allow a stepwise execution.
Typing (d) at a breakpoint will also
debug the current subexpression, and (e)
will evaluate the current subexpression. The current subexpression is stored in
the global variable ^. See also unbug, *Dbg, trace and lint.
: (de tst (N) # Define tst
(println (+ 3 N)) )
-> tst
: (debug 'tst) # Set breakpoints
-> T
: (pp 'tst)
(de tst (N)
(! println (+ 3 N)) ) # Breakpoint '!'
-> tst
: (tst 7) # Execute
(println (+ 3 N)) # Stopped at beginning of 'tst'
! (d) # Debug subexpression
-> T
! # Continue
(+ 3 N) # Stopped in subexpression
! N # Inspect variable 'N'
-> 7
! # Continue
10 # Output of print statement
-> 10 # Done
: (unbug 'tst)
-> T
: (pp 'tst) # Restore to original
(de tst (N)
(println (+ 3 N)) )
-> tst
(dec 'num) -> num
(dec 'var ['num]) -> num
num decremented by 1. The
second form decrements the VAL of var by 1, or by
num. If the first argument is NIL, it is returned
immediately. (dec Num) is equivalent to (- Num 1) and
(dec 'Var) is equivalent to (set 'Var (- Var 1)). See
also inc and -.
: (dec -1)
-> -2
: (dec 7)
-> 6
: (setq N 7)
-> 7
: (dec 'N)
-> 6
: (dec 'N 3)
-> 3
(def 'sym 'any) -> sym
(def 'sym1 'sym2 'any) -> sym1
sym argument,
by setting its VAL's to any. The second form defines a
property value any for the first argument's sym2 key.
If any of these values existed and was changed in the process, a "redefined"
message is issued. When the value of the global variable *Dbg is non-NIL, the current line number
and file name (if any) are stored in the *Dbg property of
sym. See also de and
dm.
: (def 'b '((X Y) (* X (+ X Y))))
-> b
: (def 'b 999)
# b redefined
-> b
(default var 'any ..) -> any
any in the var arguments only if
their current values are NIL. Otherwise, their values are left
unchanged. In any case, the last var's value is returned.
default is used typically in functions to initialize optional
arguments.
: (de foo (A B) # Function with two optional arguments
(default A 1 B 2) # The default values are 1 and 2
(list A B) )
-> foo
: (foo 333 444) # Called with two arguments
-> (333 444)
: (foo 333) # Called with one arguments
-> (333 2)
: (foo) # Called without arguments
-> (1 2)
(del 'any 'var) -> lst
any from the list in the value of var, and
returns the remaining list. (del 'any 'var) is equivalent to
(set 'var (delete 'any var)). See also delete, cut and pop.
: (setq S '((a b c) (d e f)))
-> ((a b c) (d e f))
: (del '(d e f) 'S)
-> ((a b c))
: (del 'b S)
-> (a c)
(delete 'any 'lst) -> lst
any from lst. If any is
contained more than once in lst, only the first occurrence is
deleted. See also delq, remove and insert.
: (delete 2 (1 2 3))
-> (1 3)
: (delete (3 4) '((1 2) (3 4) (5 6) (3 4)))
-> ((1 2) (5 6) (3 4))
delete/3
delete and
member/2.
: (? (delete b (a b c) @X))
@X=(a c)
-> NIL
(delq 'any 'lst) -> lst
any from lst. If any is
contained more than once in lst, only the first occurrence is
deleted. == is used for comparison
(pointer equality). See also delete,
asoq, memq, mmeq and Comparing.
: (delq 'b '(a b c))
-> (a c)
: (delq (2) (1 (2) 3))
-> (1 (2) 3)
(dep 'cls) -> cls
cls, i.e. the
tree of superclasses and the tree of subclasses. See also OO Concepts, methods, class and can.
: (dep '+Number) # Dependencies of '+Number'
+relation # Single superclass is '+relation'
+Number
+Date # Subclasses are '+Date' and '+Time'
+Time
-> +Number
(depth 'lst) -> (cnt1 . cnt2)
cnt1) and the average (cnt2)
"depth" of a tree structure as maintained by idx. See also length and size.
: (off X) # Clear variable
-> NIL
: (for N (1 2 3 4 5 6 7) (idx 'X N T)) # Build a degenerated tree
-> NIL
: X
-> (1 NIL 2 NIL 3 NIL 4 NIL 5 NIL 6 NIL 7) # Only right branches
: (depth X)
-> (7 . 4) # Depth is 7, average 4
(diff 'lst 'lst) -> lst
lst arguments. See also sect.
: (diff (1 2 3 4 5) (2 4))
-> (1 3 5)
: (diff (1 2 3) (1 2 3))
-> NIL
different/2
equal/2.
: (? (different 3 4))
-> T
(dir ['any] ['flg]) -> lst
any. Names
starting with a dot '.' are ignored, unless flg is
non-NIL. See also cd and
info.
: (filter '((F) (tail '(. c) (chop F))) (dir "src/"))
-> ("main.c" "subr.c" "gc.c" "io.c" "big.c" "sym.c" "tab.c" "flow.c" ..
(dirname 'any) -> sym
any. See also
basename and path.
: (dirname "a/b/c/d")
-> "a/b/c/"
(dm sym . fun|cls2) -> sym
(dm (sym . cls) . fun|cls2) -> sym
(dm (sym sym2 [. cls]) . fun|cls2) -> sym
sym in the current class,
implicitly given by the value of the global variable *Class, or - in the second form - for the
explicitly given class cls. In the third form, the class object is
obtained by geting sym2
from *Class (or cls if
given). If the method for that class existed and was changed in the process, a
"redefined" message is issued. If - instead of a method fun - a
symbol specifying another class cls2 is given, the method from that
class is used (explicit inheritance). When the value of the global variable *Dbg is non-NIL, the current line number
and file name (if any) are stored in the *Dbg property of
sym. See also OO Concepts, de, undef, class, rel, var, method, send and try.
: (dm start> ()
(super)
(mapc 'start> (: fields))
(mapc 'start> (: arrays)) )
: (dm foo> . +OtherClass) # Explicitly inherit 'foo>' from '+OtherClass'
(do 'flg|num ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any
num times (or never (if the first argument is NIL), or
an infinite number of times (if the first argument is T)). If a
clause has NIL or T as its CAR, the clause's second
element is evaluated as a condition and - if the result is NIL or
non-NIL, respectively - the prg is executed and the
result returned. Otherwise (if count drops to zero), the result of the last
expression is returned. See also loop
and for.
: (do 4 (printsp 'OK))
OK OK OK OK -> OK
: (do 4 (printsp 'OK) (T (= 3 3) (printsp 'done)))
OK done -> done
(doc ['sym1] ['sym2])
sym1. sym2 may be the name of a
browser. If not given, the value of the environment variable
BROWSER, or the w3m browser is tried. If
sym1 is NIL, the PicoLisp
Reference manual is opened. See also Function
Reference and vi.
: (doc '+) # Function reference
-> T
: (doc '+relation) # Class reference
-> T
: (doc) # Reference manual
-> T
: (doc 'vi "firefox") # Use alternative browser
-> T
E
picolisp-3.1.5.2.orig/doc/refF.html 0000644 0000000 0000000 00000045330 12265263724 015472 0 ustar root root
*Err
prg body, which
will be executed during error processing. See also Error Handling, *Msg and ^.
: (de *Err (prinl "Fatal error!"))
-> ((prinl "Fatal error!"))
: (/ 3 0)
!? (/ 3 0)
Div/0
Fatal error!
$
*Ext
ext), and the CDR should be a function taking a
single external symbol as an argument. This function should return a list, with
the value for that symbol in its CAR, and the property list (in the format used
by getl and putl) in its CDR. The symbol will be set to
this value and property list upon access. Typically this function will access
the corresponding symbol in a remote database process. See also qsym and external symbols.
### On the local machine ###
: (setq *Ext # Define extension functions
(mapcar
'((@Host @Ext)
(cons @Ext
(curry (@Host @Ext (Sock)) (Obj)
(when (or Sock (setq Sock (connect @Host 4040)))
(ext @Ext
(out Sock (pr (cons 'qsym Obj)))
(prog1 (in Sock (rd))
(unless @
(close Sock)
(off Sock) ) ) ) ) ) ) )
'("10.10.12.1" "10.10.12.2" "10.10.12.3" "10.10.12.4")
(20 40 60 80) ) )
### On the remote machines ###
(de go ()
...
(task (port 4040) # Set up background query server
(let? Sock (accept @) # Accept a connection
(unless (fork) # In child process
(in Sock
(while (rd) # Handle requests
(sync)
(out Sock
(pr (eval @)) ) ) )
(bye) ) # Exit child process
(close Sock) ) )
(forked) # Close task in children
...
+Entity
+relation and Database.
zap> () # Clean up relational structures, for removal from the DB
url> (Tab) # Call the GUI on that object (in optional Tab)
upd> (X Old) # Callback method when object is created/modified/deleted
has> (Var Val) # Check if value is present
put> (Var Val) # Put a new value
put!> (Var Val) # Put a new value, single transaction
del> (Var Val) # Delete value (also partial)
del!> (Var Val) # Delete value (also partial), single transaction
inc> (Var Val) # Increment numeric value
inc!> (Var Val) # Increment numeric value, single transaction
dec> (Var Val) # Decrement numeric value
dec!> (Var Val) # Decrement numeric value, single transaction
mis> (Var Val) # Return error message if value or type mismatch
lose1> (Var) # Delete relational structures for a single attribute
lose> (Lst) # Delete relational structures (excluding 'Lst')
lose!> () # Delete relational structures, single transaction
keep1> (Var) # Restore relational structures for single attribute
keep> (Lst) # Restore relational structures (excluding 'Lst')
keep?> (Lst) # Test for restauration (excluding 'Lst')
keep!> () # Restore relational structures, single transaction
set> (Val) # Set the value (type, i.e. class list)
set!> (Val) # Set the value, single transaction
clone> () # Object copy
clone!> () # Object copy, single transaction
(e . prg) -> any
prg in the execution
environment, or the currently executed expression if prg is not
given. See also debug, !, ^ and
*Dbg.
: (! + 3 4)
(+ 3 4)
! (e)
-> 7
(echo ['cnt ['cnt]] | ['sym ..]) -> sym
cnt is given, only that many bytes are actually echoed. In case
of two cnt arguments, the first one specifies the number of bytes
to skip in the input stream. Otherwise, if one or more sym
arguments are given, the echo process stops as soon as one of the symbol's names
is encountered in the input stream. In this case the name will be read and
returned, but not written. Returns non-NIL if the operation was
successfully completed. See also from.
: (in "x.l" (echo)) # Display file on console
..
: (out "x2.l" (in "x.l" (echo))) # Copy file "x.l" to "x2.l"
(edit 'sym ..) -> NIL
vim editor on a temporary file with these
data. When closing the editor, the modified data are read and stored into the
symbol(s). During the edit session, individual symbols are separated by the
pattern (********). These separators should not be modified. When
moving the cursor to the beginning of a symbol (no matter if internal, transient
or external), and hitting 'K', that symbol is added to the
currently edited symbols. Hitting 'Q' will go back one step and
return to the previously edited list of symbols.
edit is especially useful for browsing through the database
(with 'K' and 'Q'), inspecting external symbols, but
care must be taken when modifying any data as then the entity/relation mechanisms are circumvented, and
commit has to be called manually if
the changes should be persistent.
! breakpoints at arbitrary code locations, or
doing other temporary changes to the code for debugging purposes.
update, show, vi and em.
: (edit (db 'nr '+Item 1)) # Edit a database symbol
### 'vim' shows this ###
{3-1} (+Item)
nr 1
inv 100
pr 29900
sup {2-1} # (+CuSu)
nm "Main Part"
(********)
### Hitting 'K' on the '{' of '{2-1} ###
{2-1} (+CuSu)
nr 1
plz "3425"
mob "37 176 86303"
tel "37 4967 6846-0"
fax "37 4967 68462"
nm "Active Parts Inc."
nm2 "East Division"
ort "Freetown"
str "Wildcat Lane"
em "info@api.tld"
(********)
{3-1} (+Item)
nr 1
inv 100
pr 29900
sup {2-1} # (+CuSu)
nm "Main Part"
(********)
### Entering ':q' in vim ###
-> NIL
(em 'sym) -> sym
(em 'sym 'cls) -> sym
(em '(sym . cls)) -> sym
(em) -> NIL
sym. A call to ld thereafter will load the modified file. A call without
arguments permanently switches the REPL line editor and the edit function to "emacs" mode. See also
doc, edit, vi, *Dbg, debug and pp.
: (em 'url> '+CuSu) # Edit the method's source code, then exit from 'emacs'
-> T
(env ['lst] | ['sym 'val] ..) -> lst
lst, or the explicitly given sym-val
arguments. See also bind, job, trail and up.
: (env)
-> NIL
: (let (A 1 B 2) (env))
-> ((A . 1) (B . 2))
: (let (A 1 B 2) (env '(A B)))
-> ((B . 2) (A . 1))
: (let (A 1 B 2) (env 'X 7 '(A B (C . 3)) 'Y 8))
-> ((Y . 8) (C . 3) (B . 2) (A . 1) (X . 7))
(eof ['flg]) -> flg
flg is non-NIL, the channel's status is forced to
end-of-file, so that the next call to eof will return
T, and calls to char,
peek, line, from, till, read or skip will return NIL. Note that
eof cannot be used with the binary rd function. See also eol.
: (in "file" (until (eof) (println (line T))))
...
(eol) -> flg
eof.
: (make (until (prog (link (read)) (eol)))) # Read line into a list
a b c (d e f) 123
-> (a b c (d e f) 123)
equal/2
=, different/2 and member/2.
: (? (equal 3 4))
-> NIL
: (? (equal @N 7))
@N=7
-> NIL
(err 'sym . prg) -> any
sym during the execution
of prg. The current standard error stream will be saved and
restored appropriately. If the argument is NIL, the current output
stream will be used. Otherwise, sym is taken as a file name (opened
in "append" mode if the first character is "+"), where standard error is to be
written to. See also in, out and ctl.
: (err "/dev/null" # Suppress error messages
(call 'ls 'noSuchFile) )
-> NIL
(errno) -> cnt
native.
: (in "foo") # Produce an error
!? (in "foo")
"foo" -- Open error: No such file or directory
? (errno)
-> 2 # Returned 'ENOENT'
(eval 'any ['cnt ['lst]]) -> any
any. Note that because of the standard argument
evaluation, any is actually evaluated twice. If a binding
environment offset cnt is given, the second evaluation takes place
in the corresponding environment, and an optional lst of excluded
symbols can be supplied. See also run
and up.
: (eval (list '+ 1 2 3))
-> 6
: (setq X 'Y Y 7)
-> 7
: X
-> Y
: Y
-> 7
: (eval X)
-> 7
(expDat 'sym) -> dat
date string according to
the current locale (delimiter, and
order of year, month and day). Accepts abbreviated input, without delimiter and
with only the day, or the day and month, or the day, month and year of current
century. See also datStr, day, expTel.
: (date)
-> 733133
: (date (date))
-> (2007 5 31)
: (expDat "31")
-> 733133
: (expDat "315")
-> 733133
: (expDat "3105")
-> 733133
: (expDat "31057")
-> 733133
: (expDat "310507")
-> 733133
: (expDat "2007-05-31")
-> 733133
: (expDat "7-5-31")
-> 733133
: (locale "DE" "de")
-> NIL
: (expDat "31.5")
-> 733133
: (expDat "31.5.7")
-> 733133
(expTel 'sym) -> sym
+ or 00 is removed, a leading 0
is replaced with the current country code. Otherwise, NIL is
returned. See also telStr, expDat and locale.
: (expTel "+49 1234 5678-0")
-> "49 1234 5678-0"
: (expTel "0049 1234 5678-0")
-> "49 1234 5678-0"
: (expTel "01234 5678-0")
-> NIL
: (locale "DE" "de")
-> NIL
: (expTel "01234 5678-0")
-> "49 1234 5678-0"
(expr 'sym) -> fun
subr.
: car
-> 67313448
: (expr 'car)
-> (@ (pass $385260187))
: (car (1 2 3))
-> 1
(ext 'cnt . prg) -> any
prg, all external symbols processed by rd, pr or
udp are modified by an offset
cnt suitable for mapping via the *Ext mechanism. All external symbol's file
numbers are decremented by cnt during output, and incremented by
cnt during input.
: (out 'a (ext 5 (pr '({6-2} ({8-9} . a) ({7-7} . b)))))
-> ({6-2} ({8-9} . a) ({7-7} . b))
: (in 'a (rd))
-> ({2} ({3-9} . a) ({2-7} . b))
: (in 'a (ext 5 (rd)))
-> ({6-2} ({8-9} . a) ({7-7} . b))
(ext? 'any) -> sym | NIL
any when it is an existing external
symbol, otherwise NIL. See also sym?, box?, str?, extern and lieu.
: (ext? *DB)
-> {1}
: (ext? 'abc)
-> NIL
: (ext? "abc")
-> NIL
: (ext? 123)
-> NIL
(extend cls) -> cls
cls, by storing it in the global variable
*Class. As a consequence, all
following method, relation and class variable definitions are applied to that
class. See also OO Concepts, class, dm, var,
rel, type and isa.
(extern 'sym) -> sym | NIL
sym is already extern, it is returned. Otherwise, a new external
symbol is returned. NIL is returned if sym does not
exist in the database. See also intern and ext?.
: (extern "A1b")
-> {A1b}
: (extern "{A1b}")
-> {A1b}
(extra ['any ..]) -> any
This, this time starting the search for a method at the
remaining branches of the inheritance tree of the class where the current method
was found. See also OO Concepts, super, method, meth, send and try.
(dm key> (C) # 'key>' method of the '+Uppc' class
(uppc (extra C)) ) # Convert 'key>' of extra classes to upper case
(extract 'fun 'lst ..) -> lst
fun to each element of lst. When
additional lst arguments are given, their elements are also passed
to fun. Returns a list of all non-NIL values returned
by fun. (extract 'fun 'lst) is equivalent to
(mapcar 'fun (filter 'fun 'lst)) or, for non-NIL results, to
(mapcan '((X) (and (fun X) (cons @))) 'lst). See also filter, find, pick and mapcan.
: (setq A NIL B 1 C NIL D 2 E NIL F 3)
-> 3
: (filter val '(A B C D E F))
-> (B D F)
: (extract val '(A B C D E F))
-> (1 2 3)
F
picolisp-3.1.5.2.orig/doc/refG.html 0000644 0000000 0000000 00000014570 12265263724 015475 0 ustar root root
*Fork
prg body, to be
executed after a call to fork in the
child process.
: (push '*Fork '(off *Tmp)) # Clear '*Tmp' in child process
-> (off *Tmp)
+Fold
folded indexes to +String relations. Typically used in
combination with the +Ref or +Idx prefix classes. See also +IdxFold and Database.
(rel nm (+Fold +Idx +String)) # Item Description
...
(rel tel (+Fold +Ref +String)) # Phone number
(fail) -> lst
goal.
(dm clr> () # Clear query chart in search dialogs
(query> This (fail)) )
fail/0
true/0.
: (? (fail))
-> NIL
(fetch 'tree 'any) -> any
any from a database tree. See also
tree and store.
: (fetch (tree 'nr '+Item) 2)
-> {3-2}
(fifo 'var ['any ..]) -> any
any arguments, they will be concatenated to end of the
structure. Otherwise, the first element is removed from the structure and
returned. See also queue, push, pop, rot and circ.
: (fifo 'X 1)
-> 1
: (fifo 'X 2 3)
-> 3
: X
-> (3 1 2 .)
: (fifo 'X)
-> 1
: (fifo 'X)
-> 2
: X
-> (3 .)
(file) -> (sym1 sym2 . num) | NIL
sym1, the
file name sym2, and the current line number num. If
the current input channel is not a file, NIL is returned. See also
info, in and load.
: (load (pack (car (file)) "localFile.l")) # Load a file in same directory
(fill 'any ['sym|lst]) -> any
any, by substituting
sym, or all symbols in lst, or - if no second argument
is given - each pattern symbol in any (see pat?), with its current value. @
itself is not considered a pattern symbol here. Unmodified subexpressions are
shared. In any case, expressions following the symbol ^ should
evaluate to lists which are then (destructively) spliced into the result. See
also match.
: (setq @X 1234 @Y (1 2 3 4))
-> (1 2 3 4)
: (fill '@X)
-> 1234
: (fill '(a b (c @X) ((@Y . d) e)))
-> (a b (c 1234) (((1 2 3 4) . d) e))
: (let X 2 (fill (1 X 3) 'X))
-> (1 2 3)
: (fill (1 ^ (list 'a 'b 'c) 9))
-> (1 a b c 9)
: (match '(This is @X) '(This is a pen))
-> T
: (fill '(Got ^ @X))
-> (Got a pen)
(filter 'fun 'lst ..) -> lst
fun to each element of lst. When
additional lst arguments are given, their elements are also passed
to fun. Returns a list of all elements of lst where
fun returned non-NIL. See also fish, find, pick and extract.
: (filter num? (1 A 2 (B) 3 CDE))
-> (1 2 3)
(fin 'any) -> num|sym
any if it is an atom, otherwise the CDR of its last
cell. See also last and tail.
: (fin 'a)
-> a
: (fin '(a . b))
-> b
: (fin '(a b . c))
-> c
: (fin '(a b c))
-> NIL
(finally exe . prg) -> any
prg is executed, then exe is evaluated, and the
result of prg is returned. exe will also be evaluated
if prg does not terminate normally due to a runtime error or a call
to throw. See also bye, catch, quit and Error
Handling.
: (finally (prinl "Done!")
(println 123)
(quit)
(println 456) )
123
Done!
: (catch 'A
(finally (prinl "Done!")
(println 1)
(throw 'A 123)
(println 2) ) )
1
Done!
-> 123
(find 'fun 'lst ..) -> any
fun to successive elements of lst until
non-NIL is returned. Returns that element, or NIL if
fun did not return non-NIL for any element of
lst. When additional lst arguments are given, their
elements are also passed to fun. See also seek, pick and filter.
: (find pair (1 A 2 (B) 3 CDE))
-> (B)
: (find '((A B) (> A B)) (1 2 3 4 5 6) (6 5 4 3 2 1))
-> 4
: (find > (1 2 3 4 5 6) (6 5 4 3 2 1)) # shorter
-> 4
(fish 'fun 'any) -> lst
fun to each element - and recursively to all sublists -
of any. Returns a list of all items where fun returned
non-NIL. See also filter.
: (fish gt0 '(a -2 (1 b (-3 c 2)) 3 d -1))
-> (1 2 3)
: (fish sym? '(a -2 (1 b (-3 c 2)) 3 d -1))
-> (a b c d)
(flg? 'any) -> flg
T when the argument any is either
NIL or T. See also bool. (flg? X) is equivalent to
(or (not X) (=T X)).
: (flg? (= 3 3))
-> T
: (flg? (= 3 4))
-> T
: (flg? (+ 3 4))
-> NIL
(flip 'lst ['cnt]) -> lst
lst (destructively) reversed. Without the optional
cnt argument, the whole list is flipped, otherwise only the first
cnt elements. See also reverse and rot.
: (flip (1 2 3 4)) # Flip all four elements
-> (4 3 2 1)
: (flip (1 2 3 4 5 6) 3) # Flip only the first three elements
-> (3 2 1 4 5 6)
(flush) -> flg
flush for standard output is done automatically before a call to
key. Returns T when
successful. See also rewind.
: (flush)
-> T
(fmt64 'num) -> sym
(fmt64 'sym) -> num
num to a string in base-64 notation, or a
base-64 formatted string to a number. The digits are represented with the
characters 0 - 9, :, ;,
A - Z and a - z. This format
is used internally for the names of external symbols in the 32-bit version.
See also hax, hex, bin and oct.
: (fmt64 9)
-> "9"
: (fmt64 10)
-> ":"
: (fmt64 11)
-> ";"
: (fmt64 12)
-> "A"
: (fmt64 "100")
-> 4096
(fold 'any ['cnt]) -> sym
any is not a symbol, it is
returned as it is. Otherwise, a new transient symbol with all digits and all
letters of any, converted to lower case, is returned. If the
cnt argument is given and non-zero, the result is truncated to that
length. See also lowc.
: (fold " 1A 2-b/3")
-> "1a2b3"
: (fold " 1A 2-B/3" 3)
-> "1a2"
fold/3
folding it to a
canonical form, is a prefix of the folded string representation of the
result of applying the get algorithm to
the following arguments. Typically used as filter predicate in select/3 database queries. See also
pre?, isa/2, same/3, bool/3, range/3, head/3, part/3 and tolr/3.
: (?
@Nr (1 . 5)
@Nm "main"
(select (@Item)
((nr +Item @Nr) (nm +Item @Nm))
(range @Nr @Item nr)
(fold @Nm @Item nm) ) )
@Nr=(1 . 5) @Nm="main" @Item={3-1}
-> NIL
(for sym 'num ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any
(for sym|(sym2 . sym) 'lst ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any
(for (sym|(sym2 . sym) 'any1 'any2 [. prg]) ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any
In the first form, the value of sym is saved, sym is
bound to 1, and the body is executed with increasing values up to
(and including) num.
In the second form, the value of sym is saved, sym is
subsequently bound to the elements of lst, and the body is executed
each time.
In the third form, the value of sym is saved, and sym
is bound to any1. If sym2 is given, it is treated as a
counter variable, first bound to 1 and then incremented for each execution of
the body. While the condition any2 evaluates to
non-NIL, the body is repeatedly executed and, if prg
is given, sym is re-bound to the result of its evaluation.
If a clause has NIL or T as its CAR, the clause's
second element is evaluated as a condition and - if the result is
NIL or non-NIL, respectively - the prg is
executed and the result returned. If the body is never executed,
NIL is returned.
See also do and loop.
# First form:
: (for N 5 (printsp N))
1 2 3 4 5 -> 5
: (for N 5 (printsp N) (NIL (< N 3) (printsp 'enough)))
1 2 3 enough -> enough
: (for N 5 (T (> N 3) (printsp 'enough)) (printsp N))
1 2 3 enough -> enough
# Second form:
: (for X (1 a 2 b) (printsp X))
1 a 2 b -> b
: (for (I . X) '(a b c) (println I X))
1 a
2 b
3 c
-> c
# Third form:
: (for (L (1 2 3 4 5) L) (printsp (pop 'L)))
1 2 3 4 5 -> 5
: (for (N 1 (>= 5 N) (inc N)) (printsp N))
1 2 3 4 5 -> 5
: (for ((I . L) '(a b c d e f) L (cddr L)) (println I L))
1 (a b c d e f)
2 (c d e f)
3 (e f)
-> (e f)
for/2
for/3
for/4
for and range.
: (? (for @I 3))
@I=1
@I=2
@I=3
-> NIL
: (? (for @I 3 7))
@I=3
@I=4
@I=5
@I=6
@I=7
-> NIL
: (? (for @I 7 3 2))
@I=7
@I=5
@I=3
-> NIL
(fork) -> pid | NIL
NIL in the child, and the
child's process ID pid in the parent. In the child, the
VAL of the global variable *Fork (should be a prg) is
executed. See also pipe and tell.
: (unless (fork) (do 5 (println 'OK) (wait 1000)) (bye))
-> NIL
OK # Child's output
: OK
OK
OK
OK
(forked)
*Fork to close server sockets and clean up
*Run code in child processes. Should
only be called immediately after task.
: (task -60000 60000 (msg 'OK)) # Install timer task
-> (-60000 60000 (msg 'OK))
: (forked) # No timer in child processes
-> (task -60000)
: *Run
-> ((-60000 56432 (msg 'OK)))
: *Fork
-> ((task -60000) (del '(saveHistory) '*Bye))
(format 'num ['cnt ['sym1 ['sym2]]]) -> sym
(format 'sym|lst ['cnt ['sym1 ['sym2]]]) -> num
num to a string, or a string
sym|lst to a number. In both cases, optionally a precision
cnt, a decimal-separator sym1 and a
thousands-separator sym2 can be supplied. Returns NIL
if the conversion is unsuccessful. See also Numbers and round.
: (format 123456789) # Integer conversion
-> "123456789"
: (format 123456789 2) # Fixed point
-> "1234567.89"
: (format 123456789 2 ",") # Comma as decimal-separator
-> "1234567,89"
: (format 123456789 2 "," ".") # and period as thousands-separator
-> "1.234.567,89"
: (format "123456789") # String to number
-> 123456789
: (format (1 "23" (4 5 6)))
-> 123456
: (format "1234567.89" 4) # scaled to four digits
-> 12345678900
: (format "1.234.567,89") # separators not recognized
-> NIL
: (format "1234567,89" 4 ",")
-> 12345678900
: (format "1.234.567,89" 4 ",") # thousands-separator not recognized
-> NIL
: (format "1.234.567,89" 4 "," ".")
-> 12345678900
(free 'cnt) -> (sym . lst)
cnt'th database file, the next available
symbol sym (i.e. the first symbol greater than any symbol in the
database), and the list lst of free symbols. See also seq, zap and dbck.
: (pool "x") # A new database
-> T
: (new T) # Create a new symbol
-> {2}
: (new T) # Create another symbol
-> {3}
: (commit) # Commit changes
-> T
: (zap '{2}) # Delete the first symbol
-> {2}
: (free 1) # Show free list
-> ({4}) # {3} was the last symbol allocated
: (commit) # Commit the deletion of {2}
-> T
: (free 1) # Now {2} is in the free list
-> ({4} {2})
(from 'any ..) -> sym
any is
found, and starts subsequent reading from that point. The found any
argument, or NIL (if none is found) is returned. See also till and echo.
: (and (from "val='") (till "'" T))
test val='abc'
-> "abc"
(full 'any) -> bool
NIL if any is a non-empty list with at
least one NIL element, otherwise T. (full
X) is equivalent to (not (memq NIL X)).
: (full (1 2 3))
-> T
: (full (1 NIL 3))
-> NIL
: (full 123)
-> T
(fun? 'any) -> any
NIL when the argument any is neither a
number suitable for a code-pointer, nor a list suitable for a lambda expression
(function). Otherwise a number is returned for a code-pointer, T
for a function without arguments, and a single formal parameter or a list of
formal parameters for a function. See also getd.
: (fun? 1000000000) # Might be a code pointer
-> 1000000000
: (fun? 100000000000000) # Too big for a code pointer
-> NIL
: (fun? 1000000001) # Cannot be a code pointer (odd)
-> NIL
: (fun? '((A B) (* A B))) # Lambda expression
-> (A B)
: (fun? '((A B) (* A B) . C)) # Not a lambda expression
-> NIL
: (fun? '(1 2 3 4)) # Not a lambda expression
-> NIL
: (fun? '((A 2 B) (* A B))) # Not a lambda expression
-> NIL
G
picolisp-3.1.5.2.orig/doc/refH.html 0000644 0000000 0000000 00000020202 12265263724 015463 0 ustar root root
(gc ['cnt [cnt2]]) -> cnt | NIL
cnt is given, so many
megabytes of free cells are reserved, increasing the heap size if necessary. If
cnt is zero, all currently unused heap blocks are purged,
decreasing the heap size if possible. If cnt2 (64-bit version only)
is given, the reserve size (defaults to 1 megabyte) is set to that value. See
also heap.
: (gc)
-> NIL
: (heap)
-> 2
: (gc 4)
-> 4
: (heap)
-> 5
(ge0 'any) -> num | NIL
num when the argument is a number and greater or equal
zero, otherwise NIL. See also lt0, le0, gt0, =0
and n0.
: (ge0 -2)
-> NIL
: (ge0 3)
-> 3
: (ge0 0)
-> 0
(genKey 'var 'cls ['hook ['num1 ['num2]]]) -> num
num1
and/or a maximal key num2 is given, the next free number in that
range is returned. Otherwise, the current maximal key plus one is returned. See
also useKey, genStrKey and maxKey.
: (maxKey (tree 'nr '+Item))
-> 8
: (genKey 'nr '+Item)
-> 9
(genStrKey 'sym 'var 'cls ['hook]) -> sym
genKey.
: (genStrKey "ben" 'nm '+User)
-> "# ben"
(get 'sym1|lst ['sym2|cnt ..]) -> any
any from the properties of a symbol, or from a
list. From the first argument sym1|lst, values are retrieved in
successive steps by either extracting the value (if the next argument is zero)
or a property from a symbol, the asoqed element (if the next argument is a
symbol), the n'th element (if the next argument is a positive number) or the
n'th CDR (if the next argument is a negative number) from a list. See also
put, ; and :.
: (put 'X 'a 1)
-> 1
: (get 'X 'a)
-> 1
: (put 'Y 'link 'X)
-> X
: (get 'Y 'link)
-> X
: (get 'Y 'link 'a)
-> 1
: (get '((a (b . 1) (c . 2)) (d (e . 3) (f . 4))) 'a 'b)
-> 1
: (get '((a (b . 1) (c . 2)) (d (e . 3) (f . 4))) 'd 'f)
-> 4
: (get '(X Y Z) 2)
-> Y
: (get '(X Y Z) 2 'link 'a)
-> 1
(getd 'any) -> fun | NIL
fun if any is a symbol that has a function
definition, otherwise NIL. See also fun?.
: (getd '+)
-> 67327232
: (getd 'script)
-> ((File . @) (load File))
: (getd 1)
-> NIL
(getl 'sym1|lst1 ['sym2|cnt ..]) -> lst
lst from a symbol. That
symbol is sym1 (if no other arguments are given), or a symbol found
by applying the get algorithm to
sym1|lst1 and the following arguments. See also putl and maps.
: (put 'X 'a 1)
-> 1
: (put 'X 'b 2)
-> 2
: (put 'X 'flg T)
-> T
: (getl 'X)
-> (flg (2 . b) (1 . a))
(glue 'any 'lst) -> sym
packing the any argument between
the individual elements of lst. See also text.
: (glue "," '(a b c d))
-> "a,b,c,d"
(goal '([pat 'any ..] . lst) ['sym 'any ..]) -> lst
lst. The head of the argument list may consist of a
sequence of pattern symbols (Pilog variables) and expressions, which are used
together with the optional sym and any arguments to
form an initial environment. See also prove and fail.
: (goal '((likes John @X)))
-> (((1 (0) NIL ((likes John @X)) NIL T)))
: (goal '(@X 'John (likes @X @Y)))
-> (((1 (0) NIL ((likes @X @Y)) NIL ((0 . @X) 1 . John) T)))
(group 'lst) -> lst
lst with
the same CAR into a common sublist. See also Comparing, by, sort and uniq.
: (group '((1 . a) (1 . b) (1 . c) (2 . d) (2 . e) (2 . f)))
-> ((1 a b c) (2 d e f))
: (by name group '("x" "x" "y" "z" "x" "z")))
-> (("x" "x" "x") ("y") ("z" "z"))
: (by length group '(123 (1 2) "abcd" "xyz" (1 2 3 4) "XY"))
-> ((123 "xyz") ((1 2) "XY") ("abcd" (1 2 3 4))
(gt0 'any) -> num | NIL
num when the argument is a number and greater than
zero, otherwise NIL. See also lt0, le0, ge0, =0
and n0.
: (gt0 -2)
-> NIL
: (gt0 3)
-> 3
H
picolisp-3.1.5.2.orig/doc/refI.html 0000644 0000000 0000000 00000036576 12265263724 015511 0 ustar root root
*Hup
prg body, which will
be executed when a SIGHUP signal is sent to the current process. See also
alarm, sigio and *Sig[12].
: (de *Hup (msg 'SIGHUP))
-> *Hup
+Hook
+relations,
typically +Link or +Joint. In essence, this maintains an local
database in the referred object. See also Database.
(rel sup (+Hook +Link) (+Sup)) # Supplier
(rel nr (+Key +Number) sup) # Item number, unique per supplier
(rel dsc (+Ref +String) sup) # Item description, indexed per supplier
+Hook2
+index
relations. It maintains both a normal (global) index, and an object-local index
in the corresponding +Hook object.
See also Database.
(rel nm (+Hook2 +IdxFold +String) 3 shop) # Global and shop-local index
(hash 'any) -> cnt
any, suitable as a
hash value for various purposes, like randomly balanced idx structures. See also cache and seed.
: (hash 0)
-> 1
: (hash 1)
-> 55682
: (hash "abc")
-> 45454
(hax 'num) -> sym
(hax 'sym) -> num
num to a string in hexadecimal/alpha
notation, or a hexadecimal/alpha formatted string to a number. The digits are
represented with '@' (zero) and the letters 'A' -
'O' (from "alpha" to "omega"). This format is used internally for
the names of external symbols in
the 64-bit version. See also fmt64,
hex, bin and oct.
: (hax 7)
-> "G"
: (hax 16)
-> "A@"
: (hax 255)
-> "OO"
: (hax "A")
-> 1
(hd 'sym ['cnt]) -> NIL
sym, limited to cnt lines. See also proc.
: (hd "lib.l" 4)
00000000 23 20 32 33 64 65 63 30 39 61 62 75 0A 23 20 28 # 23dec09abu.# (
00000010 63 29 20 53 6F 66 74 77 61 72 65 20 4C 61 62 2E c) Software Lab.
00000020 20 41 6C 65 78 61 6E 64 65 72 20 42 75 72 67 65 Alexander Burge
00000030 72 0A 0A 28 64 65 20 74 61 73 6B 20 28 4B 65 79 r..(de task (Key
-> NIL
(head 'cnt|lst 'lst) -> lst
cnt elements of
lst. If cnt is negative, it is added to the length of
lst. If the first argument is a lst, head
is a predicate function returning that argument list if it is equal
to the head of the second argument, and NIL otherwise. See also
tail.
: (head 3 '(a b c d e f))
-> (a b c)
: (head 0 '(a b c d e f))
-> NIL
: (head 10 '(a b c d e f))
-> (a b c d e f)
: (head -2 '(a b c d e f))
-> (a b c d)
: (head '(a b c) '(a b c d e f))
-> (a b c)
head/3
get algorithm to the
following arguments. Typically used as filter predicate in select/3 database queries. See also
pre?, isa/2, same/3, bool/3, range/3, fold/3, part/3 and tolr/3.
: (?
@Nm "Muller"
@Tel "37"
(select (@CuSu)
((nm +CuSu @Nm) (tel +CuSu @Tel))
(tolr @Nm @CuSu nm)
(head @Tel @CuSu tel) )
(val @Name @CuSu nm)
(val @Phone @CuSu tel) )
@Nm="Muller" @Tel="37" @CuSu={2-3} @Name="Miller" @Phone="37 4773 82534"
-> NIL
(heap 'flg) -> cnt
flg is non-NIL, the size of the currently free space
is returned. See also stack and
gc.
: (gc 4)
-> 4
: (heap)
-> 5
: (heap T)
-> 4
(hear 'cnt) -> cnt
cnt as an asynchronous command input
channel. Any executable list received via this channel will be executed in the
background. As this mechanism is also used for inter-family communication (see
tell), hear is usually
only called explicitly by a top level parent process.
: (call 'mkfifo "fifo/cmd")
-> T
: (hear (open "fifo/cmd"))
-> 3
(here ['sym]) -> sym
sym is encountered, or
until end of file. See also echo.
$ cat hello.l
(html 0 "Hello" "lib.css" NIL
(<h2> NIL "Hello")
(here) )
<p>Hello!</p>
<p>This is a test.</p>
$ pil @lib/http.l @lib/xhtml.l hello.l
HTTP/1.0 200 OK
Server: PicoLisp
Date: Sun, 03 Jun 2007 11:41:27 GMT
Cache-Control: max-age=0
Cache-Control: no-cache
Content-Type: text/html; charset=utf-8
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Hello</title>
<link rel="stylesheet" href="http://:/lib.css" type="text/css"/>
</head>
<body><h2>Hello</h2>
<p>Hello!</p>
<p>This is a test.</p>
</body>
</html>
(hex 'num ['num]) -> sym
(hex 'sym) -> num
num to a hexadecimal string, or a hexadecimal
string sym to a number. In the first case, if the second argument
is given, the result is separated by spaces into groups of such many digits. See
also bin, oct, fmt64, hax and format.
: (hex 273)
-> "111"
: (hex "111")
-> 273
: (hex 1234567 4)
-> "12 D687"
(host 'any) -> sym
*Adr.
: (host "80.190.158.9")
-> "www.leo.org"
I
picolisp-3.1.5.2.orig/doc/refJ.html 0000644 0000000 0000000 00000005021 12265263724 015467 0 ustar root root
+Idx
+String relations, a subclass of +Ref. Accepts optional arguments for the
minimally indexed substring length (defaults to 3), and a +Hook attribute. Often used in combination
with the +Sn soundex index, or the
+Fold index prefix classes. See also
Database.
(rel nm (+Sn +Idx +String)) # Name
+IdxFold
folded individual words of
+String relations. Accepts optional
arguments for the minimally indexed substring length (defaults to 3), and a
+Hook attribute. See also +Idx and Database.
(rel nm (+IdxFold +String)) # Item Description
+index
+relations). The class
hierarchy includes +Key, +Ref, +Idx and +IdxFold. See also Database.
(isa '+index Rel) # Check for an index relation
(id 'num ['num]) -> sym
(id 'sym [NIL]) -> num
(id 'sym T) -> (num . num)
: (id 7)
-> {7}
: (id 1 2)
-> {2}
: (id '{1-2})
-> 2
: (id '{1-2} T)
-> (1 . 2)
(idx 'var 'any 'flg) -> lst
(idx 'var 'any) -> lst
(idx 'var) -> lstvar, and checks for the existence of
any. If any is contained in var, the
corresponding subtree is returned, otherwise NIL. In the first
form, any is destructively inserted into the tree if
flg is non-NIL (and any was not already
there), or deleted from the tree if flg is NIL. The
second form only checks for existence, but does not change the index tree. In
the third form (when called with a single var argument) the
contents of the tree are returned as a sorted list. If all elements are inserted
in sorted order, the tree degenerates into a linear list. See also lup, hash, depth, sort, balance and member.
: (idx 'X 'd T) # Insert data
-> NIL
: (idx 'X 2 T)
-> NIL
: (idx 'X '(a b c) T)
-> NIL
: (idx 'X 17 T)
-> NIL
: (idx 'X 'A T)
-> NIL
: (idx 'X 'd T)
-> (d (2 NIL 17 NIL A) (a b c)) # 'd' already existed
: (idx 'X T T)
-> NIL
: X # View the index tree
-> (d (2 NIL 17 NIL A) (a b c) NIL T)
: (idx 'X 'A) # Check for 'A'
-> (A)
: (idx 'X 'B) # Check for 'B'
-> NIL
: (idx 'X)
-> (2 17 A d (a b c) T) # Get list
: (idx 'X 17 NIL) # Delete '17'
-> (17 NIL A)
: X
-> (d (2 NIL A) (a b c) NIL T) # View it again
: (idx 'X)
-> (2 A d (a b c) T) # '17' is deleted
(if 'any1 'any2 . prg) -> any
any1 evaluates to
non-NIL, any2 is evaluated and returned. Otherwise,
prg is executed and the result returned. See also cond, when and if2.
: (if (> 4 3) (println 'OK) (println 'Bad))
OK
-> OK
: (if (> 3 4) (println 'OK) (println 'Bad))
Bad
-> Bad
(if2 'any1 'any2 'any3 'any4 'any5 . prg) -> any
any1 and any2 evaluate to non-NIL,
any3 is evaluated and returned. Otherwise, any4 or
any5 is evaluated and returned if any1 or
any2 evaluate to non-NIL, respectively. If none of the
conditions evaluate to non-NIL, prg is executed and
the result returned. See also if and
cond.
: (if2 T T 'both 'first 'second 'none)
-> both
: (if2 T NIL 'both 'first 'second 'none)
-> first
: (if2 NIL T 'both 'first 'second 'none)
-> second
: (if2 NIL NIL 'both 'first 'second 'none)
-> none
(ifn 'any1 'any2 . prg) -> any
any1
evaluates to NIL, any2 is evaluated and returned.
Otherwise, prg is executed and the result returned.
: (ifn (= 3 4) (println 'OK) (println 'Bad))
OK
-> OK
(import . lst) -> NIL
intern.
Typically used to import symbols from other namespaces, as created by symbols. lst should be a list
of symbols. An import conflict error is issued when a symbol with the same name
already exists in the current namespace. See also pico and local.
: (import libA~foo libB~bar)
-> NIL
(in 'any . prg) -> any
any as input channel during the execution of
prg. The current input channel will be saved and restored
appropriately. If the argument is NIL, standard input is used. If
the argument is a symbol, it is used as a file name (opened for reading
and writing if the first character is "+"). If it is a
positive number, it is used as the descriptor of an open file. If it is a
negative number, the saved input channel such many levels above the current one
is used. Otherwise (if it is a list), it is taken as a command with arguments,
and a pipe is opened for input. See also ipid, call, load, file, out, err, poll, pipe and ctl.
: (in "a" (list (read) (read) (read))) # Read three items from file "a"
-> (123 (a b c) def)
(inc 'num) -> num
(inc 'var ['num]) -> numnum incremented by 1. The
second form increments the VAL of var by 1, or by
num. If the first argument is NIL, it is returned
immediately. (inc Num) is equivalent to (+ Num 1) and
(inc 'Var) is equivalent to (set 'Var (+ Var 1)). See
also dec and +.
: (inc 7)
-> 8
: (inc -1)
-> 0
: (zero N)
-> 0
: (inc 'N)
-> 1
: (inc 'N 7)
-> 8
: N
-> 8
: (setq L (1 2 3 4))
-> (1 2 3 4)
: (inc (cdr L))
-> 3
: L
-> (1 3 3 4)
(inc! 'obj 'sym ['num]) -> num
inc. num defaults to 1. Note that
for incrementing a property value of an entity typically the inc!> message is used. See also
new!, set! and put!.
(inc! Obj 'cnt 0) # Incrementing a property of a non-entity object
(index 'any 'lst) -> cnt | NIL
cnt position of any in
lst, or NIL if it is not found. See also offset.
: (index 'c '(a b c d e f))
-> 3
: (index '(5 6) '((1 2) (3 4) (5 6) (7 8)))
-> 3
(info 'any ['flg]) -> (cnt|T dat . tim)
any: The current
size cnt in bytes, and the modification date and time (UTC). For
directories, T is returned instead of the size. If flg
is non-NIL and any is the name of a symbolic link,
then the link itself is used, not the file that it refers to. See also dir, date, time and lines.
$ ls -l x.l
-rw-r--r-- 1 abu users 208 Jun 17 08:58 x.l
$ pil +
: (info "x.l")
-> (208 730594 . 32315)
: (stamp 730594 32315)
-> "2000-06-17 08:58:35"
(init 'tree ['any1] ['any2]) -> lst
any1 and any2 may specify a range of keys. If
any2 is greater than any1, the traversal will be in
opposite direction. See also tree,
step, iter and scan.
: (init (tree 'nr '+Item) 3 5)
-> (((3 . 5) ((3 NIL . {3-3}) (4 NIL . {3-4}) (5 NIL . {3-5}) (6 NIL . {3-6}) (7 NIL . {3-8}))))
(insert 'cnt 'lst 'any) -> lst
any into lst at position cnt.
This is a non-destructive operation. See also remove, place, append, delete and replace.
: (insert 3 '(a b c d e) 777)
-> (a b 777 c d e)
: (insert 1 '(a b c d e) 777)
-> (777 a b c d e)
: (insert 9 '(a b c d e) 777)
-> (a b c d e 777)
(intern 'sym) -> sym
sym is already intern, it is returned. Otherwise, sym
is interned and returned. See also symbols, zap, extern and ====.
: (intern "abc")
-> abc
: (intern 'car)
-> car
: ((intern (pack "c" "a" "r")) (1 2 3))
-> 1
(ipid) -> pid | NIL
NIL. See also opid, in, pipe and load.
: (in '(ls "-l") (println (line T)) (kill (ipid)))
"total 7364"
-> T
(isa 'cls|typ 'obj) -> obj | NIL
obj when it is an object that inherits from
cls or type. See also OO
Concepts, class, type, new and object.
: (isa '+Address Obj)
-> {1-17}
: (isa '(+Male +Person) Obj)
-> NIL
isa/2
isa function. Typically used in
db/3 or select/3 database queries. See also
same/3, bool/3, range/3, head/3, fold/3, part/3 and tolr/3.
: (? (db nm +Person @Prs) (isa +Woman @Prs) (val @Nm @Prs nm))
@Prs={2-Y} @Nm="Alexandra of Denmark"
@Prs={2-1I} @Nm="Alice Maud Mary"
@Prs={2-F} @Nm="Anne"
@Prs={2-j} @Nm="Augusta Victoria". # Stop
(iter 'tree ['fun] ['any1] ['any2] ['flg])
fun to all values.
fun defaults to println. any1 and
any2 may specify a range of keys. If any2 is greater
than any1, the traversal will be in opposite direction. Note that
the keys need not to be atomic, depending on the application's index structure.
If flg is non-NIL, partial keys are skipped. See also
tree, ubIter, scan, init and step.
: (iter (tree 'nr '+Item))
{3-1}
{3-2}
{3-3}
{3-4}
{3-5}
{3-6}
{3-8}
-> {7-1}
: (iter (tree 'nr '+Item) '((This) (println (: nm))))
"Main Part"
"Spare Part"
"Auxiliary Construction"
"Enhancement Additive"
"Metal Fittings"
"Gadget Appliance"
"Testartikel"
-> {7-1}
J
picolisp-3.1.5.2.orig/doc/refK.html 0000644 0000000 0000000 00000004061 12265263724 015473 0 ustar root root
+Joint
+Link. Expects a (symbolic) attribute, and
list of classes as type of the
referred database object (of class +Entity). A +Joint corresponds
to two +Links, where the attribute argument is the relation of the
back-link in the referred object. See also Database.
(class +Ord +Entity) # Order class
(rel pos (+List +Joint) ord (+Pos)) # List of positions in that order
...
(class +Pos +Entity) # Position class
(rel ord (+Joint) # Back-link to the parent order
(job 'lst . prg) -> any
lst). The current values of all symbols are saved, the
symbols are bound to the values in lst, prg is
executed, then the (possibly modified) symbol values are (destructively) stored
in the environment list, and the symbols are restored to their original values.
The return value is the result of prg. Typically used in curried functions and *Run tasks. See also env, bind, let, use and state.
: (de tst ()
(job '((A . 0) (B . 0))
(println (inc 'A) (inc 'B 2)) ) )
-> tst
: (tst)
1 2
-> 2
: (tst)
2 4
-> 4
: (tst)
3 6
-> 6
: (pp 'tst)
(de tst NIL
(job '((A . 3) (B . 6))
(println (inc 'A) (inc 'B 2)) ) )
-> tst
(journal 'any ..) -> T
any, and
writes all changes to the database. See also pool.
: (journal "db.log")
-> T
K
picolisp-3.1.5.2.orig/doc/refL.html 0000644 0000000 0000000 00000051126 12265263724 015500 0 ustar root root
+Key
+relations, a subclass of +index. Accepts an optional argument for a
+Hook attribute. See also Database.
(rel nr (+Need +Key +Number)) # Mandatory, unique Customer/Supplier number
(key ['cnt]) -> sym
select system call is executed for all file descriptors and
timers in the VAL of the global variable *Run. If cnt is
non-NIL, that amount of milliseconds is waited maximally, and
NIL is returned upon timeout. See also raw and wait.
: (key) # Wait for a key
-> "a" # 'a' pressed
(kill 'pid ['cnt]) -> flg
cnt (or SIGTERM if
cnt is not given) to the process with the ID pid.
Returns T if successful.
: (kill *Pid 20) # Stop current process
[2]+ Stopped pil + # Unix shell
$ fg # Job control: Foreground
pil +
-> T # 'kill' was successful
L
picolisp-3.1.5.2.orig/doc/refM.html 0000644 0000000 0000000 00000054337 12265263724 015510 0 ustar root root
*Led
prg body that implements a "Line editor". When
non-NIL, it should return a single symbol (string) upon execution.
: (de *Led "(bye)")
# *Led redefined
-> *Led
: $ # Exit
+Link
+relation. Expects a list of classes as
type of the referred database object
(of class +Entity). See also Database.
(rel sup (+Ref +Link) NIL (+CuSu)) # Supplier (class Customer/Supplier)
+List
(rel pos (+List +Joint) ord (+Pos)) # Positions
(rel nm (+List +Ref +String)) # List of indexed strings
(rel val (+Ref +List +Number)) # Indexed list of numeric values
(last 'lst) -> any
lst. See also fin and tail.
: (last (1 2 3 4))
-> 4
: (last '((a b) c (d e f)))
-> (d e f)
(later 'var . prg) -> var
prg in a pipe'ed child process. The return value of
prg will later be available in var.
: (prog1 # Parallel background calculation of square numbers
(mapcan '((N) (later (cons) (* N N))) (1 2 3 4))
(wait NIL (full @)) )
-> (1 4 9 16)
(ld) -> any
loads the last
file edited with vi or em.
: (vi 'main)
-> T
: (ld)
# main redefined
-> go
(le0 'any) -> num | NIL
num when the argument is a number less or equal zero,
otherwise NIL. See also lt0, ge0, gt0, =0
and n0.
: (le0 -2)
-> -2
: (le0 0)
-> 0
: (le0 3)
-> NIL
(leaf 'tree) -> any
tree, minKey, maxKey and step.
: (leaf (tree 'nr '+Item))
-> {3-1}
: (db 'nr '+Item (minKey (tree 'nr '+Item)))
-> {3-1}
(length 'any) -> cnt | T
any. For numbers this is the number of
decimal digits in the value (plus 1 for negative values), for symbols it is the
number of characters in the name, and for lists it is the number of cells (or
T for circular lists). See also size and bytes.
: (length "abc")
-> 3
: (length "äbc")
-> 3
: (length 123)
-> 3
: (length (1 (2) 3))
-> 3
: (length (1 2 3 .))
-> T
(let sym 'any . prg) -> any
(let (sym 'any ..) . prg) -> any
sym - or the
values of the symbols sym in the list of the second form - are
saved and the symbols are bound to the evaluated any arguments.
prg is executed, then the symbols are restored to their original
values. The result of prg is returned. It is an error condition to
pass NIL as a sym argument. See also let?, bind, recur, with, for, job and use.
: (setq X 123 Y 456)
-> 456
: (let X "Hello" (println X))
"Hello"
-> "Hello"
: (let (X "Hello" Y "world") (prinl X " " Y))
Hello world
-> "world"
: X
-> 123
: Y
-> 456
(let? sym 'any . prg) -> any
any
evalutes to NIL, NIL is returned. Otherwise, the value
of the symbol sym is saved and sym is bound to the
evaluated any argument. prg is executed, then
sym is restored to its original value. The result of
prg is returned. It is an error condition to pass NIL
as the sym argument. (let? sym 'any ..) is equivalent
to (when 'any (let sym @ ..)). See also let, bind, job and use.
: (setq Lst (1 NIL 2 NIL 3))
-> (1 NIL 2 NIL 3)
: (let? A (pop 'Lst) (println 'A A))
A 1
-> 1
: (let? A (pop 'Lst) (println 'A A))
-> NIL
(lieu 'any) -> sym | NIL
any when it is an external symbol and
currently manifest in heap space, otherwise NIL. See also ext?.
: (lieu *DB)
-> {1}
(line 'flg ['cnt ..]) -> lst|sym
flg is
NIL, a list of single-character transient symbols is returned. When
cnt arguments are given, subsequent characters of the input line
are grouped into sublists, to allow parsing of fixed field length records. If
flg is non-NIL, strings are returned instead of
single-character lists. NIL is returned upon end of file. See also
char, read, till and eof.
: (line)
abcdefghijkl
-> ("a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l")
: (line T)
abcdefghijkl
-> "abcdefghijkl"
: (line NIL 1 2 3)
abcdefghijkl
-> (("a") ("b" "c") ("d" "e" "f") "g" "h" "i" "j" "k" "l")
: (line T 1 2 3)
abcdefghijkl
-> ("a" "bc" "def" "g" "h" "i" "j" "k" "l")
(lines 'any ..) -> cnt
any, or NIL if none was found. See also info.
: (lines "x.l")
-> 11
(link 'any ..) -> any
any to the end of the list in
the current make environment. This
operation is efficient also for long lists, because a pointer to the last
element of the list is maintained. link returns the last linked
argument. See also yoke, chain and made.
: (make
(println (link 1))
(println (link 2 3)) )
1
3
-> (1 2 3)
(lint 'sym) -> lst
(lint 'sym 'cls) -> lst
(lint '(sym . cls)) -> lst
var
indicates improper variables, dup duplicate parameters,
def an undefined function, bnd an unbound variable,
and use unused variables. See also noLint, lintAll, debug, trace and *Dbg.
: (de foo (R S T R) # 'T' is a improper parameter, 'R' is duplicated
(let N 7 # 'N' is unused
(bar X Y) ) ) # 'bar' is undefined, 'X' and 'Y' are not bound
-> foo
: (lint 'foo)
-> ((var T) (dup R) (def bar) (bnd Y X) (use N))
(lintAll ['sym ..]) -> lst
lint to
all internal symbols - and optionally
to all files sym - and returns a list of diagnoses. See also
noLint.
: (more (lintAll "file1.l" "file2.l"))
...
(lisp 'sym ['fun]) -> num
sym a callback
function fun, and returns a pointer num suitable to be
passed to a C function via 'native'. If fun is NIL,
the corresponding entry is freed. Maximally 24 callback functions can be
installed that way. 'fun' should be a function of maximally five numbers, and
should return a number. "Numbers" in this context are 64-bit scalars, and may
not only represent integers, but also pointers or other encoded data. See also
native and struct.
(load "lib/native.l")
(gcc "ltest" NIL
(cbTest (Fun) cbTest 'N Fun) )
long cbTest(int(*fun)(int,int,int,int,int)) {
return fun(1,2,3,4,5);
}
/**/
: (cbTest
(lisp 'cbTest
'((A B C D E)
(msg (list A B C D E))
(* A B C D E) ) ) )
(1 2 3 4 5)
-> 120
(list 'any ['any ..]) -> lst
any arguments. See also cons.
: (list 1 2 3 4)
-> (1 2 3 4)
: (list 'a (2 3) "OK")
-> (a (2 3) "OK")
lst/3
get
algorithm to that object and the following arguments. Often used in database
queries. See also map/3.
: (? (db nr +Ord 1 @Ord) (lst @Pos @Ord pos))
@Ord={3-7} @Pos={4-1}
@Ord={3-7} @Pos={4-2}
@Ord={3-7} @Pos={4-3}
-> NIL
(lst? 'any) -> flg
T when the argument any is a (possibly
empty) list (NIL or a cons pair). See also pair.
: (lst? NIL)
-> T
: (lst? (1 . 2))
-> T
: (lst? (1 2 3))
-> T
(listen 'cnt1 ['cnt2]) -> cnt | NIL
cnt1 (as received by port) for an incoming connection, and returns
the new socket descriptor cnt. While waiting for a connection, a
select system call is executed for all file descriptors and timers
in the VAL of the global variable *Run. If cnt2 is
non-NIL, that amount of milliseconds is waited maximally, and
NIL is returned upon timeout. The global variable *Adr
is set to the IP address of the client. See also accept, connect, *Adr.
: (setq *Socket
(listen (port 6789) 60000) ) # Listen at port 6789 for max 60 seconds
-> 4
: *Adr
-> "127.0.0.1"
(lit 'any) -> any
any, by
consing it with the quote function if necessary.
: (lit T)
-> T
: (lit 1)
-> 1
: (lit '(1))
-> (1)
: (lit '(a))
-> '(a)
(load 'any ..) -> any
any arguments. Normally, the name of each argument is
taken as a file to be executed in a read-eval loop. The argument semantics are
identical to that of in, with the
exception that if an argument is a symbol and its first character is a hyphen
'-', then that argument is parsed as an executable list (without the surrounding
parentheses). When any is T, all remaining command
line arguments are loaded recursively. When any is
NIL, standard input is read, a prompt is issued before each read
operation, the results are printed to standard output (read-eval-print loop),
and load terminates when an empty line is entered. In any case,
load terminates upon end of file, or when NIL is read.
The index for transient symbols is cleared before and after the load, so that
all transient symbols in a file have a local scope. If the namespace was
switched (with symbols) while
executing a file, it is restored to the previous one. Returns the value of the
last evaluated expression. See also script, ipid, call, file, in, out
and str.
: (load "lib.l" "-* 1 2 3")
-> 6
(loc 'sym 'lst) -> sym
lst a transient symbol with the same name as
sym. Allows to get hold of otherwise inaccessible symbols. See also
====.
: (loc "X" curry)
-> "X"
: (== @ "X")
-> NIL
(local . lst) -> sym
zap. Typically
used to create namespace-local symbols. lst should be a list of
symbols. See also pico, symbols, import and intern.
: (symbols 'myLib 'pico)
-> pico
myLib: (local bar foo)
-> "foo"
myLib: (de foo (A) # 'foo' is local to 'myLib'
...
myLib: (de bar (B) # 'bar' is local to 'myLib'
...
(locale 'sym1 'sym2 ['sym ..])
sym1
and the language file sym2 (both located in the "loc/" directory),
and optional application-specific directories sym. The locale
influences the language, and numerical, date and other formats. See also
*Uni, datStr, strDat, expDat, day, telStr, expTel and and money.
: (locale "DE" "de" "app/loc/")
-> "Zip"
: ,"Yes"
-> "Ja"
(lock ['sym]) -> cnt | NIL
sym (file record locking), or
the whole database root file if sym is NIL. Returns
NIL if successful, or the ID of the process currently holding the
lock. When sym is non-NIL, the lock is released at the
next top level call to commit or
rollback, otherwise only when
another database is opened with pool,
or when the process terminates. See also *Solo.
: (lock '{1}) # Lock single object
-> NIL
: (lock) # Lock whole database
-> NIL
(loop ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any
NIL or T as
its CAR, the clause's second element is evaluated as a condition and - if the
result is NIL or non-NIL, respectively - the
prg is executed and the result returned. See also do and for.
: (let N 3
(loop
(prinl N)
(T (=0 (dec 'N)) 'done) ) )
3
2
1
-> done
(low? 'any) -> sym | NIL any when the argument is a string (symbol) that starts with a
lowercase character. See also lowc and
upp?
: (low? "a")
-> "a"
: (low? "A")
-> NIL
: (low? 123)
-> NIL
: (low? ".")
-> NIL
(lowc 'any) -> any
any is not a symbol, it is returned
as it is. Otherwise, a new transient symbol with all characters of
any, converted to lower case, is returned. See also uppc, fold and low?.
: (lowc 123)
-> 123
: (lowc "ABC")
-> "abc"
(lt0 'any) -> num | NIL
num when the argument is a number and less than zero,
otherwise NIL. See also le0, ge0, gt0, =0
and n0.
: (lt0 -2)
-> -2
: (lt0 3)
-> NIL
(lup 'lst 'any) -> lst
(lup 'lst 'any 'any2) -> lst
any in the CAR-elements of cons pairs stored in the
index tree lst, as built-up by idx. In the first form, the first found cons
pair is returned, in the second form a list of all pairs whose CAR is in the
range any .. any2. See also assoc.
: (idx 'A 'a T)
-> NIL
: (idx 'A (1 . b) T)
-> NIL
: (idx 'A 123 T)
-> NIL
: (idx 'A (1 . a) T)
-> NIL
: (idx 'A (1 . c) T)
-> NIL
: (idx 'A (2 . d) T)
-> NIL
: (idx 'A)
-> (123 a (1 . a) (1 . b) (1 . c) (2 . d))
: (lup A 1)
-> (1 . b)
: (lup A 2)
-> (2 . d)
: (lup A 1 1)
-> ((1 . a) (1 . b) (1 . c))
: (lup A 1 2)
-> ((1 . a) (1 . b) (1 . c) (2 . d))
M
picolisp-3.1.5.2.orig/doc/refN.html 0000644 0000000 0000000 00000036542 12265263724 015507 0 ustar root root
*Msg
Error Handling, *Err and ^.
: (+ 'A 2)
!? (+ 'A 2)
A -- Number expected
?
:
: *Msg
-> "Number expected"
+Mis
+relations. Expects a function that takes
a value and an entity object, and returns NIL if everything is
correct, or an error string. See also Database.
(class +Ord +Entity) # Order class
(rel pos (+Mis +List +Joint) # List of positions in that order
((Val Obj)
(when (memq NIL Val)
"There are empty positions" ) )
ord (+Pos) )
(macro prg) -> any
pat? symbols in
prg (using fill), and
executes the result with run. Used
occasionally to call functions which otherwise do not evaluate their arguments.
: (de timerMessage (@N . @Prg)
(setq @N (- @N))
(macro
(task @N 0 . @Prg) ) )
-> timerMessage
: (timerMessage 6000 (println 'Timer 6000))
-> (-6000 0 (println 'Timer 6000))
: (timerMessage 12000 (println 'Timer 12000))
-> (-12000 0 (println 'Timer 12000))
: (more *Run)
(-12000 2616 (println 'Timer 12000))
(-6000 2100 (println 'Timer 6000))
-> NIL
: Timer 6000
Timer 12000
...
(made ['lst1 ['lst2]]) -> lst
make environment. All list elements already
produced with chain and link are discarded, and lst1 is
used instead. Optionally, lst2 can be specified as the new linkage
cell, otherwise the last cell of lst1 is used. When called without
arguments, made does not modify the environment. In any case, the
current list is returned.
: (make
(link 'a 'b 'c) # Link three items
(println (made)) # Print current list (a b c)
(made (1 2 3)) # Discard it, start new with (1 2 3)
(link 4) ) # Link 4
(a b c)
-> (1 2 3 4)
(mail 'any 'cnt 'sym1 'sym2|lst1 'sym3 'lst2 . prg)'
any, port
cnt. sym1 should be the "from" address,
sym2|lst1 the "to" address(es), and sym3 the subject.
lst2 is a list of attachments, each one specified by three elements
for path, name and mime type. prg generates the mail body with
prEval. See also connect.
(mail "localhost" 25 # Local mail server
"a@bc.de" # "From" address
"abu@software-lab.de" # "To" address
"Testmail" # Subject
(quote
"img/go.png" "go.png" "image/png" # First attachment
"img/7fach.gif" "7fach.gif" "image/gif" ) # Second attachment
"Hello," # First line
NIL # (empty line)
(prinl (pack "This is mail #" (+ 3 4))) ) # Third line
(make .. [(made 'lst ..)] .. [(link 'any ..)] ..) -> any
made, chain, link and yoke functions, and returns the result list.
For efficiency, pointers to the head and the tail of the list are maintained
internally.
: (make (link 1) (link 2 3) (link 4))
-> (1 2 3 4)
: (make (made (1 2 3)) (link 4))
-> (1 2 3 4)
(map 'fun 'lst ..) -> lst
fun to lst and all successive CDRs. When
additional lst arguments are given, they are passed to
fun in the same way. Returns the result of the last application.
See also mapc, maplist, mapcar, mapcon, mapcan and filter.
: (map println (1 2 3 4) '(A B C))
(1 2 3 4) (A B C)
(2 3 4) (B C)
(3 4) (C)
(4) NIL
-> NIL
map/3
get algorithm to that object and the following
arguments. Often used in database queries. See also lst/3.
: (? (db nr +Ord 1 @Ord) (map @L @Ord pos))
@Ord={3-7} @L=({4-1} {4-2} {4-3})
@Ord={3-7} @L=({4-2} {4-3})
@Ord={3-7} @L=({4-3})
-> NIL
(mapc 'fun 'lst ..) -> any
fun to each element of lst. When
additional lst arguments are given, their elements are also passed
to fun. Returns the result of the last application. See also
map, maplist, mapcar, mapcon, mapcan and filter.
: (mapc println (1 2 3 4) '(A B C))
1 A
2 B
3 C
4 NIL
-> NIL
(mapcan 'fun 'lst ..) -> lst
fun to each element of lst. When
additional lst arguments are given, their elements are also passed
to fun. Returns a (destructively) concatenated list of all results.
See also map, mapc, maplist, mapcar, mapcon, filter.
: (mapcan reverse '((a b c) (d e f) (g h i)))
-> (c b a f e d i h g)
(mapcar 'fun 'lst ..) -> lst
fun to each element of lst. When
additional lst arguments are given, their elements are also passed
to fun. Returns a list of all results. See also map, mapc, maplist, mapcon, mapcan and filter.
: (mapcar + (1 2 3) (4 5 6))
-> (5 7 9)
: (mapcar '((X Y) (+ X (* Y Y))) (1 2 3 4) (5 6 7 8))
-> (26 38 52 68)
(mapcon 'fun 'lst ..) -> lst
fun to lst and all successive CDRs. When
additional lst arguments are given, they are passed to
fun in the same way. Returns a (destructively) concatenated list of
all results. See also map, mapc, maplist, mapcar, mapcan and filter.
: (mapcon copy '(1 2 3 4 5))
-> (1 2 3 4 5 2 3 4 5 3 4 5 4 5 5)
(maplist 'fun 'lst ..) -> lst
fun to lst and all successive CDRs. When
additional lst arguments are given, they are passed to
fun in the same way. Returns a list of all results. See also
map, mapc, mapcar, mapcon, mapcan and filter.
: (maplist cons (1 2 3) '(A B C))
-> (((1 2 3) A B C) ((2 3) B C) ((3) C))
(maps 'fun 'sym ['lst ..]) -> any
fun to all properties of sym. When
additional lst arguments are given, their elements are also passed
to fun. Returns the result of the last application. See also
putl and getl.
: (put 'X 'a 1)
-> 1
: (put 'X 'b 2)
-> 2
: (put 'X 'flg T)
-> T
: (getl 'X)
-> (flg (2 . b) (1 . a))
: (maps println 'X '(A B))
flg A
(2 . b) B
(1 . a) NIL
-> NIL
(mark 'sym|0 ['NIL | 'T | '0]) -> flg
sym in the database (for a
second argument of NIL, T or 0,
respectively), and returns the old value. The marks are local to the current
process (not stored in the database), and vanish when the process terminates. If
the first argument is zero, all marks are cleared.
: (pool "db")
-> T
: (mark '{1} T) # Mark
-> NIL
: (mark '{1}) # Test
-> T # -> marked
: (mark '{1} 0) # Unmark
-> T
: (mark '{1}) # Test
-> NIL # -> unmarked
(match 'lst1 'lst2) -> flg
lst1 as a pattern to be matched against
lst2, and returns T when successful. Atoms must be
equal, and sublists must match recursively. Symbols in the pattern list with
names starting with an at-mark "@" (see pat?) are taken as wildcards. They can match
zero, one or more elements, and are bound to the corresponding data. See also
chop, split and fill.
: (match '(@A is @B) '(This is a test))
-> T
: @A
-> (This)
: @B
-> (a test)
: (match '(@X (d @Y) @Z) '((a b c) (d (e f) g) h i))
-> T
: @X
-> ((a b c))
: @Y
-> ((e f) g)
: @Z
-> (h i)
(max 'any ..) -> any
any arguments. See also min and Comparing.
: (max 2 'a 'z 9)
-> z
: (max (5) (2 3) 'X)
-> (5)
(maxKey 'tree ['any1 ['any2]]) -> any
any1 and/or a maximal key any2 is given, the largest
key from that range is returned. See also tree, leaf, minKey and genKey.
: (maxKey (tree 'nr '+Item))
-> 7
: (maxKey (tree 'nr '+Item) 3 5)
-> 5
(maxi 'fun 'lst ..) -> any
fun to each element of lst. When
additional lst arguments are given, their elements are also passed
to fun. Returns that element from lst for which
fun returned a maximal value. See also mini and sort.
: (setq A 1 B 2 C 3)
-> 3
: (maxi val '(A B C))
-> C
: (maxi # Symbol with largest list value
'((X)
(and (pair (val X)) (size @)) )
(all) )
-> pico
(member 'any 'lst) -> any
lst that starts with any when
any is a member of lst, otherwise NIL.
See also memq, assoc and idx.
: (member 3 (1 2 3 4 5 6))
-> (3 4 5 6)
: (member 9 (1 2 3 4 5 6))
-> NIL
: (member '(d e f) '((a b c) (d e f) (g h i)))
-> ((d e f) (g h i))
member/2
equal/2 and member.
: (? (member @X (a b c)))
@X=a
@X=b
@X=c
-> NIL
(memq 'any 'lst) -> any
lst that starts with any when
any is a member of lst, otherwise NIL.
== is used for comparison (pointer
equality). See also member, mmeq, asoq, delq and Comparing.
: (memq 'c '(a b c d e f))
-> (c d e f)
: (memq (2) '((1) (2) (3)))
-> NIL
(meta 'obj|typ 'sym ['sym2|cnt ..]) -> any
any, by searching the property lists
of the classes and superclasses of obj, or the classes in
typ, for the property key sym, and by applying the
get algorithm to the following optional
arguments. See also var:.
: (setq A '(B)) # Be 'A' an object of class 'B'
-> (B)
: (put 'B 'a 123)
-> 123
: (meta 'A 'a) # Fetch 'a' from 'B'
-> 123
(meth 'obj ['any ..]) -> any
dm as a template to initialize the
VAL of message symbols. It searches for itself in the methods of
obj and its classes and superclasses, and executes that method. An
error "Bad message" is issued if the search is unsuccessful. See
also OO Concepts, method, send and try.
: meth
-> 67283504 # Value of 'meth'
: stop>
-> 67283504 # Value of any message
(method 'msg 'obj) -> fun
msg to the object obj. If the message
cannot be located in obj, its classes and superclasses,
NIL is returned. See also OO Concepts,
send, try, meth, super, extra, class.
: (method 'mis> '+Number)
-> ((Val Obj) (and Val (not (num? Val)) "Numeric input expected"))
(methods 'sym) -> lst
sym, as they are inherited from sym's classes
and superclasses. See also OO Concepts, dep, class and can.
: (more (methods '+Joint))
(keep> . +Joint)
(lose> . +Joint)
(rel> . +Joint)
(mis> . +Joint)
(T . +Joint)
(revise> . +relation)
(print> . +relation)
(zap> . +relation)
(del> . +relation)
(put> . +relation)
(has> . +relation)
(ele> . +relation)
(min 'any ..) -> any
any arguments. See also max and Comparing.
: (min 2 'a 'z 9)
-> 2
: (min (5) (2 3) 'X)
-> X
(minKey 'tree ['any1 ['any2]]) -> any
any1 and/or a maximal key any2 is given, the smallest
key from that range is returned. See also tree, leaf, maxKey and genKey.
: (minKey (tree 'nr '+Item))
-> 1
: (minKey (tree 'nr '+Item) 3 5)
-> 3
(mini 'fun 'lst ..) -> any
fun to each element of lst. When
additional lst arguments are given, their elements are also passed
to fun. Returns that element from lst for which
fun returned a minimal value. See also maxi and sort.
: (setq A 1 B 2 C 3)
-> 3
: (mini val '(A B C))
-> A
(mix 'lst cnt|'any ..) -> lst
lst, as
specified by the following cnt|'any arguments. If such an argument
is a number, the cnt'th element from lst is taken,
otherwise that argument is evaluated and the result is used.
: (mix '(a b c d) 3 4 1 2)
-> (c d a b)
: (mix '(a b c d) 1 'A 4 'D)
-> (a A d D)
(mmeq 'lst 'lst) -> any
lst that starts with a
member of the first argument lst, otherwise NIL.
== is used for comparison (pointer
equality). See also member, memq, asoq and delq.
: (mmeq '(a b c) '(d e f))
-> NIL
: (mmeq '(a b c) '(d b x))
-> (b x)
(money 'num ['sym]) -> sym
num into a digit string with two decimal
places, according to the current locale. If an additional currency name is
given, it is appended (separated by a space). See also telStr, datStr and format.
: (money 123456789)
-> "1,234,567.89"
: (money 12345 "EUR")
-> "123.45 EUR"
: (locale "DE" "de")
-> NIL
: (money 123456789 "EUR")
-> "1.234.567,89 EUR"
(more 'lst ['fun]) -> flg
(more 'cls) -> any
lst (first form), or
the type and methods of cls (second form). fun
defaults to print. In the second
form, the method definitions of cls are pretty-printed with
pp. After each step, more
waits for console input, and terminates when a non-empty line is entered. In
that case, T is returned, otherwise (when end of data is reached)
NIL. See also query and
show.
: (more (all)) # Display all internal symbols
inc>
leaf
nil
inc!
accept. # Stop
-> T
: (more (all) show) # 'show' all internal symbols
inc> 67292896
*Dbg ((859 . "lib/db.l"))
leaf ((Tree) (let (Node (cdr (root Tree)) X) (while (val Node) (setq X (cadr @) Node (car @))) (cddr X)))
*Dbg ((173 . "lib/btree.l"))
nil 67284680
T (((@X) (^ @ (not (-> @X)))))
. # Stop
-> T
: (more '+Link) # Display a class
(+relation)
(dm mis> (Val Obj)
(and
Val
(nor (isa (: type) Val) (canQuery Val))
"Type error" ) )
(dm T (Var Lst)
(unless (=: type (car Lst)) (quit "No Link" Var))
(super Var (cdr Lst)) )
-> NIL
(msg 'any ['any ..]) -> any
any with print, followed by all any
arguments (printed with prin) and a
newline, to standard error. The first any argument is returned.
: (msg (1 a 2 b 3 c) " is a mixed " "list")
(1 a 2 b 3 c) is a mixed list
-> (1 a 2 b 3 c)
N
picolisp-3.1.5.2.orig/doc/refO.html 0000644 0000000 0000000 00000021337 12265263724 015504 0 ustar root root
+Need
+relations. Note that this does not
enforce any requirements by itself, it only returns an error message if the
mis> message is explicitly called, e.g. by GUI functions. See
also Database.
(rel nr (+Need +Key +Number)) # Item number is mandatory
+Number
+relation. Accepts an optional argument
for the fixpoint scale (currently not used). See also Database.
(rel pr (+Number) 2) # Price, with two decimal places
(n== 'any ..) -> flg
T when not all any arguments are the same
(pointer equality). (n== 'any ..) is equivalent to (not (==
'any ..)). See also == and Comparing.
: (n== 'a 'a)
-> NIL
: (n== (1) (1))
-> T
(n0 'any) -> flg
T when any is not a number with value
zero. See also =0, lt0, le0, ge0 and gt0.
: (n0 (- 6 3 2 1))
-> NIL
: (n0 'a)
-> T
(nT 'any) -> flg
T when any is not the symbol
T. See also =T.
: (nT 0)
-> T
: (nT "T")
-> T
: (nT T)
-> NIL
(name 'sym ['sym2]) -> sym
sym2 is not given, a new transient symbol with the
name of sym. Otherwise sym must be a transient symbol,
and its name is changed to that of sym2 (note that this may give
inconsistencies if the symbol is still referred to from other namespaces). See
also str, sym, symbols, zap and intern.
: (name 'abc)
-> "abc"
: (name "abc")
-> "abc"
: (name '{abc})
-> "abc"
: (name (new))
-> NIL
: (de foo (Lst) (car Lst)) # 'foo' calls 'car'
-> foo
: (intern (name (zap 'car) "xxx")) # Globally change the name of 'car'
-> xxx
: (xxx (1 2 3))
-> 1
: (pp 'foo)
(de foo (Lst)
(xxx Lst) ) # Name changed
-> foo
: (foo (1 2 3)) # 'foo' still works
-> 1
: (car (1 2 3)) # Reader returns a new 'car' symbol
!? (car (1 2 3))
car -- Undefined
?
(nand 'any ..) -> flg
any are evaluated from left to
right. If NIL is encountered, T is returned
immediately. Else NIL is returned. (nand ..) is
equivalent to (not (and ..)).
: (nand (lt0 7) (read))
-> T
: (nand (lt0 -7) (read))
abc
-> NIL
: (nand (lt0 -7) (read))
NIL
-> T
(native 'cnt1|sym1 'cnt2|sym2 'any 'any ..) -> any
"@" (the current main
program), sym1 (a library path name), or cnt1 (a
library handle obtained by a previous call). The second argument should be a
symbol name sym2, or a function pointer cnt2 obtained
by a previous call). Practically, the first two arguments will be always passed
as transient symbols, which will get the library handle and function pointer
assigned as values to be cached and used in subsequent calls. The third argument
any is a result specification, while all following arguments are
the arguments to the native function. The functionality is described in detail
in Native C Calls.
NIL void
B byte # Byte (unsigned 8 bit)
C char # Character (UTF-8, 1-3 bytes)
I int # Integer (signed 32 bit)
N long # Long or pointer (signed 64 bit)
S string # String (UTF-8)
-1.0 float # Scaled fixpoint number
+1.0 double # Scaled fixpoint number
(N . 4) # long[4]; -> (1 2 3 4)
(N (C . 4)) # {long; char[4];} -> (1234 ("a" "b" "c" NIL))
(N (B . 7)) # {long; byte[7];} -> (1234 (1 2 3 4 5 6 7))
double, otherwise as a float)
NIL)
If the last CDR of the initialization sequence is a number, it is used
as a fill-byte value for the remaining space in the structure.
(num . cnt) where 'num' is stored in
a field of 'cnt' bytes
(sym . cnt) where 'sym' is stored as
a null-terminated string in a field of 'cnt' bytes
(1.0 num ...) where the 'num'
elements (scaled fixpoint numbers) are stored as a sequence of double
precision floating point numbers
(-1.0 num ...) where the 'num'
elements (scaled fixpoint numbers) are stored as a sequence of single
precision floating point numbers
native takes care of allocating memory for strings, arrays or
structures, and frees that memory when done.
NIL, and for positive infinity T is returned.
long lisp(char*, long, long, long, long, long);
lisp() calls that symbol with the five numbers, and expects a
numeric return value. "Numbers" in this context are 64-bit scalars, and may not
only represent integers, but also pointers or other encoded data. See also
struct, lisp and errno.
: (native "@" "getenv" 'S "TERM") # Same as (sys "TERM")
-> "xterm"
: (native "@" "printf" 'I "abc%d%s^J" (+ 3 4) (pack "X" "Y" "Z"))
abc7XYZ
-> 8
: (native "@" "printf" 'I "This is %.3f^J" (123456 . 1000))
This is 123.456
-> 16
: (use Tim
(native "@" "time" NIL '(Tim (8 B . 8))) # time_t 8 # Get time_t structure
(native "@" "localtime" '(I . 9) (cons NIL (8) Tim)) ) # Read local time
-> (32 18 13 31 11 109 4 364 0) # 13:18:32, Dec. 31st, 2009
: (native "libcrypto.so" "SHA1" '(B . 20) "abcd" 4 0)
-> (129 254 139 254 135 87 108 62 203 34 66 111 142 87 132 115 130 145 122 207)
(need 'cnt ['lst ['any]]) -> lst
(need 'cnt ['num|sym]) -> lst
cnt elements. When called without
optional arguments, a list of cnt NIL's is returned.
When lst is given, it is extended to the left (if cnt
is positive) or (destructively) to the right (if cnt is negative)
with any elements. In the second form, a list of cnt
atomic values is returned. See also range.
: (need 5)
-> (NIL NIL NIL NIL NIL) # Allocate 5 cells
: (need 5 '(a b c))
-> (NIL NIL a b c)
: (need -5 '(a b c))
-> (a b c NIL NIL)
: (need 5 '(a b c) " ") # String alignment
-> (" " " " a b c)
: (need 7 0)
-> (0 0 0 0 0 0 0)
(new ['flg|num] ['typ ['any ..]]) -> obj
flg is given and
non-NIL, the new object will be an external symbol (created in
database file 1 if T, or in the corresponding database file if
num is given). typ (typically a list of classes) is
assigned to the VAL, and the initial T message is sent
with the arguments any to the new object. If no T
message is defined for the classes in typ or their superclasses,
the any arguments should evaluate to alternating keys and values
for the initialization of the new object. See also box, object, class, type, isa, send and Database.
: (new)
-> $134426427
: (new T '(+Address))
-> {1A;3}
(new! 'typ ['any ..]) -> obj
new. (new! '(+Cls) 'key 'val ...)
is equivalent to (dbSync) (new (db: +Cls) '(+Cls) 'key 'val ...) (commit
'upd). See also set!, put! and inc!.
: (new! '(+Item) # Create a new item
'nr 2 # Item number
'nm "Spare Part" # Description
'sup (db 'nr '+CuSu 2) # Supplier
'inv 100 # Inventory
pr 12.50 ) # Price
(next) -> any
@). Returns the next argument from the internal list. See also
args, arg, rest, and pass.
: (de foo @ (println (next))) # Print next argument
-> foo
: (foo)
NIL
-> NIL
: (foo 123)
123
-> 123
(nil . prg) -> NIL
prg, and returns NIL. See also t, prog,
prog1 and prog2.
: (nil (println 'OK))
OK
-> NIL
nil/1
NIL. See also not/1.
: (? @X NIL (nil @X))
@X=NIL
-> NIL
(noLint 'sym)
(noLint 'sym|(sym . cls) 'sym2)
sym (in the first form), or for variable binding and usage of
sym2 in the function definition, file contents or method body of
sym (second form), during calls to lint. See also lintAll.
: (de foo ()
(bar FreeVariable) )
-> foo
: (lint 'foo)
-> ((def bar) (bnd FreeVariable))
: (noLint 'bar)
-> bar
: (noLint 'foo 'FreeVariable)
-> (foo . FreeVariable)
: (lint 'foo)
-> NIL
(nond ('any1 . prg1) ('any2 . prg2) ..) -> any
anyN
conditions evaluates to NIL, prgN is executed and the
result returned. Otherwise (all conditions evaluate to non-NIL),
NIL is returned. See also cond, ifn and unless.
: (nond
((= 3 3) (println 1))
((= 3 4) (println 2))
(NIL (println 3)) )
2
-> 2
(nor 'any ..) -> flg
any are evaluated from left to
right. If a non-NIL value is encountered, NIL is
returned immediately. Else T is returned. (nor ..) is
equivalent to (not (or ..)).
: (nor (lt0 7) (= 3 4))
-> T
(not 'any) -> flg
T if any evaluates to
NIL.
: (not (== 'a 'a))
-> NIL
: (not (get 'a 'a))
-> T
not/1
nil/1, true/0 and fail/0.
: (? (equal 3 4))
-> NIL
: (? (not (equal 3 4)))
-> T
(nth 'lst 'cnt ..) -> lst
lst starting from the cnt'th
element of lst. Successive cnt arguments operate on
the results in the same way. (nth 'lst 2) is equivalent to
(cdr 'lst). See also get.
: (nth '(a b c d) 2)
-> (b c d)
: (nth '(a (b c) d) 2 2)
-> (c)
: (cdadr '(a (b c) d))
-> (c)
(num? 'any) -> num | NIL
any when the argument any is a number,
otherwise NIL.
: (num? 123)
-> 123
: (num? (1 2 3))
-> NIL
O
picolisp-3.1.5.2.orig/doc/refP.html 0000644 0000000 0000000 00000071401 12265263724 015502 0 ustar root root
*Once
idx tree of already
loaded source locations (as returned
by file) See also once.
: *Once
-> (("lib/" "misc.l" . 11) (("lib/" "http.l" . 9) (("lib/" "form.l" . 11))))
*OS
"Linux", "FreeBSD", "Darwin" or
"Cygwin". See also *CPU.
: *OS
-> "Linux"
(obj (typ var [hook] val ..) var2 val2 ..) -> obj
request) corresponding to (typ var
[hook] val ..), and initializes additional properties using the
varN and valN arguments.
: (obj ((+Item) nr 2) nm "Spare Part" sup `(db 'nr '+CuSu 2) inv 100 pr 1250)
-> {3-2}
(object 'sym 'any ['sym2 'any2 ..]) -> obj
sym to be an object with the value (or type)
any. The property list is initialized with all optionally supplied
key-value pairs. See also OO Concepts, new, type and isa.
: (object 'Obj '(+A +B +C) 'a 1 'b 2 'c 3)
-> Obj
: (show 'Obj)
Obj (+A +B +C)
c 3
b 2
a 1
-> Obj
(oct 'num ['num]) -> sym
(oct 'sym) -> num
num to an octal string, or an octal string
sym to a number. In the first case, if the second argument is
given, the result is separated by spaces into groups of such many digits. See
also bin, hex, fmt64, hax and format.
: (oct 73)
-> "111"
: (oct "111")
-> 73
: (oct 1234567 3)
-> "4 553 207"
(off var ..) -> NIL
NIL in all var arguments. See also on, onOff, zero and one.
: (off A B)
-> NIL
: A
-> NIL
: B
-> NIL
(offset 'lst1 'lst2) -> cnt | NIL
cnt position of the tail list lst1 in
lst2, or NIL if it is not found. See also index and tail.
: (offset '(c d e f) '(a b c d e f))
-> 3
: (offset '(c d e) '(a b c d e f))
-> NIL
(on var ..) -> T
T in all var arguments. See also off, onOff, zero and one.
: (on A B)
-> T
: A
-> T
: B
-> T
(once . prg) -> any
prg once, when the current file is loaded the first time. Subsequent loads at a
later time will not execute prg, and once returns
NIL. See also *Once.
(once
(zero *Cnt1 *Cnt2) # Init counters
(load "file1.l" "file2.l") ) # Load other files
(one var ..) -> 1
1 in all var arguments. See also zero, on, off
and onOff.
: (one A B)
-> 1
: A
-> 1
: B
-> 1
(onOff var ..) -> flg
var arguments. Returns the
new value of the last symbol. See also on, off,
zero and one.
: (onOff A B)
-> T
: A
-> T
: B
-> T
: (onOff A B)
-> NIL
: A
-> NIL
: B
-> NIL
(open 'any ['flg]) -> cnt | NIL
any in read/write mode (or
read-only if flg is non-NIL), and returns a file
descriptor cnt (or NIL on error). A leading
"@" character in any is substituted with the
PicoLisp Home Directory, as it was remembered during interpreter startup.
If flg is NIL and the file does not exist, it is
created. The file descriptor can be used in subsequent calls to in and out. See also close and poll.
: (open "x")
-> 3
(opid) -> pid | NIL
NIL. See also ipid and out.
: (out '(cat) (call 'ps "-p" (opid)))
PID TTY TIME CMD
7127 pts/3 00:00:00 cat
-> T
(opt) -> sym
load) as a string, and remove it from
the remaining command line arguments. See also Invocation and argv.
$ pil -"de f () (println 'opt (opt))" -f abc -bye
opt "abc"
(or 'any ..) -> any
any are evaluated from left to
right. If a non-NIL value is encountered, it is returned
immediately. Else the result of the last expression is returned.
: (or (= 3 3) (read))
-> T
: (or (= 3 4) (read))
abc
-> abc
or/2
not/1.
: (?
(or
((equal 3 @X) (equal @X 4))
((equal 7 @X) (equal @X 7)) ) )
@X=7
-> NIL(out 'any . prg) -> any
any as output channel during the execution of
prg. The current output channel will be saved and restored
appropriately. If the argument is NIL, standard output is used. If
the argument is a symbol, it is used as a file name (opened in "append" mode if
the first character is "+"). If it is a positve number, it is used
as the descriptor of an open file. If it is a negative number, the saved output
channel such many levels above the current one is used. Otherwise (if it is a
list), it is taken as a command with arguments, and a pipe is opened for output.
See also opid, call, in, err, ctl, pipe, poll, close and load.
: (out "a" (println 123 '(a b c) 'def)) # Write one line to file "a"
-> def
P
picolisp-3.1.5.2.orig/doc/refQ.html 0000644 0000000 0000000 00000005776 12265263724 015517 0 ustar root root
*PPid
NIL if the current process is a top level process.
: (println *PPid *Pid)
NIL 5286
: (unless (fork) (println *PPid *Pid) (bye))
5286 5522
*Pid
: *Pid
-> 6386
: (call "ps") # Show processes
PID TTY TIME CMD
.... ... ........ .....
6386 pts/1 00:00:00 pil # <- current process
6388 pts/1 00:00:00 ps
-> T
*Prompt
prg body, which is
executed - and the result printed -
every time before a prompt is output to the console in the
"read-eval-print-loop" (REPL).
: (de *Prompt (pack "[" (stamp) "]"))
# *Prompt redefined
-> *Prompt
[2011-10-11 16:50:05]: (+ 1 2 3)
-> 6
[2011-10-11 16:50:11]:
(pack 'any ..) -> sym
any. A NIL arguments contributes nothing to the result
string, a number is converted to a digit string, a symbol supplies the
characters of its name, and for a list its elements are taken. See also text and glue.
: (pack 'car " is " 1 '(" symbol " name))
-> "car is 1 symbol name"
(pad 'cnt 'any) -> sym
any packed with leading '0' characters, up to a
field width of cnt. See also format and align.
: (pad 5 1)
-> "00001"
: (pad 5 123456789)
-> "123456789"
(pair 'any) -> any
any when the argument is a cons pair. See also atom and lst?.
: (pair NIL)
-> NIL
: (pair (1 . 2))
-> (1 . 2)
: (pair (1 2 3))
-> (1 2 3)
part/3
folding it to a
canonical form, is a substring of the folded string representation of the
result of applying the get algorithm to
the following arguments. Typically used as filter predicate in select/3 database queries. See also
sub?, isa/2, same/3, bool/3, range/3, head/3, fold/3 and tolr/3.
: (?
@Nr (1 . 5)
@Nm "part"
(select (@Item)
((nr +Item @Nr) (nm +Item @Nm))
(range @Nr @Item nr)
(part @Nm @Item nm) ) )
@Nr=(1 . 5) @Nm="part" @Item={3-1}
@Nr=(1 . 5) @Nm="part" @Item={3-2}
-> NIL
(pass 'fun ['any ..]) -> any
fun all arguments any, and all remaining
variable arguments (@) as they would be returned by rest. (pass 'fun 'any) is
equivalent to (apply 'fun (rest) 'any). See also apply.
: (de bar (A B . @)
(println 'bar A B (rest)) )
-> bar
: (de foo (A B . @)
(println 'foo A B)
(pass bar 1)
(pass bar 2) )
-> foo
: (foo 'a 'b 'c 'd 'e 'f)
foo a b
bar 1 c (d e f)
bar 2 c (d e f)
-> (d e f)
(pat? 'any) -> pat | NIL
any when the argument any is a symbol
whose name starts with an at-mark "@", otherwise NIL.
: (pat? '@)
-> @
: (pat? "@Abc")
-> "@Abc"
: (pat? "ABC")
-> NIL
: (pat? 123)
-> NIL
(patch 'lst 'any . prg) -> any
lst, that
match the pattern any,
by the result of the execution of prg. See also daemon and redef.
: (pp 'hello)
(de hello NIL
(prinl "Hello world!") )
-> hello
: (patch hello 'prinl 'println)
-> NIL
: (pp 'hello)
(de hello NIL
(println "Hello world!") )
-> hello
: (patch hello '(prinl @S) (fill '(println "We said: " . @S)))
-> NIL
: (hello)
We said: Hello world!
-> "Hello world!"
(path 'any) -> sym
@" character in the any
argument with the PicoLisp Home Directory, as it was remembered during
interpreter startup. Optionally, the name may be preceded by a "+"
character (as used by in and out). This mechanism is used internally by all
I/O functions. See also Invocation, basename and dirname.
$ /usr/bin/picolisp /usr/lib/picolisp/lib.l
: (path "a/b/c")
-> "a/b/c"
: (path "@a/b/c")
-> "/usr/lib/picolisp/a/b/c"
: (path "+@a/b/c")
-> "+/usr/lib/picolisp/a/b/c"
(peek) -> sym
char would return. See also skip.
$ cat a
# Comment
abcd
$ pil +
: (in "a" (list (peek) (char)))
-> ("#" "#")
permute/2
append/3.
: (? (permute (a b c) @X))
@X=(a b c)
@X=(a c b)
@X=(b a c)
@X=(b c a)
@X=(c a b)
@X=(c b a)
-> NIL
(pick 'fun 'lst ..) -> any
fun to successive elements of lst until
non-NIL is returned. Returns that value, or NIL if
fun did not return non-NIL for any element of
lst. When additional lst arguments are given, their
elements are also passed to fun. (pick 'fun 'lst) is
equivalent to (fun (find 'fun 'lst)). See also seek, find and extract.
: (setq A NIL B 1 C NIL D 2 E NIL F 3)
-> 3
: (find val '(A B C D E))
-> B
: (pick val '(A B C D E))
-> 1
pico
idx' trees, one for symbols with short names and
one for symbols with long names (more than 7 bytes in the name). See also
symbols, import and intern.
: (symbols)
-> pico
: (cdr pico)
-> (rollback (*NoTrace (ledSearch (expandTab (********)) *CtryCode ...
(pil ['any ..]) -> sym
packed any arguments in
the directory ".pil/" in the user's home directory.
See also tmp.
: (pil "history") # Path to the line editor's history file
-> "/home/app/.pil/history"
(pilog 'lst . prg) -> any
prg for each result set with all Pilog variables bound to their
matching values. See also solve,
?, goal and prove.
: (pilog '((append @X @Y (a b c))) (println @X '- @Y))
NIL - (a b c)
(a) - (b c)
(a b) - (c)
(a b c) - NIL
-> NIL
(pipe exe) -> cnt
(pipe exe . prg) -> any
exe in a fork'ed child process (which terminates
thereafter). In the first form, pipe just returns a file descriptor
to read from the standard output of that process. In the second form, it opens
the standard output of that process as input channel during the execution of
prg. The current input channel will be saved and restored
appropriately. See also later,
ipid, in and out.
: (pipe # equivalent to 'any'
(prinl "(a b # Comment^Jc d)") # (child process)
(read) ) # (parent process)
-> (a b c d)
: (pipe # pipe through an external program
(out '(tr "[a-z]" "[A-Z]") # (child process)
(prinl "abc def ghi") )
(line T) ) # (parent process)
-> "ABC DEF GHI"
(place 'cnt 'lst 'any) -> lst
any into lst at position cnt.
This is a non-destructive operation. See also insert, remove, append, delete and replace.
: (place 3 '(a b c d e) 777)
-> (a b 777 d e)
: (place 1 '(a b c d e) 777)
-> (777 b c d e)
: (place 9 '(a b c d e) 777)
-> (a b c d e 777)
(poll 'cnt) -> cnt | NIL
cnt. See also open,
in and close.
: (and (poll *Fd) (in @ (read))) # Prevent blocking
(pool ['sym1 ['lst] ['sym2] ['sym3]]) -> T
sym1 as a database file in read/write mode. If
the file does not exist, it is created. A currently open database is closed.
lst is a list of block size scale factors (i.e. numbers),
defaulting to (2) (for a single file with a 256 byte block size). If
lst is given, an individual database file is opened for each item.
If sym2 is non-NIL, it is opened in append-mode as an
asynchronous replication journal. If sym3 is non-NIL,
it is opened for reading and appending, to be used as a synchronous transaction
log during commits. See also
dbs, *Dbs and journal.
: (pool "/dev/hda2")
-> T
: *Dbs
-> (1 2 2 4)
: (pool "dbFile" *Dbs)
-> T
:
abu:~/pico ls -l dbFile*
-rw-r--r-- 1 abu abu 256 2007-06-11 07:57 dbFile1
-rw-r--r-- 1 abu abu 13 2007-06-11 07:57 dbFile2
-rw-r--r-- 1 abu abu 13 2007-06-11 07:57 dbFile3
-rw-r--r-- 1 abu abu 13 2007-06-11 07:57 dbFile4
(pop 'var) -> any
var. See also
push, queue, cut, del and fifo.
: (setq S '((a b c) (1 2 3)))
-> ((a b c) (1 2 3))
: (pop S)
-> a
: (pop (cdr S))
-> 1
: (pop 'S)
-> (b c)
: S
-> ((2 3))
(port ['T] 'cnt|(cnt . cnt) ['var]) -> cnt
cnt (or a UDP-Port if the first argument is
T), and returns a socket descriptor suitable as an argument for
listen or accept (or udp, respectively). If cnt is zero,
some free port number is allocated. If a pair of cnts is given
instead, it should be a range of numbers which are tried in turn. When
var is given, it is bound to the port number.
: (port 0 'A) # Allocate free port
-> 4
: A
-> 1034 # Got 1034
: (port (4000 . 4008) 'A) # Try one of these ports
-> 5
: A
-> 4002
(pp 'sym) -> sym
(pp 'sym 'cls) -> sym
(pp '(sym . cls)) -> sym
sym. The
output format would regenerate that same definition when read and executed. See
also pretty, debug and vi.
: (pp 'tab)
(de tab (Lst . @)
(for N Lst
(let V (next)
(and (gt0 N) (space (- N (length V))))
(prin V)
(and
(lt0 N)
(space (- 0 N (length V))) ) ) )
(prinl) )
-> tab
: (pp 'has> '+Entity)
(dm has> (Var Val)
(or
(nor Val (get This Var))
(has> (meta This Var) Val (get This Var)) ) )
-> has>
: (more (can 'has>) pp)
(dm (has> . +relation) (Val X)
(and (= Val X) X) )
(dm (has> . +Fold) (Val X)
(extra
Val
(if (= Val (fold Val)) (fold X) X) ) )
(dm (has> . +Entity) (Var Val)
(or
(nor Val (get This Var))
(has> (meta This Var) Val (get This Var)) ) )
(dm (has> . +List) (Val X)
(and
Val
(or
(extra Val X)
(find '((X) (extra Val X)) X) ) ) )
(dm (has> . +Bag) (Val X)
(and
Val
(or (super Val X) (car (member Val X))) ) )
(pr 'any ..) -> any
any arguments to the current output
channel in encoded binary format. See also rd, bytes, tell, hear and wr.
: (out "x" (pr 7 "abc" (1 2 3) 'a)) # Print to "x"
-> a
: (hd "x")
00000000 04 0E 0E 61 62 63 01 04 02 04 04 04 06 03 05 61 ...abc.........a
-> NIL
(prEval 'prg ['cnt]) -> any
prg, similar to run, by evaluating all expressions in
prg (within the binding environment given by cnt-1).
As a side effect, all atomic expressions will be printed with prinl. See also eval.
: (let Prg 567
(prEval
'("abc" (prinl (+ 1 2 3)) Prg 987) ) )
abc
6
567
987
-> 987
(pre? 'any1 'any2) -> any2 | NIL
any2 when the string representation of
any1 is a prefix of the string representation of any2.
See also sub?.
: (pre? "abc" "abcdef")
-> "abcdef"
: (pre? "def" "abcdef")
-> NIL
: (pre? (+ 3 4) "7fach")
-> "7fach"
: (pre? NIL "abcdef")
-> "abcdef"
(pretty 'any 'cnt)
any. If any is an atom, or a list
with a size not greater than 12, it is
printed as is. Otherwise, only the
opening parenthesis and the CAR of the list is printed, all other elementes are
pretty-printed recursively indented by three spaces, followed by a space and the
corresponding closing parenthesis. The initial indentation level
cnt defaults to zero. See also pp.
: (pretty '(a (b c d) (e (f (g) (h) (i)) (j (k) (l) (m))) (n o p) q))
(a
(b c d)
(e
(f (g) (h) (i))
(j (k) (l) (m)) )
(n o p)
q )-> ")"
(prin 'any ..) -> any
any arguments to the
current output channel. No space or newline is printed between individual items,
or after the last item. For lists, all elements are prin'ted
recursively. See also prinl.
: (prin 'abc 123 '(a 1 b 2))
abc123a1b2-> (a 1 b 2)
(prinl 'any ..) -> any
any arguments to the
current output channel, followed by a newline. No space or newline is printed
between individual items. For lists, all elements are prin'ted
recursively. See also prin.
: (prinl 'abc 123 '(a 1 b 2))
abc123a1b2
-> (a 1 b 2)
(print 'any ..) -> any
any arguments to the current output channel. If
there is more than one argument, a space is printed between successive
arguments. No space or newline is printed after the last item. See also println, printsp, sym and str
: (print 123)
123-> 123
: (print 1 2 3)
1 2 3-> 3
: (print '(a b c) 'def)
(a b c) def-> def
(println 'any ..) -> any
any arguments to the current output channel,
followed by a newline. If there is more than one argument, a space is printed
between successive arguments. See also print, printsp.
: (println '(a b c) 'def)
(a b c) def
-> def
(printsp 'any ..) -> any
any arguments to the current output channel,
followed by a space. If there is more than one argument, a space is printed
between successive arguments. See also print, println.
: (printsp '(a b c) 'def)
(a b c) def -> def
(prior 'lst1 'lst2) -> lst | NIL
lst2 which immediately precedes the cell
lst1, or NIL if lst1 is not found in
lst2 or is the very first cell. == is used for comparison (pointer equality). See
also offset and memq.
: (setq L (1 2 3 4 5 6))
-> (1 2 3 4 5 6)
: (setq X (cdddr L))
-> (4 5 6)
: (prior X L)
-> (3 4 5 6)
(proc 'sym ..) -> T
sym arguments, using the system ps utility. See also
hd.
: (proc 'pil)
PID PPID STARTED SIZE %CPU WCHAN CMD
16993 3267 12:38:21 1516 0.5 - /usr/bin/picolisp /usr/lib/picolisp/lib.l /usr/bin/pil +
15731 1834 12:36:35 2544 0.1 - /usr/bin/picolisp /usr/lib/picolisp/lib.l /usr/bin/pil app/main.l -main -go +
15823 15731 12:36:44 2548 0.0 - /usr/bin/picolisp /usr/lib/picolisp/lib.l /usr/bin/pil app/main.l -main -go +
-> T
(prog . prg) -> any
prg, and returns the result of the last expression.
See also nil, t, prog1 and prog2.
: (prog (print 1) (print 2) (print 3))
123-> 3
(prog1 'any1 . prg) -> any1
any1. See also nil,
t, prog and prog2.
: (prog1 (print 1) (print 2) (print 3))
123-> 1
(prog2 'any1 'any2 . prg) -> any2
any2. See also nil,
t, prog and prog1.
: (prog2 (print 1) (print 2) (print 3))
123-> 2
(prop 'sym1|lst ['sym2|cnt ..] 'sym) -> var
sym from a symbol. That
symbol is sym1 (if no other arguments are given), or a symbol found
by applying the get algorithm to
sym1|lst and the following arguments. The property (the cons pair,
not just its value) is returned, suitable for direct (destructive) manipulations
with functions expecting a var argument. See also ::.
: (put 'X 'cnt 0)
-> 0
: (prop 'X 'cnt)
-> (0 . cnt)
: (inc (prop 'X 'cnt)) # Directly manipulate the property value
-> 1
: (get 'X 'cnt)
-> 1
(protect . prg) -> any
prg, and returns the result of the last expression. If
a signal is received during that time, its handling will be delayed until the
execution of prg is completed. See also alarm, *Hup, *Sig[12] and kill.
: (protect (journal "db1.log" "db2.log"))
-> T
(prove 'lst ['lst]) -> lst
NIL if not successful. The query list is modified as a
side effect, allowing subsequent calls to prove for further
results. The optional second argument may contain a list of symbols; in that
case the successful matches of rules defined for these symbols will be traced.
See also goal, -> and unify.
: (prove (goal '((equal 3 3))))
-> T
: (prove (goal '((equal 3 @X))))
-> ((@X . 3))
: (prove (goal '((equal 3 4))))
-> NIL
(prune ['cnt])
cnt is
NIL, further pruning will be disabled. Otherwise, all nodes which
have not been accessed (with fetch or
store) for cnt calls to
prune will be wiped. See
also lieu.
(in File1
(while (someData)
(new T '(+Cls1) ..)
(at (0 . 10000) (commit) (prune 100)) ) )
(in File2
(while (moreData)
(new T '(+Cls2) ..)
(at (0 . 10000) (commit) (prune 100)) ) )
(commit)
(prune)
(push 'var 'any ..) -> any
var. The any
arguments are cons'ed in front of the value list. See also push1, pop, queue and fifo.
: (push 'S 3) # Use the VAL of 'S' as a stack
-> 3
: S
-> (3)
: (push 'S 2)
-> 2
: (push 'S 1)
-> 1
: S
-> (1 2 3)
: (push S 999) # Now use the CAR of the list in 'S'
-> 999
: (push S 888 777)
-> 777
: S
-> ((777 888 999 . 1) 2 3)
(push1 'var 'any ..) -> any
var. Each any argument
is cons'ed in front of the value list only if it is not already a member of that list. See also push, pop and queue.
: (push1 'S 1 2 3)
-> 3
: S
-> (3 2 1)
: (push1 'S 2 4)
-> 4
: S
-> (4 3 2 1)
(put 'sym1|lst ['sym2|cnt ..] 'sym|0 'any) ->
any any for a property key
sym (or in the symbol value for zero) in a symbol. That symbol is
sym1 (if no other arguments are given), or a symbol found by
applying the get algorithm to
sym1|lst and the following arguments. See also =:.
: (put 'X 'a 1)
-> 1
: (get 'X 'a)
-> 1
: (prop 'X 'a)
-> (1 . a)
: (setq L '(A B C))
-> (A B C)
: (setq B 'D)
-> D
: (put L 2 0 'p 5) # Store '5' under the 'p' propery of the value of 'B'
-> 5
: (getl 'D)
-> ((5 . p))
(put! 'obj 'sym 'any) -> any
put. Note that for setting property values of
entities typically the put!> message is used. See also
new!, set! and inc!.
(put! Obj 'cnt 0) # Setting a property of a non-entity object
(putl 'sym1|lst1 ['sym2|cnt ..] 'lst) -> lst
lst in a symbol. That
symbol is sym1 (if no other arguments are given), or a symbol found
by applying the get algorithm to
sym1|lst1 and the following arguments. All previously defined
properties for that symbol are lost. See also getl and maps.
: (putl 'X '((123 . a) flg ("Hello" . b)))
-> ((123 . a) flg ("Hello" . b))
: (get 'X 'a)
-> 123
: (get 'X 'b)
-> "Hello"
: (get 'X 'flg)
-> T
(pwd) -> sym
dir and cd.
: (pwd)
-> "/home/app/"
Q
picolisp-3.1.5.2.orig/doc/refR.html 0000644 0000000 0000000 00000057364 12265263724 015520 0 ustar root root
(qsym . sym) -> lst
sym. See
also quote, val and getl.
: (setq A 1234)
-> 1234
: (put 'A 'a 1)
-> 1
: (put 'A 'b 2)
-> 2
: (put 'A 'f T)
-> T
: (qsym . A)
-> (1234 f (2 . b) (1 . a))
(quote . any) -> any
any unevaluated. The reader recognizes the single quote
char ' as a macro for this function. See also lit.
: 'a
-> a
: '(foo a b c)
-> (foo a b c)
: (quote (quote (quote a)))
-> ('('(a)))
(query 'lst ['lst]) -> flg
lst arguments are passed to prove. query displays each
result, waits for console input, and terminates when a non-empty line is
entered. See also ?, pilog and solve.
: (query (goal '((append @X @Y (a b c)))))
@X=NIL @Y=(a b c)
@X=(a) @Y=(b c). # Stop
-> NIL
(queue 'var 'any) -> any
var. The any
argument is (destructively) concatenated to the end of the value list. See also
push, pop and fifo.
: (queue 'A 1)
-> 1
: (queue 'A 2)
-> 2
: (queue 'A 3)
-> 3
: A
-> (1 2 3)
: (pop 'A)
-> 1
: A
-> (2 3)
(quit ['any ['any]])
finally expressions are executed and control
is returned to the top level read-eval-print loop. Otherwise, an error handler
is entered. The first argument can be some error message, and the second might
be the reason for the error. See also Error
Handling.
: (de foo (X) (quit "Sorry, my error" X))
-> foo
: (foo 123) # 'X' is bound to '123'
123 -- Sorry, my error # Error entered
? X # Inspect 'X'
-> 123
? # Empty line: Exit
:
R
picolisp-3.1.5.2.orig/doc/refS.html 0000644 0000000 0000000 00000105373 12265263724 015513 0 ustar root root
*Run
prg expressions which
are used during key, sync, wait and listen. The first element of each expression
must either be a positive number (thus denoting a file descriptor to wait for)
or a negative number (denoting a timeout value in milliseconds (in that case
another number must follow to hold the remaining time)). A select
system call is performed with these values, and the corresponding
prg body is executed when input data are available or when a
timeout occurred. See also task.
: (de *Run (-2000 0 (println '2sec))) # Install 2-sec-timer
-> *Run
: 2sec # Prints "2sec" every 2 seconds
2sec
2sec
# (Ctrl-D) Exit
$
+Ref
+relations, a subclass of +index. Accepts an optional argument for a
+Hook attribute. See also Database.
(rel tel (+Fold +Ref +String)) # Phone number with folded, non-unique index
+Ref2
+relations. Can only be used as a prefix
class to +Key or +Ref. It maintains an index in the current
(sub)class, in addition to that in one of the superclasses, to allow
(sub)class-specific queries. See also Database.
(class +Ord +Entity) # Order class
(rel nr (+Need +Key +Number)) # Order number
...
(class +EuOrd +Ord) # EU-specific order subclass
(rel nr (+Ref2 +Key +Number)) # Order number with backing index
+relation
rel. The class hierarchy
includes the classes +Any, +Bag, +Bool, +Number, +Date, +Time, +Symbol, +String, +Link, +Joint and +Blob, and the prefix classes +Hook, +Hook2, +index, +Key, +Ref, +Ref2, +Idx, +IdxFold, +Sn, +Fold, +Aux, +UB, +Dep, +List, +Need, +Mis and +Alt. See also Database and +Entity.
mis> (Val Obj) # Return error if mismatching type or value
has> (Val X) # Check if the value is present
put> (Obj Old New) # Put new value
rel> (Obj Old New) # Maintain relational strutures
lose> (Obj Val) # Delete relational structures
keep> (Obj Val) # Restore deleted relational structures
zap> (Obj Val) # Clean up relational structures
(rand ['cnt1 'cnt2] | ['T]) -> cnt | flg
T, a
boolean value flg is returned. See also seed.
: (rand 3 9)
-> 3
: (rand 3 9)
-> 7
(range 'num1 'num2 ['num3]) -> lst
num1 through
num2. When num3 is non-NIL), it is used
to increment num1 (if it is smaller than num2) or to
decrement num1 (if it is greater than num2). See also
need.
: (range 1 6)
-> (1 2 3 4 5 6)
: (range 6 1)
-> (6 5 4 3 2 1)
: (range -3 3)
-> (-3 -2 -1 0 1 2 3)
: (range 3 -3 2)
-> (3 1 -1 -3)
range/3
get algorithm to the following arguments.
Typically used as filter predicate in select/3 database queries. See also
Comparing, isa/2, same/3, bool/3, head/3, fold/3, part/3 and tolr/3.
: (?
@Nr (1 . 5) # Numbers between 1 and 5
@Nm "part"
(select (@Item)
((nr +Item @Nr) (nm +Item @Nm))
(range @Nr @Item nr)
(part @Nm @Item nm) ) )
@Nr=(1 . 5) @Nm="part" @Item={3-1}
@Nr=(1 . 5) @Nm="part" @Item={3-2}
-> NIL
(rank 'any 'lst ['flg]) -> lst
lst should be sorted. Returns the
element from lst with a maximal CAR less or equal to
any (if flg is NIL), or with a minimal
CAR greater or equal to any (if flg is
non-NIL), or NIL if no match is found. See also
assoc and Comparing.
: (rank 0 '((1 . a) (100 . b) (1000 . c)))
-> NIL
: (rank 50 '((1 . a) (100 . b) (1000 . c)))
-> (1 . a)
: (rank 100 '((1 . a) (100 . b) (1000 . c)))
-> (100 . b)
: (rank 300 '((1 . a) (100 . b) (1000 . c)))
-> (100 . b)
: (rank 9999 '((1 . a) (100 . b) (1000 . c)))
-> (1000 . c)
: (rank 50 '((1000 . a) (100 . b) (1 . c)) T)
-> (100 . b)
(raw ['flg]) -> flg
NIL for "cooked mode"). Otherwise, the
console is set to the new state. See also key.
$ pil
: (raw)
-> NIL
$ pil +
: (raw)
-> T
(rc 'sym 'any1 ['any2]) -> any
sym, or stores a value
any2 in that file, using a key any1. All values are
stored in a list in the file, using assoc. During the whole operation, the file is
exclusively locked with ctl.
: (info "a.rc") # File exists?
-> NIL # No
: (rc "a.rc" 'a 1) # Store 1 for 'a'
-> 1
: (rc "a.rc" 'b (2 3 4)) # Store (2 3 4) for 'b'
-> (2 3 4)
: (rc "a.rc" 'c 'b) # Store 'b' for 'c'
-> b
: (info "a.rc") # Check file
-> (28 733124 . 61673)
: (in "a.rc" (echo)) # Display it
((c . b) (b 2 3 4) (a . 1))
-> T
: (rc "a.rc" 'c) # Fetch value for 'c'
-> b
: (rc "a.rc" @) # Fetch value for 'b'
-> (2 3 4)
(rd ['sym]) -> any
(rd 'cnt) -> num | NIL
cnt argument (second form), that number
of raw bytes (in big endian format if cnt is positive, otherwise
little endian) is read as a single number. Upon end of file, if the
sym argument is given, it is returned, otherwise NIL.
See also pr, tell, hear and wr.
: (out "x" (pr 'abc "EOF" 123 "def"))
-> "def"
: (in "x" (rd))
-> abc
: (in "x"
(make
(use X
(until (== "EOF" (setq X (rd "EOF"))) # '==' detects end of file
(link X) ) ) ) )
-> (abc "EOF" 123 "def") # as opposed to reading a symbol "EOF"
: (in "/dev/urandom" (rd 20))
-> 396737673456823753584720194864200246115286686486
(read ['sym1 ['sym2]]) -> any
NIL is returned
upon end of file. When called without arguments, an arbitrary Lisp expression is
read. Otherwise, a token (a number, an internal symbol, a transient symbol (for
punctuation), or a list of symbols (for a string)) is read. In that case,
sym1 specifies which set of characters to accept for continuous
symbol names (in addition to the standard alphanumerical characters), and
sym2 an optional comment character. See also any, str, line, skip and eof.
: (list (read) (read) (read)) # Read three things from console
123 # a number
abcd # a symbol
(def # and a list
ghi
jkl
)
-> (123 abcd (def ghi jkl))
: (make (while (read "_" "#") (link @)))
abc = def_ghi("xyz"+-123) # Comment
NIL
-> (abc "=" def_ghi "(" ("x" "y" "z") "+" "-" 123 ")")
(recur fun) -> any
(recurse ..) -> any
recurse on the fly. During the execution of fun, the
symbol recurse is bound to the function definition
fun. See also let and
lambda.
: (de fibonacci (N)
(when (lt0 N)
(quit "Bad fibonacci" N) )
(recur (N)
(if (> 2 N)
1
(+
(recurse (dec N))
(recurse (- N 2)) ) ) ) )
-> fibonacci
: (fibonacci 22)
-> 28657
: (fibonacci -7)
-7 -- Bad fibonacci
(redef sym . fun) -> sym
sym in terms of itself. The current definition is
saved in a new symbol, which is substituted for each occurrence of
sym in fun, and which is also returned. See also
de, undef, daemon and patch.
: (de hello () (prinl "Hello world!"))
-> hello
: (pp 'hello)
(de hello NIL
(prinl "Hello world!") )
-> hello
: (redef hello (A B)
(println 'Before A)
(prog1 (hello) (println 'After B)) )
-> "hello"
: (pp 'hello)
(de hello (A B)
(println 'Before A)
(prog1 ("hello") (println 'After B)) )
-> hello
: (hello 1 2)
Before 1
Hello world!
After 2
-> "Hello world!"
: (redef * @
(msg (rest))
(pass *) )
-> "*"
: (* 1 2 3)
(1 2 3)
-> 6
: (redef + @
(pass (ifn (num? (next)) pack +) (arg)) )
-> "+"
: (+ 1 2 3)
-> 6
: (+ "a" 'b '(c d e))
-> "abcde"
(rel var lst [any ..]) -> any
var in the current class *Class, using lst as the list of
classes for that relation, and possibly additional arguments any
for its initialization. See also Database, class, extend, dm and var.
(class +Person +Entity)
(rel nm (+List +Ref +String)) # Names
(rel tel (+Ref +String)) # Telephone
(rel adr (+Joint) prs (+Address)) # Address
(class +Address +Entity)
(rel cit (+Need +Hook +Link) (+City)) # City
(rel str (+List +Ref +String) cit) # Street
(rel prs (+List +Joint) adr (+Person)) # Inhabitants
(class +City +Entity)
(rel nm (+List +Ref +String)) # Zip / Names
(release 'sym) -> NIL
acquire.
: (release "sema1")
-> NIL
remote/2
*Ext, select/3 and db/3.
(setq *Ext # Set up external offsets
(mapcar
'((@Host @Ext)
(cons @Ext
(curry (@Host @Ext (Sock)) (Obj)
(when (or Sock (setq Sock (connect @Host 4040)))
(ext @Ext
(out Sock (pr (cons 'qsym Obj)))
(prog1 (in Sock (rd))
(unless @
(close Sock)
(off Sock) ) ) ) ) ) ) )
'("localhost")
'(20) ) )
(de rsrc () # Simple resource handler, ignoring errors or EOFs
(extract
'((@Ext Host)
(let? @Sock (connect Host 4040)
(cons
(curry (@Ext @Sock) (X) # out
(ext @Ext (out @Sock (pr X))) )
(curry (@Ext @Sock) () # in
(ext @Ext (in @Sock (rd))) ) ) ) )
'(20)
'("localhost") ) )
: (?
@Nr (1 . 3)
@Sup 2
@Rsrc (rsrc)
(remote (@Item . @Rsrc)
(db nr +Item @Nr @Item)
(val @Sup @Item sup nr) )
(show @Item) )
{L-2} (+Item)
pr 1250
inv 100
sup {K-2}
nm Spare Part
nr 2
@Nr=(1 . 3) @Sup=2 @Rsrc=((((X) (ext 20 (out 16 (pr X)))) NIL (ext 20 (in 16 (rd))))) @Item={L-2}
-> NIL
(remove 'cnt 'lst) -> lst
cnt from lst. This
is a non-destructive operation. See also insert, place, append, delete and replace.
: (remove 3 '(a b c d e))
-> (a b d e)
: (remove 1 '(a b c d e))
-> (b c d e)
: (remove 9 '(a b c d e))
-> (a b c d e)
(repeat) -> lst
repeat/0 and be.
(be a (1)) # Define three facts
(be a (2))
(be a (3))
(repeat) # Unlimited supply
: (? (a @N))
@N=1
@N=2
@N=3
@N=1
@N=2
@N=3. # Stop
-> NIL
repeat/0
repeat and
true/0.
: (be integer (@I) # Generate unlimited supply of integers
(^ @C (box 0)) # Init to zero
(repeat) # Repeat from here
(^ @I (inc (-> @C))) )
-> integer
: (? (integer @X))
@X=1
@X=2
@X=3
@X=4. # Stop
-> NIL
(replace 'lst 'any1 'any2 ..) -> lst
lst all occurrences of any1 with
any2. For optional additional argument pairs, this process is
repeated. This is a non-destructive operation. See also append, delete, insert, remove and place.
: (replace '(a b b a) 'a 'A)
-> (A b b A)
: (replace '(a b b a) 'b 'B)
-> (a B B a)
: (replace '(a b b a) 'a 'B 'b 'A)
-> (B A A B)
(request 'typ 'var ['hook] 'val ..) -> obj
db), a new object of the given type is
created (using new). See also obj.
: (request '(+Item) 'nr 2)
-> {3-2}
(rest) -> lst
@). Returns the list of all remaining arguments from the internal
list. See also args, next, arg and pass.
: (de foo @ (println (rest)))
-> foo
: (foo 1 2 3)
(1 2 3)
-> (1 2 3)
(retract) -> lst
be, clause, asserta and assertz.
: (be a (1))
-> a
: (be a (2))
-> a
: (be a (3))
-> a
: (retract '(a (2)))
-> (((1)) ((3)))
: (? (a @N))
@N=1
@N=3
-> NIL
retract/1
retract, asserta/1 and assertz/1.
: (be a (1))
-> a
: (be a (2))
-> a
: (be a (3))
-> a
: (? (retract (a 2)))
-> T
: (rules 'a)
1 (be a (1))
2 (be a (3))
-> a
(reverse 'lst) -> lst
lst. See also flip.
: (reverse (1 2 3 4))
-> (4 3 2 1)
(rewind) -> flg
T when successful. See also flush.
: (out "a" (prinl "Hello world"))
-> "Hello world"
: (in "a" (echo))
Hello world
-> T
: (info "a")
-> (12 733216 . 53888)
: (out "a" (rewind))
-> T
: (info "a")
-> (0 733216 . 53922)
(rollback) -> flg
commit.
: (pool "db")
-> T
# .. Modify external objects ..
: (rollback) # Rollback
-> T
(root 'tree) -> (num . sym)
num, and the base node in sym. See also tree.
: (root (tree 'nr '+Item))
-> (7 . {7-1})
(rot 'lst ['cnt]) -> lst
lst are (destructively)
shifted right, and the value from the last cell is stored in the first cell.
Without the optional cnt argument, the whole list is rotated,
otherwise only the first cnt elements. See also flip .
: (rot (1 2 3 4)) # Rotate all four elements
-> (4 1 2 3)
: (rot (1 2 3 4 5 6) 3) # Rotate only the first three elements
-> (3 1 2 4 5 6)
(round 'num1 'num2) -> sym
num1 with num2 decimal places,
according to the current scale *Scl.
num2 defaults to 3. See also Numbers
and format.
: (scl 4) # Set scale to 4
-> 4
: (round 123456) # Format with three decimal places
-> "12.346"
: (round 123456 2) # Format with two decimal places
-> "12.35"
: (format 123456 *Scl) # Format with full precision
-> "12.3456"
(rules 'sym ..) -> sym
sym arguments. See also Pilog and be.
: (rules 'member 'append)
1 (be member (@X (@X . @)))
2 (be member (@X (@ . @Y)) (member @X @Y))
1 (be append (NIL @X @X))
2 (be append ((@A . @X) @Y (@A . @Z)) (append @X @Y @Z))
-> append
(run 'any ['cnt ['lst]]) -> any
any is an atom, run behaves like eval. Otherwise any is a list,
which is evaluated in sequence. The last result is returned. If a binding
environment offset cnt is given, that evaluation takes place in the
corresponding environment, and an optional lst of excluded symbols
can be supplied. See also up.
: (run '((println (+ 1 2 3)) (println 'OK)))
6
OK
-> OK
S
picolisp-3.1.5.2.orig/doc/refT.html 0000644 0000000 0000000 00000053453 12265263724 015515 0 ustar root root
*Scl
scl.
: (str "123.45") # Default value of '*Scl' is 0
-> (123)
: (setq *Scl 3)
-> 3
: (str "123.45")
-> (123450)
: 123.4567
-> 123457
: 12.3456
-> 12346
*Sig1
*Sig2
prg bodies, which
will be executed when a SIGUSR1 signal (or a SIGUSR2 signal, respectively) is
sent to the current process. See also alarm, sigio and *Hup.
: (de *Sig1 (msg 'SIGUSR1))
-> *Sig1
*Solo
0 initially, set to T (or NIL) during
cooperative database locks when lock
is successfully called with a NIL (or non-NIL)
argument. See also *Zap.
: *Solo
-> 0
: (lock *DB)
-> NIL
: *Solo
-> NIL
: (rollback)
-> T
: *Solo
-> 0
: (lock)
-> NIL
: *Solo
-> T
: (rollback)
-> T
: *Solo
-> T
+Sn
+String relations. Typically used in
combination with the +Idx prefix
class. See also Database.
(rel nm (+Sn +Idx +String)) # Name
+String
+Symbol. Accepts an optional argument for
the string length (currently not used). See also Database.
(rel nm (+Sn +Idx +String)) # Name, indexed by soundex and substrings
+Swap
+relations
where the data are to be stored in the value of a separate external symbol
instead of the relation's object. Typically used for data which are relatively
large and/or rarely accessed. Doesn't work with bidirectional relations
(+Joint or +index). See also Database.
(rel pw (+Swap +String)) # Password
(rel nr (+Swap +List +Number)) # List of bignums
+Symbol
+relation. Objects of that class typically
maintain internal symbols, as opposed to the more often-used +String for transient symbols. See also Database.
(rel perm (+List +Symbol)) # Permission list
same/3
get algorithm to the following arguments.
Typically used as filter predicate in select/3 database queries. See also
isa/2, bool/3, range/3, head/3, fold/3, part/3 and tolr/3.
: (?
@Nr 2
@Nm "Spare"
(select (@Item)
((nr +Item @Nr) (nm +Item @Nm))
(same @Nr @Item nr)
(head @Nm @Item nm) ) )
@Nr=2 @Nm="Spare" @Item={3-2}
(scan 'tree ['fun] ['any1] ['any2] ['flg])
fun to all key-value
pairs. fun should be a function accepting two arguments for key and
value. It defaults to println.
any1 and any2 may specify a range of keys. If
any2 is greater than any1, the traversal will be in
opposite direction. Note that the keys need not to be atomic, depending on the
application's index structure. If flg is non-NIL,
partial keys are skipped. See also tree, iter, init and step.
: (scan (tree 'nm '+Item))
("ASLRSNSTRSTN" {3-3} . T) {3-3}
("Additive" {3-4}) {3-4}
("Appliance" {3-6}) {3-6}
("Auxiliary Construction" . {3-3}) {3-3}
("Construction" {3-3}) {3-3}
("ENNSNNTTTF" {3-4} . T) {3-4}
("Enhancement Additive" . {3-4}) {3-4}
("Fittings" {3-5}) {3-5}
("GTSTFLNS" {3-6} . T) {3-6}
("Gadget Appliance" . {3-6}) {3-6}
...
: (scan (tree 'nm '+Item) println NIL T T) # 'flg' is non-NIL
("Auxiliary Construction" . {3-3}) {3-3}
("Enhancement Additive" . {3-4}) {3-4}
("Gadget Appliance" . {3-6}) {3-6}
("Main Part" . {3-1}) {3-1}
("Metal Fittings" . {3-5}) {3-5}
("Spare Part" . {3-2}) {3-2}
("Testartikel" . {3-8}) {3-8}
-> {7-6}
(scl 'num [. prg]) -> num
prg is given, it binds *Scl dynamically to num during the
execution of prg. Otherwise, it sets *Scl globally to num. See also Numbers.
: (scl 0)
-> 0
: (str "123.45")
-> (123)
: (scl 1)
-> 1
: (read)
123.45
-> 1235
: (scl 3)
-> 3
: (str "123.45")
-> (123450)
: (scl 1 (str "123.45"))
-> (1235)
: *Scl
-> 3
(script 'any ..) -> any
any argument is loaded, with the remaining arguments passed as variable arguments. They can be
accessed with next, arg, args and rest. With that, the syntax in the script is
the same as that in the body of a function with variable arguments (see lambda expressions, "when the CAR is the symbol @").
$ cat x
(* (next) (next))
$ pil +
: (script "x" 3 4)
-> 12
(sect 'lst 'lst) -> lst
lst arguments. See also
diff.
: (sect (1 2 3 4) (3 4 5 6))
-> (3 4)
: (sect (1 2 3) (4 5 6))
-> NIL
(seed 'any) -> cnt
rand and hash.
: (seed "init string")
-> 2015582081
: (rand)
-> -706917003
: (rand)
-> 1224196082
: (seed (time))
-> 128285383
(seek 'fun 'lst ..) -> lst
fun to lst and all successive CDRs, until
non-NIL is returned. Returns the tail of lst starting
with that element, or NIL if fun did not return
non-NIL for any element of lst. When additional
lst arguments are given, they are passed to fun in the
same way. See also find, pick.
: (seek '((X) (> (car X) 9)) (1 5 8 12 19 22))
-> (12 19 22)
(select [var ..] cls [hook|T] [var val ..]) -> obj | NIL
SELECT' command. A (limited) front-end to the Pilog select/3 predicate. When called with only a
cls argument, select steps through all objects of that
class, and shows their complete
contents (this is analog to 'SELECT * from CLS'). If cls is
followed by attribute/value specifications, the search is limited to these
values (this is analog to 'SELECT * from CLS where VAR = VAL'). If between the
select function and cls one or several attribute names
are supplied, only these attribute (instead of the full show) are
printed. These attribute specifications may also be lists, then the get algorithm will be used to retrieve related
data. See also update, Database and Pilog.
: (select +Item) # Show all items
{3-1} (+Item)
nr 1
pr 29900
inv 100
sup {2-1}
nm "Main Part"
{3-2} (+Item)
nr 2
pr 1250
inv 100
sup {2-2}
nm "Spare Part"
. # Stop
-> {3-2}
: (select +Item nr 3) # Show only item 3
{3-3} (+Item)
nr 3
sup {2-1}
pr 15700
nm "Auxiliary Construction"
inv 100
. # Stop
-> {3-3}
# Show selected attributes for items 3 through 3
: (select nr nm pr (sup nm) +Item nr (3 . 5))
3 "Auxiliary Construction" 157.00 "Active Parts Inc." {3-3}
4 "Enhancement Additive" 9.99 "Seven Oaks Ltd." {3-4}
5 "Metal Fittings" 79.80 "Active Parts Inc." {3-5}
-> NIL
select/3
+index and other
relations. It takes a list of Pilog variables, a list of generator clauses, and
an arbitrary number of filter clauses. The functionality is described in detail
in The 'select' Predicate. See also db/3, isa/2, same/3, bool/3, range/3, head/3, fold/3, part/3, tolr/3 and remote/2.
: (?
@Nr (2 . 5) # Select all items with numbers between 2 and 5
@Sup "Active" # and suppliers matching "Active"
(select (@Item) # Bind results to '@Item'
((nr +Item @Nr) (nm +CuSu @Sup (sup +Item))) # Generator clauses
(range @Nr @Item nr) # Filter clauses
(part @Sup @Item sup nm) ) )
@Nr=(2 . 5) @Sup="Active" @Item={3-3}
@Nr=(2 . 5) @Sup="Active" @Item={3-5}
-> NIL
(send 'msg 'obj ['any ..]) -> any
msg to the object obj,
optionally with arguments any. If the message cannot be located in
obj, its classes and superclasses, an error "Bad
message" is issued. See also OO Concepts,
try, method, meth, super and extra.
: (send 'stop> Dlg) # Equivalent to (stop> Dlg)
-> NIL
(seq 'cnt|sym1) -> sym | NIL
cnt'th database file, or the next external symbol following
sym1 in the database, or NIL when the end of the
database is reached. See also free.
: (pool "db")
-> T
: (seq *DB)
-> {2}
: (seq @)
-> {3}
(set 'var 'any ..) -> any
any in the var arguments. See
also setq, val, con and def.
: (set 'L '(a b c) (cdr L) '999)
-> 999
: L
-> (a 999 c)
(set! 'obj 'any) -> any
set. Note that for setting the value of entities
typically the set!> message
is used. See also new!, put! and inc!.
(set! Obj (* Count Size)) # Setting a non-entity object to a numeric value
(setq var 'any ..) -> any
any in the var arguments. See
also set, val and def.
: (setq A 123 B (list A A)) # Set 'A' to 123, then 'B' to (123 123)
-> (123 123)
(show 'any ['sym|cnt ..]) -> any
get algorithm to any and
the following arguments. See also edit
and view.
: (setq A 123456)
-> 123456
: (put 'A 'x 1)
-> 1
: (put 'A 'lst (9 8 7))
-> (9 8 7)
: (put 'A 'flg T)
-> T
: (show 'A)
A 123456
flg
lst (9 8 7)
x 1
-> A
: (show 'A 'lst 2)
-> 8
show/1
show.
: (? (db nr +Item 2 @Item) (show @Item))
{3-2} (+Item)
nm "Spare Part"
nr 2
pr 1250
inv 100
sup {2-2}
@Item={3-2}
-> NIL
(sigio 'cnt . prg) -> cnt
prg for SIGIO on the file descriptor
cnt. Returns the file descriptor. See also alarm, *Hup and *Sig[12].
# First session
: (sigio (setq *SigSock (port T 4444)) # Register signal handler at UDP port
(while (udp *SigSock) # Queue all received data
(fifo '*SigQueue @) ) )
-> 3
# Second session
: (for I 7 (udp "localhost" 4444 I)) # Send numbers to first session
# First session
: (fifo '*SigQueue)
-> 1
: (fifo '*SigQueue)
-> 2
(size 'any) -> cnt
any. For numbers this is the number of
bytes needed for the value, for external symbols it is the number of bytes it
would occupy in the database, for other symbols it is the number of bytes
occupied by the UTF-8 representation of the name, and for lists it is the total
number of cells in this list and all its sublists. See also length and bytes.
: (size "abc")
-> 3
: (size "äbc")
-> 4
: (size 127) # One byte
-> 1
: (size 128) # Two bytes (eight bits plus sign bit!)
-> 2
: (size (1 (2) 3))
-> 4
: (size (1 2 3 .))
-> 3
(skip ['any]) -> sym
any is given) in the
input stream. Returns the next available character, or NIL upon end
of file. See also peek and eof.
$ cat a
# Comment
abcd
$ pil +
: (in "a" (skip "#"))
-> "a"
(solve 'lst [. prg]) -> lst
prg is given, it is executed for each result
set, with all Pilog variables bound to their matching values, and returns a list
of the results. See also pilog,
?, goal and prove.
: (solve '((append @X @Y (a b c))))
-> (((@X) (@Y a b c)) ((@X a) (@Y b c)) ((@X a b) (@Y c)) ((@X a b c) (@Y)))
: (solve '((append @X @Y (a b c))) @X)
-> (NIL (a) (a b) (a b c))
(sort 'lst ['fun]) -> lst
lst by destructively exchanging its elements. If
fun is given, it is used as a "less than" predicate for
comparisons. Typically, sort is used in combination with by, giving shorter and often more efficient solutions
than with the predicate function. See also Comparing,
group, maxi, mini and uniq.
: (sort '(a 3 1 (1 2 3) d b 4 T NIL (a b c) (x y z) c 2))
-> (NIL 1 2 3 4 a b c d (1 2 3) (a b c) (x y z) T)
: (sort '(a 3 1 (1 2 3) d b 4 T NIL (a b c) (x y z) c 2) >)
-> (T (x y z) (a b c) (1 2 3) d c b a 4 3 2 1 NIL)
: (by cadr sort '((1 4 3) (5 1 3) (1 2 4) (3 8 5) (6 4 5)))
-> ((5 1 3) (1 2 4) (1 4 3) (6 4 5) (3 8 5))
(space ['cnt]) -> cnt
cnt spaces, or a single space when cnt is
not given. See also beep, prin and char.
: (space)
-> 1
: (space 1)
-> 1
: (space 2)
-> 2
(sp? 'any) -> flg
T when the argument any is
NIL, or if it is a string (symbol) that consists only of whitespace
characters.
: (sp? " ")
-> T
: (sp? "ABC")
-> NIL
: (sp? 123)
-> NIL
(split 'lst 'any ..) -> lst
lst at all places containing an element any
and returns the resulting list of sublists. See also stem.
: (split (1 a 2 b 3 c 4 d 5 e 6) 'e 3 'a)
-> ((1) (2 b) (c 4 d 5) (6))
: (mapcar pack (split (chop "The quick brown fox") " "))
-> ("The" "quick" "brown" "fox")
(sqrt 'num ['flg|num]) -> num
num argument. If
flg is given and non-NIL, the result will be rounded.
If in addition to that flg is a number, the first argument will be
multiplied with it before doing the square root calculation. See also */.
: (sqrt 64)
-> 8
: (sqrt 1000)
-> 31
: (sqrt 1000 T)
-> 32
: (sqrt 10000000000000000000000000000000000000000)
-> 100000000000000000000
: (scl 6)
-> 6
: (sqrt 2.0 1.0)
-> 1414214
(stack ['cnt]) -> cnt | (.. sym . cnt)
cnt argument, or if already one or more coroutines are
running, the current size in megabytes is returned. Otherwise, the stack segment
size is set to the new value (default 1 MB). The main segment's size is always
four times the size of coroutine segments. If there are running coroutines,
their tags will be consed in front of
the size. See also heap.
$ ulimit -s unlimited && pil + # Guarantee stack space
: (stack) # Current size
-> 1
: (stack 4) # Set to 4 MB
-> 4
: (co 'inc (let N 0 (loop (yield (inc 'N))))) # Create two coroutines
-> 1
: (co 'dec (let N 0 (loop (yield (dec 'N)))))
-> -1
: (stack)
-> (dec inc . 4)
(stamp ['dat 'tim]|['T]) -> sym
dat and tim is missing, the current date and time is
used. If T is passed, the current Coordinated Universal Time (UTC)
is used instead. See also date and
time.
: (stamp)
-> "2000-09-12 07:48:04"
: (stamp (date) 0)
-> "2000-09-12 00:00:00"
: (stamp (date 2000 1 1) (time 12 0 0))
-> "2000-01-01 12:00:00"
(state 'var (sym|lst exe [. prg]) ..) -> any
var holds the
current state as a symbolic value. When a clause is found that contains the
current state in its CAR sym|lst value, and where the
exe in its CADR evaluates to non-NIL, the current
state will be set to that value, the body prg in the CDDR will be
executed, and the result returned. T is a catch-all for any state.
If no state-condition matches, NIL is returned. See also case, cond and job.
: (de tst ()
(job '((Cnt . 4))
(state '(start)
(start 'run
(printsp 'start) )
(run (and (gt0 (dec 'Cnt)) 'run)
(printsp 'run) )
(run 'stop
(printsp 'run) )
(stop 'start
(setq Cnt 4)
(println 'stop) ) ) ) )
-> tst
: (do 12 (tst))
start run run run run stop
start run run run run stop
-> stop
: (pp 'tst)
(de tst NIL
(job '((Cnt . 4))
(state '(start)
...
-> tst
: (do 3 (tst))
start run run -> run
: (pp 'tst)
(de tst NIL
(job '((Cnt . 2))
(state '(run)
...
-> tst
(stem 'lst 'any ..) -> lst
lst that does not contain any of the
any arguments. (stem 'lst 'any ..) is equivalent to
(last (split 'lst 'any ..)). See also tail and split.
: (stem (chop "abc/def\\ghi") "/" "\\")
-> ("g" "h" "i")
(step 'lst ['flg]) -> any
lst is a
structure as received from init. If
flg is non-NIL, partial keys are skipped. See also
tree, scan, iter, leaf and fetch.
: (setq Q (init (tree 'nr '+Item) 3 5))
-> (((3 . 5) ((3 NIL . {3-3}) (4 NIL . {3-4}) (5 NIL . {3-5}) (6 NIL . {3-6}) (7 NIL . {3-8}))))
: (get (step Q) 'nr)
-> 3
: (get (step Q) 'nr)
-> 4
: (get (step Q) 'nr)
-> 5
: (get (step Q) 'nr)
-> NIL
(store 'tree 'any1 'any2 ['(num1 . num2)])
any2 for the key any1 in a database
tree. num1 is a database file number, as used in new (defaulting to 1), and num2 a
database block size (defaulting to 256). When any2 is
NIL, the corresponding entry is deleted from the tree. See also
tree and fetch.
: (store (tree 'nr '+Item) 2 '{3-2})
(str 'sym ['sym1]) -> lst
(str 'lst) -> sym
sym is parsed into a list. This
mechanism is also used by load. If
sym1 is given, it should specify a set of characters, and
str will then return a list of tokens analog to read. The second form does the reverse
operation by building a string from a list. See also any, name and sym.
: (str "a (1 2) b")
-> (a (1 2) b)
: (str '(a "Hello" DEF))
-> "a \"Hello\" DEF"
: (str "a*3+b*4" "_")
-> (a "*" 3 "+" b "*" 4)
(str? 'any) -> sym | NIL
any when it is a transient symbol
(string), otherwise NIL. See also sym?, box? and ext?.
: (str? 123)
-> NIL
: (str? '{ABC})
-> NIL
: (str? 'abc)
-> NIL
: (str? "abc")
-> "abc"
(strDat 'sym) -> dat
sym in the date format of the current
locale to a date. See also expDat, $dat and datStr.
: (strDat "2007-06-01")
-> 733134
: (strDat "01.06.2007")
-> NIL
: (locale "DE" "de")
-> NIL
: (strDat "01.06.2007")
-> 733134
: (strDat "1.6.2007")
-> 733134
(strip 'any) -> any
quote symbols from any.
: (strip 123)
-> 123
: (strip '''(a))
-> (a)
: (strip (quote quote a b c))
-> (a b c)
(struct 'num 'any 'any ..) -> any
native C functions. The first
num argument should be a native value, either a scalar, or a
pointer obtained by calling functions like malloc(). The second
argument any is a result
specification, while all following initialization items are stored in the structure
pointed to by the first argument. See also Native C
Calls.
: (scl 2)
-> 2
## /* We assume the following C structure */
## typedef struct value {
## int x, y;
## double a, b, c;
## long z;
## char nm[4];
## } value;
# Allocate structure
: (setq P (native "@" "malloc" 'N 44))
-> 9204032
# Store two integers, three doubles, one long, and four characters
: (struct P 'N -7 -4 (1.0 0.11 0.22 0.33) (7 . 8) 65 66 67 0)
-> 9204032
# Extract the structure
: (struct P '((I . 2) (1.0 . 3) N (C . 4)))
-> ((7 4) (11 22 33) 7 ("A" "B" "C" NIL))
# Do both in a single call (allowing conversions of data types)
: (struct P
'((I . 2) (1.0 . 3) N (C . 4))
-7 -4 (1.0 0.11 0.22 0.33) (7 . 8) 65 66 67 0 )
-> ((7 4) (11 22 33) 7 ("A" "B" "C" NIL))
# De-allocate structure
: (native "@" "free" NIL P)
-> NIL
(sub? 'any1 'any2) -> any2 | NIL
any2 when the string representation of
any1 is a substring of the string representation of
any2. See also pre?.
: (sub? "def" "abcdef")
-> T
: (sub? "abb" "abcdef")
-> NIL
: (sub? NIL "abcdef")
-> T
(subr 'sym) -> num
expr back to a C-function.
: car
-> 67313448
: (expr 'car)
-> (@ (pass $385260187))
: (subr 'car)
-> 67313448
: car
-> 67313448
(sum 'fun 'lst ..) -> num
fun to each element of lst. When
additional lst arguments are given, their elements are also passed
to fun. Returns the sum of all numeric values returned from
fun.
: (setq A 1 B 2 C 3)
-> 3
: (sum val '(A B C))
-> 6
: (sum * (3 4 5) (5 6 7)) # Vector dot product
-> 74
: (sum # Total size of symbol list values
'((X)
(and (pair (val X)) (size @)) )
(what) )
-> 32021
(super ['any ..]) -> any
This, this time starting the search for a method at the
superclass(es) of the class where the current method was found. See also OO Concepts, extra, method, meth, send and try.
(dm stop> () # 'stop>' method of current class
(super) # Call the 'stop>' method of the superclass
... ) # other things
(swap 'var 'any) -> any
var to any, and return the
previous value. See also xchg and
set.
: (setq A 7 L (1 2 3))
-> (1 2 3)
: (swap (cdr L) (swap 'A 'xyz))
-> 2
: A
-> xyz
: L
-> (1 7 3)
(sym 'any) -> sym
any into the name of a
new symbol sym. This is the reverse operation of any. See also name and str.
: (sym '(abc "Hello" 123))
-> "(abc \"Hello\" 123)"
(sym? 'any) -> flg
T when the argument any is a symbol. See
also str?, box? and ext?.
: (sym? 'a)
-> T
: (sym? NIL)
-> T
: (sym? 123)
-> NIL
: (sym? '(a b))
-> NIL
(symbols) -> sym
(symbols 'sym1) -> sym2
(symbols 'sym1 'sym ..) -> sym2
sym1, and the previous namespace
sym2 is returned. In the third form, sym1 is assigned
a balanced copy of the existing
namespace(s) sym, and becomes the new current namespace, returning
the previous namespace sym2. If in the third form more than one
sym argument is given, possibly conflicting symbols in later
namespaces are not interned into sym2. See also pico, local, import, intern and load.
: (symbols 'myLib 'pico)
-> pico
myLib: (de foo (X)
(bar (inc X)) )
-> foo
myLib: (symbols 'pico)
-> myLib
: (pp 'foo)
(de foo . NIL)
-> foo
: (pp 'myLib~foo)
(de "foo" (X)
("bar" (inc X)) )
-> "foo"
: (symbols 'myLib)
-> pico
myLib: (pp 'foo)
(de foo (X)
(bar (inc X)) )
-> foo
myLib:
(sync) -> flg
tell
mechanism), a select system call is executed for all file
descriptors and timers in the VAL of the global variable *Run. When used in a non-database context,
(tell) should be called in the end to inform the parent process
that it may grant synchronization to other processes waiting for
sync. In a database context, where sync is usually
called by dbSync, this is not
necessary because it is done internally by commit or rollback.
See also key and wait.
: (or (lock) (sync)) # Ensure database consistency
-> T # (numeric process-id if lock failed)
(sys 'any ['any]) -> sym
: (sys "TERM") # Get current value
-> "xterm"
: (sys "TERM" "vt100") # Set new value
-> "vt100"
: (sys "TERM")
-> "vt100"
T
picolisp-3.1.5.2.orig/doc/refU.html 0000644 0000000 0000000 00000034113 12265263724 015506 0 ustar root root
*Tmp
tmp. See also *Bye.
: *Bye
-> ((saveHistory) (and *Tmp (call 'rm "-r" *Tmp)))
: (tmp "foo" 123)
-> "/home/app/.pil/tmp/27140/foo123"
: *Tmp
-> "/home/app/.pil/tmp/27140/"
*Tsm
print will output these sequences to
the console instead of the standard double quote markup characters. An easy way
to switch on transient symbol markup is loading "@lib/tsm.l".
: (de *Tsm "^[[4m" . "^[[24m") # vt100 escape sequences for underline
-> *Tsm
: Hello world
-> Hello world
: (off *Tsm)
-> NIL
: "Hello world" # No underlining
-> "Hello world"
+Time
time), a subclass of +Number. See also Database.
(rel tim (+Time)) # Time of the day
T
T is commonly returned
as the boolean value "true" (though any non-NIL values could be
used). It represents the absolute maximum, as it is larger than any other
object. As a property key, it is used to store Pilog clauses, and inside Pilog clauses it is the
cut operator. See also NIL and
and Comparing.
: T
-> T
: (= 123 123)
-> T
: (get 'not T)
-> ((@P (1 (-> @P)) T (fail)) (@P))
This
with statement. As it is a normal symbol,
however, it can be used in normal bindings anywhere. See also isa, :,
=:, :: and var:.
: (with 'X (println 'This 'is This))
This is X
-> X
: (put 'X 'a 1)
-> 1
: (put 'X 'b 2)
-> 2
: (put 'Y 'a 111)
-> 111
: (put 'Y 'b 222)
-> 222
: (mapcar '((This) (cons (: a) (: b))) '(X Y))
-> ((1 . 2) (111 . 222))
(t . prg) -> T
prg, and returns T. See also nil, prog, prog1 and prog2.
: (t (println 'OK))
OK
-> T
(tab 'lst 'any ..) -> NIL
any arguments in a tabular format. lst
should be a list of numbers, specifying the field width for each argument. All
items in a column will be left-aligned for negative numbers, otherwise
right-aligned. See also align,
center and wrap.
: (let Fmt (-3 14 14)
(tab Fmt "Key" "Rand 1" "Rand 2")
(tab Fmt "---" "------" "------")
(for C '(A B C D E F)
(tab Fmt C (rand) (rand)) ) )
Key Rand 1 Rand 2
--- ------ ------
A 0 1481765933
B -1062105905 -877267386
C -956092119 812669700
D 553475508 -1702133896
E 1344887256 -1417066392
F 1812158119 -1999783937
-> NIL
(tail 'cnt|lst 'lst) -> lst
cnt elements of lst. If
cnt is negative, it is added to the length of lst. If
the first argument is a lst, tail is a predicate
function returning that argument list if it is equal to the tail of
the second argument, and NIL otherwise. (tail -2 Lst)
is equivalent to (nth Lst 3). See also offset, head, last and stem.
: (tail 3 '(a b c d e f))
-> (d e f)
: (tail -2 '(a b c d e f))
-> (c d e f)
: (tail 0 '(a b c d e f))
-> NIL
: (tail 10 '(a b c d e f))
-> (a b c d e f)
: (tail '(d e f) '(a b c d e f))
-> (d e f)
(task 'num ['num] [sym 'any ..] [. prg]) -> lst
*Run global. If
called with only a single num argument, the corresponding entry is
removed from the value of *Run. Otherwise, a new entry is created.
If an entry with that key already exists, an error is issued. For negative
numbers, a second number must be supplied. If sym/any
arguments are given, a job environment
is built for thie *Run entry. See also forked and timeout.
: (task -10000 5000 N 0 (msg (inc 'N))) # Install task
-> (-10000 5000 (job '((N . 0)) (msg (inc 'N)))) # for every 10 seconds
: 1 # ... after 5 seconds
2 # ... after 10 seconds
3 # ... after 10 seconds
(task -10000) # remove again
-> NIL
: (task (port T 4444) (eval (udp @))) # Receive RPC via UDP
-> (3 (eval (udp @)))
# Another session (on the same machine)
: (udp "localhost" 4444 '(println *Pid)) # Send RPC message
-> (println *Pid)
(telStr 'sym) -> sym
locale. If the string head matches the local
country code, it is replaced with 0, otherwise + is
prepended. See also expTel, datStr, money and format.
: (telStr "49 1234 5678-0")
-> "+49 1234 5678-0"
: (locale "DE" "de")
-> NIL
: (telStr "49 1234 5678-0")
-> "01234 5678-0"
(tell ['cnt] 'sym ['any ..]) -> any
(sym any ..) to all family
members (i.e. all children of the current process, and all other children of the
parent process, see fork) for
automatic execution. When the cnt argument is given and non-zero,
it should be the PID of such a process, and the list will be sent only to that
process. tell is also used internally by commit to notify about database changes. When
called without arguments, no message is actually sent, and the parent process
may grant sync to the next waiting
process. See also hear.
: (call 'ps "x") # Show processes
PID TTY STAT TIME COMMAND
..
1321 pts/0 S 0:00 /usr/bin/picolisp .. # Parent process
1324 pts/0 S 0:01 /usr/bin/picolisp .. # First child
1325 pts/0 S 0:01 /usr/bin/picolisp .. # Second child
1326 pts/0 R 0:00 ps x
-> T
: *Pid # We are the second child
-> 1325
: (tell 'println '*Pid) # Ask all others to print their Pid's
1324
-> *Pid
(test 'any . prg)
prg, and issues an error if the result does not match the any argument. See also
assert.
: (test 12 (* 3 4))
-> NIL
: (test 12 (+ 3 4))
((+ 3 4))
12 -- 'test' failed
?
(text 'any1 'any ..) -> sym
any1, by replacing all occurrences of an at-mark "@",
followed by one of the letters "1" through "9", and
"A" through "Z", with the corresponding
any argument. In this context "@A" refers to the 10th
argument. A literal at-mark in the text can be represented by two successive
at-marks. See also pack and glue.
: (text "abc @1 def @2" 'XYZ 123)
-> "abc XYZ def 123"
: (text "a@@bc.@1" "de")
-> "a@bc.de"
(throw 'sym 'any)
catch environment with the jump label
sym (or T as a catch-all). Any pending finally expressions are executed, local
symbol bindings are restored, open files are closed and internal data structures
are reset appropriately, as the environment was at the time when the
corresponding catch was called. Then any is returned
from that catch. See also quit.
: (de foo (N)
(println N)
(throw 'OK) )
-> foo
: (let N 1 (catch 'OK (foo 7)) (println N))
7
1
-> 1
(tick (cnt1 . cnt2) . prg) -> any
prg, then (destructively) adds the number of elapsed
user ticks to the cnt1 parameter, and the number of elapsed system
ticks to the cnt2 parameter. Thus, cnt1 and
cnt2 will finally contain the total number of user and system time
ticks spent in prg and all functions called (this works also for
recursive functions). For execution profiling, tick is usually
inserted into words with prof, and removed with
unprof. See also usec.
: (de foo () # Define function with empty loop
(tick (0 . 0) (do 100000000)) )
-> foo
: (foo) # Execute it
-> NIL
: (pp 'foo)
(de foo NIL
(tick (97 . 0) (do 100000000)) ) # 'tick' incremented 'cnt1' by 97
-> foo
(till 'any ['flg]) -> lst|sym
any is found (or until end of file if any is
NIL). If flg is NIL, a list of
single-character transient symbols is returned. Otherwise, a single string is
returned. See also from and line.
: (till ":")
abc:def
-> ("a" "b" "c")
: (till ":" T)
abc:def
-> "abc"
(tim$ 'tim ['flg]) -> sym
time tim.
If flg is NIL, the format is HH:MM, otherwise it is
HH:MM:SS. See also $tim and dat$.
: (tim$ (time))
-> "10:57"
: (tim$ (time) T)
-> "10:57:56"
(time ['T]) -> tim
(time 'tim) -> (h m s)
(time 'h 'm ['s]) -> tim | NIL
(time '(h m [s])) -> tim | NIL
T argument, the time of the last call to
date is returned. When called with a
single number tim, it is taken as a time value and a list with the
corresponding hour, minute and second is returned. When called with two or three
numbers (or a list of two or three numbers) for the hour, minute (and optionally
the second), the corresponding time value is returned (or NIL if
they do not represent a legal time). See also date, stamp, usec, tim$ and $tim.
: (time) # Now
-> 32334
: (time 32334) # Now
-> (8 58 54)
: (time 25 30) # Illegal time
-> NIL
(timeout ['num])
*Run global, so that the current process
executes bye after the given period. If
called without arguments, the timeout is removed. See also task.
: (timeout 3600000) # Timeout after one hour
-> (-1 3600000 (bye))
: *Run # Look after a few seconds
-> ((-1 3574516 (bye)))
(tmp ['any ..]) -> sym
packed any arguments in a
process-local temporary directory. The directory name consists of the path to
".pil/tmp/" in the user's home directory, followed by the current process ID
*Pid. This directory is automatically
created if necessary, and removed upon termination of the process (bye). See also pil, *Tmp and *Bye .
: *Pid
-> 27140
: (tmp "foo" 123)
-> "/home/app/.pil/tmp/27140/foo123"
: (out (tmp "foo" 123) (println 'OK))
-> OK
: (dir (tmp))
-> ("foo123")
: (in (tmp "foo" 123) (read))
-> OK
tolr/3
+Sn soundex match of the result of
applying the get algorithm to the
following arguments. Typically used as filter predicate in select/3 database queries. See also
isa/2, same/3, bool/3, range/3, head/3, fold/3 and part/3.
: (?
@Nr (1 . 5)
@Nm "Sven"
(select (@CuSu)
((nr +CuSu @Nr) (nm +CuSu @Nm))
(range @Nr @CuSu nr)
(tolr @Nm @CuSu nm) )
(val @Name @CuSu nm) )
@Nr=(1 . 5) @Nm="Sven" @CuSu={2-2} @Name="Seven Oaks Ltd."
(touch 'sym) -> sym
sym is an external symbol, it is marked as "modified" so
that upon a later commit it will be
written to the database file. An explicit call of touch is only
necessary when the value or properties of sym are indirectly
modified.
: (get '{2} 'lst)
-> (1 2 3 4 5)
: (set (cdr (get (touch '{2}) 'lst)) 999) # Only read-access, need 'touch'
-> 999
: (get '{2} 'lst) # Modified second list element
-> (1 999 3 4 5)
(trace 'sym) -> sym
(trace 'sym 'cls) -> sym
(trace '(sym . cls)) -> sym
$ trace
function call at the beginning of the function or method body of
sym, so that trace information will be printed before and after
execution. Built-in functions (C-function pointer) are automatically converted
to Lisp expressions (see expr). See
also *Dbg, traceAll and untrace, debug and lint.
: (trace '+)
-> +
: (+ 3 4)
+ : 3 4
+ = 7
-> 7
(traceAll ['lst]) -> sym
$ function call at the beginning. lst
may contain symbols which are to be excluded from that process. In addition, all
symbols in the global variable *NoTrace are excluded. See also
trace, untrace and *Dbg.
: (traceAll) # Trace all Lisp level functions
-> balance
(trail ['flg]) -> lst
flg is NIL, the symbols and their values are omitted,
and only the expressions are returned. See also up and env.
: (de f (A B)
(g (inc A) (dec B)) )
-> f
: (de g (X Y)
(trail T) )
-> g
: (f 3 4)
-> ((f 3 4) A 3 B 4 (g (inc A) (dec B)) X 4 Y 3)
: (for (L (f 3 4) L) # Pretty-print trail
(if (pair (car L))
(println (pop 'L))
(space 3)
(println (pop 'L) (pop 'L)) ) )
L NIL
(f 3 4)
A 3
B 4
(g (inc A) (dec B))
X 4
Y 3
(tree 'var 'cls ['hook]) -> tree
var
and cls determine the relation, with an optional hook
object. See also root, fetch, store, count, leaf, minKey, maxKey, init, step, scan, iter, prune, zapTree and chkTree.
: (tree 'nm '+Item)
-> (nm . +Item)
(trim 'lst) -> lst
lst with all trailing whitespace characters
or NIL elements removed. See also clip.
: (trim (1 NIL 2 NIL NIL))
-> (1 NIL 2)
: (trim '(a b " " " "))
-> (a b)
true/0
fail/0 and repeat/0.
: (? (true))
-> T
(try 'msg 'obj ['any ..]) -> any
msg to the object obj,
optionally with arguments any. If obj is not an
object, or if the message cannot be located in obj, in its classes
or superclasses, NIL is returned. See also OO Concepts, send, method, meth, super and extra.
: (try 'msg> 123)
-> NIL
: (try 'html> 'a)
-> NIL
(type 'any) -> lst
sym. See also
OO Concepts, isa, class, new and object.
: (type '{1A;3})
(+Address)
: (type '+DnButton)
-> (+Tiny +Rid +JS +Able +Button)
U
picolisp-3.1.5.2.orig/doc/refV.html 0000644 0000000 0000000 00000012376 12265263724 015516 0 ustar root root
*Uni
idx
tree, with all unique data that were collected with the comma (,)
read-macro. Typically used for localization. See also Read-Macros and locale.
: (off *Uni) # Clear
-> NIL
: ,"abc" # Collect a transient symbol
-> "abc"
: ,(1 2 3) # Collect a list
-> (1 2 3)
: *Uni
-> ("abc" NIL (1 2 3))
+UB
+Aux to maintain
an UB-Tree index instead of the direct values. This allows efficient range
access to multidimensional data. Only positive numeric keys are supported. See
also ubIter and Database.
(class +Pos +Entity)
(rel x (+UB +Aux +Ref +Number) (y z))
(rel y (+Number))
(rel z (+Number))
: (scan (tree 'x '+Pos))
(288362200753438306 . {13}) {13}
(348187139486943716 . {16}) {16}
(605261596962573238 . {11}) {11}
(638523558602802506 . {7}) {7} # UBKEY of (453062 450921 613956)
(654697989157410399 . {12}) {12}
...
: (show '{7})
{7} (+Pos)
x 453062
y 450921
z 613956
-> {7}
# Discrete queries work the same way as without the +UB prefix
: (db 'x '+Pos 453062 'y 450921 'z 613956)
-> {7}
: (aux 'x '+Pos 453062 450921 613956)
-> {7}
: (? (db x +Pos (453062 450921 613956) @Pos))
@Pos={7}
-> NIL
# Range queries work efficiently with 'collect'. Note that though also Pilog
queries can handle UB-trees, they may do so sub-optimally for certain ranges.
: (collect 'x '+Pos (200000 200000 200000) (899999 899999 899999))
-> ({7} {14} {17} {15})
(u) -> T
! all
breakpoints in all subexpressions of the current breakpoint. Typically used when
single-stepping a function or method with debug. See also d and unbug.
! (u) # Unbug subexpression(s) at breakpoint
-> T
(ubIter 'tree 'dim 'fun 'lst1 'lst2)
+UB tree, by applying fun to all
values. dim is the number of the key dimensions, lst1
and lst2 specify a range of keys. collect uses ubIter internally
for UB-tree queries. See also iter.
: (ubIter (tree 'x '+Pos) 3 show (200000 200000 200000) (899999 899999 899999))
{7} (+Pos)
z 613956
y 450921
x 453062
{14} (+Pos)
z 771372
y 262217
x 862358
{17} (+Pos)
z 676836
y 529576
x 398229
{15} (+Pos)
z 889332
y 691799
x 265381
-> NIL
(udp 'any1 'any2 'any3) -> any
(udp 'cnt) -> any
any3 is sent to a UDP server listening at host any1,
port any2. In the second form, one item is received from a UDP
socket cnt, established with port. See also listen and connect.
# First session
: (port T 6666)
-> 3
: (udp 3) # Receive a datagram
# Second session (on the same machine)
: (udp "localhost" 6666 '(a b c))
-> (a b c)
# First session
-> (a b c)
(ultimo 'y 'm) -> cnt
date of the last day
of the month m in the year y. See also day and week.
: (date (ultimo 2007 1))
-> (2007 1 31)
: (date (ultimo 2007 2))
-> (2007 2 28)
: (date (ultimo 2004 2))
-> (2004 2 29)
: (date (ultimo 2000 2))
-> (2000 2 29)
: (date (ultimo 1900 2))
-> (1900 2 28)
(unbug 'sym) -> T
(unbug 'sym 'cls) -> T
(unbug '(sym . cls)) -> T
!
breakpoints in the function or method body of sym, as inserted with debug or d, or directly with edit. See also u.
: (pp 'tst)
(de tst (N)
(! println (+ 3 N)) ) # 'tst' has a breakpoint '!'
-> tst
: (unbug 'tst) # Unbug it
-> T
: (pp 'tst) # Restore
(de tst (N)
(println (+ 3 N)) )
(undef 'sym) -> fun
(undef 'sym 'cls) -> fun
(undef '(sym . cls)) -> fun
sym. Returns the previous
definition. See also de, dm, def
and redef.
: (de hello () "Hello world!")
-> hello
: hello
-> (NIL "Hello world!")
: (undef 'hello)
-> (NIL "Hello world!")
: hello
-> NIL
(unify 'any) -> lst
any with the current Pilog
environment at the current level and with a value of NIL, and
returns the new environment or NIL if not successful. See also
prove and ->.
: (? (^ @A (unify '(@B @C))))
@A=(((NIL . @C) 0 . @C) ((NIL . @B) 0 . @B) T)
(uniq 'lst) -> lst
lst. See also Comparing, sort and group.
: (uniq (2 4 6 1 2 3 4 5 6 1 3 5))
-> (2 4 6 1 3 5)
uniq/2
idx is used internally storing for the values
and checking for uniqueness. See also member/2.
: (? (uniq a @Z)) # Remember 'a'
@Z=NIL # Succeeded
: (? (uniq b @Z)) # Remember 'b'
@Z=NIL # Succeeded
: (? (uniq a @Z)) # Remembered 'a'?
-> NIL # Yes: Not unique
(unless 'any . prg) -> any
any evaluates to
non-NIL, NIL is returned. Otherwise prg
is executed and the result returned. See also when.
: (unless (= 3 3) (println 'Strange 'result))
-> NIL
: (unless (= 3 4) (println 'Strange 'result))
Strange result
-> result
(until 'any . prg) -> any
any evaluates to
NIL, prg is repeatedly executed. If prg
is never executed, NIL is returned. Otherwise the result of
prg is returned. See also while.
: (until (=T (setq N (read)))
(println 'square (* N N)) )
4
square 16
9
square 81
T
-> 81
(untrace 'sym) -> sym
(untrace 'sym 'cls) -> sym
(untrace '(sym . cls)) -> sym
$ trace
function call at the beginning of the function or method body of
sym, so that no more trace information will be printed before and
after execution. Built-in functions (C-function pointer) are automatically
converted to their original form (see subr). See also trace and traceAll.
: (trace '+) # Trace the '+' function
-> +
: +
-> (@ ($ + @ (pass $385455126))) # Modified for tracing
: (untrace '+) # Untrace '+'
-> +
: +
-> 67319120 # Back to original form
(up [cnt] sym ['val]) -> any
cnt'th previously saved value of
sym in the corresponding enclosing environment. If cnt
is not given, 1 is used. The 64-bit version also allows to omit the
sym argument, then the corresponding expression (function or method
call) is returned. See also eval,
run, trail and env.
: (let N 1 ((quote (N) (println N (up N))) 2))
2 1
-> 1
: (let N 1 ((quote (N) (println N (up N) (up N 7))) 2) N)
2 1 7
-> 7
: (de foo (N)
(println (up)) # 64-bits only
(inc N) )
-> foo
: (foo 7)
(foo 7)
-> 8
(upd sym ..) -> lst
wipe. upd is the
standard function passed to commit
during database transactions.
(commit 'upd) # Commit changes, informing all sister processes
(update 'obj ['var]) -> obj
obj argument, update
steps through the value and all properties of that object (and recursively also
through substructures) and allows to edit them with the console line editor.
When the var argument is given, only that single property is handed
to the editor. To delete a propery, NIL must be explicitly entered.
update will correctly handle all entity/relation mechanisms. See also select, edit and Database.
: (show '{3-1}) # Show item 1
{3-1} (+Item)
nr 1
pr 29900
inv 100
sup {2-1}
nm "Main Part"
-> {3-1}
: (update '{3-1} 'pr) # Update the prices of that item
{3-1} pr 299.00 # The cursor is right behind "299.00"
-> {3-1}
(upp? 'any) -> sym | NIL any when the argument is a string (symbol) that starts with an
uppercase character. See also uppc and
low?
: (upp? "A")
-> T
: (upp? "a")
-> NIL
: (upp? 123)
-> NIL
: (upp? ".")
-> NIL
(uppc 'any) -> any
any is not a symbol, it is returned
as it is. Otherwise, a new transient symbol with all characters of
any, converted to upper case, is returned. See also lowc, fold and upp?.
: (uppc 123)
-> 123
: (uppc "abc")
-> "ABC"
: (uppc 'car)
-> "CAR"
(use sym . prg) -> any
(use (sym ..) . prg) -> any
sym - or the
values of the symbols sym in the list of the second form - are
saved, prg is executed, then the symbols are restored to their
original values. During execution of prg, the values of the symbols
can be temporarily modified. The return value is the result of prg.
See also bind, job and let.
: (setq X 123 Y 456)
-> 456
: (use (X Y) (setq X 3 Y 4) (* X Y))
-> 12
: X
-> 123
: Y
-> 456
(useKey 'var 'cls ['hook]) -> num
genKey.
: (maxKey (tree 'nr '+Item))
-> 8
: (useKey 'nr '+Item)
-> 12
(usec ['flg]) -> num
flg is
non-NIL, the microsecond fraction of the last call to time is returned, otherwise the number of
microseconds since interpreter startup. See also date and tick.
: (usec)
-> 1154702479219050
: (list (date (date)) (time (time T)) (usec T))
-> ((2013 1 4) (10 12 39) 483321)
V
picolisp-3.1.5.2.orig/doc/refW.html 0000644 0000000 0000000 00000014126 12265263724 015512 0 ustar root root
(val 'var) -> any
var. See also setq, set and def.
: (setq L '(a b c))
-> (a b c)
: (val 'L)
-> (a b c)
: (val (cdr L))
-> b
val/3
get algorithm to that object. See also db/3 and select/3.
: (?
(db nr +Item (2 . 5) @Item) # Fetch articles 2 through 5
(val @Nm @Item nm) # Get item description
(val @Sup @Item sup nm) ) # and supplier's name
@Item={3-2} @Nm="Spare Part" @Sup="Seven Oaks Ltd." @Item={3-3} @Nm="Auxiliary Construction" @Sup="Active Parts Inc."
@Item={3-4} @Nm="Enhancement Additive" @Sup="Seven Oaks Ltd."
@Item={3-5} @Nm="Metal Fittings" @Sup="Active Parts Inc."
-> NIL
(var sym . any) -> any
(var (sym . cls) . any) -> any
sym with the initial value
any for the current class, implicitly given by the value of the
global variable *Class, or - in the
second form - for the explicitly given class cls. See also OO Concepts, rel and var:.
: (class +A)
-> +A
: (var a . 1)
-> 1
: (var b . 2)
-> 2
: (show '+A)
+A NIL
b 2
a 1
-> +A
(var: sym) -> any
sym for the current
object This, by searching the property
lists of its class(es) and supperclasses. See also OO
Concepts, var, with, meta, :,
=: and ::.
: (object 'O '(+A) 'a 9 'b 8)
-> O
: (with 'O (list (: a) (: b) (var: a) (var: b)))
-> (9 8 1 2)
(version ['flg]) -> lst
flg is non-NIL, printing is suppressed.
$ pil -version
3.0.1.22
: (version T)
-> (3 0 1 22)
(vi 'sym) -> sym
(vi 'sym 'cls) -> sym
(vi '(sym . cls)) -> sym
(vi) -> NIL
sym. A call to ld
thereafter will load the modified
file. A call without arguments permanently switches the REPL line editor and the
edit function to "vi" mode. See also
doc, edit, em, *Dbg, debug and pp.
: (vi 'url> '+CuSu) # Edit the method's source code, then exit from 'vi'
-> T
(view 'lst ['T]) -> any
lst as tree-structured ASCII graphics. When the
T argument is given, lst should be a binary tree
structure (as generated by idx), which
is then shown as a left-rotated tree. See also pretty and show.
: (balance 'I '(a b c d e f g h i j k l m n o))
-> NIL
: I
-> (h (d (b (a) c) f (e) g) l (j (i) k) n (m) o)
: (view I)
+-- h
|
+---+-- d
| |
| +---+-- b
| | |
| | +---+-- a
| | |
| | +-- c
| |
| +-- f
| |
| +---+-- e
| |
| +-- g
|
+-- l
|
+---+-- j
| |
| +---+-- i
| |
| +-- k
|
+-- n
|
+---+-- m
|
+-- o
-> NIL
: (view I T)
o
n
m
l
k
j
i
h
g
f
e
d
c
b
a
-> NIL
W
picolisp-3.1.5.2.orig/doc/refX.html 0000644 0000000 0000000 00000002477 12265263724 015521 0 ustar root root
(wait ['cnt] . prg) -> any
prg
is NIL, a select system call is executed for all file
descriptors and timers in the VAL of the global variable *Run. When cnt is
non-NIL, the waiting time is limited to cnt
milliseconds. Returns the result of prg. See also key and sync.
: (wait 2000) # Wait 2 seconds
-> NIL
: (prog
(zero *Cnt)
(setq *Run # Install background loop
'((-2000 0 (println (inc '*Cnt)))) ) # Increment '*Cnt' every 2 sec
(wait NIL (> *Cnt 6)) # Wait until > 6
(off *Run) )
1 # Waiting ..
2
3
4
5
6
7
-> NIL
(week 'dat) -> num
date dat. See also day, ultimo, datStr and strDat.
: (datStr (date))
-> "2007-06-01"
: (week (date))
-> 22
(when 'any . prg) -> any
any evaluates to
non-NIL, prg is executed and the result is returned.
Otherwise NIL is returned. See also unless.
: (when (> 4 3) (println 'OK) (println 'Good))
OK
Good
-> Good
(while 'any . prg) -> any
any evaluates to
non-NIL, prg is repeatedly executed. If
prg is never executed, NIL is returned. Otherwise the
result of prg is returned. See also until.
: (while (read)
(println 'got: @) )
abc
got: abc
1234
got: 1234
NIL
-> 1234
(what 'sym) -> lst
sym. See also match, who and can.
: (what "cd@dr")
-> (cdaddr cdaadr cddr cddddr cdddr cddadr cdadr)
(who 'any) -> lst
any. See also match, what and can.
: (who 'caddr) # Who is using 'caddr'?
-> ($dat lint1 expDat datStr $tim tim$ mail _gen dat$ datSym)
: (who "Type error")
-> ((mis> . +Link) *Uni (mis> . +Joint))
: (more (who "Type error") pp) # Pretty print all results
(dm (mis> . +Link) (Val Obj)
(and
Val
(nor (isa (: type) Val) (canQuery Val))
"Type error" ) )
. # Stop
-> T
(wipe 'sym|lst) -> sym|lst
VAL and the property list of sym, or of
all symbols in the list lst. When a symbol is an external symbol,
its state is also set to "not loaded". Does nothing when sym is an
external symbol that has been modified or deleted ("dirty").
: (setq A (1 2 3 4))
-> (1 2 3 4)
: (put 'A 'a 1)
-> 1
: (put 'A 'b 2)
-> 2
: (show 'A)
A (1 2 3 4)
b 2
a 1
-> A
: (wipe 'A)
-> A
: (show 'A)
A NIL
-> A
(with 'sym . prg) -> any
This and sets it to the new value
sym. Then prg is executed, and This is
restored to its previous value. The return value is the result of
prg. Used typically to access the local data of sym in
the same manner as inside a method body. prg is not executed (and
NIL is returned) when sym is NIL.
(with 'X . prg) is equivalent to (let? This 'X . prg).
: (put 'X 'a 1)
-> 1
: (put 'X 'b 2)
-> 2
: (with 'X (list (: a) (: b)))
-> (1 2)
(wr 'cnt ..) -> cnt
cnt arguments as raw bytes to the current output
channel. See also rd and pr.
: (out "x" (wr 1 255 257)) # Write to "x"
-> 257
: (hd "x")
00000000 01 FF 01 ...
-> NIL
(wrap 'cnt 'lst) -> sym
lst packed in lines with a maximal length of
cnt. See also tab,
align and center.
: (wrap 20 (chop "The quick brown fox jumps over the lazy dog"))
-> "The quick brown fox^Jjumps over the lazy^Jdog"
: (wrap 8 (chop "The quick brown fox jumps over the lazy dog"))
-> "The^Jquick^Jbrown^Jfox^Jjumps^Jover the^Jlazy dog"
X
picolisp-3.1.5.2.orig/doc/refY.html 0000644 0000000 0000000 00000003677 12265263724 015525 0 ustar root root
(xchg 'var 'var ..) -> any
var argument pairs. See also
swap and set.
: (setq A 1 B 2 C '(a b c))
-> (a b c)
: (xchg 'A C 'B (cdr C))
-> 2
: A
-> a
: B
-> b
: C
-> (1 2 c)
(xor 'any 'any) -> flg
NIL.
: (xor T NIL)
-> T
: (xor T T)
-> NIL
(x| 'num ..) -> num
XOR of all num arguments. When
one of the arguments evaluates to NIL, it is returned immediately.
See also &, | and bit?.
: (x| 2 7)
-> 5
: (x| 2 7 1)
-> 4
Y
picolisp-3.1.5.2.orig/doc/refZ.html 0000644 0000000 0000000 00000006214 12265263724 015514 0 ustar root root
(yield 'any ['sym]) -> any
sym tag is not given), or to some other coroutine (specified by
sym) to continue execution at the point where that coroutine had
called yield before. In the first case, the value any
will be returned from the corresponding co call, in the second case it will be the return
value of that yield call. See also stack, catch and throw.
: (co "rt1" # Start first routine
(msg (yield 1) " in rt1 from rt2") # Return '1', wait for value from "rt2"
7 ) # Then return '7'
-> 1
: (co "rt2" # Start second routine
(yield 2 "rt1") ) # Send '2' to "rt1"
2 in rt1 from rt2
-> 7
(yoke 'any ..) -> any
any in front of the list in
the current make environment.
yoke returns the last inserted argument. See also link, chain and made.
: (make (link 2 3) (yoke 1) (link 4))
-> (1 2 3 4)
Z
picolisp-3.1.5.2.orig/CHANGES 0000644 0000000 0000000 00000040050 12265263724 014142 0 ustar root root * XXmar14 picoLisp-3.1.6
* 31dec13 picoLisp-3.1.5
Phone GUI support
'prune' LRU scheme
Bug in volatile properties
'cnt2' argument to 'gc' (64-bit)
Improved UB-Tree support
* 30sep13 picoLisp-3.1.4
Bug in bignum 'rd' (64-bit)
'swap' function
Optimized 'sqrt'
Changed 'canvas' to '*Zap
*Solo is NIL, external
symbols which are no longer accessible can be collected in the CAR, e.g. during
DB tree processing, and written to the file in the CDR at the next commit. A (typically periodic) call to
zap_ will clean them up later.
: (setq *Zap '(NIL . "db/app/_zap"))
-> "db/app/_zap"
(zap 'sym) -> sym
sym. For internal symbols, that means to
remove it from the internal index, effectively transforming it to a transient
symbol. For external symbols, it means to mark it as "deleted", so that upon a
later commit it will be removed from
the database file. See also intern.
: (de foo (Lst) (car Lst)) # 'foo' calls 'car'
-> foo
: (zap 'car) # Delete the symbol 'car'
-> "car"
: (pp 'foo)
(de foo (Lst)
("car" Lst) ) # 'car' is now a transient symbol
-> foo
: (foo (1 2 3)) # 'foo' still works
-> 1
: (car (1 2 3)) # Reader returns a new 'car' symbol
!? (car (1 2 3))
car -- Undefined
?
(zapTree 'sym)
tree, chkTree and prune.
: (zapTree (cdr (root (tree 'nm '+Item))))
(zap_)
zap) of
external symbols which were collected e.g. during DB tree processing. An
auxiliary file (with the name taken from the CDR of the value of *Zap, concatenated with a "_"
character) is used as an intermediary file.
: *Zap
-> (NIL . "db/app/Z")
: (call 'ls "-l" "db/app")
...
-rw-r--r-- 1 abu abu 1536 2007-06-23 12:34 Z
-rw-r--r-- 1 abu abu 1280 2007-05-23 12:15 Z_
...
: (zap_)
...
: (call 'ls "-l" "db/app")
...
-rw-r--r-- 1 abu abu 1536 2007-06-23 12:34 Z_
...
(zero var ..) -> 0
0 in all var arguments. See also one, on,
off and onOff.
: (zero A B)
-> 0
: A
-> 0
: B
-> 0