Complicated Completions

Complicated Completions

[David Remahl]

Hi. I'm new to the list - I did try to search the archives, but I'm  
afraid my question is of a more abstract kind.

I have spent some time trying to get to know the completion system. My  
aim is to create completion functions for some of the useful and  
surprisingly well-documented command line tools specific to Mac OS X  
(hdiutil, diskutil, defaults, SystemStarter, ditto to mention a few).  
The thing is, some of them use rather peculiar and complex command line  
syntaxes, so creating useful completions is quite a challenge.

I would like to request some guidance in creating a completion function  
for the hdiutil command. As you know, the documentation is thorough,  
but not very friendly to new developers, so I believe all I need is  
some help getting started.

I will begin by describing the command line syntax of hdiutil, using  
snippets from the man page.

SYNOPSIS
      hdiutil verb [options]

Verb is one of the following:
	attach, detach, verify, create, convert, burn, help, info, load,  
checksum, eject (synonym for detach), flatten, unflatten, imageinfo,  
mount (synonym for attach), mountvol, unmount, plugins,  
internet-enable, resize, segment, partition, makehybrid, pmap

The set of allowed options depends on the sub command (verb). All verbs  
accept the following optional options (duh), all mutually exclusive:
	-verbose
	-quiet
	-debug

Many verbs accept these options:
	-plist
	-srcimagekey <key>=<value>
	-tgtimagekey <key>=<value>
	-encryption [crypto method]
	-stdinpass
	-passphrase password
	-shadow [shadow file]

Many verbs take additional options that are specific to that verb. For  
example, convert takes the following additional arguments / options:
Required:
	imagefile (source file name)
	-format fmt (fmt is one of UDRW UFBI UDRO UDCO...DC42)
	-o dest (destination file name)
Optional:
	-align sector_alignment
	-segmentSize [sector count]
		or
	-segmentSize <??b|??k|??m|??g|??t??p|??e> like mkfile(8)

Several commands  
(attach|verify|compact|convert|burn|checksum|chpass|*flatten|fsid|image- 
info|internet-enable|resize|segment|partition|pmap) take exactly one  
filename argument - of a .dmg file. That corresponds to imagefile in  
teh above convert example.

Could someone outline how I would arrange the completion function for  
this command? The _ifconfig sample gave me some hints, but I'm having  
trouble extending it past the verb...

/ Rgds, David Remahl

Re: Complicated Completions

[Oliver Kiddle]

David Remahl wrote:

> I have spent some time trying to get to know the completion system. My  
> aim is to create completion functions for some of the useful and  
> surprisingly well-documented command line tools specific to Mac OS X  
> (hdiutil, diskutil, defaults, SystemStarter, ditto to mention a few).  

Sounds good.

> The thing is, some of them use rather peculiar and complex command line  
> syntaxes, so creating useful completions is quite a challenge.

There's a few other commands that follow a similar scheme. _sccs might
be a better example than _ifconfig. Also worth looking at are _xauth
and _cdcd which are simpler and _cvs which is more complicated.

> I will begin by describing the command line syntax of hdiutil, using  
> snippets from the man page.
> 
> SYNOPSIS
>       hdiutil verb [options]

Can any options appear between hdiutil and the verb? If so, begin with
an _arguments for those options finishing with a '*:: :->verbs' rule to
complete the sub commands in a state.

> Verb is one of the following:
> 	attach, detach, verify, create, convert, burn, help, info, load,  
> checksum, eject (synonym for detach), flatten, unflatten, imageinfo,  
> mount (synonym for attach), mountvol, unmount, plugins,  
> internet-enable, resize, segment, partition, makehybrid, pmap

Just completing those should be straight-forward. If you can use
_describe to give descriptions for them, that is better. For the
synonyms, give them the same description, e.g:
  {eject,detach}':description'
in zsh 4.1, they will then be grouped together.

What does the help verb output? You might be able to parse this to get
descriptions. If you get a recent _cvs from CVS, it does this.

Then follow the pattern of one of the examples:
  service="$words[1]"
  curcontext="${curcontext%:*}-$service:"

This puts the verb into $service and into the zstyle context (so you
will have, e.g. hdiutil-attach in the command part of the zstyle
context). Then, just have a case statement for each possible verb:
  case $service in
    attach)
      ...

> The set of allowed options depends on the sub command (verb). All verbs  
> accept the following optional options (duh), all mutually exclusive:
> 	-verbose
> 	-quiet
> 	-debug

Stick the _arguments specifcations for them in an array at the
beginning and include the array in all later calls to _arguments. e.g:

  args=(
    '(-quiet -debug)-verbose'
    '(-verbose -debug)-quiet'
    '(-quiet -verbose)-debug'
  )

