Merge pull request #4 from falti/improve_interface

Improve interface

README.md

@@ -10,7 +10,7 @@ by adding `ex_nric` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:ex_nric, "~> 0.1.0"}
+    {:ex_nric, "~> 0.2.0"}
   ]
 end
 ```
@@ -19,3 +19,25 @@ Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_do
 and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
 be found at [https://hexdocs.pm/ex_nric](https://hexdocs.pm/ex_nric).
 
+## Usage
+
+```elixir
+
+import ExNric
+
+{:ok, "S7343684B"} = validate("S7343684B")
+
+{:error, :invalid_format} = validate("x")
+{:error, :invalid_format} = validate("x")
+{:error, :checksum_error} = validate("G0047750U")
+
+```
+
+## Contributing
+
+Pull requests to contribute new or improved features, and extend documentation are most welcome.
+
+Please follow the existing coding conventions, or refer to the [Elixir style guide](https://github.com/niftyn8/elixir_style_guide).
+
+You should include unit tests to cover any changes. Run `mix test` to execute the test suite.
+You should also ensure that dialyzer checks pass. Run `mix dialyzer` to verify. 

lib/ex_nric.ex

@@ -21,13 +21,14 @@ defmodule ExNric do
       {:ok, "G0047750N"}
 
       iex> ExNric.validate("G0047750U")
-      {:error, "checksum failed"}
+      {:error, :checksum_error}
 
       iex> ExNric.validate("X")
-      {:error, "not an NRIC"}
+      {:error, :invalid_format}
 
   """
-  @spec validate(String.t()) :: {atom(), String.t()}
+  @spec validate(String.t()) ::
+          {:ok, String.t()} | {:error, :checksum_error} | {:error, :invalid_format}
   def validate(nric) when is_binary(nric) do
     nric_pattern = ~r/^([STFG])(\d{7})([A-Z])$/
 
@@ -37,15 +38,15 @@ defmodule ExNric do
         do_check(calculated_checksum, checksum, nric)
 
       _ ->
-        {:error, "not an NRIC"}
+        {:error, :invalid_format}
     end
   end
 
   defp do_check(calculated_checksum, checksum, nric) do
     if calculated_checksum == checksum do
       {:ok, nric}
     else
-      {:error, "checksum failed"}
+      {:error, :checksum_error}
     end
   end
 

mix.exs

@@ -4,7 +4,7 @@ defmodule ExNric.MixProject do
   def project do
     [
       app: :ex_nric,
-      version: "0.1.0",
+      version: "0.2.0",
       elixir: "~> 1.6",
       start_permanent: Mix.env() == :prod,
       description: "Validation for Singapore National Registration Identity Card numbers (NRIC)",