update documentation for cli

issue #31

README.md

@@ -1,11 +1,11 @@
-Kumo
-==============
+# Kumo
 
 Kumo's goal is to create a powerful and user friendly Word Cloud API in Java. Kumo directly generates an image file without the need to create an applet as many other libraries do.
 
 Please feel free to jump in and help improve Kumo! There are many places for performance optimization in Kumo!
 
-**Current Features**
+### Current Features
+
 - Draw Rectangle, Circle or Image Overlay word clouds. Image Overlay will draw words over all non-transparent pixels.
 - Linear, Square-Root Font Scalars. Fully extendable.
 - Variable Font Sizes.
@@ -18,17 +18,20 @@ Please feel free to jump in and help improve Kumo! There are many places for per
 - Layered Word Clouds. Overlay multiple word clouds.
 - WhiteSpace and Chinese Word Tokenizer. Fully extendable. 
 - Frequency Analyzer to tokenize, filter and compute word counts.
+- Command Line Interface
+
+### Available from Maven Central
 
-**Available from Maven Central**
 ```xml
 <dependency>
     <groupId>com.kennycason</groupId>
     <artifactId>kumo</artifactId>
-    <version>1.5</version>
+    <version>1.6</version>
 </dependency>
 ```
 
-**Screenshots**
+### Screenshots
+
 <table>
 <tr><td>
 <img src="output/whale_wordcloud_large_impact.png?raw=true" width="300"/>
@@ -72,7 +75,7 @@ Please feel free to jump in and help improve Kumo! There are many places for per
 </td></tr>
 </table>
 
-**Examples**
+### Examples
 
 Example to generate a Word Cloud on top of an image.
 
@@ -267,7 +270,7 @@ parallelLayeredWordCloud.writeToFile("parallelBubbleText.png");
 
 Refer to JPanelDemo.java for an example integrating into a JPanel.
 
-**Tokenizers**
+### Tokenizers
 
 Tokenizers are the code that splits a sentence/text into a list of words. Currently only two tokenizers are built into Kumo.
 To add your own just create a class that override the `Tokenizer` interface and call the `FrequencyAnalyzer.setTokenizer()` or `FrequencyAnalyzer.addTokenizer()`.
@@ -278,7 +281,7 @@ To add your own just create a class that override the `Tokenizer` interface and
 | ChineseWordTokenizer |
 
 
-**Filters**
+### Filters
 
 After tokenization, filters are applied to each word to determine whether or not should be omitted from the word list. 
 
@@ -292,7 +295,7 @@ To add set the filter, call `FrequencyAnalyzer.setFilter()` or `FrequencyAnalyze
 | StopWordFilter | Internally used, the FrequencyAnalyzer makes this filter easy to use via `FrequencyAnalyzer.setStopWords()`. |
 | WordSizeFilter | Internally used, the FrequencyAnalyzer makes this filter easy to use via `FrequencyAnalyzer.setMinWordLength()` and `FrequencyAnalyzer.setMaxWordLength()`. |
 
-**Normalizers**
+### Normalizers
 
 After word tokenization and filtering has occurred you can further transform each word via a normalizer.
 The default normalizer ia `lowerCase•characterStripping*trimToEmpty(word)`, the normalizer is even named `DefaultNormalizer`
@@ -309,3 +312,69 @@ To add set the normalizer, call `FrequencyAnalyzer.setNormalizer()` or `Frequenc
 | StringToHexNormalizer | Converts each character to it's hex value and concatenates them. |
 | DefaultNormalizer | Combines the TrimToEmptyNormalizer, CharacterStrippingNormalizer, and LowerCaseNormalizer. |
 | BubbleTextNormalizer | Replaces A-Z,a-z with characters enclosed in Bubbles ⓐ-ⓩⒶ-Ⓩ (requires a supporting font) |
