Skip to content

Commit

Permalink
DOC update release notes
Browse files Browse the repository at this point in the history
  • Loading branch information
remkop committed May 12, 2020
1 parent 7445dbf commit 5fd7460
Showing 1 changed file with 57 additions and 12 deletions.
69 changes: 57 additions & 12 deletions RELEASE-NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,21 @@
# <a name="4.3.0"></a> Picocli 4.3.0 (UNRELEASED)
The picocli community is pleased to announce picocli 4.3.0.

This is a fairly big release with over 50 bugfixes and enhancements. Many thanks to the picocli community who contributed 21 pull requests!
This is a fairly big release with 70 [tickets closed](https://github.com/remkop/picocli/milestone/65?closed=1), and over 50 [bugfixes and enhancements](#4.3.0-fixes). Many thanks to the picocli community who contributed 21 pull requests!

This release adds support for "inherited" options. Options defined with `scope = ScopeType.INHERIT` are shared with all subcommands (and sub-subcommands, to any level of depth). Applications can define an inherited option on the top-level command, in one place, to allow end users to specify this option anywhere: not only on the top-level command, but also on any of the subcommands and nested sub-subcommands.

The parser now supports case-insensitive mode for options and subcommands.

Additionally, this release improves support for automatic indexes for positional parameters. Single-value positional parameters without an explicit `index = "..."` attribute are now automatically assigned an index based on the other positional parameters in the command. One use case is mixins with positional parameters.

Also, mixins are now more powerful. Mixin classes can declare a `@Spec(MIXEE)`-annotated field, and picocli will inject the `CommandSpec` of the command _receiving_ this mixin (the "mixee") into this field. This is useful for mixins containing shared logic, in addition to shared options and parameters.
A major theme of this release is sharing options between commands:
* New feature: "inherited" options. Options defined with `scope = ScopeType.INHERIT` are shared with all subcommands (and sub-subcommands, to any level of depth). Applications can define an inherited option on the top-level command, in one place, to allow end users to specify this option anywhere: not only on the top-level command, but also on any of the subcommands and nested sub-subcommands.
* More powerful mixins. Mixin classes can declare a `@Spec(MIXEE)`-annotated field, and picocli will inject the `CommandSpec` of the command _receiving_ this mixin (the "mixee") into this field. This is useful for mixins containing shared logic, in addition to shared options and parameters.

From this release, picocli makes it easy to make subcommands mandatory by making the top-level command a class that does not implement `Runnable` or `Callable`.
Another major theme is improved support for positional parameters:
* Automatic indexes for positional parameters. Single-value positional parameters without an explicit `index = "..."` attribute are now automatically assigned an index based on the other positional parameters in the command. One use case is mixins with positional parameters.
* Repeatable ArgGroups can now define positional parameters.

Additionally, an entry for `--` can be shown in the options list of the usage help message of a command with the `@Command(showEndOfOptionsDelimiterInUsageHelp = true)` annotation.

Error handlers now use ANSI colors and styles. The default styles are bold red for the error message, and italic for stack traces. Applications can customize with the new `Help.ColorScheme` methods `errors` and `stackTraces`.
Other improvements:
* The parser now supports case-insensitive mode for options and subcommands.
* Error handlers now use ANSI colors and styles. The default styles are bold red for the error message, and italic for stack traces. Applications can customize with the new `Help.ColorScheme` methods `errors` and `stackTraces`.
* The usage help message can now show an entry for `--` in the options list with the `@Command(showEndOfOptionsDelimiterInUsageHelp = true)` annotation.
* Easily make subcommands mandatory by making the top-level command a class that does not implement `Runnable` or `Callable`.


This is the sixty-eighth public release.
Expand All @@ -28,6 +28,7 @@ Picocli follows [semantic versioning](http://semver.org/).
* [Inherited Options](#4.3.0-inherited-options)
* [Case-insensitive mode](#4.3.0-case-insensitive)
* [Automatic Indexes for Positional Parameters](#4.3.0-auto-index)
* [Repeatable ArgGroups with Positional Parameters](#4.3.0-positionals-in-groups)
* [`@Spec(MIXEE)` Annotation](#4.3.0-mixee)
* [Showing `--` End of Options in usage help](#4.3.0-end-of-options)
* [Fixed issues](#4.3.0-fixes)
Expand Down Expand Up @@ -151,6 +152,50 @@ class Unanchored {
}
```

### <a name="4.3.0-positionals-in-groups"></a> Repeatable ArgGroups with Positional Parameters

From this release, positional parameters can be used in repeating [Argument Groups](https://picocli.info/#_argument_groups).

When a `@Parameters` positional parameter is part of a group, its `index` is the index _within the group_, not within the command.

Below is an example of an application that uses a repeating group of positional parameters:

```java
@Command(name = "grades", mixinStandardHelpOptions = true, version = "grades 1.0")
public class Grades implements Runnable {

static class StudentGrade {
@Parameters(index = "0") String name;
@Parameters(index = "1") BigDecimal grade;
}

@ArgGroup(exclusive = false, multiplicity = "1..*")
List<StudentGrade> gradeList;

@Override
public void run() {
gradeList.forEach(e -> System.out.println(e.name + ": " + e.grade));
}

public static void main(String[] args) {
System.exit(new CommandLine(new Grades()).execute(args));
}
}
```

Running the above program with this input:

```
Alice 3.1 Betty 4.0 "X Æ A-12" 3.5 Zaphod 3.4
```
Produces the following output:

```
Alice: 3.1
Betty: 4.0
X Æ A-12: 3.5
Zaphod: 3.4
```

### <a name="4.3.0-mixee"></a> `@Spec(MIXEE)` Annotation
From this release, mixins are more powerful. Mixin classes can declare a `@Spec(MIXEE)`-annotated field, and picocli will inject the `CommandSpec` of the command _receiving_ this mixin (the "mixee") into this field. This is useful for mixins containing shared logic, in addition to shared options and parameters.
Expand Down

0 comments on commit 5fd7460

Please sign in to comment.