Home     |     .Net Programming    |     cSharp Home    |     Sql Server Home    |     Javascript / Client Side Development     |     Ajax Programming

Ruby on Rails Development     |     Perl Programming     |     C Programming Language     |     C++ Programming     |     IT Jobs

Python Programming Language     |     Laptop Suggestions?    |     TCL Scripting     |     Fortran Programming     |     Scheme Programming Language


 
 
Cervo Technologies
The Right Source to Outsource

MS Dynamics CRM 3.0

TCL(Tool Command Language) Scripting

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:

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:

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.

Add to del.icio.us | Digg this | Stumble it | Powered by Megasolutions Inc