D

*DB

A global variable holding the external symbol {1} (the database root) while a database is open, otherwise NIL. All external 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

A boolean variable indicating "debug mode". It can be conveniently switched on with a trailing + 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, dm and symbols. 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

A global variable holding a list of numbers (block size scale factors, as needed by pool). It is typically set by dbs.

: *Dbs
-> (1 2 1 0 2 3 3 3)

+Date

Class for calender dates (as calculated by date), a subclass of +Number. See also Database.

(rel dat (+Ref +Date))  # Indexed date

+Dep

+Joint prefix class for maintaining dependencies between +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.

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:

(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

(Debug mode only) Inserts ! 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

Inserts prg in the beginning of the function (first form), the method body of sym in cls (second form) or in the class obtained by getting sym2 from *Class (or cls if given) (third form). Built-in functions (SUBRs) 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

Formats a 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

Formats a 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

Formats a date dat 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

Calculates a (gregorian) calendar date. It is represented as a day number, starting first of March of the year 0 AD. When called without arguments, the current date is returned. When called with a 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

Returns the name of the day for a given 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 'sym 'cls ['hook] 'any ['sym 'any ..]) -> sym | NIL

Returns a database object of class cls, where the values for the sym arguments correspond to the any arguments. If a matching object cannot be found, NIL is returned. sym, 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)
-> {B1}
: (db 'nm '+Item "Main Part")
-> {B1}

db/3

db/4

db/5

Pilog database predicate that returns objects matching the given key-value (and optional hook) relation. The relation should be of type +index. For the key pattern applies:

• a symbol (string) returns all entries which start with that string
• other atoms (numbers, external symbols) match as they are
• cons pairs constitute a range, returning objects
  • in increasing order if the CDR is greater than the CAR
  • in decreasing order otherwise
• other lists are matched for +Aux key combinations

The optional hook can be supplied as the third argument. See also select/3 and remote/2.

: (? (db nr +Item @Item))              # No value given
 @Item={B1}
 @Item={B2}
 @Item={B3}
 @Item={B4}
 @Item={B5}
 @Item={B6}
-> NIL

: (? (db nr +Item 2 @Item))            # Get item no. 2
 @Item={B2}
-> NIL

: (? (db nm +Item Spare @Item) (show @Item))  # Search for "Spare.."
{B2} (+Item)
   pr 1250
   inv 100
   sup {C2}
   nm "Spare Part"
   nr 2
 @Item={B2}
-> NIL

(db: cls ..) -> num

Returns the database file number for objects of the type given by the cls argument(s). Needed, for example, for the creation of new objects. See also dbs.

: (db: +Item)
-> 3

(dbSync 'obj) -> flg

Starts a database transaction, by trying to obtain a lock on the database root object *DB (or obj if given), 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

Performs a low-level integrity check of the current (or 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 committing newly allocated (new) external symbols) are appended to the free list.

: (pool "db")
-> T
: (dbck)
-> NIL

(dbs . lst)

Initializes the global variable *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 pool.

(dbs
   (3 +Role +User +Sal (+User pw))              # 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
-> (3 0 1 2 2 4 4 4 4 4 4 4)
: (get '+Item 'Dbf)
-> (3 . 128)
: (get '+Item 'nr 'dbf)
-> (9 . 1024)

(de sym . any) -> sym

Assigns a definition to the 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)

(debug 'sym 'cls)

(debug '(sym . cls))

(Debug mode only) Inserts a ! 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

(-debug)

(Debug mode only) Command line frontend to debug. See also -trace.

$ ./pil --debug tst +

(dec 'num) -> num

(dec 'var ['num]) -> num

The first form returns the value of 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|cnt 'any) -> sym1

The first form assigns a definition to the first sym argument, by setting its VAL's to any. The second form defines a property value any for the first argument's sym2 key (or the symbol value for zero). 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

Stores new values 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 ['flg]) -> lst

Deletes any from the list in the value of var, and returns the remaining list. If flg is NIL and any is contained more than once in the value of var, only the first occurrence is deleted. (del 'any 'var) is equivalent to (set 'var (delete 'any var)). See also delete, rid, 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 ['flg]) -> lst

Deletes any from lst. If flg is NIL and any is contained more than once in lst, only the first occurrence is deleted. See also delq, del, 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

Pilog predicate that succeeds if deleting the first argument from the list in the second argument is equal to the third argument. See also delete and member/2.

: (? (delete b (a b c) @X))
 @X=(a c)
-> NIL

(delq 'any 'lst ['flg]) -> lst

Deletes any from lst. If flg is NIL and any is contained more than once in lst, only the first occurrence is deleted. == is used for comparison (pointer equality). See also delete, asoq, push1q, memq, mmeq and Comparing.

: (delq 'b '(a b c))
-> (a c)
: (delq (2) (1 (2) 3))
-> (1 (2) 3)

(dep 'cls) -> cls

(Debug mode only) Displays the "dependencies" of cls, i.e. the tree of superclasses and the tree of subclasses. See also OO Concepts, methods, class, what, who, has and 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)

Returns the maximal (cnt1) and the average (cnt2) "depth" of a tree structure as maintained by idx. The total number of nodes is stored in the global variable @@. 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

: (balance 'X (1 2 3 4 5 6 7))               # Build a balanced tree
-> NIL
: (depth X)
-> (3 . 2)                                   # Depth is 3, average 2

(detach) -> pid | NIL

Detach the current process from its PicoLisp parent, and return the parent's process ID. This causes the parent to "forget" this child process (freeing resources like buffers and pipes), effectively disabling family IPC via tell. See also fork and kids.

: (unless (fork)
   (detach)
   (runAlone)
   (bye) )

(diff 'lst1 'lst2) -> lst

Returns the difference of list arguments, all elements of lst1 which are not in lst2. See also sect.

: (diff (1 2 3 4 5) (2 4))
-> (1 3 5)
: (diff (1 2 3) (1 2 3))
-> NIL

different/2

Pilog predicate that succeeds if the two arguments are different. See also equal/2.

: (? (different 3 4))
-> T

(dir ['any] ['flg]) -> lst

Returns a list of all filenames in the directory 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

Returns the directory part of a path name 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

Defines a method for the message 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 getting 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

Counted loop with multiple conditional exits: The body is executed at most 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])

(Debug mode only) Opens a browser, and tries to display the reference documentation for 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, docs and vi.

: (doc '+)  # Function reference
-> NIL
: (doc '+relation)  # Class reference
-> NIL
: (doc)  # Reference manual
-> NIL
:  (doc 'vi "firefox")  # Use alternative browser
-> NIL

(docs 'any)

(Debug mode only) Parses all files with names of the form "ref@.html" in the directory any, to set the doc property for later calls to doc.

: (docs "@doc/")
-> NIL

(download 'host 'src 'dst) -> any

Tries to download the file src from host with "@bin/ssl", and stores it in dst. Returns non-NIL if successful. See also ssl.

: (download "de.wikipedia.org" "static/images/wikimedia-button.png" "button.png")
-> 0
: (info "button.png")
-> (2426 736804 . 35589)