User Procs with Command Line Argument - 2024.2 English

Vivado Design Suite User Guide: Using Tcl Scripting (UG894)

Document ID
UG894
Release Date
2024-11-13
Version
2024.2 English

Like any Tcl proc, the arguments definition of the user procs can be either position-based or accept a variable list of arguments through the args variable.

proc ::tclapp::mycompany::template::my_command2 { arg1 {optional1 ,} } {
…
}

or,

proc ::tclapp::mycompany::template::my_command2 { args } {
…
}

In both cases, it is up to the developer to define the meta-comment Argument Usage to reflect the list of command line arguments accepted by the proc. The system does not check the consistency between the list of arguments from the meta-comment Argument Usage with the actual arguments definition.

Because the meta-comment Argument Usage is used to build the Help message, whatever above form is used for the proc to pass argument, the meta-comment must be updated accordingly. For example:

proc ::tclapp::mycompany::template::my_command2 { arg1 {optional1 ,} } {
    # Summary : A one line summary of what this proc does
    # Argument Usage:
    # arg1 : A one line summary of this argument
    # [optional1=,] : A one line summary of this argument
    # Return Value: 
    # TCL_OK is returned with result set to a string
    # Categories: xilinxtclstore, template
…
}

or,

proc ::tclapp::mycompany::template::my_command2 { args } {
    # Summary : A one line summary of what this proc does
    # Argument Usage:
    # arg1 : A one line summary of this argument
    # [optional1=,] : A one line summary of this argument
    # Return Value: 
    # TCL_OK is returned with result set to a string
    # Categories: xilinxtclstore, template
…
}
Note: Using args should always be preferred whenever possible over using position-based arguments. The args method provides the best user experience as the list and order of the command line arguments has no restriction. If the proc supports only one or two command arguments then the position-based can be still used, but is not as user-friendly because the arguments are ordered and the user does not know in which order the arguments should be passed to the proc (information not provided by the Help system).