Skip to content

Commit

Permalink
More work on annotations pages (#35)
Browse files Browse the repository at this point in the history
- Wrote most of the `@Parser` annotation up
- Stub for rest of `@Cli` annotation page
- Stub for more In Practise pages
  • Loading branch information
rvesse committed Jan 15, 2016
1 parent fe0335f commit 47b2ec6
Show file tree
Hide file tree
Showing 5 changed files with 113 additions and 4 deletions.
12 changes: 12 additions & 0 deletions guide/annotations/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,4 +35,16 @@ As with commands typically we also want to add a `description` that describes wh
public class BasicCli {
```

### Commands

### Default Command

### Groups

### Global Restrictions

### Parser Configuration

Parser configuration for a CLI may be specified via the `parserConfiguration` field which takes a [`@Parser`](parser.html) annotation. Please see the documentation for that annotation for notes on controlling the parser configuration.

**TODO Write up the rest of the @Cli annotation**
88 changes: 86 additions & 2 deletions guide/annotations/parser.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,90 @@ title: Parser Annotation

The `@Parser` annotation is applied to classes also annotated with `@Command` to configure the parser behaviour for that single command when parsers are created using `SingleCommand.singleCommand()`.

It may also be used as an argument to the [`@Cli`](cli.html) annotation in order to configure parser behaviour for a CLI.
It may also be used as an argument to the [`@Cli`](cli.html) annotation in order to configure parser behaviour for a CLI via the `parserConfiguration` field of that annotation.

**TODO Write up @Parser annotation**
### Default Configuration

To get the default parser configuration you do not need to specify any fields on the annotation i.e. simply provide a basic annotation:

```java
@Parser()
```

This has the same effect as not specifying any parser configuration since in that case Airline will use its defaults which are sufficient for most basic uses.

### Option Parsers

[Option Parsers](../parser/options.html) are used to control how Airline parses options, Airline comes with a variety of implementations of these and there are several fields of the `@Parser` annotation that are used to configure these.

Firstly there are the `useDefaultOptionParsers` and `defaultParsersFirst` fields, the former indicates that the default set of option parsers should be used and the latter indicates whether the defaults are configured before/after any other option parsers that you might configure. Both of these default to `true` so there is no need to specify either unless you want to disable the default parsers or use alternative parsers in preference to the defaults e.g.

```java
@Parser(useDefaultOptionParsers = true, defaultParsersFirst = false)
```

The `optionParsers` field is used to provide an array of classes that implement the `OptionParser` interface and thus can be used to customise the option parsers used or to change the order in which they are used.

For example with the default parsers if we had an option that had arity 2 with the default parsers the user would be expected to specify it as `--option foo bar`. However often in reality if we have an arity 2 argument we are expecting users to pass in a pair of values and it is quite common to do this as `--option foo=bar` which with the default configuration would be an error. If we wanted to enable this style of parsing we could do so by enabling the built-in `MaybePairValueOptionParser` e.g.

```java
@Parser(defaultParsersFirst = false, optionParsers = { MaybePairValueOptionParser.class })
```

### Type Converter

If we wanted to use a custom type converter as detailed in [Supported Types](../practise/types.html) then we can use the `typeConverter` field to do this e.g.

```java
@Parser(typeConverter = ExtendedTypeConverter.class)
```

### Command Factory

If we wanted to use a custom command factory then we can use the `commandFactory` field to do this e.g.

```java
@Parser(commandFactory = ExtendedCommandFactory.class)
```

### Option and Command Abbreviation

Option and command abbreviation is an advanced feature of the Airline parser that allows users to avoid typing the full option and/or command names provided that the portion they type is unambiguous.

For example say we had a CLI which contained a `remove` and a `replace` command, by default users always have to type the full command name. However if we enable `allowCommandAbbreviation` then users only need to type enough characters to unambiguously identify the command e.g.

```java
@Parser(allowCommandAbbreviation = true)
```

With that enabled a user can now type `rem` for `remove` and `rep` for `replace`, since the abbreviation must be unambiguous typing `re` would not be acceptable as it could refer to either command.

Similarly we can allow the same for option names via the `allowOptionAbbreviation`, option abbreviation is slightly more restrictive in that at least 3 characters must be typed i.e. short names such as `-a` can never be abbreviated.

### Arguments Separator

By default Airline supports a separator of `--` which can be used to separate options from arguments where arguments may be misinterpreted as options. After this separator is seen any further command line arguments are treated as arguments and not as options.

If you wish to customise the separator then you can this like so:

```java
@Parser(argumentsSeparator = "@@")
```

Would instead use `@@` as the arguments separator.

### Aliases

Airline supports a [User Defined Aliases](../practise/aliases.html) system which allows for users to define custom aliases for use with your Airline powered CLIs.

To specify where to get user defined aliases from you use some combination of the `userAliasesFile`, `userAliasesSearchLocation` and `userAliasesPrefix` fields e.g.

```java
@Parser(userAliasesFile = "example.config",
userAliasesSearchLocation = { "~/example/" },
userAliasesPrefix = "alias.")
```

Here we define that aliases will be defined in a file `example.config` which should be found under `~/example` (where `~` is treated as special value for users home directory)

**TODO Write up remainder of notes on @Parser annotation**
8 changes: 8 additions & 0 deletions guide/parser/options.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
layout: page
title: Option Parsing
---

Option parsing is provided to Airline by the instances of the `OptionParser` interface. Airline ships with a variety of these which implement common option parsing styles. It is also possible to provide your own custom implementations if you wish to more closely control the option parsing process yourself

**TODO Document the OptionParser and implementations thereof**
4 changes: 4 additions & 0 deletions guide/practise/aliases.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
layout: page
title: User Defined Aliases
---
5 changes: 3 additions & 2 deletions guide/practise/types.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ Often it may be easier to simply extend the default behaviour described on this
```java
package com.github.rvesse.airline.examples.userguide.practise;

import com.github.rvesse.airline.ConvertResult;
import com.github.rvesse.airline.DefaultTypeConverter;

/**
Expand Down Expand Up @@ -91,14 +92,14 @@ In order to use a custom type converter you will need to register it with your p
@Parser(typeConverter = ExtendedTypeConverter.class)
```

If you are creating a single command i.e. a single `@Command` annotated class then simply add this annotation to your class. If you are creating a CLI i.e. a `@Cli` annotation then you can use the `parser` field of the annotation like so:
If you are creating a single command i.e. a single `@Command` annotated class then simply add this annotation to your class. If you are creating a CLI i.e. a `@Cli` annotation then you can use the `parserConfiguration` field of the annotation like so:

```java
@Cli(name = "basic",
description = "Provides a basic example CLI",
defaultCommand = GettingStarted.class,
commands = { GettingStarted.class, Tool.class },
parser = @Parser(typeConverter = ExtendedTypeConverter.class))
parserConfiguration = @Parser(typeConverter = ExtendedTypeConverter.class))
```

Or if you are creating the `ParserMetadata<T>` using the fluent `ParserBuilder<T>` API you can add your custom type converter like so:
Expand Down

0 comments on commit 47b2ec6

Please sign in to comment.