squib 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3977769e38bdf72d2dd035c62648b2ffaae2085c
-  data.tar.gz: e9d8ad1586160caee1be3d2b497ab9c71daa56b2
+  metadata.gz: 1bdd8eafb413745ef16bdd12e11696a748ef60ec
+  data.tar.gz: 9fada45fed185c9b847f40b301d2e7283ad9b3ea
 SHA512:
-  metadata.gz: e8238d6b6e236a22a2bd164712771b9366f20e3d4d04101b0992d2517d666bd0e6cd8996c8ba24aeb56133b2d30b405ba37fd26a44f8d5b3017b1146bde63ad1
-  data.tar.gz: 4593d6fae7feac75dab22efa560042c7fc932f1b056d029ef53464bac21a1a2bda6a711336ef358c831de33930344251380975e66f16c73a1f1f8c1447191c0b
+  metadata.gz: e9b3665709f6d61c13eea918bfd63ec55877baa21d8e4ae056773e12ac6da08729cf0c123af7fc17b32aca28ff81d4d4b99afac45c58f32ec949546ae8840496
+  data.tar.gz: ddde2eead6b96ce895d5c39af1072e1cc36f6590fc17565a4ff6b1e4a6c93001f737b5bc657e5f004360c938b48a00c0b2f6551981a200f25346afab86a38e39

data/.gitignore

