squib 0.0.1 → 0.0.2

data/lib/squib/api/settings.rb

@@ -0,0 +1,35 @@
+module Squib
+  class Deck
+
+    # Toggle hints globally. 
+    #
+    # Text hints are rectangles around where the text will be laid out. They are intended to be temporary.
+    # Setting a hint to nil or to :off will disable hints. @see samples/text.rb
+    # @example
+    #   hint text:cyan
+    #
+    # @param [String] text the color of the text hint. To turn off use nil or :off. @see API.md 
+    # @return [nil] Returns nothing
+    # @api public
+    def hint(text: nil)
+      text = nil if text == :off
+      @text_hint = text
+    end
+
+    # Sets various defaults for this deck. Defaults can be overriden by the commands themselves
+    # @example 
+    #   set font: 'Arial 26'
+    #   text 'blah'                     # in Arial 26
+    #   text 'blah24', font: 'Arial 24' # in Arial 24
+    #   set font: :default              # Back to Squib-wide default
+    #
+    # @option opts font: the font string to set as default. Can also be set to `:default` to use the Squib-wide default.
+    # @return [nil] Returns nothing
+    # @api public
+    def set(opts = {})
+      opts = needs(opts, [:font])
+      @font = opts[:font]
+    end 
+
+  end
+end

data/lib/squib/api/shapes.rb

@@ -1,13 +1,107 @@
-module Squib
-  class Deck
-    
-    def rect(range: :all, x: 0, y: 0, width: 825, height: 1125, \
-              x_radius: 0, y_radius: 0)
-      range = rangeify(range)
-      range.each do |i|
-        @cards[i].draw_rectangle(x, y, width, height, x_radius, y_radius)
-      end
-    end
-    
-  end
+module Squib
+  class Deck
+    
+    # Draw a rounded rectangle
+    # 
+    # @example 
+    #   rect x: 0, y: 0, width: 825, height: 1125, radius: 25
+    #
+    # @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 x [Integer] (0) the x-coordinate to place
+    # @option opts y [Integer] (0) the y-coordinate to place
+    # @option opts width [Integer] the width of the rectangle.
+    # @option opts height [Integer] the height of the rectangle.
+    # @option opts x_radius [Integer] (0) the radius of the rounded corner horiztonally. Zero is a non-rounded corner.
+    # @option opts y_radius [Integer] (0) the radius of the rounded corner vertically. Zero is a non-rounded corner.
+    # @option opts radius [Integer] (nil) when set, overrides both x_radius and y_radius
+    # @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 = {})
+      opts = needs(opts, [:range, :x, :y, :width, :height, :radius, 
+                          :fill_color, :stroke_color, :stroke_width, :layout])
+      opts[:range].each do |i|
+        @cards[i].rect(opts[:x], opts[:y], opts[:width], opts[:height], 
+          opts[:x_radius], opts[:y_radius], 
+          opts[:fill_color], opts[:stroke_color], opts[:stroke_width])
+      end
+    end
+
+    # Draw a circle centered at the given coordinates
+    # 
+    # @example 
+    #   circle x: 0, y: 0, radius: 100
+    #
+    # @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 x [Integer] (0) the x-coordinate to place
+    # @option opts y [Integer] (0) the y-coordinate to place
+    # @option opts radius [Integer] (100) radius of the circle
+    # @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
+    # @return [nil] intended to be void
+    # @api public
+    def circle(opts = {})
+      opts = {radius: 100}.merge(opts)
+      opts = needs(opts, [:range, :x, :y, :circle_radius, :layout,
+                          :fill_color, :stroke_color, :stroke_width])
+      opts[:range].each do |i|
+        @cards[i].circle(opts[:x], opts[:y], opts[:radius], 
+          opts[:fill_color], opts[:stroke_color], opts[:stroke_width])
+      end
+    end
+
+    # Draw a triangle using the given coordinates
+    # 
+    # @example 
+    #   triangle :x1 => 0, :y1 => 0, :x2 => 50, :y2 => 50, :x3 => 0, :y3 => 50
+    #
+    # @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 x1 [Integer] (0) the x-coordinate to place
+    # @option opts y1 [Integer] (0) the y-coordinate to place
+    # @option opts x2 [Integer] (50) the x-coordinate to place
+    # @option opts y2 [Integer] (50) the y-coordinate to place
+    # @option opts x3 [Integer] (0) the x-coordinate to place
+    # @option opts y3 [Integer] (50) the y-coordinate to place
+    # @option opts fill_color [String] ('#0000') the color with which to fill the triangle
+    # @option opts stroke_color [String] (:black) the color with which to stroke the outside of the triangle
+    # @option opts stroke_width [Decimal] (2.0) the width of the outside stroke
+    # @return [nil] intended to be void
+    # @api public
+    def triangle(opts = {})
+      opts = needs(opts, [:range, :x1, :y1, :x2, :y2, :x3, :y3, :layout,
+                          :fill_color, :stroke_color, :stroke_width])
+      opts[:range].each do |i|
+        @cards[i].triangle(opts[:x1], opts[:y1], opts[:x2], opts[:y2],opts[:x3], opts[:y3], 
+          opts[:fill_color], opts[:stroke_color], opts[:stroke_width])
+      end
+    end
+
+    # Draw a line using the given coordinates
+    # 
+    # @example 
+    #   triangle :x1 => 0, :y1 => 0, :x2 => 50, :y2 => 50
+    #
+    # @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 x1 [Integer] (0) the x-coordinate to place
+    # @option opts y1 [Integer] (0) the y-coordinate to place
+    # @option opts x2 [Integer] (50) the x-coordinate to place
+    # @option opts y2 [Integer] (50) the y-coordinate to place
+    # @option opts stroke_color [String] (:black) the color with which to stroke the line
+    # @option opts stroke_width [Decimal] (2.0) the width of the outside stroke
+    # @return [nil] intended to be void
+    # @api public
+    def line(opts = {})
+      opts = needs(opts, [:range, :x1, :y1, :x2, :y2, :layout,
+                          :stroke_color, :stroke_width])
+      opts[:range].each do |i|
+        @cards[i].line(opts[:x1], opts[:y1], opts[:x2], opts[:y2],
+                       opts[:stroke_color], opts[:stroke_width])
+      end
+    end
+    
+  end
 end

