unkrig.de - User contributions [en]

CommandLineOptions tutorial

2024-05-01T20:50:22Z

Admin: Created page with "===Processing command line options is easy, so why do I need a helper?=== To illustrate the reason being, let's develop a command line application to show the typical problems and how <code>CommandLineOptions</code> can help you: <pre> package com.acme.clo_demo; public class Diff { public static void main(String[] args) { boolean brief = false; boolean reportIdenticalFiles = false; int context = 3;..."

===Processing command line options is easy, so why do I need a helper?===

To illustrate the reason being, let's develop a command line application to show the typical problems and how <code>CommandLineOptions</code> can help you:

<pre>
package com.acme.clo_demo;

public class Diff {

public static void main(String[] args) {

boolean brief = false;
boolean reportIdenticalFiles = false;
int context = 3;

int idx = 0;
while (idx < args.length) {
String arg = args[idx];
if (!arg.startsWith("-")) break;
idx++;
if ("-q".equals(arg) || "--brief".equals(arg)) {
brief = true;
} else
if ("-s".equals(arg) || "--report-identical-files".equals(arg)) {
reportIdenticalFiles = true;
} else
if ("-C".equals(arg) || "--Context".equals(arg)) {
context = Integer.parseInt(args[idx++]);
} else
{
System.err.println("Unrecognized command line option \"" + arg + "\"");
}
}

// Now process args[idx]... and do the "real work".
}
}
</pre>

This implementation supports both "short" and "long" options, and detects invalid options. However there is room for improvement:
* You cannot have "compact" short options, e.g. "<tt>-qs</tt>" for "<tt>-q -s</tt>".
* You get an <code>ArrayIndexOutOfBoundsException</code> when "<tt>-C</tt>" is not followed by an argument.
* You get a <code>NumberFormatException</code> when the argument of "<tt>-C</tt>" cannot be converted to an integer.
* If the first argument after the options starts with a hyphen, it is identified as an invalid option.
* The code is not documented.
* The only support the user gets when it uses the tool is the "Unsupported command line option..." error message.

So here's the second version that overcomes these deficits:

<pre>
package com.acme.clo_demo;

/**
* A (rudimentary) re-implementation of the well-known DIFF command line utility.
*/
public class Diff {

/**
* Parses the command line options and arguments, then prints the differences between two files or two
* directories.
* <p>
* Supports the following command line options:
* </p>
* <dl>
* <dt>--help</dt>
* <dd>Print usage help and exit</dd>
* <dt>-q, --brief</dt>
* <dd>Don't report the differences, only which files have changed</dd>
* <dt>-s, --report-identical-files</dt>
* <dd>Also report about files that did NOT change</dd>
* <dt>-C <var>NUM</var>, --context <var>NUM</var></dt>
* <dd>Report differences in "context diff" format, with <var>NUM</var> lines of context</dd>
* </dl>
*/
public static void main(String[] args) {

boolean brief = false;
boolean reportIdenticalFiles = false;
int context = 3;

int idx = 0;
while (idx < args.length) {

String arg = args[idx];

if (!arg.startsWith("-")) break;

idx++;

if ("--".equals(arg)) {
break;
} else
if ("--help".equals(arg)) {
System.out.println("Prints the differences between files.");
System.out.println();
System.out.println("Usage:");
System.out.println(" diff [ <option> ] ... <file1> <file2>");
System.out.println(" Prints the differences between <file1> and <file2>.");
System.out.println(" diff [ <option> ] ... <dir1> <dir2>");
System.out.println(" Prints the differences between the files under <dir1> and <dir2>.");
System.out.println();
System.out.println("Supports the following command line options:");
System.out.println(" --help</dt>");
System.out.println(" Print usage help and exit");
System.out.println(" -q, --brief");
System.out.println(" Don't report the differences, only which files have changed");
System.out.println(" -s, --report-identical-files");
System.out.println(" Also report about files that did NOT change");
System.out.println(" -C <NUM>, --context <NUM>");
System.out.println(" Report differences in \"context diff\" format, with <NUM> lines of");
System.out.println(" context");
System.exit(0);
} else
if ("-q".equals(arg) || "--brief".equals(arg)) {
brief = true;
} else
if ("-s".equals(arg) || "--report-identical-files".equals(arg)) {
reportIdenticalFiles = true;
} else
if ("-C".equals(arg) || "--Context".equals(arg)) {
if (idx == args.length) {
System.err.println("Count missing after \"-C\" or \"--context\".");
System.exit(1);
}
try {
context = Integer.parseInt(args[idx++]);
} catch (NumberFormatException nfe) {
System.err.println("Cannot convert \"" + args[idx - 1] + "\" to an integer");
System.exit(1);
}
} else
{
System.err.println("Unrecognized command line option \"" + arg + "\"; try \"--help\".");
}
}

// Now process args[idx]... and do the "real work".
}
}
</pre>