@@ -1,26 +1,29 @@
-.DS_Store
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
-*.bundle
-*.so
-*.o
-*.a
-mkmf.log
-_img
-samples/_img
-samples/_output/*.png
+.DS_Store
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.inch
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+_img
+samples/_img
+samples/_output/*.png
+samples/_output/*.pdf
+samples/_output/foo

data/.travis.yml

@@ -1,4 +1,6 @@
-language: ruby
-rvm:
-  - 2.0.0
-  - 2.1.0
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.2
+before_install: gem install bundler --version '~> 1.6' 
+

data/.yardopts

@@ -0,0 +1,6 @@
+--readme README.md
+--markup markdown
+--api public
+-
+API.md
+LICENSE.txt

data/API.md

@@ -0,0 +1,59 @@
+# Squib API
+
+The Squib DSL is based on a collection of methods provided to the `Squib::Deck` class. The general philosophy of Squib is to specify as little as possible with layers of defaults, highly flexible input, and good ol' Ruby duck-typing. Ruby does a lot to make Squib useful.
+
+# Squib::Deck and Squib::Card
+
+Squib essentially has two main classes: `Deck` and `Card`. `Deck` is the front-end, and `Card` is the back-end. The contract of `Deck` is to do the various manipulations of options and then delegate the operation to `Card` to do the low-level graphical operations. 
+
+For most users, I recommending solely using `Deck` methods. If you want to roll up your sleeves and get your hands messy, you can access the Cairo or Pango contexts the directly via the `Card` class. The API documentation doesn't really cover these, however, so you're on your own there.
+
+# Specifying Parameters
+
+Squib is all about sane defaults and shorthand specification. Arguments are almost always using hashes, which look a lot like [Ruby 2.0's named parameters](http://www.ruby-doc.org/core-2.0.0/doc/syntax/calling_methods_rdoc.html#label-Keyword+Arguments). This means you can specify your parameters in any order you please. All parameters are optional. For example `x` and `y` default to 0 (i.e. the upper-left corner of the card). Any parameter that is specified in the command overrides any Squib defaults, `config.yml` settings, or layout rules. 
+
+# Specifying Ranges
+
+Most public `Deck` methods allow a `range` to be specified as a first parameter. This parameter is used to access an internal `Array` of `Squib::Cards`. This can be an actual Ruby range, or anything that implements `#each` (thus can be an `Enumerable`). Integers are also supported for changing one card only. Negatives work from the back of the deck. Here are some examples from `samples/ranges.rb` found [here](https://github.com/andymeneely/squib/tree/master/samples/ranges.rb)
+
+{include:file:samples/ranges.rb}
+
+Many more examples can be found in `ranges.rb` in the [samples](https://github.com/andymeneely/squib/tree/master/samples/) folder . In particular, take a look at some idioms that uses hashes to denote things like card "types", or future-proofing against creating and deleting cards with an ID column.
+
+# Pixels and Other Units
+
+By default, Squib thinks in pixels. This decision was made so that we can have pixel-perfect layouts without automatically scaling everything, even though working in units is sometimes easier. To convert, we provide the `Deck#inch` method, as shown in `samples/units.rb` found [here](https://github.com/andymeneely/squib/tree/master/samples/units.rb)
+
+{include:file:samples/units.rb}
+
+# Specifying Colors
+
+Colors can be specified in a wide variety of ways, mostly in a hex-string. Take a look at the examples from `samples/colors.rb`, found [here](https://github.com/andymeneely/squib/tree/master/samples/colors.rb)
+
+{include:file:samples/colors.rb}
+
+Under the hood, Squib uses the `rcairo` [color parser](https://github.com/rcairo/rcairo/blob/master/lib/cairo/color.rb) to accept a variety of color specifications, along with over [300 pre-defined constants](https://github.com/rcairo/rcairo/blob/master/lib/cairo/colors.rb). 
+
+# Specifying Files
+
+All files opened for reading or writing (e.g. for `png` and `xlsx`) are opened relative to the current directory. Files opened for writing (e.g. for `save_png`) will be overwritten without warning. 
+
+# Custom Layouts
+
+Working with x-y coordinates all the time can be tiresome, and ideally everything in a game prototype should be data-driven and easily changed. For this, many Squib methods allow for a `layout` to be set. In essence, layouts are a way of setting default values for any argument given to the command. 
+
+To use a layout, set the `layout:` option on a `Deck.new` command 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 `x`, `y`, `width`, and `height`. The individual command can also override these options. 
+
+Note: YAML is very finnicky about having tabs in the file. Use two spaces for indentation instead.
+
+Layouts will override Squib's defaults, but are overriden by anything specified in the command itself. Thus, the order of precedence looks like this:
+
+* Use what the command specified
+* 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)
+* If still anything was not yet specified, use what was given in Squib's defaults.
+
+Layouts also allow for a special `extends` field that will copy all of the settings from another entry. Only a single level of extends are supported currently (contact the developer if you want multiple levels). 
+
+See the `use_layout` sample found [here](https://github.com/andymeneely/squib/tree/master/samples/)
+
+{include:file:samples/use_layout.rb}

data/Gemfile

@@ -1,2 +1,2 @@
-source 'https://rubygems.org'
-gemspec
+source 'https://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -1,22 +1,22 @@
-Copyright (c) 2014 Andy Meneely
-
-MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2014 Andy Meneely
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,55 +1,92 @@
-[![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)
-[![Dependency Status](https://gemnasium.com/andymeneely/squib.svg)](https://gemnasium.com/andymeneely/squib)
-
-# Squib
-
-Squib is a ruby DSL for prototyping card and board games. Think of it like [nanDeck](http://nandeck.it) done "the Ruby way". Start with some basic commands and generate print-ready PNGs and PDFs. 
-
-Squib is currently pre-release alpha. 
-
-```ruby
-require 'squib'
-
-Squib::Deck.new(width: 825, height: 1125, cards: 3) do
-  background color: [1.0,1.0,1.0]
-  data = xlsx file: 'sample.xlsx'
-
-  rect x: 15, y: 15, width: 795, height: 1095, x_radius: 50, y_radius: 50
-
-  text str: data['name'], x: 250, y: 55, font: 'Arial 54'
-  text str: data['level'], x: 65, y: 40, font: 'Arial 72'
-
-  png file: 'icon.png', x: 665, y: 30
-
-  save format: :png
-end
-```
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'squib'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install squib
-
-Note: Squib is based on the `cairo` and `pango` extensions, which require at least Ruby 2.0
-
-## API
-
-API docs to be written. See the `samples` directory.
-
-## Contributing
-
-1. Fork it ( 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
+# 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) [![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) [![Inline docs](http://inch-ci.org/github/andymeneely/squib.png?branch=master)](http://inch-ci.org/github/andymeneely/squib)
+Squib is a Ruby [DSL](http://en.wikipedia.org/wiki/Domain-specific_language) for prototyping card and board games. With Squib, you just write a little bit of Ruby and you can compile your game's data and images into a series of images raedy for print-and-play or even print-on-demand. Squib is very data-driven - think of it like [nanDeck](http://www.nand.it/nandeck/) done "the Ruby way". Squib currently supports:
+
+* Reading PNGs and SVGs using [Cairo](http://cairographics.org/)
+* Complex text rendering using [Pango](http://www.pango.org/)
+* Reading `.xlsx` files
+* Basic shape drawing
+* Rendering to PNGs and PDFs
+* Unit conversion
+* Specfiying your layouts in a YML file
+* Plus the full power of Ruby! 
+
+Check this out. 
+
+```ruby
+require 'squib'
+
+Squib::Deck.new do
+  text str: 'Hello, World!'  
+  save_png
+end
+```
+
+That script just created a deck of with 1 image at 825x1125 with the string "Hello, World" in the upper-left corner.
+
+## Installation
+
+Install it yourself with:
+
+    $ gem install squib
+
+If you're using Bundler, add this line to your application's Gemfile:
+
+    gem 'squib'
+
+And then execute:
+
+    $ bundle
+
+Note: 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 all require DevKit to compile C code. This is usually not painful, but can cause headaches on some setups. For Windows users, I *strongly* recommend using the *non-64 bit* RubyInstaller at http://rubyinstaller.org. For Mac, I recommend using [rvm](https://rvm.io). 
+
+Note: Squib requires Ruby 2.0 or later.
+
+## Getting Started
+
+After installing Squib, you can create a project and run your first build like this:
+
+```sh
+$ squib new my-cool-game
+$ cd my-cool-game
+$ ruby deck.rb
+```
+
+The `squib new` command will generate files and folders like this:
+
+```
+_output
+  gitkeep.txt
+.gitignore
+ABOUT.md
+config.yml
+deck.rb
+Gemfile
+layout.yml
+PNP NOTES.md
+```
+
+The central file here is `deck.rb`. Here's a basic example of a deck to work from:
+
+{include:file:samples/basic.rb basic.rb}
+
+## Learning Squib
+
+After going over this README, here are some other places to go learn Squib:
+
+* The YARD-generated API documentation [for the latest Squib gem](http://rubydoc.info/gems/squib/) is a method-by-method reference. I recommend starting with the `API` file, and looking at the `Deck` class. If you are following Squib master, see [the latest version](http://rubydoc.info/github/andymeneely/squib/frames)
+* The `samples` directory in the [source repository](https://github.com/andymeneely/squib) has lots of examples
+* Junk Land (link TBD) is my own creation that's uses Squib for both black-and-white print-and-play and full color.
+
+## Development
+
+Squib is currently in pre-release alpha, so the API is still maturing. If you are using Squib, however, I'd love to hear about it! Feel free to [file a bug or feature request](https://github.com/andymeneely/squib/issues).
+
+## Contributing
+
+Squib is an open source tool, and I would love participation. If you want your code integrated:
+
+1. Fork it ( 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

data/Rakefile

@@ -1,6 +1,11 @@
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-
-task :default => :spec
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new(:spec)
+task :default => [:install, :spec]
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files   = ['lib/**/*.rb', 'samples/**/*.rb']   # optional
+  #t.options = ['--any', '--extra', '--opts'] # optional
+end