then later, _arguments "$args[@]" \
The lists in parenthesis at the start of the specifications specifies
that they are mutually exclusive.

> Many verbs accept these options:
> 	-plist
> 	-srcimagekey <key>=<value>
> 	-tgtimagekey <key>=<value>
> 	-encryption [crypto method]
> 	-stdinpass
> 	-passphrase password
> 	-shadow [shadow file]

Again, put the specifications for those options in an array and use the
array with those sub-commands that need them.

> Many verbs take additional options that are specific to that verb. For  
> example, convert takes the following additional arguments / options:
> Required:

Specify these options in each branch of the case statement.

> Several commands  
> (attach|verify|compact|convert|burn|checksum|chpass|*flatten|fsid|image- 
> info|internet-enable|resize|segment|partition|pmap) take exactly one  
> filename argument - of a .dmg file. That corresponds to imagefile in  
> teh above convert example.

So they need an _arguments specification that looks like:
  '1:file:_files -g "*.dmg"'

Hope that helps

Oliver

Re: Complicated Completions

[David Remahl]

Thanks for your help!

I've now gotten started on something that I hope will work out...But  
why doesn't this work? I have only written a small part of the  
completion, for just the attach subcommand (verb). Try this:

type: hdiutil attach abc.dmg <tab>

Why doesn't it show the three switches -quiet, -debug and -verbose?

/ rgds, David Remahl

#compdef hdiutil

local opts args hdiverbs

_hdiutil_verbs ()
{
   local -a commands
   verbs=(
     {attach,mount}':attach (mount) an image'
     {detach,eject}':detach (eject) an image'
     'create:create a new image'
     'verify:verify image integrity'
     'convert:convert an image from one format to another'
     'burn:burn an image to optical media'
     'help:get help help on usage'
     'info:get information about an driver or mounted image'
     'load:manually load the image driver'
     'checksum:calculate image checksum'
     'flatten:flatten dual-fork image to single-fork'
     'unflatten:unflatten single-fork image to dual fork'
     'imageinfo:print information about an image file'
     'mountvol:mount a /dev node using disk arbitration'
     'unmount:unmount a mounted volume'
     'plugins:print information about plugins'
     'internet-enable:enable postprocessing for an image'
     'resize:attempt to resize HFS+ filesystem on UDIF image'
     'segment:segment NDIF or UDIF image'
     'partition:unknown verb'
     'makehybrid:create a hybrid version of an image'
     'pmap:display partition map from image or device'
     'compact:compact is undocumented'
     'fsid:fsid is undocumented'
     'chpass:chpass is undocumented'
   )
   _describe -t commands 'hdiutil verb' verbs
}

if (( CURRENT == 2 )); then
     _hdiutil_verbs
else
     local -a commonargs
     alwaysargs=(
       '(-quiet -debug)-verbose'
       '(-verbose -debug)-quiet'
       '(-quiet -verbose)-debug'
     )
     cmd="$words[2]"
     curcontext="${curcontext%:*:*}:xauth-${cmd}:"
     case "$cmd" in
         # sub-commands with no args
         help)
             _message 'no more arguments'
             ;;
	# sub-commands with image argument
	attach)
             if (( CURRENT == 3 )); then
                 _arguments \
                     '2:disk image file:_files -g  
"*.(dmg|img|smi|dmgz)"' && ret=0
             else
                 case "$cmd" in
                     attach)
                          _arguments \
                              '(-quiet -debug)-verbose'
                              '(-verbose -debug)-quiet'
                              '(-quiet -verbose)-debug' && ret=0
                          ;;
                 esac
             fi
	    ;;
     esac
fi


On den 26 augusti 2003, at 11:11:39AM, Oliver Kiddle wrote:

