squib 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dc3e963811aff757de4bb9fdbe27a512e108ea3f
-  data.tar.gz: 94098850ead4d37cae33a5040aa47f6fdf284c24
+  metadata.gz: 0608aabb4ced2bce20fa90269f10747796ec296e
+  data.tar.gz: cd08eebeaf494d3f116d045be57a04120aff27e2
 SHA512:
-  metadata.gz: 768da6ac1f30e27a6f50de8acc7e38ab82b466ed78b4fab69375c62de5deaae03bf3387bea76d6a0a778c2f76736335794bd7e4f28c37224a2e78d0ba4241e65
-  data.tar.gz: 153722e40cc1a4c3fe04ce30672d6489133d9ef5b692deac675b0705f92a6f04f90358c93a196120bb4a5e8d2e73c244cd77cfea88c10e4d986e6fb9aef77d24
+  metadata.gz: 6129e710a9b678f0c17ec360030f206ce30a7315eeaf133ddcfe662544240b8e67e68ee79c81400934434f0f8f49a62a6f619b52b74fde6e25e9053195243866
+  data.tar.gz: 1b8c6fe2cb4d580daec68d5cfcec00cf2f7b79eafe03b06d957eab8d3c7c0861204dd6d44d8ff4779a17d44d5554ca4a6cc50779d9258fc16de576a6b93b7757

data/.gitignore

@@ -11,6 +11,7 @@ _yardoc
 coverage
 docs/_build*
 doc/
+docs/_build
 lib/bundler/man
 pkg
 rdoc
