RFC open on newLISP documentation

[Lutz]

... sometimes the distinction is blurry:

Code Select Expand


(set 'foo:foo '(a b c d e f g))

(foo 3) => d


in this case of implicit indexing the 'default functor' referring to a data object is used as a function overloaded with 'nth' functionality. So in this case its a little bit of both a 'functor' and a 'function'. But also in this case I would prefer to call it 'functor'.



Lutz

[m i c h a e l]

Here are the three places in the manual (before the function reference) where the term "functor" is used:



Like Scheme, newLISP also evaluates the functor part of an expression

Using default functors can simplify the syntax further

;; pass an object by reference with default functor



Based what Lutz has said in the preceding two posts, it seems that all references to functor here should stay as is.



m i c h a e l

[newdep]

Hi Lutz,



Still I found a small issue in the menual of 8.9.0 i could not fix right away...



I picked up my linux machine since 2 months and downloaded 890

opened the manual in FireFox 1.5.0.3 and it seems its unable

to handle the following quotes in HTML...



<span class="arw">&rArr;</span>



This generated a very strange charater instead of an arrow, changing

the document language or page codig did not work..its odd...



Any idea? because i think <span class="arw">&rArr;</span> is just

an official quote.. and under windows it works..



PS: I dont use any default language settnigs on my linux machine,

its pure a default rollout...





Norman.

[m i c h a e l]

Hi Norman,



Thanks for mentioning this. Seems you became a bit of a guinea pig here ;-)



I now see that &rArr; is not supported for all users. We could try &rarr;, &raquo;, or &rsaquo;, as these are all more openly adopted by browsers. Lutz's call.



As the manual is part of someone's first impression of newLISP, it can't be the first thing to cause them a problem! This one's mine, again. Sorry Lutz.



m i c h a e l

[newdep]

aaahh im always the little pig that has to deal with the wolf ;-)



The &rarr;, &raquo;, or &rsaquo; all work fine here..



Personaly i prefer the &rarr; but the &rsaquo; is more newlisp prompt like..



Norman.

[cormullion]

Reading the fine manual - a few minor typos and infelicities.



Section 18: UTF

date   converts date number to string (when used with the third argument)/td>

Syntax section

context



A An expression evaluationg to a context or namespace, or a variable symbol holding a context.

multiply   multiplies to matrices

bayes-train   counts items in lists for Bayesian or frequentist analysis

list?   checka if expression is a list

macro?   checka if a lambda-macro expression

main-args   geta command line arguments

process   launches a child process, remap standard I/O and standrad error

Function section



amb

On of the expressions exp-1 ... n is selected at random and the evaluation result is returned.

append

In the first form append works on lists and all list-n ... are appended to form a new lisp. The original lists are unchanged.

append-file

If the file does not exists it gets created, in this case append-file works identical to write-file.

array

Arrays in newLISP are used whenever randomly indexing into a big list gets to slow. Only a subset of list functions can be used with arrays. For a more detailed discussion see the chapter about arrays in the userers manual.

If not enough initializers are found in the list than the list is repeated until all elements of the array are initialized.

atan

The arctangent function of num-radians is calculated an returned.

bayes-query

in the default R.A. Fisher method priors are not not passed on via chaining, but probabilities are compounded using the CHi2 method.

bayes-train

Each token in D is a content addressable symbol in D containing a list of ferquencies of that token describing how often it occurs in each category. String tokens are prepended with an undersocre _ before converting them to a symbol in D. A total symbol is built containing the totals in each categorie. The symbol total should not be part of symbols passed in a categoy Mi.

Note that these examples are for demo purposes. In reality trainings sets may contain thousands or millions of words, especially when training natural language models. But small data sets may be used when then the frequency of symbols just describes already known proportions. In this case it may be better to describe the model data set explicitely without the bayes-train function:

define

The return value of define is the assigned lambda expression. When calling a user defined function, it's return value is the last expression evaluated in the function body.

lambda or fn expressions may be used by itself as an anonymous function without being defined into a symbol:

Trying to redefine ant protected symbol will cause an error message.

define-macro

New functions can be created which behave just like built-in functions delaying evaluation fo certain parameters or accessing parameters inside list expressions passed as parameters like the built-in functions for flow control.

format:

