RFC open on newLISP documentation

[Lutz]

Before I had capitalization in all the headings, but then decided, that it looked to heavy, I still do it on the main section titles and perhaps will go one more level deeper.



To Ryon's comment: I didn't mean to be picky on how anybody here on the forum writes the word 'newLISP', but in the manual and website I try to be consistent about it.



Other news: I did some benchmarks of newLISP comparing it to Perl, Python and Guile (a GNU Scheme). The results are positively surprising and I am preparing a webpage for it the coming weekend.



The next development version (7.5.2) which is a precursor to 8.0 later this year also includes arrays! as a new datatype in newLISP. They are also already included in the benchmark, have increased the executable size by less than 2k and are well integrated into the language in general.



Lutz

[Sammo]

Hi Lutz,



re: 7.5.2 -- thanks for the arrays!  Very nice.



There may be a couple of typos in the 'array' function.



1) The first line of code following "To convert a list back to an array ..." should be (I think) "(set 'aList '((1 2) (3 4))) => ((1 2) (3 4))".



2) Should the line beginning "Lists are modified using the usual ..." read "Arrays are modified using the usual ..."?



3) Following the line beginning "The function array? can be ..."



a) "(array? (list myarray) => nil" should be "(array? (array-list myarray)) => nil"



b) "(array 3 4 (sequence 1 4)))" should be "(set 'myarray (array 3 4 (sequence 1 4)))"



c) "(list myarray) => ((1 2 3 4)(5 6 7 8) (9 10 11 12))" should be "(array-list myarray) ..."



The corresponding examples under 'array-list' and 'array?' are correct.

[Lutz]

thankyou Sam, reading this section again and putting in your corrections this (chilly, even here in Florida) Sunday morning, I realized that the whole piece was a mess. This happens when you write/change several times the documentation before you start coding. I also rearranged some paragraphs and took some double stuff out. "rev-1" is in the development directory:



http://newlisp.org/download/development/newlisp_manual.html">http://newlisp.org/download/development ... anual.html">http://newlisp.org/download/development/newlisp_manual.html



Lutz

[nigelbrown]

In manual (7.5.8) info on symbol? should first example be

(set 'x 'y)  => y

to fit the text that follows it:





syntax: (symbol? exp)

Expression exp is evaluated and returns true only if the value is a non-primitive symbol and otherwise returns nil. Note that symbol? only evaluates to true on symbols which are not built-in primitives.



example:

(set 'x 'var)  => var



(symbol? x)    => true



(symbol? (first '(var x y z))) => true





The first statement sets the contents of x to the symbol y. The second statement than checks the contents of x. The last example checks the first element of a list.

[nigelbrown]

The manual has some examples that fail because of the default protection of built-in functions viz:

Built in functions evaluate to themselves:



add                     => add <B845770D>

(eval (eval add))       => add <B845770D>

(set '+ add)            => add <B845770D>



last line fails:

> (set '+ add)



symbol is protected in function set : +



>

The correct version is in the manual down further:

constant has to be used to rename symbols of built-in primitives instead of set, because all built-in function symbols are protected by default against accidental overwriting.



(constant '+ add)



Also incorrect:

example:

;; use underscores on symbols

(define-macro (setq _x _y) (set _x (eval _y)))

(setq x 123)            =>      123



viz:

> (define-macro (setq _x _y) (set _x (eval _y)))



symbol is protected in function define-macro : (setq _x _y)



>

[nigelbrown]

continued



for the define-macro I guess the way is:



> (define-macro (mysetq _x _y) (set _x (eval _y)))

(lambda-macro (_x _y) (set _x (eval _y)))

> (constant 'setq mysetq)

(lambda-macro (_x _y) (set _x (eval _y)))

>

[Lutz]

Thanks for the corrections Nigel. Also, the statement that 'symbol?' would not evaluate to 'true' on symbols of primitives is of course nonsense:



(symbol? 'print) => true ; of course



Lutz

[Lutz]

I added 'constant' protection checking to all functions which change the contents of a symbol (called destructive functions).



So now using these functions on symbols protected with 'constant'  will cause an error message as described in the manual previously. Look for it in 7.5.9 due in a few days.



Lutz

[nigelbrown]

will it protect against maybe? less direct changes viz:



> (constant 'a '(a B c))

(a B c)

> (replace 'B (eval (quote a)) 'Z)

(a Z c)

> (setq x 'a)

a

> (replace 'Z (eval x) 'w)

(a w c)

> a

(a w c)

>  



I guess it would but just checking

[Lutz]

It is Ok, 'eval' is the only function returning symbol contents without copying it for usage in macros, but this case handled.



Lutz

[nigelbrown]

The syntax entry for (float in manual still says

 str must start with space(s), a number digit or the + or - sign.

when starting with decimal point is now valid viz

> (float ".5")

0.5

[nigelbrown]

Also -.5 is a valid C float viz

#include <stdio.h>

int main () {

   double f;

        f = -.5;

        printf("%gn",f);

}

compiles with gcc

but



> (float ".5")

0.5

> (float "-.5")

nil

> (float "-0.5")

-0.5

>

[Lutz]

this will be changed, there is also a new chapter in the docs about syntax of variable names and numbers



Lutz

[Lutz]

I had to roll back one of the changes in 7.5.9 and posted a 7.5.10 this morning: http://newlisp.org/download/development/">http://newlisp.org/download/development/



Lutz

[Lutz]

Still fixing constant protection and iteration, protection inside 'dotimes and 'for also rolled back in 7.5.11:



http://newlisp.org/download/development/">http://newlisp.org/download/development/



Lutz