Find the 9.4.0 manual and reference here:
http://www.newlisp.org/download/development/newlisp_manual.html
... still changing, to make this the best quality manual ever released with newLISP. All corrections and suggestions are welcome.
Pointed this out before. Maybe it was missed, or not really important.
The description for read-line doesn't explicitly mentioned that it will ever return nil (although the example suggests that it will).
Thanks Michael, updated here:
http://www.newlisp.org/download/development/newlisp_manual.html
Good to see new version is coming. User manual and reference is comprehensive and pretty easy to read. Unfortunately, I'm not capable to say anything about 90% of the document because I do not know Newlisp that good, however, I have few proposals.
* consider to add example (or explicit claim) that "eval" has access to the local variables.
(let ((x 3)(y 7))(eval '(+ x y))) ;=> 10
* consider extending introduction with few sentences explaining "what is Newlisp" and "what is the purpose of this document."
* consider Unix instead of UNIX.
* consider to put "Functions in alphabetical order" as a 4th chapter of "Function reference".
Thanks for the input Kazimir, revision 6:
http://www.newlisp.org/download/development/newlisp_manual.html
Good examples for eval, just I think quote is omitted in all three eval examples with (+ x y) so these examples are true, but trivial. And one less important typo: "expi" in sentence "eval evaluates the result of evaluating expi in the current variable environment."
One of my previous jobs was as a technical writer dealing mainly with preparing user guides for software. I am a nOOb to newLISP, so can't address much on the technical merit of the text. However, I can offer some suggestions for style changes as well as some grammar and spelling corrections. In some matters of grammar, there is no consensus by the "experts" as to which form is correct. Therefore, you may find some of my suggestions more a matter of "preferred by school of thought XYZ" than as correcting an error. (For example, "since" and "because" are often used as synonyms. I adhere to the shchool of thought that if a clause or phrase is dealing with cause-and-effect, "because" should be used rather than "since". "Since" should be used as a time reference. For example. "It has been raining non-stop since yesterday." It is not possible to replace "since" with "because" because there is no "cause-and-effect" here, but rather "since" is making a time reference.)
You'll find below my suggestions for the first two sections. I copied the original text first, and then placed the suggested text below the original.
========================================
Consider using numbered sub-headings. For example
1. Introduction
1.1 newLISP-GS
1.2 Licensing
(You'll see as you go through the suggested changes that it would be much easier to reference by simply stating "section 1.2 para x" than to have to write out the sub-heading.)
Consider using a style for top-level headings of mixed case. For example:
instead of
2. Deprecated functions and futures changes
use
2. Deprecated Functions and Future Changes
=====================================================
1. Introduction
para.5
In this way, contexts can serve as dynamically created objects packaging symbols and methods.
In this way, contexts can serve as dynamically created objects that package symbols and methods.
para. 10 (Better to use "because" than "since" when a casue-and-effect is described.)
Since strings can contain null characters in newLISP, they can be used to process binary data.
Because strings can contain null characters in newLISP, they can be used to process binary data.
para. 14
On 64-bit Linux, SUN Solaris and True64Unix newLISP can be compiled as a 64-bit LP64...
On 64-bit Linux, SUN Solaris, and True64Unix, newLISP can be compiled as a 64-bit LP64...
1. Introduction
newLISP-GS
para. 1
newLISP-GS is a graphical user interface front-end written in newLISP and a Java based library server using the standard Java runtime environment installed on all Windows and Mac OS X platforms.
newLISP-GS comprises a graphical user interface (GUI) and library server. The GUI front-end is written in newLISP, whereas the library server is Java based and implements the standard Java runtime environment installed on all Windows and Mac OS X platforms.
para.2
This makes newLISP-GS is a platform-independent solution for writing GUI applications.
This makes newLISP-GS a platform-independent solution for writing GUI applications.
1. Introduction
Licensing
para. 1
Both the newLISP and other documentation packaged with newLISP are licensed under the GNU Free Documentation License.
The newLISP documentaiton as well as other documentation packaged with newLISP are licensed under the GNU Free Documentation License.
2. Deprecated functions and future changes
sub-heading 1 (don't use periods)
Flat and parenthesized syntax rules for index and keyed lsit access.
Flat and parenthesized syntax rules for index and keyed lsit access
para. 1
With release 9.3.0 the number of functions in the nth, assoc and ref families of functions has grown substantially through introduction of setter and multiple key access function for association lists. Some of these functions support both, the flat and the parenthesized syntax, other functions only support the newer parenthesized forms.
With release 9.3.0, the number of functions in the nth, assoc and ref families of functions has grown substantially through introduction of setter and multiple key access function for association lists. Some of these functions support both the flat and the parenthesized syntax; other functions only support the newer parenthesized forms.
para. 2
No rules existed to remember which of both syntax forms where supported in a given function. The parenthesized syntax groups the list or string together with the indices or keys for better readability and faster parseing by the interpreter routines. This is similar to the usage of parenthesis in the for, doargs, dolist, dotimes and dotree functions. Flat forms are faster to type, because they don't require additional parentheses and can be used with curry.
Previously, no rules existed to remember which of the two syntax forms, parenthesized or flat, were supported in a given function. The parenthesized syntax groups the list or string together with the indices or keys for better readability and faster parseing by the interpreter routines. This is similar to the usage of parentheses in the for, doargs, dolist, dotimes and dotree functions. Flat forms are faster to type because they don't require additional parentheses and can be used with curry.
para. 4
Where flat syntax forms exists in setter functions, i.e. nth-set and set-nth, they are not documented anymore and may be eliminated in the future.
Although flat syntax forms exist in some setter functions, e.g. nth-set and set-nth, they are not documented anymore and may be eliminated in the future.
2. Deprecated functions and future changes
Other changes
para. 1
The set-assoc or pop-assoc functions should be used instead of the deprecated replace-assoc, to replace or remove an association in an association list. The old replace-assoc has been removed from the documentation, and will be removed in a a future version.
The set-assoc or pop-assoc functions should be used instead of the deprecated replace-assoc to replace or remove an association in an association list. The deprecated replace-assoc has been removed from the documentation and will be removed in a a future version.
para. 3
The command-line function has been eliminated, command-event should be used instead to modify behavior of the command-line.
The command-line function has been eliminated; command-event should be used instead to modify behavior of the command-line.
Quote
instead of
2. Deprecated functions and futures changes
use
2. Deprecated Functions and Future Changes
If we're voting, I vote against making this change...:) I see no advantage in adopting this style.
Lutz - I'd like to go through the document again, but it will probably be over the weekend. When's your deadline?
Oh - and here's a typo I noticed yesterday while playing with bayes-query:
Quote
Thanks DrDave, changes are here in revision 8:
http://newlisp.nfshost.com/download/development/newlisp_manual.html
Quote from: "Cormullion"
Thankyou very much, that would be great, deadline is June 27th. If you want you can edit directly into the file using a text editor (e.g. BBEdit, Taco etc). I have TextWrangler, the free version of BBEdit installed. Don't use any word processor, because they screw up the HTML, which I have under tight control for reliable PDF conversion, usage in shell help functions, etc.. After you are done I use FileMerge.app (Apple developer utility) to see all your changes.
Since Michael and Melissa made the last complete pass through the manual, a few releases have gone by with changes and additions made by me, introducing new ways to misspell and mangle the English language :).
The good news is, that the manual has much improved eliminating inconsistencies in the HTML, so that it is easier to parse it programatically.
The chapter "15. The context default functor" is a regrouping and rewriting of older content in this new chapter.
There is undocumented form of let in Newlisp. Like in Common Lisp, but unlike in Scheme, let does not necessarily contain initialization parts.
(let ((x) (y "y"))
(println x y))
=> nily
There is a small practical, but I'd say significant aesthetic advantage of that form - because declaration is essential, initialization is only handy, so I think it could be good to document it. You need only this:
syntax: (let ((sym1 [exp-init1]) [(sym2 [exp-init2]) ... ]) body)
And perhaps to insert something like "if some exp-init is omitted, default value of nil is used instead" because few lines later, you explain that let is optimized equivalent of
((lambda (sym1 [sym2 ... ]) exp-body ) exp-init1 [ exp-init2 ])
and here exp-init cannot be just omitted, it has to be replaced with nil.
The atan entry is broken... (also in v.9.3.14)
Missing: (syntax:(atan... etc...
5,900,000 (atan num-radians)
The arctangent of num-radians is calculated and returned.
example:
(atan 1) → 0.7853981634
(tan (atan 1)) → 1
-- xytroxon
In section 3 of the manual, there is this example to test starting a newLISP server in Unix and then making a Telnet connection. (local domain socket connetions.)
Quote
I found at the very end of the section
Quote
I program in Win32. It would be a lot more useful to have this remark placed at the start of the section rather than at the end. It really does not make sense for us Win32 users to read an interesting and maybe useful bit of information only to be taken by surprise at the very end of it.
Quote from: "cormullion"
Quote
instead of
2. Deprecated functions and futures changes
use
2. Deprecated Functions and Future Changes
If we're voting, I vote against making this change...:) I see no advantage in adopting this style.
I second that.
K.
Thanks to everyone for all the help, here revision 9:
http://www.newlisp.org/download/development/newlisp_manual.html
For DrDave: on Windows just start the server in the foreground (can also use -d ):
then open a second command window window for the telnet application.
This also has been added to the documentation.
Found a few more...
3. Functions in groups
List processing, flow control, and integer arithmetic
Should be:
String and conversion functions
Should be:
Importing libraries
Should be:
Thanks xytroxon, here revision 10:
http://www.newlisp.org/download/development/newlisp_manual.html
Lutz,
I saw your comment about being able to edit directly into the HTML source file. I see that I can run the entire doc through a spell checker and make corrections. So how to send to you the corrected file?
Thanks DrDave, actually I spell-checked it already, but I may have forgotten something. You can send it as an email attachement to lutz at nuevatec dot com. Take the latest from the development directory, currently revision 10.
spellchecking the newLISP way:
(parse (read-file (string (env "HOME") "/Desktop/newLISP v.9.4.0 Manual and Reference.html")) {W} 0)))
(set 'words (parse (read-file "/usr/share/dict/words")))
(difference file words)
("" "doctype" "html" "w3c" "dtd" "4" "0" "http" "equiv" "charset" "utf" "8" "lutz"
"mueller" "keywords" "newlisp" "programming" "nuevatec" "users" "9" "css" "2em"
"1em" "roman" "ffaa28" "optima" "georgia" "456" "100" "16px" "arw" "303030" "cc0000"
"555555" "aa0000" "keyword" ... ... ...
Oh no, the list is way too long - that old Unix dictionary is showing its age!
But glancing through the list, I can see some typos:
So it finds a few more for you... :)
Thanks Cormullion, updated revision 11:
http://www.newlisp.org/download/development/newlisp_manual.html
at some point I would like to hand it off to you, so we don't work on two different versions. Tell me when the time has come, that you want to start the final review and correction pass. Then I stop correcting, and if people find stuff, you can work it in.
Thanks again for offering to do this, its a rather big piece of work. On the other side, since Michael and Melissa made a complete pass, I probably haven't touched more then 15% of it. The art is to find those 15% though ;-)
Just received a complete spell-check by DrDave.
Thank you very much.
82 mispelled words, missing commas, double word occurrences etc., have been fixed in revision 12:
http://www.newlisp.org/download/development/newlisp_manual.html
Sorry Lutz, I was hoping to spend some time on the manual over the weekend, but life caught up with me - and then overtook me... Not sure what I can do in the next few days either.
For the future, I can't help thinking that getting a number of different people to contribute to the manual this way is a bit too ..., well, 20th century. Isn't there some more dynamic way to allow people to collaborate as a loosely constructed group and work on areas that they feel comfortable with, in their own time? GoogleDocs? (No, not GoogleDocs, that can't even handle documents over 512K) What else is out there?
"retrieves the argument list of a macro expression" --> "retrieves the argument list of a function or a macro expression"
Quote from: "cormullion"
http://savannah.nongnu.org
Letex example has one extra quote:
(letex '(x 1 y 2 z 3) '(x y z))
I noted that length requires constant time in Newlisp, and that is some advantage over other Lisp dialects where it is linear. Maybe it deserves to be mentioned in the function reference.
"integer" appears to be alias for "int" but is not documented in manual.
On the other side, "int?" is not defined as predicate, but "integer?" is.
I think it is the best to define both as aliases - "int" and "integer"; "int?" and "integer?" and also to document both. (Such aliases, short and long seem to be good practice to me.)
I thought
Quote from: "cormullion"
See item 3
Lutz,
Regarding newlisp 10.0
Have you ever considered porting the documentaion to windows chm format?
Not sure how much work it takes but its a nice format that reads good too.
Norman
I'm not sure it would easy. And I think Microsoft have announced they're moving away from that format to another one. Also, I don't think it's easy to develop on systems other than Windows.
chm just is so easy to click on actualy and Voila you have a nice windowed
manual that runs on everything that has windows on it..
But i agree chm is from the OS2 days and its time for Microsoft to invent
their own stuff for once ;-)
I think Ill continue with porting the the Newlisp manual then to my JAVA
manual viewer by use of GS...(always a pleasure to use domestic tools ;-)
For release 10.0
perhpas the left pane index could get a little more extention?
! +-*/% Ab Ap B Ca Co Da Di Em Ev Fa Fn G I J La Li Ma Me Na Ne No O Pa Q Ra Reg Sa Sh St T U W X
more function now exist and this small index jumps over functions...
Not realy an issue but would walking through the manual a little more
smooth...
! +-*/% Ab An Ap B Ca Co Da Di Em Ev Fa Fn G I J La Li Lo Ma Me Na Ne Ni No Nu O Pa Pe Pi Q Ra Re Ro Sa Se Si Sg Sh So St Sy Ta Ti Un Up Ut Wa Wr X Ze
For release 10.0
another document extention...
Could the Chapters listed on the left frame ->
List processing, flow control and integer arithmetic
String and conversion functions
Floating point math and special functions
Matrix functions
Array functions
..
..
Also "be" a link that points to the description of these...
setq is not a valid jump target any more.
file:///C:/Programme/newlisp/newlisp_manual.html#setf
does work but
file:///C:/Programme/newlisp/newlisp_manual.html#setq
does not.
9.9.9.3
Manual states, which does not work anymore due to inc/dec changes->
Functions with memory
A default function can update the lexically isolated static variables contained inside its namespace:
;; a function with memory
(define (Gen:Gen x)
(if Gen:acc
(inc 'Gen:acc x)
(set 'Gen:acc x)))
(Gen 1) → 1
(Gen 1) → 2
(Gen 2) → 4
(Gen 3) → 7
gen:acc → 7
Thanks, I am working all this week on documentation, so any corrections are specially welcome this week.
init.conf.example has a wrong directory for lynx.
"lynx /usr/share/newlisp/doc/newlisp_manual.html#%s"
should be (according to the Makefile) ->
"lynx /usr/share/doc/newlisp/newlisp_manual.html#%s"
On the otherhand? You could change it with this ->
(but the html is very nice too)
;; --- command line help
(define-macro (help func-name)
(if (find func-name "|+*-") (push "\" func-name))
(set 'html-text (join (find-all (format {(syntax: (%s.*?)} (name func-name) )
(read-file "/usr/share/doc/newlisp/newlisp_manual.html")) "n"))
(println (replace "<.*?>" html-text "" 0))
"" )
Errata:
http://newlisp.nfshost.com/downloads/development/newlisp_manual.html
A sneaky html / frames problem with this section in the manual:
---------
4. Functions in alphabetical order
! +-*/% Ab Ap As Ba Ca Cl Co Cu De Di Do En
Ex Fi Fl Ga Gl In La Li Ma Mu Net New Nt Pa
Pr Ra Rea Reg Sea Seq Sl St Sy Ti Tr Ut Wr
Appendix...
-------
When reading the newLISP manual in HTML format,
The problem is caused by the links being in the form:
when
So the links in
Note:
---------
set-ref-all * <- uses asterisk instead of ! (exclamation point) as used by all other destructive functions
----------
-- xytroxon
Thanks for all the manual corrections. An updated version is available here:
http://www.newlisp.org/downloads/development/newlisp_manual.html
Missing brackets ->
manual 9.9.9.4
8. Lambda expressions in newLISP
(set 'double (lambda (x) (+ x x)) <---- missing )
(set 'double (fn (x) (+ x x)) <---- missing )
The define function is just a shorter way of assigning a lambda expression to a symbol:
(define (double x) (+ x x))) → (lambda (x) (+ x x))
(double 123) → 246
should be ->
(define (double x) (+ x x)) → (lambda (x) (+ x x))
(double 123) → 246
according to the manual ->
A lambda list can be manipulated as a first-class object using any function that operates on lists:
(setf (double 1) '(mul 2 x)) → (lambda (x) (mul 2 x))
double → (lambda (x) (mul 2 x))
(double 123) → 246
But that gives ->
# No Symbol reference found!
The example in the manual is wrong, because '(double 1)' will be evaluated returning 2, its the ambiguity of implicit indexing versus function call, therefore 'nth' has to be used:
This is the correct example:
double => (lambda (x) (mul 2 x))
Use the constant function (which works like set) to protect the symbol from subsequent alteration. Using the setq or setq function eliminates the need to quote the variable symbol.
should be ->
Use the constant function (which works like set) to protect the symbol from subsequent alteration. Using the setq or setf function eliminates the need to quote the variable symbol.
(setq should be setf, the link is oke though...)
9.9.95 typo...
syntax: (copy exp)
Make a copy from evaluating expression in exp. Some built-in functions are destructive, changing the original contents of a list, array or string they are working on. With copy their behvior can be made non-destructive.
should be "behavior"
I was looking at some functions in the manual and noted EXEC enables launching a process, such as another newlisp process (among others), and passing a command to it. For example,
7
true
For those that use newLISP quite a lot, I'm sure that the text in the manual is sufficient. But for new folks, or those that aren't hard-core users (I'm in that group), a couple of examples of code that really works would be very helpful.
I suspect that this could be useful if a blocking function needs to be called. So rather than calling the blocking function in the first newlisp process, launch a second newlisp process and call the blocking function and somehow capture the result. It is not clear to me how to capture the result from the second process. To where does the result go? How to determine if the result is availalble (maybe run a timer and check for wherever the result goes being true? Or somehow check for the final return value of true?)
Note that when using the second syntax of 'exec' feeding stdin to the process. Only 'true' or 'nil' is returned. The '7' you are seeing is only stdout of the process showing up in the your console terminal. Only when not feeding stdin, the output of the process is collected and comes back in a list:
("7")
>
For what you are suggesting 'process' with the pipes option may be the better solution, because you can set up a non-blocking bidirectional communication and use 'peek' to check if something is ready on the input pipe:
(3 4)
> (map set '(nlin myout) (pipe))
(5 6)
> (process "/usr/bin/newlisp" nlin nlout)
15763
> (write-buffer myout "(+ 3 4)n")
8
> (peek myin)
2
> (read-line myin)
"7"
> (write-buffer myout "(exit)")
6
> (peek myin)
0
>
Look also into 'net-eval' which allows you to distribute processes on different machines on a network. Its blocking but can also be event driven when a node has a result ready.
If you are on Mac OS X, Linux or other Unix you should also look into newLISP's Cilk API with the functions 'spawn', 'sync' etc.
Thanks for the explanation.
This code doesn't work for me (Windows XP pro, newLISP 9.3.0)
("7")
>
Here is the result I get
(There are probably more spaces betwee the + and \, but I didn't count them all.)
Try this:
("7")
>
Quotes are not permitted on Windows as token delimiters on the command line, using curly braces as the outer string delimiters you can use double quotes inside.
ps: redundant parentheses removed
Thanks.
This works as you wrote it
("7")
>
This also works with one set of parentheses eliminated
("7")
>
Also this variation
("7")
>
regarding 'inc and 'dec.. I think the manual needs an addon..
when using 'inc excluding place and num
'inc will increase by itself. like in (inc)
Any increment of a value afterwards using place will
start from that value on..Except when place was initialized first.
i.e.
If X is a list then (X (inc)) will run until 'ERR:..out bound of bound" occeurs
the following (inc Z) will continue where (inc) left off..
PS:
if (inc) is a feature? then ->
* how do i reset (inc) ?
* could (inc) always start at 0 <-initialy at newlisp startup ? and (inc place) at 1 ?
Quote from: "newdep"
when using 'inc excluding place and num
'inc will increase by itself. like in (inc)
Are you saying that you want (inc) to be pointing to a variable such as 'inc-value that will be incremented by 1 (integer only) with every call of (inc) ? In other words, it would be doing this behind the scenes:
And the user can both query and change 'inc-value at will?
If so, I don't see the point of it.
when starting newlisp and running (inc) it will show 1
if (inc) is a feature you could use (inc) as an implicit index counter
but because at the first (inc) it starts at a 1 its of no use ;-)
(this is my request for (inc) starting at 0 initialy at newlisp startup)
Im just wondering if (inc) is a feature, which is usefull, but how to
reset it then back to 0 ?
(inc) will only increase
(inc a) will take value of (inc)
(setq b 0)
(inc b) is always 1
(X (inc)) can't be used as an index because (inc) is always +
the use of (inc) is not documented so im just wondering about its use..
(inc) -> should throw an error. Its a bug!
Quote from: "Lutz"
throws error in v 9.3.0 on Win32
In
The line
"The return value of bind is the value of the last association."
is written twice.
manual 10.0
missing parenthesis in -> when <-
(when (read-line)
(set 'result (analyze (current-line)))
(report result
(finish)
)
syntax statements for cond and chop are missing final parentheses
(Don't ask why/how I spotted that - it's something I'm working on at the moment...!)
Also, "co" in contents jumps to copy - should jump to command-event...
Errata:
Code Patterms:
23. Extending newLISP
,,,
#include <stdio>
#include <stdlib>
#include <ctype>>
-------------
newLISP manual:
dec !
syntax: (dec place [num])
...
example:
...
Places in a list structurei
---------
========
newLISPdoc.html
Change: "exactly on space"
To: "exactly one space"
========
newlisp_manual.html
dostring
...
example:
; ASCII example
(set 'str "abcdefg")
(dostring (c str) (println c " - " (char c)))
97
98 - a
99 - b
100 - c
101 - d
102 - e
103 - f
Change to:
97 - a
98 - b
99 - c
100 - d
101 - e
102 - f
103 - g
----------
when
...
Change: "See also the function when"
To: "See also the function unless"
=========
(lambda-macro (a b) (set (eval a) b)) → (lambda (x) (* x x))
Noted by
Quote from: "Kazimir Majorinc"
Noted by
Kind of them to help proofread the manual... :) Usually they have only insults and condescensions - perhaps they've decided to become better people!
Every time newLISP is mentioned on comp.lang.lisp, a hatestorm breaks out, causing every newLISPhobe to come out of the woodwork and vent their spleens. Good thing Kazimir is so flame-retardant!
They do this so often, I'm beginning to believe they like the smell of their own bullshit. They produce so much of it ;-)
m i c h a e l
Quote from: "m i c h a e l"
m i c h a e l
Fools... Don't they know they must fear Haskell as the true heir to the advanced purely functional programming language crown? ;)
Maybe someone could write a post explaining how modernizing the antiquated
-- xytroxon
Quote from: "xytroxon"
Maybe someone could write a post explaining how modernizing the antiquated...
As I recall, they like to remind those that question the CL dogma that they have a "Standard". While standards usually have a positive aspect, it seems to me that the standard bearers are so afraid of breaking any existing code that their community cannot (will not?) modernize the standard. Hence, the standard they so proudly defend is probably their greatest impediment to progress
About
[list=1]
It appears that
It should probably say:
manual 10.0
Clicking on hyperlink Wr in left frame 'Functions in alphabetical order' jumps to 'write-file' instead of 'write-buffer'.