Merge pull request #72 from google/closure

Add Closure JS implementation

Author: drinckes

.gitignore

@@ -0,0 +1,7 @@
+# Ignore backup and swap files.
+*~
+.*.swp
+# Ignore all bazel-* links.
+/bazel-*
+# Ignore outputs generated during Bazel bootstrapping.
+/output/

CONTRIBUTING.md

@@ -1,55 +1,72 @@
-Want to contribute? Great! First, read this page (including the small print at the end).
-
-## Before you contribute
-Before we can use your code, you must sign the
-[Google Individual Contributor License Agreement](https://developers.google.com/open-source/cla/individual?csw=1)
-(CLA), which you can do online.
-
-The CLA is necessary mainly because you own the
-copyright to your changes, even after your contribution becomes part of our
-codebase, so we need your permission to use and distribute your code. We also
-need to be sure of various other things—for instance that you'll tell us if you
-know that your code infringes on other people's patents.
-
-You don't have to sign
-the CLA until after you've submitted your code for review and a member has
-approved it, but you must do it before we can put your code into our codebase.
-Before you start working on a larger contribution, you should get in touch with
-us first through the issue tracker with your idea so that we can help out and
-possibly guide you. Coordinating up front makes it much easier to avoid
-frustration later on.
-
-## Writing a new implementation
-
-Before you start writing a new implementation, look at some of the existing ones. If you copy the
-code structure from them, you are more likely to have fewer bugs and an easier review cycle.
-
-If you create new algorithms to encode or decode, then your reviewer will have to spend more time
-trying to understand your code in a language they may not be familiar with, and the review cycle
-will take longer.
-
-The reason we say this is because once code is accepted into our repository, we have the responsibility
-to maintain and look after it. You are not writing the code for you, but for the OLC project team.
-
-## Code reviews
-All submissions, including submissions by project members, require review. We
-use Github pull requests for this purpose.
-
-## Code Style
-Programs written in Go must be formatted with `gofmt`. For other languages, we use the 
-[Google style guides](https://google.github.io/styleguide/) for code styling. Specifically, this means:
-
-* Line length: 80 chars (Java 100)
-* No extra whitespace around arguments `(code)` not `( code )`
-*  K & R style braces:
-```java
-if (condition()) {
-  something();
-} else {
-  somethingElse();
-}
-```
-
-## The small print
-Contributions made by corporations are covered by a different agreement than
-the one above, the Software Grant and Corporate Contributor License Agreement.
+# Contributing to Open Location Code
+
+The Open Location Code project strongly encourages technical contributions.
+
+We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.
+
+- [Filing issues](#filing-issues)
+  * [Bugs](#bugs)
+  * [Suggestions](#suggestions)
+- [Contributing code](#contributing-code)
+- [Contributing a new implementation](#contributing-a-new-implementation)
+- [Contributor License Agreement](#contributor-license-agreement)
+- [Ongoing participation](#ongoing-participation)
+  * [Discussion channels](#discussion-channels)
+
+## Filing issues
+
+### Bugs
+
+If you find a bug in an Open Location Code library, please [file an issue](https://github.com/google/open-location-code/issues/new).  Members of the community are regularly monitoring issues and will try to fix open bugs quickly.
+
+The best bug reports provide a detailed description of the issue, step-by-step instructions for predictably reproducing the issue, and possibly even a working example that demonstrates the issue.
+
+Please note that questions about how to use Open Location Code or other general questions should be asked on the [Open Location Code Google Group](https://groups.google.com/forum/#!forum/open-location-code)<!-- Uncomment if this becomes sensible --><!-- or [Stack Overflow under the Open Location Code tag](http://stackoverflow.com/questions/tagged/open-location-code) -->
+instead of filing an issue here.
+
+### Suggestions
+
+The Open Location Code project is meant to evolve with feedback.  The project and its users appreciate your thoughts on ways to improve the design or features or creative ways to use the codes.
+
+To make a suggestion [file an issue](https://github.com/google/open-location-code/issues/new).
+
+If you are intending to implement, please see the [Contributing code](#contributing-code) section below for next steps.
+
+If you are adding Open Location Codes to your project, please contact the [Open Location Code Google Group](https://groups.google.com/forum/#!forum/open-location-code) so we can suggest how you can make the most of the codes.
+
+## Contributing code
+
+The Open Location Code project accepts and greatly appreciates code contributions!
+
+If you are contributing code to the project consider [joining the Open Location Code project on GitHub](https://goo.gl/forms/T65peVtfQfEoDWeD3).
+
+A few things to note:
+
+* The Open Location Code project follows the [fork & pull](https://help.github.com/articles/using-pull-requests/#fork--pull) model for accepting contributions.
+* We follow [Google's JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html).  More generally make sure to follow the same comment and coding style as the rest of the project.
+* Include [tests](TESTING.md) when contributing code.  There are tests that you can use as examples.
+
+## Contributing a new implementation
+
+Follow this process for contributing a new implementation:
+
+* Look at the existing implementations, to get an idea of the usage and how much work is involved.
+* If you copy the code structure and algorithms from an existing implementation, you'll have a much shorter review cycle.
+* [Create a new GitHub issue](https://github.com/google/open-location-code/issues/new) to start discussion of the new feature.
+* Follow the guidelines for [Contributing code](#contributing-code) described above.
+
+## Contributor License Agreement
+
+The Open Location Code project hosted at GitHub requires all contributors to sign a Contributor License Agreement ([individual](https://developers.google.com/open-source/cla/individual) or [corporation](https://developers.google.com/open-source/cla/corporate)) in order to protect contributors, users and Google in issues of intellectual property.
+
+When you create a Pull Request a check will be run to ensure that you have signed the CLA.  Make sure that you sign the CLA with the same email address you associate with your commits (likely via the `user.email` Git config as described on GitHub's [Set up Git](https://help.github.com/articles/set-up-git/) page).
+
+## Ongoing participation
+
+We actively encourage ongoing participation by community members.
+
+### Discussion channels
+
+Technical issues, designs, etc. are discussed on [GitHub issues](https://github.com/google/open-location-code/issues) and [pull requests](https://github.com/google/open-location-code/pulls),
+or the [Open Location Code Google Group](https://groups.google.com/forum/#!forum/open-location-code)<!-- Uncomment if this becomes sensible --><!-- and [Stack Overflow under the Open Location Code tag](http://stackoverflow.com/questions/tagged/open-location-code) -->.
+

TESTING.md

@@ -1,18 +1,36 @@
-# Automated Integration Testing
+# Testing
+The preferred mechanism for testing is using the [Bazel](https://bazel.build/)
+build system. This uses files called `BUILD` ([example](https://github.com/google/open-location-code/blob/master/BUILD)
+to provide rules to build code and run tests.
+
+Create a `BUILD` file in your code directory with a [test rule](https://bazel.build/versions/master/docs/test-encyclopedia.html).
+You can then test your code by running:
+
+```sh
+blaze test <dir>:<rule>
+```
+
+All tests can be run with:
+
+```sh
+blaze test ...:all
+```
+
+## Automated Integration Testing
 Changes are sent to [Travis CI](https://travis-ci.org)
 for integration testing after pushes, and you can see the current test status
 [here](https://travis-ci.org/google/open-location-code).
 
 The testing configuration is controlled by two files:
 [`travis.yml`](.travis.yml) and [`run_tests.sh`](run_tests.sh).
 
-## [.travis.yml](.travis.yml)
+### [.travis.yml](.travis.yml)
 This file defines the prerequisites required for testing, and the list of
 directories to be tested. (The directories listed are tested in parallel.)
 
 The same script ([run_tests.sh](run_tests.sh)) is executed for all directories.
 
-## [run_tests.sh](run_tests.sh)
+### [run_tests.sh](run_tests.sh)
 This file is run once for _each_ directory defined in
 `.travis.yml`. The directory name being tested is passed in the environment
 variable `TEST_DIR`.)
@@ -23,7 +41,7 @@ commands to test the relevant implementation. The commands that do the testing
 return zero, even if they output error messages, will be considered by the
 testing framework as a success_.
 
-## Adding Your Tests
+### Adding Your Tests
 Add your directory to the [`.travis.yml`](.travis.yml) file:
 ```
 # Define the list of directories to execute tests in.
@@ -49,7 +67,7 @@ the script will return the same status as the tests. If this status is zero,
 the test will be marked successful. If not, the test will be marked as a
 failure.
 
-## Testing Multiple Languages
+### Testing Multiple Languages
 [Travis CI](https://travis-ci.org) assumes that each github project has only
 a single language. That language is specified in the [.travis.yml](.travis.yml)
 file (`language: node_js`).

WORKSPACE

@@ -0,0 +1,25 @@
+workspace(name = "openlocationcode")
+
+# Include the Google Test framework for C++ testing.
+# See https://github.com/google/googletest
+new_http_archive(
+    name = "gtest",
+    url = "https://github.com/google/googletest/archive/release-1.8.0.zip",
+    sha256 = "f3ed3b58511efd272eb074a3a6d6fb79d7c2e6a0e374323d1e6bcbcc1ef141bf",
+    build_file = "cpp/gtest.BUILD",
+    strip_prefix = "googletest-release-1.8.0/googletest",
+)
+
+# Include the Bazel Closure rules for javascript testing..
+# See https://github.com/bazelbuild/rules_closure
+http_archive(
+    name = "io_bazel_rules_closure",
+    url = "http://mirror.bazel.build/github.com/bazelbuild/rules_closure/archive/0.4.1.tar.gz",
+    sha256 = "ba5e2e10cdc4027702f96e9bdc536c6595decafa94847d08ae28c6cb48225124",
+    strip_prefix = "rules_closure-0.4.1",
+)
+
+load("@io_bazel_rules_closure//closure:defs.bzl", "closure_repositories")
+
+closure_repositories()
+

cpp/WORKSPACE

@@ -0,0 +1,67 @@
+
+java_library(
+    name = "openlocationcode",
+    srcs = [
+        "com/google/openlocationcode/OpenLocationCode.java",
+    ],
+)
+
+java_test(
+    name = "encoding_Test",
+    srcs = [
+        "com/google/openlocationcode/tests/EncodingTest.java",
+    ],
+    test_class = "com.google.openlocationcode.tests.EncodingTest",
+    size = "small",
+    deps = [
+        ":openlocationcode",
+    ],
+    data = [
+        "//test_data:test_data"
+    ],
+)
+
+java_test(
+    name = "precision_test",
+    srcs = [
+        "com/google/openlocationcode/tests/PrecisionTest.java",
+    ],
+    test_class = "com.google.openlocationcode.tests.PrecisionTest",
+    size = "small",
+    deps = [
+        ":openlocationcode",
+    ],
+    data = [
+        "//test_data:test_data"
+    ],
+)
+
+java_test(
+    name = "shortening_test",
+    srcs = [
+        "com/google/openlocationcode/tests/ShorteningTest.java",
+    ],
+    test_class = "com.google.openlocationcode.tests.ShorteningTest",
+    size = "small",
+    deps = [
+        ":openlocationcode",
+    ],
+    data = [
+        "//test_data:test_data"
+    ],
+)
+
+java_test(
+    name = "validity_test",
+    srcs = [
+        "com/google/openlocationcode/tests/ValidityTest.java",
+    ],
+    test_class = "com.google.openlocationcode.tests.ValidityTest",
+    size = "small",
+    deps = [
+        ":openlocationcode",
+    ],
+    data = [
+        "//test_data:test_data"
+    ],
+)

java/BUILD

@@ -1,47 +1,49 @@
 # Java Open Location Code library
 
-## Building
+## Building and Testing
 
-Create an empty `build` directory:
+Included is a `BUILD` file that uses the [Bazel](https://bazel.build/) build system to produce a JAR file and to run tests. You will need to install Bazel on your system to run the tests.
 
-```shell
-mkdir build
-```
+### Building the JAR file
 
-Compile the `com/google/openlocationcode/OpenLocationCode.java` file and then
-package it as a jar file:
+To build a JAR file, run:
 
-```shell
-javac -d build com/google/openlocationcode/OpenLocationCode.java
-cd build
-jar cvf OpenLocationCode.jar com/google/openlocationcode/OpenLocationCode*.class
-cd ..
 ```
-That's it - you'll have a jar file in `build/OpenLocationCode.jar`.
+$ bazel build java:openlocationcode
+INFO: Found 1 target...
+Target //java:openlocationcode up-to-date:
+  bazel-bin/java/libopenlocationcode.jar
+INFO: Elapsed time: 3.107s, Critical Path: 0.22s
+$
+```
 
-## Testing
+The JAR file is accessable using the path shown in the output.
 
-Download the `junit` and `hamcrest` jar files from [their repository](https://github.com/junit-team/junit4/wiki/Download-and-Install)
-and place them somewhere.
+If you cannot install Bazel, you can build the JAR file manually with:
 
-(This will assume you downloaded `junit-41.2.jar` and `hamcrest-core-1.3.jar`)
+```
+mkdir build
+javac -d build com/google/openlocationcode/OpenLocationCode.java
+```
 
-Build the `OpenLocationCode.jar` file as above.
+This will  create a JAR file in the `build` directory. Change that to a suitable location.
 
-Add all three files to your `CLASSPATH` variable (obviously use the real paths to the files):
+### Running tests
 
-```shell
-CLASSPATH=$CLASSPATH:build/OpenLocationCode.jar:/path/to/junit-4.12.jar:/path/to/hamcrest-core-1.3.jar
-```
+The tests read their data from the [`test_data`](https://github.com/google/open-location-code/tree/master/test_data) directory.
 
-Compile the test classes:
+Run the tests from the top-level github directory. This command will build the JAR file and test classes, and execute them:
 
-```shell
-javac -cp $CLASSPATH -d build com/google/openlocationcode/tests/*java
 ```
-
-Run the tests. Note that we need to use the `-cp` argument to give the location of the test classes and the test data files:
-
-```shell
-java -cp $CLASSPATH:build:../test_data: org.junit.runner.JUnitCore com.google.openlocationcode.tests.EncodingTest com.google.openlocationcode.tests.PrecisionTest com.google.openlocationcode.tests.ShorteningTest com.google.openlocationcode.tests.ValidityTest
+$ bazel test java:all
+INFO: Found 1 target and 4 test targets...
+INFO: Elapsed time: 0.657s, Critical Path: 0.46s
+//java:encoding_Test                                                     PASSED in 0.4s
+//java:precision_test                                                    PASSED in 0.4s
+//java:shortening_test                                                   PASSED in 0.4s
+//java:validity_test                                                     PASSED in 0.4s
+
+Executed 4 out of 4 tests: 4 tests pass.
+$
 ```
+

java/README.md

@@ -7,6 +7,8 @@
 import org.junit.Test;
 
 import java.io.BufferedReader;
+import java.io.File;
+import java.io.FileInputStream;
 import java.io.InputStream;
 import java.io.InputStreamReader;
 import java.util.ArrayList;
@@ -46,7 +48,8 @@ public TestData(String line) {
 
   @Before
   public void setUp() throws Exception {
-    InputStream testDataStream = ClassLoader.getSystemResourceAsStream("encodingTests.csv");
+    File testFile = new File(System.getenv("JAVA_RUNFILES"), "openlocationcode/test_data/encodingTests.csv");
+    InputStream testDataStream = new FileInputStream(testFile);
     BufferedReader reader = new BufferedReader(new InputStreamReader(testDataStream));
     String line;
     while ((line = reader.readLine()) != null) {