dsl: add Squib.configure

I ended up adding this one on a whim, but it feels like a long time coming. We need cleaner support for Rakefiles, and this is a good step toward that I think.

CHANGELOG.md

@@ -5,6 +5,7 @@ Squib follows [semantic versioning](http://semver.org).
 
 Features:
 * `save_pdf` now supports crop marks! These are lines drawn in the margins of a PDF file to help you cut. These can be enabled by setting `crop_marks: true` in your `save_pdf` call. Can be further customized with `crop_margin_bottom`, `crop_margin_left`, `crop_margin_right`, `crop_margin_top`, `crop_marks`, `crop_stroke_color`, `crop_stroke_dash`, and `crop_stroke_width` (#123)
+* `Squib.configure` allows you to set options programmatically, overriding your config.yml. This is useful for Rakefiles, and will be documented in my upcoming tutorial on workflows.
 
 Bugs:
 * `showcase` works as expected when using `backend: svg` (#179)

docs/config.rst

@@ -47,7 +47,7 @@ prefix
 
 img_dir
   default: ``'.'``
-  
+
   For reading image file command (e.g. png and svg), read from this directory instead
 
 warn_ellipsize
@@ -111,6 +111,19 @@ For debugging/sanity purposes, if you want to make sure your configuration optio
     puts backend # prints 'memory' by default
   end
 
+These are read-only - you will not be able to change these.
+
+Squib.configure sets options programmatically
+---------------------------------------------
+
+You can also use :doc:`/dsl/configure` to override anything in the config file. Use it like this:
+
+.. literalinclude:: ../samples/project/Rakefile
+  :language: ruby
+  :linenos:
+
+
+See :doc:`/guides/getting-started/part_3_workflows` for how we put this to good use.
 
 Making Squib Verbose
 --------------------

docs/dsl/configure.rst

@@ -0,0 +1,18 @@
+Squib.configure
+---------------
+
+Prior to the construction of a Squib::Deck, set a global default that overrides what is specified `config.yml`.
+
+This is intended to be done prior to Squib::Deck.new, and is intended to be used inside of a Rakefile
+
+Options
+^^^^^^^
+
+All options that are specified in :doc:`/config`
+
+Exmaples
+^^^^^^^^
+
+.. literalinclude:: ../../samples/project/Rakefile
+  :language: ruby
+  :linenos:

lib/squib/conf.rb

@@ -3,6 +3,14 @@ require 'yaml'
 require_relative 'args/typographer'
 
 module Squib
+  USER_CONFIG = {}
+
+  def configure(opts)
+    str_hash = opts.inject({}) { |h, (k, v)| h[k.to_s] = v; h }
+    USER_CONFIG.merge! str_hash
+  end
+  module_function :configure
+
   # @api private
   class Conf
 
@@ -40,7 +48,7 @@ module Squib
     }
 
     def initialize(config_hash = DEFAULTS)
-      @config_hash = config_hash
+      @config_hash = config_hash.merge USER_CONFIG # programmatic overrides yml
       @typographer = Args::Typographer.new(config_hash)
       normalize_antialias
     end

spec/conf_spec.rb

@@ -36,4 +36,12 @@ describe Squib::Conf do
     expect(conf.to_s).to start_with 'Conf: '
   end
 
+  it 'allows Squib.configure to override yml' do
+    Squib.configure img_dir: 'color'
+    c = Squib::Conf.load conf('basic.yml')
+    expect(c.img_dir).to eq 'color'
+    # reset our state to be nice
+    Squib::USER_CONFIG.clear
+  end
+
 end

spec/data/conf/basic.yml

@@ -0,0 +1 @@
+img_dir: bw