

Command Reference  2.  FPGA Express Shell Commanddsefine_proc_attributes


_N_A_M_E
          define_proc_attributes
                         Defines attributes of a Tcl procedure,
                         including an information string for
                         help, a command group, a set of argument
                         descriptions for help, and so on. The
                         command returns the empty string.


SYNTAX
          string define_proc_attributes _p_r_o_c__n_a_m_e
                 [-info _i_n_f_o__t_e_x_t]
                 [-define_args _a_r_g__d_e_f_s]
                 [-command_group _g_r_o_u_p__n_a_m_e]
                 [-hide_body]
                 [-dont_abbrev]
                 [-permanent]
         string    _p_r_o_c__n_a_m_e
         string    _i_n_f_o__t_e_x_t
         list _a_r_g__d_e_f_s
         string    _g_r_o_u_p__n_a_m_e


ARGUMENTS
          _p_r_o_c__n_a_m_e      Name of the existing procedure.


          -info _i_n_f_o__t_e_x_t
                         Provides a help string for the
                         procedure. This is printed by the help
                         command when you request help for the
                         procedure. If you don't specify
                         _i_n_f_o__t_e_x_t, the default is "Procedure".


          -define_args _a_r_g__d_e_f_s
                         Defines each possible procedure argument
                         for use with help -verbose. This is a
                         list of lists where each list element
                         defines one argument.


          -command_group _g_r_o_u_p__n_a_m_e
                         Defines the command group for the
                         procedure. By default, procedures are
                         placed in the "Procedures" command
                         group.


          -hide_body     Hides the body of the procedure from
                         -info body.


v3.0      Synopsys Inc. 1988-1998. All rights reserved.       2-1


define_proc_attribut2e.s FPGA Express Shell Commands   Command Reference


          -dont_abbrev   The procedure can never be abbreviated.
                         By default, procedures can be
                         abbreviated, subject to the value of the
                         sh_command_abbrev_mode variable.


          -permanent     Defines the procedure as permanent. You
                         cannot modify permanent procedures in
                         any way, so use this option carefully.


DESCRIPTION
          The define_proc_attributes command associates
          attributes with a Tcl procedure. These attributes are
          used to define help for the procedure, locate it in a
          particular command group, and protect it.

          When a procedure is created with the proc command, it
          is placed in the Procedures command group. It has no
          help text for its arguments. You can view the body of
          the procedure with -info body, and you can modify the
          procedure and its attributes. The
          define_proc_attributes command allows you to change
          these aspects of a procedure.

          Note that the arguments to Tcl procedures are all named
          positional arguments. They can be programmed with
          default values, and there can be optional arguments by
          using the special argument name _a_r_g_s. The
          define_proc_attributes command does not relate the
          information that you enter for argument definitions
          with -define_args to the actual argument names. If you
          are describing anything other than positional
          arguments, it is expected that you are also using
          parse_proc_arguments to validate and extract your
          arguments.

          The _i_n_f_o__t_e_x_t is displayed when you use the help
          command on the procedure.

          Use -define_args to define help text and constraints
          for individual arguments. This makes the help for the
          procedure look like the help for an application
          command. The value for -define_args is a list of lists.
          Each element has this format:

              _a_r_g__n_a_m_e _o_p_t_i_o_n__h_e_l_p _v_a_l_u_e__h_e_l_p _d_a_t_a__t_y_p_e _a_t_t_r_i_b_u_t_e_s

          The _a_r_g__n_a_m_e is the name of the argument.  _o_p_t_i_o_n__h_e_l_p
          is a short description of the argument. The _v_a_l_u_e__h_e_l_p
          is typically the argument name for positional


2-2       Synopsys Inc. 1988-1998. All rights reserved.      v3.0


Command Reference  2.  FPGA Express Shell Commanddsefine_proc_attributes


          arguments, or a one word description for dash options.
          It has no meaning for a boolean option. The _d_a_t_a__t_y_p_e
          and _a_t_t_r_i_b_u_t_e_s are optional and will be used for option
          validation. The _d_a_t_a__t_y_p_e can be any of: string, list,
          boolean, int, float, or one_of_string. The default is
          string. The _a_t_t_r_i_b_u_t_e_s is itself a list that can have
          any of the following entries: "required", "optional",
          "value_help", and "values {<list of values for a
          one_of_string argument type>}". Note that "required"
          and "optional" are mutually exclusive. If the argument
          type is one_of_string, you must specify the "values"
          attribute. The "value_help" attribute indicates that
          the valid values for a one_of_string argument should be
          listed whenever argument help is shown. The default for
          _a_t_t_r_i_b_u_t_e_s is "required".

          Change the command group of the procedure using
          -command_group. Protect the contents of the procedure
          from being viewed by using -hide_body. Prevent further
          modifications to the procedure by using -permanent.
          Prevent abbreviation of the procedure by using
          -dont_abbrev.


EXAMPLES
          The following procedure adds two numbers together and
          returns the sum.  For demonstration purposes, unused
          arguments are defined.
               prompt> proc plus {a b} { return [expr $a + $b]}
               prompt> define_proc_attributes plus -info "Add two numbers" ? -define_args {
                 {a "first addend" a string required}
                 {b "second addend" b string required}
                 {"-verbose" "issue a message" "" boolean optional}}
               prompt> help -verbose plus
               Usage: plus    # Add two numbers
                   [-verbose]         (issue a message)
                   a                  (first addend)
                   b                  (second addend)
               prompt> plus 5 6
               11


SEE ALSO
          help(2), _p_a_r_s_e__p_r_o_c__a_r_g_u_m_e_n_t_s(_2), _p_r_o_c(_2),
          _s_h__c_o_m_m_a_n_d__a_b_b_r_e_v__m_o_d_e(_3).


v3.0      Synopsys Inc. 1988-1998. All rights reserved.       2-3