improvements, documentation changes

Author: codebox

.gitignore

@@ -3,6 +3,8 @@
 .idea
 node_modules
 *.iml
+*.ipr
+*.iws
 build
 .gradle
 gradle*

README.md

@@ -1,4 +1,45 @@
 # Homoglyphs
+
+## Java Quick Start
+
+Include the Homoglyph library in your project by downloading it from Maven Central:
+
+```xml
+<dependency>
+    <groupId>net.codebox</groupId>
+    <artifactId>homoglyph</artifactId>
+    <version>1.0.2</version>
+</dependency>
+```
+
+Then use the `HomoglyphBuilder` class to build a `Homoglyph` object, and call its `search()` method with the text you want
+to search, and the word/s you want to search for:
+
+```java
+String textToSearch = "Get free ϲrEd1ᴛ";
+String[] bannedWords = new String[]{"credit"};
+Homoglyph homoglyph = HomoglyphBuilder.build();
+List<SearchResult> results = homoglyph.search(textToSearch, bannedWords);
+```
+
+## JavaScript Quick Start
+
+Include the Homoglyph library in your project by downloading it from NPM:
+
+```
+npm install homoglyph-search
+```
+
+Then call the module's `search()` function with the text you want to search, and the word/s you want to search for:
+
+```javascript
+var homoglyphSearch = require('homoglyph-search');
+var bannedWords = ['credit'];
+var textToSearch = 'Get free ϲrEd1ᴛ';
+var results = homoglyphSearch.search(textToSearch, bannedWords);
+```
+
+## Background
 Homoglyphs are characters with different meanings, that look similar/identical to each other - like the digit '0' and the capital letter 'O' for example.
 
 Homoglyphs within a single alphabet tend to be rare for obvious reasons. These days, however, the internet runs on Unicode which means that it is possible to mix the letters from many [different languages](http://www.unicode.org/cldr/charts/latest/supplemental/languages_and_scripts.html) together in one place, massively increasing the number of homoglyphs.

build.gradle

@@ -1,11 +1,15 @@
 group = "net.codebox"
-version = "1.0.0"
+version = "1.0.2"
 
 apply plugin: 'java'
 apply plugin: 'idea'
 apply plugin: 'maven'
 apply plugin: 'signing'
 
+sourceSets.main.resources {
+    srcDirs = ["raw_data"]; include "char_codes.txt"
+}
+
 repositories {
     mavenCentral()
 }

src/main/java/net/codebox/homoglyph/Homoglyph.java

@@ -1,9 +1,5 @@
 package net.codebox.homoglyph;
 
-import java.io.BufferedReader;
-import java.io.FileNotFoundException;
-import java.io.FileReader;
-import java.io.IOException;
 import java.util.*;
 
 /**
@@ -64,7 +60,6 @@ public List<SearchResult> search(final String text, final String... targetWords)
         return search(text, Arrays.asList(targetWords));
     }
 
-
     private Collection<SearchResult> checkForWord(final CodePoints text, final CodePoints targetWord) {
         final Collection<SearchResult> results = new ArrayList<SearchResult>();
 
@@ -104,6 +99,11 @@ public SearchResult(final int index, final String match, final String word){
         public int index;
         public String match;
         public String word;
+
+        @Override
+        public String toString() {
+            return String.format("'%s' at position %s matches '%s'", match, index, word);
+        }
     }
 
     public static class CodePoints{
@@ -165,27 +165,4 @@ public Set<Integer> lookup(final int cp){
         }
     }
 
-    public static List<Set<Integer>> parseCharCodesFile(final String path) throws IOException {
-        final List<Set<Integer>> homoglyphs = new ArrayList<Set<Integer>>();
-        final BufferedReader reader = new BufferedReader(new FileReader(path));
-
-        String line;
-        while((line = reader.readLine()) != null){
-            line = line.trim();
-            if (line.startsWith("#") || line.length() == 0){
-                continue;
-            }
-            final Set<Integer> set = new HashSet<Integer>();
-            for (String charCode : line.split(",")) {
-                try {
-                    set.add(Integer.parseInt(charCode, 16));
-                } catch (NumberFormatException ex){
-                    // ignore badly formatted lines
-                }
-            }
-            homoglyphs.add(set);
-        }
-
-        return homoglyphs;
-    }
 }

src/main/java/net/codebox/homoglyph/HomoglyphBuilder.java

@@ -0,0 +1,77 @@
+package net.codebox.homoglyph;
+
+import java.io.*;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import java.util.*;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
+/**
+ * Helper class providing methods that supply populated Homoglyph objects.
+ *
+ * @author Rob Dawson
+ */
+public class HomoglyphBuilder {
+    private static final String CHAR_CODES_FILE = "/char_codes.txt";
+
+    /**
+     * Parses the bundled char_codes.txt file, and uses it to construct a populated Homoglyph object.
+     *
+     * @return a Homoglyph object populated using the contents of the char_codes.txt file
+     *
+     * @throws MissingResourceException if the char_codes.txt file is missing
+     * @throws IOException if the char_codes.txt exists but cannot be read
+     */
+    public static Homoglyph build() throws IOException {
+        final InputStream is = HomoglyphBuilder.class.getResourceAsStream(CHAR_CODES_FILE);
+        if (is == null){
+            throw new MissingResourceException("Unable to read " + CHAR_CODES_FILE,
+                    HomoglyphBuilder.class.getName(), CHAR_CODES_FILE);
+        }
+        return build(new InputStreamReader(is));
+    }
+
+    /**
+     * Parses the specified file and uses it to construct a populated Homoglyph object.
+     *
+     * @return a Homoglyph object populated using the contents of the specified file
+     *
+     * @throws IOException if the specified file cannot be read
+     */
+    public static Homoglyph build(final String path) throws IOException {
+        return build(new FileReader(path));
+    }
+
+    /**
+     * Consumes the supplied Reader and uses it to construct a populated Homoglyph object.
+     *
+     * @return a Homoglyph object populated using the data returned by the Reader object
+     *
+     * @throws IOException if the specified Reader cannot be read
+     */
+    public static Homoglyph build(final Reader reader) throws IOException {
+        final List<Set<Integer>> homoglyphs = new ArrayList<Set<Integer>>();
+        final BufferedReader bufferedReader = new BufferedReader(reader);
+
+        String line;
+        while((line = bufferedReader.readLine()) != null){
+            line = line.trim();
+            if (line.startsWith("#") || line.length() == 0){
+                continue;
+            }
+            final Set<Integer> set = new HashSet<Integer>();
+            for (String charCode : line.split(",")) {
+                try {
+                    set.add(Integer.parseInt(charCode, 16));
+                } catch (NumberFormatException ex){
+                    // ignore badly formatted lines
+                }
+            }
+            homoglyphs.add(set);
+        }
+
+        return new Homoglyph(homoglyphs);
+    }
+
+}

src/test/java/net/codebox/homoglyph/HomoglyphDataTest.java

@@ -1,12 +1,10 @@
 package net.codebox.homoglyph;
 
-import org.junit.Assert;
 import org.junit.Before;
 import org.junit.Test;
 
 import java.io.IOException;
 import java.util.Arrays;
-import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
@@ -46,7 +44,7 @@ public void testMixedCase(){
     }
 
     private void check(String text, String targetWord){
-        List<Homoglyph.SearchResult> r = homoglyph.search(text, Arrays.asList(targetWord));
+        List<SearchResult> r = homoglyph.search(text, Arrays.asList(targetWord));
         assertEquals(1, r.size());
         assertEquals(targetWord, r.get(0).word);
     }

src/test/java/net/codebox/homoglyph/HomoglyphLogicTest.java

@@ -1,6 +1,5 @@
 package net.codebox.homoglyph;
 
-import org.junit.Assert;
 import org.junit.Before;
 import org.junit.Test;
 
@@ -34,69 +33,69 @@ public void setup() throws IOException {
 
     @Test
     public void whenTextDoesNotContainAnyTargetWords_thenNoMatchesFound(){
-        List<Homoglyph.SearchResult> r = homoglyph.search("Nothing to see here", "TARGET");
+        List<SearchResult> r = homoglyph.search("Nothing to see here", "TARGET");
         assertEquals(0, r.size());
     }
 
     @Test
     public void whenTextIdenticalToTargetWord_thenMatchFound(){
-        List<Homoglyph.SearchResult> r = homoglyph.search("SOIL", "SOIL");
+        List<SearchResult> r = homoglyph.search("SOIL", "SOIL");
         assertEquals(1, r.size());
         checkResult(r.get(0), 0, "SOIL", "SOIL");
     }
 
     @Test
     public void whenTextContainsTargetWord_thenMatchFound(){
-        List<Homoglyph.SearchResult> r = homoglyph.search("I have SOIL in my garden", "SOIL");
+        List<SearchResult> r = homoglyph.search("I have SOIL in my garden", "SOIL");
         assertEquals(1, r.size());
         checkResult(r.get(0), 7, "SOIL", "SOIL");
     }
 
     @Test
     public void whenTextContainsOneOfTheTargetWords_thenMatchFound(){
-        List<Homoglyph.SearchResult> r = homoglyph.search("I have SOIL in my garden", "CHEESE", "SOIL", "FALCONS");
+        List<SearchResult> r = homoglyph.search("I have SOIL in my garden", "CHEESE", "SOIL", "FALCONS");
         assertEquals(1, r.size());
         checkResult(r.get(0), 7, "SOIL", "SOIL");
     }
 
     @Test
     public void whenTargetWordContainsHomoglyphs_thenMatchFound(){
-        List<Homoglyph.SearchResult> r = homoglyph.search("I have 501L in my garden", Arrays.asList("CHEESE", "SOIL", "FALCONS"));
+        List<SearchResult> r = homoglyph.search("I have 501L in my garden", Arrays.asList("CHEESE", "SOIL", "FALCONS"));
         assertEquals(1, r.size());
         checkResult(r.get(0), 7, "SOIL", "501L");
     }
 
     @Test
     public void whenTargetWordIsAtStartOfText_thenMatchFound(){
-        List<Homoglyph.SearchResult> r = homoglyph.search("FALC0N5 fly", Arrays.asList("CHEESE", "SOIL", "FALCONS"));
+        List<SearchResult> r = homoglyph.search("FALC0N5 fly", Arrays.asList("CHEESE", "SOIL", "FALCONS"));
         assertEquals(1, r.size());
         checkResult(r.get(0), 0, "FALCONS", "FALC0N5");
     }
 
     @Test
     public void whenTargetWordIsAtEndOfText_thenMatchFound(){
-        List<Homoglyph.SearchResult> r = homoglyph.search("I like FALC0N5", Arrays.asList("CHEESE", "SOIL", "FALCONS"));
+        List<SearchResult> r = homoglyph.search("I like FALC0N5", Arrays.asList("CHEESE", "SOIL", "FALCONS"));
         assertEquals(1, r.size());
         checkResult(r.get(0), 7, "FALCONS", "FALC0N5");
     }
 
     @Test
     public void whenTargetWordHasDifferentCaseInText_thenMatchFound(){
-        List<Homoglyph.SearchResult> r = homoglyph.search("I like fALc0N5 fly", "Falcons");
+        List<SearchResult> r = homoglyph.search("I like fALc0N5 fly", "Falcons");
         assertEquals(1, r.size());
         checkResult(r.get(0), 7, "Falcons", "fALc0N5");
     }
 
     @Test
     public void whenTargetWordContainsMultipleMatchesWithDifferentHomoglyphs_thenMatchFound(){
-        List<Homoglyph.SearchResult> r = homoglyph.search("I have 501L and FALC0N5 in my garden, I prefer the SO|L", Arrays.asList("CHEESE", "SOIL", "FALCONS"));
+        List<SearchResult> r = homoglyph.search("I have 501L and FALC0N5 in my garden, I prefer the SO|L", Arrays.asList("CHEESE", "SOIL", "FALCONS"));
         assertEquals(3, r.size());
         checkResult(r.get(0), 7, "SOIL", "501L");
         checkResult(r.get(1), 51, "SOIL", "SO|L");
         checkResult(r.get(2), 16, "FALCONS", "FALC0N5");
     }
 
-    private void checkResult(Homoglyph.SearchResult result, int expectedIndex, String expectedWord, String expectedMatch){
+    private void checkResult(SearchResult result, int expectedIndex, String expectedWord, String expectedMatch){
         assertEquals(expectedIndex, result.index);
         assertEquals(expectedWord, result.word);
         assertEquals(expectedMatch, result.match);