squib 0.0.2 → 0.0.3

data/Rakefile

@@ -1,11 +1,11 @@
-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
+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,19 +1,19 @@
-#!/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
-  
+#!/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.rb

@@ -1,19 +1,32 @@
-require 'logger'
-require 'cairo'
-require 'pango'
-require 'rsvg2'
-require 'squib/version'
-require 'squib/commands/new'
-require 'squib/deck'
-require 'squib/card'
-
-module Squib
-  
-  # :nodoc:
-  # @api private 
-  def logger
-    @logger ||= Logger.new(STDOUT)
-  end
-  module_function :logger
-  
+require 'logger'
+require 'cairo'
+require 'pango'
+require 'rsvg2'
+require 'squib/version'
+require 'squib/commands/new'
+require 'squib/deck'
+require 'squib/card'
+
+module Squib
+  
+  # Access the internal logger that Squib uses. By default, Squib configure the logger to the WARN level
+  # Use this to suppress or increase output levels. 
+  # @example
+  #   Squib.logger.level = Logger::DEBUG #show waaaay more information than you probably need, unless you're a dev
+  #   Squib.logger.level = Logger::ERROR #basically turns it off
+  # 
+  # @return [Logger] the ruby logger
+  # @api public 
+  def logger
+    if @logger.nil?
+      @logger = Logger.new(STDOUT);
+      @logger.level = Logger::WARN;
+      @logger.formatter = proc do |severity, datetime, progname, msg|
+        "#{severity} #{progname}: #{msg}\n"
+      end
+    end
+    @logger
+  end
+  module_function :logger
+  
 end

data/lib/squib/api/background.rb

@@ -1,17 +1,19 @@
-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
+module Squib
+  class Deck
+    # Fills the background with the given color 
+    # @example
+    #   background color: :white
+    #
+    # Options support Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    #
+    # @option opts range [Enumerable] (:all) the range of cards over which this will be rendered. See {file:README.md#Specifying_Ranges Specifying Ranges}
+    # @option opts color [String] (:black) the color the font will render to. See {file:README.md#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][i]) }
+    end
+      
+  end
 end

data/lib/squib/api/data.rb

@@ -1,52 +1,52 @@
-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
-
+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,49 +1,67 @@
-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
+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:README.md#Specifying_Ranges Specifying Ranges}
+    # @option opts file [String] ((empty)) 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. If any of them are nil or '', nothing is done. See {file:README.md#Specifying_Files Specifying Files}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts x [Integer] (0) the x-coordinate to place. Supports Arrays, see {file:README#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts y [Integer] (0) the y-coordinate to place. Supports Arrays, see {file:README#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:README.md#Custom_Layouts Custom Layouts}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts alpha [Decimal] (1.0) the alpha-transparency percentage used to blend this image. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts blend [:none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity] (:none) the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @return [nil] Returns nil
+    # @api public
+    def png(opts = {})
+      opts = needs(opts, [:range, :files, :x, :y, :alpha, :layout, :blend])
+      Dir.chdir(@img_dir) do
+        @progress_bar.start("Loading PNG(s)", opts[:range].size) do |bar|
+          opts[:range].each do |i| 
+            @cards[i].png(opts[:file][i], opts[:x][i], opts[:y][i], opts[:alpha][i], opts[:blend][i]) 
+            bar.increment
+          end
+        end
+      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:README.md#Specifying_Ranges Specifying Ranges}
+    # @option opts file [String] ('') 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. If any of them are nil or '', nothing is done. See {file:README.md#Specifying_Files Specifying Files}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts id [String] (nil) if set, then only render the SVG element with the given id. Prefix '#' is optional. Note: the x-y coordinates are still relative to the SVG document's page. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts force_id [Boolean] (false) if set, then this svg will not be rendered at all if the id is empty or nil. If not set, the entire SVG is rendered. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts x [Integer] (0) the x-coordinate to place. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts y [Integer] (0) the y-coordinate to place. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @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. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @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. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:README.md#Custom_Layouts Custom Layouts}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts alpha [Decimal] (1.0) the alpha-transparency percentage used to blend this image. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts blend [:none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity] (:none) the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @return [nil] Returns nil
+    # @api public
+    def svg(opts = {})
+      p = needs(opts,[:range, :files, :svgid, :force_svgid, :x, :y, :width, :height, :layout, :alpha, :blend])
+      Dir.chdir(@img_dir) do
+        @progress_bar.start("Loading SVG(s)", p[:range].size) do |bar|
+          p[:range].each do |i|
+            unless p[:force_id][i] && p[:id][i].to_s.empty?
+              @cards[i].svg(p[:file][i], p[:id][i], p[:x][i], p[:y][i], 
+                            p[:width][i], p[:height][i], p[:alpha][i], p[:blend][i]) 
+            end
+            bar.increment
+          end
+        end
+      end
+    end
+
+  end
 end

data/lib/squib/api/save.rb

@@ -1,37 +1,43 @@
-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
+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:README.md#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
+    # @option opts [Boolean] rotate (false) PNG saving only. If true, the saved cards will be rotated 90 degrees clockwise. Intended to rendering landscape instead of portrait.
+    # @return self
+    # @api public
+    def save(opts = {})
+      opts = needs(opts, [:range, :creatable_dir, :formats, :prefix, :rotate])
+      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:README.md#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.
+    # @option opts [Boolean, :clockwise, :counterclockwise] rotate (false) if true, the saved cards will be rotated 90 degrees clockwise. Or, rotate by the number of radians. Intended to rendering landscape instead of portrait.
+    # @return [nil] Returns nothing
+    # @api public
+    def save_png(opts = {})
+      opts = needs(opts,[:range, :creatable_dir, :prefix, :rotate])
+      @progress_bar.start("Saving PNGs to #{opts[:dir]}/#{opts[:prefix]}*", @cards.size) do |bar|
+        opts[:range].each do |i| 
+          @cards[i].save_png(i, opts[:dir], opts[:prefix], opts[:rotate], opts[:angle])
+          bar.increment
+        end
+      end
+    end
+
+  end
+end
+