data/lib/squib/api/text.rb

@@ -1,26 +1,46 @@
-module Squib
-  class Deck
-    def fontify (font)
-      font = 'Arial 36' if font==:use_set
-      font
-    end
-
-    def font(type: 'Arial', size: 12, **options)
-      raise 'Not implemented!'
-    end
-
-    def set_font(type: 'Arial', size: 12, **options)
-      raise 'Not implemented!'
-    end
-
-    def text(range: :all, str: '', font: :use_set, x: 0, y: 0, **options)
-      range = rangeify(range)
-      str = [str] * @cards.size unless str.respond_to? :each
-      font = fontify(font)
-      range.each do |i|
-        cards[i].text(str[i], font, x, y, options)
-      end
-    end
-
-  end
+module Squib
+  class Deck
+
+    # 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 
+    #   text str: 'hello'
+    #   text str: 'hello', x: 50, y:50, align: center
+    # 
+    # @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.
+    # @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 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
+    # @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}). 
+    # @return [nil] Returns nothing
+    # @api public
+    def text(opts = {})
+      opts = needs(opts, [:range, :str, :font, :x, :y, :width, :height, :text_color, :wrap,
+                          :align, :justify, :valign, :ellipsize, :hint, :layout])
+      opts[:str] = [opts[:str]] * @cards.size unless opts[:str].respond_to? :each
+      opts[:range].each do |i|
+        @cards[i].text(opts[:str][i], opts[:font], opts[:x], opts[:y], opts[:color], opts)
+      end
+    end
+
+  end
 end

data/lib/squib/api/units.rb

@@ -0,0 +1,17 @@
+module Squib
+  class Deck
+
+    # Given inches, returns the number of pixels according to the deck's DPI.
+    # 
+    # @example 
+    #   inches(2.5) # 750 (for default Deck::dpi of 300)
+    #
+    # @param [Decimal] n, the number of inches
+    # @return [Decimal] the number of pixels, according to the deck's DPI
+    # @api public
+    def inches(n)
+      @dpi * n
+    end
+
+  end
+end

data/lib/squib/card.rb

