RFC open on newLISP documentation

[nigelbrown]

In discussion of contexts or of (delete syntax perhaps some of Lutz's examples from this topic could be included:

http://www.alh.net/newlisp/phpbb/viewtopic.php?t=152">http://www.alh.net/newlisp/phpbb/viewtopic.php?t=152

Nigel

[nigelbrown]

re various examples:

1) it says

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

but

> (set '+ add)



symbol is protected in function set : +



>

see for this non-working example:

Built in functions evaluate to themselves:



add                     => add <B845770D>

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

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

+                       => add <B845770D>

and:

(set 'subtract -)      

(set '+ add)

subtract will behave like -. + is redefined to use the mixed type floating point mode of add.

2)

But unlike other LISPs the inside of the lambda list is still accessible in double (as shown previously):



(set 'double (lambda (x) (+ x x))



should be:

(set 'double (lambda (x) (+ x x)))

better still - for consistency have:

(set 'double (lambda (x) (+ x x)))  =>  (lambda (x) (+ x x))

also

(set-nth 1 double '(mul 2 x))  =>  (+ x x) ; the old contents

is incorrect as

> (set 'double (lambda (x) (+ x x)))

(lambda (x) (+ x x))

> (last double)

(+ x x)

> (set-nth 1 double '(mul 2 x))

(lambda (x) (mul 2 x))

>



3)

(set 'lst '(nil nil nil))    =>    (nil nil nil))

should be

(set 'lst '(nil nil nil))    =>    (nil nil nil)



Nigel

[nigelbrown]

re more examples

1)

(= (name 'CTAX:val) (name 'CTXB:val))  => true

should be

(= (name 'CTXA:val) (name 'CTXB:val))  => true



and for consistency

(set 'CTXA:val 123)

(set 'CTXB:val 456)

may better be

(set 'CTXA:val 123)    =>  123

(set 'CTXB:val 456)    =>  456



2)similarly for consistency and a correction

in  Changing scoping and symbol protection

(set 'aVar 123)

(global aVar)



(context 'FOO)

could be made (note correction of quoting aVar in global)

(set 'aVar 123)  => 123

(global 'aVar)    => aVar



(context 'FOO)  => FOO>       ; prompt shows context



and below that

(constant 'aVar 123)

could be

(constant 'aVar 123)  =>  123



3)in section Variables holding contexts

(set 'ctx FOO)



ctx:x => 123



(set 'ctx:x 999)

FOO:x => 999

 could be

(set 'FOO:x 123)  => 123

(set 'ctx FOO)      => FOO



ctx:x => 123



(set 'ctx:x 999)    => 999

FOO:x => 999



4) in <<,>> it says

( >> 0x80000000 1) => 0xC0000000   ; not 0x04000000 !

now

> ( >> 0x80000000 1)

-1073741824

>

the example could be (similar to other hex example)

(format "%x" ( >> 0x80000000 1)) => "c0000000"  ; not "4000000"





Nigel

[nigelbrown]

re various examples

1) in apply syntax

(set 'list '(3 4 5))                    => (3 4 5)

(apply * list)                          => 60



but

> (set 'list '(3 4 5))



symbol is protected in function set : list



>

could use

(set 'aList '(3 4 5))                    => (3 4 5)

(apply * aList)                          => 60  



2) in atan2 syntax:

(div (acos 0) (atan2 1 1)         => 2

should be

(div (acos 0) (atan2 1 1))        => 2



3) in catch syntax examples because in the apply example we did

(set 'func sqrt)                        => sqrt

 if you just work through entering the examples you can get

(set 'func sqrt)   =>  sqrt <406C2E>

...

(catch (func 3 4) 'result)   => true



I guess the answer to 'Who would do that!?' is 'Me'

Note also that (set 'func sqrt)   =>  sqrt <406C2E>



4)in (ceil syntax

(ceil -1.5)  => 1

should be

(ceil -1.5)  => -1



5) in chop syntax for consistency

(set 'str "newLISP")

could be

(set 'str "newLISP")   =>  "newLISP"



below that is an error:

(set 'lst '(a b (c d) e)

is missing a ), should be

(set 'lst '(a b (c d) e))  =>  (a b (c d) e)



6) in char syntax perhaps

(map char (sequence 1 255)) ; will print current character set

could say

(map char (sequence 1 255)) ; will print current character set in a list



Nigel

[nigelbrown]

re various examples

1) cons syntax

(cons a '(b c))         => (a b c)

should be

(cons 'a '(b c))         => (a b c)

and

(cons (+ 3 4) (* 5 5))  => (12 25)

should be

(cons (+ 3 4) (* 5 5))  => (7 25)

or

(cons (* 3 4) (* 5 5))  => (12 25)



2) in context? syntax the examples

(set 'foo:q "hola")

(set 'ctx foo)

(context? ctx)       => true  ; ctx contains context foo

should use FOO to follow on from previous examples or

should create a lowercase foo context to use.



3) in cos syntax rather than

pi         => 3.141592654

using

(set 'pi 3.141592654) => 3.141592654

makes example self sufficient



4) in crit-chi2 syntax it says

(crit-chi2 0.01 4) => 13.277

but

> (crit-chi2 0.01 4)

0.2971091866

>

below that says

(crit-z 0.999) => 3.090232

> (crit-z 0.999)

3.090232372

>



5) in date-value for

(date-value 2002 2 28)          =>  1080777600

I get 1014854400 on WinXP Pro - probably a windows thing?



Nigel

[nigelbrown]

A comment on above checking of manual examples -

I've tried to add some  simple automation to the process of checking manual examples - my steps were

1) from Internet Explorer save the manual as a text file (save as) called newlispman.txt.

2) define some lisp functions to step through file lines and if one contains a => then display line and ask if eval-string should be applied to it - if y then do eval-string on it and print result - I visually compare result with expected output as displayed

the functions in tryexamples.lsp are:



 (define (tryexamples fileh )(while (read-line fileh)(if (find "=>" (current-line))(doify (current-line)))))



 (define (doify str) (begin (print "n" (current-line) "nDo it?") (if (= (read-line) "y") (print "n=>" (eval-string (first (parse str "=>")) "syntax error")))))



then in newlisp-tk I do

(load "tryexamples.lsp")

(tryexamples (open "newlispman.txt" "read"))



then I step through the examples - some lines are not examples or incomplete parts of multiline examples or not suitable for execution then I say n.

This is why I suggest consistent use of => in example lines where possible.



So far I'm up to the (device syntax entry.



Nigel

[Lutz]

Thanks again for all your time in checking the manual and suggesting improvements.



regarding (set '+ add):

since 7.3.0 (constant '+ add) has to be used to redefine primitives, as built-in fucntions are protected symbols since version 7.3.0 . These examples will be taken out and put into 'constant' instead.



regarding (set 'function sqrt) => sqrt <406C2E>

the display of <406C2E> is just a visual thing to show that a bulit-in function is displayed. (fuction 10) => 3.16227766 will work Ok. This will be shown more consistently in the manual. The hexadecimal code displayed will be different on different platforms and states of the OS.



regarding (crit-chi2  0.01 4):

this should be:



(crit-chi2  0.99 4)   ;; not 0.01 but 1-0.01



regarding (date-value 2002 2 28):

1014854400 is the correct result and the same on all OSs and timezones, the returned value is always Universal Time.



Lutz

[Lutz]

All of Nigel's last corrections are online in revision 5 of the documentation:



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



http://newlisp.org/download/newlisp_manual.pdf">http://newlisp.org/download/newlisp_manual.pdf



Happy new Year Nigel!  (the first one on this board to cross the date-line)



Hans-Peter, you are next?



Lutz

[HPW]

>Hans-Peter, you are next?



Don't sure where all other member are located.

For me are 5.5 hours remaining.



Happy new Year to all newlispers!

[nigelbrown]

Happy New Year!

My earlier posts on this thread were actually 5pmish 31Dec local time which is GMT minus 10h - the board time adjustments must have made them look this year.



A correction for the http://www.newlisp">www.newlisp page:

XML functios and SXML support

needs functions.



Re manual - Lutz you mentioned setting memory limits but I can't see that in the command line switch topic of rev5.



Nigel

[nigelbrown]

re various examples

1) dolist

(dolist (x '(a b c d e f g)) (print x))   => abcdefg

could say

(dolist (x '(a b c d e f g)) (print x))   =>prints  abcdefg returns g



2)

(dotimes (x 10) (print x))   => 9

could say

(dotimes (x 10) (print x))   => prints 0123456789 returns 9



Nigel

[nigelbrown]

re various examples

1) floor syntax

(floor -1.5)  => 2

should be -2 viz

> (floor -1.5)

-2



2) (fv

(fv (div 0.07 12) 240 775.30 -100000) => 0.55

but

> (fv (div 0.07 12) 240 775.30 -100000)

-0.5544645052

>



Nigel

[HPW]

There is this topic:



Licensing

newLISP and newLISP-tk are licensed under version 2 of the GPL (General Public License).





where the link is:



file:///C:/newlisp/newlisp_manual.html#GNU



but must be:



file:///C:/newlisp/newlisp_manual.html#GNUGPL

[nigelbrown]

re various examples

1)

(gammai 4 5)   =>   0.734974

full result:

                         => 0.7349740847



2) (index

(index symbol? '(1 2 d 4 f g 5 h)) => (3 4 5 7)

should be

(index symbol? '(1 2 d 4 f g 5 h)) => (2 4 5 7)



3) (integer?

(integer? (integer 1.00) => true

should be

(integer? (integer 1.00)) => true



4) (npv

(npv 0.2027 '(500 400 300 200 100))               => 999.9983704 ; ~ 1000

but

> (npv 0.2027 '(500 400 300 200 100))

1000.033848



5) (last

(last '(a b (c d))             => (c d)

should be

(last '(a b (c d)))            => (c d)



6) (last

(set 'var '(1 2 3 4)    => (1 2 3 4)

should be

(set 'var '(1 2 3 4))    => (1 2 3 4)



7) (net-lookup

(net-lookup "209.24.120.224"    => "http://www.nuevatec.com">www.nuevatec.com"

(net-lookup "http://www.nuevatec.com">www.nuevatec.com"  => "209.24.120.224"

should be?

(net-lookup "209.24.120.224")    => "http://www.nuevatec.com">www.nuevatec.com"

(net-lookup "http://www.nuevatec.com">www.nuevatec.com")  => "209.24.120.224"



8) (normal

says

(normal 10 3 10)  =>

    (6.5517812 6.57125 10.72219 8.133062 9.291025

     8.66425 7.97812 7.17125 11.39094 11.34456)

but

> (normal 10 3 10)

(7 6.563476562 11.93945312 6.153320312 9.98828125 7.984375 10.17871094

 6.58984375 9.42578125 12.11230469)

>



and

(normal 0 1) => -0.3964

but

> (normal 0 1)

0.6630859375

>



9) (not

(not (not (< 1 10))     => true

should be

(not (not (< 1 10)))     => true



10) (nth

(nth 3 "newLISP")    => "N"

should be

(nth 3 "newLISP")    => "L"



Nigel

[nigelbrown]

re various examples

1) (pow

(pow 100 2)     => 100

should be

(pow 100 2)     => 10000





2) (prob-chi2

(prob-chi2 10 6) => 0.125

full result



=>0.1246520195



3) (pv

(pv (div 0.07 12) 240 775.30)) => 100000.1373

should be?

(pv (div 0.07 12) 240 775.30) => 100000.1373



however

> (pv (div 0.07 12) 240 775.30)

-100000.1373



4) (regex

(regx {"} "abc"def")                       => (""" 3 1)  

should be

(regex {"} "abc"def")                       => (""" 3 1)  



5) (rest

(rest (rest alist))            => (d e)

should be

(rest (rest aList))            => (d e)



6) (rest

(first (rest "newLISP")        => "e"

should be

(first (rest "newLISP"))        => "e"



7)

(sequence 0 1 0.2) => (0 0.2 0.4 0.8 1)

should be

(sequence 0 1 0.2) => (0 0.2 0.4 0.6 0.8 1)



8) (sort

(sort '((3 4) (2 1) (1 10))            => ((1 10) (2 1) (3 4))

should be

(sort '((3 4) (2 1) (1 10)))            => ((1 10) (2 1) (3 4))



Nigel