squib 0.8.0 → 0.9.0

data/samples/layouts_builtin.rb

@@ -1,51 +1,51 @@
-require 'squib'
-
-# This sample demonstrates the built-in layouts for Squib.
-# Each card demonstrates a different built-in layout.
-Squib::Deck.new(layout: 'fantasy.yml') do
-  background color: 'white'
-
-  set font: 'Times New Roman,Serif 32'
-  hint text: '#333' # show extents of text boxes to demo the layout
-
-  text str: 'fantasy.yml', layout: :title
-  text str: 'ur',          layout: :upper_right
-  text str: 'art',         layout: :art
-  text str: 'type',        layout: :type
-  text str: 'tr',          layout: :type_right
-  text str: 'description', layout: :description
-  text str: 'lr',          layout: :lower_right
-  text str: 'll',          layout: :lower_left
-  text str: 'credits',     layout: :copy
-
-  rect layout: :safe
-  rect layout: :cut
-  save_png prefix: 'layouts_builtin_fantasy_'
-end
-
-Squib::Deck.new(layout: 'economy.yml') do
-  background color: 'white'
-
-  set font: 'Times New Roman,Serif 32'
-  hint text: '#333' # show extents of text boxes to demo the layout
-
-  text str: 'economy.yml', layout: :title
-  text str: 'art',         layout: :art
-  text str: 'description', layout: :description
-  text str: 'type',        layout: :type
-  text str: 'lr',          layout: :lower_right
-  text str: 'll',          layout: :lower_left
-  text str: 'credits',     layout: :copy
-
-  rect layout: :safe
-  rect layout: :cut
-  save_png prefix: 'layouts_builtin_economy_'
-end
-
-# Stitch together a deck of all the above examples
-Squib::Deck.new(cards: 2) do
-  Dir.glob('_output/layouts_builtin_*.png').each.with_index do |file, i|
-    png file: file, range: i
-  end
-  save_sheet prefix: 'layouts_builtinsheet_'
-end
+require 'squib'
+
+# This sample demonstrates the built-in layouts for Squib.
+# Each card demonstrates a different built-in layout.
+Squib::Deck.new(layout: 'fantasy.yml') do
+  background color: 'white'
+
+  set font: 'Times New Roman,Serif 32'
+  hint text: '#333' # show extents of text boxes to demo the layout
+
+  text str: 'fantasy.yml', layout: :title
+  text str: 'ur',          layout: :upper_right
+  text str: 'art',         layout: :art
+  text str: 'type',        layout: :type
+  text str: 'tr',          layout: :type_right
+  text str: 'description', layout: :description
+  text str: 'lr',          layout: :lower_right
+  text str: 'll',          layout: :lower_left
+  text str: 'credits',     layout: :copy
+
+  rect layout: :safe
+  rect layout: :cut
+  save_png prefix: 'layouts_builtin_fantasy_'
+end
+
+Squib::Deck.new(layout: 'economy.yml') do
+  background color: 'white'
+
+  set font: 'Times New Roman,Serif 32'
+  hint text: '#333' # show extents of text boxes to demo the layout
+
+  text str: 'economy.yml', layout: :title
+  text str: 'art',         layout: :art
+  text str: 'description', layout: :description
+  text str: 'type',        layout: :type
+  text str: 'lr',          layout: :lower_right
+  text str: 'll',          layout: :lower_left
+  text str: 'credits',     layout: :copy
+
+  rect layout: :safe
+  rect layout: :cut
+  save_png prefix: 'layouts_builtin_economy_'
+end
+
+# Stitch together a deck of all the above examples
+Squib::Deck.new(cards: 2) do
+  Dir.glob('_output/layouts_builtin_*.png').each.with_index do |file, i|
+    png file: file, range: i
+  end
+  save_sheet prefix: 'layouts_builtinsheet_'
+end

data/samples/load_images.rb

