squib 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 88dc6fa44ed331fbc2a3985342f8643411150ccf
-  data.tar.gz: 53688a6d02c0f26ab0f80a0e6cad0c801e101305
+  metadata.gz: 1f92ed35ef9dd4ecc229f5608a621af891c3e31f
+  data.tar.gz: d45847e33458b00f6642558892abeb4f7682e0f0
 SHA512:
-  metadata.gz: 45d3440c0f8e28a459d12a89a650ec30e0c6d3d8b1c22b1ca558927af336d4f9f0be562ce7b50c3e52a1bfd3c08cfd0973b7e8e15b405fee66727fd3c1f6002b
-  data.tar.gz: d2d258e94fdaf3be396de46dc3ffccd8ce55c87735b714657a2d60c42f063ca1a6ac0c7ad4cc8bb8fce1ac10c76865d266d656f91f0707c13d1aece99ad3a869
+  metadata.gz: d0fe30d4bfcf1f528140cbda4cd3662b88a06b605093390d2bf0ad28243b83b54ca97a294a3882f161db92d51ee13654519285df0c555c1e7aa5848a14de3520
+  data.tar.gz: 0acfc9a5e09394528b0eb3a6ed5df1ae528b18324ffe336e1f01d981ef839808283ab1b66468d66568869a376e99fde087bd2dfb9381069d353be29d15ba8a75

data/.yardopts

@@ -1,8 +1,10 @@
 --readme README.md
---markup-provider=redcarpet
+--title 'Squib API Documentation'
 --markup markdown
+--markup-provider=redcarpet
 --api public
 --asset samples:samples
+--charset utf-8
 -
 samples/**/*.rb
 LICENSE.txt

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Squib CHANGELOG
 
+## v0.0.6
+# Added a `csv` command that works just like `xslx`. Uses Ruby's CSV inside, with some extra checking and warnings. 
+# Custom layouts now support loading & merging multiple Yaml files! Updated README, docs, and sample to document it.
+# Built-in layouts! Currently we support `hand.yml` and `playing-card.yml`. Documented in the `layouts.rb` sample.
+# `text` now returns the ink extent rectangle of the rendered text. Updated docs and sample to document it.
+# Samples now show that you can use text instead of symbols for things like `center`
+# Improved logging, and documentation on increasing logger verboseness
+# Better regression testing technique that tracks when a sample has changed.
+# Bumped version of Cairo to ~> 1.14
+
 ## v0.0.5
 * Image rotation for png and svg via `angle`
 * New sample for demonstrating direct cairo access

data/README.md

