Some documentation questions

What exactly is a plugin?

In this framework there are three organizational concepts for the code. There are command scripts that actually make the project usable. Then there are modules, more or less libraries that can be loaded and then used by command scripts. If so, what exactly are plugins? Is there an example plugin in the code?

Ansewr: A plugin is a folder that contains scripts and libraries as defined in the README. The commands should be exposed to the go-script and be usable like normal commands. The libraries in the plugin can be used by the plugin commands. These libraries can be named similar to other, non-plugin libraries and they will be used instead. The plugin is supposed to allow for plug-n-play functionality being added to the go-script via 3rd parties.

If I have a group of commands under scripts/project.d/, eg build and install, and I need some common function between them, should I:

create a library under scripts/lib (Yes)
put the functions in one of the two commands and source it from the other (No)
create a plugin (irrelevant)

Documentation only files

I want to have go help eastereggs that will output a list of eastereggs present in the project. I do not want this to be exposed as a command, ie ethhak eastereggs should say command not found or at least `eastereggs should not be returned in autocompletion of commands or in command lists. Is there a way to do that?

Answer: No (other than custom logic in the go script directly.

Common command parameters

I want to have some parameters like -vvv' and--debug` that are common to all my command scripts. From what I understand, I have to make the code that reads these parameters from the command line a module and then source this module from each and every command script I write. Some questions:

can I source it once and for all somewhere else? Answer: Common flags/options can be taken care of in the entry-point, custom go-script. Example:

. "${0%/*}/go-core.bash" "scripts"
cli_arguments="$@"
cli_arguments=( $(clean_arguments "$cli_arguments"))
@go "$cli_arguments"

where in clean_arguments() you loop through the argument list and remove the global ones.

can I add documentation for these options to only one file and have that documentation pop up in the documentation of other commands, perhaps in footer section named common {{cmd}} options? Answer: No

Multiple command parameters

Is it possible to pass multiple parameters to a command? Eg go command_name -vvv --debug?

Answer: Parameters/flags are handled on a per command basis. Each command script takes care of parameter handling for its own sake. Below is an example of a common way to organize commmand scripts. It also show how to enable multiple options and --key=value options for your command.

command_name_do_sth() {
  ...
}

command_name_do_sth_else() {
  ...
}

command_name_bash_completion() {
  local word_index="${1-0}"
  shift
  local -a argv=( "$@" )

  completions=( '-option1' '--option2=' 'possible_argument1' 'possible_argument2' )

  . "$_GO_USE_MODULE" 'complete'
  @go.complete_remove_completions_already_present 'argv' 'completions' "${#completions[@]}"
}

command_name() {
  local flag1=false
  local option=''
  local argument=''

  while [[ "$#" -gt 0 ]]; do
    case "$1" in
      --complete)
        # Tab completions
        shift
        command_name_completions "$@"
        return
      -option1)
        flag1=true
        ;;
      --option2=*)
        option="${1/--option2=}"
        ;;
      *)
        argument="$1"
        ;;
    esac
    shift
  done

  if [[ "$argument" == '' ]]; then
    echo 'Error msg'
    exit 1
  else
    command_name_do_sth "$argument" "$flag1"
  fi
}

command_name "$@"

Command Parameters with a single dash

Is ti possible to pass parameters like -vvv that have a single dash?

Answer: See previous question.

Parameters with values

Is it possible to have a parameter like --target=first? Generally, what is the recommended way to pass arguments into the command scripts?

Answer: See previous question.

mbland / go-script-bash