@@ -1,78 +1,99 @@
-require 'squib'
-
-Squib::Deck.new(width: 825, height: 1125, cards: 1) do
-  background color: '#0b7c8e'
-  rect x: 38, y: 38, width: 750, height: 1050, x_radius: 38, y_radius: 38
-
-  png file: 'shiny-purse.png', x: 620, y: 75 # no scaling is done by default
-  svg file: 'spanner.svg', x: 620, y: 218
-
-  # Can be scaled if width and height are set
-  svg file: 'spanner.svg', x: 50, y: 50, width: 250, height: 250
-  png file: 'shiny-purse.png', x: 305, y: 50, width: 250, height: 250
-  #...but PNGs will warn if it's an upscale
-
-  # Can be scaled using just width or height, if one of them is set to :scale
-  svg file: 'spanner.svg', x: 200, y: 350, width: 35,     height: :scale
-  svg file: 'spanner.svg', x: 200, y: 390, width: :scale, height: 35
-  png file: 'shiny-purse.png', x: 240, y: 350, width: 35,     height: :scale
-  png file: 'shiny-purse.png', x: 240, y: 390, width: :scale, height: 35
-
-  # We can also limit our rendering to a single object, if the SVG ID is set
-  svg file: 'spanner.svg', id: '#backdrop', x: 50, y: 350, width: 75, height: 75
-  # Squib prepends a #-sign if one is not specified
-  svg file: 'spanner.svg', id: 'backdrop', x: 50, y: 450, width: 125, height: 125
-
-  # We can also load SVGs as a string of XML
-  svg data: File.read('spanner.svg'), x: 50, y: 600, width: 75, height: 75
-
-  # The svg data field works nicely with modifying the SVG XML on-the-fly.
-  # To run this one, do `gem install game_icons` and uncomment the following
-  #
-  # require 'game_icons'
-  # svg data: GameIcons.get('angler-fish').recolor(fg: '#ccc', bg: '#333').string,
-  #     x: 150, y: 600, width: 75, height: 75
-  #
-  # More examples at https://github.com/andymeneely/game_icons
-  # (or `gem install game_icons`) to get & manipulate art from game-icons.net
-  # Nokogiri (already included in Squib) is also great for XML manipulation.
-
-  # WARNING! If you choose to use the SVG ID, the x-y coordinates are still
-  # relative to the SVG page. See this example in an SVG editor
-  svg file: 'offset.svg', id: 'thing',  x: 0, y: 0, width: 600, height: 600
-
-  # Over 15 different blending operators are supported.
-  # See http://cairographics.org/operators
-  # Alpha transparency too
-  png file: 'ball.png', x: 50, y: 700
-  png file: 'grit.png', x: 70, y: 750, blend: :color_burn, alpha: 0.75
-
-  # Images can be rotated around their upper-left corner
-  png file: 'shiny-purse.png', x: 300, y: 700, angle: 0.0 # default (no rotate)
-  png file: 'shiny-purse.png', x: 300, y: 800, angle: Math::PI / 4
-  svg file: 'spanner.svg',     x: 300, y: 900, angle: Math::PI / 2 - 0.1
-
-  # Images can also be used as masks instead of being directly painted.
-  # This is particularly useful for switching directly over to black-and-white for printing
-  # Or, if you want the same image to be used but with different colors/gradients
-  svg mask: '#00ff00',
-      file: 'glass-heart.svg',
-      x: 500, y: 600, width: 200, height: 200
-  svg mask: '(0,0)(0,500) #ccc@0.0 #333@1.0',
-      file: 'glass-heart.svg',
-      x: 500, y: 800, width: 200, height: 200
-
-  # Masks are based on the alpha channel, so this is just a magenta square
-  png mask: :magenta, file: 'shiny-purse.png',
-      x: 650, y: 950
-
-  # Note that this method does nothing, even though it would normally fill up
-  # the card. force_id: true looks to the id field to be non-empty to render.
-  # This is useful if you have multiple different icons in one SVG file,
-  # but sometimes want to use none.
-  # e.g. id: [:attack, :defend, nil]
-  svg file: 'spanner.svg', width: :deck, height: :deck,
-      force_id: true, id: '' # <-- the important part
-
-  save prefix: 'load_images_', format: :png
-end
+require 'squib'
+
+Squib::Deck.new(width: 825, height: 1125, cards: 1, config: 'load_images_config.yml') do
+  background color: '#0b7c8e'
+  rect x: 38, y: 38, width: 750, height: 1050, x_radius: 38, y_radius: 38
+
+  png file: 'shiny-purse.png', x: 620, y: 75 # no scaling is done by default
+  svg file: 'spanner.svg', x: 620, y: 218
+
+  # Can be scaled if width and height are set
+  svg file: 'spanner.svg', x: 50, y: 50, width: 250, height: 250
+  png file: 'shiny-purse.png', x: 305, y: 50, width: 250, height: 250
+  #...but PNGs will warn if it's an upscale, unless you disable them in config.yml
+
+  # Can be scaled using just width or height, if one of them is set to :scale
+  svg file: 'spanner.svg', x: 200, y: 350, width: 35,     height: :scale
+  svg file: 'spanner.svg', x: 200, y: 390, width: :scale, height: 35
+  png file: 'shiny-purse.png', x: 240, y: 350, width: 35,     height: :scale
+  png file: 'shiny-purse.png', x: 240, y: 390, width: :scale, height: 35
+
+  # You can also crop the loaded images, so you can work from a sprite sheet
+  png file: 'sprites.png', x: 300, y: 350  # entire sprite sheet
+  png file: 'sprites.png', x: 300, y: 425, # just the robot golem image
+      crop_x: 0, crop_y: 0, crop_corner_radius: 10,
+      crop_width: 64, crop_height: 64
+  png file: 'sprites.png', x: 400, y: 425, # just the drakkar ship image
+      crop_x: 64, crop_y: 0, crop_corner_x_radius: 25, crop_corner_y_radius: 25,
+      crop_width: 64, crop_height: 64
+  png file: 'sprites.png', x: 500, y: 415, # just the drakkar ship image, rotated
+      crop_x: 64, crop_y: 0, crop_corner_x_radius: 25, crop_corner_y_radius: 25,
+      crop_width: 64, crop_height: 64, angle: Math::PI / 6
+
+  # Cropping also works on SVGs too
+  svg file: 'spanner.svg', x: 300, y: 500, width: 64, height: 64,
+      crop_x: 32, crop_y: 32, crop_width: 32, crop_height:32
+
+  # We can flip our images too
+  png file: 'sprites.png', x: 300, y: 535, flip_vertical: true, flip_horizontal: true
+  svg file: 'spanner.svg', x: 300, y: 615, width: 64, height: 64,
+      flip_vertical: true, flip_horizontal: true
+
+  # We can also limit our rendering to a single object, if the SVG ID is set
+  svg file: 'spanner.svg', id: '#backdrop', x: 50, y: 350, width: 75, height: 75
+  # Squib prepends a #-sign if one is not specified
+  svg file: 'spanner.svg', id: 'backdrop', x: 50, y: 450, width: 125, height: 125
+
+  # We can also load SVGs as a string of XML
+  svg data: File.read('spanner.svg'), x: 50, y: 600, width: 75, height: 75
+
+  # The svg data field works nicely with modifying the SVG XML on-the-fly.
+  # To run this one, do `gem install game_icons` and uncomment the following
+  #
+  # require 'game_icons'
+  # svg data: GameIcons.get('angler-fish').recolor(fg: '#ccc', bg: '#333').string,
+  #     x: 150, y: 600, width: 75, height: 75
+  #
+  # More examples at https://github.com/andymeneely/game_icons
+  # (or `gem install game_icons`) to get & manipulate art from game-icons.net
+  # Nokogiri (already included in Squib) is also great for XML manipulation.
+
+  # WARNING! If you choose to use the SVG ID, the x-y coordinates are still
+  # relative to the SVG page. See this example in an SVG editor
+  svg file: 'offset.svg', id: 'thing',  x: 0, y: 0, width: 600, height: 600
+
+  # Over 15 different blending operators are supported.
+  # See http://cairographics.org/operators
+  # Alpha transparency too
+  png file: 'ball.png', x: 50, y: 700
+  png file: 'grit.png', x: 70, y: 750, blend: :color_burn, alpha: 0.75
+
+  # Images can be rotated around their upper-left corner
+  png file: 'shiny-purse.png', x: 300, y: 700, angle: 0.0 # default (no rotate)
+  png file: 'shiny-purse.png', x: 300, y: 800, angle: Math::PI / 4
+  svg file: 'spanner.svg',     x: 300, y: 900, angle: Math::PI / 2 - 0.1
+
+  # Images can also be used as masks instead of being directly painted.
+  # This is particularly useful for switching directly over to black-and-white for printing
+  # Or, if you want the same image to be used but with different colors/gradients
+  svg mask: '#00ff00',
+      file: 'glass-heart.svg',
+      x: 500, y: 600, width: 200, height: 200
+  svg mask: '(0,0)(0,500) #ccc@0.0 #333@1.0',
+      file: 'glass-heart.svg',
+      x: 500, y: 800, width: 200, height: 200
+
+  # Masks are based on the alpha channel, so this is just a magenta square
+  png mask: :magenta, file: 'shiny-purse.png',
+      x: 650, y: 950
+
+  # Note that this method does nothing, even though it would normally fill up
+  # the card. force_id: true looks to the id field to be non-empty to render.
+  # This is useful if you have multiple different icons in one SVG file,
+  # but sometimes want to use none.
+  # e.g. id: [:attack, :defend, nil]
+  svg file: 'spanner.svg', width: :deck, height: :deck,
+      force_id: true, id: '' # <-- the important part
+
+  save prefix: 'load_images_', format: :png
+end

