From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 18016 invoked from network); 1 Aug 2001 06:59:57 -0000 Received: from sunsite.dk (130.225.51.30) by ns1.primenet.com.au with SMTP; 1 Aug 2001 06:59:57 -0000 Received: (qmail 9772 invoked by alias); 1 Aug 2001 06:59:47 -0000 Mailing-List: contact zsh-workers-help@sunsite.dk; run by ezmlm Precedence: bulk X-No-Archive: yes X-Seq: 15554 Received: (qmail 9756 invoked from network); 1 Aug 2001 06:59:42 -0000 Message-ID: <20010801065937.52572.qmail@web10407.mail.yahoo.com> Date: Tue, 31 Jul 2001 23:59:37 -0700 (PDT) From: Felix Rosencrantz Subject: XML version of completion function To: zsh-workers MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="0-969153482-996649177=:52106" --0-969153482-996649177=:52106 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Here are some first drafts of a couple XML examples based on the _zip & _find files. While I haven't done it, it seems to me that it wouldn't be difficult to use these files to generate equivalent versions of the existing _zip & _find files. These files becomes more readable in an XML viewer that can collapse elements (e.g. emacs?, gxmlviewer, IBM's XML viewer). Though several of these have some difficulty showing the help text in a useful manor. Some of the features in this draft: *) The ability to specify language for descriptions/explanations using the xml:lang attribute. *) The ability to add documentation from the man page of zip and zsh. The _arguments specific flag documentation, and help on the zip options. *) Ability to specify other completions, such as for the ZIPOPT environment variable. Though this hasn't really been thought out, not quite sure how the completion function would be generated based on this format. Some things missing that I wanted to add *) Ability to reuse exclusion groups. Make a definition and then reuse it for all the options. *) Reuse a set of flags with a small set of edits. Not all of zip's flags can be used with ZIPOPT, there should be an easy way to take a set of flags an delete/add some. *) More of the options (!+=- etc.) that can be placed in the optspecs. *) Ability to specify compdef options. *) Show equivalent flags. Some of the things I like about this format: *) Appropriate documentation can be inserted at the place where you need it. Whether it be zsh-specific or command-specific. Also, it leaves open additional sources of documentation such as the file's author (i.e. comments.) *) I think it is straight forward to convert this file into zsh scripts. (Though, it might take a little XSL work. ) The structure of the xml is strongly tied to the _arguments format, Also it is tied to some extent to the completion file format, though I haven't done survey of common file structures, if there is such a thing. *) There is a mechanism for handling non-declarative parts (i.e. code blocks). Some of the things I don't like about this format: *) The xml is about 14 times the size of the shell version in the case of _zip. *) Missing stuff to handle repeated information, such as exclusion lists. *) More difficult to comprehend what is happening without an XML editor. And even with that, pertinent information takes some work to find. My original goal was to make it easier to create new functions. So the next thing I would like to do is markup the usage output from a command. I'd like that format to be easy to modify by hand, and then taking that hand edit and transform it into the format I've shown for _find and _zip. I'll try to send that out next week. Does this seem useful, yet? Any suggestions for making it better? -FR. __________________________________________________ Do You Yahoo!? Make international calls for as low as $.04/minute with Yahoo! Messenger http://phonecard.yahoo.com/ --0-969153482-996649177=:52106 Content-Type: text/xml; name="find.xml" Content-Description: find.xml Content-Disposition: inline; filename="find.xml" _find maximum search depth minimum search depth access time (minutes) inode change time (minutes) modification time (minutes) access time (days) inode change time (days) modification time (days) file to compare (access time) _files file to compare (inode change time) _files file to compare (modification time) _files access after inode change (days) filesystem type ufs 4.2 4.3 nfs tmp mfs S51K S52K numeric group ID group _groups numeric user ID user _users link pattern to search link pattern to search (case insensitive) name pattern to search name pattern to search (case insensitive) path pattern to search path pattern to search (case insensitive) regular expression to search regular expression to search (case insensitive) inode number number of links file permission bits file size file type b block special file c character special file d directory p named pipe f normal file l symbolic link s socket file type b block special file c character special file d directory p named pipe f normal file l symbolic link s socket program _command_names -e \; program arguments _normal program _command_names -e \; program arguments _normal output file _files output file _files output file _files output file _files output format output format directory _files -/ --0-969153482-996649177=:52106 Content-Type: text/xml; name="zip.xml" Content-Description: zip.xml Content-Disposition: inline; filename="zip.xml" _zip local suffixes suf zipfile izip local expl curcontext="$curcontext" state line typeset -A opt_args ZIPOPT The argoption elements are used to specify the flags that _arguments takes. If the "use" attribute is set to "false" this argoption will not be generated. -A With -A, no options will be completed after the first non-option argument on the line. The -A has to be followed by a pattern matching all strings which are not to be taken as arguments. For example, to make _arguments stop completing options after the first normal argument, but ignoring all strings starting with a hyphen even if they are not described by one of the optspecs, one would use: `-A "-*"'. -C The option -C can be given to make _arguments modify the curcontext parameter when an action of the form `->state' is used. This parameter is used to keep track of the current context and in this case it (and not the parameter context as explained above) has to be made local to make sure that calling functions don't use the modified value. -O This flag takes one argument like `-O name'. The name will be taken as the name of an array and its elements will be given to functions called to generate matches when execut­ ing the actions. For example, this allows one to give options for the compadd builtin that should be used for all actions. -R The function returns with a non-zero return value if the cursor is not in a position where options can be completed or if the current word could not be completed to an option. But if the -R option is given to _arguments, the function will instead return with a return value of 300 (to make it distinguishable from other return values) after setting the global `context', `line' and `opt_args' parameters, and without resetting any changes made to the special parameters such as PREFIX and words. This enables wrapper functions around _arguments to be able to find out if they have to make sure that the special completion parameters are not reset when they return. -w Used with the"-s" flag to say that more option characters are to be expected even after an option that takes an argument. For example, if a command takes the options `a' and `b', where `a' takes an argument in the next word, _arguments would normally not complete the other option directly after `-a', but it would allow that if given the -w option. -s Option names represented by optname are normally taken to be multi-character names, and a word from the line is considered to contain only one option (or none). By giving the -s option to _arguments before the first spec, each optname is considered to be a single character and each word from the line may contain more than one such option letter. However, words beginning with two hyphens (like `--prefix') are still considered to contain only one option name. This allows the use of the `-s' option to describe single-letter options together with such long option names. The -s option can be combined with the "-w" or "-W" option. -W Similarly, the option -W may be given together with -s to force completion of sin­ gle-letter options even after options that get an argument in the same word. For exam­ ple, if a command takes the options `a' and `b', where `a' needs an argument in the same word, directly after the option character, _arguments would normally only execute the action for that argument and not offer other single-letter options as possible comple­ tions. If given the -W option, it will offer other options as possible completions after executing the action for the argument. Note that, depending on the action, this may mean that the other options can't really be completed, but at least they will be listed. For more control, use an utility function like _guard in the argument's action. -M The -M option followed by a string may be given before the first description. The string will be used as the match specification when completing option names and values instead of the default `r:|[_-]=* r:|=*'. -S With -S, no option will be completed after a `--' on the line and this argument will otherwise be ignored. freshen: only changed files delete entries in zipfile recurse into directories quiet operation add one-line comments use "path" for temp file path for temporary archive _files -/ read names from stdin fix zipfile try harder to fix zipfile adjust self-extracting exe test zipfile integrity store symbolic links as the link instead of the referenced file encrypt show help update: only changed or new files move into zipfile (delete files) allow growing existing zipfile junk: do not record directory names convert LF to CR LF convert CR LF to LF display license verbose operation/print version info add zipfile comment only do files after or at "mmddyyyy" mmddyyyy only do files before "mmddyyyy" mmddyyyy make zipfile as old as latest entry do not add directory entries junk zip file prefix (unzipsfx) eXclude eXtra file attributes specify suffixes of files not to be compressed suffixes ->suffixes -1 -2 -3 -4 -5 -6 -7 -8 -9 store only -0 -2 -3 -4 -5 -6 -7 -8 -9 compress faster -0 -1 -3 -4 -5 -6 -7 -8 -9 -0 -1 -2 -4 -5 -6 -7 -8 -9 -0 -1 -2 -3 -5 -6 -7 -8 -9 -0 -1 -2 -3 -4 -6 -7 -8 -9 -0 -1 -2 -3 -4 -5 -7 -8 -9 -0 -1 -2 -3 -4 -5 -6 -8 -9 -0 -1 -2 -3 -4 -5 -6 -7 -9 -0 -1 -2 -3 -4 -5 -6 -7 -8 compress better exclude the following names include only the following names -f -d -R -q -c -b -@ -F -FF -A -T -y -e -h -u -m -g -j -l -ll -L -v -z -t -tt -o -D -J -X -n -0 -1 -2 -3 -4 -5 -6 -7 -8 -9 zip file _files -g '(#i)*.(zip|[jw]ar)' file ->files && return 0 C s -f -u -l -t -z -d extract files to pipe -p -u -l -t -z freshen existing files; create none -p -f -l -t -z update files; create if necessary -p -f -u -t -z -d list files -p -f -u -l -z -d test compressed archive data -p -f -u -l -t -d display archive comment -p -l -t -z specify directory to extract files to directory _files -/ -p -l -t -z -o never overwrite existing files -p -l -t -z -n overwrite files without prompting -p -l -t -z junk paths (don't make directories) match filenames case-insensitively -p -l -t -z restore UID/GID info quiet quieter -l -t -z auto-convert any text files -l -t -z treat all files as text verbose/display version info -p -z lowercase (some) filenames page output exclude the following names -p -f -u -l -t -z -n -o -j -C -X -q -qq -a -aa -v -L -M zip file _files -g '(#i)*.(zip|[jw]ar)' file ->files && return 0 C s -2 -s -m -l -v -h -t -T -z filenames only -1 -s -m -l -v -T just filenames but allow -h/-t/-z -1 -2 -m -l -v -h -t short format -1 -2 -s -l -v -h -t medium format -1 -2 -s -m -v -h -t long format -1 -2 -s -m -l -h -z verbose, multi-page format -1 -s -m -l -v print header line -1 -v print zipfile comment match filenames case-insensitively -1 -s -m -l print totals -1 -2 use sortable decimal format for file times page output exclude the following names -1 -2 -s -m -l -v -h -z -C -t -T -M zip file _files -g '(#i)*.(zip|[jw]ar)' file ->files && return 0 suffixes files --0-969153482-996649177=:52106--