> David Remahl wrote:
>
>> I have spent some time trying to get to know the completion system. My
>> aim is to create completion functions for some of the useful and
>> surprisingly well-documented command line tools specific to Mac OS X
>> (hdiutil, diskutil, defaults, SystemStarter, ditto to mention a few).
>
> Sounds good.
>
>> The thing is, some of them use rather peculiar and complex command  
>> line
>> syntaxes, so creating useful completions is quite a challenge.
>
> There's a few other commands that follow a similar scheme. _sccs might
> be a better example than _ifconfig. Also worth looking at are _xauth
> and _cdcd which are simpler and _cvs which is more complicated.
>
>> I will begin by describing the command line syntax of hdiutil, using
>> snippets from the man page.
>>
>> SYNOPSIS
>>       hdiutil verb [options]
>
> Can any options appear between hdiutil and the verb? If so, begin with
> an _arguments for those options finishing with a '*:: :->verbs' rule to
> complete the sub commands in a state.
>
>> Verb is one of the following:
>> 	attach, detach, verify, create, convert, burn, help, info, load,
>> checksum, eject (synonym for detach), flatten, unflatten, imageinfo,
>> mount (synonym for attach), mountvol, unmount, plugins,
>> internet-enable, resize, segment, partition, makehybrid, pmap
>
> Just completing those should be straight-forward. If you can use
> _describe to give descriptions for them, that is better. For the
> synonyms, give them the same description, e.g:
>   {eject,detach}':description'
> in zsh 4.1, they will then be grouped together.
>
> What does the help verb output? You might be able to parse this to get
> descriptions. If you get a recent _cvs from CVS, it does this.
>
> Then follow the pattern of one of the examples:
>   service="$words[1]"
>   curcontext="${curcontext%:*}-$service:"
>
> This puts the verb into $service and into the zstyle context (so you
> will have, e.g. hdiutil-attach in the command part of the zstyle
> context). Then, just have a case statement for each possible verb:
>   case $service in
>     attach)
>       ...
>
>> The set of allowed options depends on the sub command (verb). All  
>> verbs
>> accept the following optional options (duh), all mutually exclusive:
>> 	-verbose
>> 	-quiet
>> 	-debug
>
> Stick the _arguments specifcations for them in an array at the
> beginning and include the array in all later calls to _arguments. e.g:
>
>   args=(
>     '(-quiet -debug)-verbose'
>     '(-verbose -debug)-quiet'
>     '(-quiet -verbose)-debug'
>   )
>
> then later, _arguments "$args[@]" \
> The lists in parenthesis at the start of the specifications specifies
> that they are mutually exclusive.
>
>> Many verbs accept these options:
>> 	-plist
>> 	-srcimagekey <key>=<value>
>> 	-tgtimagekey <key>=<value>
>> 	-encryption [crypto method]
>> 	-stdinpass
>> 	-passphrase password
>> 	-shadow [shadow file]
>
> Again, put the specifications for those options in an array and use the
> array with those sub-commands that need them.
>
>> Many verbs take additional options that are specific to that verb. For
>> example, convert takes the following additional arguments / options:
>> Required:
>
> Specify these options in each branch of the case statement.
>
>> Several commands
>> (attach|verify|compact|convert|burn|checksum|chpass|*flatten|fsid|imag 
>> e-
>> info|internet-enable|resize|segment|partition|pmap) take exactly one
>> filename argument - of a .dmg file. That corresponds to imagefile in
>> teh above convert example.
>
> So they need an _arguments specification that looks like:
>   '1:file:_files -g "*.dmg"'
>
> Hope that helps
>
> Oliver
>

Re: Complicated Completions

[Oliver Kiddle]

David Remahl wrote:
> Thanks for your help!
> 
> I've now gotten started on something that I hope will work out...But  
> why doesn't this work? I have only written a small part of the  
> completion, for just the attach subcommand (verb). Try this:
> 
> type: hdiutil attach abc.dmg <tab>
> 
> Why doesn't it show the three switches -quiet, -debug and -verbose?

_arguments looks at the $words array and expects to find the command
name in the first element and other arguments thereafter. So in this
case, you need to add:
  shift 2 words
  (( CURRENT-=2 ))
before the call to _arguments.

Is it not possible for the -quiet, -debug and -verbose options to
appear before the .dmg file on the command-line though?

If so, you should be able to use just:

  attach)
    shift words
    (( CURRENT-- ))
    _arguments \
       '(-quiet -debug)-verbose' \
       '(-verbose -debug)-quiet' \
       '(-quiet -verbose)-debug' \
       '1:disk image file:_files -g  "*.(dmg|img|smi|dmgz)"' && ret=0

  ;;

I you are wondering why _xauth and _sccs don't need to shift the words
array, it is because they they have a previous call to
_arguments with this rule:
       '*::command:->subcmd' && ret=0

And the documentation for *::MESSAGE:ACTION spec says:

          With two colons before the MESSAGE, the words special array
          and the CURRENT special parameter are modified to refer only
          to the normal arguments when the ACTION is executed or
          evaluated.


>      curcontext="${curcontext%:*:*}:xauth-${cmd}:"

don't forget to change xauth to hdiutil

>              if (( CURRENT == 3 )); then
>                  _arguments \
>                      '2:disk image file:_files -g "*.(dmg|img|smi|dmgz)"' && ret=0

If this does need to stay (if the switches can only be after the .dmg
file), then you can write it as:

  _wanted files expl 'disc image file' \
      _files -g "*.(dmg|img|smi|dmgz)" && ret=0

>                           _arguments \
>                               '(-quiet -debug)-verbose'
>                               '(-verbose -debug)-quiet'


Don't forget the backslash (\) at the end of each of these lines so
that it knows to continue on the next line. I expect you copied this
over from the alwaysargs array assignment where you don't need them.

Oliver