RFC open on newLISP documentation

[nigelbrown]

re various examples
1) (sort
(sort '((3 4) "hi" 2.8 8 b) => (2.8 8 "hi" b (3 4))
should eb
(sort '((3 4) "hi" 2.8 8 b)) => (2.8 8 "hi" b (3 4))
Nigel

[Lutz]

thanks for all the corrections Nigel, a comment to (normal ...)

The 'normal' , 'random' and 'rand' functions will cause different values on each computer executed and on each invocation, so it is natural that the documentation will show something different (but I think you where referring to the precision of the numbers). All rely on a pseudo random generator, which can be initialized using the 'seed' function. Using seed repeatable random sequences can be generated.

Lutz

[Lutz]

I did not yet put in the description for the memory limiting commandline switch ( -m N , where N is megabytes of max cell mem permitted), because of all the corrections we are doing on the manual, which I always post online for 7.4.0 users i the new revision.

This way I don't need to update two versions of the manual, and can make corrections available to users not using development versions. New features will always be shortly explained in the CHANGES file.

Lutz

[eddier]

The floor example has an error.

(floor -1.5) => -2

The definition of atan2 is incorrect in the index but correct in the body.

Eddie

[Lutz]

Thanks for all of the corrections, revision 6 of 7.4.0 is online at:

http://newlisp.org/download/newlisp_manual.html
http://newlisp.org/download/newlisp_manual.pdf

Lutz

[Sammo]

A few typos in v.7.4.8:

in the 'swap' command, "In the second form the charcaters ..." should be "In the second form the characters ..."

in the 'swap' command last sentence before example should end with "... the list or string."

in the 'symbol?' command, "= >" in the first example should be "=>"

[Lutz]

thanks for the corrections

Lutz

[Lutz]

Sam,

I am preparing some pages for a new section on the http://newlisp.org/news/ site for the 'Tips&Tricks' section.

I wonder if you give me permission to publish your 'roman.lsp' code. It is a nice small piece of newLISP code ideal for that section.

There will also be a small (and hopefully growing) collection of 'Code Snippets' with very short functions like 'allocate', 'cwd' etc, which I collected on this site and from my own stuff.

Lutz

[Sammo]

Lutz,

You are more than welcome to use my code. FYI, I wrote it originally in muLISP on an old DOS box. After I rewrote it just recently in newLISP, I read an article about Roman Numerals that suggests that not every numeral I generate is "correct" -- whatever "correct" means in Roman Numeral-land. When I have a little time I will reread the article and perhaps update my code to comply with its recommendations. In the meantime, the code is yours. I hereby testify that the code is my own creation and not the property or invention of anyone else.

[eddier]

There is an error in the 7.5.1 manual under Contexts as Classes

The last line should be

JD-001:balance =>123.45

Eddie

[eddier]

Under the heading

"Hash tables" should be "Hash Tables"

"newLisp" should be "NewLisp"

"very efficient with" should be "very efficiently with"

Eddie

[Lutz]

thanks Eddie

Lutz

[Lutz]

'newLISP' should always be written with lower case 'new' and uppercase 'LISP', it's a trademark.

On 'Hash tables' I am not sure. I don't capitalize nouns (except for the first one) in any other heading, or should I ?

Lutz

[Ryon]

Uh oh.

[eddier]

For books and other titles, capitalize the first and last word, as well as all the nouns, pronouns, adjectives, verbs and adverbs. Also capitalize any conjunction or preposition that is at least four letters long.

Trademarks are capitalized, but the generic product is not. It is Post-it notes, not Post-it Notes.

Source: http://www.alh.net/newlisp/phpbb/postin ... eply&t=119

I've always heard that we should always capitalize the first letter of the first word of a sentence, but with trademarks, I'm not sure. Maybe the site above will help.

Eddie[/quote]

[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 ... anual.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