@@ -1,27 +1,36 @@
-require 'cairo'
-
-module Squib
-
-	class Card
-    attr_reader :width, :height
-    attr_accessor :cairo_surface, :cairo_context
-
-    def initialize(width, height)
-      @width=width; @height=height
-      @cairo_surface = Cairo::ImageSurface.new(width,height)
-      @cairo_context = Cairo::Context.new(@cairo_surface)
-    end
-
-    ########################
-    ### BACKEND GRAPHICS ###
-    ########################
-    require 'squib/graphics/background'
-    require 'squib/graphics/image'
-    require 'squib/graphics/save_doc'
-    require 'squib/graphics/save_images'
-    require 'squib/graphics/shapes'
-    require 'squib/graphics/text'
-    
-	end
-
-end
+require 'cairo'
+require 'squib/input_helpers'
+
+module Squib
+    # Back end graphics. Private.
+	class Card
+    include Squib::InputHelpers
+
+    # :nodoc:
+    # @api private 
+    attr_reader :width, :height
+
+    # :nodoc:
+    # @api private 
+    attr_accessor :cairo_surface, :cairo_context
+
+        # :nodoc:
+        # @api private 
+        def initialize(deck, width, height)
+          @deck=deck; @width=width; @height=height
+          @cairo_surface = Cairo::ImageSurface.new(width,height)
+          @cairo_context = Cairo::Context.new(@cairo_surface)
+        end
+
+        ########################
+        ### BACKEND GRAPHICS ###
+        ########################
+        require 'squib/graphics/background'
+        require 'squib/graphics/image'
+        require 'squib/graphics/save_doc'
+        require 'squib/graphics/save_images'
+        require 'squib/graphics/shapes'
+        require 'squib/graphics/text'
+        
+      end
+    end

data/lib/squib/commands/new.rb

@@ -0,0 +1,40 @@
+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?
+
+        new_project_path = File.expand_path(args.join(" "), Dir.pwd)
+        template_path = File.expand_path('../project_template', File.dirname(__FILE__))
+
+        FileUtils.mkdir_p new_project_path
+        if !Dir["#{new_project_path}/**/*"].empty?
+          $stderr.puts "#{new_project_path} exists and is not empty. Doing nothing and quitting."
+        else
+          Dir.chdir(new_project_path) do
+            FileUtils.cp_r template_path + '/.', new_project_path
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/squib/constants.rb

@@ -0,0 +1,40 @@
+module Squib
+    # Squib's defaults for when arguments are not specified in the command nor layouts.
+    # 
+    # @api public
+    SYSTEM_DEFAULTS = { 
+      :range => :all,
+      :color => :black,
+      :str => '',
+      :fill_color => '#0000',
+      :stroke_color => :black,
+      :stroke_width => 2.0,
+      :font => :use_set,
+      :default_font => 'Arial 36',
+      :sheet => 0,
+      :x => 0,
+      :y => 0,
+      :x1 => 100,
+      :y1 => 100,
+      :x2 => 150,
+      :y2 => 150,
+      :x3 => 100,
+      :y3 => 150,
+      :x_radius => 0, 
+      :y_radius => 0,
+      :align => :left,
+      :valign => :top,
+      :justify => false,
+      :ellipsize => :end,
+      :width => :native,
+      :height => :native,
+      :alpha => 1.0,
+      :format => :png,
+      :dir => "_output",
+      :prefix => "card_",
+      :margin => 75,
+      :gap => 0,
+      :trim => 0
+    }
+
+end

data/lib/squib/deck.rb

