File: refN.html

package info (click to toggle)
picolisp 3.1.0.7-1
links: PTS, VCS
area: main
in suites: wheezy
size: 4,100 kB
sloc: ansic: 14,205; lisp: 795; makefile: 290; sh: 13
file content (455 lines) | stat: -rw-r--r-- 15,735 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/1998/REC-html40-19980424/loose.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>N</title>
<link rel="stylesheet" href="doc.css" type="text/css">
</head>
<body>

<h1>N</h1>

<dl>

<dt><a name="+Need"><code>+Need</code></a>
<dd>Prefix class for mandatory <code><a
href="refR.html#+relation">+relation</a></code>s. Note that this does not
enforce any requirements by itself, it only returns an error message if the
<code>mis&gt;</code> message is explicitly called, e.g. by GUI functions. See
also <code><a href="ref.html#dbase">Database</a></code>.

<pre><code>
(rel nr (+Need +Key +Number))  # Item number is mandatory
</code></pre>

<dt><a name="+Number"><code>+Number</code></a>
<dd>Class for numeric relations, a subclass of <code><a
href="refR.html#+relation">+relation</a></code>. Accepts an optional argument
for the fixpoint scale (currently not used). See also <code><a
href="ref.html#dbase">Database</a></code>.

<pre><code>
(rel pr (+Number) 2)  # Price, with two decimal places
</code></pre>

