squib 0.9.0 → 0.10.0

data/docs/config.rst

@@ -0,0 +1,117 @@
+Configuration Options
+=====================
+
+Squib supports various configuration properties that can be specified in an external file. By default, Squib looks for a file called ``config.yml`` in the current directory. Or, you can set the  ``config:`` option in ``Deck.new`` to specify the name of the configuration file.
+
+These properties are intended to be immutable for the life of the Deck, and intended to configure how Squib behaves.
+
+The options include:
+
+progress_bars
+  default: ``false``
+
+  When set to ``true``, long-running operations will show a progress bar in the console
+
+hint
+  default: ``:off``
+
+  Text hints are used to show the boundaries of text boxes. Can be enabled/disabled for individual commands, or set globally with the `hint` method. This setting is overridden by `hint` (and subsequently individual :doc:`/dsl/text`).
+
+custom_colors
+  default: ``{}``
+
+  Defines globally-available named colors available to the deck. Must be specified as a hash in yaml. For example::
+
+    # config.yml
+    custom_colors:
+      fg: '#abc'
+      bg: '#def'
+
+
+antialias
+  default: ``'best'``
+
+  Set the algorithm that Cairo will use for anti-aliasing throughout its rendering. Available options are ``fast``, ``good``, ``best``, ``none``, ``gray``, ``subpixel``.
+
+  Not every option is available on every platform. Using our benchmarks on large decks, `best` is only ~10% slower anyway. For more info see the `Cairo docs <http://www.cairographics.org/manual/cairo-cairo-t.html#cairo-antialias-t>`_.
+
+backend
+  default: ``'memory'``
+
+  Defines how Cairo will store the operations. Can be ``svg`` or ``memory``. See :doc:`/backends`.
+
+prefix
+  default: ``'card_'``
+
+  When using an SVG backend, cards are auto-saved with this prefix and ``'%02d'`` numbering format.
+
+warn_ellipsize
+  default: true
+
+  Show a warning on the console when text is ellipsized. Warning is issued per card.
+
+warn_png_scale
+  default: true
+
+  Show a warning on the console when a PNG file is upscaled. Warning is issued per card.
+
+lsquote
+  default: ``"\u2018"``
+
+  Smart quoting: change the left single quote when ``markup: true``
+
+rsquote
+  default: ``"\u2019"``
+
+  Smart quoting: change the right single quote when ``markup: true``
+
+ldquote
+  default: ``"\u201C"``
+
+  Smart quoting: change the left double quote when ``markup: true``
+
+rdquote
+  default: ``"\u201D"``
+
+  Smart quoting: change the right double quote when ``markup: true``
+
+em_dash
+  default: ``"\u2014"``
+
+  Convert the ``--`` to this character when ``markup: true``
+
+en_dash
+  default: ``"\u2013"``
+
+  Convert the ``---`` to this character when ``markup: true``
+
+
+ellipsis
+  default: ``"\u2026"``
+
+  Convert ``...`` to this character when ``markup: true``
+
+smart_quotes
+  default: true
+
+  When ``markup: true``, the ``text`` method will convert quotes. With ``smart_quotes: false``, explicit replacements like em-dashes and en-dashes will be replaced but not smart quotes.
+
+
+Options are available as methods
+--------------------------------
+
+For debugging/sanity purposes, if you want to make sure your configuration options are parsed correctly, the above options are also available as methods within ``Squib::Deck``, for example::
+
+  Squib::Deck.new do
+    puts backend # prints 'memory' by default
+  end
+
+
+Making Squib Verbose
+--------------------
+
+By default, Squib's logger is set to ``WARN``, but more fine-grained logging is embedded in the code. To set the logger, just put this at the top of your script::
+
+  Squib::logger.level = Logger::INFO
+
+If you REALLY want to see tons of output, you can also set DEBUG, but that's not intended for general consumption.

data/docs/data.rst

