* Complicated Completions
@ 2003-08-26 0:18 David Remahl
2003-08-26 9:11 ` Oliver Kiddle
0 siblings, 1 reply; 4+ messages in thread
From: David Remahl @ 2003-08-26 0:18 UTC (permalink / raw)
To: zsh-workers
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: Complicated Completions
2003-08-26 0:18 Complicated Completions David Remahl
@ 2003-08-26 9:11 ` Oliver Kiddle
2003-08-28 19:50 ` David Remahl
0 siblings, 1 reply; 4+ messages in thread
From: Oliver Kiddle @ 2003-08-26 9:11 UTC (permalink / raw)
To: David Remahl; +Cc: zsh-workers
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: Complicated Completions
2003-08-26 9:11 ` Oliver Kiddle
@ 2003-08-28 19:50 ` David Remahl
2003-08-29 9:27 ` Oliver Kiddle
0 siblings, 1 reply; 4+ messages in thread
From: David Remahl @ 2003-08-28 19:50 UTC (permalink / raw)
To: Oliver Kiddle; +Cc: zsh-workers
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
>
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: Complicated Completions
2003-08-28 19:50 ` David Remahl
@ 2003-08-29 9:27 ` Oliver Kiddle
0 siblings, 0 replies; 4+ messages in thread
From: Oliver Kiddle @ 2003-08-29 9:27 UTC (permalink / raw)
To: David Remahl; +Cc: zsh-workers
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
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2003-08-29 9:25 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2003-08-26 0:18 Complicated Completions David Remahl
2003-08-26 9:11 ` Oliver Kiddle
2003-08-28 19:50 ` David Remahl
2003-08-29 9:27 ` Oliver Kiddle
Code repositories for project(s) associated with this public inbox
https://git.vuxu.org/mirror/zsh/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).