RFC open on newLISP documentation

[nigelbrown]

Yes, that achieves the same, thanks for pointing it out.

[Sammo]

Documentation for the 'normal' function is unusually sparse. That is, I can't find it.

[Lutz]

Oops, it is out of the sort order after 'net-sessions' before 'new' ;-), will correct this in 8.0 final, meanwhile:

http://newlisp.org/download/newlisp_manual.html#normal

you can also get it from the index "Floating point math and special functions"


Lutz

[nigelbrown]

looking at the docs of replace shows inconsistencies viz
replace
syntax: (replace exp-key list exp-replacement)
syntax: (replace str-key str-data exp-replacement)
syntax: (replace str-pattern str-text exp-replacement int-option)
syntax: (replace exp list)
...

String replacement without regular expression

If all arguments are strings, replace replaces all occurrences of key-str in str-text with str-replacement and returns the changed string (previous to v.7.2.4 the number of changes). The expression in exp-replacement is evaluated for every replacement.

could be

replace
syntax: (replace exp-key list exp-replacement)
syntax: (replace str-key str-text exp-replacement)
___________________^^^^^^
syntax: (replace str-pattern str-text exp-replacement int-option)
syntax: (replace exp list)
...

String replacement without regular expression

If all arguments are strings, replace replaces all occurrences of str-key in str-text with
_______________________________________________^^^^^^
evaluated exp-replacement and returns the changed string (previous to v.7.2.4 the number
^^^^^^^
of changes). The expression in exp-replacement is evaluated for every replacement.

eg

