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