+
+
+### Command Line Interface (CLI)
+
+Kumo can now be accessed via CLI. It is not quite as flexible as the programmatic interface yet but should support most of the common needs.
+
+The CLI Documentation can be found [here](https://raw.githubusercontent.com/kennycason/kumo/master/CLI.md).
+
+The below examples assume you have the jar installed under the name of "kumo". To install via Brew run the following command.
+
+`brew install https://raw.githubusercontent.com/kennycason/kumo/master/script/brew.rb`
+
+Examples:
+
+Create a standard word cloud.
+```
+kumo --input "https://en.wikipedia.org/wiki/Nintendo" --output "/tmp/wordcloud.png"
+```
+
+Create a standard word cloud excluding stop words.
+```
+kumo --input "https://en.wikipedia.org/wiki/Nintendo" --output "/tmp/wordcloud.png" --stop-words "nintendo,the"
+```
+
+Create a standard word cloud with a limited word count.
+```
+kumo --input "https://en.wikipedia.org/wiki/Nintendo" --output "/tmp/wordcloud.png" --word-count 10
+```
+
+Create a standard word cloud with a custom width and height.
+```
+kumo --input "https://en.wikipedia.org/wiki/Nintendo" --output "/tmp/wordcloud.png" --width 256 --height 256
+```
+
+Create a standard word cloud with custom font configuration.
+```
+kumo --input "https://en.wikipedia.org/wiki/Nintendo" --output "/tmp/wordcloud.png" --font-scalar sqrt --font-type Impact --font-weight plain --font-size-min 4 --font-size-max 60
+```
+
+Create a standard word cloud with a custom shape.
+```
+kumo --input "https://en.wikipedia.org/wiki/Nintendo" --output "/tmp/wordcloud.png" --width 990 --height 618 --background "https://raw.githubusercontent.com/kennycason/kumo/master/src/test/resources/backgrounds/whale.png
+```
+
+Create a standard word cloud with a custom color palette.
+```
+kumo --input "https://en.wikipedia.org/wiki/Nintendo" --output "/tmp/wordcloud.png" --color "(255,0,0),(0,255,0),(0,0,255)"
+```
+```
+kumo --input "https://en.wikipedia.org/wiki/Nintendo" --output "/tmp/wordcloud.png" --color "(0xffffff),(0xcccccc),(0x999999),(0x666666),(0x333333)"
+```
+
+Create a standard word cloud using a Chinese tokenizer
+```
+kumo --input "https://zh.wikipedia.org/wiki/%E4%BB%BB%E5%A4%A9%E5%A0%82" --output "/tmp/wordcloud.png" --tokenizer chinese
+```
+
+Create a polar word cloud
+```
+kumo --input "https://en.wikipedia.org/wiki/Nintendo,https://en.wikipedia.org/wiki/PlayStation" --output "/tmp/nintendo_vs_playstation.png" --type polar --color "(0x00ff00),(0x00dd00),(0x007700)|(0xff0000),(0xdd0000),(0x770000)"
+```
+
+Create a layered word cloud
+```
+kumo --input "https://www.haskell.org/, https://en.wikipedia.org/wiki/Haskell_(programming_language)" --output "/tmp/nintendo_vs_playstation.png" --type layered --background "https://raw.githubusercontent.com/kennycason/kumo/master/src/test/resources/backgrounds/haskell_1.bmp,https://raw.githubusercontent.com/kennycason/kumo/master/src/test/resources/backgrounds/haskell_2.bmp" --color "(0xFA6C07),(0xFF7614),(0xFF8936)|(0x080706),(0x3B3029),(0x47362A)"
+```

pom.xml

@@ -9,7 +9,7 @@
     <name>${project.artifactId}</name>
     <description>Kumo's goal is to create a powerful and user friendly Word Cloud API in Java. Kumo directly generates an image file without the need to create an applet (as many other libraries do).</description>
     <url>https://github.com/kennycason/kumo</url>
-    <version>1.5</version>
+    <version>1.6</version>
     
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

script/brew.rb

@@ -0,0 +1,22 @@
+class Kumo < Formula
+  desc "Kumo: Word Clouds in Java"
+  homepage "https://github.com/kennycason/kumo"
+  url "http://search.maven.org/remotecontent?filepath=com/kennycason/kumo/1.6/kumo-1.6.jar"
+  sha256 "<TO_ADD>"
+
+  def install
+    libexec.install "kumo-1.6.jar"
+    bin.write_jar_script libexec/"kumo-1.6.jar", "kumo"
+    puts "Finished installing kumo 1.6"
+  end
+
+  def server_script(server_jar); <<-EOS.undent
+    #!/bin/bash
+    exec java -cp #{server_jar} com.kennycason.kumo.cli.KumoCli "$@"
+  EOS
+  end
+
+  test do
+    pipe_output("#{bin}/kumo --version", "Test Kumo version command")
+  end
+end

src/main/java/com/kennycason/kumo/cli/CliParameters.java

@@ -23,6 +23,9 @@ import static org.apache.commons.lang3.StringUtils.isBlank;
  */
 public class CliParameters {
 
+    @Parameter(names = "--version", description = "Print the current version of Kumo", arity = 1)
+    private boolean printVersion = false;
+
     @Parameter(names = "--type", description = "The type of word cloud to generate.", converter = TypeConverter.class)
     private Type type = Type.STANDARD;
 
@@ -96,6 +99,10 @@ public class CliParameters {
     @Parameter(names = "--tokenizer", description = "Determine where to start drawing text to the word cloud.", converter = TokenizerConverter.class)
     private TokenizerType tokenizer = TokenizerType.WHITE_SPACE;
 
+    public boolean isPrintVersion() {
+        return printVersion;
+    }
+
     public List<String> getBackgrounds() {
         return backgrounds;
     }

src/main/java/com/kennycason/kumo/cli/KumoCli.java

@@ -45,6 +45,12 @@ public class KumoCli {
 
     public void runWithArguments(final String[] args) {
         new JCommander(cliParameters).parse(args);
+
+        if (cliParameters.isPrintVersion()) {
+            System.out.println("Kumo Version 1.6"); // TODO do not hard code.
+            return;
+        }
+
         switch (cliParameters.getType()) {
             case STANDARD:
                 buildStandardWordCloud();

src/test/java/com/kennycason/kumo/cli/KumoCliITest.java

@@ -124,7 +124,7 @@ public class KumoCliITest {
     @Test
     public void polar() {
         KumoCli.main(new String[] {
-                "--input", "https://en.wikipedia.org/wiki/Nintendo,https://en.wikipedia.org/wiki/PlayStation",
+                "--input", "https://en.wikipedia.org/wiki/Nintendo, https://en.wikipedia.org/wiki/PlayStation",
                 "--output", "/tmp/nintendo_vs_playstation.png",
                 "--type", "polar",
                 "--color", "(0x00ff00),(0x00dd00),(0x007700)|(0xff0000),(0xdd0000),(0x770000)"
@@ -134,7 +134,7 @@ public class KumoCliITest {
     @Test
     public void layered() {
         KumoCli.main(new String[] {
-                "--input", "https://www.haskell.org/,https://en.wikipedia.org/wiki/Haskell_(programming_language)",
+                "--input", "https://www.haskell.org/, https://en.wikipedia.org/wiki/Haskell_(programming_language)",
                 "--output", "/tmp/haskell_layered.png",
                 "--background", "https://raw.githubusercontent.com/kennycason/kumo/master/src/test/resources/backgrounds/haskell_1.bmp,https://raw.githubusercontent.com/kennycason/kumo/master/src/test/resources/backgrounds/haskell_2.bmp",
                 "--type", "layered",