Cleanup and tests of yaml method

docs/dsl/yaml.rst

@@ -0,0 +1,73 @@
+yaml
+====
+
+Pulls deck data from a YAML files into a ``Squib::DataFrame`` (essentially a hash of arrays).
+
+Parsing uses Ruby's built-in Yaml package.
+
+The ``yaml`` method is a member of ``Squib::Deck``, but it is also available outside of the Deck DSL with ``Squib.yaml()``. This allows a construction like::
+
+  data = Squib.Yaml file: 'data.yml'
+    Squib::Deck.new(cards: data['name'].size) do
+  end
+
+The Yaml file format assumes that the entire deck is an array, then each element of the array is a hash. Every key encountered in that hash will translate to a "column" in the data frame. If a key exists in one card and not in another, then it defaults to ``nil``.
+
+.. warning::
+
+  Case matters in your Yaml keys.
+
+Options
+-------
+
+file
+  default: ``'deck.yml'``
+
+  the YAML-formatted file to open. Opens relative to the current directory. If ``data`` is set, this option is overridden.
+
+data
+  default: ``nil``
+
+  when set, method will parse this Yaml data instead of reading the file.
+
+explode
+  default: ``'qty'``
+
+  Quantity explosion will be applied to the column this name. For example, rows in the csv with a ``'qty'`` of 3 will be duplicated 3 times.
+
+
+Individual Pre-processing
+-------------------------
+
+The ``yaml`` method also takes in a block that will be executed for each cell in your data. This is useful for processing individual cells, like putting a dollar sign in front of dollars, or converting from a float to an integer. The value of the block will be what is assigned to that cell. For example::
+
+  resource_data = Squib.yaml(file: 'sample.yaml') do |header, value|
+    case header
+    when 'Cost'
+      "$#{value}k" # e.g. "3" becomes "$3k"
+    else
+      value # always return the original value if you didn't do anything to it
+    end
+  end
+
+Examples
+--------
+
+
+To get the sample Excel files, go to `its source <https://github.com/andymeneely/squib/tree/dev/samples/data>`_
+
+.. literalinclude:: ../../samples/data/_csv.rb
+  :language: ruby
+  :linenos:
+
+Here's the sample.csv
+
+.. literalinclude:: ../../samples/data/sample.csv
+  :language: text
+  :linenos:
+
+Here's the quantity_explosion.csv
+
+.. literalinclude:: ../../samples/data/quantity_explosion.csv
+  :language: text
+  :linenos: