src.elv.sh@v0.21.0-dev.0.20240515223629-06979efb9a2a/pkg/edit/complete_getopt.d.elv (about)

     1  # Produces completions according to a specification of accepted command-line
     2  # options (both short and long options are handled), positional handler
     3  # functions for each command position, and the current arguments in the command
     4  # line. The arguments are as follows:
     5  #
     6  # * `$args` is an array containing the current arguments in the command line
     7  #   (without the command itself). These are the arguments as passed to the
     8  #   [Argument Completer](#argument-completer) function.
     9  #
    10  # * `$opt-specs` is an array of maps, each one containing the definition of
    11  #   one possible command-line option. Matching options will be provided as
    12  #   completions when the last element of `$args` starts with a dash, but not
    13  #   otherwise. Each map can contain the following keys (at least one of `short`
    14  #   or `long` needs to be specified):
    15  #
    16  #   - `short` contains the one-letter short option, if any, without the dash.
    17  #
    18  #   - `long` contains the long option name, if any, without the initial two
    19  #     dashes.
    20  #
    21  #   - `arg-optional`, if set to `$true`, specifies that the option receives an
    22  #     optional argument.
    23  #
    24  #   - `arg-required`, if set to `$true`, specifies that the option receives a
    25  #     mandatory argument. Only one of `arg-optional` or `arg-required` can be
    26  #     set to `$true`.
    27  #
    28  #   - `desc` can be set to a human-readable description of the option which
    29  #     will be displayed in the completion menu.
    30  #
    31  #   - `completer` can be set to a function to generate possible completions for
    32  #     the option argument. The function receives as argument the element at
    33  #     that position and return zero or more candidates.
    34  #
    35  # * `$arg-handlers` is an array of functions, each one returning the possible
    36  #   completions for that position in the arguments. Each function receives
    37  #   as argument the last element of `$args`, and should return zero or more
    38  #   possible values for the completions at that point. The returned values can
    39  #   be plain strings or the output of `edit:complex-candidate`. If the last
    40  #   element of the list is the string `...`, then the last handler is reused
    41  #   for all following arguments.
    42  #
    43  # Example:
    44  #
    45  # ```elvish-transcript
    46  # ~> fn complete {|@args|
    47  #      opt-specs = [ [&short=a &long=all &desc="Show all"]
    48  #                    [&short=n &desc="Set name" &arg-required=$true
    49  #                     &completer= {|_| put name1 name2 }] ]
    50  #      arg-handlers = [ {|_| put first1 first2 }
    51  #                       {|_| put second1 second2 } ... ]
    52  #      edit:complete-getopt $args $opt-specs $arg-handlers
    53  #    }
    54  # ~> complete ''
    55  # ▶ first1
    56  # ▶ first2
    57  # ~> complete '-'
    58  # ▶ (edit:complex-candidate -a &display='-a (Show all)')
    59  # ▶ (edit:complex-candidate --all &display='--all (Show all)')
    60  # ▶ (edit:complex-candidate -n &display='-n (Set name)')
    61  # ~> complete -n ''
    62  # ▶ name1
    63  # ▶ name2
    64  # ~> complete -a ''
    65  # ▶ first1
    66  # ▶ first2
    67  # ~> complete arg1 ''
    68  # ▶ second1
    69  # ▶ second2
    70  # ~> complete arg1 arg2 ''
    71  # ▶ second1
    72  # ▶ second2
    73  # ```
    74  #
    75  # See also [`flag:parse-getopt`]().
    76  fn complete-getopt {|args opt-specs arg-handlers| }