Clean running examples!

[aadrian]

Hi,

Would be nice to have some clean and running examples.

The existing ones seem "overloaded" and and mixed with unit tests :( .

Thank you.

[remkop]

Good point. The manual contains mostly snippets to illustrate a point very briefly.
The Checksum example at the beginning of the manual is the only full running example.

If you have ideas for additional full examples that’d be great. They need to be fairly short though, about 20-25 lines of code or less.

[RobertZenz]

Where should they go to? I think I could vamp up a few simple examples on the spot for at least basic usage. Ideally, they could be self-contained, runnable example files, like SimpleUsageMain.java somewhere in the source tree which contains everything needed including a main method to simply run it.

[aadrian]

Where should they go to?

One possibility would be to have an /examples subdirectory/package, but that would require changing the build.gradle too.
Many other projects just use the multi-module features of Gradle but that also requires allot of changes.

Maybe a much simpler way would be to just make another GitHub repo: e.g. picocli-examples that would have:

dependencies {
    compile 'info.picocli:picocli:2.0.1'
    compile 'org.fusesource.jansi:jansi:1.16'
}

in build.gralde

Ideally, they could be self-contained,

Yes, but each example in it's own sub-directory? This way best practices could be better demonstrated (e.g. even if one example requires more than one file)

[remkop]

I'd prefer to keep the examples in the same repo.

I'm open to other ideas but I was thinking to add an picocli.examples package under src/test/ (with subpackages if needed for elaborate examples). One nice thing is that the tests can have dependencies on other libraries, that may be useful for some examples.

Something like:

src/test/groovy/picocli/examples
src/test/java/picocli/examples

[RobertZenz]

I'd also opt for the same repository. On a similar note, I wouldn't put the examples into the test directory, because, at least for me, I'd only expect "automated" tests in there not some form of documentation.

Maybe src/examples/java/Blah.java is an alternative? Or putting the examples directory directly under the root, to make it easily findable/visible?

[remkop]

Yes that would work. Would be cleaner but just need to work out how the gradle build needs to change. Should be doable...

// assuming a picocli.examples package:
src/examples/java/picocli/examples/Blah.java
src/examples/groovy/picocli/examples/Blah.groovy

[remkop]

Or we can have a separate module (in the same repo):

// main module (part of the distribution)
src/main/java
src/test/groovy
src/test/java

// separate module (not part of the distribution)
examples/src/main/java
examples/src/main/groovy

[RobertZenz]

Either way sounds good to me, whatever is easier for you to manage (I'm not really into gradle).

[remkop]

User eprozium on Reddit requested subcommand examples.

If anyone has subcommand examples they would not mind contributing, all pull requests are welcome.