@@ -28,6 +29,7 @@ samples/_img
 samples/_output/*.png
 samples/_output/*.pdf
 samples/_output/foo
+samples/**/_output/*
 rubocop.txt
 benchmarks/_output/*.png
 benchmarks/_output/*.pdf
@@ -36,3 +38,4 @@ samples/_output/*.svg
 *.sublime-workspace
 spec/samples/sanity.html
 spec/samples/_diffs/*.png
+.byebug_history

data/.travis.yml

@@ -1,6 +1,7 @@
 dist: trusty
 language: ruby
-sudo: false # taking advantage of container-based infrastructure
+sudo: true # need this for libgirepository1.0-dev
+# sudo: false # taking advantage of container-based infrastructure
 cache: bundler # cache bundled gems from build to build
 
 addons:
@@ -10,7 +11,8 @@ addons:
 
 rvm:
   - 2.2
-  - 2.3.0
+  - 2.3.3
+  - 2.4.0-preview3
 matrix:
   allow_failures:
-    - rvm: 2.3.0
+    - rvm: 2.4.0-preview3

data/CHANGELOG.md

@@ -1,7 +1,29 @@
 # Squib CHANGELOG
 Squib follows [semantic versioning](http://semver.org).
 
-## v0.11.0 / Unreleased
+## v0.12.0 / Unreleased
+
+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. Also will be documented in upcoming workflow tutorial.
+* The import methods `csv` and `xlsx` now return `Squib::DataFrame`, which behaves exactly as before - but has more cool features like being able to do `data.name` instead of `data['name']`. Also: check out `data.to_pretty_text`. Check out the docs. (#156)
+
+Bugs:
+* `showcase` works as expected when using `backend: svg` (#179)
+* Graphics will get flushed upon exit, so working under Guard with `backend: svg` is more reliable (#180)
+
+Docs:
+* Wrote out documentation for [Squib and GameIcons](http://squib.readthedocs.io/en/latest/guides/game_icons.html)
+* Wrote out documentation for Hello World! Dissected
+* Un-submoduled our samples and simply embedded them into the docs (e.g. [Squib Thinks in Arrays](http://squib.readthedocs.io/en/latest/arrays.html)). Lots of cleanup there
+* Wrote up [Squib in Action](http://squib.readthedocs.io/en/latest/guides/projects.html), which documents other Squib projects. Ask for yours to be put there!!
+
+Chores:
+* Bumped dependency roo to 2.5.1. Nothing that affects Squib users (probably).
+* Bumped graphics and text dependencies (cairo to 1.15.3, pango+rsvg et al. to 3.1.0). No new features for us, but some stability improvements.
+
+## v0.11.0 / 2016-09-05
 
 Features:
 * Unit conversion supports mm (#161)
@@ -18,7 +40,7 @@ Bugs:
 * Unit conversion is supported when using `extends` in layouts, as promised in the docs (#173)
 
 Compatibility:
-* I reworked the way icons are embedded, and that was a big change internally (#177). We're now using Pango's API in the expected way and not dealing with "undefined behavior" situations with zero-sized fonts and obscure UTF-8 characters as we were before. But, as a result, Pango handles custom shapes a little differently than before. Wrapping doesn't render exactly the same way as before, although it's acceptable in most cases. If you still find problems, please file a bug.
+* I reworked the way icons are embedded, and that was a big change internally (#177). We're now using Pango's API in the expected way and not dealing with "undefined behavior" situations with zero-sized fonts and obscure UTF-8 characters as we were before. But, as a result, Pango handles custom shapes acd  little differently than before. Wrapping doesn't render exactly the same way as before, although it's acceptable in most cases. If you still find problems, please file a bug.
 
 Special thanks to everyone who tested, reported, suggested, and helped for this release! bcompter, rhyok, temetherian, rpond-pa, Nibodhika,  briant-spindance, lcarlsen, spilth
 

data/README.md

@@ -1,8 +1,6 @@
-# Squib [![Gem Version](https://badge.fury.io/rb/squib.svg)](https://rubygems.org/gems/squib) [![Build Status](https://secure.travis-ci.org/andymeneely/squib.svg?branch=master)](https://travis-ci.org/andymeneely/squib) [![Vey][vey]][vey_url] [![Dependency Status](https://gemnasium.com/andymeneely/squib.svg)](https://gemnasium.com/andymeneely/squib) [![Coverage Status](https://img.shields.io/coveralls/andymeneely/squib.svg)](https://coveralls.io/r/andymeneely/squib) [![ReadTheDocs](https://readthedocs.org/projects/squib/badge/?version=latest)](http://squib.readthedocs.io/en/latest/?badge=latest) [![BoardGameGeek](https://cdn.rawgit.com/andymeneely/squib/gh-pages/images/microbadge.png)](https://boardgamegeek.com/guild/2601)
-Squib is a Ruby [DSL](http://en.wikipedia.org/wiki/Domain-specific_language) for prototyping card and board games. Write a little bit of Ruby, define your deck's stats, then compile your game into a series of images ready for print-and-play or even print-on-demand. Squib is very data-driven and built on the principle of Don't Repeat Yourself. Think of it like [nanDeck](http://www.nand.it/nandeck/) done "the Ruby way". Squib supports:
+# Squib [![Gem Version](https://badge.fury.io/rb/squib.svg)](https://rubygems.org/gems/squib) [![Build Status](https://secure.travis-ci.org/andymeneely/squib.svg?branch=master)](https://travis-ci.org/andymeneely/squib) [![Build status](https://ci.appveyor.com/api/projects/status/ptjw6fvjh73anlau/branch/master?svg=true)](https://ci.appveyor.com/project/andymeneely/squib/branch/master) [![Dependency Status](https://gemnasium.com/andymeneely/squib.svg)](https://gemnasium.com/andymeneely/squib) [![Coverage Status](https://img.shields.io/coveralls/andymeneely/squib.svg)](https://coveralls.io/r/andymeneely/squib) [![ReadTheDocs](https://readthedocs.org/projects/squib/badge/?version=latest)](http://squib.readthedocs.io/en/latest/?badge=latest) [![BoardGameGeek](https://cdn.rawgit.com/andymeneely/squib/gh-pages/images/microbadge.png)](https://boardgamegeek.com/guild/2601)
 
-[vey]: https://ci.appveyor.com/api/projects/status/github/andymeneely/squib?svg=true
-[vey_url]: https://ci.appveyor.com/project/andymeneely/squib
+Squib is a Ruby [DSL](http://en.wikipedia.org/wiki/Domain-specific_language) for prototyping card and board games. Write a little bit of Ruby, define your deck's stats, then compile your game into a series of images ready for print-and-play or even print-on-demand. Squib is very data-driven and built on the principle of Don't Repeat Yourself. Think of it like [nanDeck](http://www.nand.it/nandeck/) done "the Ruby way". Squib supports:
 
 * A concise set of rules for laying out your cards
 * Loading PNGs and SVGs

data/RELEASE TODO.md

@@ -3,6 +3,7 @@ Be sure to remember to do the following for releases. (Copy into a GitHub issue)
  - [ ] CHANGELOG is written for all new changes
  - [ ] README is updated
  - [ ] Samples are updated
+ - [ ] Are all the dependencies up to date?
  - [ ] Check `sample_regression_spec.rb` regression tests are all enabled (i.e. `overwrite_sample` is commented out)
  - [ ] Bump version.rb
  - [ ] Bump docs/conf.py versions

data/Rakefile

@@ -4,7 +4,7 @@ require 'benchmark'
 # require 'byebug'
 
 desc 'install + spec'
-task default: [:install, :spec]
+task default: ['install:local', :spec]
 
 # Useful for hooking up with SublimeText.
 # e.g. rake sample[basic.rb]

data/docs/arrays.rst

@@ -66,10 +66,13 @@ Examples
 
 Here are a few recipes for using arrays and ranges in practice:
 
-.. raw:: HTML
+.. literalinclude:: ../samples/ranges/_ranges.rb
+  :language: ruby
+  :linenos:
 
-  <script src="https://gist.github.com/andymeneely/25b0da2a84ab906bd44b.js"></script>
+.. raw:: html
 
+  <img src="ranges/ranges_00_expected.png">
 
 Contribute Recipes!
 -------------------

data/docs/build_groups.rst

@@ -9,36 +9,34 @@ Squib's Build Groups help you with these situations. By grouping your Squib code
 
 Here's a basic example:
 
-.. raw:: html
+.. literalinclude:: ../samples/build_groups/build_groups.rb
+  :language: ruby
+  :linenos:
 
-  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
-  <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/gist-embed/2.4/gist-embed.min.js"></script>
-  <code data-gist-id="bda48487e3b8c9d15edb" data-gist-file="build_groups.rb"></code>
-
-Only one group is enabled by default: ``:all``. All other groups are disabled by default. To see which groups are enabled currently, the :doc:`/dsl/groups` returns the set.
+Only one group is enabled by default: ``:all``. All other groups are disabled by default. To see which groups are enabled currently, the :doc:`/dsl/build_groups` returns the set.
 
 Groups can be enabled and disabled in several ways:
 
-  * The :doc:`/dsl/enable_group` and :doc:`/dsl/disable_group`  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 <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.
+  * 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. 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 (see above gist for examples in various OS's).
+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.
-
-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:
+  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.
 
+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:
 
-.. raw:: html
 
-  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
-  <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/gist-embed/2.4/gist-embed.min.js"></script>
-  <code data-gist-id="bda48487e3b8c9d15edb" data-gist-file="Rakefile"></code>
+.. literalinclude:: ../samples/build_groups/Rakefile
+  :language: ruby
+  :linenos:
 
+Thus, you can just run this code on the command line like these:
 
-Thus, you can just run this code with commands like these::
+.. code-block:: none
 
   $ rake
   $ rake pnp

data/docs/colors.rst

@@ -40,7 +40,7 @@ by custom name
 In your ``config.yml``, as described in :doc:`/config`, you can specify custom names of colors. For example, ``'foreground'``.
 
 Gradients
---------
+---------
 
 In most places where colors are allowed, you may also supply a string that defines a gradient. Squib supports two flavors of gradients: linear and radial. Gradients are specified by supplying some xy coordinates, which are relative to the card (not the command). Each stop must be between ``0.0`` and ``1.0``, and you can supply as many as you like. Colors can be specified as above (in any of the hex notations or built-in constant). If you add two or more colors at the same stop, then the gradient keeps the colors in the in order specified and treats it like sharp transition.
 
@@ -60,5 +60,31 @@ In both of these formats, whitespace is ignored between tokens so as to make com
 
 If you need something more powerful than these two types of gradients (e.g. mesh gradients), then we suggest encapsulating your logic within an SVG and using the :doc:`/dsl/svg` method to render it.
 
-Examples
---------
+Samples
+-------
+
+Code is maintained in the `repository here <https://github.com/andymeneely/squib/tree/master/samples>`_ in case you need some of the assets referenced.
+
+Sample: colors and color constants
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ../samples/colors/_colors.rb
+  :language: ruby
+  :linenos:
+
+.. raw:: html
+
+  <img src="colors/colors_00_expected.png" width=600 class="figure">
+
+  <img src="colors/color_constants_00_expected.png" width=600 class="figure">
+
+Sample: gradients
+^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ../samples/colors/_gradients.rb
+  :language: ruby
+  :linenos:
+
+.. raw:: html
+
+  <img src="colors/gradient_00_expected.png" width=600 class="figure">

data/docs/conf.py

@@ -55,9 +55,9 @@ author = u'Andy Meneely'
 # built documents.
 #
 # The short X.Y version.
-version = u'v0.11'
+version = u'v0.12'
 # The full version, including alpha/beta/rc tags.
-release = u'v0.11.0'
+release = u'v0.12.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -74,7 +74,7 @@ language = None
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', 'args/*.rst']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

data/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
 --------------------

data/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
 ------------------

data/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:

data/docs/dsl/csv.rst

@@ -60,3 +60,22 @@ The ``xlsx`` method also takes in a block that will be executed for each cell in
 
 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:

data/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.               |
+              ╰------------------------------------╯

data/docs/dsl/disable_build.rst

@@ -1,7 +1,7 @@
 disable_build
 =============
 
-Disable the given build group for the rest of the build. Thus, code within the corresponding :doc:`/dsl/group` block will not be executed. See :doc:`/build_groups` for ways to use this effectively.
+Disable the given build group for the rest of the build. Thus, code within the corresponding :doc:`/dsl/build` block will not be executed. See :doc:`/build_groups` for ways to use this effectively.
 
 
 Required Arguments
@@ -11,9 +11,6 @@ build_group_name
   default: ``:all``
   the name of the group to disable. Convention is to use a Ruby symbol.
 
-.. note::
-
-
 
 Examples
 --------