diff options
Diffstat (limited to 'tools')
| -rw-r--r-- | tools/completion/README.md | 185 |
1 files changed, 181 insertions, 4 deletions
diff --git a/tools/completion/README.md b/tools/completion/README.md index 2dbdbb5d..f33965e9 100644 --- a/tools/completion/README.md +++ b/tools/completion/README.md @@ -1,7 +1,12 @@ -Completion -======================== +# Completion -### bash completion +This page explains completion for gobgp client. + +## Bash completion + +The described how to use and how to customize of bash completion. + +### How to use 1. install bash-completion as follows: @@ -24,9 +29,181 @@ Completion You can use tab completion for gobgp after loading gobgp-completion.bash. +### How to customize + In order to customize the bash completion, please follow steps below: + +1. generate bash completion file + Generate the bash completion file by using binary of gobgp client. + This generating function uses [cobra bash completion](https://github.com/spf13/cobra#generating-bash-completions-for-your-command) internally. + ``` + % gobgp --gen-cmpl --bash-cmpl-file=<specifying a file name> + ``` -### zsh completion + The following function is generated if added the "gobgp neighbor" command to gobgp client. + + ``` + _gobgp_neighbor() + { + last_command="gobgp_neighbor" + commands=() + + flags=() + two_word_flags=() + flags_with_completion=() + flags_completion=() + + flags+=("--bash-cmpl-file=") + flags+=("--debug") + flags+=("-d") + flags+=("--gen-cmpl") + flags+=("-c") + flags+=("--host=") + two_word_flags+=("-u") + flags+=("--json") + flags+=("-j") + flags+=("--port=") + two_word_flags+=("-p") + flags+=("--quiet") + flags+=("-q") + + must_have_one_flag=() + must_have_one_noun=() + } + ``` + +1. copy the generated functions + + Copy the above function to **gogbp-static-completion.bash**. + +1. implement a dynamic completion + + If you want to add dynamic completion, you need to implement that part yourself. + For example, if you want to add the neighbor address after the "gobgp neighbor" command dynamically, you can achieve it by implementing the specific internal command in **gobgp-dynamic-completion.bash**. + + 1. implement command to get a list of the neighbor address + + You need to add the processing function of the following like below to **gobgp-dynamic-completion.bash**. + ``` + # Get bgp neighbors by using gobgp command. + __gobgp_q_neighbor() + { + local neighbors=( $(__gobgp_q $url $port --quiet neighbor) ) + case "${neighbors[*]}" in + "grpc: timed out"* | "rpc error:"* ) + req_faild="True" + return + ;; + esac + for n in ${neighbors[*]}; do + commands+=($n) + done + searched="True" + } + ``` + + 1. add a call to "__gobgp_q_neighbor" + + You can call the above functions by implementing as follows to **gobgp-static-completion.bash**: + ``` + _gobgp_neighbor() + { + last_command="gobgp_neighbor" + commands=() + + flags=() + two_word_flags=() + flags_with_completion=() + flags_completion=() + + flags+=("--bash-cmpl-file=") + flags+=("--debug") + flags+=("-d") + flags+=("--gen-cmpl") + flags+=("-c") + flags+=("--host=") + two_word_flags+=("-u") + flags+=("--json") + flags+=("-j") + flags+=("--port=") + two_word_flags+=("-p") + flags+=("--quiet") + flags+=("-q") + + must_have_one_flag=() + must_have_one_noun=() + + # Implement call processing to here + __gobgp_q_neighbor + } + ``` + + 1. implement the handle processing + + If you want to add the completion following the "gobgp neighbor \<neighbor address\>" command, you need to add a handler for _gobgp_neighbor_addr() like below to "__handle_gobgp_command()" function in **gobgp-dynamic-completion.bash**. + + ``` + case "${last_command}" in + # Control after dynamic completion of bgp neighbor command + gobgp_neighbor ) + next_command="_${last_command}_addr" + ;; + esac + ``` + + "next_command" variable above indicates a function to be called after "gobgp neighbor", and the function name of next command is supposed to be "_gobgp_neighbor_addr" in the example above. + Therefore the actual "gobgp_neighbor_addr" function needs to be implemented in **gobgp-dynamic-completion.bash**. + ``` + _gobgp_neighbor_addr() + { + last_command="gobgp_neighbor_addr" + + commands=() + commands+=("local") + commands+=("adj-in") + commands+=("adj-out") + commands+=("reset") + commands+=("softreset") + commands+=("softresetin") + commands+=("softresetout") + commands+=("shutdown") + commands+=("enable") + commands+=("disable") + commands+=("policy") + + flags=() + two_word_flags=() + flags_with_completion=() + flags_completion=() + + flags+=("--address-family=") + two_word_flags+=("-a") + flags+=("--bash-cmpl-file=") + flags+=("--debug") + flags+=("-d") + flags+=("--gen-cmpl") + flags+=("-c") + flags+=("--host=") + two_word_flags+=("-u") + flags+=("--json") + flags+=("-j") + flags+=("--port=") + two_word_flags+=("-p") + flags+=("--quiet") + flags+=("-q") + + must_have_one_flag=() + must_have_one_noun=() + } + ``` + +1. delete the generated bash completion file. + +## Zsh completion + +The described how to use of bash completion. + +### How to use zsh completion for gobgp works by adding the path of gobgp zsh completion directory to $fpath and enabling zsh completion like below: |