Picocli

These examples utilize Picocli, a library for writing command line applications that can understand a wide variety of optional and positional parameter types, based upon annotations added to your Java code.

Picocli's features include multiple argument styles, multi-valued fields, default values, argument grouping, automatic conversion of arguments to Java types, automatic help and version options, ANSI colors, password processing, argument files (@-files), git-like subcommands, and the automatic generation of AsciiDoc man pages.

My Examples

The usage information shown for each example is generated by Picocli automatically, based on annotations included in the code.

• Banner.java

  Usage: Banner [-dhV] [-s=<style>] [-z=<fontSize>] [<text>...]
  Prints an ASCII banner.
      [<text>...]            Text to be displayed.
  -d, --down                 Print down the screen
  -h, --help                 Show this help message and exit.
  -s, --font-style=<style>   <style> values: plain, bold, italics
  -V, --version              Print version information and exit.
  -z, --font-size=<fontSize> Font size (default: 12)
  

  Try these examples (run is the run.bat batch file):

  > run Banner --help
  > run Banner -V
  > run Banner
  > run Banner -d
  > run Banner -z=30 "Hi"
  > run Banner -d -z=30 "Hello world"
  > run Banner -d -z=50 -s=bold "Hello world"
  > run Banner -z=30 -s=italics "Hi"
  

  Notable Picocli features: automatic help and version options, default values, enum usage, automatic conversion of command line arguments to data types. Banner utilizes a support class, StringMetrics.java, to calculate the pixel dimensions of the drawn string.

  
   
  
• CheckSum.java

  Usage: CheckSum [-hV] [-a=<alg>] <file>
  Prints a file's checksum.
      <file>              The file whose checksum is calculated.
  -a, --algorithm=<alg>   SHA-1, SHA-256, MD5, ...  (default: SHA-1)
  -h, --help              Show this help message and exit.
  -V, --version           Print version information and exit.
  

  Try these examples:

  > run CheckSum -h
  > run CheckSum -V
  > run CheckSum CheckSum.java
  

  
   
  
