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 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 '/home/build/eng/bash/bash_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 GFLAGS_COMPLETIONS_H_ 113#define GFLAGS_COMPLETIONS_H_ 114 115namespace @GFLAGS_NAMESPACE@ { 116 117extern void HandleCommandLineCompletions(void); 118 119} 120 121#endif // GFLAGS_COMPLETIONS_H_ 122