[Japi-cvs] SF.net SVN: japi: [167] libs/argparser/trunk/src/net/sf/japi/io/args

[<chr...@us...>]

Revision: 167
          http://svn.sourceforge.net/japi/?rev=167&view=rev
Author:   christianhujer
Date:     2006-09-24 04:43:34 -0700 (Sun, 24 Sep 2006)

Log Message:
-----------
Cosmetic rework of argument parser library.

Modified Paths:
--------------
    libs/argparser/trunk/src/net/sf/japi/io/args/ArgParser.java
    libs/argparser/trunk/src/net/sf/japi/io/args/Command.java
    libs/argparser/trunk/src/net/sf/japi/io/args/Option.java
    libs/argparser/trunk/src/net/sf/japi/io/args/RequiredOptionsMissingException.java
    libs/argparser/trunk/src/net/sf/japi/io/args/TerminalException.java

Added Paths:
-----------
    libs/argparser/trunk/src/net/sf/japi/io/args/StringJoiner.java

Modified: libs/argparser/trunk/src/net/sf/japi/io/args/ArgParser.java
===================================================================
--- libs/argparser/trunk/src/net/sf/japi/io/args/ArgParser.java	2006-09-24 10:28:58 UTC (rev 166)
+++ libs/argparser/trunk/src/net/sf/japi/io/args/ArgParser.java	2006-09-24 11:43:34 UTC (rev 167)
@@ -25,7 +25,8 @@
 import java.lang.reflect.Method;
 import java.util.*;
 
-/** Parser for command line arguments.
+/**
+ * Parser for command line arguments.
  * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
  * TODO: arguments for options, argument conversion for the method invokation.
  */