• QSql.java

     ____   _____       _
    / __ \ / ____|     | |
   | |  | | (___   __ _| |
   | |  | |\___ \ / _` | |
   | |__| |____) | (_| | |
    \___\_\_____/ \__, |_|
                     | |
                     |_|
  
  Usage: QSql [-hpV] -d=<dbName> [-q=<query>]
  Queries a SQLite database.
    -d, --database=<dbName>   SQLite database
    -h, --help                Show this help message and exit.
    -p, --pretty-print        display an ASCII table
    -q, --query=<query>       SQL Query
    -V, --version             Print version information and exit.
  

  Try these examples:

  > run QSql -h
  > run QSql -d=worldcities.db
  > run QSql -d=worldcities.db -q="select * from cities WHERE city = 'London'"
  > run QSql -d=worldcities.db  -p -q="select * from cities WHERE city = 'London'"
  

  It uses the worldcities.db database, and the sqlite-jdbc-3.16.1.jar and DBTablePrinter.jar libraries (see below). Naturally, you also need to install SQLite.

  I generated the ASCII header at this site.

  
   
  
• Jwc.java

  Usage: Jwc [-hlLmVw] [FILE...]
  A simple Java version of wc.
        [FILE...]           File(s) to be searched
    -h, --help              Show this help message and exit.
    -l, --lines             print the newlines count
    -L, --max-line-length   print the length of the longest line
    -m, --chars             print the character count
    -V, --version           Print version information and exit.
    -w, --words             print the word count
  

  Try these examples:

  > run Jwc Jwc.java
  > run Jwc *.java
  > run Jwc -lw Jwc.java
  

  
   
  
• Jps.java

  Usage: Jps [-ahlV] [-c=<cmdName>] [-r=<min-max>] [-p=PID[,PID...]]...
  A simple Java version of ps.
    -a, --all                 print info about all processes
    -c, --command=<cmdName>   list only command name processes
    -h, --help                Show this help message and exit.
    -l, --label               print field labels
    -p, --pids=PID[,PID...]   selects the processes in pidlist
    -r, --range=<min-max>     selects pids based on min-max range
    -V, --version             Print version information and exit.
  

  Try these examples:

  > run Jps
  > run Jps -l
  > run Jps -al
  > run Jps -r=10000-15000
  > run Jps -p=11224,11900,11904
  > run Jps -c=note
  

  Notable Picocli features: split regexs, option labels, use of arity, value validation, ParameterException.

  
   
  
• JGrep.java

  Usage: JGrep [-chHilnsvV] [--color] PATTERN [FILE...] [COMMAND]
  A simple Java version of grep.
        PATTERN                PATTERN is a basic regular expression.
        [FILE...]              File(s) to be searched for PATTERN
    -c, --count                print only a count of matching lines per FILE
        --color, --colour      show PATTERN matches in red
    -h, --help                 Show this help message and exit.
    -H, --no-filename          suppress the prefixing filename on output
    -i, --ignore-case          ignore case distinctions
    -l, --files-with-matches   print only names of FILEs containing matches
    -n, --line-number          print line number with output lines
    -s, --no-messages          suppress error messages
    -v, --invert-match         select non-matching lines
    -V, --version              Print version information and exit.
  Commands:
    gen-manpage  Generates man pages for all commands in the specified directory.
  

  Try these examples:

  > run JGrep "private" JGrep.java
  > run JGrep --color "private" JGrep.java
  > run JGrep "^public" *.java
  > run JGrep -c "private" JGrep.java
  > run JGrep -Hl "private" JGrep.java
  > run JGrep -l "concurrent" *.java
  
  > cat JGrep.java | run JGrep -n "private"
  > cat JGrep.java | run JGrep -Hc "private"
  
  > run JGrep gen-manpage -v JGrep
  

  Notable Picocli feature: the generation of AsciiDoc documentation, which requires the picocli-codegen-4.7.4.jar library (see below).

  
   
  
• SendGmail.java

  Usage: SendGmail [-dhvV] [-a=<fnm>] [-b=<bcc>] [-c=<cc>] [-f=<from>]
                   -s=<subject> -t=<to> (-U=<usr> -P=<pwd>) [<bodyText>]
  Send an email using a Gmail account.
        [<bodyText>]          Body text of the message
    -a, --attach=<fnm>        File to attach to message
    -b, --bcc=<bcc>           Bcc address of message
    -c, --cc=<cc>             Cc address of message
    -d, --debug               Turn on session debugging
    -f, --from=<from>         Sender's address; default is username
    -h, --help                Show this help message and exit.
    -P, --password=<pwd>      Google account password
    -s, --subject=<subject>   Subject line of message
    -t, --to=<to>             To address of message
    -U, --username=<usr>      Google account username
    -v, --verbose             Turn on session reports
    -V, --version             Print version information and exit.
  
  

  Try these examples (but with your Gmail account's username and password):

  > run SendGmail -s="test 1" -t="chunkylover53@aol.com" -U="UUUUUU" -P="XXXX" "this is message 1"
  
  > run SendGmail -s="test 2" -t="chunkylover53@aol.com" @login.txt -a="SendGmail.java" "this is message 2"
  
  > cat Calc.java | run SendGmail -s="test 3" -t="chunkylover53@aol.com" @login.txt -a="SendGmail.java" 
  
  > run SendGmail -s="test 4" -a="Calc.java" -t="chunkylover53@aol.com" @login.txt 
      this is message 4
      ctrl-Z
  > run SendGmail -v @login.txt -s="test 5" -t="chunkylover53@aol.com" @longMsg.txt
  

  Note: chunkylover53@aol.com is Homer Simpson's email, circa 2003.

  Notable Picocli features: argument groups, command-line argument files (@-files), but not an interactive password since I found its input interferred with reading a message from stdin.

  SendGmail relies on the jakarta.mail-2.0.2.jar, angus-activation-2.0.1.jar, and jakarta.activation-api-2.1.2.jar libraries (see below).

  I had several problems getting this example to work.

  One issue was that Google doesn't by default support network access using only an account's username and password. You either have to configure the Gmail account to enable 'less secure apps' (which I did), or use OAuth2 authentication (which is somewhat more complex). The relevant setting is "Less secure app access" in the "Security" category of your Google Account page.

  Another issue was my anti-virus software (Avast) which would not allow SendGmail to connect to Gmail's SMTP host at smtp.gmail.com, port 465. I had to disable its "Scan outbound emails (SMTP)" setting in its Mail Shield.

  Yet another issue was Angus Mail's use of reflective access to sockets, which triggered a warning from Java 11. This was switched off by adding the option --add-opens java.base/sun.security.util=ALL-UNNAMED to the call to java inside run.bat. This will become a more serious problem in later versions of Java since this option is scheduled for removal.

  
   
  
• ISOCodeResolver.java

  Usage: ISOCodeResolver [COMMAND]
  Resolve ISO country or language codes
  Commands:
    language  Resolve ISO language code(s)
    help      Display help information about the specified command.
    country   Resolve ISO country code(s)
  

  Try these examples:

  > run ISOCodeResolver language de cs en sd se
  > run ISOCodeResolver country cn fr th ro no
  

Notable Picocli features: git-like subcommands, subcommand creation using a method and a class, use of the help command.

Other Downloads and Links

• Batch files to easily compile and run my code: compile.bat and run.bat
   
  
• All the examples in one zipped file (2.13 MB)
   
  
• My copies of the libraries (7.06 MB). They are picocli-4.7.4.jar, picocli-codegen-4.7.4.jar, sqlite-jdbc-3.16.1.jar, DBTablePrinter.jar, jakarta.mail-2.0.2.jar, angus-activation-2.0.1.jar, and jakarta.activation-api-2.1.2.jar. Only the first two are needed for Picocli, while the others are used in some of the examples. In fact, picocli-codegen-4.7.4.jar is only required for JGrep.java, to generate AsciiDoc documentation.
   
  Unzip the file, and place the libs folder in the same directory as the examples and batch files.
   
  
• The official Picocli libraries. The other libraries used in some of the examples: the JDBC driver for SQLite and SQLite; Database Table Printer; Jakarta/Angus Mail.
   
  
• Picocli documentation comes in several flavors: a whirlwind tour, a quick guide, and a detailed manual
   
  
• The Picocli API documentation.
   
  
• A directory of examples at the Picocli website.