Tons more documentation.
Andy Meneely
parent
f3b4ca50a2
commit
e5a889a274
37
API.md
37
API.md
|
|
@ -1,35 +1,20 @@
|
|||
# Squib API
|
||||
|
||||
The Squib DSL is based on a collection of methods provided to the `Squib::Deck` class. The general philosophy of Squib is to specify as little as possible (i.e. great defaults )
|
||||
The Squib DSL is based on a collection of methods provided to the `Squib::Deck` class. The general philosophy of Squib is to specify as little as possible with layers of defaults, highly flexible input, and good ol' Ruby duck-typing. Ruby does a lot to make Squib useful.
|
||||
|
||||
# Squib::Deck and Squib::Card
|
||||
|
||||
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.
|
||||
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. The API documentation doesn't really cover these, however, so you're on your own there.
|
||||
|
||||
# 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.
|
||||
Squib is all about sane defaults and shorthand specification. Arguments are almost always using hashes, which look a lot like [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. 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
|
||||
|
||||
Most 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)
|
||||
Most 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}
|
||||
|
||||
|
|
@ -47,7 +32,7 @@ Colors can be specified in a wide variety of ways, mostly in a hex-string. Take
|
|||
|
||||
{include:file:samples/colors.rb}
|
||||
|
||||
Under the hood, 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).
|
||||
Under the hood, Squib uses the `rcairo` [color parser](https://github.com/rcairo/rcairo/blob/master/lib/cairo/color.rb) to accept a variety of color specifications, along with over [300 pre-defined constants](https://github.com/rcairo/rcairo/blob/master/lib/cairo/colors.rb).
|
||||
|
||||
# Specifying Files
|
||||
|
||||
|
|
@ -55,14 +40,20 @@ All files opened for reading or writing (e.g. for `png` and `xlsx`) are opened r
|
|||
|
||||
# Custom Layouts
|
||||
|
||||
Working with x-y coordinates can be tiresome, and ideally everything in a game prototype should be data-driven. To counter this, many Squib methods allow for a `layout` to be set. In essence, layouts are a way of setting default values for `x, y, width` and `height`.
|
||||
Working with x-y coordinates all the time can be tiresome, and ideally everything in a game prototype should be data-driven and easily changed. For this, many Squib methods allow for a `layout` to be set. In essence, layouts are a way of setting default values for any argument given to the command.
|
||||
|
||||
To use a layout, set the `layout:` option on a `Deck.new` command to point to a YAML file. Any command that allows a `layout` option can be set with a Ruby symbol or String, and the command will then load the specified `x`, `y`, `width`, and `height`. The individual command can also override these options.
|
||||
|
||||
Note: YAML is very finnicky about having tabs in the file. Use two spaces for indentation instead.
|
||||
|
||||
Layouts will override Squib's defaults, but are overriden by anything specified in the command itself. Thus, the order of precedence looks like this:
|
||||
|
||||
* Use what the command 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 for a special `extends` field that will copy all of the settings from another entry. Only a single level of extends are supported currently (contact the developer if you want multiple levels).
|
||||
|
||||
See the `use_layout` sample found [here](https://github.com/andymeneely/squib/tree/master/samples/)
|
||||
|
||||
{include:file:samples/use_layout.rb}
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -12,6 +12,7 @@ module Squib
|
|||
# @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 layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:API.md#label-Custom+Layouts Custom Layouts}
|
||||
# @option opts alpha [Decimal] (1.0) the alpha-transparency percentage used to blend this image
|
||||
# @return [nil] Returns nil
|
||||
# @api public
|
||||
|
|
@ -34,6 +35,7 @@ module Squib
|
|||
# @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 layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:API.md#label-Custom+Layouts Custom Layouts}
|
||||
# @return [nil] Returns nil
|
||||
# @api public
|
||||
def svg(opts = {})
|
||||
|
|
|
|||
|
|
@ -17,6 +17,7 @@ module Squib
|
|||
# @option opts fill_color [String] ('#0000') the color with which to fill the rectangle
|
||||
# @option opts stroke_color [String] (:black) the color with which to stroke the outside of the rectangle
|
||||
# @option opts stroke_width [Decimal] (2.0) the width of the outside stroke
|
||||
# @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:API.md#label-Custom+Layouts Custom Layouts}
|
||||
# @return [nil] intended to be void
|
||||
# @api public
|
||||
def rect(opts = {})
|
||||
|
|
|
|||
|
|
@ -23,6 +23,7 @@ module Squib
|
|||
# @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 layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:API.md#label-Custom+Layouts Custom Layouts}
|
||||
# @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 opts align [:left, right, :center] (:left) The alignment of the text
|
||||
|
|
|
|||
|
|
@ -1,7 +1,24 @@
|
|||
module Squib
|
||||
# Squib's command-line options
|
||||
module Commands
|
||||
|
||||
# Generate a new Squib project into a fresh directory.
|
||||
#
|
||||
# Provides conventions for using Git (you are using version control, right??).
|
||||
# Also provides some basic layout and config files to start from, along with templates for instructions and other notes you don't want to forget.
|
||||
#
|
||||
#
|
||||
# @example
|
||||
# squib new foo-blasters
|
||||
# cd foo-blasters
|
||||
# ruby deck.rb
|
||||
# git commit -am "Starting my cool new game using Squib!"
|
||||
#
|
||||
# @api public
|
||||
class New
|
||||
|
||||
# :nodoc:
|
||||
# @api private
|
||||
def process(args)
|
||||
raise ArgumentError.new('Please specify a path.') if args.empty?
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
module Squib
|
||||
|
||||
# Squib's defaults for when arguments are not specified in the command nor layouts.
|
||||
#
|
||||
# @api public
|
||||
SYSTEM_DEFAULTS = {
|
||||
:range => :all,
|
||||
|
|
|
|||
|
|
@ -5,6 +5,7 @@ module Squib
|
|||
# @api private
|
||||
module InputHelpers
|
||||
|
||||
# :nodoc:
|
||||
# @api private
|
||||
def needs(opts, params)
|
||||
opts = layoutify(opts) if params.include? :layout
|
||||
|
|
@ -25,6 +26,7 @@ module Squib
|
|||
end
|
||||
module_function :needs
|
||||
|
||||
# :nodoc:
|
||||
# @api private
|
||||
def layoutify(opts)
|
||||
unless opts[:layout].nil?
|
||||
|
|
@ -41,6 +43,7 @@ module Squib
|
|||
end
|
||||
module_function :layoutify
|
||||
|
||||
# :nodoc:
|
||||
# @api private
|
||||
def formatify(opts)
|
||||
opts[:format] = [opts[:format]].flatten
|
||||
|
|
@ -48,6 +51,7 @@ module Squib
|
|||
end
|
||||
module_function :formatify
|
||||
|
||||
# :nodoc:
|
||||
# @api private
|
||||
def rangeify (opts)
|
||||
range = opts[:range]
|
||||
|
|
@ -62,6 +66,7 @@ module Squib
|
|||
end
|
||||
module_function :rangeify
|
||||
|
||||
# :nodoc:
|
||||
# @api private
|
||||
def fileify(opts, expand_singletons=false, allow_non_exist=false)
|
||||
opts[:file] = [opts[:file]] * @cards.size if expand_singletons
|
||||
|
|
@ -75,6 +80,7 @@ module Squib
|
|||
end
|
||||
module_function :fileify
|
||||
|
||||
# :nodoc:
|
||||
# @api private
|
||||
def dirify(opts, allow_create=false)
|
||||
return opts if Dir.exists?(opts[:dir])
|
||||
|
|
@ -88,6 +94,7 @@ module Squib
|
|||
end
|
||||
module_function :dirify
|
||||
|
||||
# :nodoc:
|
||||
# @api private
|
||||
def colorify(opts, nillable=false)
|
||||
if nillable # for optional color arguments like text hints
|
||||
|
|
@ -99,6 +106,7 @@ module Squib
|
|||
end
|
||||
module_function :colorify
|
||||
|
||||
# :nodoc:
|
||||
# @api private
|
||||
def fontify (opts)
|
||||
opts[:font] = @font if opts[:font]==:use_set
|
||||
|
|
@ -107,6 +115,7 @@ module Squib
|
|||
end
|
||||
module_function :fontify
|
||||
|
||||
# :nodoc:
|
||||
# @api private
|
||||
def radiusify(opts)
|
||||
unless opts[:radius].nil?
|
||||
|
|
@ -117,6 +126,7 @@ module Squib
|
|||
end
|
||||
module_function :radiusify
|
||||
|
||||
# :nodoc:
|
||||
# @api private
|
||||
def svgidify(opts)
|
||||
unless opts[:id].nil?
|
||||
|
|
|
|||
|
|
@ -1,3 +1,6 @@
|
|||
module Squib
|
||||
|
||||
# The next version to be released.
|
||||
# Uses semantic versioning
|
||||
VERSION = "0.0.2"
|
||||
end
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ Squib::Deck.new(layout: 'custom-layout.yml') do
|
|||
# You can also override a given layout entry in the command
|
||||
circle layout: :frame, x: 50, y: 50, radius: 25
|
||||
|
||||
# Any command with x-y-width-height options, we can use a custom layout
|
||||
# Lots of commands have the :layout option
|
||||
text str: 'The Title', layout: :title
|
||||
|
||||
# Layouts also support an "extends" attribute to reuse settings
|
||||
|
|
|
|||
Loading…
Reference in New Issue