# 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) -> sym`
  Returns a new transient symbol with the name of `sym`. See also `str`, `sym`, `symbols`, `zap` and `intern`.

      : (name 'abc)
      -> "abc"
      : (name "abc")
      -> "abc"
      : (name '{A17})
      -> "A17"
      : (name (new))
      -> NIL

`(namespaces ['flg]) -> lst`
  (Debug mode only) Returns a list of all namespaces nested in the current search order. When `flg` is non-`NIL`, their nested tree is printed as a side effect. See also `symbols` and `shadows`.

      $ pil +
      : (namespaces)
      -> (pico vip llvm priv)
      : (namespaces T)
         pico
            vip
            llvm
            priv
      -> (pico vip llvm priv)

      $ pty  # After starting "steps", "browser" and "chess" in PilBox
      chess: (namespaces T)
         chess
         simul
         android
            steps
            browser
         pico
            svg
            vip
            gis
            llvm
            priv
      -> (chess simul android steps browser pico svg vip gis llvm priv)

`(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`
  Calls a native 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 handle `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 handle 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. 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-4 bytes)
         W     short    # Word (signed 16 bit)
         I     int      # Integer (signed 32 bit)
         N     long     # Number (signed 64 bit)
         P     void*    # Pointer (unsigned 64 bit)
         S     string   # String (UTF-8)
        -1.0   float    # Scaled fixpoint number
        +1.0   double   # Scaled fixpoint number
         T              # Direct Lisp value

  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
  - Lisp expressions, passed as cons pairs with `T` in the CAR
  - 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.

  For NaN or negative infinity fixpoint values `NIL`, and for positive infinity `T` is returned.

  See also `%@`, `struct`, `adr`, `lisp` and `errno`.

      : (native "@" "unlink" 'I "file")  # Same as (%@ "unlink" 'I "file")
      -> 0
      : (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|sym] ['typ ['any ..]]) -> obj`
  Creates and returns a new object. If the first (optional) argument is `T` or a number, 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). If it is a symbol, it is used directly. `typ` (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))
      -> {A3}

`(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

`(nsp 'sym) -> sym`
  Returns the (first) namespace where `sym` is found in, according to the current `symbols` search order. See also `pico`.

      (load "@lib/gis.l")

      : (symbols '(gis pico))
      -> (pico)
      gis: (nsp 'gis)
      -> pico
      gis: (nsp 'Zoom)
      -> gis
      gis: (nsp 'osmStat)
      -> gis

`(nth 'lst 'cnt ..) -> lst`
  Returns the tail of `lst` starting from the `cnt`'th element of `lst`. Successive `cnt` arguments operate on the CARs of 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