Well, that's a lot of boilerplate code! And it's just this trivial example...

Also, people may want to read about the tool without installing or running it, so you fire up the word processor, or the HTML editor, or the Wiki...

But after all, you have written and documented a professional command line tool, congratulations!

But wait, now there is number of ''new'' problems:
* The code for processing the command line options is ''huge'', and most of it deals with trivial error conditions.
* There is a lot of redundancy in the command line options: There's the CLO ''implementation'', and the ''description'' appears in three places: The JAVADOC of the <code>main()</code> method, the <code>System.out.println()</code> for the "<tt>--help</tt>" option, and in the online/paper documentation.

What a maintenance nightmare!

==So how can <code>CommandLineOptions</code> help?==

Here's how it works:

'''First''', you replace the command line option parsing with a call to [http://commons.unkrig.de/javadoc/de/unkrig/commons/util/CommandLineOptions.html#parse-java.lang.String:A-java.lang.Object- CommandLineOptions.parse()]. Also add a method for each command line option, annotate it with [http://commons.unkrig.de/javadoc/de/unkrig/commons/util/annotation/CommandLineOption.html @CommandLineOption] and add its description as JAVADOC. Put the usage text into the JAVADOC comment of the "<code>main()</code>" method, with a placeholder "<tt>{@command-line-options}</tt> for the descriptions of the command line options.

'''Second''', you generate HTML documentation with the [[Doclet#The_MAIN_Doclet|MAIN doclet]]:

<javadoc doclet="de.unkrig.doclet.main.MainDoclet" docletpath="de.unkrig.doclet.main.jar" destdir="src">
<fileset file="src/com/acme/clo_demo/Diff.java" />
</javadoc>

'''Third''', you convert the HTML documentation into plain text with the [http://html2txt.unkrig.de HTML2TXT] utility:

<taskdef classpath="html2txt.jar" resource="de/unkrig/html2txt/antlib.xml" />
<html2txt>
<fileset dir="src" includes="com/acme/clo_demo/Diff.main(String[]).html" />
</html2txt>

'''Fourth''', rewrite the "<tt>--help</tt>" option to simply copy the plain text documentation to <code>System.out</code>.

==So here's the code==

<pre>
package com.acme.clo_demo;

import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.io.Writer;
import java.util.regex.Pattern;

import de.unkrig.commons.text.pattern.PatternUtil;
import de.unkrig.commons.util.CommandLineOptions;
import de.unkrig.commons.util.annotation.CommandLineOption;

/**
* A (rudimentary) re-implementation of the well-known DIFF command line utility.
*/
public class Diff {

/**
* Prints the differences between files.
* <h2>Usage:</h2>
* <dl>
* <dt>diff [ <var>option</var> ] ... <var>file1</var> <var>file2</var></dt>
* <dd>Prints the differences between <var>file1</var> and <var>file2</var>.</dd>
* <dt>diff [ <var>option</var> ] ... <var>dir1</var> <var>dir2</var></dt>
* <dd>Prints the differences between the files under <var>dir1</var> and <var>dir2</var>.</dd>
* </dl>
* <h2>Options:</h2>
* {@command-line-options}
*/
public static void main(String[] args) {

Diff diff = new Diff();

args = CommandLineOptions.parse(args, diff);

// Now process args[idx]... and do the "real work".
}

private boolean brief = false;
private boolean reportIdenticalFiles = false;
private int context = 3;

/**
* Print usage help and exit.
*/
@CommandLineOption public void
help() throws IOException {
CommandLineOptions.printResource(Diff.class, "main(String[]).txt", null, System.out);
System.exit(0);
}

/**
* Don't report the differences, only which files have changed.
*/
@CommandLineOption(name = { "-q", "--brief" }) public void
setBrief() { this.brief = true; }

/**
* Also report about files that did NOT change.
*/
@CommandLineOption(name = { "-s", "--report-identical-files"}) public void
setReportIdenticalFiles() { this.reportIdenticalFiles = true; }

/**
* Report differences in "context diff" format, with <var>number-of-lines</var> lines of context.
*/
@CommandLineOption(name = { "-C", "--Context" }) public void
setContext(int numberOfLines) { this.context = numberOfLines; }
}
</pre>

When you run it with the "<tt>--help</tt>" option, you get:

Prints the differences between files.

Usage:
======

diff [ <option> ] ... <file1> <file2>
Prints the differences between <file1> and <file2>.
diff [ <option> ] ... <dir1> <dir2>
Prints the differences between the files under <dir1> and <dir2>.

Options:
========

--help
Print usage help and exit.
-q
--brief
Don't report the differences, only which files have changed.
-s
--report-identical-files
Also report about files that did NOT change.
-C <number-of-lines>
--context <number-of-lines>
Report differences in "context diff" format, with <number-of-lines> lines
of context.

And voila - you have zero redundancy, and HTML documentation for printing and/or online presentation for free!

Using Globs

2024-05-01T20:18:28Z

Admin: Created page with "This article documents the "Globs" feature implemented in [http://commons.unkrig.de/commons-text/apidocs/index.html?de/unkrig/commons/text/pattern/package-summary.html commons.unkrig.de]. === Introduction === Surely you have used globs before (maybe even without knowing that they call them "globs"): *.txt dir/*.doc execut?r.txt Globs are a widely spread concept that is used throughout the UNIX, MICROSOFT and other "worlds". All implementations support at least th..."

This article documents the "Globs" feature implemented in [http://commons.unkrig.de/commons-text/apidocs/index.html?de/unkrig/commons/text/pattern/package-summary.html commons.unkrig.de].

=== Introduction ===

Surely you have used globs before (maybe even without knowing that they call them "globs"):

*.txt
dir/*.doc
execut?r.txt

Globs are a widely spread concept that is used throughout the UNIX, MICROSOFT and other "worlds".

All implementations support at least the following elements:

{| class="wikitable"
!Construct !!Matches
|-
|<tt>?</tt> ||Any character except the file separator ("<code>/</code>" and/or "<code>\</code>")
|-
|<tt>*</tt> ||Zero or more characters except the file separator
|-
|<tt>''x''</tt>||The character <tt>''x''</tt>
|}

Some implementations add more features:

{| class="wikitable"
!Construct !!Matches
|-
|<tt>[abc]</tt> ||Exactly one of the characters "<tt>a</tt>", "<tt>b</tt>" and "<tt>c</tt>"
|-
|<tt>[^abc]</tt><br />or<br /><tt>[!abc]</tt>||Any character ''except'' "<tt>a</tt>", "<tt>b</tt>" or "<tt>c</tt>"
|-
|<tt>[A-Za-z]</tt> ||Any (latin) letter
|-
|<tt>**</tt> ||Zero or more characters (''including'' the file separator)
|-
|<tt>\''X''</tt> ||"<tt>''X''</tt>", even if "<tt>''X''</tt>" is a meta character
|}

Since version 1.7 JAVA provides [http://docs.oracle.com/javase/7/docs/api/java/nio/file/FileSystem.html#getPathMatcher%28java.lang.String%29 its own implementation] of "glob matching", which adds another (quite uncommon) construct:

{| class="wikitable"
!Construct !!Matches
|-
|<tt>{''alpha'',''beta'',''gamma''}</tt>||Any of "<tt>alpha</tt>", "<tt>beta</tt>" or "<tt>gamma</tt>"
|}

All in all, globs are very practical, though not very powerful. This is why <code>de.unkrig.commons</code> provides yet another implementation, as follows:

=== Regular expressions features ===

First,
[http://commons.unkrig.de/commons-text/apidocs/index.html?de/unkrig/commons/text/pattern/Pattern2.html <code>de.unkrig.commons.text.pattern.Pattern2</code>]
combines the simplicity of globs with the full power of
[http://docs.oracle.com/javase/7/docs/api/index.html?java/util/regex/Pattern.html JAVA regular expressions].
It does so by modifying a few characters in the glob before feeding it to <code>java.util.text.pattern.Pattern.compile()</code>, making that effectively a glob compiler:

{| class="wikitable"
!Glob construct!!Regex construct !!Matches
|-
|<tt>?</tt> ||<tt>[^/\\!]*</tt>||Any character except the file separator and "!"
|-
|<tt>*</tt> ||<tt>[^/\\!]*</tt>||Zero or more characters except the file separator and "!"
|-
|<tt>**</tt> ||<tt>[^!]*</tt> ||Zero or more characters except "!"
|-
|<tt>***</tt> ||<tt>.*</tt> ||Zero or more characters
|-
|<tt>.</tt>||<tt>\.</tt>||The dot is a literal (not a character class as in a regular expression)
|-
|}

If you have not yet worked with regular expressions: JAVA regular expressions are very powerful and introduce many constructs and meta characters. Find the complete reference documentation [http://docs.oracle.com/javase/7/docs/api/index.html?java/util/regex/Pattern.html here].

Since "<tt>?</tt>" and "<tt>*</tt>" are not quantifiers as in regular expression ("<tt>?</tt>" == zero-or-one, "<tt>*</tt>" == zero-or-more), one has to use "<tt>{0,1}</tt>" and "<tt>{0,}</tt>" instead. The alternative notation for "<tt>.</tt>" ("any character") is "<tt>[^]</tt>".

Find the reference documentation [http://commons.unkrig.de/javadoc/index.html?de/unkrig/commons/text/pattern/Pattern2.html here].

The API of
[http://commons.unkrig.de/commons-text/apidocs/index.html?de/unkrig/commons/text/pattern/Pattern2.html <code>de.unkrig.commons.text.pattern.Pattern2</code>]
is totally compatible with that of
[http://docs.oracle.com/javase/7/docs/api/index.html?java/util/regex/Pattern.html <code>java.util.pattern.Pattern</code>],
plus it adds a new compilation Flag <code>Pattern2.WILDCARD</code> that modifies the expression syntax from regex to globs.

=== Includes-Excludes ===

Second, it adds ''includes-excludes''. This involves two new meta characters, "<code>,</code>" and "<code>~</code>":
{| class="wikitable"
!Construct !!Matches
|-
|<tt>''pattern1'',''pattern2''</tt>||Any string that matches ''pattern1'' or ''pattern2''
|-
|<tt>''pattern1''~''pattern2''</tt>||Any string that matches ''pattern1'', but not ''pattern2''
|-
|<tt>~''pattern1''</tt> ||Any string that does ''not'' match ''pattern1''
|-
|<tt>''pattern1'',''pattern2''~''pattern3''~''pattern4'',''pattern5''</tt>||Any string that matches ''pattern1'' or ''pattern2'', but not ''pattern3'' nor ''pattern4''; plus any string that matches ''pattern5''
|}

This may sound complicated, but the very simple rule is: The patterns are applied ''right-to-left'', and the first match determines the result.

This comes with [http://commons.unkrig.de/javadoc/index.html?de/unkrig/commons/text/pattern/Glob.html <tt>de.unkrig.commons.text.pattern.Glob.compile()</tt>] and the new [http://commons.unkrig.de/javadoc/index.html?de/unkrig/commons/text/pattern/Glob.html <tt>INCLUDES_EXCLUDES</tt>] compilation flag.

=== Replacements ===

Third, it adds ''replacements''. This involves one new meta character, "<tt>=</tt>":

{| class="wikitable"
!Construct !!Matches !!Replaces with
|-
|<tt>*.c=$0.bak</tt> ||Any string ending with "<tt>.c</tt>"||The original string plus "<tt>.bak</tt>" ("<tt>$0</tt>" represents the "entire match")
|-
|<tt>(*).(*)=$1.$2$2</tt>||Any string containing a dot ||The original string, with the file name extension doubled
|}

This comes with the [http://commons.unkrig.de/javadoc/index.html?de/unkrig/commons/text/pattern/Glob.html <tt>Glob.replace()</tt>] API.

Notice that "<tt>$</tt>" is a meta character ''only in the replacement''.

Also notice that when combining replacements with includes-excludes (see above), replacements are specific for ''each'' include (while it does not make any sense to use replacements with excludes, though).

=== Conclusion ===

All these features can be combined mercilessly, e.g.:

*=$0$0~*.bak
(*).docx{0,1}=$1.txt~*blabla*

Using it is simple:

import de.unkrig.commons.text.pattern.Glob;
import de.unkrig.commons.text.pattern.Pattern2;

Glob glob = Glob.compile("*.c=$0.C,*.h=$0.H", Pattern2.WILDCARD | Glob.INCLUDES_EXCLUDES | Glob.REPLACEMENT);
glob.match("foo.c"); // returns true
glob.replace("foo.h"); // returns "foo.H"
glob.replace("foo.cpp"); // returns null

Remember: The <tt>Pattern2.WILDCARD</tt> modifies the regex compilation to understand wildcard characters. <tt>Glob.INCLUDES_EXCLUDES</tt> activates the recognition of "<tt>,</tt>" and "<tt>~</tt>". Finally, <tt>Glob.REPLACEMENT</tt> activates the recognition of "<tt>=</tt>".

Unkrig.de

2024-05-01T19:55:39Z

Admin: Admin moved page Unkrig.de:Unkrig.de to Unkrig.de

 
<div align="center"><font size="+6"><b>Welcome to unkrig.de!</b></font><br><br><font color="#777">''Where the fine software grows''</font></div>
 

[[image:Javawordcloud.png|right]]

== Preamble ==

Hello out there!

I am a professional programmer, and when I have time I work on several cool open source projects. Find them useful, interesting, inspiring - or contribute! To contact me, send email to 'arno att unkrig dott de'.

Cheers, Arno

== Larger Projects ==

=== [https://janino-compiler.github.io/janino/ Janino] ===
: A super-small, super-fast Java™ compiler for embedded applications where you want to compile code on-the-fly into byte code which is executed in the running JVM.

=== [https://github.com/aunkrig/lfr LFR - Lightning-fast Regular Expressions for Java] ===
: A 99.9%-complete reimplementation of <code>java.util.regex</code> ("JUR") with better <code>match()</code> and <code>find()</code> performance.

=== [[Antology]] ===
: Some contributions to [http://ant.apache.org APACHE ANT], e.g. the <code><swingDialog></code> task which significantly enhances ANT's <code><input></code> task.

=== [[Zz.unkrig.de|ZZ Tools]] ===
: Enhanced versions of the widely known DIFF, FIND, GREP and PATCH command-line tools, which handle not only directories and files, but also archive and compressed files, and even nested archive and compressed files. They can even disassemble Java <code>.class</code> files on-the fly and operate on the disassembly.

=== [[Cs-contrib.unkrig.de|CheckStyle Contributions]] ===
: Additional checks, filters and quickfixes for [http://checkstyle.sourceforge.net/ CheckStyle] and [http://eclipse-cs.sourceforge.net/ Eclipse-CS].

=== [[Commons.unkrig.de]] ===
: A versatile Java™ library, including a highly flexible HTTP and FTP server.

== Smaller Projects ==

=== [https://github.com/aunkrig/autoauth AUTOAUTH] ===

An HTTP proxy that handles proxy authentication.

=== [[Doclet|Doclets]] ===

Doclets are a way to re-use the JAVADOC tool to do other things than just generate Java API documentation. I wrote a few of them for different purposes:

===== [[ANT doclet|The ANT Doclet]] =====
: Generates JAVADOC-like HTML documentation for an ANTLIB, e.g. for [[Antology]] and the [[Zz.unkrig.de|ZZ tools]].

===== [[Cs-doclet|The CheckStyle Doclet]] =====
: Generates the metadata files for CheckStyle and eclipse-cs from 'doc tags' in the source code of your checks and filters.

===== [[JAVADOC doclet|The JAVADOC Doclet]] =====
: A re-implementation of the JAVADOC standard doclet, basically a reference to show how to use the "[[No-template|no-template]]" framework.

===== [[MAIN doclet|The MAIN Doclet]] =====
: Generates HTML documentation for a "main()" method - useful for command line tools with a set of command line options.

=== [[Html2txt|html2txt]] ===
: A Java tool to convert HTML documents into plain text.

=== [[JDisasm|jdisasm]] ===
: A disassembler for Java .class files.

=== [[No-template|no-template]] ===
: A super-small Java library for templating, i.e. generating text files (HTML, XML, whatever) from a "template" text file.

== Retired Projects ==

These projects are no longer maintained and are only of limited use, e.g. because they work only with old Java versions.

=== [[Loggifier.unkrig.de|Loggifier]] ===
: A tool for automatic injection of logging code into Java™ class files, making it unnecessary to mess up your code with hand-written logging.

=== [[Cvstools.unkrig.de|Eclipse plug-in for extended CVS possibilities]] ===

: An ECLIPSE plug-in that adds CVS functionality that is sometimes painfully missing from ECLIPSE's built-in CVS client.

=== [[Subclipse.unkrig.de|Subclipse enhancements Eclipse plug-in]] ===

: The often-missed <code><de.unkrig.subclipse.svn></code> ANT task that uses the SUBCLIPSE client of the running ECLIPSE workbench.

Unkrig.de

2024-05-01T19:52:20Z

Admin: Admin moved page Main Page to Unkrig.de:Unkrig.de without leaving a redirect

MediaWiki:Mainpage

2024-05-01T19:50:49Z

Admin: Created page with "Unkrig.de"

Unkrig.de