diff --git a/CHANGELOG.md b/CHANGELOG.md index 918a3e1..6936bff 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/docs/build_groups.rst b/docs/build_groups.rst index aa83e99..3251502 100644 --- a/docs/build_groups.rst +++ b/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. - * When a ``Squib::Deck`` is initialized, the `environment variable `_ ``SQUIB_BUILD`` is consulted for a comma-separated string. These are converted to Ruby symbols and the corresponding groups are enabled. + * 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 `_ ``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 ` and :doc:`Squib.disable_build_globally ` to manipulate ``SQUIB_BUILD`` environment variable programmatically (e.g. from a Rakefile, inside a `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 `_ 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 diff --git a/docs/dsl/disable_build_globally.rst b/docs/dsl/disable_build_globally.rst new file mode 100644 index 0000000..5ae3106 --- /dev/null +++ b/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 diff --git a/docs/dsl/enable_build_globally.rst b/docs/dsl/enable_build_globally.rst new file mode 100644 index 0000000..f132f1d --- /dev/null +++ b/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 diff --git a/docs/guides/guard.rst b/docs/guides/guard.rst index d4f3a91..2e311e4 100644 --- a/docs/guides/guard.rst +++ b/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. diff --git a/lib/squib/api/groups.rb b/lib/squib/api/groups.rb index e20932d..5d5ae47 100644 --- a/lib/squib/api/groups.rb +++ b/lib/squib/api/groups.rb @@ -2,13 +2,20 @@ require 'set' module Squib - # An idea for later... - # def enable_group_env group - # ENV['SQUIB_BUILD'] ||= '' - # ENV['SQUIB_BUILD'] += ',' - # ENV['SQUIB_BUILD'] += group - # end - # module_function :enable_group_env + # DSL method. See http://squib.readthedocs.io + def enable_build_globally group + groups = (ENV['SQUIB_BUILD'] ||= '').split(',') + ENV['SQUIB_BUILD'] = (groups << group).uniq.join(',') + end + module_function :enable_build_globally + + # 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 diff --git a/samples/build_groups/Rakefile b/samples/build_groups/Rakefile index 7aecac1..7fd2a2c 100644 --- a/samples/build_groups/Rakefile +++ b/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 diff --git a/spec/api/api_groups_spec.rb b/spec/api/api_groups_spec.rb new file mode 100644 index 0000000..c5f8c32 --- /dev/null +++ b/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