data/bin/squib

@@ -1,2 +1,19 @@
-#!/usr/bin/env ruby
-require 'squib'
+#!/usr/bin/env ruby
+require 'squib'
+require 'mercenary'
+
+Mercenary.program(:squib) do |p|
+  p.version Squib::VERSION
+  p.description "A Ruby DSL for prototyping card games"
+  p.syntax "squib <subcommand> [options]"
+
+  p.command(:new) do |c|
+    c.syntax "new PATH"
+    c.description "Creates a new Squib project scaffolding in PATH. Must be a new directory or already empty." 
+
+    c.action do |args, options|
+      Squib::Commands::New.new.process(args)
+    end
+  end
+  
+end

data/lib/squib/api/background.rb

@@ -1,12 +1,17 @@
-module Squib
-  class Deck
-    #module API
-
-      def background(range: :all, color: '#000000')
-        range = rangeify(range)
-        range.each { |i| @cards[i].background(color) }
-      end
-      
-    #end
-  end
+module Squib
+  class Deck
+    # Fills the background with the given color 
+    # @example
+    #   background color: :white
+    #
+    # @option range [Enumerable] (:all) the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
+    # @option color [String] (:black) the color the font will render to. See {file:API.md#label-Specifying+Colors Specifying Colors}
+    # @return [nil] nothing
+    # @api public
+    def background(opts = {})
+      opts = needs(opts,[:range, :color])
+      opts[:range].each { |i| @cards[i].background(opts[:color]) }
+    end
+      
+  end
 end