@@ -54,6 +55,8 @@
      * This ArgParser uses {@link System#in}, {@link System#out} and {@link System#err}.
      * @param command Command to initialize and run
      * @param args Arguments to parse
+     * @throws RequiredOptionsMissingException in case an option is missing
+     * @throws TerminalException in case argument parsing was stopped
      */
     private ArgParser(final Command command, final String... args) throws TerminalException, RequiredOptionsMissingException {
         this.command = command;
@@ -73,6 +76,7 @@
 
     /**
      * Checks that all required methods have been invoked.
+     * @throws RequiredOptionsMissingException in case a required command line argument was missing
      */
     private void checkRequiredMethods() throws RequiredOptionsMissingException {
         if (requiredMethods.size() > 0) {
@@ -112,6 +116,7 @@
 
     /**
      * Parses arguments into an arguments container and invokes the Command's {@link Command#run(List<String>)} method.
+     * @throws TerminalException in case argument parsing was stopped
      */
     private void parse() throws TerminalException {
         try {

Modified: libs/argparser/trunk/src/net/sf/japi/io/args/Command.java
===================================================================
--- libs/argparser/trunk/src/net/sf/japi/io/args/Command.java	2006-09-24 10:28:58 UTC (rev 166)
+++ libs/argparser/trunk/src/net/sf/japi/io/args/Command.java	2006-09-24 11:43:34 UTC (rev 167)
@@ -23,12 +23,14 @@
 
 import java.util.List;
 
-/** Shell commands can implement this interface and make use of ArgParser.
- * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
+/**
+ * Shell commands can implement this interface and make use of ArgParser.
+ * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
  */
 public interface Command {
 
-    /** Run the command.
+    /**
+     * Run the command.
      * This method is invoked by {@link ArgParser} once it is finnished with parsing the arguments.
      * @param args the argument strings that were not parsed away by {@link ArgParser}.
      */

Modified: libs/argparser/trunk/src/net/sf/japi/io/args/Option.java
===================================================================
--- libs/argparser/trunk/src/net/sf/japi/io/args/Option.java	2006-09-24 10:28:58 UTC (rev 166)
+++ libs/argparser/trunk/src/net/sf/japi/io/args/Option.java	2006-09-24 11:43:34 UTC (rev 167)
@@ -26,8 +26,9 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 import java.lang.annotation.Target;
 
-/** Annotation to mark a method as command argument method.
- * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
+/**
+ * Annotation to mark a method as command argument method.
+ * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
  */
 @Retention(RUNTIME)
 @Target(METHOD)
@@ -43,7 +44,8 @@
     /**
      * The option names.
      * Usually this is two Strings, a single letter and a descriptive String.
-     * @note the supplied string values should contain neither spaces nor non-ascii characters.
+     * Multiple descriptive Strings as well as no single letter String are allowed.
+     * @note the supplied string values MUST consist of ASCII-letters only (match regex <code>[a-zA-Z]+</code>).
      * @return option names
      */
     String[] value();

Modified: libs/argparser/trunk/src/net/sf/japi/io/args/RequiredOptionsMissingException.java
===================================================================
--- libs/argparser/trunk/src/net/sf/japi/io/args/RequiredOptionsMissingException.java	2006-09-24 10:28:58 UTC (rev 166)
+++ libs/argparser/trunk/src/net/sf/japi/io/args/RequiredOptionsMissingException.java	2006-09-24 11:43:34 UTC (rev 167)
@@ -24,6 +24,7 @@
 
 /**
  * This exception is thrown in case required options are missing.
+ * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
  */
 public class RequiredOptionsMissingException extends Exception {
 
@@ -33,23 +34,32 @@
     /**
      * Create a RequiredOptionsMissingException.
      * @param missingOptions options that were missing.
+     * @throws IllegalArgumentException in case <var>missingOptions</var> was null or of zero length
      */
     public RequiredOptionsMissingException(@NotNull final String[] missingOptions) {
+        super(createMessage(missingOptions));
+        this.missingOptions = missingOptions.clone();
+    }
+
+    /**
+     * Creates the message.
+     * @param missingOptions options that were missing
+     * @return message string
+     * @throws IllegalArgumentException in case <var>missingOptions</var> was null or of zero length
+     */
+    private static String createMessage(final String[] missingOptions) {
         if (missingOptions == null || missingOptions.length < 1) {
             throw new IllegalArgumentException("RequiredOptionsMissingException created but no missing options given.");
         }
-        this.missingOptions = missingOptions.clone();
+        return StringJoiner.join(new StringBuilder("required options missing: "), ", ", missingOptions).toString();
     }
 
-    /** {@inheritDoc} */
-    public String toString() {
-        final StringBuilder msg = new StringBuilder("required options missing: ");
-        for (final String missingOption : missingOptions) {
-            msg.append(missingOption);
-            msg.append(", ");
-        }
-        msg.setLength(msg.length() - 2);
-        return msg.toString();
+    /**
+     * Get the options that were missing.
+     * @return options that were missing
+     */
+    public String[] getMissingOptions() {
+        return missingOptions.clone();
     }
 
 } // class RequiredOptionsMissingException

Added: libs/argparser/trunk/src/net/sf/japi/io/args/StringJoiner.java
===================================================================
--- libs/argparser/trunk/src/net/sf/japi/io/args/StringJoiner.java	                        (rev 0)
+++ libs/argparser/trunk/src/net/sf/japi/io/args/StringJoiner.java	2006-09-24 11:43:34 UTC (rev 167)
@@ -0,0 +1,192 @@
+package net.sf.japi.io.args;
+
+import java.io.IOException;
+import java.util.Iterator;
+
+/**
+ * Class with utility methods for joining strings.
+ * The class is intended to be as flexible and convenient as possible.
+ * Therefore it mostly operates on {@link CharSequence} instead of {@link String}, so you're free to use other kinds of "Strings" as well, not only {@link String} itself.
+ * Apart from methods that create a new {@link String}, you will also find methods that work on {@link Appendable}s so you can use these methods to append on implementations of {@link Appendable}.
+ * <p />
+ * Because {@link Appendable#append(CharSequence)} throws {@link IOException}, methods that work on {@link Appendable} have been overloaded to work on certain known {@link Appendable}-implementations that do not throw an {@link IOException} when appending.
+ * Currently this is namely {@link StringBuilder} and {@link StringBuffer}.
+ * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
+ */
+public final class StringJoiner {
+
+    /**
+     * Utility class - do not instanciate.
+     */
+    private StringJoiner() {
+    }
+
+    /**
+     * Join Strings.
+     * @param delim delimiter to use for joining the strings
+     * @param strings Strings to join
+     * @return joined string
+     */
+    public static String join(final CharSequence delim, final CharSequence... strings) {
+        return join(new StringBuilder(), delim, strings).toString();
+    }
+
+    /**
+     * Join Strings.
+     * @param delim delimiter to use for joining the strings
+     * @param strings Strings to join
+     * @return joined string
+     */
+    public static String join(final CharSequence delim, final Iterable<? extends CharSequence> strings) {
+        return join(new StringBuilder(), delim, strings).toString();
+    }
+
+    /**
+     * Join Strings.
+     * @param delim delimiter to use for joining the strings
+     * @param strings Strings to join
+     * @return joined string
+     */
+    public static String join(final CharSequence delim, final Iterator<? extends CharSequence> strings) {
+        return join(new StringBuilder(), delim, strings).toString();
+    }
+
+    /**
+     * Join Strings to an Appendable.
+     * @param dest Appendable to join Strings to
+     * @param delim delimiter to use for joining the strings
+     * @param strings Strings to join
+     * @return Appendable
+     */
+    public static Appendable join(final Appendable dest, final CharSequence delim, final CharSequence... strings) throws IOException {
+        for (int i = 0; i < strings.length; i++) {
+            if (i > 0) {
+                dest.append(delim);
+            }
+            dest.append(strings[i]);
+        }
+        return dest;
+    }
+
+    /**
+     * Join Strings to an Appendable.
+     * @param dest Appendable to join Strings to
+     * @param delim delimiter to use for joining the strings
+     * @param strings Strings to join
+     * @return Appendable
+     */
+    public static Appendable join(final Appendable dest, final CharSequence delim, final Iterable<? extends CharSequence> strings) throws IOException {
+        return join(dest, delim, strings.iterator());
+    }
+
+    /**
+     * Join Strings to an Appendable.
+     * @param dest Appendable to join Strings to
+     * @param delim delimiter to use for joining the strings
+     * @param strings Strings to join
+     * @return Appendable
+     */
+    public static Appendable join(final Appendable dest, final CharSequence delim, final Iterator<? extends CharSequence> strings) throws IOException {
+        if (strings.hasNext()) {
+            dest.append(strings.next());
+        }
+        while (strings.hasNext()) {
+            dest.append(delim);
+            dest.append(strings.next());
+        }
+        return dest;
+    }
+
+    /**
+     * Join Strings to a StringBuilder.
+     * @param dest StringBuilder to join Strings to
+     * @param delim delimiter to use for joining the strings
+     * @param strings Strings to join
+     * @return supplied StringBuilder (<var>dest</var>)
+     */
+    public static StringBuilder join(final StringBuilder dest, final CharSequence delim, final CharSequence... strings) {
+        for (int i = 0; i < strings.length; i++) {
+            if (i > 0) {
+                dest.append(delim);
+            }
+            dest.append(strings[i]);
+        }
+        return dest;
+    }
+
+    /**
+     * Join Strings to a StringBuilder.
+     * @param dest StringBuilder to join Strings to
+     * @param delim delimiter to use for joining the strings
+     * @param strings Strings to join
+     * @return supplied StringBuilder (<var>dest</var>)
+     */
+    public static StringBuilder join(final StringBuilder dest, final CharSequence delim, final Iterable<? extends CharSequence> strings) {
+        return join(dest, delim, strings.iterator());
+    }
+
+    /**
+     * Join Strings to a StringBuilder.
+     * @param dest StringBuilder to join Strings to
+     * @param delim delimiter to use for joining the strings
+     * @param strings Strings to join
+     * @return supplied StringBuilder (<var>dest</var>)
+     */
+    public static StringBuilder join(final StringBuilder dest, final CharSequence delim, final Iterator<? extends CharSequence> strings) {
+        if (strings.hasNext()) {
+            dest.append(strings.next());
+        }
+        while (strings.hasNext()) {
+            dest.append(delim);
+            dest.append(strings.next());
+        }
+        return dest;
+    }
+
+    /**
+     * Join Strings to a StringBuffer.
+     * @param dest StringBuffer to join Strings to
+     * @param delim delimiter to use for joining the strings
+     * @param strings Strings to join
+     * @return supplied StringBuffer (<var>dest</var>)
+     */
+    public static StringBuffer join(final StringBuffer dest, final CharSequence delim, final CharSequence... strings) {
+        for (int i = 0; i < strings.length; i++) {
+            if (i > 0) {
+                dest.append(delim);
+            }
+            dest.append(strings[i]);
+        }
+        return dest;
+    }
+
+    /**
+     * Join Strings to a StringBuffer.
+     * @param dest StringBuffer to join Strings to
+     * @param delim delimiter to use for joining the strings
+     * @param strings Strings to join
+     * @return supplied StringBuffer (<var>dest</var>)
+     */
+    public static StringBuffer join(final StringBuffer dest, final CharSequence delim, final Iterable<? extends CharSequence> strings) {
+        return join(dest, delim, strings.iterator());
+    }
+
+    /**
+     * Join Strings to a StringBuffer.
+     * @param dest StringBuffer to join Strings to
+     * @param delim delimiter to use for joining the strings
+     * @param strings Strings to join
+     * @return supplied StringBuffer (<var>dest</var>)
+     */
+    public static StringBuffer join(final StringBuffer dest, final CharSequence delim, final Iterator<? extends CharSequence> strings) {
+        if (strings.hasNext()) {
+            dest.append(strings.next());
+        }
+        while (strings.hasNext()) {
+            dest.append(delim);
+            dest.append(strings.next());
+        }
+        return dest;
+    }
+
+} // class StringJoiner


Property changes on: libs/argparser/trunk/src/net/sf/japi/io/args/StringJoiner.java
___________________________________________________________________
Name: svn:mime-type
   + text/plain
Name: svn:eol-style
   + LF

Modified: libs/argparser/trunk/src/net/sf/japi/io/args/TerminalException.java
===================================================================
--- libs/argparser/trunk/src/net/sf/japi/io/args/TerminalException.java	2006-09-24 10:28:58 UTC (rev 166)
+++ libs/argparser/trunk/src/net/sf/japi/io/args/TerminalException.java	2006-09-24 11:43:34 UTC (rev 167)
@@ -22,6 +22,7 @@
 
 /**
  * This exception is thrown when an argument method is terminal, i.e. stops further command processing.
+ * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
  */
 public class TerminalException extends Exception {
 


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.