20230322
[shlib.git] / doc / UM.txt.zh_CN / 6.args程序参数.txt
blob5da6cc992515335b694b34d7281818f1cf3c6b1d
3 # arguments
4 ===========
6     argument is a general name of cmd line paramter. actually, there are some conception of argument.
7 @ argument, general name. it is usually seen in main function in c code. here means a paramter to program passed from cmd line.
8 @ option, it is another way to call argument. but option is optional, append or not append some argument. so, argument like '-h' is an feature option for program, and this type of argument is called option.
9 @ paramter, it's equal to argument, but it pay attension to the value of argument. if -f option is append to a cmd, it follows a string without '-' prefix, it's the value of -f option, and it is called paramter.
10 @ subcmd, it is in argument, but it it is not the meaning of option and paramter. generally, it is the first argument of program in cmd line. it is used to invoking subrouting or sub-feature of a program code.
13 # argument process
14 =================
16     linux shell script provide 2 type of method to do this.
17     first one, using builtin cmd getopts, $OPTARG is the paramter of option.
18 ```
19 while  getopts :f:vh opt; do
20                 case "$opt" in
21                         f)
22                         echo "-f $OPTARG"
23                         ;;
24                         v)
25                         ;;
26                         h)
27                         ;;
28         esac
29 done
30 ```
33 # optional paramter
34 ================
36     but it can not process option with or without paramter. the paramter for option is optional. it is improved like this.
37 ```
38 while  getopts :fvh opt; do
39         eval optstr=\${$OPTIND}
40         case "$opt" in
41                 f)
42                 echo -ne "param -f and its opt $OPTARG\n"
43                 
44                 if [[ -n $optstr && ${optstr:0:1} != '-' ]]; then
45                         echo -ne "param -f with its paramter $optstr\n"
46                         shift
47                 else
48                         echo -ne "param -f without paramter."
49                 fi
50                 ;;
51         esac
52 done
53 ```
55     another way to implement it, is using getopt cmd. it support ' :: ' operation, treat option with '::' followed as a paramter optional option. and getopt support long option with '--' prefix.
56 ```
57         #
58         # paramter format translating.
59         #  --long=a => --long a
60         #
61         ARGS="getopt -o f::vh -l file,version, -- $@"
62         ARGS=`eval $ARGS`
63         
64         # exit if failed
65         if [[ $? != 0 ]]; then
66                 err "Fail to get args.\n"
67                 exit 1
68         fi
70         # trimp arguments
71         eval set -- ${ARGS}
72         
73         # option dispatcher
74         for ((i=0; i < 1000 ; i++)) do
75                 case "$1" in
76                         -- )
77 #                       dbgout "param --\n"
78                         general_param="$@"
79                         break
80                         ;;
81                 easc
82         done
83 ```
84     
85     
86 # proc of args.shlib
87 ================
89     in args.shlib, it define args info like this formated string.
90 ```
91 usage_desc_str_syntax="
92 prog $0 '<prog_desc>'
93 param -<pchar> --<long-opt> ---<cmd-opt> =<value> %<pname> !<pproc> '<pdesc-str>'
94                                                                 '<pdesc-str2>'
96 ```
97     for this syntax
98 @ pchar, short option char.
99 @ long-opt, long option string.
100 @ cmd-opt, sub-cmd option.
101 @ value, paramter name string, displayed follow the option argument. if the paramter is neccisory, use []. if it is optional for this option, use <>.
102 @ pname, paramter store paramter into this environment variable.
103 @ pproc, process function name for this option.
104 @ pdesc-str, describe string for this option. if the string is too long to display on console, it would be truncated to several lines to display.
105 @ pdesc-str2, describe string continued with last option describe string. it is not the line seperator for actual display.
107     here is the example:
109 usage_desc_str="
110 prog $0 'helpertesting program'
111 param -f --file ---file =[file_module] %<file> !<param_file> 'optional option to specify a file name that used '
112                                                  'for processing. and this is the describe string in'
113                                                  'second line.ÕâÀï¿ÉÒÔʹÓÃutf8×Ö·ûÏÔʾ£¬¿í¶È'
114                                                  '¸ù¾ÝÖÐÎÄ×Ö·û×Ô¶¯Æ¥Åä.'
115 param -h --help ---help = %<help> !<opt_proc_help>        'help information.'
116 param -h --help ---help = %<help> !<opt_proc_help>        'help information.'
118 main ()
120     ProgOptDispatch "$@"
121     
122     # todo:
125     the benifit of args.shlib is that:
126 @ it describe option, option param, option proc function, option describe string together.
127 @ it will be less mistake between helper description and actual code implement.
128 @ put paramter value of option to environment variable automatically.
129 @ invoke proc function if specified in describe string.
130 @ display describe string is aligned automatically. event if there are char encoded by utf8.
131     for auto-align in CJK char, the string is translatrd utf8 string to gbk string, and a gbk char is 2 byte width, so string lenth is the display width of the string. but it coast more cpu resource to do that.
132     
134 # future
135 =======
137     the process of argument dispatch coast more cpu resource, it should be improved.
138     argument describe string dspatch function should be improved with [[ $xx =~ xxx ]], by using regular expression. but it canbe only used In bash shell.