@@ -4,7 +4,7 @@ Squib is a Ruby [DSL](http://en.wikipedia.org/wiki/Domain-specific_language) for
 * A concise set of rules for laying out your cards
 * Loading PNGs and SVGs using [Cairo](http://cairographics.org/)
 * Complex text rendering using [Pango](http://www.pango.org/)
-* Reading `.xlsx` files
+* Reading `xlsx` and `csv` files
 * Basic shape drawing
 * Rendering decks to PNGs and PDFs
 * Data-driven layouts
@@ -38,7 +38,7 @@ 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 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 along with installing DevKit. For Mac, I recommend using [rvm](https://rvm.io).
 
 Note: Squib requires Ruby 2.0 or later.
 
@@ -169,6 +169,12 @@ Layouts will override Squib's defaults, but are overriden by anything 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 merging, extending, and combining layouts. The sample demonstrates this, but they are also explained below. See the `layouts.rb` sample found [here](https://github.com/andymeneely/squib/tree/master/samples/)
+
+{include:file:samples/layouts.rb}
+
+### Merge Keys and `extends`
+
 Since Layouts are in Yaml, we have the full power of that data format. One particular feature you should look into are ["merge keys"](http://www.yaml.org/YAML_for_ruby.html#merge_key). With merge keys, you can define base styles in one entry, then include those keys elsewhere. For example:
 
 ```yaml
@@ -193,9 +199,46 @@ yang:
   x: += 50
 ```
 
-See the `use_layout` sample found [here](https://github.com/andymeneely/squib/tree/master/samples/)
+### Multiple layout files
+
+Squib also supports the combination of multiple layout files. As shown in the above example, if you provide an `Array` of files then Squib will merge them sequentially. Colliding keys will be completely re-defined by the later file. Extends is processed after _each file_. YAML merge keys are NOT supported across multiple files - use extends instead. Here's a demonstrative example:
+
+```yaml
+# 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
+  x: += 3    # evaluates to 113
+parent_b:    # redefined
+  extends: grandparent
+  x: += 30   # evaluates to 130
+child_b:
+  extends: parent_b
+  x: += 3    # evaluates to 133
+```
+
+This can hopefully be helpful for:
+  * Creating a base layout for structure, and one for color (for easier color/black-and-white switching)
+  * Sharing base layouts with other designers
+
+### Built-in Layout Files
 
-{include:file:samples/use_layout.rb}
+If your layout file is not found in the current directory, Squib will search for its own set of layout files (here's the latest the development version [on GitHub](https://github.com/andymeneely/squib/tree/master/lib/squib/layouts). See the `layouts.rb` sample found [here](https://github.com/andymeneely/squib/tree/master/samples/) for some demonstrative examples.
 
 ## Configuration File
 
@@ -212,6 +255,24 @@ See the `custom_config` sample found [here](https://github.com/andymeneely/squib
 
 {include:file:samples/custom_config.rb}
 
+## Importing from Excel and CSV
+
+Squib supports importing data from `xlsx` files and `csv` files. 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 column. Squib will return a `Hash` of `Arrays` correspoding to each row. Warnings are thrown on things like duplicate columns. See the `excel.rb` and the `csv_import.rb` sample found [here](https://github.com/andymeneely/squib/tree/master/samples/).
+
+{include:file:samples/excel.rb}
+
+Of course, you can always import your game data other ways using just Ruby. There's nothing special about Squib's methods other than their convenience.
+
+## 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:
+
+```ruby
+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.
+
 ## Staying DRY
 
 Squib tries to keep you DRY (Don't Repeat Yourself) with the following features:

data/lib/squib/api/data.rb

@@ -1,4 +1,5 @@
 require 'roo'
+require 'csv'
 
 module Squib
 
@@ -40,12 +41,58 @@ module Squib
   end#xlsx
   module_function :xlsx
 
+  # Pulls CSV data from `.csv` 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/csv.rb` in the [source repository](https://github.com/andymeneely/squib/tree/master/samples)
+  #
+  # @example
+  #   # File data.csv looks like this (without the comment symbols)
+  #   # h1,h2
+  #   # 1,2
+  #   # 3,4
+  #   data = csv file: 'data.csv'
+  #   => {'h1' => [1,3], 'h2' => [2,4]}
+  #
+  # Parsing uses Ruby's CSV, options: {headers: true, converters: :numeric}
+  # http://www.ruby-doc.org/stdlib-2.0/libdoc/csv/rdoc/CSV.html
+  #
+  # @option opts file [String]  the CSV-formatted file to open. Opens relative to the current directory.
+  # @return [Hash] a hash of arrays based on columns in the spreadsheet
+  # @api public
+  def csv(opts = {})
+    opts = Squib::SYSTEM_DEFAULTS.merge(opts)
+    opts = Squib::InputHelpers.fileify(opts)
+    table = CSV.read(opts[:file], headers: true, converters: :numeric)
+    check_duplicate_csv_headers(table)
+    hash = Hash.new
+    table.headers.each do |header|
+      hash[header.to_s] ||= table[header]
+    end
+    return hash
+  end
+  module_function :csv
+
+  # Check if the given CSV table has duplicate columns, and throw a warning
+  # @api private
+  def check_duplicate_csv_headers(table)
+    if table.headers.size != table.headers.uniq.size
+      dups = table.headers.select{|e| table.headers.count(e) > 1 }
+      Squib.logger.warn "CSV duplicated the following column keys: #{dups.join(',')}"
+    end
+  end
+  module_function :check_duplicate_csv_headers
+
   class Deck
 
-    # Convenience call for Squib.xlsx
+    # Convenience call on deck goes to the module function
     def xlsx(opts = {})
       Squib.xlsx(opts)
     end
 
+    def csv(opts = {})
+      Squib.csv(opts)
+    end
+
   end
 end

data/lib/squib/api/text.rb

@@ -36,18 +36,20 @@ module Squib
     # @option opts ellipsize [:none, :start, :middle, :end, true, false] (:end) When width and height are set, determines the behavior of overflowing text. Also: `true` maps to `:end` and `false` maps to `:none`. Default `:end`
     # @option opts angle [FixNum] (0) Rotation of the text in radians. Note that this rotates around the upper-left corner of the text box, making the placement of x-y coordinates slightly tricky.
     # @option opts hint [String] (:nil) draw a rectangle around the text with the given color. Overrides global hints (see {Deck#hint}).
-    # @return [nil] Returns nothing
+    # @return [Array] Returns an Array of hashes keyed by :width and :height that mark the ink extents of the text rendered.
     # @api public
     def text(opts = {})
       opts = needs(opts, [:range, :str, :font, :font_size, :x, :y, :width, :height, :color, :wrap,
                           :align, :justify, :spacing, :valign, :markup, :ellipsize, :hint, :layout, :angle])
+      extents = Array.new(@cards.size)
       opts[:range].each do |i|
-        @cards[i].text(opts[:str][i], opts[:font][i], opts[:font_size][i], opts[:color][i],
+        extents[i] = @cards[i].text(opts[:str][i], opts[:font][i], opts[:font_size][i], opts[:color][i],
                        opts[:x][i], opts[:y][i], opts[:width][i], opts[:height][i],
                        opts[:markup][i], opts[:justify][i], opts[:wrap][i],
                        opts[:ellipsize][i], opts[:spacing][i], opts[:align][i],
                        opts[:valign][i], opts[:hint][i], opts[:angle][i])
       end
+      return extents
     end
 
   end

data/lib/squib/deck.rb

@@ -50,6 +50,7 @@ module Squib
     # @param cards [Integer] the number of cards in the deck
     # @param dpi [Integer] the pixels per inch when rendering out to PDF or calculating using inches.
     # @param config [String] the file used for global settings of this deck
+    # @param layout [String, Array] load a YML file of custom layouts. Multiple files are merged sequentially, redefining collisons. See README and sample for details.
     # @param block [Block] the main body of the script.
     # @api public
     def initialize(width: 825, height: 1125, cards: 1, dpi: 300, config: 'config.yml', layout: nil, &block)
@@ -62,6 +63,7 @@ module Squib
       @progress_bar = Squib::Progress.new(false)
       @text_hint = :off
       cards.times{ @cards << Squib::Card.new(self, width, height) }
+      show_info(config, layout)
       load_config(config)
       load_layout(layout)
       if block_given?
@@ -94,6 +96,7 @@ module Squib
     # @api private
     def load_config(file)
       if File.exists?(file) && config = YAML.load_file(file)
+        Squib::logger.info { "  using config: #{file}" }
         config = Squib::CONFIG_DEFAULTS.merge(config)
         @dpi = config['dpi'].to_i
         @text_hint = config['text_hint']
@@ -105,12 +108,21 @@ module Squib
 
     # Load the layout configuration file, if exists
     # @api private
-    def load_layout(file)
-      return if file.nil?
+    def load_layout(files)
       @layout = {}
-      yml = YAML.load_file(file)
-      yml.each do |key, value|
-        @layout[key] = recurse_extends(yml, key, {})
+      Squib::logger.info { "  using layout(s): #{files}" }
+      Array(files).each do |file|
+        thefile = file
+        thefile = "#{File.dirname(__FILE__)}/layouts/#{file}" unless File.exists?(file)
+        if File.exists? thefile
+          yml = @layout.merge(YAML.load_file(thefile))
+          yml.each do |key, value|
+            @layout[key] = recurse_extends(yml, key, {})
+          end
+        else
+          puts "the file: #{thefile}"
+          Squib::logger.error { "Layout file not found: #{file}" }
+        end
       end
     end
 
@@ -157,6 +169,11 @@ module Squib
       end
     end
 
+    def show_info(config, layout)
+      Squib::logger.info "Squib v#{Squib::VERSION}"
+      Squib::logger.info "  building #{@cards.size} #{@width}x#{@height} cards"
+    end
+
     ##################
     ### PUBLIC API ###
     ##################

data/lib/squib/graphics/text.rb

@@ -89,6 +89,7 @@ module Squib
              markup, justify, wrap, ellipsize,
              spacing, align, valign, hint, angle)
       Squib.logger.debug {"Placing '#{str}'' with font '#{font}' @ #{x}, #{y}, color: #{color}, angle: #{angle} etc."}
+      extents = nil
       use_cairo do |cc|
         cc.set_source_color(color)
         cc.translate(x,y)
@@ -112,7 +113,10 @@ module Squib
         valign!(cc, layout, x, y, valign)
         cc.update_pango_layout(layout) ; cc.show_pango_layout(layout)
         draw_text_hint(cc,x,y,layout,hint,angle)
+        extents = { width: layout.extents[1].width / Pango::SCALE,
+                    height: layout.extents[1].height / Pango::SCALE }
       end
+      return extents
     end
 
   end

data/lib/squib/layouts/hand.yml

@@ -0,0 +1,46 @@
+# A layout designed for a card to be held in your hand.
+#   * Bonuses align along the left-hand side.
+#   * Title along the top.
+#   * Middle area for artwork,
+#   * Room for a text description
+#   * And some theme-based text (which I like call the "snark")
+# Along the lines of Race for the Galaxy or 7 Wonders
+# Based on TheGameCrafter.com's Poker Card, which is 825x1125
+# Sample usage is found in samples/layouts.rb
+title:
+  x: 275
+  y: 75
+  width: 475
+  height: 125
+art:
+  x: 275
+  y: 225
+  width: 475
+  height: 475
+description:
+  x: 275
+  y: 725
+  width: 475
+  height: 200
+snark:
+  x: 275
+  y: 950
+  width: 475
+  height: 100
+bonus1:
+  x: 75
+  y: 75
+  width:  175
+  height: 175
+bonus2:
+  extends: bonus1
+  y: += 198
+bonus3:
+  extends: bonus2
+  y: += 198
+bonus4:
+  extends: bonus3
+  y: += 198
+bonus5:
+  extends: bonus4
+  y: += 198

data/lib/squib/layouts/playing-card.yml

@@ -0,0 +1,18 @@
+# A basic playing card layout with bonuses in the upper-left and lower-right. The lower-right angle is rotated for text.
+bonus_ul:
+  x: 75
+  y: 75
+  width: 200
+  height: 200
+bonus_lr:
+  extends: bonus_ul
+  x: 750
+  y: 1050
+  angle: 3.14159
+art:
+  x: 150
+  y: 275
+  width: 525
+  height: 575
+  valign: middle
+  align: center

data/lib/squib/version.rb

@@ -6,5 +6,5 @@ module Squib
   # Most of the time this is in the alpha of the next release.
   # e.g. v0.0.5a is on its way to becoming v0.0.5
   #
-  VERSION = '0.0.5'
+  VERSION = '0.0.6'
 end

data/samples/cairo_access.rb

@@ -1,7 +1,7 @@
 require 'squib'
 
 Squib::Deck.new(cards: 2) do
-
+  background color: :white
   # If you really need something custom-made, the underlying cairo context
   # can be accessed directly via each Squib::Card
   #
@@ -11,8 +11,9 @@ Squib::Deck.new(cards: 2) do
   # I also recommend wrapping it in a Cairo save/restore, which Squib calls "use_cairo"
   each do |card|
     card.use_cairo do |cairo_context|
-      cairo_context.set_source_color(:white)
-      cairo_context.paint
+      cairo_context.set_source_color(:blue)
+      cairo_context.circle(150, 150, 150)
+      cairo_context.fill
     end
   end
 

data/samples/csv_import.rb

@@ -0,0 +1,20 @@
+require 'squib'
+
+Squib::Deck.new(cards: 2) do
+  background color: :white
+
+  # Outputs a hash of arrays with the header names as keys
+  data = csv file: 'sample.csv'
+
+  text str: data['Name'], x: 250, y: 55, font: 'Arial 54'
+  text str: data['Level'], x: 65, y: 65, font: 'Arial 72'
+  text str: data['Description'], x: 65, y: 600, font: 'Arial 36'
+
+  # You can also specify the sheet, starting at 0
+  data = xlsx file: 'sample.xlsx', sheet: 2
+
+  save format: :png, prefix: 'sample_csv_'
+end
+
+# CSV is also a Squib-module-level function, so this also works:
+data = Squib.csv file: 'sample.csv'

data/samples/custom-layout.yml

@@ -1,3 +1,4 @@
+# Used in the layouts.rb sample in conjunction with custom-layout2.yml
 frame:
   x: 38
   y: 38
@@ -9,15 +10,15 @@ title:
   y: 50
   width: 625
   height: 100
-  align: !ruby/symbol center #see http://www.yaml.org/YAML_for_ruby.html#symbols
-  valign: !ruby/symbol middle
+  align: center #strings also work for most options
+  valign: !ruby/symbol middle #yaml also support symbols, see http://www.yaml.org/YAML_for_ruby.html#symbols
 subtitle:
   x: 150
   y: 150
   width: 575
   height: 60
-  align: !ruby/symbol center
-  valign: !ruby/symbol middle
+  align: center 
+  valign: middle
 icon:
   width: 125
   height: 125