# I

`+Idx`
  Prefix class for maintaining non-unique full-text indexes to `+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`
  Prefix class for maintaining non-unique indexes to subsequent substrings of the `fold`ed 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`
  Abstract base class of all database B-Tree index relations (prefix classes for `+relation`s). 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)`
  Converts one (the internal block number) or two (file and block) numbers to an external symbol, or an external symbol to a number or a pair of numbers.

      : (id 7)
      -> {7}
      : (id 1 2)
      -> {2}
      : (id '{A2})
      -> 2
      : (id '{A2} T)
      -> (2 . 2)

`(idx 'var 'any 'flg) -> lst`
`(idx 'var 'any) -> lst`
`(idx 'var) -> lst`
  Maintains an index tree in `var`, 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`. If all elements are inserted in sorted order, the tree degenerates into a linear list. In such cases, `0` may be passed for `flg` to randomize the insertion order. 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. See also `lup`, `enum`, `hash`, `rev`, `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

      : (off X Y)
      -> NIL
      : (for I 9 (idx 'X I T))                     # Sorted insert order
      -> NIL
      : (for I 9 (idx 'Y I 0))                     # Randomize
      -> NIL
      : (view X T)
                              9
                           8
                        7
                     6
                  5
               4
            3
         2
      1
      -> NIL
      : (view Y T)
               9
            8
               7
         6
            5
               4
      3
         2
            1
      -> NIL

`(if 'any1 any2 . prg) -> any`
  Conditional execution: If the condition `any1` evaluates to non-`NIL`, `any2` is evaluated and returned. Otherwise, `prg` is executed and the result returned. See also `ifn`, `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`
  Four-way conditional execution for two conditions: If both conditions `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`
  Conditional execution ("If not"): If the condition `any1` evaluates to `NIL`, `any2` is evaluated and returned. Otherwise, `prg` is executed and the result returned. See also `if`, `nor`, `nand`, `unless` and `nond`.

      : (ifn (= 3 4) (println 'OK) (println 'Bad))
      OK
      -> OK

`(import . lst) -> lst`
  Wrapper function for `intern`. Typically used to import symbols from other namespaces, as created by `symbols`. `lst` should be a list of symbols. See also `pico`, `private` and `local` and `export`.

      : (import libA~foo libB~bar)
      -> (foo bar)

`(in 'any . prg) -> any`
  Opens `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 in read-only mode). 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. The (system dependent) exit status code of the child process is stored in the global variable `@@`. See also `out`, `err`, `fd`, `ipid`, `call`, `load`, `file`, `poll`, `pipe` and `ctl`.

      : (in "a" (list (read) (read) (read)))  # Read three items from file "a"
      -> (123 (a b c) def)

      : (in '(file "-b" "--mime" "bin/picolisp")  # Get the mime type
         (line T) )
      -> "application/x-executable; charset=binary"

`(inc 'num) -> num`
`(inc 'var ['num]) -> num`
  The first form returns the value of `num` 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`
  Transaction wrapper function for `inc`. `num` defaults to 1. Note that for incrementing a property value of an entity typically the `inc!>` message is used. See also `new!`, `request!`, `set!` and `put!`.

      (inc! Obj 'cnt 0)  # Incrementing a property of a non-entity object

`(index 'any 'lst) -> cnt | NIL`
  Returns the `cnt` position of `any` in `lst`, or `NIL` if it is not found. See also `offset` and `sub?`.

      : (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|flg dat . tim)`
  Returns information about a file with the name `any`: The current size `cnt` in bytes, and the modification date and time (UTC, or local time if `flg` is zero). For directories, `T` is returned instead of the size, and `NIL` for other non-regular files. The file argument itself is stored in the global variable `@@`). 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` and `time`.

      $ 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`
  Initializes a structure for stepping iteratively through a database tree. `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 . {B3}) (4 NIL . {B4}) (5 NIL . {B5}) (6 NIL . {B6}))))

`(input exe . prg) -> any`
  Establishes an input stream, by redirecting the current input channel during the execution of `prg`. The current input channel will be saved and restored appropriately. `exe` is executed (in the context of the original input channel) whenever a character is required by read calls in `prg`, and should return a single character upon each execution. See also `output`, `in` and `pipe`.

      : (input "A" (char))
      -> "A"
      : (let L (chop "(+ 2 (* 3 4))")
         (input (++ L) (read)) )
      -> (+ 2 (* 3 4))
      : (let L (chop "AQIDBAUGBw==")
         (input (++ L)
            (while (ext:Base64)
               (printsp @) ) ) )
      1 2 3 4 5 6 7 -> 7

`(insert 'cnt 'lst 'any) -> lst`
  Inserts `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 'any ['nsp]) -> sym`
  Creates or finds an internal symbol. If a symbol with the name `any` is already intern, it is returned. Otherwise, `any` is interned in the current namespaces and returned. If `nsp` is non-`NIL`, `any` is always interned in the current namespace (if `nsp` is `T`) or in the given namespace, even if it is found in other namespaces. See also `symbols`, `zap`, `import` and `extern`.

      : (intern "abc")
      -> abc
      : (intern 'car)
      -> car
      : ((intern "car") (1 2 3))
      -> 1
      : ((intern '("c" "a" "r")) (1 2 3))
      -> 1

`(ipid) -> pid | NIL`
  Returns the corresponding process ID when the current input channel is reading from a pipe, otherwise `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`
  Returns `obj` when it is an object that inherits from `cls` or `type`. See also OO Concepts, `class`, `type`, `new` and `object`.

      : (isa '+Address Obj)
      -> {A17}
      : (isa '(+Male +Person) Obj)
      -> NIL

`isa/2`
  Pilog predicate that succeeds if the second argument is of the type or class given by the first argument, according to the `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={A44} @Nm="Alexandra of Denmark"
       @Prs={A124} @Nm="Alice Maud Mary"
       @Prs={A21} @Nm="Anne"
       @Prs={A57} @Nm="Augusta Victoria".  # Stop

`(iter 'tree ['fun] ['any1] ['any2] ['flg]) -> NIL`
  Iterates through a database tree by applying `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))
      {B1}
      {B2}
      {B3}
      {B4}
      {B5}
      {B6}
      -> NIL
      : (iter (tree 'nr '+Item) '((This) (println (: nm))))
      "Main Part"
      "Spare Part"
      "Auxiliary Construction"
      "Enhancement Additive"
      "Metal Fittings"
      "Gadget Appliance"
      "Testartikel"
      -> NIL