Configuration Options

Squib supports various configuration properties that can be specified in an external file. By default, Squib looks for a file called config.yml in the current directory. Or, you can set the config: option in Deck.new to specify the name of the configuration file.

These properties are intended to be immutable for the life of the Deck, and intended to configure how Squib behaves.

The options include:

progress_bars

default: false

When set to true, long-running operations will show a progress bar in the console

hint

default: :off

Text hints are used to show the boundaries of text boxes. Can be enabled/disabled for individual commands, or set globally with the hint method. This setting is overridden by hint (and subsequently individual text).

custom_colors

default: {}

Defines globally-available named colors available to the deck. Must be specified as a hash in yaml. For example:

# config.yml
custom_colors:
  fg: '#abc'
  bg: '#def'
antialias

default: 'best'

Set the algorithm that Cairo will use for anti-aliasing throughout its rendering. Available options are fast, good, best, none, gray, subpixel.

Not every option is available on every platform. Using our benchmarks on large decks, best is only ~10% slower anyway. For more info see the Cairo docs.

backend

default: 'memory'

Defines how Cairo will store the operations. Can be svg or memory. See Vector vs. Raster Backends.

prefix

default: 'card_'

When using an SVG backend, cards are auto-saved with this prefix and '%02d' numbering format.

img_dir

default: '.'

For reading image file command (e.g. png and svg), read from this directory instead

img_missing:

default: :warn

Log a warning if an image file is missing. This option is only consulted if the following are true:

  • If the file specified for an input image (e.g. png or svg) does not exist,
  • AND a placeholder image does not exist
Other options:
  • error - raise a RuntimeError and halt the entire build.
  • silent - do nothing, log nothing, and act as if the file was nil
warn_ellipsize

default: true

Show a warning on the console when text is ellipsized. Warning is issued per card.

warn_png_scale

default: true

Show a warning on the console when a PNG file is upscaled. Warning is issued per card.

lsquote

default: "\u2018"

Smart quoting: change the left single quote when markup: true

rsquote

default: "\u2019"

Smart quoting: change the right single quote when markup: true

ldquote

default: "\u201C"

Smart quoting: change the left double quote when markup: true

rdquote

default: "\u201D"

Smart quoting: change the right double quote when markup: true

em_dash

default: "\u2014"

Convert the -- to this character when markup: true

en_dash

default: "\u2013"

Convert the --- to this character when markup: true

ellipsis

default: "\u2026"

Convert ... to this character when markup: true

smart_quotes

default: true

When markup: true, the text method will convert quotes. With smart_quotes: false, explicit replacements like em-dashes and en-dashes will be replaced but not smart quotes.

cell_px

default: 37.5

The number of pixels that the “cell” custom unit is set to. See Unit Conversion

Options are available as methods

For debugging/sanity purposes, if you want to make sure your configuration options are parsed correctly, the above options are also available as methods within Squib::Deck, for example:

Squib::Deck.new do
  puts backend # prints 'memory' by default
end

These are read-only - you will not be able to change these.

Set options programmatically

You can also use Squib.configure to override anything in the config file. Use it like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# This is a sample Rakefile
require 'squib'

desc 'Build all decks black-and-white'
task default: [:characters, :skills]

desc 'Build all decks with color'
task color: [:with_color, :default]

desc 'Enable color build'
task :with_color do
  puts "Enabling color build"
  Squib.configure img_dir: 'color'
end

desc 'Build the character deck'
task :characters do
  puts "Building characters"
  load 'src/characters.rb'
end

desc 'Build the skills deck'
task :skills do
  puts "Building skills"
  load 'src/skills.rb'
end

See The Squib Way pt 3: Workflows for how we put this to good use.

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:

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.