build groups: add convenience methods

CHANGELOG.md

@@ -6,6 +6,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.
+* `Squib.enable_build_globally` and `Squib.disable_build_globally` are new convenience methods for working with the `SQUIB_BUILD` environment variable. Handy for Rakefiles and Guard sessions for turning certain builds on an off.
 
 Bugs:
 * `showcase` works as expected when using `backend: svg` (#179)

docs/build_groups.rst

@@ -17,23 +17,24 @@ Only one group is enabled by default: ``:all``. All other groups are disabled by
 
 Groups can be enabled and disabled in several ways:
 
-  * The :doc:`/dsl/enable_build` and :doc:`/dsl/disable_build`  DSL methods can explicitly enable/disable a group. Again, you're back to commenting out the *enable_group* call, but that's easier than remembering what lines to comment out each time.
+  * The :doc:`/dsl/enable_build` and :doc:`/dsl/disable_build`  DSL methods within a given ``Squib::Deck`` can explicitly enable/disable a group. Again, you're back to commenting out the *enable_group* call, but that's easier than remembering what lines to comment out each time.
-  * When a ``Squib::Deck`` is initialized, the `environment variable <https://en.wikipedia.org/wiki/Environment_variable>`_ ``SQUIB_BUILD`` is consulted for a comma-separated string. These are converted to Ruby symbols and the corresponding groups are enabled.
+  * When a ``Squib::Deck`` is initialized, the `environment variable <https://en.wikipedia.org/wiki/Environment_variable>`_ ``SQUIB_BUILD`` is consulted for a comma-separated string. These are converted to Ruby symbols and the corresponding groups are enabled. This is handy for enabling builds on the command line (e.g. turn on color, work in that for a while, then turn it off)
+  * Furthermore, you can use :doc:`Squib.enable_build_globally </dsl/enable_build_globally>` and :doc:`Squib.disable_build_globally </dsl/disable_build_globally>` to manipulate ``SQUIB_BUILD`` environment variable programmatically (e.g. from a Rakefile, inside a `Guard <https://github.com/guard/guard>`_ session, or other build script).
 
-Note that the environment variables are intended to change from run to run, from the command line.
+The :doc:`/guides/getting-started/part_3_workflows` tutorial covers how to work these features into your workflow.
 
 .. note::
 
-  There should be no need to set the SQUIB_BUILD variable globally on your system.
+  There should be no need to set the SQUIB_BUILD variable globally on your system (e.g. at boot). The intent is to set SQUIB_BUILD as part of your session.
 
-Don't like how Windows specifies environment variables? One adaptation of this is to do the environment setting in a ``Rakefile``. Rake is the build utility that comes with Ruby, and it allows us to set different tasks exactly in this way. This Rakefile works nicely with our above code example:
+One adaptation of this is to do the environment setting in a ``Rakefile``. `Rake <https://ruby.github.io/rake/>`_ is the build utility that comes with Ruby, and it allows us to set different tasks exactly in this way. This Rakefile works nicely with our above code example:
 
 
 .. literalinclude:: ../samples/build_groups/Rakefile
   :language: ruby
   :linenos:
 
-Thus, you can just run this code with commands like these::
+Thus, you can just run this code on the command line like these::
 
   $ rake
   $ rake pnp

docs/dsl/disable_build_globally.rst

@@ -0,0 +1,46 @@
+disable_build_globally
+======================
+
+Disable the given build group for all future ``Squib::Deck`` runs.
+
+Essentially a convenience method for setting the ``SQUIB_BUILD`` environment variable. See :doc:`/build_groups` for ways to use this effectively.
+
+This is a member of the ``Squib`` module, so you must run it like this::
+
+  Squib.disable_build_globally :pdf
+
+The intended purpose of this method is to be able to alter the environment from other build scripts, such as a Rakefile.
+
+Required Arguments
+------------------
+
+build_group_name
+
+  the name of the build group to disable. Convention is to use a Ruby symbol.
+
+
+Examples
+--------
+
+Can be used to disable a group, overriding setting the environment variable at the command line::
+
+  Squib.enable_build_globally :pdf
+  Squib.disable_build_globally :pdf
+
+  Squib::Deck.new do
+    build :pdf do
+      save_pdf #does not get run regardless of incoming environment
+    end
+  end
+
+But gets overridden by an individual ``Squib::Deck`` programmatically enabling a build via :doc:`/dsl/enable_build`::
+
+  Squib.enable_build_globally :pdf
+  Squib.disable_build_globally :pdf
+
+  Squib::Deck.new do
+    enable_build :pdf
+    build :pdf do
+      save_pdf # this will be run no matter what
+    end
+  end

docs/dsl/enable_build_globally.rst

@@ -0,0 +1,44 @@
+disable_build_globally
+======================
+
+Enagle the given build group for all future ``Squib::Deck`` runs.
+
+Essentially a convenience method for setting the ``SQUIB_BUILD`` environment variable. See :doc:`/build_groups` for ways to use this effectively.
+
+This is a member of the ``Squib`` module, so you must run it like this::
+
+  Squib.enable_build_globally :pdf
+
+The intended purpose of this method is to be able to alter the environment from other build scripts, such as a Rakefile.
+
+Required Arguments
+------------------
+
+build_group_name
+
+  the name of the build group to enable. Convention is to use a Ruby symbol.
+
+
+Examples
+--------
+
+Can be used to enable a group, overriding setting the environment variable at the command line::
+
+  Squib.enable_build_globally :pdf
+
+  Squib::Deck.new do
+    build :pdf do
+      save_pdf # this runs regardless of incoming environment
+    end
+  end
+
+But gets overridden by an individual ``Squib::Deck`` programmatically enabling a build via :doc:`/dsl/enable_build`::
+
+  Squib.enable_build_globally :pdf
+
+  Squib::Deck.new do
+    disable_build :pdf
+    build :pdf do
+      save_pdf # this will NOT be run no matter what
+    end
+  end

docs/guides/guard.rst

@@ -35,19 +35,19 @@ Using Guard + Rake
 
 Guard is a gem, just like Squib. When using Guard, I recommend also using Bundler. So your Gemfile will look like this.
 
-.. literalinclude:: ../../samples/rake-guard/Gemfile
+.. literalinclude:: ../../samples/project/Gemfile
   :language: ruby
   :linenos:
 
 And then your Rakefile might look something like this
 
-.. literalinclude:: ../../samples/rake-guard/Rakefile
+.. literalinclude:: ../../samples/project/Rakefile
   :language: ruby
   :linenos:
 
 To get our images directory set, and to turn on proress bars (which I recommend when working under Guard), you'll need a ``config.yml`` file that looks like this.
 
-.. literalinclude:: ../../samples/rake-guard/config.yml
+.. literalinclude:: ../../samples/project/config.yml
   :language: yaml
   :linenos:
 
@@ -55,7 +55,7 @@ Note that we are using ``load`` instead of ``require`` to run our code. In Ruby,
 
 And then our Guardfile
 
-.. literalinclude:: ../../samples/rake-guard/Guardfile
+.. literalinclude:: ../../samples/project/Guardfile
   :language: ruby
   :linenos:
 
@@ -71,7 +71,7 @@ So, let's say we're working on our Character deck. To run all this we can kick o
   Loading SVG(s) <===========================================> 100% Time: 00:00:00
   Saving PNGs to _output/character__* <======================> 100% Time: 00:00:00
   ]2;[running rake task: characters] watched files: []
