# Convenience method for pulling Excel data from `.xlsx` files
# 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 at {file:samples/excel.rb samples/excel.rb}. The accompanying Excel file is in the [source repository](https://github.com/andymeneely/squib/tree/master/samples)
# See the example `samples/excel.rb` in the [source repository](https://github.com/andymeneely/squib/tree/master/samples)
#
# @param file: [String] the file to open. Must end in `.xlsx`. Opens relative to the current directory.
# @param sheet: [Integer] The zero-based index of the sheet from which to read.
# @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
# 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
#
# @param range: the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
# @param file: file(s) to read in. If it's a single file, then it's use for every card. 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}
# @param x: the x-coordinate to place
# @param y: the y-coordinate to place
# @param alpha: the alpha-transparency percentage used to blend this image
# @return [nil] intended to be void
# @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 alpha [Decimal] (1.0) the alpha-transparency percentage used to blend this image
# @return [nil] Returns nil
# @api public
defpng(opts={})
opts=needs(opts,[:range,:files,:x,:y,:alpha])
@ -20,19 +23,18 @@ module Squib
end
# Renders an entire svg file at the given location. Uses the SVG-specified units and DPI to determine the pixel width and height.
# @example
# svg 1..2, 'icon.svg', '#stone', x: 50, y:50
#
# 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
#
# @param range: the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
# @param file: the svg file to render. See {file:API.md#Specifying+Files Specifying Files}
# @param id: if specified, only render the SVG element with the supplied id. Otherwise, render the entire SVG file
# @param x: the x-coordinate to place
# @param y: the y-coordinate to place
# @param width: 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.
# @param height: 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.
# @return [nil] essentially a void method
# @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 [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.
# Renders a string at a given location, width, alignment, font, etc.
#
# Unix-like newlines are interpreted even on Windows.
# See the {file:samples/text-options.rb samples/text.rb} for a lengthy example.
#
# @example See the {file:samples/text-options.rb samples/text.rb} for a lengthy example.
# @example
# text str: 'hello'
# text str: 'hello', x: 50, y:50, align: center
#
# @param range: the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
# @param str: the string to be rendered. Must support `#to_s`. If the card responds to `#each`, it's mapped out one at a time across the cards.
# @param font: the Font description string, including family, styles, and size.
# @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 str [String, Array] ('') the string to be rendered. Must support `#to_s`. If the card responds to `#each`, it's mapped out one at a time across the cards.
# @option opts font [String] (Arial 36 or whatever was set with `set`) the Font description string, including family, styles, and size.
# (e.g. `'Arial bold italic 12'`)
# For the official documentation, see the [Pango docs](http://ruby-gnome2.sourceforge.jp/hiki.cgi?Pango%3A%3AFontDescription#style).
# This [description](http://www.pygtk.org/pygtk2reference/class-pangofontdescription.html) is also quite good.
# See the {file:samples/text-options.rb samples/text.rb} as well.
# @param x: the x-coordinate to place
# @param y: the y-coordinate to place
# @param options: captures the additional input options below
# @option color: (default: :black) the color the font will render to. See {file:API.md#label-Specifying+Colors Specifying Colors}
# @option markup: [Boolean] (default: false) Enable markup parsing of `str` using the HTML-like Pango Markup syntax, defined [here](http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup) and [here](https://developer.gnome.org/pango/stable/PangoMarkupFormat.html).
# @option width: the width of the box the string will be placed in. Stretches to the content by default.
# @option height: the height of the box the string will be placed in. Stretches to the content by default.
# @option wrap: When height is set, determines the behavior of how the string wraps. The `:word_char` option will break at words, but then fall back to characters when the word cannot fit. #
# @option opts x [Integer] (0) the x-coordinate to place
# @option opts y [Integer] (0) the y-coordinate to place
# @option opts color [String] (:black) the color the font will render to. See {file:API.md#label-Specifying+Colors Specifying Colors}
# @option opts markup: [Boolean] (false) Enable markup parsing of `str` using the HTML-like Pango Markup syntax, defined [here](http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup) and [here](https://developer.gnome.org/pango/stable/PangoMarkupFormat.html).
# @option opts width [Integer, :native] (:native) the width of the box the string will be placed in. Stretches to the content by default.
# @option opts height [Integer, :native] the height of the box the string will be placed in. Stretches to the content by default.
# @option opts wrap [:none, :word, :char, :word_char, true, false] (:word_char) When height is set, determines the behavior of how the string wraps. The `:word_char` option will break at words, but then fall back to characters when the word cannot fit. #
# Options are `:none, :word, :char, :word_char`. Also: `true` is the same as `:word_char`, `false` is the same as `:none`. Default `:word_char`
# @option align: options `:left, :right, and :center`. Default `:left`
# @option justify: [Boolean] toggles whether or not the text is justified or not. Default `false`
# @option valign: When width and height are set, align text vertically according to the logical extents of the text. Options are `:top, :middle, :bottom`. Default `:top`
# @option ellipsize: When width and height are set, determines the behavior of overflowing text. Options are `:none, :start, :middle, :end`. Also: `true` maps to `:end` and `false` maps to `:none`. Default `:end`
# @option hint: show a text hint with the given color. Overrides global hints (see {Deck#hint}).
# @option opts align [:left, right, :center] (:left) The alignment of the text
# @option opts justify [Boolean] (false) toggles whether or not the text is justified or not.
# @option opts valign [:top, :middle, :bottom] (:top) When width and height are set, align text vertically according to the logical extents of the text.
# @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 hint [String] (:nil) draw a rectangle around the text with the given color. Overrides global hints (see {Deck#hint}).
# Squib's constructor that sets the immutable properties.
#
# This is the starting point for Squib. In providing a block to the constructor, you have access to all of Deck's instance methods.
# The documented methods in Deck are the ones intended for use by most users.
# If your game requires multiple different sizes or orientations, I recommend using multiple `Squib::Deck`s in your `deck.rb`. You can modify the internals of `Squib::Deck` (e.g. `@cards`), but that's not recommended.
# @example
# require 'squib'
# Squib::Deck.new do
# text str: 'Hello, World!'
# end
#
# @param width [Integer] the width of each card in pixels
# @param height [Integer] the height of each card in pixels
# @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 block [Block] the main body of the script.
Andy Meneely
12 years ago