squib 0.12.0 → 0.13.0

data/docs/guides/projects.rst

@@ -1,35 +0,0 @@
-Squib in Action
-===============
-
-Squib is in use by a lot of people! You can learn a lot from looking at how a whole project is put together.
-
-A good way to peruse Squib code is to search for Ruby files on GitHub that have the phrase ``require 'squib'`` in them. And these are the just the people who have decided to release their code open source!
-
-My Projects
------------
-
-Here are some of my own board and card games that use Squib. They are all under "active" development, which means that sometimes I leave them alone for long periods of time ;)
-
-  * `Your Last Heist <http://github.com/andymeneely/project-timber-wolf>`_ is a big-box cooperative game. Lots of really cool Squib things in here, including lots of Rake features, color+bw, and showing how skills can "level up" on their backs by diff'ing the stats in Squib. You can see what the components look like at `the game website <http://yourlastheist.com>`_. Also: the best game I've ever made.
-  * `Victory Point Salad <https://github.com/andymeneely/victory-point-salad>`_. A card-only game with lots and lots and lots of cards. Pretty straightforward as far as Squib usage goes, but it's a good peek into how I like to use Squib. Also: the funniest game I've made.
-  * `Junk Land <https://github.com/andymeneely/junk-land>`_ A game I made prior to making starting Squib, but then ported over to Squib while developing Squib. Uses some strange features of SVG, but also a good intro. Also: the scrappiest game I've made.
-
-.. note::
-
-  Want to donate back to Squib? Volunteer to playtest these games :)
-
-Other Projects using Squib
---------------------------
-
-Poking around GitHub, here are a few sightings of Squib:
-
-  * `Ecovalia <https://github.com/evolve2k/ecovalia-game>`_ - a game rapidly prototyped in a hackathon. Squib is featured in their video!
-  * `Werewolf <https://github.com/Xpktro/werewolf>`_ implemented and even uses GitHub releases!
-  * `Cult Following <https://github.com/ericathegreat/Cult-Following>`_ is a neat-looking project
-  * ScrapyardArmory's `Dysplacement <https://www.thegamecrafter.com/games/dysplacement>`_ was used with Squib, and **won** the `Worker Placement contest <https://www.thegamecrafter.com/games/dysplacement>`_ over at TheGameCrafter.
-  * `Mad World <https://github.com/spilth/madworld>`_ uses CircleCI to build, even with some custom fonts.
-
-Want yours here?
-----------------
-
-Create an issue on Github and ask for a link her and  we'll add it here!

data/docs/help.rst

