Home | History | Annotate | Download | only in gflags
      1 // Copyright (c) 2008, Google Inc.
      2 // All rights reserved.
      3 //
      4 // Redistribution and use in source and binary forms, with or without
      5 // modification, are permitted provided that the following conditions are
      6 // met:
      7 //
      8 //     * Redistributions of source code must retain the above copyright
      9 // notice, this list of conditions and the following disclaimer.
     10 //     * Redistributions in binary form must reproduce the above
     11 // copyright notice, this list of conditions and the following disclaimer
     12 // in the documentation and/or other materials provided with the
     13 // distribution.
     14 //     * Neither the name of Google Inc. nor the names of its
     15 // contributors may be used to endorse or promote products derived from
     16 // this software without specific prior written permission.
     17 //
     18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
     20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
     21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
     22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
     24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
     25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
     26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
     27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     29 //
     30 // ---
     31 // Author: Dave Nicponski
     32 //
     33 // Implement helpful bash-style command line flag completions
     34 //
     35 // ** Functional API:
     36 // HandleCommandLineCompletions() should be called early during
     37 // program startup, but after command line flag code has been
     38 // initialized, such as the beginning of HandleCommandLineHelpFlags().
     39 // It checks the value of the flag --tab_completion_word.  If this
     40 // flag is empty, nothing happens here.  If it contains a string,
     41 // however, then HandleCommandLineCompletions() will hijack the
     42 // process, attempting to identify the intention behind this
     43 // completion.  Regardless of the outcome of this deduction, the
     44 // process will be terminated, similar to --helpshort flag
     45 // handling.
     46 //
     47 // ** Overview of Bash completions:
     48 // Bash can be told to programatically determine completions for the
     49 // current 'cursor word'.  It does this by (in this case) invoking a
     50 // command with some additional arguments identifying the command
     51 // being executed, the word being completed, and the previous word
     52 // (if any).  Bash then expects a sequence of output lines to be
     53 // printed to stdout.  If these lines all contain a common prefix
     54 // longer than the cursor word, bash will replace the cursor word
     55 // with that common prefix, and display nothing.  If there isn't such
     56 // a common prefix, bash will display the lines in pages using 'more'.
     57 //
     58 // ** Strategy taken for command line completions:
     59 // If we can deduce either the exact flag intended, or a common flag
     60 // prefix, we'll output exactly that.  Otherwise, if information
     61 // must be displayed to the user, we'll take the opportunity to add
     62 // some helpful information beyond just the flag name (specifically,
     63 // we'll include the default flag value and as much of the flag's
     64 // description as can fit on a single terminal line width, as specified
     65 // by the flag --tab_completion_columns).  Furthermore, we'll try to
     66 // make bash order the output such that the most useful or relevent
     67 // flags are the most likely to be shown at the top.
     68 //
     69 // ** Additional features:
     70 // To assist in finding that one really useful flag, substring matching
     71 // was implemented.  Before pressing a <TAB> to get completion for the
     72 // current word, you can append one or more '?' to the flag to do
     73 // substring matching.  Here's the semantics:
     74 //   --foo<TAB>     Show me all flags with names prefixed by 'foo'
     75 //   --foo?<TAB>    Show me all flags with 'foo' somewhere in the name
     76 //   --foo??<TAB>   Same as prior case, but also search in module
     77 //                  definition path for 'foo'
     78 //   --foo???<TAB>  Same as prior case, but also search in flag
     79 //                  descriptions for 'foo'
     80 // Finally, we'll trim the output to a relatively small number of
     81 // flags to keep bash quiet about the verbosity of output.  If one
     82 // really wanted to see all possible matches, appending a '+' to the
     83 // search word will force the exhaustive list of matches to be printed.
     84 //
     85 // ** How to have bash accept completions from a binary:
     86 // Bash requires that it be informed about each command that programmatic
     87 // completion should be enabled for.  Example addition to a .bashrc
     88 // file would be (your path to gflags_completions.sh file may differ):
     89 
     90 /*
     91 $ complete -o bashdefault -o default -o nospace -C                        \
     92  '/usr/local/bin/gflags_completions.sh --tab_completion_columns $COLUMNS' \
     93   time  env  binary_name  another_binary  [...]
     94 */
     95 
     96 // This would allow the following to work:
     97 //   $ /path/to/binary_name --vmodule<TAB>
     98 // Or:
     99 //   $ ./bin/path/another_binary --gfs_u<TAB>
    100 // (etc)
    101 //
    102 // Sadly, it appears that bash gives no easy way to force this behavior for
    103 // all commands.  That's where the "time" in the above example comes in.
    104 // If you haven't specifically added a command to the list of completion
    105 // supported commands, you can still get completions by prefixing the
    106 // entire command with "env".
    107 //   $ env /some/brand/new/binary --vmod<TAB>
    108 // Assuming that "binary" is a newly compiled binary, this should still
    109 // produce the expected completion output.
    110 
    111 
    112 #ifndef GOOGLE_GFLAGS_COMPLETIONS_H_
    113 #define GOOGLE_GFLAGS_COMPLETIONS_H_
    114 
    115 namespace google {
    116 
    117 void HandleCommandLineCompletions(void);
    118 
    119 }
    120 
    121 #endif  // GOOGLE_GFLAGS_COMPLETIONS_H_
    122