In newLISP format will automatically convert from inter to floating point numbers or from floating point to integer if the format strings requires it:

[cormullion]

continued....



Function reference



define-macro

A function with this chracteristic is called the default function.

A third possibility is too refer to passed parameters using args:

See also expand do do variable expansion explicit without evaluation of the expanded expression.

device

int may also be a the file handle previously obtained from opening a file using open.

dolist

Opionally a condition for early loop exit may be defined in exp-break.

An internal system variable $idx keeps track of the current offset into the list and can be accessed duwing execution of dolist:

do-while

If the evaluation of exp-condition is nil, then the do-while expression is finished, else the the expressions in body get evaluated again.

error-event

See also the also the function catch for a different possibility to handle errors and the function throw-error to throw user defined errors.

eval-string

If the string contains more then one expressions, the result of the last evaluation is returned.

exec

In this example cgiProc could be a cgi processor like Perl or newLISP receiving processing standard input, which would be supplied by a string contained in the variable query.

expand

expand reduces it's parameter list similar to apply.

factor

For numbers smaller than 2 or for numbers which are to big factor returns nil.

file?

The existence of a file does not imply anything about it's read or write permissions.

fn

The function is mapped on to a list of arguments usiung map. The seconnd example shows sorting strings by length.

for

Opionally a condition for early loop exit may be defined in exp-break.

get-string

When giving a string as an argument get-string will take it's address as the argument. Because get-string always breaks off at the first first 00- (zero) character it encounters, it can be used to get a string out of a buffer:

invert

The function will throw and error if the matrix cannot be inverted.

irr

The next line demonstrates the the relation between irr and npv.

In the last example securities where purchased initially for 5000 then for another 2000 3 month later

legal?

The token in string is checked if a legal symbol in newLISP source code. Non legal symbols can be created using the sym function, i.e. symbols containing spaces, quotes or other characters not allowed. Non legal symbols are created frequently when using symbols for for associative data access:

letex

The function args is used to access the un-evalutuated argument list from define-macro.

load

By default files which do not contain context switches with get loaded in to the MAIN context.

member

(member "" "newLISP")     ? "newLISP")

name

If the expression in bool evaluates to anything else than nil the name of the context, where the symbol belongs to, is returned.

net-connect

net-select or net-peek can be used to check for incoming commications in a non-blocking fashion.

net-eval

The following example illustrates the difference between the default evaluated and raw mode or net-eval:

The last to statements reveal that in the default evaluated

The example waits for a connections on port 1234,

new-listen

Optionally an interface IP address or name can be specified in str-ip-addr to listen on a specified address on computers with more then one interface card.

See the examples: UDP client and UDP server in the manuals appendix for a working example.

net-ping

Optionally a timeout parameter to wait for an answer can can be specified in int-timeout in milli seconds.

In the seconds syntax net-ping is run in batch-mode.

Usage of this this parameter can speed up return from the function before the timeout specified.

net-ping

While in broadcast mode net-ping sends out only one packet, which is received by multiple addresses, batch-mode explicitely generates multiple packets, one each for a target address.

... to be continued

[cormullion]

I just realised that you might consider this post-release week to be the wrong time to send in a long list of minor corrections! Sorry!



It's just that I didn't have so much time earlier this month, and I spent some of the available time on the Introduction. Also, I gathered that the document was already being edited and didn't want to spend the time going through an older version or having to synchronise editing versions, etc.

[Lutz]

With Michael's help we will publish manual revisions frequently as they come available. The next will be this Sunday.



So just keep those manual bugs coming on this thread as they jump into your eyes and Michael will work them in to his convenience, and make sure to always be based on the last version published.



Lutz

[cormullion]

I've started so I'll finish:



net-receive

When calling gettime The program connects to port 13 of the server netcom.com.

net-receive-udp

On Win32 is more bytes arrive net-receive-udp returns nil.

new

The example refers to contexts in variables and merges context foo into into bar.

normal

In the first form normal returns a list if int-n of random continuously distributed floating point numbers with a mean of float-mean and a standard deviation of float-stdev.

nth-set

Sets the nth in int-nth element in a list

An index out of bound always picks the last or first

See also the set-nth, which works like nth-set but returns the whole changed expression instead of the replaced element and is slower when doing replacements in a larger lists or string buffers.