@@ -1,157 +0,0 @@
-Get Help and Give Help
-======================
-
-.. raw:: html
-
-  On BoardGameGeek.com? Show your Squib pride by <a href="https://boardgamegeek.com/microbadge/37841">getting the microbadge <img src="https://cdn.rawgit.com/andymeneely/squib/gh-pages/images/microbadge.png"></a> and <a href="https://boardgamegeek.com/guilds/2601">joining our guild!</a>
-
-Get Help
---------
-
-Squib is powerful and customizable, which means it can get complicated pretty quickly. Don't settle for being stuck.
-
-Here's an ordered list of how to find help:
-
-1. Go through this documentation
-2. Go through `the wiki <https://github.com/andymeneely/squib/wiki>`_
-3. Go through `the samples <https://github.com/andymeneely/squib/tree/master/samples>`_
-4. Google it - people have asked lots of questions about Squib already in many forums.
-5. Ask on Stackoverflow `using the tags "ruby" and "squib" <http://stackoverflow.com/questions/ask?tags=ruby squib>`_. You will get answers quickly from Ruby programmers it's and a great way for us to archive questions for future Squibbers.
-6. Our `thread on BoardGameGeek <http://boardgamegeek.com/thread/1293453>`_ or `our guild <https://boardgamegeek.com/guild/2601>`_ is quite active and informal (if a bit unstructured).
-
-If you email me directly I'll probably ask you to post your question publicly so we can document answers for future Googling Squibbers.
-
-Please use GitHub issues for bugs and feature requests.
-
-Help by Troubleshooting
------------------------
-
-One of the best ways you can help the Squib community is to be active on the above forums. Help people out. Answer questions. Share your code. Most of those forums have a "subscribe" feature.
-
-You can also watch the project on GitHub, which means you get notified when new bugs and features are entered. Try reproducing code on your own machine to confirm a bug. Help write minimal test cases. Suggest workarounds.
-
-Help by Beta Testing
---------------------
-
-.. Testers needed!! If you want to test new features as I develop them, or make sure I didn't break your code, you can always point your Gemfile to the repository and follow what I'm doing there. Your Gemfile specification looks like this::
-..
-..   gem 'squib', git: 'git://github.com/andymeneely/squib', branch: 'dev'
-..
-.. * The ``dev`` branch is where I am working on features in-process. I have not done much regression testing at this point, but would love testing feedback nonetheless.
-.. * The ``master`` branch is where I consider features and bug that are done and tested, but not released yet.
-
-Squib is a small operation. And programming is hard. So we need testers! In particular, I could use help from people to do the following:
-
-  * Test out new features as I write them
-  * Watch for regression bugs by running their current projects on new Squib code, checking for compatibility issues.
-
-Want to join the mailing list and get notifications? https://groups.google.com/forum/#!forum/squib-testers
-
-There's no time commitment expectation associated with signing up. Any help you can give is appreciated!
-
-Beta: Using Pre-Builds
-^^^^^^^^^^^^^^^^^^^^^^
-
-The preferred way of doing beta testing is by to get Squib directly from my GitHub repository. Bundler makes this easy.
-
-If you are just starting out you'll need to install bundler::
-
-  $ gem install bundler
-
-Then, in the root of your Squib project, create a file called `Gemfile` (capitalization counts). Put this in it::
-
-  source 'https://rubygems.org'
-
-  gem 'squib', git: 'git://github.com/andymeneely/squib', branch: 'master'
-
-Then run::
-
-  $ bundle install
-
-Your output will look something like this::
-
-
-  Fetching git://github.com/andymeneely/squib
-  Fetching gem metadata from https://rubygems.org/.........
-  Fetching version metadata from https://rubygems.org/...
-  Fetching dependency metadata from https://rubygems.org/..
-  Resolving dependencies...
-  Using pkg-config 1.1.6
-  Using cairo 1.14.3
-  Using glib2 3.0.7
-  Using gdk_pixbuf2 3.0.7
-  Using mercenary 0.3.5
-  Using mini_portile2 2.0.0
-  Using nokogiri 1.6.7
-  Using pango 3.0.7
-  Using rubyzip 1.1.7
-  Using roo 2.3.0
-  Using rsvg2 3.0.7
-  Using ruby-progressbar 1.7.5
-  Using squib 0.9.0b from git://github.com/andymeneely/squib (at master)
-  Using bundler 1.10.6
-  Bundle complete! 1 Gemfile dependency, 14 gems now installed.
-  Use `bundle show [gemname]` to see where a bundled gem is installed.
-
-To double-check that you're using the test version of Squib, puts this in your code::
-
-  require 'squib'
-  puts Squib::VERSION # prints the Squib version to the console when you run this code
-
-  # Rest of your Squib code...
-
-When you run your code, say ``deck.rb``, you'll need to put ``bundle exec`` in front of it. Otherwise Ruby will just go with full releases (e.g. ``0.8`` instead of pre-releases, e.g. ``0.9a``). That would look like this::
-
-  $ bundle exec ruby deck.rb
-
-If you need to know the exact commit of the build, you can see that commit hash in the generated ``Gemfile.lock``. That ``revision`` field will tell you the *exact* version you're using, which can be helpful for debugging. That will look something like this::
-
-  remote: git://github.com/andymeneely/squib
-    revision: 440a8628ed83b24987b9f6af66ad9a6e6032e781
-    branch: master
-
-To update to the latest from the repository, run ``bundle up``.
-
-To remove Squib versions, run ``gem cleanup squib``. This will also remove old Squib releases.
-
-Beta: About versions
-^^^^^^^^^^^^^^^^^^^^
-
-  * When the version ends in "a" (e.g. ``v0.9a``), then the build is "alpha". I could be putting in new code all the time without bumping the version. I try to keep things as stable after every commit, but this is considered the least stable code. (Testing still appreciated here, though.) This is also tracked by my ``dev`` branch.
-  * For versions ending in "b" (e.g. ``v0.9b``), then the build is in "beta". Features are frozen until release, and we're just looking for bug fixes.  This tends to be tracked by the ``master`` branch in my repository.
-  * I follow the `Semantic Versioning <http://semver.org>`_ as best I can
-
-Beta: About Bundler+RubyGems
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The Gemfile is a configuration file (technically it's a Ruby DSL) for a widely-used library in the Ruby community called Bundler. Bundler is a way of managing multiple RubyGems at once, and specifying exactly what you want.
-
-Bundler is different from RubyGems. Technically, you CAN use RubyGems without Bundler: just ``gem install`` what you need and your ``require`` statements will work. BUT Bundler helps you specify versions with the Gemfile, and where to get your gems. If you're switching between different versions of gems (like with being tester!), then Bundler is the way to go. The Bundler website is here: http://bundler.io/.
-
-By convention, your ``Gemfile`` should be in the root directory of your project. If you did ``squib new``, there will be one created by default. Normally, a Squib project Gemfile will look `like this <https://github.com/andymeneely/squib/blob/master/lib/squib/project_template/Gemfile>`_. That configuration just pulls the Squib from RubyGems.
-
-But, as a tester, you'll want to have Bundler install Squib from my repository. That would look like this: https://github.com/andymeneely/project-spider-monkey/blob/master/Gemfile. (Just line 4 - ignore the other stuff.) I tend to work with two main branches - dev and master. Master is more stable, dev is more bleeding edge. Problems in the master branch will be a surprise to me, problems in the dev branch probably won't surprise me.
-
-After changing your Gemfile, you'll need to run ``bundle install``. That will generate a ``Gemfile.lock`` file - that's Bundler's way of saying exactly what it's planning on using. You don't modify the Gemfile.lock, but you can look at it to see what version of Squib it's locked onto.
-
-
-
-Help by Fixing Bugs
--------------------
-
-A great way to make yourself known in the community is to go over `our backlog <https://github.com/andymeneely/squib/issues>`_ and work on fixing bugs. Even suggestions on troubleshooting what's going on (e.g. trying it out on different OS versions) can be a big help.
-
-Help by Contributing Code
--------------------------
-
-Our biggest needs are in community support. But, if you happen to have some code to contribute,  follow this process:
-
-1. Fork the git repository ( https://github.com/[my-github-username]/squib/fork )
-2. Create your feature branch (``git checkout -b my-new-feature``)
-3. Commit your changes (``git commit -am 'Add some feature'``)
-4. Push to the branch (``git push origin my-new-feature``)
-5. Create a new Pull Request
-
-Be sure to write tests and samples for new features.
-
-Be sure to run the unit tests and packaging with just ``rake``. Also, you can check that the samples render properly with ``rake sanity``.

data/docs/index.rst

@@ -1,35 +0,0 @@
-Squib Documentation
-===================
-
-Welcome to the official Squib documentation!
-
-Contents:
-
-.. toctree::
-   :maxdepth: 3
-
-   install
-   learning
-   parameters
-   arrays
-   layouts
-   data
-   units
-   colors
-   text_feature
-   bleed
-   config
-   backends
-   build_groups
-   help
-   dsl/index.rst
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
-
-
-.. meta::
-   :google-site-verification: BWelviUOeiImUuyxt54P6YinZcSuxHm8_aQidm9ju-U

data/docs/install.rst

@@ -1,68 +0,0 @@
-Install & Update
-================
-
-Squib is a Ruby gem, and installation is handled like most gems.
-
-Pre-requisites
---------------
-
-  * `Ruby 2.1+ <https://www.ruby-lang.org>`_
-
-Squib works with both x86 and x86_64 versions of Ruby.
-
-Typical Install
----------------
-
-Regardless of your OS, installation is
-
-.. code-block:: none
-
-  $ gem install squib
-
-If you're using `Bundler <http://bundler.io>`_, add this line to your application's Gemfile::
-
-  gem 'squib'
-
-And then execute::
-
-  $ bundle install
-
-Squib has some native dependencies, such as `Cairo <https://github.com/rcairo/rcairo>`_, `Pango <http://ruby-gnome2.sourceforge.jp/hiki.cgi?Pango%3A%3ALayout>`_, and `Nokogiri <http://nokogiri.org/>`_, which will compile upon installation - this is normal.
-
-Updating Squib
---------------
-
-At this time we consider Squib to be still in initial development, so we are not supporting older versions. Please upgrade your Squib as often as possible.
-
-To keep track of when new Squib releases come out, you can watch the `BoardGameGeek thread <https://boardgamegeek.com/thread/1293453>`_ or follow the RSS feed for Squib on its `RubyGems page <https://rubygems.org/gems/squib>`_.
-
-In RubyGems, the command looks like this::
-
-  $ gem up squib
-
-As a quirk of Ruby/RubyGems, sometimes older versions of gems get caught in caches. You can see which versions of Squib are installed and clean them up, use ``gem list`` and ``gem cleanup``::
-
-  $ gem list squib
-
-  *** LOCAL GEMS ***
-
-  squib (0.9.0, 0.8.0)
-
-  $ gem cleanup squib
-  Cleaning up installed gems...
-  Attempting to uninstall squib-0.8.0
-  Successfully uninstalled squib-0.8.0
-  Clean Up Complete
-
-This will remove all prior versions of Squib.
-
-As a sanity check, you can see what version of Squib you're using by referencing the ``Squib::VERSION`` constant::
-
-  require 'squib'
-  puts Squib::VERSION
-
-
-OS-Specific Quirks
-------------------
-
-See the `wiki <http://github.com/andymeneely/squib/wiki>`_ for idiosyncracies about specific operating systems, dependency clashes, and other installation issues. If you've run into issues and solved them, please post your solutions for others!

data/docs/layouts.rst

@@ -1,290 +0,0 @@
-Layouts are Squib's Best Feature
-================================
-
-Working with tons of options to a method can be tiresome. Ideally everything in a game prototype should be data-driven, easily changed, and your Ruby code should readable without being littered with `magic numbers <http://stackoverflow.com/questions/47882/what-is-a-magic-number-and-why-is-it-bad>`_.
-
-For this, most Squib methods have a ``layout`` option. Layouts are a way of setting default values for any parameter given to the method. They let you group things logically, manipulate options, and use built-in stylings.
-
-Think of layouts and DSL calls like CSS and HTML: you can always specify style in your logic (e.g. directly in an HTML tag), but a cleaner approach is to group your styles together in a separate sheet and work on them separately.
-
-To use a layout, set the ``layout:`` option on ``Deck.new`` to point to a YAML file. Any command that allows a ``layout`` option can be set with a Ruby symbol or string, and the command will then load the specified options. The individual command can also override these options.
-
-For example, instead of this::
-
-  # deck.rb
-  Squib::Deck.new do
-    rect x: 75, y: 75, width: 675, height: 975
-  end
-
-You can put your logic in the layout file and reference them::
-
-  # custom-layout.yml
-  bleed:
-    x: 75
-    y: 75
-    width: 975
-    height: 675
-
-Then your script looks like this::
-
-  # deck.rb
-  Squib::Deck.new(layout: 'custom-layout.yml') do
-    rect layout: 'bleed'
-  end
-
-The goal is to make your Ruby code separate the data decisions from logic. For the above example, you are separating the decision to draw rectangle around the "bleed" area, and then your YAML file is defining specifically what "bleed" actually means. (Who is going to remember that ``x: 75`` means "bleed area"??) This process of separating logic from data makes your code more readable, changeable, and maintainable.
-
-.. warning::
-
-   YAML is very finnicky about not allowing tab characters. Use two spaces for indentation instead. If you get a ``Psych`` syntax error, this is likely the culprit. Indendation is also strongly enforced in Yaml too. See the `Yaml docs <http://www.yaml.org/YAML_for_ruby.html>`_ for more info.
-
-Order of Precedence for Options
--------------------------------
-
-Layouts will override Squib's system defaults, but are overriden by anything specified in the command itself. Thus, the order of precedence looks like this:
-
-  1. Use what the DSL method specified, e.g. ``rect x: 25``
-  2. If anything was not yet specified, use what was given in a layout (if a layout was specified in the command and the file was given to the Deck). e.g. ``rect layout: :bleed``
-  3. If still anything was not yet specified, use what was given in Squib's defaults as defined in the :doc:`dsl/index`.
-
-For example, back to our example::
-
-  # custom-layout.yml
-  bleed:
-    x: 0.25in
-    y: 0.25in
-    width: 2.5in
-    height: 3.5in
-
-(Note that this example makes use of :doc:`/units`)
-
-Combined with this script:
-
-.. code-block:: ruby
-
-  # deck.rb
-  Squib::Deck.new(layout: 'custom-layout.yml') do
-    rect layout: 'bleed', x: 50
-  end
-
-The options that go into ``rect`` will be:
-
-  * ``x`` will be 50 because it's specified in the DSL method and overrides the layout
-  * ``y``, ``width``, and ``height`` were specified in the layout file, so their values are used
-  * The rect's ``stroke_color`` (and others options like it) was never specified anywhere, so the default for ``rect`` is used - as discussed in :doc:`parameters`.
-
-.. note::
-
- Defaults are not global for the name of the option - they are specific to the method itself. For example, the default ``fill_color`` for ``rect`` is ``'#0000'`` but for ``showcase`` it's ``:white``.
-
-.. note::
-
-  Layouts work with *all* options (for DSL methods that support layouts), so you can use options like ``file`` or ``font`` or whatever is needed.
-
-.. warning::
-
-  If you provide an option in the Yaml file that is not supported by the DSL method, the DSL method will simply ignore it. Same behavior as described in :doc:`parameters`.
-
-
-When Layouts Are Similar, Use ``extends``
------------------------------------------
-
-Using layouts are a great way of keeping your Ruby code clean and concise. But those layout Yaml files can get pretty long. If you have a bunch of icons along the top of a card, for example, you're specifying the same ``y`` option over and over again. This is annoyingly verbose, and what if you want to move all those icons downward at once?
-
-Squib provides a way of reusing layouts with the special `extends`` key. When defining an ```extends`` key, we can merge in another key and modify its data coming in if we want to. This allows us to do things like place text next to an icon and be able to move them with each other. Like this::
-
-  # If we change attack, we move defend too!
-  attack:
-    x: 100
-    y: 100
-  defend:
-    extends: attack
-    x: 150
-    #defend now is {:x => 150, :y => 100}
-
-Over time, using ``extends`` saves you a lot of space in your Yaml files while also giving more structure and readability to the file itself.
-
-You can also **modify** data as they get passed through extends::
-
-  # If we change attack, we move defend too!
-  attack:
-    x: 100
-  defend:
-    extends: attack
-    x: += 50
-    #defend now is {:x => 150, :y => 100}
-
-The following operators are supported within evaluating ``extends``
-  * ``+=`` will add the giuven number to the inherited number
-  * ``-=`` will subtract the given number from the inherited number
-
-Both operators also support :doc:`/units`
-
-From a design point of view, you can also extract out a base design and have your other layouts extend from them::
-
-  top_icons:
-    y: 100
-    font: Arial 36
-  attack:
-    extends: top_icon
-    x: 25
-  defend:
-    extends: top_icon
-    x: 50
-  health:
-    extends: top_icon
-    x: 75
-  # ...and so on
-
-.. note::
-
-   Those fluent in Yaml may notice that ``extends`` key is similar to Yaml's `merge keys <http://www.yaml.org/YAML_for_ruby.html#merge_key>`_. Technically, you can use these together - but I just recommend sticking with ``extends`` since it does what merge keys do *and more*. If you do choose to use both ``extends`` and Yaml merge keys, the Yaml merge keys are processed first (upon Yaml parsing), then ``extends`` (after parsing).
-
-Yes, ``extends`` is Multi-Generational
---------------------------------------
-
-As you might expect, ``extends`` can be composed multiple times::
-
-  socrates:
-    x: 100
-  plato:
-    extends: socrates
-    x: += 10    # evaluates to 150
-  aristotle:
-    extends: plato
-    x: += 20    # evaluates to 150
-
-Yes, ``extends`` has Multiple Inheritance
------------------------------------------
-
-If you want to extend multiple parents, it looks like this::
-
-  socrates:
-    x: 100
-  plato:
-    y: 200
-  aristotle:
-    extends:
-      - socrates
-      - plato
-    x: += 50    # evaluates to 150
-
-If multiple keys override the same keys in a parent, the later ("younger") child in the ``extends`` list takes precedent. Like this::
-
-  socrates:
-    x: 100
-  plato:
-    x: 200
-  aristotle:
-    extends:
-      - plato    # note the order here
-      - socrates
-    x: += 50     # evaluates to 150 from socrates
-
-
-Multiple Layout Files get Merged
---------------------------------
-
-Squib also supports the combination of multiple layout files. If you provide an ``Array`` of files then Squib will merge them sequentially. Colliding keys will be completely re-defined by the later file. The ``extends`` key is processed after *each file*, but can be used across files. Here's an example::
-
-  # load order: a.yml, b.yml
-
-  ##############
-  # file a.yml #
-  ##############
-  grandparent:
-    x: 100
-  parent_a:
-    extends: grandparent
-    x: += 10   # evaluates to 110
-  parent_b:
-    extends: grandparent
-    x: += 20   # evaluates to 120
-
-  ##############
-  # file b.yml #
-  ##############
-  child_a:
-    extends: parent_a  # i.e. extends a layout in a separate file
-    x: += 3    # evaluates to 113 (i.e 110 + 3)
-  parent_b:    # redefined
-    extends: grandparent
-    x: += 30   # evaluates to 130 (i.e. 100 + 30)
-  child_b:
-    extends: parent_b
-    x: += 3    # evaluates to 133 (i.e. 130 + 3)
-
-This can be helpful for:
-  * Creating a base layout for structure, and one for full color for easier color/black-and-white switching
-  * Sharing base layouts with other designers
-
-Squib Comes with Built-In Layouts
----------------------------------
-
-Why mess with x-y coordinates when you're first prototyping your game? Just use a built-in layout to get your game to the table as quickly as possible.
-
-If your layout file is not found in the current directory, Squib will search for its own set of layout files.  The latest the development version of these can be found `on GitHub <https://github.com/andymeneely/squib/tree/master/lib/squib/layouts>`_.
-
-Contributions in this area are particularly welcome!!
-
-The following depictions of the layouts are generated with `this script <https://github.com/andymeneely/squib/tree/master/samples/layouts/builtin_layouts.rb>`_
-
-fantasy.yml
-~~~~~~~~~~~
-
-.. raw:: html
-
-  <img src="layouts/expected_layouts_builtin_fantasy_00.png"
-    class="figure" width=350>
-
-https://github.com/andymeneely/squib/tree/master/lib/squib/layouts/fantasy.yml
-
-economy.yml
-~~~~~~~~~~~
-
-.. raw:: html
-
-  <img src="layouts/expected_layouts_builtin_economy_00.png"
-    class="figure" width=350>
-
-https://github.com/andymeneely/squib/tree/master/lib/squib/layouts/economy.yml
-
-tuck_box.yml
-~~~~~~~~~~~~
-
-Based on TheGameCrafter's template.
-
-.. raw:: html
-
-  <img src="layouts/expected_layouts_builtin_tuck_box_00.png"
-    class="figure" width=450>
-
-https://github.com/andymeneely/squib/tree/master/lib/squib/layouts/tuck_box.yml
-
-
-hand.yml
-~~~~~~~~
-
-.. raw:: html
-
-  <img src="layouts/expected_layouts_builtin_hand_00.png"
-    class="figure" width=350>
-
-https://github.com/andymeneely/squib/tree/master/lib/squib/layouts/hand.yml
-
-playing_card.yml
-~~~~~~~~~~~~~~~~
-
-.. raw:: html
-
-  <img src="layouts/expected_layouts_builtin_playing_card_00.png"
-    class="figure" width=350>
-
-https://github.com/andymeneely/squib/tree/master/lib/squib/layouts/playing_card.yml
-
-See Layouts in Action
----------------------
-
-`This sample <https://github.com/andymeneely/squib/tree/master/samples/>`_ demonstrates many different ways of using and combining layouts.
-
-`This sample <https://github.com/andymeneely/squib/tree/master/samples/>`_ demonstrates built-in layouts based on popular games (e.g. ``fantasy.yml`` and ``economy.yml``)