update docs and add tests

Author: rubysolo

.gitignore

@@ -1,5 +1,6 @@
 /_build
 /cover
 /deps
+/doc
 erl_crash.dump
 *.ez

README.md

@@ -16,58 +16,58 @@ If [available in Hex](https://hex.pm/docs/publish), the package can be installed
 
   1. Import `Excelerator.Workbook` into your module, then generate the XML content:
 
-      workbook do
-        worksheet "My Sheet" do
-          row do
-            cell "Name"
-            cell "Status"
-          end
-
-          row do
-            cell "Elixir"
-            cell 1
+        workbook do
+          worksheet "My Sheet" do
+            row do
+              cell "Name"
+              cell "Status"
+            end
+
+            row do
+              cell "Elixir"
+              cell 1
+            end
           end
         end
-      end
 
-      # => <?xml version="1.0" encoding="UTF-8" ?><Workbook ...
+        # => <?xml version="1.0" encoding="UTF-8" ?><Workbook ...
 
 ## Usage with Phoenix
 
   1. Use `Excelerator.Phoenix` in your controller:
 
-      defmodule MyApp.MyController do
-        use MyApp.Web, :controller
-        use Excelerator.Phoenix
+        defmodule MyApp.MyController do
+          use MyApp.Web, :controller
+          use Excelerator.Phoenix
 
   1. Import `Excelerator.Workbook` into your view module:
 
-      defmodule MyApp.MyView do
-        use MyApp.Web, :view
-        import Excelerator.Workbook
+        defmodule MyApp.MyView do
+          use MyApp.Web, :view
+          import Excelerator.Workbook
 
-  1. Alternatively, add the use / import statements to the appropriate sections
+     (Alternatively, add the use / import statements to the appropriate sections
      of `web/web.ex`, which will make excelerator available in all controllers/
-     views.
+     views.)
 
   1. Call `xls` in your controller action to send content as a file download:
 
-      def show(conn, %{"format" => "xls"} = params) do
-        xls conn, "show.xls", favorite: "Elixir"
-      end
+        def show(conn, %{"format" => "xls"} = params) do
+          xls conn, "show.xls", favorite: "Elixir"
+        end
 
   1. Create `web/templates/RESOURCE/NAME.xls.exs`
 
-      workbook do
-        worksheet "My Sheet" do
-          row do
-            cell "Name"
-            cell "Status"
-          end
-
-          row do
-            cell assigns.favorite
-            cell 1
+        workbook do
+          worksheet "My Sheet" do
+            row do
+              cell "Name"
+              cell "Status"
+            end
+
+            row do
+              cell assigns.favorite
+              cell 1
+            end
           end
         end
-      end

lib/excelerator/phoenix.ex

@@ -1,8 +1,26 @@
 defmodule Excelerator.Phoenix do
+  @moduledoc """
+  Provides the `xls` function for rendering Excel spreadsheets as file downloads
+  from Phoenix controllers.
+
+  ## Using
+
+  When used, `Excelerator.Phoenix` generates the `xls` function in your
+  controller so you can send file downloads like:
+
+      xls conn, "invoice.xls", items: line_items
+
+  The attachment filename defaults to the same name as the controller, but can
+  be overridden with the `:filename` option.
+
+      xls conn, "template.xls", data, filename: "SrsBizness.xls"
+
+  """
+
   defmacro __using__(options) do
     quote do
-      def xls(conn, template, data, opts \\ []) do
-        excel_data = view_module(conn).render(template, data)
+      def xls(conn, template, assigns, opts \\ []) do
+        excel_data = view_module(conn).render(template, assigns)
 
         default_filename = Phoenix.Naming.resource_name(__MODULE__, "Controller") <> ".xls"
         filename = Keyword.get(opts, :filename, default_filename)

lib/excelerator/workbook.ex

@@ -1,4 +1,12 @@
 defmodule Excelerator.Workbook do
+  @moduledoc """
+  Provides functions to generate Excel spreadsheets.
+
+  ## Importing
+
+  You may want to import this module where you are generating spreadsheets.
+  """
+
   require Logger
   import XmlBuilder
 
@@ -25,12 +33,18 @@ defmodule Excelerator.Workbook do
     end
   end
 
-  defmacro row(do: {_, _, statements}) do
+  defmacro row(do: {_, _, statements} = content) do
     quote do
       {:Row, unquote(statements)}
     end
   end
 
+  defmacro row(do: content) do
+    quote do
+      {:Row, unquote(content || [])}
+    end
+  end
+
   def cell(content) when is_bitstring(content), do: cell(content, "String")
   def cell(content) when is_number(content),    do: cell(content, "Number")
   def cell(content) do

mix.exs

@@ -6,9 +6,12 @@ defmodule Excelerator.Mixfile do
       app: :excelerator,
       version: "0.0.1",
       elixir: "~> 1.0",
+      name: "excelerator",
+      source_url: "https://github.com/rubysolo/excelerator",
       description: description,
       package: package,
-      deps: deps
+      deps: deps,
+      docs: [extras: ["README.md"]]
     ]
   end
 
