# T

`*TStp1`
`*TStp2`
  Global variables holding (possibly empty) `prg` bodies, which will be executed when a SIGTSTP signal (`*TStp1`) or a SIGCONT signal (`*TStp2`) is sent to the current process. See also `alarm`, `sigio`, `*Hup`, `*Sig[12]` and `*Winch`.

      : (de *TStp1 (msg 'SIGTSTP))
      -> *TStp1

`*Tmp`
  A global variable holding the temporary directory name created with `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/"

`+Time`
  Class for clock time values (as calculated by `time`), a subclass of `+Number`. See also Database.

      (rel tim (+Time))  # Time of the day

`T`
  A global constant, evaluating to itself. `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`
  Holds the current object during method execution (see OO Concepts), or inside the body of a `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`
  Executes `prg`, and returns `T`. See also `nil`, `prog`, `prog1` and `prog2`.

      : (t (println 'OK))
      OK
      -> T

`(tab 'lst 'any ..) -> NIL`
  Print all `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`
  Returns the last `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`
  A front-end to the `*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 the `*Run` entry. See also `tasks` and `timeout`.

      : (task -10000 5000 N 0 (tty (println (inc 'N))))  # Install task for every 10 seconds
      -> (-10000 5000 (job '((N . 0)) (tty (println (inc 'N)))))
      : 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)

`(tasks . prg)`
  Runs a `task` with variable event specification in a single `*Run` entry. The task body `prg` should return either a positive number (a file descriptor) or a negative number (a timeout value) to be used in the next iteration. The first value must be a timeout. A value of `NIL` removes the task. Uses `-2` as implicit key. See also `timeout`.

      (tasks  # Three iterations with varying timeout
         (let X (pop '(((-1000 . a) (-4000 . b) (-1000 . c))))
            (tty (println (cdr X)))
            (car X) ) )

      (tasks
         (co 'echoes  # Coroutine
            (use S
               (loop  # Loop infinitely
                  (yield -4000)  # First wait 4 seconds
                  (tty (println 'OK))
                  (yield  # Then wait for remote data
                     (setq S
                        (pipe (exec "sh" "-c" "sleep 2; echo 7")) ) )
                  (tty (println (in S (read))))
                  (close S) ) ) ) )

`(telStr 'sym) -> sym`
  Formats a telephone number according to the current `locale`. If the string head matches the local country code, it is replaced with the national trunk prefix, 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`
  Family IPC: Send an executable list `(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. When called without arguments, no message is actually sent, and the parent process may grant `sync` to the next waiting process. `tell` is also used internally by `commit` to notify about database changes. When called explicitly, the size of the message is limited to the POSIX constant PIPE_BUF. See also `kids`, `detach` and `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)`
  Executes `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`
  Builds a new transient symbol (string) from the string representation of `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)`
  Non-local jump into a previous `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

`(till 'any ['flg]) -> lst|sym`
  Reads from the current input channel till a character contained in `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`
  Formats a `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`
  Calculates the time of day, represented as the number of seconds since midnight. When called without arguments, the current local time is returned. When called with a `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 12 70)                   # Illegal time
      -> NIL

`(timeout ['num])`
  Sets or refreshes a timeout value in the `*Run` global, so that the current process executes `bye` after the given period. If called without arguments, the timeout is removed. Uses `-1` as implicit key. See also `task`.

      : (timeout 3600000)           # Timeout after one hour
      -> (-1 3600000 (bye))
      : *Run                        # Look after a few seconds
      -> ((-1 3574516 (bye)))

`(tmp ['any ..]) -> sym`
  Returns the path name to the `pack`ed `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`
  Pilog predicate that succeeds if the first argument, after `fold`ing it to a canonical form, is either a substring or a `+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={C2} @Name="Seven Oaks Ltd."

`(touch 'sym) -> sym`
  When `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`
  (Debug mode only) Inserts a `$` 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. Can only be used with EXPRs and SUBRs. Built-in functions (SUBRs) 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`
  (Debug mode only) Traces all Lisp level functions by inserting a `$` 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`
  Returns a stack backtrace for the current point of program execution. The list elements are either list expressions (denoting function or method calls), or symbols followed by their corresponding values. If `flg` is `NIL`, the symbols and their values are omitted, and only the expressions are returned. See also `bt`, `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)

`(tree 'sym 'cls ['hook]) -> tree`
  Returns a data structure specifying a database index tree. `sym` 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`
  Returns a copy of `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`
  Pilog predicate that always succeeds. See also `fail/0` and `repeat/0`.

      :  (? (true))
      -> T

`(try 'msg 'obj ['any ..]) -> any`
  Tries to send the message `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

`(tty . prg) -> any`
  Redirects the current output channel to the terminal (stderr) during the execution of `prg`. The current output channel and the state of `readline(3)` will be saved and restored appropriately. See also `out`.

      : (task -2000 0 (tty (println (inc (0)))))
      -> (-2000 0 (tty (println (inc (0)))))
      1
      2
      3
      : (* 3 4)  # Typed while numbers are printed

`(type 'any) -> lst`
  Return the type (list of classes) of the object `sym`. See also OO Concepts, `isa`, `class`, `new` and `object`.

      : (type '{1A;3})
      (+Address)
      : (type '+DnButton)
      -> (+Tiny +Rid +JS +Able +Button)