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.
# Specifying Parameters
Squib makes extensive use of [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. In fact, with named parameters you *must* specify which argument ties to which parameter. If you get an error like this:
```cmd
C:/Ruby200/lib/ruby/gems/2.0.0/gems/squib-0.0.2/lib/squib/api/text.rb:17:in `text': wrong number of arguments (1 for 0)
(ArgumentError)
from hello-world.rb:5:in `block in <main>'
from C:/Ruby200/lib/ruby/gems/2.0.0/gems/squib-0.0.2/lib/squib/deck.rb:21:in `instance_eval'
from C:/Ruby200/lib/ruby/gems/2.0.0/gems/squib-0.0.2/lib/squib/deck.rb:21:in `initialize'
from hello-world.rb:4:in `new'
from hello-world.rb:4:in `<main>'
```
...then you're not specifying the parameters explicitly (e.g. the above example was with `text 'X'` instead of `text str: 'X'`)
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
All 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]() 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)
# Specifying Colors
Squib uses the `rcairo` [color parser](https://github.com/rcairo/rcairo/blob/master/lib/cairo/color.rb) to accepts a variety of color specifications, along with over [300 pre-defined constants](https://github.com/rcairo/rcairo/blob/master/lib/cairo/colors.rb). Here are some examples from `samples/colors.rb` found [here](https://github.com/andymeneely/squib/tree/master/samples/colors.rb)
{include:file:samples/colors.rb}
# Specifying Files
All files opened for reading (e.g. for `png` and `xlsx`) are opened relative to the current directory.
Squib is a ruby DSL for prototyping card and board games. Think of it like [nanDeck](http://www.nand.it/nandeck/) done "the Ruby way". Start with some basic commands and generate print-ready PNGs and PDFs. Squib supports complex text rendering, reading PNGs and SVGs, reading from ExcelX files, and shape drawing. Plus, you have the full power of Ruby behind you.
Squib is a Ruby DSL for prototyping card and board games. Think of it like [nanDeck](http://www.nand.it/nandeck/) done "the Ruby way". Start with some basic commands and generate print-ready PNGs and PDFs. Squib supports:
Check it out!
* Complex text rendering using [Pango](http://www.pango.org/)
* Reading PNGs and SVGs using [Cairo](http://cairographics.org/)
* Reading `.xlsx` files
* Basic shape drawing
* Saving to PNGs and PDFs
* Plus the full power of Ruby!
```ruby
require 'squib'
Squib::Deck.new(width: 825, height: 1125, cards: 3) do
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
Squib::Deck.new do
text str: 'Hello, World!'
save_png
end
```
@ -36,18 +32,65 @@ Or install it yourself as:
$ gem install squib
Note: Squib has some native dependencies, such as [Cairo](https://github.com/rcairo/rcairo) and [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 on some setups can cause headaches. For Windows users, I *highly* recommend using [http://rubyinstaller.org/].
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 on some setups can cause headaches. For Windows users, I *strongly* recommend using the *non-*64 bit RubyInstaller at http://rubyinstaller.org/
## Development
## 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
```
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](https://github.com/andymeneely/squib/issues) if you find any.
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
```
## API
The central file here is `deck.rb`. Here's a more complex example of a deck to work from:
API docs to be written. The `samples` directory for in-depth examples.
```ruby
require 'squib'
Squib::Deck.new(width: 825, height: 1125, cards: 3) do
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
```
## Learning Squib's API
* The `samples` directory in the [source repository](https://github.com/andymeneely/squib) has lots of examples
* The [API.md]() walks through the various methods and options
* [API Documentation](http://rubydoc.info/gems/squib/) is also kept up-to-date.
## 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'`)
# Convenience method for pulling Excel data from `.xlsx` files
# 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)
#
# @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.
# font: description string, including family, styles, and size.
# 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.
#
# => e.g. 'Arial bold italic 12'
# For the official documentation the string, 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.
# @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`.
# @param font: 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 color: (default: :black) the color the font will render to. See {file:API.md#label-Specifying+Colors Specifying Colors}
# @param 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).
# @param width: the width of the box the string will be placed in. Stretches to the content by default.
# @param height: the height of the box the string will be placed in. Stretches to the content by default.
# @param 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. #
# Options are `:none, :word, :char, :word_char`. Also: `true` is the same as `:word_char`, `false` is the same as `:none`. Default `:word_char`
# @param fitxy: sets the text `width` and `height` to be equal to `width - x` and `height - y` for easy centering
# @param align: options `:left, :right, and :center`. Default `:left`
# @param justify: [Boolean] toggles whether or not the text is justified or not. Default `false`
# @param 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`
# @param 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`
# @param hint: show a text hint with the given color. Overrides global hints (see {Deck#hint}).
Andy Meneely
12 years ago