-  [1] Characters guard(main)> ow watching at 'C:/Users/andy/code/squib/samples/rake-guard'
+  [1] Characters guard(main)> ow watching at 'C:/Users/andy/code/squib/samples/project'
 
 Guard will do an initial build, then wait for file changes to be made. From here, once we edit and save anything related to characters - any Excel file, our ``characters.rb`` file, any YML file, etc, we'll rebuild our images.
 

lib/squib/api/groups.rb

@@ -2,13 +2,20 @@ require 'set'
 
 module Squib
 
-  # An idea for later...
+  # DSL method. See http://squib.readthedocs.io
-  # def enable_group_env group
+  def enable_build_globally group
-  #   ENV['SQUIB_BUILD'] ||= ''
+    groups = (ENV['SQUIB_BUILD'] ||= '').split(',')
-  #   ENV['SQUIB_BUILD'] += ','
+    ENV['SQUIB_BUILD'] = (groups << group).uniq.join(',')
-  #   ENV['SQUIB_BUILD'] += group
+  end
-  # end
+  module_function :enable_build_globally
-  # module_function :enable_group_env
+
+  # DSL method. See http://squib.readthedocs.io
+  def disable_build_globally group
+    groups = (ENV['SQUIB_BUILD'] ||= '').split(',')
+    groups.delete(group.to_s)
+    ENV['SQUIB_BUILD'] = groups.uniq.join(',')
+  end
+  module_function :disable_build_globally
 
   class Deck
 

samples/build_groups/Rakefile

@@ -8,18 +8,18 @@ task both: [:bw, :color]
 
 desc 'Build black-and-white only'
 task :bw do
-  ENV['SQUIB_BUILD'] = 'print_n_play'
+  Squib.enable_build_globally :print_n_play
   load 'build_groups.rb'
 end
 
 desc 'Build the color version only'
 task :color do
-  ENV['SQUIB_BUILD'] = 'color'
+  Squib.enable_build_globally :color
   load 'build_groups.rb'
 end
 
 desc 'Build a test card'
 task :color do
-  ENV['SQUIB_BUILD'] = 'test'
+  Squib.enable_build_globally :test
   load 'build_groups.rb'
 end

spec/api/api_groups_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+require 'squib'
+
+describe :build_group do
+
+  context '#enable_build_globally' do
+    before(:each) { ENV['SQUIB_BUILD'] = '' }
+
+    it 'enables one group via ENV' do
+      Squib.enable_build_globally 'foo'
+      expect(ENV['SQUIB_BUILD']).to eq 'foo'
+    end
+
+    it 'enables two groups via ENV' do
+      Squib.enable_build_globally 'foo'
+      Squib.enable_build_globally 'bar'
+      expect(ENV['SQUIB_BUILD']).to eq 'foo,bar'
+    end
+
+    it 'uniqs the groups' do
+      Squib.enable_build_globally 'foo'
+      Squib.enable_build_globally 'bar'
+      Squib.enable_build_globally 'bar'
+      expect(ENV['SQUIB_BUILD']).to eq 'foo,bar'
+    end
+
+    it 'handles symbols' do
+      Squib.enable_build_globally :foo
+      expect(ENV['SQUIB_BUILD']).to eq 'foo'
+    end
+
+  end
+
+  context '#disable_build_globally' do
+    before(:each) { ENV['SQUIB_BUILD'] = 'foo,bar' }
+
+    it 'can be disabled globally via ENV' do
+      Squib.disable_build_globally 'bar'
+      expect(ENV['SQUIB_BUILD']).to eq 'foo'
+    end
+
+    it 'handles symbols' do
+      Squib.disable_build_globally :bar
+      expect(ENV['SQUIB_BUILD']).to eq 'foo'
+    end
+  end
+
+
+end