@@ -1,49 +1,114 @@
-require 'squib/card'
-
-module Squib
-  class Deck
-    include Enumerable
-    attr_reader :width, :height
-    attr_reader :cards
-
-    def initialize(width: 825, height: 1125, cards: 1, &block)
-      @width=width; @height=height
-      @cards = []
-      cards.times{ @cards << Squib::Card.new(width, height) }
-      if block_given?
-        instance_eval(&block)
-      end
-    end
-
-    def [](key)
-      @cards[key]
-    end
-
-    #For Enumerable
-    def each(&block)
-      @cards.each { |card| block.call(card) }
-    end
-
-    def rangeify (range)
-      range = 0..(@cards.size-1) if range == :all
-      range = range..range if range.is_a? Integer
-      return range
-    end
-
-    def fileify(file)
-      raise 'File #{file} does not exist!' unless File.exists? file
-      file
-    end
-
-    ##################
-    ### PUBLIC API ###
-    ##################
-    require 'squib/api/background'
-    require 'squib/api/data'
-    require 'squib/api/image'
-    require 'squib/api/save'
-    require 'squib/api/shapes'
-    require 'squib/api/text'
-
-  end
+require 'yaml'
+require 'pp'
+require 'squib/card'
+require 'squib/input_helpers'
+require 'squib/constants'
+
+# The project module
+#
+# @api public
+module Squib
+
+  # The main interface to Squib. Provides a front-end porcelain whereas the Card class interacts with the graphics plumbing.
+  #
+  # @api public
+  class Deck
+    include Enumerable
+    include Squib::InputHelpers
+
+    # :nodoc:
+    # @api private 
+    attr_reader :width, :height
+    
+    # :nodoc:
+    # @api private 
+    attr_reader :cards
+    
+    # :nodoc:
+    # @api private 
+    attr_reader :text_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.
+    # @api public
+    def initialize(width: 825, height: 1125, cards: 1, dpi: 300, config: 'config.yml', layout: nil, &block)
+      @width=width; @height=height
+      @dpi = dpi
+      @font = Squib::SYSTEM_DEFAULTS[:default_font]
+      @cards = []
+      cards.times{ @cards << Squib::Card.new(self, width, height) }
+      load_config(config)
+      load_layout(layout)
+      if block_given?
+        instance_eval(&block)
+      end
+    end
+
+    # Directly accesses the array of cards in the deck
+    #
+    # @api private
+    def [](key)
+      @cards[key]
+    end
+
+    # Iterates over each card in the deck
+    # 
+    # @api private
+    def each(&block)
+      @cards.each { |card| block.call(card) }
+    end
+
+    # Load the configuration file, if exists, overriding hardcoded defaults
+    # @api private
+    def load_config(file)
+      if File.exists? file
+        if config = YAML.load_file(file)
+          @dpi = config['dpi'].to_i
+        end
+      end
+    end
+
+    # Load the layout configuration file, if exists
+    # @api private
+    def load_layout(file)
+      return if file.nil?
+      prelayout = YAML.load_file(file)
+      @layout = {}
+      prelayout.each do |key, value|
+        if value.key? "extends"
+          @layout[key] = prelayout[value["extends"]].merge prelayout[key]
+        else 
+          @layout[key] = value
+        end
+      end
+    end
+
+    ##################
+    ### PUBLIC API ###
+    ##################
+    require 'squib/api/background'
+    require 'squib/api/data'
+    require 'squib/api/image'
+    require 'squib/api/save'
+    require 'squib/api/settings'
+    require 'squib/api/shapes'
+    require 'squib/api/text'
+    require 'squib/api/units'
+
+  end
 end

data/lib/squib/graphics/background.rb

@@ -1,11 +1,13 @@
-module Squib
-  class Card
-
-    def background(color)
-      cc = cairo_context
-      cc.set_source_rgb(*color)
-      cc.paint
-    end
-      
-  end
+module Squib
+  class Card
+
+    # :nodoc:
+    # @api private 
+    def background(color)
+      cc = cairo_context
+      cc.set_source_color(color)
+      cc.paint
+    end
+      
+  end
 end

data/lib/squib/graphics/image.rb

@@ -1,12 +1,28 @@
-module Squib
-  class Card
-
-    def png(file, x, y)
-      cc = cairo_context
-      png = Cairo::ImageSurface.from_png(file)
-      cc.set_source(png, x, y)
-      cc.paint
-    end
-
-  end
-end
+module Squib
+  class Card
+
+    # :nodoc:
+    # @api private 
+    def png(file, x, y, alpha)
+      cc = cairo_context
+      png = Cairo::ImageSurface.from_png(file)
+      cc.set_source(png, x, y)
+      cc.paint(alpha)
+    end
+
+    # :nodoc:
+    # @api private 
+    def svg(file, id, x, y, width, height)
+      svg = RSVG::Handle.new_from_file(file)
+      width = svg.width if width == :native
+      height = svg.height if height == :native
+      tmp = Cairo::ImageSurface.new(width, height)
+      tmp_cc = Cairo::Context.new(tmp)
+      tmp_cc.scale(width.to_f / svg.width.to_f, height.to_f / svg.height.to_f)
+      tmp_cc.render_rsvg_handle(svg, id)
+      cairo_context.set_source(tmp, x, y)
+      cairo_context.paint
+    end
+
+  end
+end