auto-auto-complete -- Autogenerate shell auto-completion scripts
****************************************************************

Copyright © 2014 Mattias Andrée

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Overview
********

auto-auto-complete provides a LISP-like (A sane alternative to using XML.) declarative language for creating auto-completion scripts for commands in a shell-agnostic way. The current version of auto-auto-complete can use such files to generate auto-completion scripts for the bash, zsh and fish shells.

auto-auto-complete's language limited in comparsion to for example raw auto-completion scripts for the bash shell, however it is well enough for most projects.

Invoking
********

auto-auto-complete recognises two options:

-o
--output OUTPUT_FILE
     Specifies the pathname of the generated file.

-s
-f
--file
--source SOURCE_FILE
     Specifies the pathname of the auto-auto-complete script.

Both of these options must be used. Additionally the shell that the generate file should be generated for must be specified; this is done by adding name of the shell as a stand-along argument, for example auto-auto-complete bash --output mycmd.bash --source mycmd.autocomplete

It is also possible to define variables that can be used the auto-auto-complete script. If you, for example, want to give the variable COMMAND the value mycmd, add the argument command=mycmd. It is also possible to define arrays, for example if you want the variable SRCOPT to be an array of the for values -s, -f, --source and --file, add the arguments srcopt=-s, srcopt=-f, srcopt=--source and srcopt=--file. It is not possible to have variable whose name begin with a dash (`-').

Syntax
******

auto-auto-complete uses a LISP-like free form syntax. Valid whitespace is normal blank space, horizontal tab space (Also know simply as tab.), carriage return (The first character in a new line in for example the HTTP protocol and in Window's encoding for new lines, it was the new line character in the classical Mac operating systems), line feed (new line) and form feed (new page). Comments can be started with either a semicolon (;) or a hash (#). Comments end at the next following new line, which may either be a carriage return, line feed or form feed. Comments cannot be started inside quotes.

The backslash character (\) can be used to force the following character to be parsed verbatim, this is called escaping. It is highly discourage to use this to escape new lines, especially if the new line encoding used in the document is carrige return–line feed, as that would only escape the carrige return. There is also a set of characters that have a special meaning when they are escaped:

a
     Audible bell character.

b
     Backspace character.

e
     Escape character.

f
     Form feed character.

n
     Line feed character.

r
     Carriage character.

t
     Horizontal tab space character.

v
     Vertical tab space character.

0
     Null character.

Quotes, either simple quotes (') or double quotes (") can be used to parse all character verbatim except backslash (\). A quote ends at the next quote character that is not escaped by a backslash (\) and is identical to the opening quote character. This is especially useful for escaping whitespace and round brackets.

The rest of this chapter will demonstrate how to write a script by example of ponysay (because it uses most of the syntax).

The first thing we do is to declare which command the script is for. We do this by creating the root brackets and put the name of the command as the first element.

     (ponysay)

However, ponysay has a very similar command called ponythink. It is sensible to let the same script be used for auto-complete for both commands, to do this we utilise that we can define variables when we invoke auto-auto-complete.

     ((value command))

Now when we compile this script we need invoke auto-auto-complete with either command=ponysay or command=ponythink. If we want ponysay to be used if we do not specify a value for COMMAND we instead write:

     ((value command ponysay))

Remember that we could give a variable multiple values. This can also be done here. However in this example we only want one value. For example, ((value var a b)) would generate (a b) if VAR has not been set.

ponysay recognises the options -h and --help for printing a summary of recognised options. These options does not take any arguments and hence are specified with (unargumented).

     ((value command ponysay)
       (unargumented (options -h --help)
                     (desc 'Show summary of options'))
     )

This only specifies that these option exists, if we also want the generated scripts to suggest --help we need to add (complete --help).

     ((value command ponysay)
       (unargumented (options -h --help)
                     (complete --help)
                     (desc 'Show summary of options'))
     )

Now that we have our first option, lets add a few others, to keep the example short, we will skip the most of the options.

     ((value command ponysay)
       (unargumented (options -h --help)
                     (complete --help)
                     (desc 'Show summary of options'))
       (unargumented (options -l --list)
                     (complete --list)
                     (desc 'List all MLP:FiM ponies'))
       (unargumented (options +l ++list)
                     (complete ++list)
                     (desc 'List all non-MLP:FiM ponies'))
       (unargumented (options -X --256-colours --256colours --x-colours)
                     (desc 'Use xterm colours'))
     )

Now (especially if we had added all options) we have many (unargumented) blocks. We can use (multiple) so we do not have to write unargumented so many times.

     ((value command ponysay)
       (multiple unargumented
         ((options -h --help) (complete --help)
          (desc 'Show summary of options'))
         ((options -l --list) (complete --list)
          (desc 'List all MLP:FiM ponies'))
         ((options +l ++list) (complete ++list)
          (desc 'List all non-MLP:FiM ponies'))
         ((options -X --256-colours --256colours --x-colours)
          (desc 'Use xterm colours'))
       )
     )

To keep this example short we will truncate this to:

     ((value command ponysay)
       (multiple unargumented ...) ;We have cut out the options.
     )

ponysay also have a number of options that does take an argument. We will add a few of them.

     ((value command ponysay)
       (multiple unargumented ...) ;We have cut out the options.
       (multiple argumented
         ((options -f --file --pony) (complete --file --pony)
          (desc 'Specify the pony that should printed'))
         ((options -b --bubble --balloon) (complete --balloon)
          (desc 'Specify message balloon style'))
         ((options -W --wrap) (complete --wrap)
          (desc 'Specify wrapping column'))
         ((options +c --colour) (complete --colour)
          (desc 'Specify colour of the balloon, balloon link and message'))
       )
     )

Just like ponysay --help prints --wrap COLUMN to indicate that the argument for --wrap is is an index of the column where the message printed by ponysay is wrapped, shells could display the text COLUMN as a placeholder for the next argument when you have typed --wrap. To enable this in shells that support it, we use (arg).

     ((value command ponysay)
       (multiple unargumented ...) ;We have cut out the options.
       (multiple argumented
         ((options -f --file --pony) (complete --file --pony) (arg PONY)
          (desc 'Specify the pony that should printed'))
         ((options -b --bubble --balloon) (complete --balloon) (arg STYLE)
          (desc 'Specify message balloon style'))
         ((options -W --wrap) (complete --wrap) (arg COLUMN)
          (desc 'Specify wrapping column)')
         ((options +c --colour) (complete --colour) (arg ANSI-COLOUR)
          (desc 'Specify colour of the balloon, balloon link and message'))
       )
     )

The next step now is to specify the type of argument the options want. To do this we use (files). The elements in (files) specify what type of file the shell should suggest. Multiple type can be used. Tehe recognsied ones are:

-0
     Do not suggest files, or do not suggest files of types specified after -0.

-a
     Suggest all files.

-f
     Suggest regular files and pipes.

-r
     Suggest regular files but not pipes.

-d
     Suggest directories.

-l
     Suggest symlinks. This is suggest by default, but -0 can be used to stop this.

-s
     Suggest sockets.

-D
     Suggest doors.

     ((value command ponysay)
       (multiple unargumented ...) ;We have cut out the options.
       (multiple argumented
         ((options -f --file --pony) (complete --file --pony) (arg PONY)
          (files -f)
          (desc 'Specify the pony that should printed'))
         ((options -b --bubble --balloon) (complete --balloon) (arg STYLE)
          (files -f)
          (desc 'Specify message balloon style'))
         ((options -W --wrap) (complete --wrap) (arg COLUMN)
          (files -0)
          (desc Specify wrapping column))
         ((options +c --colour) (complete --colour) (arg ANSI-COLOUR)
          (files -0)
          (desc 'Specify colour of the balloon, balloon link and message'))
       )
     )

(files) can also be used to specify patterns (using sh-globbing) for the filenames of the files to suggest. For example --pony in ponysay should only, in respect to files, suggest files that end with .pony.

     ((value command ponysay)
       (multiple unargumented ...) ;We have cut out the options.
       (multiple argumented
         ((options -f --file --pony) (complete --file --pony) (arg PONY)
          (files -f *.pony)
          (desc 'Specify the pony that should printed'))
         ((options -b --bubble --balloon) (complete --balloon) (arg STYLE)
          (files -f *.say)
          (desc 'Specify message balloon style'))
         ((options -W --wrap) (complete --wrap) (arg COLUMN)
          (files -0)
          (desc Specify wrapping column))
         ((options +c --colour) (complete --colour) (arg ANSI-COLOUR)
          (files -0)
          (desc 'Specify colour of the balloon, balloon link and message'))
       )
     )

For --balloon files ending with .say should be suggested if the completion is for ponysay, but for ponythink .think-files should be suggest. We can use (case) to select this based on the value of the first element in the root block, which is the name of the command.

     ((value command ponysay)
       (multiple unargumented ...) ;We have cut out the options.
       (multiple argumented
         ((options -f --file --pony) (complete --file --pony) (arg PONY)
          (files -f *.pony)
          (desc 'Specify the pony that should printed'))
         ((options -b --bubble --balloon) (complete --balloon) (arg STYLE)
          (files -f (case (ponysay *.say) (ponythink *.think)))
          (desc 'Specify message balloon style'))
         ((options -W --wrap) (complete --wrap) (arg COLUMN)
          (files -0)
          (desc Specify wrapping column))
         ((options +c --colour) (complete --colour) (arg ANSI-COLOUR)
          (files -0)
          (desc 'Specify colour of the balloon, balloon link and message'))
       )
     )

Another part of options with arguments is suggestions that are not based on filenames.

     ((value command ponysay)
       (multiple unargumented ...) ;We have cut out the options.
       (multiple argumented
         ((options -f --file --pony) (complete --file --pony) (arg PONY)
          (suggest pony-f) (files -f *.pony)
          (desc 'Specify the pony that should printed'))
         ((options -b --bubble --balloon) (complete --balloon) (arg STYLE)
          (suggest balloon)
          (files -f (case (ponysay *.say) (ponythink *.think)))
          (desc 'Specify message balloon style'))
         ((options -W --wrap) (complete --wrap) (arg COLUMN)
          (suggest wrap) (files -0)
          (desc Specify wrapping column))
         ((options +c --colour) (complete --colour) (arg ANSI-COLOUR)
          (files -0)
          (desc 'Specify colour of the balloon, balloon link and message'))
       )
       (suggestion pony-f)  ;We will fill this in later...
       (suggestion balloon) ;We will fill this in later...
       (suggestion wrap)    ;We will fill this in later...
     )

Lets cut out the options again to make this shorter.

     ((value command ponysay)
       (multiple unargumented ...) ;We have cut out the options.
       (multiple argumented ...)   ;We have cut out the options.
       (suggestion pony-f)  ;We will fill this in later...
       (suggestion balloon) ;We will fill this in later...
       (suggestion wrap)    ;We will fill this in later...
     )

Another part of ponysay is that it will take also argument that are not associated with an option make make a message it prints out of thiat.

     ((value command ponysay)
       (default (arg MESSAGE) (files -0) (suggest message)
        (desc 'Message spoken by the pony'))
       (multiple unargumented ...) ;We have cut out the options.
       (multiple argumented ...)   ;We have cut out the options.
       (suggestion message) ;We will fill this in later...
       (suggestion pony-f)  ;We will fill this in later...
       (suggestion balloon) ;We will fill this in later...
       (suggestion wrap)    ;We will fill this in later...
     )

A rather unusual part of ponysay is that it has variadic options. A variadic option is a option that takes all following arguments, unconditionally. For example, in ponysay you can write --ponies twilight trixie instead of --pony twilight --pony trixie. (variadic) is used to declare a variadic option. (bind) becomes interesting here; because ponysay's variadic options have non-variadic counterparts, it is pleasant to reuse the non-variadic options' configurations. (bind) will copy everything that is missing except (options) and (complete). In this example we will not use (complete) because we do not want variadic options to be suggest but we will use (desc) because we want to adjust the descriptions.

     ((value command ponysay)
       (default (arg MESSAGE) (files -0) (suggest message)
        (desc 'Message spoken by the pony'))
       (multiple unargumented ...) ;We have cut out the options.
       (multiple argumented ...)   ;We have cut out the options.
       (variadic (options --f --files --ponies) (bind -f)
                 (desc 'Specify the ponies that may be printed'))
       (suggestion message) ;We will fill this in later...
       (suggestion pony-f)  ;We will fill this in later...
       (suggestion balloon) ;We will fill this in later...
       (suggestion wrap)    ;We will fill this in later...
     )

Notice that we used -f for the element in (bind), this is because we want --f, --files and --ponies to have the same configurations (with exception for the description) as the -f option.

GNU Free Documentation License
******************************

     [file fdl.texinfo not included]