RFC open on newLISP documentation

nigelbrown · Post by **nigelbrown** » Tue Dec 16, 2003 9:41 pm

In case these (from manual 7.4.0 development) haven't been caught yet:

In (rest examples
(rest 'aList) => (b c d e)
unquote 'alist :
(rest aList) => (b c d e)

(rest "newLISP") => "ewLISP")
drop end bracket:
(rest "newLISP") => "ewLISP"

In (floor examples
(floor -1.5) => 2
should be => -2

Regards
Nigel

Lutz · Post by **Lutz** » Tue Dec 16, 2003 10:19 pm

thanks, will be corrected

Lutz

nigelbrown · Post by **nigelbrown** » Wed Dec 17, 2003 4:01 am

A suggestion: nowhere in manual is www.newlisp.org referred/linked to.

(% definition says:
syntax: (% int-1 [int-2 ... ])
Expressions are evaluated. Each result is divided successively by the next int and the rest (modulo operation) is returned. Division by zero will cause an error.

now in Newlisp:
newLISP v7.4.0 Copyright (c) 2003 Lutz Mueller. All rights reserved.

> (/ -340 10)
-34
> (% -340 10)
6
>
I'm not sure what % is doing - whether there is some logic that is not clear
from the manual or an error/quirk of % with negatives - but I think it's
an error - see below.

The code in nl-math.c (7.3.17) is
case OP_MODULO:
if(number == 0) return(errorProc(ERR_MATH));
result %= number; break;

However the other definitions around there cast number long
viz:
case OP_SUBTRACT: result -= (long)number; break;

Has the lack of cast broken % ?

Nigel

PS I found an interesting, although long, discussion of modulo functions in programming languages and mathematics here:
http://mathforum.org/library/drmath/view/52343.html

nigelbrown · Post by **nigelbrown** » Wed Dec 17, 2003 10:59 am

Apologies that the previous post wandered away from pure manual corrections - back to a correction?

the manual says
(< 6 1.2 "Hello" any (1 2 3)) => true
newlisp says
> (< 6 1.2 "Hello" any (1 2 3))
nil

and
> (< "hello" any)
nil

The manual says :
When mixed type expressions are compared, their types are compared in the following order (low to high).

Atoms: nil, true, integer, float, string, symbol, primitive Lists: quoted list/expression, list/expression, lambda , lambda-macro

The string, symbol comparison returns nil? Should the manual have a different comparison order?

Nigel

Lutz · Post by **Lutz** » Wed Dec 17, 2003 2:37 pm

(< 6 1.2 "Hello" any (1 2 3)) ; wrong

fails becuase of (< 6 1.2) also 'any' ans (1 2 3)should be quoted:

(< 1.2 6 "Hello" 'any '(1 2 3)) => true
(< "Hello" 'any) => true

will be corrected in the manual

Lutz

nigelbrown · Post by **nigelbrown** » Wed Dec 17, 2003 3:03 pm

Manual correction?
Manual says
(sort '((3 4) "hi" 2.8 8 b) => (8 2.8 "hi" b (3 4))
as stand should be
(sort '((3 4) "hi" 2.8 8 b)) => (8 2.8 "hi" b (3 4))

however:
> (sort '((3 4) "hi" 2.8 8 b))
(2.8 8 "hi" b (3 4))
>
This means the bit about comparing different types viz
If two expressions of different type get compared, then the lower type is sorted before the higher type in the following order:

Atoms: nil, true, integer, float, string, symbol, primitive

is not correct as integer and float get compared as numbers not as
types. This also applies to the < discussed above.

Nigel

Lutz · Post by **Lutz** » Wed Dec 17, 2003 3:24 pm

Yes, the cast was missing in the code for %.

Following comment after reading http://mathforum.org/library/drmath/view/52343.html :

The modular function 'mod' for floats and '%' for integers work differently for negative numbers in newLISP compared to Excel. I am using the 'C' operator and the fp function fmod() (previously handcoded), which both work consistently returning :

(% -340 60) => -40
(mod -340 60) => -40

They work as of the following definition, which I also added to the manual:

>> GNU libc documentation: >>
These functions compute the remainder from the division of numerator by denominator. Specifically, the return value is numerator - n * denominator, where n is the quotient of numerator divided by denominator, rounded towards zero to an integer. Thus, fmod (6.5, 2.3) returns 1.9, which is 6.5 minus 4.6.

The result has the same sign as the numerator and has magnitude less than the magnitude of the denominator.
<<

A similar definition is also used in: http://www.opengroup.org/onlinepubs/007 ... /fmod.html

Lutz

Lutz · Post by **Lutz** » Wed Dec 17, 2003 5:00 pm

Also, I wonder what Eddie's opinion (aren't you a math person?) is on this one?

Lutz

eddier · Post by **eddier** » Thu Dec 18, 2003 3:13 pm

I have never worked with a mod for floating point numbers?

As for integers, this is a can of worms. Different language compilers (even different C compilers) don't even agree on x / y. If exactly one of x and y is negative, some will round down, -3 / 2 => -2, while others will round toward 0, -3 / 2 => -1. But rumor has it that / and % should agee to x = y*(x/y) + x%y where y is not 0.

Eddie

eddier · Post by **eddier** » Thu Dec 18, 2003 3:58 pm

Here are some results of different languages.

GNU C gives
-340 % 60 => -40

Perl, Python, and Ruby give
-340 % 60 => 20

According to http://www.python.org/doc/current/ref/binary.html the sign of x % y is the
same as its second argument. I would that is true for Perl and ruby as well.

Eddie

Lutz · Post by **Lutz** » Thu Dec 18, 2003 4:44 pm

GNU 'C' does the same for mod and %, always taking the remainder of the division towards zero versus towards the smaller (more left on the numbers axis) integer multiple of the denominator.

I will stay with theirs (GNU C) for now and have documented it in the manual. I find it more intuitive and easier to understand (of course this is very subjective). The Gnu 'C' version produces the same 'magnitude' for both signs =/-, while the other method produces two different numbers.

In any case the difference between the versions is only important when dealing with negative numbers. I wonder what tools like Mathematika or Matlab do and I also wonder what the 'deeper' mathematical meaning behind this is; perhaps its just that: viewing negative numbers as magnitudes versus point on a line starting at infinitive negative?

Lutz

eddier · Post by **eddier** » Thu Dec 18, 2003 5:56 pm

Tonight, I will dig up my number theory book and see what it has to say.

Eddie

Sammo · Post by **Sammo** » Fri Dec 19, 2003 2:10 pm

What's the latest newLISP Users Manual and Reference? I've noticed a few more typos in v.7.4.0 but want to make sure I'm reading the latest revision before I post anything.

Lutz · Post by **Lutz** » Fri Dec 19, 2003 5:10 pm

the latest one is always the latest in:
http://newlisp.org/download/development/

Both, the source and the Windows distribution have the manuals. The rc1,rc2,rc3 versions did not distinguish with version numbers inside, they say all: 7.4.0. So the stuff in rc3 is the latest.

I am about to post the final 7.4.0 but if you have some other typos today, I delay it until tomorrow.

In the release version of 7.4.0 you will have the copyright date changed to 2004, which will be the only thing indicating the difference between release candidate versions and the fnal release.

Lutz

Sammo · Post by **Sammo** » Fri Dec 19, 2003 7:25 pm

Just a few observations. The page 7 and page 124 notes are the most important.

page 7: "When the DLL is loaded it looks for an ini.lsp file ..." -- should that be "an init.lsp file"? If it should really be "ini.lsp", please emphasize (e.g., "yes, ini.lsp for the DLL instead of init.lsp").

page 124: syntax: (rename-file str-path) looks like (per the example) as if 'rename-file' should have two parameters.

page 145: in the paragraph describing 'trim': "... the space is assumes by default." should be "... the space character is assumed."

Sammo · Post by **Sammo** » Fri Dec 19, 2003 7:32 pm

page 35: in the paragraph beginning "Calculations which result in value ..." -- the negation sign "-" in -2147483648 appears on a line by itself which can be confusing. Is there a way to force it to move with the body of the number to the next line?

Lutz · Post by **Lutz** » Fri Dec 19, 2003 9:05 pm

Thanks for the corrections Sam, I have put tags around the numbers, that will hopefully keep the sign with the number during PDF conversion.

Lutz

Sammo · Post by **Sammo** » Fri Dec 19, 2003 9:51 pm

page 88: the syntax for 'list' should have a closing parenthesis.

Lutz · Post by **Lutz** » Sat Dec 20, 2003 3:43 pm

Thanks to all of you for helping to move newLISP forward a big step. Release 7.4.0 is available at http://newlisp.org and http://sourceforge.net/projects/newlisp

Lutz

Sammo · Post by **Sammo** » Sat Dec 20, 2003 4:00 pm

This is late, I know, but maybe for the next update.

page 59: directory section: The last sentence should be followed by an example such as (directory "c:/").

Lutz · Post by **Lutz** » Sat Dec 20, 2003 5:06 pm

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

Lutz

Sammo · Post by **Sammo** » Sun Dec 21, 2003 6:16 pm

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 · Post by **Lutz** » Sun Dec 21, 2003 7:09 pm

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 · Post by **nigelbrown** » Mon Dec 22, 2003 4:37 am

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 · Post by **nigelbrown** » Wed Dec 24, 2003 5:40 am

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