# L

`+Link`
  Class for object relations, a subclass of `+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`
  Prefix class for a list of identical relations. Objects of that class maintain a list of Lisp data of uniform type. See also Database.

      (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`
  Returns the last element of `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`
  Executes `prg` in a `pipe`'ed child process. The return value of `prg` will later be available in `var`. Note that `later` uses `pr` and `rd` to communicate the result, so `prg` should not write any data to standard output as a side effect.

      : (prog1  # Parallel background calculation of square numbers
         (mapcan '((N) (later (cons) (* N N))) (1 2 3 4))
         (wait NIL (full @)) )
      -> (1 4 9 16)

`(le0 'any) -> num | NIL`
  Returns `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`
  Returns the first leaf (i.e. the value of the smallest key) in a database tree. See also `tree`, `minKey`, `maxKey` and `step`.

      : (leaf (tree 'nr '+Item))
      -> {B1}
      : (db 'nr '+Item (minKey (tree 'nr '+Item)))
      -> {B1}

`(length 'any) -> cnt | T`
  Returns the "length" of `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

`(less 'any ['cnt]) -> any`
  Returns a reduced form of `any`, where for each list and its sublists only the first `cnt` elements (default 4), possibly followed by `..`, are retained.

      : (less '(a b c d e f))
      -> (a b c d ..)
      : (less '((a b c) ((d e f g h i) (j k l m n))))
      -> ((a b c) ((d e f ..) (j k ..)))
      : (less '((a b c) ((d e f g h i) (j k l m n))) 2)
      -> ((a b ..) ((d ..) ..))

`(let sym 'any . prg) -> any`
`(let (sym|lst 'any ..) . prg) -> any`
  Defines local variables. The value of the symbol `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. The `lst` arguments in the second form may consist only of symbols and sublists, and match the `any` argument (destructuring bind). `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. In destructuring patterns, `NIL` denotes a "don't care" position. 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 (A 1  (B . C) (2 3)  D 4)
         (list A B C D) )
      -> (1 2 (3) 4)

      : (let (((A . B) (C) . D) '((1 2 3) (4 5 6) 7 8 9))
         (list A B C D) )
      -> (1 (2 3) 4 (7 8 9))

      : (let (((A . NIL) NIL NIL D) '((1 2 3) (4 5 6) 7 8 9))
         (trail T) )
      -> (A 1 D 8)

`(let? sym 'any . prg) -> any`
  Conditional local variable binding and execution: If `any` evaluates 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`
  Returns the argument `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`
  Reads a line of characters from the current input channel. End of line is recognized as linefeed (hex "0A"), carriage return (hex "0D"), or the combination of both. (Note that a single carriage return may not work on network connections, because the character look-ahead to distinguish from return+linefeed can block the connection.) If `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")

`(link 'any ..) -> any`
  Links one or several new elements `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`
  (Debug mode only) Checks the function definition or file contents (in the first form), or the method body of sym (second and third form), for possible pitfalls. Returns an association list of diagnoses, where `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 an 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`
  (Debug mode only) Applies `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`
  Installs under the tag `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/clang.l")

      (clang "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`
  Returns a list of all `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`
  Pilog predicate that returns subsequent list elements, after applying the `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={B7} @Pos={A1}
       @Ord={B7} @Pos={A2}
       @Ord={B7} @Pos={A3}
      -> NIL

`(lst? 'any) -> flg`
  Returns `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`
  Listens at a socket descriptor `cnt1` (as received by `port`) for an incoming connection, and returns the new socket descriptor `cnt`. While waiting for a connection, a `poll(2)` 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`
  Returns the literal (i.e. quoted) value of `any`, by `cons`ing it with the `quote` function if necessary. See also `strip`.

      : (lit T)
      -> T
      : (lit 1)
      -> 1
      : (lit '(1))
      -> (1)
      : (lit '(a))
      -> '(a)

`(load 'any ..) -> any`
  Loads all `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 `load`ed 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`
  Locates in `lst` a `transient` symbol with the same name as `sym`. Allows to get hold of otherwise inaccessible symbols.

      : (loc "X" curry)
      -> "X"
      : (== @ "X")
      -> NIL

`(local) sym|lst`
  Intern symbols locally in the current namespace. `(local)` expects a single symbol or a list of symbols immediately following in the current input stream. See also `pico`, `symbols`, `private`, `export`, `import` and `intern`.

      : (symbols 'myLib 'pico)
      -> (pico)
      myLib: (local) (foo bar)

      myLib: (de foo (A)  # 'foo' is local to 'myLib'
         ...
      myLib: (de bar (B)  # 'bar' is local to 'myLib'
         ...

`(locale 'sym1 'sym2 ['sym ..])`
  Sets the current locale to that given by the country file `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/")
      -> NIL
      : ,"Yes"
      -> "Ja"

`(lock ['sym]) -> cnt | NIL`
  Write-locks an external symbol `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 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`
  Endless loop with multiple conditional exits: The body is executed an unlimited number of times. 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. See also `do` and `for`.

      : (let N 3
         (loop
            (prinl N)
            (T (=0 (dec 'N)) 'done) ) )
      3
      2
      1
      -> done

`(low? 'any) -> sym | NIL`
  Returns `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`
  Lower case conversion: If `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`
  Returns `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`
  Looks up `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`. If the tree is empty, `NIL` is returned immediately. See also `enum?` and `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))