data/samples/load_images_config.yml

@@ -0,0 +1 @@
+warn_png_scale: false

data/samples/quantity_explosion.csv

@@ -1,3 +1,3 @@
-Name,Qty
-Basilisk,3
+Name,Qty
+Basilisk,3
 High Templar,1

data/samples/ranges.rb

@@ -1,64 +1,64 @@
-require 'squib'
-
-data = {'name' => ['Thief', 'Grifter', 'Mastermind'],
-        'type' => ['Thug', 'Thinker', 'Thinker'],
-        'level' => [1,2,3]}
-
-Squib::Deck.new(width: 825, height: 1125, cards: 3) do
-  # Default range is :all
-  background color: :white
-  text str: data['name'], x: 250, y: 55, font: 'Arial 54'
-  text str: data['level'], x: 65, y: 40, font: 'Arial 72'
-
-  # Could be explicit about using :all, too
-  text range: :all,
-       str: data['type'], x: 40, y: 128, font: 'Arial 18',
-       width: 100, align: :center
-
-  # Ranges are inclusive, zero-based
-  text range: 0..1, str: 'Thief and Grifter only!!', x: 25, y:200
-
-  # Integers are also allowed
-  text range: 0, str: 'Thief only!', x: 25, y: 250
-
-  # Negatives go from the back of the deck
-  text range: -1, str: 'Mastermind only!', x: 25, y: 250
-  text range: -2..-1, str: 'Grifter and Mastermind only!', x: 25, y: 650
-
-  # We can use Arrays too!
-  text range: [0,2], str: 'Thief and Mastermind only!!', x: 25, y:300
-
-  # Just about everything in Squib can be given an array that
-  # corresponds to the deck's cards. This allows for each card to be styled differently
-  # This renders three cards, with three strings that had three different colors at three different locations.
-  text str: %w(red green blue),
-       color: [:red, :green, :blue],
-       x: [40, 80, 120],
-       y: [700, 750, 800]
-
-  # Useful idiom: construct a hash from card names back to its index (ID),
-  # then use a range. No need to memorize IDs, and you can add cards easily
-  id = {} ; data['name'].each_with_index{ |name,i| id[name] = i}
-  text range: id['Thief']..id['Grifter'],
-       str: 'Thief through Grifter with id lookup!!',
-       x:25, y: 400
-
-  # Useful idiom: generate arrays from a column called 'type'
-  type = {}; data['type'].each_with_index{ |t,i| (type[t] ||= []) << i}
-  text range: type['Thinker'],
-       str: 'Only for Thinkers!',
-       x:25, y: 500
-
-  # Useful idiom: draw a different number of images for different cards
-  hearts = [nil, 1, 2] #i.e. card 0 has no hearts, card 2 has 2 hearts drawn
-  1.upto(2).each do |n|
-    range = hearts.each_index.select { |i| hearts[i] == n}
-    n.times do |i|
-      svg file: 'glass-heart.svg', range: range,
-          x: 150, y: 55 + i*42, width: 40, height: 40
-    end
-  end
-
-  rect color: 'black' # just a border
-  save_sheet prefix: 'ranges_', columns: 3
-end
+require 'squib'
+
+data = {'name' => ['Thief', 'Grifter', 'Mastermind'],
+        'type' => ['Thug', 'Thinker', 'Thinker'],
+        'level' => [1,2,3]}
+
+Squib::Deck.new(width: 825, height: 1125, cards: 3) do
+  # Default range is :all
+  background color: :white
+  text str: data['name'], x: 250, y: 55, font: 'Arial 54'
+  text str: data['level'], x: 65, y: 40, font: 'Arial 72'
+
+  # Could be explicit about using :all, too
+  text range: :all,
+       str: data['type'], x: 40, y: 128, font: 'Arial 18',
+       width: 100, align: :center
+
+  # Ranges are inclusive, zero-based
+  text range: 0..1, str: 'Thief and Grifter only!!', x: 25, y:200
+
+  # Integers are also allowed
+  text range: 0, str: 'Thief only!', x: 25, y: 250
+
+  # Negatives go from the back of the deck
+  text range: -1, str: 'Mastermind only!', x: 25, y: 250
+  text range: -2..-1, str: 'Grifter and Mastermind only!', x: 25, y: 650
+
+  # We can use Arrays too!
+  text range: [0,2], str: 'Thief and Mastermind only!!', x: 25, y:300
+
+  # Just about everything in Squib can be given an array that
+  # corresponds to the deck's cards. This allows for each card to be styled differently
+  # This renders three cards, with three strings that had three different colors at three different locations.
+  text str: %w(red green blue),
+       color: [:red, :green, :blue],
+       x: [40, 80, 120],
+       y: [700, 750, 800]
+
+  # Useful idiom: construct a hash from card names back to its index (ID),
+  # then use a range. No need to memorize IDs, and you can add cards easily
+  id = {} ; data['name'].each_with_index{ |name,i| id[name] = i}
+  text range: id['Thief']..id['Grifter'],
+       str: 'Thief through Grifter with id lookup!!',
+       x:25, y: 400
+
+  # Useful idiom: generate arrays from a column called 'type'
+  type = {}; data['type'].each_with_index{ |t,i| (type[t] ||= []) << i}
+  text range: type['Thinker'],
+       str: 'Only for Thinkers!',
+       x:25, y: 500
+
+  # Useful idiom: draw a different number of images for different cards
+  hearts = [nil, 1, 2] #i.e. card 0 has no hearts, card 2 has 2 hearts drawn
+  1.upto(2).each do |n|
+    range = hearts.each_index.select { |i| hearts[i] == n}
+    n.times do |i|
+      svg file: 'glass-heart.svg', range: range,
+          x: 150, y: 55 + i*42, width: 40, height: 40
+    end
+  end
+
+  rect color: 'black' # just a border
+  save_sheet prefix: 'ranges_', columns: 3
+end