@@ -18,7 +21,7 @@ defmodule Excelerator.Mixfile do
 
   def description do
     """
-    Generate Excel workbooks
+    Generate Excel workbooks in Elixir
     """
   end
 
@@ -36,7 +39,8 @@ defmodule Excelerator.Mixfile do
 
   defp deps do
     [
-      {:xml_builder, github: "joshnuss/xml_builder"}
+      {:xml_builder, github: "joshnuss/xml_builder"},
+      {:earmark, "~> 0.1", optional: true},
     ]
   end
 end

mix.lock

@@ -1,2 +1,3 @@
-%{"ex_doc": {:git, "https://github.com/elixir-lang/ex_doc.git", "63342194e8a572485b37b4a58668f9b43ab7ab26", []},
+%{"earmark": {:hex, :earmark, "0.1.17"},
+  "ex_doc": {:git, "https://github.com/elixir-lang/ex_doc.git", "63342194e8a572485b37b4a58668f9b43ab7ab26", []},
   "xml_builder": {:git, "https://github.com/joshnuss/xml_builder.git", "84c310903af9b80fc54829c88d2c4bc898a65233", []}}

test/excelerator/workbook_test.exs

@@ -0,0 +1,62 @@
+defmodule Excelerator.WorkbookTest do
+  use ExUnit.Case
+  doctest Excelerator.Workbook
+
+  import Excelerator.Workbook
+
+  test "top-level workbook structure" do
+    xml = workbook do: []
+    assert xml == """
+    <?xml version="1.0" encoding="UTF-8" ?>
+    <Workbook xmlns="urn:schemas-microsoft-com:office:spreadsheet" xmlns:html="http://www.w3.org/TR/REC-html40" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:ss="urn:schemas-microsoft-com:office:spreadsheet" xmlns:x="urn:schemas-microsoft-com:office:excel">
+    	<Styles>
+    		<Style ss:ID="Default" ss:Name="Normal">
+    			<Alignment ss:Vertical="Bottom"/>
+    			<Borders/>
+    			<Font ss:FontName="Verdana"/>
+    			<Interior/>
+    			<NumberFormat/>
+    			<Protection/>
+    		</Style>
+    	</Styles>
+
+    </Workbook>
+    """ |> String.rstrip
+  end
+
+  test "worksheet with default name" do
+    sheet = worksheet do: :content
+    assert sheet == {:Worksheet, %{"ss:Name" => "Sheet1"}, [Table: [:content]]}
+  end
+
+  test "worksheet with custom name" do
+    sheet = worksheet "Custom", do: :content
+    assert sheet == {:Worksheet, %{"ss:Name" => "Custom"}, [Table: [:content]]}
+  end
+
+  test "row" do
+    r = row do
+    end
+    assert r == {:Row, []}
+  end
+
+  defmodule User do
+    defstruct name: "John", age: 27
+  end
+
+  test "row with cells" do
+    user = %User{}
+
+    r = row do
+      cell "Hello"
+      cell 123
+      cell user.name
+    end
+
+    assert r == {:Row, [
+      {:Cell, [{:Data, %{"ss:Type" => "String"}, "Hello"}]},
+      {:Cell, [{:Data, %{"ss:Type" => "Number"}, 123}]},
+      {:Cell, [{:Data, %{"ss:Type" => "String"}, "John"}]},
+    ]}
+  end
+end