data/lib/squib/api/data.rb

@@ -1,29 +1,52 @@
-require 'roo'
-
-module Squib
-  class Deck
-
-    def csv(file: 'deck.csv', header: true)
-      raise 'Not implemented!'
-    end
-
-    def xlsx(file: 'deck.xlsx', sheet: 0)
-      s = Roo::Excelx.new(file)
-      s.default_sheet = s.sheets.first
-      data = {}
-      s.first_column.upto(s.last_column) do |col|
-        header = s.cell(s.first_row,col).to_s
-        data[header] = []
-        (s.first_row+1).upto(s.last_row) do |row|
-          cell = s.cell(row,col)
-          # Roo hack for avoiding unnecessary .0's on whole integers
-          cell = s.excelx_value(row,col) if s.excelx_type(row,col) == [:numeric_or_formula, "General"]
-          data[header] << cell
-        end#row
-      end#col
-      data
-    end#xlsx
-
-  end
-end
-
+require 'roo'
+
+module Squib
+
+  # Pulls Excel data from `.xlsx` files into a column-based hash
+  #
+  # Pulls the data into a Hash of arrays based on the columns. First row is assumed to be the header row. 
+  # See the example `samples/excel.rb` in the [source repository](https://github.com/andymeneely/squib/tree/master/samples)
+  #
+  # @example
+  #   # Excel file looks like this:
+  #   # | h1 | h2 |
+  #   # ------------ 
+  #   # | 1  | 2  |
+  #   # | 3  | 4  |
+  #   data = xlsx file: 'data.xlsx', sheet: 0
+  #   {'h1' => [1,3], 'h2' => [2,4]}
+  #
+  # @option opts file [String]  the file to open. Must end in `.xlsx`. Opens relative to the current directory.
+  # @option opts sheet [Integer] (0) The zero-based index of the sheet from which to read.
+  # @return [Hash] a hash of arrays based on columns in the spreadsheet
+  # @api public
+  def xlsx(opts = {})
+    opts = Squib::SYSTEM_DEFAULTS.merge(opts)
+    opts = Squib::InputHelpers.fileify(opts)
+    s = Roo::Excelx.new(opts[:file])
+    s.default_sheet = s.sheets[opts[:sheet]]
+    data = {}
+    s.first_column.upto(s.last_column) do |col|
+      header = s.cell(s.first_row,col).to_s
+      data[header] = []
+      (s.first_row+1).upto(s.last_row) do |row|
+        cell = s.cell(row,col)
+        # Roo hack for avoiding unnecessary .0's on whole integers
+        cell = s.excelx_value(row,col) if s.excelx_type(row,col) == [:numeric_or_formula, "General"]
+        data[header] << cell
+      end#row
+    end#col
+    data
+  end#xlsx
+  module_function :xlsx
+
+  class Deck
+    
+    # Convenience call for Squib.xlsx
+    def xlsx(opts = {})
+      Squib.xlsx(opts)
+    end    
+
+  end
+end
+

data/lib/squib/api/image.rb