data/samples/sample.csv

@@ -1,3 +1,3 @@
-Type,"Level"
-Thief,1
+Type,"Level"
+Thief,1
 Mastermind,2

data/samples/saves.rb

@@ -4,10 +4,18 @@ require 'squib'
 
 Squib::Deck.new(width: 825, height: 1125, cards: 16) do
   background color: :gray
-  rect x: 38, y: 38, width: 750, height: 1050, x_radius: 38, y_radius: 38
+  rect x: 38, y: 38, width: 750, height: 1050,
+       x_radius: 38, y_radius: 38, stroke: 3.0, dash: '4 4'
 
   text str: (1..16).to_a, x: 220, y: 78, font: 'Arial 54'
 
+  # Here's what a regular save_png looks like for just the first card
+  save_png range: 0, prefix: 'save_png_'
+
+  # save_png supports trim and trim_radius
+  save_png trim: 30, trim_radius: 38,
+           range: 0, prefix: 'save_png_trimmed_'
+
   # Place on multiple pages over the PDF, with bleed beeing trimmed off
   save_pdf file: 'save-pdf.pdf', margin: 75, gap: 5, trim: 37
 

data/samples/text/_text.rb

@@ -0,0 +1,46 @@
+require 'squib'
+require 'squib/sample_helpers'
+
+Squib::Deck.new(width: 1000, height: 2000) do
+  draw_graph_paper width, height
+
+  sample 'Font strings are quite expressive. Specify family, modifiers, then size. Font names with spaces in them should also have a backup afterward to help with parsing.' do |x, y|
+    text font: 'Arial bold italic 32', str: 'Bold and italic!', x: x, y: y - 50
+    text font: 'Arial weight=300 32', str: 'Light bold!', x: x, y: y
+    text font: 'Times New Roman,Arial 32', str: 'Times New Roman', x: x, y: y + 50
+  end
+
+  sample 'Specify width and height to see a text box. Also: set "hint" to see the extents of your text box' do |x, y|
+    text str: 'This has fixed width and height.', x: x, y: y,
+         hint: :red, width: 300, height: 100, font: 'Serif bold 24'
+  end
+
+  sample 'If you specify the width only, the text will ellipsize.' do |x, y|
+    text str: 'The meaning of life is 42', x: x - 50, y: y,
+         hint: :red, width: 350, font: 'Serif bold 22'
+  end
+
+  sample 'If you specify the width only, and turn off ellipsize, the height will auto-stretch.' do |x, y|
+    text str: 'This has fixed width, but not fixed height.', x: x, y: y,
+         hint: :red, width: 300, ellipsize: false, font: 'Serif bold 24'
+  end
+
+  sample 'The text method returns the ink extents of each card\'s rendered text. So you can custom-fit a shape around it.' do |x, y|
+    ['Auto fit!', 'Auto fit!!!!' ].each.with_index do |str, i|
+      text_y = y + i * 50
+      extents = text str: str, x: x, y: text_y, font: 'Sans Bold 24'
+
+      # Extents come back as an array of hashes, which can get split out like this
+      text_width  = extents[0][:width]
+      text_height = extents[0][:height]
+      rect x: x, y: text_y, width: text_width, height: text_height, radius: 10,
+           stroke_color: :purple, stroke_width: 3
+    end
+  end
+
+  sample 'Text can be rotated about the upper-left corner of the text box. Unit is in radians.' do |x, y|
+    text str: 'Rotated', hint: :red, x: x, y: y, angle: Math::PI / 6
+  end
+
+  save_png prefix: '_text_', dir: '.'
+end