github.com/osrg/gobgp/v3@v3.30.0/tools/completion/README.md (about)

     1  # Completion
     2  
     3  This page explains completion for gobgp client.
     4  
     5  ## Bash completion
     6  
     7  The described how to use and how to customize of bash completion.
     8  
     9  ### How to use
    10  
    11  1. install bash-completion as follows:
    12  
    13      ```bash
    14      $ sudo apt-get install bash-completion
    15      ```
    16  
    17  1. load completion file
    18  
    19      ```bash
    20      $ git clone https://github.com/osrg/gobgp
    21      $ source gobgp/tools/completion/gobgp-completion.bash
    22      ```
    23  
    24  You can use tab completion for gobgp after loading gobgp-completion.bash.
    25  
    26  ### How to customize
    27  
    28  In order to customize the bash completion, please follow steps below:
    29  
    30  1. generate bash completion file
    31  
    32      Generate the bash completion file by using binary of gobgp client.
    33      This generating function uses
    34      [cobra bash completion](https://github.com/spf13/cobra#generating-bash-completions-for-your-command)
    35      internally.
    36  
    37      ```bash
    38      % gobgp --gen-cmpl --bash-cmpl-file=<specifying a file name>
    39      ```
    40  
    41      The following function is generated if added the "gobgp neighbor" command
    42      to gobgp client.
    43  
    44      ```bash
    45      _gobgp_neighbor()
    46      {
    47          last_command="gobgp_neighbor"
    48          commands=()
    49  
    50          flags=()
    51          two_word_flags=()
    52          flags_with_completion=()
    53          flags_completion=()
    54  
    55          flags+=("--bash-cmpl-file=")
    56          flags+=("--debug")
    57          flags+=("-d")
    58          flags+=("--gen-cmpl")
    59          flags+=("-c")
    60          flags+=("--host=")
    61          two_word_flags+=("-u")
    62          flags+=("--json")
    63          flags+=("-j")
    64          flags+=("--port=")
    65          two_word_flags+=("-p")
    66          flags+=("--quiet")
    67          flags+=("-q")
    68  
    69          must_have_one_flag=()
    70          must_have_one_noun=()
    71      }
    72      ```
    73  
    74  1. copy the generated functions
    75  
    76      Copy the above function to **gogbp-static-completion.bash**.
    77  
    78  1. implement a dynamic completion
    79  
    80      If you want to add dynamic completion, you need to implement that part
    81      yourself.
    82      For example, if you want to add the neighbor address after the "gobgp
    83      neighbor" command dynamically, you can achieve it by implementing the
    84      specific internal command in **gobgp-dynamic-completion.bash**.
    85  
    86  1. implement command to get a list of the neighbor address
    87  
    88      You need to add the processing function of the following like below to
    89      **gobgp-dynamic-completion.bash**.
    90  
    91      ```bash
    92      # Get bgp neighbors by using gobgp command.
    93      __gobgp_q_neighbor()
    94      {
    95          local neighbors=( $(__gobgp_q $url $port --quiet neighbor) )
    96          case "${neighbors[*]}" in
    97              "grpc: timed out"* | "rpc error:"* )
    98                  req_faild="True"
    99                  return
   100              ;;
   101          esac
   102          for n in ${neighbors[*]}; do
   103              commands+=($n)
   104          done
   105          searched="True"
   106      }
   107      ```
   108  
   109  1. add a call to "__gobgp_q_neighbor"
   110  
   111      You can call the above functions by implementing as follows to
   112      **gobgp-static-completion.bash**:
   113  
   114      ```bash
   115      _gobgp_neighbor()
   116      {
   117          last_command="gobgp_neighbor"
   118          commands=()
   119  
   120          flags=()
   121          two_word_flags=()
   122          flags_with_completion=()
   123          flags_completion=()
   124  
   125          flags+=("--bash-cmpl-file=")
   126          flags+=("--debug")
   127          flags+=("-d")
   128          flags+=("--gen-cmpl")
   129          flags+=("-c")
   130          flags+=("--host=")
   131          two_word_flags+=("-u")
   132          flags+=("--json")
   133          flags+=("-j")
   134          flags+=("--port=")
   135          two_word_flags+=("-p")
   136          flags+=("--quiet")
   137          flags+=("-q")
   138  
   139          must_have_one_flag=()
   140          must_have_one_noun=()
   141  
   142          # Implement call processing to here
   143          __gobgp_q_neighbor
   144      }
   145      ```
   146  
   147  1. implement the handle processing
   148  
   149      If you want to add the completion following the "gobgp neighbor \<neighbor
   150      address\>" command, you need to add a handler for _gobgp_neighbor_addr()
   151      like below to "__handle_gobgp_command()" function in
   152      **gobgp-dynamic-completion.bash**.
   153  
   154      ```bash
   155      case "${last_command}" in
   156          # Control after dynamic completion of bgp neighbor command
   157          gobgp_neighbor )
   158              next_command="_${last_command}_addr"
   159          ;;
   160      esac
   161      ```
   162  
   163      "next_command" variable above indicates a function to be called after
   164      "gobgp neighbor", and the function name of next command is supposed to be
   165      "_gobgp_neighbor_addr" in the example above.
   166       Therefore the actual "gobgp_neighbor_addr" function needs to be
   167       implemented in **gobgp-dynamic-completion.bash**.
   168  
   169      ```bash
   170      _gobgp_neighbor_addr()
   171      {
   172          last_command="gobgp_neighbor_addr"
   173  
   174          commands=()
   175          commands+=("local")
   176          commands+=("adj-in")
   177          commands+=("adj-out")
   178          commands+=("reset")
   179          commands+=("softreset")
   180          commands+=("softresetin")
   181          commands+=("softresetout")
   182          commands+=("shutdown")
   183          commands+=("enable")
   184          commands+=("disable")
   185          commands+=("policy")
   186  
   187          flags=()
   188          two_word_flags=()
   189          flags_with_completion=()
   190          flags_completion=()
   191  
   192          flags+=("--address-family=")
   193          two_word_flags+=("-a")
   194          flags+=("--bash-cmpl-file=")
   195          flags+=("--debug")
   196          flags+=("-d")
   197          flags+=("--gen-cmpl")
   198          flags+=("-c")
   199          flags+=("--host=")
   200          two_word_flags+=("-u")
   201          flags+=("--json")
   202          flags+=("-j")
   203          flags+=("--port=")
   204          two_word_flags+=("-p")
   205          flags+=("--quiet")
   206          flags+=("-q")
   207  
   208          must_have_one_flag=()
   209          must_have_one_noun=()
   210      }
   211      ```
   212  
   213  1. delete the generated bash completion file.
   214  
   215  ## Zsh completion
   216  
   217  The described how to use of bash completion.
   218  
   219  ### How to use
   220  
   221  zsh completion for gobgp works by adding the path of gobgp zsh completion
   222  directory to $fpath and enabling zsh completion like below:
   223  
   224  ```bash
   225  % vi ~/.zshrc
   226  
   227  GOBGP_COMP=$HOME/gobgp/tools/completion/zsh
   228  fpath=($GOBGP_COMP $fpath)
   229  
   230  autoload -Uz compinit
   231  compinit
   232  ```