# D

`*DB`
  A global constant holding the external symbol `{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`
  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 `+relation`s. 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 `get`ting `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 `commit`ting 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 '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. 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 `get`ting `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)