TCL(Tool Command Language) Scripting :: Help Display for proc


	Help Display for proc Hello, I am writing multiple procedures which are to be used my team-mate to write main script. Suppose one such procedure with name "test" and has three arguments "a" "b" "c" proc test { a b c} { . . . } Now the other person who has to write the main script will use this procedure, but he wants to know what are the parameters required and their valid range etc. Either he will have to open the procedure "test" to look in the details. But I want something like if he writes test ? or test h the detailed usage of that procedure is displayed. I want to add this usage inside each procedure but not getting how to do. Suggest me some efficient wayouts > Suggest me some efficient wayouts You should look at the [info] command, which allows some introspection into defined procs. Example: # Getting Argument list of a proc % proc test {a b c} { puts "$a $b $c" } % info args test a b c # Getting default values for proc arguments, if any % proc testWithDefaults {a b {c defaultValue}} { puts "$a $b $c" } % info default testWithDefaults c default 1 % puts $default defaultValue HTH, Regards Stephan On Jun 7, 2:34 pm, skuha@web.de wrote: - Hide quoted text - > > Suggest me some efficient wayouts > You should look at the [info] command, which allows some introspection > into defined procs. Example: > # Getting Argument list of a proc > % proc test {a b c} { > puts "$a $b $c"} > % info args test > a b c > # Getting default values for proc arguments, if any > % proc testWithDefaults {a b {c defaultValue}} { > puts "$a $b $c"} > % info default testWithDefaults c default > 1 > % puts $default > defaultValue > HTH, Regards > Stephan Thanks Stephan, Besides default value, I want a help like stuff to be displayed, eg range for agrument "a" 1-10 range for argument "b" 21-25 if a < 5 or 21-30 if a > 5 etc.. test 1 22 33 will execute the procedure test but if a user writes test h , the complete usage is displayed.. thanks > Besides default value, I want a help like stuff to be displayed, > eg range for agrument "a" 1-10 > range for argument "b" 21-25 if a < 5 or 21-30 if a > 5 > etc.. > test 1 22 33 will execute the procedure test > but if a user writes test h , the complete usage is displayed.. Do you insist of this syntax "test h"? If so, I do not know an elegant solution. If not, you can create a general help command, for example "help test" prints out the complete usage. The help command can make use of [info] to give some general information about the proc. Additionally you can invent something like the docstrings in Python. For example you define [test] like this: proc test {a b {c defaultValue}} { set docString { This is the help Text spanning multiple lines giving usage info about test } puts "$a $b $c" } Then you can get the body of [test] with [info body test] and extract the contents of "docString" and print that out. Stephan help test is a good wayout. This will solve my problem. Thanks a lot Stephan. Couldnt think of such a simple strategy.. :( Thanx again Hello Rick, your wish to use something like "test h" or "help test" is nice, but only senseful inside the runtime environment of the application to be built - only with all modules and packages loaded. If somebody is outside this runtime environment, your construct will not help. And very often developers using modules or packages from other developers don't load explicitely those modules only to examine their usage. Very often developers stuck to man pages, describing the syntax and the usage of the commands or procedures inside those modules or packages. I would always suggest to let the source files contain additional information like a syntax and usage description and to extract those information to build a man page like in Java with javadoc. I know there are several packages inside the tcllib to generate documentation from source code, but I don't know how to handle them and how complex it will be. We in our team had our own selfmade tool scanning the source code for keywords to be extracted and formatted to be put to HTML man pages. In my opinion a good documented module or package has to provide an expressive man page, to easier the life of the developers using this module or package. Please take a look at the tcl community wiki http://wiki.tcl.tk/doctools! Best regards, Martin Lemburg P.S.: If you write a kind of console command using a tcl script, than it is really good to introduce something like "test --help", "test - h", or "test /?"! On Jun 7, 2:05 pm, rick <vagabond_maver@yahoo.com> wrote: - Hide quoted text - > help test is a good wayout. This will solve my problem. Thanks a lot > Stephan. Couldnt think of such a simple strategy.. :( > Thanx again - Hide quoted text - rick wrote: > Hello, > I am writing multiple procedures which are to be used my team-mate to > write main script. > Suppose one such procedure with name "test" and has three arguments > "a" "b" "c" > proc test { a b c} { > . > . > . > } > .... But I want something like if he writes > test ? or test h > the detailed usage of that procedure is displayed. Rick, It seems you already have a satisfactory answer, but the way I would do it is: proc test args { if {[llength $args] != 3} { prints {some help stuff more help stuff final help stuff} return } foreach {a b c} $args break . . } HTH, Gerry rick wrote: > [...] > test ? or test h > the detailed usage of that procedure is displayed. > I want to add this usage inside each procedure but not getting how to > do. > Suggest me some efficient wayouts Despite what others already suggested, I have two more options for you: the cmdline package (see http://wiki.tcl.tk/784) which is part of tcllib * (TCT members should now look away) the optparse package which is part of Tcl itself, but not officially supported. Please consider the warning in the first few lines of lib/tcl8.4/opt0.4/optparse.tcl carefully. kind regards -- Matthias Kraft Software AG, Germany Matthias Kraft wrote: > * (TCT members should now look away) the optparse package which is part > of Tcl itself, but not officially supported. Please consider the > warning in the first few lines of lib/tcl8.4/opt0.4/optparse.tcl > carefully. It's called the 'opt' package. (As for why it isn't supported, I never really understood that...) Donal. On Jun 7, 5:21 am, rick <vagabond_maver@yahoo.com> wrote: > Now the other person who has to write the main script will use this > procedure, but he wants to know what are the parameters required and > their valid range etc. This is such an important part of engineering software. Several suggestions: 1. When you define the procedure, use useful, informative names for the proc, its variables, etc. proc test { a b c } { : } vs proc execute_test_case {test_case_name argument timeout_value} { : : } yes, there is more typing when coding. But reading the definition, as well as usage in the code, will be clearer. 2. Add comments of some sort. Check out http://wiki.tcl.tk/13009 which lists several alternatives for adding doc to your code. 3. Tcl and Tk advocates frequently tout tcl's introspective features. Wouldn't it be wonderful if there were built in facilities that tcl used, itself, to containing documentation on its commands? It would make using it much easier. Certainly you could do as much as tcl does now - for instance, i see this: $ tclsh % package wrong # args: should be "package option ?arg arg ...?" % package help bad option "help": must be forget, ifneeded, names, prefer, present, provide, require, unknown, vcompare, versions, or vsatisfies I sure wish some kind of interactive help facility were generally available to provide this type of info. Unfortunately, many tcl commands don't do this, simply because there is no way to distinguish a request for help from an invocation of the command to do some work... Donal K. Fellows wrote: > Matthias Kraft wrote: >> * (TCT members should now look away) the optparse package which is part >> of Tcl itself, but not officially supported. Please consider the >> warning in the first few lines of lib/tcl8.4/opt0.4/optparse.tcl >> carefully. > It's called the 'opt' package. (As for why it isn't supported, I never > really understood that...) No one wants to document it and write test for it?? -- +--------------------------------+---------------------------------------+ \| Gerald W. Lester \| \|"The man who fights for his ideals is the man who is alive." - Cervantes\| +------------------------------------------------------------------------+ Gerald W. Lester schrieb: > Donal K. Fellows wrote: >> Matthias Kraft wrote: >>> * (TCT members should now look away) the optparse package which is part >>> of Tcl itself, but not officially supported. Please consider the >>> warning in the first few lines of lib/tcl8.4/opt0.4/optparse.tcl >>> carefully. >> It's called the 'opt' package. (As for why it isn't supported, I never >> really understood that...) > No one wants to document it and write test for it?? I don't think that's it, because there are quite some tests (tcl8.4/tests/opt.test) and somebody wrote quite some commentary into the file optparse.tcl itself ... kind regards -- Matthias Kraft Software AG, Germany Larry W. Virden wrote: > yes, there is more typing when coding. But reading the definition, as > well as usage in the code, will be clearer. There's one item that always throws me in the Tcl man pages. PHP writes a search function and says function search_for_substring($needle, $haystack) which (at least to native English speakers) is perfectly clear. Tcl writes a search function and says [string first $string1 $string2] Plus, of course, the order of thing-to-search-inside and thing-to-search-for isn't consistent between different commands, so I'm invariably looking it up even after 10 years of using Tcl. I guess I should probably report that as a feature request in the documentation, tho. :-) -- Darren New / San Diego, CA, USA (PST) His kernel fu is strong. He studied at the Shao Linux Temple. On Jun 8, 11:07 am, Darren New <d@san.rr.com> wrote: > I guess I should probably report that as a feature request in the > documentation, tho. :-) Or submit patches to the doc with it worded better. You wouldn't be the first person to submit improvement patches to docs <blush> Darren New wrote: > There's one item that always throws me in the Tcl man pages. > PHP writes a search function and says > function search_for_substring($needle, $haystack) > which (at least to native English speakers) is perfectly clear. > Tcl writes a search function and says > [string first $string1 $string2] Not any longer it doesn't! I've just fixed it (in the HEAD) to be worded more like the way PHP does it, on the grounds that this is either clearer or no worse than before. :-) Donal. Donal K. Fellows wrote: > Not any longer it doesn't! Very cool! Thank you! :-) I never realized till I said it here just how much that little frustration had been bugging me. :-) -- Darren New / San Diego, CA, USA (PST) His kernel fu is strong. He studied at the Shao Linux Temple. Darren New wrote: > Donal K. Fellows wrote: >> Not any longer it doesn't! > Very cool! Thank you! :-) I never realized till I said it here just how > much that little frustration had been bugging me. :-) It's been annoying me for a while, I admit, but your complaint gave me enough impetus to sort it out. Donal.