# N

`+Need`
  Prefix class for mandatory `+relation`s. Note that this does not enforce any requirements by itself, it only returns an error message if the `mis>` message is explicitly called, e.g. by GUI functions. See also Database.

      (rel nr (+Need +Key +Number))  # Item number is mandatory

`+Number`
  Class for numeric relations, a subclass of `+relation`. Accepts an optional argument for the fixpoint scale (currently not used). See also Database.

      (rel pr (+Number) 2)  # Price, with two decimal places

`(n== 'any ..) -> flg`
  Returns `T` when not all `any` arguments are the same (pointer equality). `(n== 'any ..)` is equivalent to `(not (== 'any ..))`. See also `==` and Comparing.

      : (n== 'a 'a)
      -> NIL
      : (n== (1) (1))
      -> T

`(n0 'any) -> flg`
  Returns `T` when `any` is not a number with value zero. See also `=0`, `lt0`, `le0`, `ge0` and `gt0`.

      : (n0 (- 6 3 2 1))
      -> NIL
      : (n0 'a)
      -> T

`(nT 'any) -> flg`
  Returns `T` when `any` is not the symbol `T`. See also =T.

      : (nT 0)
      -> T
      : (nT "T")
      -> T
      : (nT T)
      -> NIL

`(name 'sym ['sym2]) -> sym`
  Returns, if `sym2` is not given, a new transient symbol with the name of `sym`. Otherwise `sym` must be a transient symbol, and its name is changed to that of `sym2` (note that this may give inconsistencies if the symbol is still referred to from other namespaces). See also `str`, `sym`, `symbols`, `zap` and `intern`.

      : (name 'abc)
      -> "abc"
      : (name "abc")
      -> "abc"
      : (name '{A17})
      -> "A17"
      : (name (new))
      -> NIL
      : (de foo (Lst) (car Lst))  # 'foo' calls 'car'
      -> foo
      : (intern (name (zap 'car) "xxx") T)   # Globally change the name of 'car'
      -> xxx
      : (xxx (1 2 3))
      -> 1
      : (pp 'foo)
      (de foo (Lst)
         (xxx Lst) )                         # Name changed
      -> foo
      : (foo (1 2 3))                        # 'foo' still works
      -> 1
      : (car (1 2 3))                        # Reader returns a new 'car' symbol
      !? (car (1 2 3))
      car -- Undefined
      ?

`(nand 'any ..) -> flg`
  Logical NAND. The expressions `any` are evaluated from left to right. If `NIL` is encountered, `T` is returned immediately. Else `NIL` is returned. `(nand ..)` is equivalent to `(not (and ..))`. See also `and`, `nor`, `unless`, `ifn` and `nond`.

      : (nand (lt0 7) (read))
      -> T
      : (nand (lt0 -7) (read))
      abc
      -> NIL
      : (nand (lt0 -7) (read))
      NIL
      -> T

`(native 'cnt1|sym1 'cnt2|sym2 'any 'any ..) -> any`
  (64-bit version only) Calls a native C function. The first argument should specify a shared object library, either `"@"` (the current main program), `sym1` (a library path name), or `cnt1` (a library handle obtained by a previous call). The second argument should be a symbol name `sym2`, or a function pointer `cnt2` obtained by a previous call). Practically, the first two arguments will be always passed as transient symbols, which will get the library handle and function pointer assigned as values to be cached and used in subsequent calls. The third argument `any` is a result specification, while all following arguments are the arguments to the native function. If the result specification is `T`, the actual function call is skipped, so that only the handle and pointer are assigned. The functionality is described in detail in Native C Calls.

  The result specification may either be one of the atoms

         NIL   void
         B     byte     # Byte (unsigned 8 bit)
         C     char     # Character (UTF-8, 1-3 bytes)
         I     int      # Integer (signed 32 bit)
         N     long     # Long or pointer (signed 64 bit)
         S     string   # String (UTF-8)
        -1.0   float    # Scaled fixpoint number
        +1.0   double   # Scaled fixpoint number
         T              # Don't call, just assign handle and pointer

  or nested lists of these atoms with size specifications to denote arrays and structures, e.g.

         (N . 4)        # long[4];           -> (1 2 3 4)
         (N (C . 4))    # {long; char[4];}   -> (1234 ("a" "b" "c" NIL))
         (N (B . 7))    # {long; byte[7];}   -> (1234 (1 2 3 4 5 6 7))

  Arguments can be

  - integers (up to 64-bit) or pointers, passed as numbers
  - strings, passed as symbols
  - fixpoint numbers, passed as cons pairs consisting of a the value and the scale (if the scale is positive, the number is passed as a `double`, otherwise as a `float`)
  - structures, passed as lists with
    - a variable in the CAR (to receive the returned structure data, ignored when the CAR is `NIL`)
    - a cons pair for the size and result specification in the CADR (see above), and
    - an optional sequence of initialization items in the CDDR, where each may be
      - a positive number, stored as an unsigned byte value
      - a negative number, whose absolute value is stored as an unsigned integer
      - a pair `(num . cnt)` where '`num`' is stored in a field of '`cnt`' bytes
      - a pair `(sym . cnt)` where '`sym`' is stored as a null-terminated string in a field of '`cnt`' bytes
      - a list `(1.0 num ...)` where the '`num`' elements (scaled fixpoint numbers) are stored as a sequence of double precision floating point numbers
      - a list `(-1.0 num ...)` where the '`num`' elements (scaled fixpoint numbers) are stored as a sequence of single precision floating point numbers
      If the last CDR of the initialization sequence is a number, it is used as a fill-byte value for the remaining space in the structure.

  `native` takes care of allocating memory for strings, arrays or structures, and frees that memory when done.

  The number of fixpoint arguments is limited to six. For NaN or negative infinity `NIL`, and for positive infinity `T` is returned.

  The C function may in turn call a function

         long lisp(char*, long, long, long, long, long);

  which accepts a symbol name as the first argument, and up to 5 numbers. `lisp()` calls that symbol with the five numbers, and expects a numeric return value. "Numbers" in this context are 64-bit scalars, and may not only represent integers, but also pointers or other encoded data. See also `struct`, `lisp` and `errno`.

      : (native "@" "getenv" 'S "TERM")  # Same as (sys "TERM")
      -> "xterm"

      : (native "@" "printf" 'I "abc%d%s^J" (+ 3 4) (pack "X" "Y" "Z"))
      abc7XYZ
      -> 8

      : (native "@" "printf" 'I "This is %.3f^J" (123456 . 1000))
      This is 123.456
      -> 16

      : (use Tim
         (native "@" "time" NIL '(Tim (8 B . 8)))  # time_t 8   # Get time_t structure
         (native "@" "localtime" '(I . 9) (cons NIL (8) Tim)) ) # Read local time
      -> (32 18 13 31 11 109 4 364 0)  # 13:18:32, Dec. 31st, 2009

      : (native "libcrypto.so" "SHA1" '(B . 20) "abcd" 4 0)
      -> (129 254 139 254 135 87 108 62 203 34 66 111 142 87 132 115 130 145 122 207)

`(need 'cnt ['lst ['any]]) -> lst`
`(need 'cnt ['num|sym]) -> lst`
  Produces a list of at least `cnt` elements. When called without optional arguments, a list of `cnt` `NIL`'s is returned. When `lst` is given, it is extended to the left (if `cnt` is positive) or (destructively) to the right (if `cnt` is negative) with `any` elements. In the second form, a list of `cnt` atomic values is returned. See also `range`.

      : (need 5)
      -> (NIL NIL NIL NIL NIL)  # Allocate 5 cells
      : (need 5 '(a b c))
      -> (NIL NIL a b c)
      : (need -5 '(a b c))
      -> (a b c NIL NIL)
      : (need 5 '(a b c) " ")  # String alignment
      -> (" " " " a b c)
      : (need 7 0)
      -> (0 0 0 0 0 0 0)
      : (need 5 (2 3) 1)
      -> (1 1 1 2 3)

`(new ['flg|num] ['typ ['any ..]]) -> obj`
  Creates and returns a new object. If `flg` is given and non-`NIL`, the new object will be an external symbol (created in database file 1 if `T`, or in the corresponding database file if `num` is given). `typ` (typically a list of classes) is assigned to the `VAL`, and the initial `T` message is sent with the arguments `any` to the new object. If no `T` message is defined for the classes in `typ` or their superclasses, the `any` arguments should evaluate to alternating keys and values for the initialization of the new object. See also `box`, `object`, `class`, `type`, `isa`, `send` and Database.

      : (new)
      -> $134426427
      : (new T '(+Address))
      -> {1A;3}

`(new! 'typ ['any ..]) -> obj`
  Transaction wrapper function for `new`. `(new! '(+Cls) 'key 'val ...)` is equivalent to `(dbSync) (new (db: +Cls) '(+Cls) 'key 'val ...) (commit 'upd)`. See also `request!`, `set!`, `put!` and `inc!`.

      : (new! '(+Item)  # Create a new item
         'nr 2                      # Item number
         'nm "Spare Part"           # Description
         'sup (db 'nr '+CuSu 2)     # Supplier
         'inv 100                   # Inventory
         pr 12.50 )                 # Price

`(next) -> any`
  Can only be used inside functions with a variable number of arguments (with `@`). Returns the next argument from the internal list. See also `args`, `arg`, `rest`, and `pass`.

      : (de foo @ (println (next)))          # Print next argument
      -> foo
      : (foo)
      NIL
      -> NIL
      : (foo 123)
      123
      -> 123

`(nil . prg) -> NIL`
  Executes `prg`, and returns `NIL`. See also `t`, `prog`, `prog1` and `prog2`.

      : (nil (println 'OK))
      OK
      -> NIL

`nil/1`
  Pilog predicate expects an argument variable, and succeeds if that variable is bound to `NIL`. See also `not/1`.

      : (? @X NIL (nil @X))
       @X=NIL
      -> NIL

`(noLint 'sym)`
`(noLint 'sym|(sym . cls) 'sym2)`
  (Debug mode only) Excludes the check for a function definition of `sym` (in the first form), or for variable binding and usage of `sym2` in the function definition, file contents or method body of `sym` (second form), during calls to `lint`. See also `lintAll`.

      : (de foo ()
         (bar FreeVariable) )
      -> foo
      : (lint 'foo)
      -> ((def bar) (bnd FreeVariable))
      : (noLint 'bar)
      -> bar
      : (noLint 'foo 'FreeVariable)
      -> (foo . FreeVariable)
      : (lint 'foo)
      -> NIL

`(nond ('any1 . prg1) ('any2 . prg2) ..) -> any`
  Negated ("non-cond") multi-way conditional: If any of the `anyN` conditions evaluates to `NIL`, `prgN` is executed and the result returned. Otherwise (all conditions evaluate to non-`NIL`), `NIL` is returned. See also `cond`, `ifn`, `unless`, `nor` and `nand`.

      : (nond
         ((= 3 3) (println 1))
         ((= 3 4) (println 2))
         (NIL (println 3)) )
      2
      -> 2

`(nor 'any ..) -> flg`
  Logical NOR. The expressions `any` are evaluated from left to right. If a non-`NIL` value is encountered, `NIL` is returned immediately. Else `T` is returned. `(nor ..)` is equivalent to `(not (or ..))`. See also `or`, `nand`, `unless`, `ifn` and `nond`.

      : (nor (lt0 7) (= 3 4))
      -> T

`(not 'any) -> flg`
  Logical negation. Returns `T` if `any` evaluates to `NIL`.

      : (not (== 'a 'a))
      -> NIL
      : (not (get 'a 'a))
      -> T

`not/1`
  Pilog predicate that succeeds if and only if the goal cannot be proven. See also `nil/1`, `true/0` and `fail/0`.

      : (? (equal 3 4))
      -> NIL
      : (? (not (equal 3 4)))
      -> T

`(nth 'lst 'cnt ..) -> lst`
  Returns the tail of `lst` starting from the `cnt`'th element of `lst`. Successive `cnt` arguments operate on the results in the same way. `(nth 'lst 2)` is equivalent to `(cdr 'lst)`. See also `get`.

      : (nth '(a b c d) 2)
      -> (b c d)
      : (nth '(a (b c) d) 2 2)
      -> (c)
      : (cdadr '(a (b c) d))
      -> (c)

`(num? 'any) -> num | NIL`
  Returns `any` when the argument `any` is a number, otherwise `NIL`. See also `sym?`, `atom` and `pair`.

      : (num? 123)
      -> 123
      : (num? (1 2 3))
      -> NIL