[remark] & [end]

[newdep]

Hello Lutz,

Does newlisp have someting like 'comment or [remark] which
puts everything between [remark] [/remark] as would it be out-quoted, thus not evaluated, like ->

(define (func)
(.............................)
(begin
...
...

[remark]
(define ()
..
...
[/remark]

(...................)
)


thats quicker in bigger code then out-quoting all text with ";"


And perhpas also an [end] would be usefull in the code...
Everything after the [end] is ignored....but that could be
a single [remark] doing too perhpas ?

Regards, Norman

[Lutz]

what I always do is put

[text]
...
...
[/text]

around it. Mostly when you out-comment larger portions it is on the top level so the parser just races thru it and throws it away. Of course {,} will also work if less than 2038 characters in between.

Bit you also can do it inside a function:

(define (foo x)
[text]
large comment
[/text]
(+ x x))

It will see the string, but not do anything with it. I remember that some textbook for LISP recommended to put a string as the first thing in a user-defined function for comment purpose.

Lutz

[nigelbrown]

RE: "I remember that some textbook for LISP recommended to put a string as the first thing in a user-defined function for comment purpose."

Common Lisp has a function (documentation that returns the doc string
of various objects. eg from Corman Lisp

>(defun foo (x) "doc string is here" (+ x x))
FOO
>(documentation 'foo 'function)
"doc string is here"

However, I believe the keeping of doc strings is defined as inplementation
defined in the spec (some CLs drop doc strings on compilation I think).

CLTL2 (Common Lisp the Language, 2nd Edition ) notes:

"A simple facility is provided for attaching strings to symbols for the purpose of on-line documentation. Rather than using the property list of the symbol, a separate function documentation is provided so that implementations can optimize the storage of documentation strings. "

Nigel

[nigelbrown]

Further to common lisp usage and to Lutz's point that
"It will see the string, but not do anything with it."

I note
newLISP v8.0.6 Copyright (c) 2004 Lutz Mueller. All rights reserved.

> (define (foo x) (+ x x))
(lambda (x) (+ x x))
> (foo 2)
4
> (define (foo2 x) "doc string" (+ x x))
(lambda (x) "doc string" (+ x x))
> foo2
(lambda (x) "doc string" (+ x x))
> (nth 1 foo2)
"doc string"
> (foo2 2)
4
>

So newLISP keeps the doc string so
> (define (documentation f) (nth 1 f))
(lambda (f) (nth 1 f))
> (documentation foo2)
"doc string"
> (documentation foo)
(+ x x)
>

and in case of foo who could say that the function body was not default 'documentation'?

Nigel

PS with an if the documentation could be made to return nil a la CL if
function lambda was not length 3.

[HPW]

>and in case of foo who could say that the function body was not default 'documentation'?

How about a type-check in documentation to check for a string on the first element?

[newdep]

add on :)

Talking about doc-strings...

Rebol (lisp dialect) does it too where every thing in the first llines
of the function or object is declared between the first [ ] can be intepreted as a help (by help function) on the function or object,
its very handy...

>> ? dir?
USAGE:
DIR? target

DESCRIPTION:
Returns TRUE if a file or URL is a directory.
DIR? is a function value.

ARGUMENTS:
target -- (Type: file url)

(SPECIAL ATTRIBUTES)
catch
>>


** below you see the Doc-strings/function "DESCRIPTION" defined.
** and is not intepreted.. It can include any variable !

>> source dir?
dir?: func [
"Returns TRUE if a file or URL is a directory."
[catch]
target [file! url!]
/local info
][
info: throw-on-error [info? target]
either none? info [false] [info/type = 'directory]
]
>>

[HPW]

Would be:

Code: Select all

(define (documentation f) 
	(if (and(lambda? f)(string?(nth 1 f)))
		(nth 1 f)
		nil))

[HPW]

For a multi-row comment it would be:

Code: Select all

(define (foo2 x)
[text]
Doc string
Row2
[/text] (+ x x))

(define (documentation f)
	(if (and(or(lambda? f)(macro? f))(string?(nth 1 f)))
	(begin(print(nth 1 f))(write-line)true)
	nil))

> (documentation foo2)
Doc string
Row2
true
>

[nigelbrown]

Thanks Hans-Peter for thinking it through.
Perhaps
(list (nth 1 f) true)
to return doc rather than print
(begin(print(nth 1 f))(write-line)true)

Nigel

PS defining documentation perhaps we should have

(define (documentation f)
"This is a function to return the documentation of a function from its lambda"
(if (and(or(lambda? f)(macro? f))(string?(nth 1 f)))
(begin(print(nth 1 f))(write-line)true)
nil))

:)

[HPW]

So make it choosable:

Code: Select all

(define (doc f pflag)
[text]This is a function to return/print the documentation
of a function from its lambda/macro.
Sample call: (doc foo2) or (doc foo2 true)[/text]
	(if (and(or(lambda? f)(macro? f))(string?(nth 1 f)))
		(if pflag
		(begin(print(nth 1 f))(write-line)true)
		(nth 1 f))
		nil))

(define (foo2 x)
[text]Doc string
Row2[/text] (+ x x))