@@ -0,0 +1,22 @@
+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
+--------------
+
+In both DSL methods, Squib will return a ``Hash`` of ``Arrays`` correspoding to each row. Thus, be sure to structure your data 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
+  * Columns represent data about cards (e.g. "Type", "Cost", or "Name")
+
+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.
+
+Quantity Explosion
+------------------
+
+If you want more than one copy of a card, then have a column in your data file called ``Qty`` and fill it with counts for each card. Squib's :doc:`/dsl/xlsx` and :doc:`/dsl/xlsx` methods will automatically expand those rows according to those counts. You can also customize that "Qty" to anything you like by setting the `explode` option (e.g. ``explode: 'Quantity'``). Again, see the specific methods for examples.

data/docs/dsl/background.rst

@@ -0,0 +1,20 @@
+background
+----------
+
+Fills the background with the given color
+
+
+Options
+^^^^^^^
+.. include:: /args/expansion.rst
+
+.. include:: /args/range.rst
+
+color
+  default: ``:black``
+
+  the color or gradient to fill the background with. See :doc:`/colors`.
+
+
+Examples
+^^^^^^^^

data/docs/dsl/build.rst

@@ -0,0 +1,32 @@
+build
+=====
+
+Establish a set of commands that can be enabled/disabled together to allow for customized builds. See :doc:`/build_groups` for ways to use this effectively.
+
+Required Arguments
+------------------
+
+.. note::
+
+  This is an argument, not an option like most DSL methods. See example below.
+
+group
+  default: ``:all``
+
+  The name of the build group. Convention is to use a Ruby symbol.
+
+
+&block
+  When this group is enabled (and only ``:all`` is enabled by default), then this block is executed. Otherwise, the block is ignored.
+
+
+Examples
+--------
+
+Use group to organize your Squib code into build groups::
+
+  Squib::Deck.new do
+    build :pnp do
+      save_pdf
+    end
+  end

data/docs/dsl/build_groups.rst

@@ -0,0 +1,23 @@
+build_groups
+============
+
+Returns the set of group names that have been enabled. See :doc:`/build_groups` for ways to use this effectively.
+
+Arguments
+---------
+
+(none)
+
+
+Examples
+--------
+
+Use group to organize your Squib code into build groups::
+
+  Squib::Deck.new do
+    enable_build :pnp
+    build :pnp do
+      save_pdf
+    end
+    puts build_groups # outputs :all and :pnp
+  end

data/docs/dsl/circle.rst

@@ -0,0 +1,27 @@
+circle
+------
+
+Draw a circle centered at the given coordinates
+
+Options
+^^^^^^^
+.. include:: /args/expansion.rst
+
+.. include:: /args/xy.rst
+
+radius
+  default: ``100``
+
+  radius of the circle. Supports :doc:`/units`.
+
+.. include:: /args/draw.rst
+.. include:: /args/range.rst
+.. include:: /args/layout.rst
+
+Examples
+^^^^^^^^
+
+.. literalinclude:: /../samples/shapes/_draw_shapes.rb
+   :language: ruby
+   :linenos:
+   :caption: This snippet and others like it live `here <https://github.com/andymeneely/squib/blob/master/samples/>`_

data/docs/dsl/cm.rst

@@ -0,0 +1,19 @@
+cm
+--
+
+Given centimeters, returns the number of pixels according to the deck's DPI.
+
+Parameters
+^^^^^^^^^^
+
+n
+  the number of centimeters
+
+
+Examples
+^^^^^^^^
+
+.. code-block:: ruby
+
+  cm(1)         # 118.11px (for default Deck::dpi of 300)
+  cm(2) + cm(1) # 354.33ox (for default Deck::dpi of 300)

data/docs/dsl/csv.rst

