import: data frames are here!

Implemented a whole new class to represent the data that comes in from CSV and XLSX. See docs for more info.

Closes #153

docs/build_groups.rst

@@ -34,7 +34,9 @@ One adaptation of this is to do the environment setting in a ``Rakefile``. `Rake
   :language: ruby
   :linenos:
 
-Thus, you can just run this code on the command line like these::
+Thus, you can just run this code on the command line like these:
+
+.. code-block:: none
 
   $ rake
   $ rake pnp

docs/data.rst

@@ -3,10 +3,12 @@ Be Data-Driven with XLSX and CSV
 
 Squib supports importing data from ExcelX (.xlsx) files and Comma-Separated Values (.csv) files. Because :doc:`/arrays`, these methods are column-based, which means that they assume you have a header row in your table, and that header row will define the name of the column.
 
-Hash of Arrays
---------------
+Squib::DataFrame, or a Hash of Arrays
+-------------------------------------
 
-In both DSL methods, Squib will return a ``Hash`` of ``Arrays`` correspoding to each row. Thus, be sure to structure your data like this:
+In both DSL methods, Squib will return a "data frame" (literally of type ``Squib::DataFrame``). The best way to think of this is a ``Hash`` of ``Arrays``, where each column is a key in the hash, and every element of each Array represents a data point on a card.
+
+The data import methods expect you to structure your Excel sheet or CSV like this:
 
   * First row should be a header - preferably with concise naming since you'll reference it in Ruby code
   * Rows should represent cards in the deck
@@ -14,7 +16,9 @@ In both DSL methods, Squib will return a ``Hash`` of ``Arrays`` correspoding to
 
 Of course, you can always import your game data other ways using just Ruby (e.g. from a REST API, a JSON file, or your own custom format). There's nothing special about Squib's methods in how they relate to ``Squib::Deck`` other than their convenience.
 
-See :doc:`/dsl/xlsx` and :doc:`/dsl/csv` for more details and examples.
+See :doc:`/dsl/xlsx` and :doc:`/dsl/csv` for more details and examples on how the data can be imported.
+
+The ``Squib::DataFrame`` class provides much more than what a ``Hash`` provides, however. The :doc:`/dsl/data_frame`
 
 Quantity Explosion
 ------------------

docs/dsl/data_frame.rst

@@ -0,0 +1,85 @@
+Squib::DataFrame
+================
+
+As described in :doc:`/data`, the ``Squib::DataFrame`` is what is returned by Squib's data import methods (:doc:`/dsl/csv` and :doc:`/dsl/xlsx`).
+
+It behaves like a ``Hash`` of ``Arrays``, so acessing an individual column can be done via the square brackets, e.g. ``data['title']``.
+
+Here are some other convenience methods in ``Squib::DataFrame``
+
+columns become methods
+----------------------
+
+Through magic of Ruby metaprogramming, every column also becomes a method on the data frame. So these two are equivalent:
+
+.. code-block:: irb
+
+  irb(main):002:0> data = Squib.csv file: 'basic.csv'
+  => #<Squib::DataFrame:0x00000003764550 @hash={"h1"=>[1, 3], "h2"=>[2, 4]}>
+  irb(main):003:0> data.h1
+  => [1, 3]
+  irb(main):004:0> data['h1']
+  => [1, 3]
+
+#columns
+--------
+
+Returns an array of the column names in the data frame
+
+#ncolumns
+---------
+
+Returns the number of columns in the data frame
+
+#col?(name)
+-----------
+
+Returns ``true`` if there is column ``name``.
+
+#row(i)
+-------
+
+Returns a hash of values across all columns in the ``i``th row of the dataframe. Represents a single card.
+
+#nrows
+------
+
+Returns the number of rows the data frame has, computed by the maximum length of any column array.
+
+#to_json
+--------
+
+Returns a ``json`` representation of the entire data frame.
+
+#to_pretty_json
+---------------
+
+Returns a ``json`` representation of the entire data frame, formatted with indentation for human viewing.
+
+#to_pretty_text
+---------------
+
+Returns a textual representation of the dataframe that emulates what the information looks like on an individual card. Here's an example:
+
+.. code-block:: text
+
+              ╭------------------------------------╮
+         Name | Mage                               |
+         Cost | 1                                  |
+  Description | You may cast 1 spell per turn      |
+        Snark | Magic, dude.                       |
+              ╰------------------------------------╯
+              ╭------------------------------------╮
+         Name | Rogue                              |
+         Cost | 2                                  |
+  Description | You always take the first turn.    |
+        Snark | I like to be sneaky                |
+              ╰------------------------------------╯
+              ╭------------------------------------╮
+         Name | Warrior                            |
+         Cost | 3                                  |
+  Description |
+        Snark | I have a long story to tell to tes |
+              | t the word-wrapping ability of pre |
+              | tty text formatting.               |
+              ╰------------------------------------╯

docs/install.rst

@@ -13,7 +13,9 @@ Squib works with both x86 and x86_64 versions of Ruby.
 Typical Install
 ---------------
 
-Regardless of your OS, installation is::
+Regardless of your OS, installation is
+
+.. code-block:: none
 
   $ gem install squib