RFC open on newLISP documentation

[Lutz]

Thanks Sam, I will continue to update the HTML and PDF manuals linked to on the newLISP home page at http://newlisp.org">http://newlisp.org and put a small revision number behind the version number.



Lutz

[Sammo]

page 107: nth-set section: the syntax definitions say "set-nth" instead of "nth-set"



page 148: unpack section: the third example (unpack "s10 f" s) doesn't eval the same on this page as it does in the 'pack' section on page 109; the example in 'pack' on page 109 is correct.



page 150: write-char section: "Writes a byte specified in int-2 to a file ..." should be "Writes the byte specified in int-byte to a file ..."



page 148: until section: "The condition in expression is evaluated." should be "The condition in exp-condition is evaluated."  Also, "Evaluation is repeated until an exp-condition results in nil or the empty list ()." should be "Evaluation is repeated until exp-condition results in a value other than nil or the empty list ()."

[Lutz]

Thanks again for your time Sam, I uploaded 'rev-2' of the HTML and PDF versions of the manual to the download directory.



Lutz

[nigelbrown]

In the assoc syntax info lookup should be a link to the lookup syntax

but currently is just plain text - see:

See also replace-assoc for making replacements in association lists and lookup for an association lookup and extraction of an element in one step.



Nigel

[nigelbrown]

In xml-parse syntax in manual 7.4.0 rev2

Parsing without any options:

(xml-parse (read-file "example.lsp"))



should have "example.xml"



Regards

Nigel

[Lutz]

thanks Nigel, I will prepare and upload a rev-3 of the manual in HTML and PDF when Christmas is over tomorrow.



Lutz

[Lutz]

revision 3 of the 7.4.0 manual is online in HTML and PDF



Lutz

[nigelbrown]

In manual replace-assoc example line:

 (replace-assoc 'b aList (q "I am the replacement"))

should be

 (replace-assoc 'b aList '(q "I am the replacement"))



Nigel

[nigelbrown]

In rev3 the fact that leading spaces are allowed in strings to convert to floats is not included - in float the example

(float "1.23")          => 1.23

(float " 1.23")         => nil

is there instead of

(float " 1.23")        => 1.23

also trim is mentioned at bottom of discussion (no longer needed).



Allowing leading spaces has been corrected in the (integer syntax.

Nigel

[Lutz]

Thanks for the doc corrections, doc revision 4 and development version 7.2.4 are online: http://newlisp.org/download/development/">http://newlisp.org/download/development/



Lutz

[Sammo]

newLISP v7.4.0 (rev-3) Manual and Reference

page 144

time-of-day

syntax: (time) should be syntax: (time-of-day)

[nigelbrown]

In syntax of +, - ...

Floating pont values which evaluate to NaN (Not a Number) are treated as 0 (zero).

could say

Floating pont values which evaluate to NaN (Not a Number), +INF, or -INF  are treated as 0 (zero).







syntax of (~

says

(format "%X" (~ 0xFFFFFFAA))    => 0x55

while

> (format "%X" (~ 0xFFFFFFAA))

"55"

>

so

(format "%X" (~ 0xFFFFFFAA))    => "55"

would be clearer, or just

 (~ 0xFFFFFFAA)    => 0x55







In (and syntax re:

Expressions are evaluated from left to right until an exp-n evaluates to nil and nil is returned. If none of the expressions evaluates to nil the result of the last expression is returned.

I'm not sure if this is a documentation thing, a feature or a bug:

> (set 'x 10)

10

> (and (< x 100) (> x 2) "passed")

"passed"

> (and (< x 100) (> x 2) '(a b c))

(a b c)

> (and (< x 100) (> x 2) '())

nil

> (setq emptylist '())

()

> emptylist

()

> (and (< x 100) (> x 2) emptylist)

nil

>

As newlisp usually treats '() and nil differently I'm not sure why

the quoted '(a b c) is returned but the quoted '() isn't or

looks like it may be evaluated?



Nigel

[Lutz]

In the manual '=>' always stands for the return value you would see in the console window, which would be:



 (~ 0xFFFFFFAA) => 85



that is why I will correct the docs to:



(format "%X" (~ 0xFFFFFFAA)) => "55"



The reason I present the example for '~' with hex AA and 55 is, that these are well known complement patterns among the 'bit fiddleing' community.



01010101 <=> 10101010



they are sometimes used to test memory or other hardware devices reversing the bits and keeping them alternating the same time.



-----



The empty list '() and nil are both treated as not true in a boolean context, this is why:



(set 'x 50)

(and (< x 100) (> x 2) '()) => nil



evaluates to nil and not the empty list () and yes, 'and' evaluates it's arguments first, but will stop evaluating and return nil, when aboolean 'false' expression is found. I use this fact often for returning from a function (see pop3.lsp) when a failing condition is found. A 'boolean' evaluation of '() with 'and' 'or' and in conditional statements (if, while etc.) will return nil.



Lutz

[nigelbrown]

Thanks for the explaination.

As that is the case, in the discussion of nil vs. () in the manual the sentence:

In newLISP nil and the empty list () are not the same as in some other LISPs. Only in conditional expressions as found in if, unless, cond, while and until they are treated as a boolean false.

could be:

In newLISP nil and the empty list () are not the same as in some other LISPs. Only in boolean and conditional expressions as found in if, unless, and, or, not, cond, while and until they are treated as a boolean false.



Nigel

PS

I see you can return '() -as expected- viz

> (and (< x 100) (> x 2) ''())

'()

>

[nigelbrown]

A suggestion regarding manual discussion of contexts. It says:

All other symbols created in MAIN with exception of built-ins and symbols like true and nil are not known in other contexts. Symbols from MAIN, if used in other contexts must be prefixed with MAIN.



perhaps the globalizing function (global should have attention drawn to it here. Viz:

All other symbols created in MAIN with exception of built-ins, symbols made global using the global function, and symbols like true and nil are not known in other contexts. Symbols from MAIN, if used in other contexts must be prefixed with MAIN.



Nigel