RFC open on newLISP documentation

Notices and updates
Lutz
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by 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
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by Lutz »

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

Lutz

nigelbrown
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by Lutz »

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

Lutz

Sammo
Posts: 180
Joined: Sat Dec 06, 2003 6:11 pm
Location: Loveland, Colorado USA

Post by Sammo »

newLISP v7.4.0 (rev-3) Manual and Reference
page 144
time-of-day
syntax: (time) should be syntax: (time-of-day)

nigelbrown
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by 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
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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

nigelbrown
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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
Nigel

nigelbrown
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by 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
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by 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.pdf

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

Hans-Peter, you are next?

Lutz

HPW
Posts: 1390
Joined: Thu Sep 26, 2002 9:15 am
Location: Germany
Contact:

Post by 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!
Hans-Peter

nigelbrown
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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 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
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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
Posts: 1390
Joined: Thu Sep 26, 2002 9:15 am
Location: Germany
Contact:

Post by 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
Hans-Peter

nigelbrown
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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" => "www.nuevatec.com"
(net-lookup "www.nuevatec.com" => "209.24.120.224"
should be?
(net-lookup "209.24.120.224") => "www.nuevatec.com"
(net-lookup "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
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by 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

Locked