@@ -1,11 +1,49 @@
-module Squib
-  class Deck
-    
-    def png(range=:all, file: nil, x: 0, y: 0)
-      range = rangeify(range)
-      file = fileify(file)
-      range.each{ |i| @cards[i].png(file, x, y) }
-    end
-
-  end
+module Squib
+  class Deck
+    
+    # Renders a png file at the given location.
+    #
+    # See {file:samples/image.rb samples/image.rb} and {file:samples/tgc-overlay.rb samples/tgc-overlay.rb} as examples.
+    # Note: scaling not currently supported for PNGs.
+    # @example
+    #   png file: 'img.png', x: 50, y: 50
+    #
+    # @option opts range [Enumerable, :all] (:all) the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
+    # @option opts file [String, Array] ('') file(s) to read in. If it's a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. See {file:API.md#Specifying+Files Specifying Files}
+    # @option opts x [Integer] (0) the x-coordinate to place
+    # @option opts y [Integer] (0) the y-coordinate to place
+    # @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:API.md#label-Custom+Layouts Custom Layouts}
+    # @option opts alpha [Decimal] (1.0) the alpha-transparency percentage used to blend this image
+    # @return [nil] Returns nil
+    # @api public
+    def png(opts = {})
+      opts = needs(opts, [:range, :files, :x, :y, :alpha, :layout])
+      opts[:range].each do |i| 
+        @cards[i].png(opts[:file][i], opts[:x], opts[:y], opts[:alpha]) 
+      end
+    end
+
+    # Renders an entire svg file at the given location. Uses the SVG-specified units and DPI to determine the pixel width and height.
+    #
+    # See {file:samples/load-images.rb samples/load-images.rb} and {file:samples/tgc-overlay.rb samples/tgc-overlay.rb} as examples.
+    # @example 
+    #   svg 1..2, 'icon.svg', '#stone', x: 50, y:50
+    #
+    # @option opts range [Enumerable, :all] (:all) the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
+    # @option opts file [String, Array] ('') file(s) to read in. If it's a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. See {file:API.md#Specifying+Files Specifying Files}
+    # @option opts x [Integer] (0) the x-coordinate to place
+    # @option opts y [Integer] (0) the y-coordinate to place
+    # @option opts width [Integer] (:native) the pixel width that the image should scale to. SVG scaling is done with vectors, so the scaling should be smooth. When set to `:native`, uses the DPI and units of the loaded SVG document.
+    # @option opts height [Integer] (:native) the pixel width that the image should scale to. SVG scaling is done with vectors, so the scaling should be smooth. When set to `:native`, uses the DPI and units of the loaded SVG document.
+    # @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:API.md#label-Custom+Layouts Custom Layouts}
+    # @return [nil] Returns nil
+    # @api public
+    def svg(opts = {})
+      p = needs(opts,[:range, :files, :svgid, :x, :y, :width, :height, :layout])
+      p[:range].each do |i| 
+        @cards[i].svg(p[:file][i], p[:id], p[:x], p[:y], p[:width], p[:height]) 
+      end
+    end
+
+  end
 end

data/lib/squib/api/save.rb

@@ -1,16 +1,37 @@
-module Squib
-  class Deck
-  
-    def save(range: :all, dir: "_output", format: :png, prefix: "card_")
-      format = [format].flatten
-      save_png(range: range, dir: dir, prefix: prefix) if format.include? :png
-      save_pdf if format.include? :pdf
-    end
-    
-    def save_png(range: :all, dir: "_output", prefix: 'card_')
-      range = rangeify(range)
-      range.each { |i| @cards[i].save_png(i, dir, prefix) }
-    end
-
-  end
+module Squib
+  class Deck
+  
+    # Saves the given range of cards to either PNG or PDF
+    #
+    # @option opts [Enumerable] range (:all) the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
+    # @option opts [String] dir (_output) the directory for the output to be sent to. Will be created if it doesn't exist.
+    # @option opts [Symbol] format (:png)  the format that this will be rendered too. Options `:pdf, :png`. Array of both is allowed: `[:pdf, :png]`
+    # @option opts [String] prefix (card_) the prefix of the file name to be printed
+    # @return self
+    # @api public
+    def save(opts = {})
+      opts = needs(opts, [:range, :creatable_dir, :formats, :prefix])
+      save_png(opts) if opts[:format].include? :png
+      save_pdf(opts) if opts[:format].include? :pdf
+      self
+    end
+    
+    # Saves the given range of cards to a PNG 
+    #
+    # @example
+    #   save range: 1..8, dir: '_pnp', prefix: 'bw_'
+    #
+    # @option opts [Enumerable] range (:all) the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
+    # @option opts [String] dir (_output) the directory for the output to be sent to. Will be created if it doesn't exist.
+    # @option opts [String] prefix (card_) the prefix of the file name to be printed.
+    # @return [nil] Returns nothing
+    # @api public
+    def save_png(opts = {})
+      opts = needs(opts,[:range, :creatable_dir, :prefix])
+      opts[:range].each do |i| 
+        @cards[i].save_png(i, opts[:dir], opts[:prefix])
+      end
+    end
+
+  end
 end