# F

`*Fork`
  A global variable holding a (possibly empty) `prg` body, to be executed after a call to `fork` in the child process.

      : (push '*Fork '(off *Tmp))   # Clear '*Tmp' in child process
      -> (off *Tmp)

`+Fold`
  Prefix class for maintaining `fold`ed indexes to `+String` relations. Typically used in combination with the `+Ref` or `+Idx` prefix classes. See also `+IdxFold` and Database.

      (rel nm (+Fold +Idx +String))   # Item Description
      ...
      (rel tel (+Fold +Ref +String))  # Phone number

`(fail) -> lst`
  Constructs an empty Pilog query, i.e. a query that will always fail. See also `goal`.

      (dm clr> ()                # Clear query chart in search dialogs
         (query> This (fail)) )

`fail/0`
  Pilog predicate that always fails. See also `true/0`.

      : (? (fail))
      -> NIL

`(fd) -> cnt`
  Return the current file descriptor, typically of the closest `in` or `out` channel. See also `ipid` and `opid`.

      : (in "@lib.l" (fd))
      -> 3

`(fetch 'tree 'any) -> any`
  Fetches a value for the key `any` from a database tree. See also `tree` and `store`.

      : (fetch (tree 'nr '+Item) 2)
      -> {B2}

`(fifo 'var ['any ..]) -> any`
  Implements a first-in-first-out structure using a circular list. When called with `any` arguments, they will be concatenated to end of the structure. Otherwise, the first element is removed from the structure and returned. See also `queue`, `push`, `pop`, `rot` and `circ`.

      : (fifo 'X 1)
      -> 1
      : (fifo 'X 2 3)
      -> 3
      : X
      -> (3 1 2 .)
      : (fifo 'X)
      -> 1
      : (fifo 'X)
      -> 2
      : X
      -> (3 .)

`(file) -> (sym1 sym2 . num) | NIL`
  Returns for the current input channel the path name `sym1`, the file name `sym2`, and the current line number `num`. If the current input channel is not a file, `NIL` is returned. See also `info`, `in` and `load`.

      : (load (pack (car (file)) "localFile.l"))  # Load a file in same directory

`(fill 'any ['sym|lst]) -> any`
  Non-destructively fills a pattern `any`, by substituting `sym`, or all symbols in `lst`, or - if no second argument is given - each pattern symbol in `any` (see `pat?`), with its current value. `@` itself is not considered a pattern symbol here. Unmodified subexpressions are shared. In any case, expressions following the symbol `^` should evaluate to lists which are then (destructively) spliced into the result. See also `match`.

      : (setq  @X 1234  @Y (1 2 3 4))
      -> (1 2 3 4)
      : (fill '@X)
      -> 1234
      : (fill '(a b (c @X) ((@Y . d) e)))
      -> (a b (c 1234) (((1 2 3 4) . d) e))
      : (let X 2 (fill (1 X 3) 'X))
      -> (1 2 3)

      : (fill (1 ^ (list 'a 'b 'c) 9))
      -> (1 a b c 9)

      : (match '(This is @X) '(This is a pen))
      -> T
      : (fill '(Got ^ @X))
      -> (Got a pen)

`(filter 'fun 'lst ..) -> lst`
  Applies `fun` to each element of `lst`. When additional `lst` arguments are given, their elements are also passed to `fun`. Returns a list of all elements of `lst` where `fun` returned non-`NIL`. See also `fish`, `find`, `pick` and `extract`.

      : (filter num? (1 A 2 (B) 3 CDE))
      -> (1 2 3)
      : (filter < (2 9 3 8 4 7) (5 4 3 9 9 5))
      -> (2 8 4)
      : (filter and (1 NIL 3 NIL 5) (2 3 4 5 6) (7 8 NIL 1 1))
      -> (1 5)
      : (filter and (range 1 22) '(NIL NIL T .))
      -> (3 6 9 12 15 18 21)

`(fin 'any) -> num|sym`
  Returns `any` if it is an atom, otherwise the CDR of its last cell. See also `last` and `tail`.

      : (fin 'a)
      -> a
      : (fin '(a . b))
      -> b
      : (fin '(a b . c))
      -> c
      : (fin '(a b c))
      -> NIL

`(finally exe . prg) -> any`
  `prg` is executed, then `exe` is evaluated, and the result of `prg` is returned. `exe` will also be evaluated if `prg` does not terminate normally due to a runtime error or a call to `throw`. See also `bye`, `catch`, `quit` and `Error Handling`.

      : (finally (prinl "Done!")
         (println 123)
         (quit)
         (println 456) )
      123
      Done!
      : (catch 'A
         (finally (prinl "Done!")
            (println 1)
            (throw 'A 123)
            (println 2) ) )
      1
      Done!
      -> 123

`(find 'fun 'lst ..) -> any`
  Applies `fun` to successive elements of `lst` until non-`NIL` is returned. Returns that element (and stores the non-`NIL` value in the global variable `@@`), or `NIL` if `fun` did not return non-`NIL` for any element of `lst`. When additional `lst` arguments are given, their elements are also passed to `fun`. See also `seek`, `pick`, `fully` and `filter`.

      : (find pair (1 A 2 (B) 3 CDE))
      -> (B)
      : (find '((A B) (> A B)) (1 2 3 4 5 6) (6 5 4 3 2 1))
      -> 4
      : (find > (1 2 3 4 5 6) (6 5 4 3 2 1))  # shorter
      -> 4

`(fish 'fun 'any) -> lst`
  Applies `fun` to each element - and recursively to all sublists - of `any`. Returns a list of all items where `fun` returned non-`NIL`. See also `filter`.

      : (fish atom '((a b) c (d e)))
      -> (a b c d e)
      : (fish gt0 '(a -2 (1 b (-3 c 2)) 3 d -1))
      -> (1 2 3)
      : (fish sym? '(a -2 (1 b (-3 c 2)) 3 d -1))
      -> (a b c d)

`(flg? 'any) -> flg`
  Returns `T` when the argument `any` is either `NIL` or `T`. See also `bool`. `(flg? X)` is equivalent to `(or (not X) (=T X))`.

      : (flg? (= 3 3))
      -> T
      : (flg? (= 3 4))
      -> T
      : (flg? (+ 3 4))
      -> NIL

`(flip 'lst ['cnt]) -> lst`
  Returns `lst` (destructively) reversed. Without the optional `cnt` argument, the whole list is flipped, otherwise only the first `cnt` elements. See also `reverse` and `rot`.

      : (flip (1 2 3 4))         # Flip all  four elements
      -> (4 3 2 1)
      : (flip (1 2 3 4 5 6) 3)   # Flip only the first three elements
      -> (3 2 1 4 5 6)

`(flood 'lst1 'fun 'lst2) -> lst`
  Implements a flooding algorithm, returning a list of flooded nodes of a graph. `lst1` is a list of relevant nodes, `fun` a function accepting a node and returning a list of connected nodes, and `lst2` a list of seed nodes.

      (load "@lib/simul.l")

      : (setq *Graph (1 2 3 4 5))         # For simplicity, a one-dimensional "graph"
      -> (1 2 3 4 5)

      : (simul~flood
         (maplist prog *Graph)            # List of relevant cells
         '((X)                            # Flood the three central cells (2 3 4)
            (when (member (car X) (2 3))  # 2 -> 3 and 3 -> 4
               (list (cdr X)) ) )
         (list (cddr *Graph)) )           # Seed third (middle) cell
      -> ((3 4 5) (2 3 4 5) (4 5))        # -> Cells (3 ..) (2 ..) (4 ..)

`(flush) -> flg`
  Flushes the current output stream by writing all buffered data. A call to `flush` for standard output is done automatically before a call to `key`. Returns `T` when successful. See also `rewind`.

      : (flush)
      -> T

`(fold 'any ['cnt]) -> sym`
  Folding to a canonical form: If `any` is not a symbol, it is returned as it is. Otherwise, a new transient symbol with all digits and all letters of `any`, converted to lower case, is returned. If the `cnt` argument is given and non-zero, the result is truncated to that length. See also `lowc`.

      : (fold " 1A 2-b/3")
      -> "1a2b3"
      : (fold " 1A 2-B/3" 3)
      -> "1a2"

`fold/3`
  Pilog predicate that succeeds if the first argument, after `fold`ing it to a canonical form, is a prefix of the folded string representation of the result of applying the `get` algorithm to the following arguments. Typically used as filter predicate in `select/3` database queries. See also `pre?`, `isa/2`, `same/3`, `bool/3`, `range/3`, `head/3`, `part/3` and `tolr/3`.

      : (?
         @Nr (1 . 5)
         @Nm "main"
         (select (@Item)
            ((nr +Item @Nr) (nm +Item @Nm))
            (range @Nr @Item nr)
            (fold @Nm @Item nm) ) )
       @Nr=(1 . 5) @Nm="main" @Item={B1}
      -> NIL

`(for sym 'num ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any`
`(for sym|(sym2 . sym) 'lst ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any`
`(for (sym|(sym2 . sym) 'any1 'any2 [. prg]) ['any | (NIL 'any . prg) | (T 'any . prg) ..]) -> any`
  Conditional loop with local variable(s) and multiple conditional exits:
  In the first form, the value of `sym` is saved, `sym` is bound to `1`, and the body is executed with increasing values up to (and including) `num`.
  In the second form, the value of `sym` is saved, `sym` is subsequently bound to the elements of `lst`, and the body is executed each time.
  In the third form, the value of `sym` is saved, and `sym` is bound to `any1`. If `sym2` is given, it is treated as a counter variable, first bound to 1 and then incremented for each execution of the body. While the condition `any2` evaluates to non-`NIL`, the body is repeatedly executed and, if `prg` is given, `sym` is re-bound to the result of its evaluation.
  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. If the body is never executed, `NIL` is returned.
  See also `do` and `loop`.

      # First form:
      : (for N 5 (printsp N))
      1 2 3 4 5 -> 5
      : (for N 5 (printsp N) (NIL (< N 3) (printsp 'enough)))
      1 2 3 enough -> enough
      : (for N 5 (T (> N 3) (printsp 'enough)) (printsp N))
      1 2 3 enough -> enough

      # Second form:
      : (for X (1 a 2 b) (printsp X))
      1 a 2 b -> b
      : (for (I . X) '(a b c) (println I X))
      1 a
      2 b
      3 c
      -> c

      # Third form:
      : (for (L (1 2 3 4 5) L) (printsp (pop 'L)))
      1 2 3 4 5 -> 5
      : (for (N 1 (>= 5 N) (inc N)) (printsp N))
      1 2 3 4 5 -> 5
      : (for ((I . L) '(a b c d e f) L (cddr L)) (println I L))
      1 (a b c d e f)
      2 (c d e f)
      3 (e f)
      -> (e f)

`for/2`
`for/3`
`for/4`
  Pilog predicate that generates a sequence of numbers. See also `for` and `range`.

      : (? (for @I 3))
       @I=1
       @I=2
       @I=3
      -> NIL

      : (? (for @I 3 7))
       @I=3
       @I=4
       @I=5
       @I=6
       @I=7
      -> NIL

      : (? (for @I 7 3 2))
       @I=7
       @I=5
       @I=3
      -> NIL

      : (? (for @N T))
       @N=1
       @N=2
       @N=3
       ...

`(fork) -> pid | NIL`
  Forks a child process. Returns `NIL` in the child, and the child's process ID `pid` in the parent. In the child, the `VAL` of the global variable `*Fork` (should be a `prg`) is executed. See also `exec`, `detach`, `kids`, `pipe` and `tell`.

      : (unless (fork) (do 5 (println 'OK) (wait 1000)) (bye))
      -> NIL
      OK                                              # Child's output
      : OK
      OK
      OK
      OK

`(format 'num ['cnt ['sym1 ['sym2]]]) -> sym`
`(format 'sym|lst ['cnt ['sym1 ['sym2]]]) -> num`
  Converts a number `num` to a string, or a string `sym|lst` to a number. In both cases, optionally a precision `cnt`, a decimal-separator `sym1` and a thousands-separator `sym2` can be supplied. Returns `NIL` if the conversion is unsuccessful. See also Numbers, `pad`, `hex`, `oct`, `bin` and `round`.

      : (format 123456789)                   # Integer conversion
      -> "123456789"
      : (format 123456789 2)                 # Fixed point
      -> "1234567.89"
      : (format 123456789 2 ",")             # Comma as decimal-separator
      -> "1234567,89"
      : (format 123456789 2 "," ".")         # and period as thousands-separator
      -> "1.234.567,89"

      : (format "123456789")                 # String to number
      -> 123456789
      : (format (1 "23" (4 5 6)))
      -> 123456
      : (format "1234567.89" 4)              # scaled to four digits
      -> 12345678900
      : (format "1.234.567,89")              # separators not recognized
      -> NIL
      : (format "1234567,89" 4 ",")
      -> 12345678900
      : (format "1.234.567,89" 4 ",")        # thousands-separator not recognized
      -> NIL
      : (format "1.234.567,89" 4 "," ".")
      -> 12345678900

`(free 'cnt) -> (sym . lst)`
  Returns, for the `cnt`'th database file, the next available symbol `sym` (i.e. the first symbol greater than any symbol in the database), and the list `lst` of free symbols. See also `seq`, `zap` and `dbck`.

      : (pool "x")      # A new database
      -> T
      : (new T)         # Create a new symbol
      -> {2}
      : (new T)         # Create another symbol
      -> {3}
      : (commit)        # Commit changes
      -> T
      : (zap '{2})      # Delete the first symbol
      -> {2}
      : (free 1)        # Show free list
      -> ({4})          # {3} was the last symbol allocated
      : (commit)        # Commit the deletion of {2}
      -> T
      : (free 1)        # Now {2} is in the free list
      -> ({4} {2})

`(from 'any ..) -> sym`
  Skips the current input channel until one of the strings `any` is found, and starts subsequent reading from that point. The found `any` argument (or `NIL` if none is found) is returned. See also `till` and `echo`.

      : (and (from "val='") (till "'" T))
      test val='abc'
      -> "abc"

`(full 'any) -> bool`
  Returns `NIL` if `any` is a non-empty list with at least one `NIL` element, otherwise `T`. `(full X)` is equivalent to `(not (memq NIL X))`. See also `fully`.

      : (full (1 2 3))
      -> T
      : (full (1 NIL 3))
      -> NIL
      : (full 123)
      -> T

`(fully 'fun 'lst ..) -> flg`
  Applies `fun` to successive elements of `lst`, and returns `NIL` immediately if one of the results is `NIL`. Otherwise, `T` is returned. When additional `lst` arguments are given, their elements are also passed to `fun`. `(fully foo Lst)` is equivalent to `(not (find '((X) (not (foo X))) Lst))`. See also `find` and `full`.

      : (fully gt0 (1 2 3))
      -> T
      : (fully gt0 (1 -2 3))
      -> NIL

`(fun? 'any) -> any`
  Returns `NIL` when the argument `any` is neither a number suitable for a code-pointer, nor a list suitable for a lambda expression (function). Otherwise a number is returned for a code-pointer, `T` for a function without arguments, and a single formal parameter or a list of formal parameters for a function. See also `getd`.

      : (fun? 1000000000)              # Might be a code pointer
      -> 1000000000
      : (fun? 10000000000000000000)    # Too big for a code pointer
      -> NIL
      : (fun? '((A B) (* A B)))        # Lambda expression
      -> (A B)
      : (fun? '((A B) (* A B) . C))    # Not a lambda expression
      -> NIL
      : (fun? '(1 2 3 4))              # Not a lambda expression
      -> NIL
      : (fun? '((A 2 B) (* A B)))      # Not a lambda expression
      -> NIL