ArgumentCompletor
Date: 2015-12-09

jline

## Class ArgumentCompletor

- java.lang.Object
- - jline.ArgumentCompletor

- All Implemented Interfaces:
    Completor

      public class ArgumentCompletor
      extends java.lang.Object
      implements Completor

  A `Completor` implementation that invokes a child completor using the appropriate separator argument. This can be used instead of the individual completors having to know about argument parsing semantics.

  Example 1: Any argument of the command line can use file completion.

              consoleReader.addCompletor (new ArgumentCompletor (
                      new FileNameCompletor ()))

  Example 2: The first argument of the command line can be completed with any of "foo", "bar", or "baz", and remaining arguments can be completed with a file name.

              consoleReader.addCompletor (new ArgumentCompletor (
                      new SimpleCompletor (new String [] { "foo", "bar", "baz"})));
              consoleReader.addCompletor (new ArgumentCompletor (
                      new FileNameCompletor ()));

  When the argument index is past the last embedded completors, the last completors is always used. To disable this behavior, have the last completor be a `NullCompletor`. For example:

              consoleReader.addCompletor (new ArgumentCompletor (
                      new SimpleCompletor (new String [] { "foo", "bar", "baz"}),
                      new SimpleCompletor (new String [] { "xxx", "yyy", "xxx"}),
                      new NullCompletor
                      ));

  TODO: handle argument quoting and escape characters

  Author:
    Marc Prud'hommeaux

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ArgumentCompletor.AbstractArgumentDelimiter` Abstract implementation of a delimiter that uses the `ArgumentCompletor.AbstractArgumentDelimiter.isDelimiter(java.lang.String, int)` method to determine if a particular character should be used as a delimiter.
    `static interface` | `ArgumentCompletor.ArgumentDelimiter` The `ArgumentCompletor.ArgumentDelimiter` allows custom breaking up of a `String` into individual arguments in order to dispatch the arguments to the nested `Completor`.
    `static class` | `ArgumentCompletor.ArgumentList` The result of a delimited buffer.
    `static class` | `ArgumentCompletor.WhitespaceArgumentDelimiter` `ArgumentCompletor.ArgumentDelimiter` implementation that counts all whitespace (as reported by `Character.isWhitespace(char)`) as being a delimiter.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ArgumentCompletor(Completor completor)` Constuctor: create a new completor with the default argument separator of " ".
    `ArgumentCompletor(Completor[] completors)` Constuctor: create a new completor with the default argument separator of " ".
    `ArgumentCompletor(Completor[] completors, ArgumentCompletor.ArgumentDelimiter delim)` Constuctor: create a new completor with the specified argument delimiter.
    `ArgumentCompletor(Completor completor, ArgumentCompletor.ArgumentDelimiter delim)` Constuctor: create a new completor with the specified argument delimiter.
    `ArgumentCompletor(java.util.List completors)` Constuctor: create a new completor with the default argument separator of " ".

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `complete(java.lang.String buffer, int cursor, java.util.List candidates)` Populates candidates with a list of possible completions for the buffer.
    `boolean` | `getStrict()` Returns whether a completion at argument index N will succees if all the completions from arguments 0-(N-1) also succeed.
    `void` | `setStrict(boolean strict)` If true, a completion at argument index N will only succeed if all the completions from 0-(N-1) also succeed.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ArgumentCompletor

          public ArgumentCompletor(Completor completor)

      Constuctor: create a new completor with the default argument separator of " ".
      Parameters:
        `completor` - the embedded completor

    - #### ArgumentCompletor

          public ArgumentCompletor(java.util.List completors)

      Constuctor: create a new completor with the default argument separator of " ".
      Parameters:
        `completors` - the List of completors to use

    - #### ArgumentCompletor

          public ArgumentCompletor(Completor[] completors)

      Constuctor: create a new completor with the default argument separator of " ".
      Parameters:
        `completors` - the embedded argument completors

    - #### ArgumentCompletor

          public ArgumentCompletor(Completor completor,
                           ArgumentCompletor.ArgumentDelimiter delim)

      Constuctor: create a new completor with the specified argument delimiter.
      Parameters:
        `completor` - the embedded completor
        `delim` - the delimiter for parsing arguments

    - #### ArgumentCompletor

          public ArgumentCompletor(Completor[] completors,
                           ArgumentCompletor.ArgumentDelimiter delim)

      Constuctor: create a new completor with the specified argument delimiter.
      Parameters:
        `completors` - the embedded completors
        `delim` - the delimiter for parsing arguments

  - ### Method Detail

    - #### setStrict

          public void setStrict(boolean strict)

      If true, a completion at argument index N will only succeed if all the completions from 0-(N-1) also succeed.

    - #### getStrict

          public boolean getStrict()

      Returns whether a completion at argument index N will succees if all the completions from arguments 0-(N-1) also succeed.

    - #### complete

          public int complete(java.lang.String buffer,
                     int cursor,
                     java.util.List candidates)

      Description copied from interface: `Completor`
      Populates candidates with a list of possible completions for the buffer. The candidates list will not be sorted before being displayed to the user: thus, the complete method should sort the `List` before returning.
      Specified by:
        `complete` in interface `Completor`
      Parameters:
        `buffer` - the buffer
        `candidates` - the `List` of candidates to populate
      Returns:
        the index of the buffer for which the completion will be relative