> (setq n 1)
1
> (replace "aa" "ssaaggaahh" (append "aa" (string (inc 'n))))
"ssaa2ggaa3hh"
>

[Lutz]

thanks Nigel, this will be corrected

Lutz

[HPW]

command now in 8.0.2:

(apply date-value '(now)) => 1014834090

should be:

(apply date-value (now)) => 1014834090

[Lutz]

Thanks for the correction, rev1 of the docs in HTML and PDF format is online:

http://www.newlisp.org/index.cgi?page=Documentation

Lutz

[newdep]

**
net-listen is a blocking function call and does not return until somebody tries to connect to the listening port.
**

I think ment here is that net-accept is blocking.


**
Shared library module for Linux/BSD versions -->

(import "/usr/lib/newlisp.so" "newlispEvalStr")
(get-string (dllEvalStr "(+ 3 4)")) => "7"

must be

(import "/usr/lib/newlisp.so" "newlispEvalStr")
(get-string (newlispEvalStr "(+ 3 4)")) => "7"
***

[Lutz]

thanks for the corrections - lutz

[newdep]

** net select **
little typo ->
In the second syntax net-selectM can check for a list of sockets in list-sockets.

the "M" is too much...

[nigelbrown]

Small typo in float in Users Manual and Reference v.8.0.6:
float
syntax: (float exp [exp-default] )
If the expression in exp evaluates to a number or a string a conversion to an integer is returned.
obviously
"a float is returned"


Nigel

[Lutz]

Thanks Nigel, and thanks to anybody else taking the time to read the manual and find places for improvement. The manual should be one of the distinguishing features of newLISP. We are close to release 8.1, which will include a Freshmeat announcement and some advocacy pages on the newlisp.org web site. That will bring a lot of new curious users trying newLISP and reading, browsing the manual.

Lutz

[nigelbrown]

Regarding manual updates:
Perhaps some more context discussion and examples could be there.

I've been fiddling around with how to create and populate one context from another and found that I had difficulty thinking out how some of the symbol
resolution process within a macro occurs. I thought with
(define-macro (makecontext _ctxstr _doc) (begin
(context (symbol (eval _ctxstr)))
(set 'docs _doc)))

that
(makecontext "TEST1" "this is test1")
would create a context TEST1 which it does
but the docs symbol is in MAIN not in TEST1, I presume
because the docs symbol is resolved before context creates
and switches into the context - or am I missing something else?
eg
newLISP v8.0.6 Copyright (c) 2004 Lutz Mueller. All rights reserved.

> (makecontext "TEST1" "this is test1")
"this is test1"
TEST1> (symbols)
()
TEST1> MAIN:docs
"this is test1"
TEST1>

<split your reply into another thread if appropriate>

Nigel

[nigelbrown]

additionally with regard to the next release:
could either
modules like httpd be included in self installing win exe
or
a zip file with just the modules (ie not whole package source) be available in downloads.

Nigel

[Lutz]

The context function switches the context for subsequent translation of code. When the docs symbol gets translates the current context is MAIN. By the time the function runs all symbols already have their places in some context. In that macro only a statemens like (load ..) (symbols str) (eval-str ...) etc would be influenced by the previous context statement. It is a very common error to think symbols some how can switch contexts during runtime.

To populate a context from another context use (new OldCtx 'NewCtx)


Regarding modules and example programs, yes perhaps I should include some in the windows distribution, or have an extra archive for it. Not all programs are suited for lading them from the newLISP-tk frontend though. I think I go with an extra archive including both, the examples and modules directory.

Lutz

[Lutz]

Her is another way you code your example correctly:

Code: Select all

(define (makecontext ctxstr doc) 
    (set 'temp (context)) 
    (set 'ctx (context (symbol ctxstr))) 
    (set 'ctx:docs doc)  
    (context temp))        

The example makes use of context variables to hold the old context in temp for switching back ansd the context variable ctx, which can be used to refer to the new created context.

Lutz

[nigelbrown]

Thanks Lutz - works like a charm.
The reason I'm working on it is as a way to provide a lexical closure to simulate a
common lisp defun. I'll let the forum know how it goes.

Nigel

[Sammo]

Hi Lutz,

A few corrections for the manual. More later, perhaps.
-- Sam

GENERAL
-- sometimes you write "newlisp" and sometimes "newLISP"

COMMAND LINE OPTIONS AND DIRECTORIES
-- "and load ot if present" should be "and load it if present"
-- "the programtext is evaluated" should be "the program text is evaluated"
-- "newlisp exits otherwise" should be "newlisp exits; otherwise"

STACK SIZE
-- "loading one ore more" should be "loading one or more"

MAXIMUM MEMORY USAGE
-- "is shown as 8,l388,l608" should be "is shown as 8,388,608"
-- "counsumed" should be "consumed"

NEWLISP AS A TCP/IP SERVER (last paragraph)
-- "the the tags" should be "the tags"
-- "used in newLISP-tk a Tcl/Tk front-end" should be "used in newLISP, a Tcl/Tk front-end"

THE INITIALIZATION FILE INIT.LSP
-- "but is can be found" should be "but can be found"

DIRECTORIES ON LINUX, BSD, OSX
-- "POP3 mail etc." should be "POP3 mail, etc."

EVALUATION RULES AND DATA TYPES
-- the sentence beginning "nil are boolean ..." should be "nil and true are boolean data types and evaluate to themselves"
-- (last paragraph in this section) "In LISP built-in functions, which do not ..." should be "In LISP, built-in functions which do not ..."

[newdep]

dont forget the newlisp.so for (sys-info) :-)

net-listen ->
(net-listen 1002 "192.168.1.120" 1002 "udp")

must be ->
(net-listen 1002 "192.168.1.120" "udp")

[Lutz]

Thanks to Sam and Norman for manual corrections.

I suggest the following for 8bit OS version numbers:

bit 7 UTF-8 version
bit 6 Library version
bit 5 unused
bit 4 unused

bit 3 OS platform
bit 2 OS platform
bit 1 OS platform
bit 0 OS platform

this will allow for a total of 16 different platforms (6 currently used) with 4 categories of flavors, currently using 2 for UTF-8 and Lib

so for the library versions I will add 64, and for UTF-8 flavor 128 to the OS-platform numbers

Lutz

[newdep]

Yes... good idea to go bit-wise for version numbering...

[newdep]

net-connect

wrong link in "net-send" in think sentence ->

The function call in the example will return a socket number which can be used in a subsequent net-send to send UDP data packets.

[nigelbrown]

Re documentation of rpm use:
Downloading and installing rpm without signature checking gives 2 warnings - probably as expected but as this may be disconcerting to a linux newbie so perhaps some statement that
it is expected or how to avoid it may be worthwhile. (ie how to use the signature)

Nigel

[nigelbrown]

Installed rpm
On installing rpm (to system mdk 9.1) when clicking for help in newlisp-tk I get an error:
The file /usr/share/doc/newlisp/manual_frame.html cannot be found.
similarly for newlisp-tk.html
because the files are in
/usr/share/doc/newlisp-8.0.6

Nigel

PS I see it was a newlisp-tk.config from an earlier time - when I deleted it
and regenerated it with save settings all was well.

Perhaps a hint on that could be in the manual install section.

[Lutz]

I don't think you should get a warning messages becuase the rpms are signed? What kind of warning messages do you get? Which version are you installing? Did you get this warnings also in earlier installations?

The documentation is installed in /usr/share/doc/newlisp-x.x.x and in /usr/share/newlisp/doc . newlisp-tk requests the documentation from /usr/share/newlisp/doc not from the versioned directory. Look into your newlisp-tk.config in your home directory. Perhaps you have a wrong spec. in there from an earlier installation?

Lutz