[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 Expand


(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 Expand


(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 Expand


(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))