<dt><a name="n=="><code>(n== 'any ..) -> flg</code></a>
<dd>Returns <code>T</code> when not all <code>any</code> arguments are the same
(pointer equality). <code>(n== 'any ..)</code> is equivalent to <code>(not (==
'any ..))</code>. See also <code><a href="ref_.html#==">==</a></code> and <a
href="ref.html#cmp">Comparing</a>.

<pre><code>
: (n== 'a 'a)
-> NIL
: (n== (1) (1))
-> T
</code></pre>

<dt><a name="n0"><code>(n0 'any) -> flg</code></a>
<dd>Returns <code>T</code> when <code>any</code> is not a number with value
zero. See also <code><a href="ref_.html#=0">=0</a></code>, <code><a
href="refL.html#lt0">lt0</a></code>, <code><a
href="refL.html#le0">le0</a></code>, <code><a
href="refG.html#ge0">ge0</a></code> and <code><a
href="refG.html#gt0">gt0</a></code>.

<pre><code>
: (n0 (- 6 3 2 1))
-> NIL
: (n0 'a)
-> T
</code></pre>

<dt><a name="nT"><code>(nT 'any) -> flg</code></a>
<dd>Returns <code>T</code> when <code>any</code> is not the symbol
<code>T</code>. See also <a href="ref_.html#=T">=T</a>.

<pre><code>
: (nT 0)
-> T
: (nT "T")
-> T
: (nT T)
-> NIL
</code></pre>

<dt><a name="name"><code>(name 'sym ['sym2]) -> sym</code></a>
<dd>Returns, if <code>sym2</code> is not given, a new transient symbol with the
name of <code>sym</code>. Otherwise <code>sym</code> must be a transient symbol,
and its name is changed to that of <code>sym2</code> (note that this may give
inconsistencies if the symbol is still referred to from other namespaces). See
also <code><a href="refS.html#str">str</a></code>, <code><a
href="refS.html#sym">sym</a></code>, <code><a
href="refS.html#symbols">symbols</a></code>, <code><a
href="refZ.html#zap">zap</a></code> and <code><a
href="refI.html#intern">intern</a></code>.

<pre><code>
: (name 'abc)
-> "abc"
: (name "abc")
-> "abc"
: (name '{abc})
-> "abc"
: (name (new))
-> NIL
: (de foo (Lst) (car Lst))  # 'foo' calls 'car'
-> foo
: (intern (name (zap 'car) "xxx"))  # 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
?
</code></pre>

<dt><a name="nand"><code>(nand 'any ..) -> flg</code></a>
<dd>Logical NAND. The expressions <code>any</code> are evaluated from left to
right. If <code>NIL</code> is encountered, <code>T</code> is returned
immediately. Else <code>NIL</code> is returned. <code>(nand ..)</code> is
equivalent to <code>(not (and ..))</code>.

<pre><code>
: (nand (lt0 7) (read))
-> T
: (nand (lt0 -7) (read))
abc
-> NIL
: (nand (lt0 -7) (read))
NIL
-> T
</code></pre>

<dt><a name="native"><code>(native 'cnt1|sym1 'cnt2|sym2 'any 'any ..) -> any</code></a>
<dd>(64-bit version only) Calls a native C function. The first argument should
specify a shared object library, either <code>"@"</code> (the current main
program), <code>sym1</code> (a library path name), or <code>cnt1</code> (a
library handle obtained by a previous call). The second argument should be a
symbol name <code>sym2</code>, or a function pointer <code>cnt2</code> 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
<code>any</code> is a result specification, while all following arguments are
the arguments to the native function. The functionality is described in detail
in <a href="native.html">Native C Calls</a>.

<p><a name="natResult">The result specification</a> may either be one of the
atoms

<pre><code>
   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
</code></pre>

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

<pre><code>
   (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))
</code></pre>

<p>Arguments can be
<ul>
<li>integers (up to 64-bit) or pointers, passed as numbers
<li>strings, passed as symbols
<li>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
   <code>double</code>, otherwise as a <code>float</code>)
<li>structures, passed as lists with
   <ul>
   <li>a variable in the CAR (to recieve the returned structure data, ignored
      when the CAR is <code>NIL</code>)
   <li>a cons pair for the size and result specification in the CADR (see
      above), and
   <li>an optional sequence of <a name="natItem">initialization items</a> in the
      CDDR, where each may be
      <ul>
      <li>a positive number, stored as an unsigned byte value
      <li>a negative number, whose absolute value is stored as an unsigned
         integer
      <li>a pair <code>(num . cnt)</code> where '<code>num</code>' is stored in
         a field of '<code>cnt</code>' bytes
      <li>a pair <code>(sym . cnt)</code> where '<code>sym</code>' is stored as
         a null-terminated string in a field of '<code>cnt</code>' bytes
      <li>a list <code>(1.0 num ...)</code> where the '<code>num</code>'
         elements (scaled fixpoint numbers) are stored as a sequence of double
         precision floating point numbers
      <li>a list <code>(-1.0 num ...)</code> where the '<code>num</code>'
         elements (scaled fixpoint numbers) are stored as a sequence of single
         precision floating point numbers
      </ul>
      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.
   </ul>
</ul>

<p><code>native</code> takes care of allocating memory for strings, arrays or
structures, and frees that memory when done.

<p>The number of fixpoint arguments is limited to six. For NaN or negative
infinity <code>NIL</code>, and for positive infinity <code>T</code> is returned.

<p>The C function may in turn call a function

<pre><code>
   long lisp(char*, long, long, long, long, long);
</code></pre>

<p>which accepts a symbol name as the first argument, and up to 5 numbers.
<code>lisp()</code> 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
<code><a href="refS.html#struct">struct</a></code>, <code><a
href="refL.html#lisp">lisp</a></code> and <code><a
href="refE.html#errno">errno</a></code>.

<pre><code>
: (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)
</code></pre>

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

<pre><code>
: (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)
</code></pre>

<dt><a name="new"><code>(new ['flg|num] ['typ ['any ..]]) -> obj</code></a>
<dd>Creates and returns a new object. If <code>flg</code> is given and
non-<code>NIL</code>, the new object will be an external symbol (created in
database file 1 if <code>T</code>, or in the corresponding database file if
<code>num</code> is given). <code>typ</code> (typically a list of classes) is
assigned to the <code>VAL</code>, and the initial <code>T</code> message is sent
with the arguments <code>any</code> to the new object. If no <code>T</code>
message is defined for the classes in <code>typ</code> or their superclasses,
the <code>any</code> arguments should evaluate to alternating keys and values
for the initialization of the new object. See also <code><a
href="refB.html#box">box</a></code>, <code><a
href="refO.html#object">object</a></code>, <code><a
href="refC.html#class">class</a></code>, <code><a
href="refT.html#type">type</a></code>, <code><a
href="refI.html#isa">isa</a></code>, <code><a
href="refS.html#send">send</a></code> and <code><a
href="ref.html#dbase">Database</a></code>.

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

<dt><a name="new!"><code>(new! 'typ ['any ..]) -> obj</code></a>
<dd><a href="ref.html#trans">Transaction</a> wrapper function for <code><a
href="refN.html#new">new</a></code>. <code>(new! '(+Cls) 'key 'val ...)</code>
is equivalent to <code>(dbSync) (new (db: +Cls) '(+Cls) 'key 'val ...) (commit
'upd)</code>. See also <code><a href="refS.html#set!">set!</a></code>, <code><a
href="refP.html#put!">put!</a></code> and <code><a
href="refI.html#inc!">inc!</a></code>.

<pre><code>
: (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
</code></pre>

<dt><a name="next"><code>(next) -> any</code></a>
<dd>Can only be used inside functions with a variable number of arguments (with
<code>@</code>). Returns the next argument from the internal list. See also
<code><a href="refA.html#args">args</a></code>, <code><a
href="refA.html#arg">arg</a></code>, <code><a
href="refR.html#rest">rest</a></code>, and <code><a
href="refP.html#pass">pass</a></code>.

<pre><code>
: (de foo @ (println (next)))          # Print next argument
-> foo
: (foo)
NIL
-> NIL
: (foo 123)
123
-> 123
</code></pre>

<dt><a name="nil"><code>(nil . prg) -> NIL</code></a>
<dd>Executes <code>prg</code>, and returns <code>NIL</code>. See also <code><a
href="refT.html#t">t</a></code>, <code><a href="refP.html#prog">prog</a></code>,
<code><a href="refP.html#prog1">prog1</a></code> and <code><a
href="refP.html#prog2">prog2</a></code>.

<pre><code>
: (nil (println 'OK))
OK
-> NIL
</code></pre>

<dt><a name="nil/1"><code>nil/1</code></a>
<dd><a href="ref.html#pilog">Pilog</a> predicate expects an argument variable,
and succeeds if that variable is bound to <code>NIL</code>. See also <code><a
href="refN.html#not/1">not/1</a></code>.

<pre><code>
: (? @X NIL (nil @X))
 @X=NIL
-> NIL
</code></pre>

<dt><a name="noLint"><code>(noLint 'sym)</code></a>
<dt><code>(noLint 'sym|(sym . cls) 'sym2)</code>
<dd>Excludes the check for a function definition of <code>sym</code> (in the
first form), or for variable binding and usage of <code>sym2</code> in the
function definition, file contents or method body of <code>sym</code> (second
form), during calls to <code><a href="refL.html#lint">lint</a></code>. See also
<code><a href="refL.html#lintAll">lintAll</a></code>.

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

<dt><a name="nond"><code>(nond ('any1 . prg1) ('any2 . prg2) ..) -> any</code></a>
<dd>Negated ("non-cond") multi-way conditional: If any of the <code>anyN</code>
conditions evaluates to <code>NIL</code>, <code>prgN</code> is executed and the
result returned. Otherwise (all conditions evaluate to non-<code>NIL</code>),
<code>NIL</code> is returned. See also <code><a
href="refC.html#cond">cond</a></code>, <code><a
href="refI.html#ifn">ifn</a></code> and <code><a
href="refU.html#unless">unless</a></code>.

<pre><code>
: (nond
   ((= 3 3) (println 1))
   ((= 3 4) (println 2))
   (NIL (println 3)) )
2
-> 2
</code></pre>

<dt><a name="nor"><code>(nor 'any ..) -> flg</code></a>
<dd>Logical NOR. The expressions <code>any</code> are evaluated from left to
right. If a non-<code>NIL</code> value is encountered, <code>NIL</code> is
returned immediately. Else <code>T</code> is returned. <code>(nor ..)</code> is
equivalent to <code>(not (or ..))</code>.

<pre><code>
: (nor (lt0 7) (= 3 4))
-> T
</code></pre>

<dt><a name="not"><code>(not 'any) -> flg</code></a>
<dd>Logical negation. Returns <code>T</code> if <code>any</code> evaluates to
<code>NIL</code>.

<pre><code>
: (not (== 'a 'a))
-> NIL
: (not (get 'a 'a))
-> T
</code></pre>

<dt><a name="not/1"><code>not/1</code></a>
<dd><a href="ref.html#pilog">Pilog</a> predicate that succeeds if and only if
the goal cannot be proven. See also <code><a
href="refN.html#nil/1">nil/1</a></code>, <code><a
href="refT.html#true/0">true/0</a></code> and <code><a
href="refF.html#fail/0">fail/0</a></code>.

<pre><code>
: (? (equal 3 4))
-> NIL
: (? (not (equal 3 4)))
-> T
</code></pre>

<dt><a name="nth"><code>(nth 'lst 'cnt ..) -> lst</code></a>
<dd>Returns the tail of <code>lst</code> starting from the <code>cnt</code>'th
element of <code>lst</code>. Successive <code>cnt</code> arguments operate on
the results in the same way. <code>(nth 'lst 2)</code> is equivalent to
<code>(cdr 'lst)</code>. See also <code><a href="refG.html#get">get</a></code>.

<pre><code>
: (nth '(a b c d) 2)
-> (b c d)
: (nth '(a (b c) d) 2 2)
-> (c)
: (cdadr '(a (b c) d))
-> (c)
</code></pre>

<dt><a name="num?"><code>(num? 'any) -> num | NIL</code></a>
<dd>Returns <code>any</code> when the argument <code>any</code> is a number,
otherwise <code>NIL</code>.

<pre><code>
: (num? 123)
-> 123
: (num? (1 2 3))
-> NIL
</code></pre>

</dl>

</body>
</html>