Need help with help
[1/9] from: tim:johnsons-web at: 1-Dec-2004 17:37
Hi Rebols:
At the console:
>> help *
USAGE:
value1 * value2
DESCRIPTION:
Returns the first value multiplied by the second.
* is an op value.
ARGUMENTS:
value1 -- (Type: number pair char money time tuple)
value2 -- (Type: number pair char money time tuple)
;; Now let's suppose I want to collect help with globally-defined
;; functions. The following function collects them.
get-global-funcs: func [
"collects a list of globally-defined functions."
/local vals args here total res ][
total: copy []
vals: second system/words
foreach word first system/words [
if any-function? first vals [
args: first first vals
if here: find args /local [args: copy/part args here]
append total reduce [word mold args]
]
vals: next vals
]
global-funcs: extract sort/skip total 2 2
]
;; Next, I want to collect the documentation. I hacked 'help as 'helps
;; to do so by gathering the output as a string. helps * gives me
;; a string with the same content as the console session above.
;; 'get-global-funcs collects function names as a list.
;; So far so good. But if I attempt to iterate thru the list of
;; global functions, I don't get the results I'm looking for
;; the following code:
foreach fnc global-funcs[
?? fnc ;; yields fnc: *
help fnc ;; see yield below
help :fnc ;; see yield below
help 'fnc ;; see yield below
break
]
;; gives me
help fnc ==>>
FNC is a word of value: *
;; no good
help :fnc ==>>
Found these words:
* op! Returns the first value multiplied by the second.
** op! Returns the first number raised to the second numb...
LWS* block! length: 2
WS* block! length: 2
;; no good either
help 'fnc ==>>
;; <sigh>
What do I need to do here?
Goal is to automatically build a series of emacs docstrings to
aid in on-demand documentation.
Thanks
tim
--
Tim Johnson <[tim--johnsons-web--com]>
http://www.alaska-internet-solutions.com
[2/9] from: gabriele:colellachiara at: 2-Dec-2004 12:48
Hi Tim,
On Thursday, December 2, 2004, 3:37:34 AM, you wrote:
TJ> What do I need to do here?
One possibility is to take the source of HELP and redefine it so
that it matches your need.
Otherwise, you'll need to do something like:
do compose [help (fnc)]
Regards,
Gabriele.
--
Gabriele Santilli <[g--santilli--tiscalinet--it]> -- REBOL Programmer
Amiga Group Italia sez. L'Aquila --- SOON: http://www.rebol.it/
[3/9] from: tim:johnsons-web at: 2-Dec-2004 8:47
* Gabriele Santilli <[gabriele--colellachiara--com]> [041202 03:21]:
> Hi Tim,
> On Thursday, December 2, 2004, 3:37:34 AM, you wrote:
<<quoted lines omitted: 3>>
> Otherwise, you'll need to do something like:
> do compose [help (fnc)]
Hi Gabriele:
That doesn't *help* either. Just returns a wildcard statement.
I'm going to include the two main functions that I am using at the
end of this email. Prior to that I want to show some console
code that gets at the heart of this problem.
To recap: 'helps (a rewrite of 'help to return docs as a string)
Properly documents a function if it is evaluated outside of a
block. My code has 'helps attempting to return documentation from
a block of function words. That function is 'get-global-funcs.
If I do this:
>> helps *
word
== {USAGE:
^-value1 * value2
DESCRIPTION:
^-Returns the first value multiplied by the second.
^-* is an op value.
ARGUMENTS:
^-v...
;; Cool. Good.
If I do this:
>> fncs: get-global-funcs
== [* ** + ++ - -- / // ...] ;; Good!
If I do this:
>> t: first fncs
== *
>> helps t
word
== none
;; argh!
;; I'm lost here, but there is a glimmer of light ...
If I do this
fncs1: compose/deep[(:*) (:append)]
and I do this
foreach f fncs1[helps f]
I get something like this:
== {USAGE:
^-F series value /only
DESCRIPTION:
^-Appends a value to the tail of a series and returns the series head.
^-F is a fu...
;;; Now we are getting somewhere, The proper documentation is returned,
;;; not the right spelling, but I can live with that.
I think the key is in how 'get-global-funcs gathers the function names,
but my tiny little brain can't quite get it so far.
Code for 'helps and get-global-funcs follows:
Thanks Gabrielle
helps: func [
{returns information about words and values as a string.
Currently ignores anything but functions. Rewrite of 'help}
'word [any-type!]
/local value args item name refmode types attrs rtype return-string
][
if unset? get/any 'word [ return none]
if all [word? :word not value? :word] [word: mold :word]
if any [string? :word all [word? :word datatype? get :word]][ return none ]
type-name: func [value] [
value: mold type? :value
clear back tail value
join either find "aeiou" first value [" an "] [" a "] value
]
if not any [word? :word path? :word] [ return none ]
value: either path? :word [first reduce reduce [word]] [get :word]
if not any-function? :value [ return none]
args: third :value
;; retrieve response as a string
return-string: copy ""
prn: func[val[any-type!]][
; dbg val
append return-string val
]
prn "USAGE:^/^-"
if not op? :value [prn append uppercase mold word " "]
while [not tail? args] [
item: first args
if :item = /local [break]
if any [all [any-word? :item not set-word? :item] refinement? :item] [
prn append mold :item " "
if op? :value [prn append uppercase mold word " " value: none]
]
args: next args
]
prn newline
args: head args
value: get word
prn "^/DESCRIPTION:^/"
either string? pick args 1 [
prn rejoin[tab first args newline tab uppercase mold word " is" type-name :value " value."
newline]
args: next args
] [ prn "^-(undocumented)^/" ]
if block? pick args 1 [
attrs: first args
args: next args
]
if tail? args [exit]
while [not tail? args] [
item: first args
args: next args
if :item = /local [break]
either not refinement? :item [
all [set-word? :item :item = first [return:] block? first args rtype: first args]
if none? refmode [
prn "^/ARGUMENTS:^/"
refmode: 'args
]
] [
if refmode <> 'refs [
prn "^/REFINEMENTS:^/"
refmode: 'refs
]
]
either refinement? :item [
prn rejoin[tab mold item]
if string? pick args 1 [prn rejoin[" --" first args] args: next args]
prn newline
] [
if all [any-word? :item not set-word? :item] [
if refmode = 'refs [prn tab]
prn rejoin[tab :item "-- "]
types: if block? pick args 1 [args: next args first back args]
if string? pick args 1 [prn rejoin[first args ""] args: next args]
if not types [types: 'any]
prn rejoin ["(Type: " types ")"]
prn newline
]
]
]
if rtype [prn rejoin["^/RETURNS:^/^-" rtype newline]]
if attrs [
prn "^/(SPECIAL ATTRIBUTES)^/"
while [not tail? attrs] [
value: first attrs
attrs: next attrs
if any-word? value [
prn rejoin[tab value]
if string? pick attrs 1 [
prn rejoin[" -- " first attrs]
attrs: next attrs
]
prn newline
]
]
]
return-string
]
get-global-funcs: func [
"collects a list of globally-defined functions."
/local vals args here total res ][
total: copy []
vals: second system/words
foreach word first system/words [
if any-function? first vals [
args: first first vals
if here: find args /local [args: copy/part args here]
append total reduce [word mold args]
]
vals: next vals
]
global-funcs: extract sort/skip total 2 2
]
> Regards,
> Gabriele.
<<quoted lines omitted: 4>>
> To unsubscribe from the list, just send an email to rebol-request
> at rebol.com with unsubscribe as the subject.
--
Tim Johnson <[tim--johnsons-web--com]>
http://www.alaska-internet-solutions.com
[4/9] from: Izkata:Comcast at: 2-Dec-2004 17:11
Huhm....
A: get-global-funcs ;Create block
B: first A ;get the first one..
do rejoin [{C: helps } B];Create a command and execute it
print C ;And there ya go!
(^.-)
[5/9] from: rebolforces::gmail::com at: 3-Dec-2004 9:13
Hi Tim,
You might want to check out Carl's Doc Viewer. It has a function spec
parser, that may give you control over the formating.
http://www.rebol.com/view/docs/view-ref.r
Cheers,
Allen K
-Yes, I'm back on the list, I couldn't hide on altme forever ;-)
[6/9] from: tim:johnsons-web at: 2-Dec-2004 15:26
* Izkata <[Izkata--Comcast--net]> [041202 14:31]:
> Huhm....
>
> A: get-global-funcs ;Create block
> B: first A ;get the first one..
> do rejoin [{C: helps } B];Create a command and execute it
> print C ;And there ya go!
Bam! Why didn't I think to use a string?
Thanks
I'm on a roll!
tim
> (^.-)
>
--
Tim Johnson <[tim--johnsons-web--com]>
http://www.alaska-internet-solutions.com
[7/9] from: tim:johnsons-web at: 2-Dec-2004 17:01
* Allen Kamp <[rebolforces--gmail--com]> [041202 14:44]:
> Hi Tim,
>
> You might want to check out Carl's Doc Viewer. It has a function spec
> parser, that may give you control over the formating.
I am looking for a way to build documentation into .el
files in elisp defun strings. The way that Izkata
showed me works just as I wanted it to.
> http://www.rebol.com/view/docs/view-ref.r
>
> Cheers,
>
> Allen K
>
Seems difficult to put a lot of code into altme.....
> -Yes, I'm back on the list, I couldn't hide on altme forever ;-)
Maybe I should keep asking questions to keep you here. <grin>
How about special methods for rebol, ala python?
tim
> --
> To unsubscribe from the list, just send an email to rebol-request
> at rebol.com with unsubscribe as the subject.
--
Tim Johnson <[tim--johnsons-web--com]>
http://www.alaska-internet-solutions.com
[8/9] from: gabriele:colellachiara at: 3-Dec-2004 10:28
Hi Tim,
On Friday, December 3, 2004, 1:26:26 AM, you wrote:
TJ> Bam! Why didn't I think to use a string?
Because you don't need to:
>> fnc: '*
== *
>> do compose [help (fnc)]
USAGE:
value1 * value2
DESCRIPTION:
Returns the first value multiplied by the second.
* is an op value.
ARGUMENTS:
value1 -- (Type: number pair char money time tuple)
value2 -- (Type: number pair char money time tuple)
I guess your problem is just that you're getting the word directly
from FIRST SYSTEM/WORDS, and that's unbound.
>> fnc: first find first system/words '*
== *
>> do compose [help (fnc)]
Found these words:
* op! Returns the first value multiplied by the second.
** op! Returns the first number raised to the second numb...
copy* action! Returns a copy of a value.
>> do compose [help (in system/words fnc)]
USAGE:
value1 * value2
DESCRIPTION:
Returns the first value multiplied by the second.
* is an op value.
ARGUMENTS:
value1 -- (Type: number pair char money time tuple)
value2 -- (Type: number pair char money time tuple)
Regards,
Gabriele.
--
Gabriele Santilli <[g--santilli--tiscalinet--it]> -- REBOL Programmer
Amiga Group Italia sez. L'Aquila --- SOON: http://www.rebol.it/
[9/9] from: tim:johnsons-web at: 3-Dec-2004 16:32
* Gabriele Santilli <[gabriele--colellachiara--com]> [041203 03:42]:
Hello Gabriele:
> Hi Tim,
> I guess your problem is just that you're getting the word directly
> from FIRST SYSTEM/WORDS, and that's unbound.
Aha!
> >> fnc: first find first system/words '*
> == *
<<quoted lines omitted: 4>>
> copy* action! Returns a copy of a value.
> >> do compose [help (in system/words fnc)]
;;And what works for me is:
do compose [doc-string: helps (in system/words fnc)]
;; which captures the docs as a string
Thanks!
> USAGE:
> value1 * value2
<<quoted lines omitted: 12>>
> To unsubscribe from the list, just send an email to rebol-request
> at rebol.com with unsubscribe as the subject.
--
Tim Johnson <[tim--johnsons-web--com]>
http://www.alaska-internet-solutions.com
Notes
- Quoted lines have been omitted from some messages.
View the message alone to see the lines that have been omitted