@@ -0,0 +1,62 @@
+csv
+===
+
+Pulls CSV data from .csv files into a hash of arrays keyed by the headers. First row is assumed to be the header row.
+
+Parsing uses Ruby's CSV, with options ``{headers: true, converters: :numeric}``
+http://www.ruby-doc.org/stdlib-2.0/libdoc/csv/rdoc/CSV.html
+
+The ``csv`` method is a member of ``Squib::Deck``, but it is also available outside of the Deck DSL with ``Squib.csv()``. This allows a construction like::
+
+  data = Squib.csv file: 'data.csv'
+  Squib::Deck.new(cards: data['name'].size) do
+  end
+
+
+Options
+-------
+
+file
+  default: ``'deck.csv'``
+
+  the CSV-formatted file to open. Opens relative to the current directory. If ``data`` is set, this option is overridden.
+
+data
+  default: ``nil``
+
+  when set, CSV will parse this data instead of reading the file.
+
+strip
+  default: ``true``
+
+  When ``true``, strips leading and trailing whitespace on values and headers
+
+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.
+
+col_sep
+  default: ``','``
+
+  Column separator. One of the CSV custom options in Ruby. See next option below.
+
+CSV custom options in Ruby standard lib.
+  All of the options in Ruby's std lib version of CSV are supported **except** ``headers`` is always ``true`` and ``converters`` is always set to ``:numeric``. See the `Ruby Docs <http://ruby-doc.org/stdlib-2.2.0/libdoc/csv/rdoc/CSV.html#method-c-new>`_ for information on the options.
+
+Individual Pre-processing
+-------------------------
+
+The ``xlsx`` 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.csv(file: 'sample.xlsx') 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
+--------

data/docs/dsl/curve.rst

@@ -0,0 +1,63 @@
+curve
+-----
+
+Draw a bezier curve using the given coordinates, from x1,y1 to x2,y2. The curvature is set by the control points cx1,cy2 and cx2,cy2.
+
+Options
+^^^^^^^
+.. include:: /args/expansion.rst
+
+x1
+  default: ``0``
+
+  the x-coordinate of the first endpoint. Supports :doc:`/units`.
+
+
+y1
+  default: ``0``
+
+  the y-coordinate of the first endpoint. Supports :doc:`/units`.
+
+
+x2
+  default: ``5``
+
+  the x-coordinate of the second endpoint. Supports :doc:`/units`.
+
+
+y2
+  default: ``5``
+
+  the y-coordinate of the second endpoint. Supports :doc:`/units`.
+
+
+cx1
+  default: ``0``
+
+  the x-coordinate of the first control point. Supports :doc:`/units`.
+
+
+cy1
+  default: ``0``
+
+  the y-coordinate of the first control point. Supports :doc:`/units`.
+
+
+cx2
+  default: ``5``
+
+  the x-coordinate of the second control point. Supports :doc:`/units`.
+
+
+cy2
+  default: ``5``
+
+  the y-coordinate of the second control point. Supports :doc:`/units`.
+
+
+.. include:: /args/draw.rst
+.. include:: /args/range.rst
+.. include:: /args/layout.rst
+
+Examples
+^^^^^^^^

data/docs/dsl/deck.rst

@@ -0,0 +1,45 @@
+Squib::Deck.new
+===============
+
+The main interface to Squib. Yields to a block that is used for most of Squib's operations. The majority of the :doc:`DSL methods </dsl/index>` are instance methods of ``Squib::Deck``.
+
+Options
+-------
+These options set immutable properties for the life of the deck. They are not intended to be changed in the middle of Squib's operation.
+
+width
+  default: ``825``
+
+  the width of each card in pixels, :doc:`including bleed </bleed>`. Supports :doc:`/units` (e.g. ``'2.5in'``).
+
+height
+  default: ``1125``
+
+  the height of each card in pixels, :doc:`including bleed </bleed>`. Supports :doc:`/units` (e.g. '3.5in').
+
+cards
+  default: ``1``
+
+  the number of cards in the deck
+
+dpi
+  default: ``300``
+
+  the pixels per inch when rendering out to PDF, doing :doc:`/units`, or other operations that require measurement.
+
+config
+  default: ``'config.yml'``
+
+  the file used for global settings of this deck, see :doc:`/config`. If the file is not found, Squib does not complain.
+
+  .. note ::
+
+    Since this option has ``config.yml`` as a default, then Squib automatically looks up a ``config.yml`` in the current working directory.
+
+layout
+  default: ``nil``
+
+  load a YML file of :doc:`custom layouts </layouts>`. Multiple files in an array are merged sequentially, redefining collisons in the merge process. If no layouts are found relative to the current working directory, then Squib checks for a `built-in layout <https://github.com/andymeneely/squib/tree/master/lib/squib/layouts>`_.
+
+Examples
+--------