pack

The > and < specifiers ca be used to switch

post-url

As a last parameter an optional timeout value in milli seconds can be spcified in int-timeout

process

Not all applications usable interactive in a console are suited for remapping their standard I/O channels.

randomize

Use seed to seed the generator at for a different starting point.

read-buffer

If no news bytes have been read sym-buffer will contain nil.

read-key

The last example an be used to check return sequences from navigation and function keys.

replace

Setting the the option bit 0x8000 in in-option will force replace to replace only the first occurrence.

The last form of replace has only two arguments an expression expr and list This form removes all expr found in list.

save

When saving contexts system variables symbols and all other symbols who's name starts with the $ character are not saved.

semaphore

When making a call to a semaphore with a negative value in int-wait, which would try to decrement the semaphore beyond zero, the function call will block until an other process or thread signals the semaphore with a positive value in int-signal.

The -1 is trying to decrement the semaphore, which is not possible because it's value is already zero.

sequence

Generates a sequence of numbers from num-start to num-end and with a optional step size of num-step.

share

Therefore shared strings should be stored after other shared number fields or reside on there own shared memory page.

Instead of spcifying a symbol containing the signal handler a function can be spefied directly.

When importing kill make always sure it receives integer numbers for the signal number.

source

System symbols starting with the $ character are only serialized when mentioned explicitely.

sub

Any floating point calculation with NaNalso returns NaN.

time

In first the example 450 milliseconds were spent to evaluate (myprog x y z).

timer

With default option 0 real time is measured, 1 mesaures only the time the CPU spends processing in the process or thread owning the timer and 3 is a combination of both, called profiling time.

trace

If an expression occurs more then once in a function, always the first occurrence of in the executing function will be highlighted (bracketed).

trace-highlight

Optionally two more string can be specified for str-header str-footer which control the separator and prompt. There is a maximum of 15 characters for the header and 31 for the footer

The first example replace the default "#" with a ">>" and "<<".

unify

Unbound variables start with an upper-case character to distinguish them from symbols. unify returns nil when the unification process fails and returns a list of variable associations on success or and empty lists when no variables where bound, but the match was still successfull.

The above algorithm could be written differently by omitting expand in the definition of prove-rule and pass the environment e as an parameter to the unify and query functions.

unpack

The > and < specifiers ca be used to switch between little endian and big endian byte order when packing or unpacking:

utf8

Converts UCS-4 encoded Unicode of 4 byte integers per character in str into UTF-8 character strings in str to .

write-buffer

This method is much faster then using append when concatenating to a string in place.

xml-parse

When tags are translated into symbols using option 8, a context can be specified in sym-context if no context is specified all symbols will be created in the current context.

Note that using the option number 16 a @ symbol is added to attributes lists.

And that's that. Enough English, time for some newLISP... :-)

[cormullion]

Michael - great job already! Sorry to give you some more manual labour. A bit like the Zen monk sweeping the gravel... ;-)

[m i c h a e l]

Michael - great job already! Sorry to give you some more manual labour. A bit like the Zen monk sweeping the gravel... ;-)

Thanks for all of your manual digging, cormullion. Unfortunately, you may have dug some post holes where the swimming pool is going, since I haven't gotten to those parts yet ;-)



For the 8.9.0 release, Melissa and I edited up to the reference section. I'm just now getting to "Functions in alphabetical order." Maybe as part of the release notes, we can indicate where the editing has left off.



I'll start making the changes cormullion mentioned and keep chipping away at the reference section.



m i c h a e l



cormullion: Is this payback for the "Introduction" side-by-side? ;-)

[cormullion]

No! :-) But I have to do something constructive after all the silly mottoes...













(newLISP (not (just (a (parenthetical (language))))))

[m i c h a e l]

silly mottoes

:-(

(newLISP (not (just (a (parenthetical (language))))))

:-)



m i c h a e l

[cormullion]

The manual gives this example for 'name':

Code Select Expand

(set 'ACTX:var 123)
(set 'sym 'ACTX:var)
(string sym)         => "ACTX:var"
(name sym)           => "var"
(name sym true)      => "ACTX"

It doesn't work for me.













newLISP: "Is this really a whole language in 212KB?"*



 ( * comment from an email I received recently ...)