Merge pull request #1190 from deining/converter-demo

[#1190] Improve InetSocketAddressConverter demo

Author: remkop

docs/index.adoc

@@ -13,6 +13,7 @@
 :icons: font
 :imagesdir: images
 :sectanchors:
+:linkattrs:
 ifdef::env-github[]
 :caution-caption: :fire:
 :important-caption: :heavy_exclamation_mark:
@@ -814,15 +815,15 @@ If the user specifies invalid input, custom type converters should throw an exce
 Any exception is fine, and will result in a message like the below being displayed to the user:
 
 ----
-Invalid value for option '-a': cannot convert 'xxxinvalidinput' to InetSocketAddress (java.lang.IllegalArgumentException: Invalid format: must be 'host:port' but was 'xxxinvalidinput')
+Invalid value for option '--socket-address': cannot convert 'xxxinvalidinput' to InetSocketAddress (java.lang.IllegalArgumentException: Invalid format: must be 'host:port' but was 'xxxinvalidinput')
 ----
 
 The above error message is generic and is reasonable for many exceptions, but sometimes you want more control over the error message displayed to the user.
 To achieve this, throw a `picocli.CommandLine.TypeConversionException` instead.
 When a `TypeConversionException` is thrown, picocli will show an error message that indicates the problematic option, followed by the exception message text. The resulting output looks something like this:
 
 ----
-Invalid value for option '-a': Invalid format: must be 'host:port' but was 'xxxinvalidinput'
+Invalid value for option '--socket-address': Invalid format: must be 'host:port' but was 'xxxinvalidinput'
 ----
 
 Below is an example custom converter that throws a `TypeConversionException`:
@@ -846,7 +847,7 @@ class InetSocketAddressConverter implements ITypeConverter<InetSocketAddress> {
 }
 ----
 
-The `picocli-examples` module on GitHub has a runnable https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/java/picocli/examples/typeconverter/InetSocketAddressConverterDemo.java[example].
+The `picocli-examples` module on GitHub has a minimal working https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/java/picocli/examples/typeconverter/InetSocketAddressConverterDemo.java[example] which you can run in our https://www.jdoodle.com/embed/v0/2mxo?stdin=1&arg=1[online-editor^].
 
 === Option-specific Type Converters
 Picocli 2.2 added a `converter` attribute to the `@Option` and `@Parameter` annotations. This allows a specific option or positional parameter to use a different converter than would be used by default based on the type of the field.

docs/quick-guide.adoc

@@ -10,6 +10,7 @@
 :source-highlighter: coderay
 :icons: font
 :imagesdir: images
+:linkattrs:
 :sectanchors:
 ifdef::env-github[]
 :caution-caption: :fire:

picocli-examples/src/main/java/picocli/examples/typeconverter/InetSocketAddressConverterDemo.java

@@ -1,3 +1,10 @@
+/**
+ * Picocli: Custom converter demo
+ * Explanation: <a href="https://picocli.info/#_handling_invalid_input">Picocli user manual</a>
+ * Discussion: <a href="https://github.com/remkop/picocli/issues/972">GitHub issue</a>
+ * Origin of source code: <a href="https://github.com/remkop/picocli/tree/master/picocli-examples/src/main/java/picocli/examples/typeconverter">GitHub</a>
+ * @author Remko Popma
+ */
 package picocli.examples.typeconverter;
 
 import picocli.CommandLine;
@@ -7,7 +14,7 @@
 
 import java.net.InetSocketAddress;
 
-public class InetSocketAddressConverterDemo {
+public class InetSocketAddressConverterDemo implements Runnable {
 
     static class InetSocketAddressConverter implements ITypeConverter<InetSocketAddress> {
         @Override
@@ -23,13 +30,18 @@ public InetSocketAddress convert(String value) {
         }
     }
 
-    @Option(names = "-a", converter = InetSocketAddressConverter.class)
+    @Option(names = { "-s", "--socket-address" }, converter = InetSocketAddressConverter.class)
     InetSocketAddress address;
 
     public static void main(String[] args) {
-        new CommandLine(new InetSocketAddressConverterDemo()).execute("-a=xxxinvalidinput");
+        new CommandLine(new InetSocketAddressConverterDemo()).execute("--socket-address=invalidInputWithoutColon");
 
         // try this also:
-        //new CommandLine(new InetSocketAddressConverterDemo()).execute("-a=xxxinvalidinput:xxx");
+        //new CommandLine(new InetSocketAddressConverterDemo()).execute("--socket-address=invalidInputWithColon:xxx");
+    }
+
+    @Override
+    public void run() {
+        System.out.println(String.format("Valid socket address given: host: %s, port: %s", address.getHostString(), address.getPort()));
     }
 }