Mailing List Archive: 49091 messages
  • Home
  • Script library
  • AltME Archive
  • Mailing list
  • Articles Index
  • Site search
 

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