squib 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 54d41c6aefc288c69ad7d481ffa6e5b7b26e2658
-  data.tar.gz: fd8a41e64858c0b9b9a6e924dd64ee5ab52b46fc
+  metadata.gz: 7c3a21f564c6f39f4cdd9ac84826e2dd76df1c9e
+  data.tar.gz: dd923de21db270d9e71b5a06752a0a55390feffd
 SHA512:
-  metadata.gz: 30dcd2caaa2ec623d456184a81729aea87765f81d40c726524e2117942bf316165a0df920479faa425462501296a1b984d64ab9b03b10a04bebad4815e0dbc43
-  data.tar.gz: 77d4d1950264389af9396aa895863fc1ba0a4ba1617d4889e0aa1ce982e05d16cd7951ab6488dcf86e05ea7997edd9ab6cc6b2b80ca27be728c848a1a94f6791
+  metadata.gz: 0eab4d96556c539261b0ca346d56af96331d968a3a828826d1172315821ffe3364a5070cf868a4b837775b70ca902e51fd2f9bc194069f10bb99d1675a005549
+  data.tar.gz: c654ed7a07aa5958861b4033066fd64b1cf2e3a114a1e372fca0b58c8b8b40ec6a454fc461e5ba7d5eb60a871e677564bed71466f31f59245e5fec5062aaeca9

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Squib CHANGELOG
 
+## v0.2.0
+* Added `showcase` feature to create a fancy-looking 3D reflection to showcase your cards. Documented, tested, and added a sample for it.
+* Added a basic Rakefile, documented in README.
+* Some internal refactoring, better testing, and more documentation with layouts
+
 ## v0.1.0
 * Added `save_sheet` command that saves a range into PNG sheets, complete with trim, gap, margin, columns, and sometimes automagically computed rows. See samples/saves.rb.
 * Unit conversion! Now you can write "2in" and it will convert based on the current dpi. `save_pdf` not supported (yet).

data/README.md

@@ -76,6 +76,7 @@ About the other files:
   * `_output` is the directory where your built files will go. Can easily be changed, of course.
   * `.gitignore` and `gitkeep.txt` are for if you are using Git. See {file:README.md#Source_control Source control}. (Feel free to remove these if you are not using Git.)
   * `ABOUT.md` and `PHP NOTES.md` are Markdown files for posting. Not used by Squib, but there by convention.
+  * `Rakefile` is a basic build file. Not required but handy - see {file:README.md#Rakefile Rakefile}
 
 # Learning Squib
 
@@ -208,6 +209,20 @@ yang:
   x: += 50
 ```
 
+Furthermore, if you want to extend multiple parents, it looks like this:
+
+```yaml
+socrates:
+  x: 100
+aristotle:
+  y: 200
+aristotle:
+  extends:
+    - socrates
+    - plato
+  x: += 50
+```
+
 ### Multiple layout files
 
 Squib also supports the combination of multiple layout files. As shown in the above example, if you provide an `Array` of files then Squib will merge them sequentially. Colliding keys will be completely re-defined by the later file. Extends is processed after _each file_. YAML merge keys are NOT supported across multiple files - use extends instead. Here's a demonstrative example:
@@ -309,6 +324,14 @@ If you want to make a deck that has some portrait and some landscape cards, I re
 
 {include:file:samples/portrait-landscape.rb}
 
+## Rakefile
+
+When you run `squib new`, you are given a basic Rakefile. At this stage of Squib, it's basically just a shortcut for `ruby deck.rb`. But, even in this simple form this Rakefile has some advantages:
+
+* If you're in a subdirectory at the time, `rake` will simply traverse up and `cd` to the proper directory so you don't get rogue `_output` directories
+* If you find yourself building multiple decks, you can make your own tasks for each one individually, or all (e.g. `rake marketing`)
+* Don't need the `require squib` at the top of your code (although that breaks `ruby deck.rb`, so it's probably a bad idea)
+
 # Development
 
 Squib is currently in pre-release alpha, so the API is still maturing. I do change my mind about the names and meaning of things at this stage. 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).

data/RELEASE TODO.md

@@ -3,11 +3,14 @@ Be sure to remember to do the following for releases. (Copy into a GitHub issue)
  - [ ] CHANGELOG is written for all new changes
  - [ ] README is updated
  - [ ] Samples are updated
+ - [ ] `rake doc`
  - [ ] Check that sample regression tests are all enabled
  - [ ] Bump version.rb
  - [ ] Do a full rake locally
  - [ ] Travis is passing on dev branch
+ - [ ] Merge master branch
+ - [ ] Create GitHub release tag
  - [ ] `gem push pkg/squib-x.y.z.gem`
- - [ ] `rake doc`
+ - [ ] Github milestone closed
  - [ ] Push `rake doc` to website
  - [ ] Bump version.rb to the next alpha

data/Rakefile

@@ -2,9 +2,10 @@ require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'yard'
 
-RSpec::Core::RakeTask.new(:spec)
 task default: [:install, :spec]
 
+RSpec::Core::RakeTask.new(:spec)
+
 YARD::Rake::YardocTask.new(:doc) do |t|
   t.files   = ['lib/**/*.rb', 'samples/**/*.rb']   # optional
   #t.options = ['--any', '--extra', '--opts'] # optional

data/lib/squib.rb

@@ -19,7 +19,7 @@ module Squib
   # @api public
   def logger
     if @logger.nil?
-      @logger = Logger.new(STDOUT);
+      @logger = Logger.new($stdout);
       @logger.level = Logger::WARN;
       @logger.formatter = proc do |severity, datetime, m_progname, msg|
         "#{datetime} #{severity}: #{msg}\n"

data/lib/squib/api/save.rb

@@ -38,5 +38,36 @@ module Squib
       end
     end
 
+    # Renders a range of files in a showcase as if they are sitting on a reflective surface
+    # See {file:samples/showcase.rb} for full example
+    #
+    # @example
+    #   showcase file: 'showcase_output.png', trim: 78, trim_radius: 32
+    #
+    # @option opts [Enumerable, :all] range (:all) the range of cards over which this will be rendered. See {file:README.md#Specifying_Ranges Specifying Ranges}
+    # @option opts [Fixnum] trim (0) the margin around the card to trim before putting into the showcase
+    # @option opts [Fixnum] trim_radius (38) the rounded rectangle radius around the card to trim before putting into the showcase
+    # @option opts [Fixnum] margin (75) the margin around the entire showcase
+    # @option opts [Fixnum] scale (0.8) percentage of original width of each (trimmed) card to scale to. Must be between 0.0 and 1.0, but starts looking bad around 0.6.
+    # @option opts [Fixnum] offset (1.1) percentage of the scaled width of each card to shift each offset. e.g. 1.1 is a 10% shift, and 0.95 is overlapping by 5%
+    # @option opts [String, Color] fill_color (:white) backdrop color. Usually black or white.
+    # @option opts [Fixnum] reflect_offset (15) the number of pixels between the bottom of the card and the reflection
+    # @option opts [Fixnum] reflect_strength (0.2) the starting alpha transparency of the reflection (at the top of the card). Percentage between 0 and 1. Looks more realistic at low values since even shiny surfaces lose a lot of light.
+    # @option opts [Fixnum] reflect_percent (0.25) the length of the reflection in percentage of the card. Larger values tend to make the reflection draw just as much attention as the card, which is not good.
+    # @option opts [:left, :right] face (:left) which direction the cards face. Anything but `:right` will face left
+    # @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] file ('showcase.png') the file to save in dir. Will be overwritten.
+    # @return [nil] Returns nothing.
+    # @api public
+    def showcase(opts = {})
+      opts = {file: 'showcase.png', fill_color: :white}.merge(opts)
+      opts = needs(opts,[:range, :trim, :trim_radius, :creatable_dir, :file_to_save, :face])
+      render_showcase(opts[:range], opts[:trim], opts[:trim_radius],
+                      opts[:scale], opts[:offset], opts[:fill_color],
+                      opts[:reflect_offset], opts[:reflect_percent], opts[:reflect_strength],
+                      opts[:margin], opts[:face],
+                      opts[:dir], opts[:file])
+    end
+
   end
 end

data/lib/squib/card.rb

@@ -4,42 +4,43 @@ require 'squib/input_helpers'
 module Squib
   # Back end graphics. Private.
   class Card
-  include Squib::InputHelpers
+    include Squib::InputHelpers
 
-  # :nodoc:
-  # @api private
-  attr_reader :width, :height
+    # :nodoc:
+    # @api private
+    attr_reader :width, :height
 
-  # :nodoc:
-  # @api private
-  attr_accessor :cairo_surface, :cairo_context
+    # :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
+    # :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
 
   # A save/restore wrapper for using Cairo
   # :nodoc:
   # @api private
-  def use_cairo(&block)
-    @cairo_context.save
-    block.yield(@cairo_context)
-    @cairo_context.restore
-  end
+    def use_cairo(&block)
+      @cairo_context.save
+      block.yield(@cairo_context)
+      @cairo_context.restore
+    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'
+    ########################
+    ### 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/showcase'
+    require 'squib/graphics/text'
 
   end
 end

data/lib/squib/constants.rb

@@ -12,6 +12,7 @@ module Squib
       :default_font => 'Arial 36',
       :dir => '_output',
       :ellipsize => :end,
+      :face => :left,
       :fill_color => '#0000',
       :force_id => false,
       :font => :use_set,
@@ -24,17 +25,23 @@ module Squib
       :justify => false,
       :margin => 75,
       :markup => false,
+      :offset => 1.1,
       :prefix => 'card_',
       :progress_bar => false,
+      :reflect_offset => 15,
+      :reflect_percent => 0.25,
+      :reflect_strength => 0.2,
       :range => :all,
       :rotate => false,
       :rows => :infinite,
+      :scale => 0.85,
       :sheet => 0,
       :spacing => 0,
       :str => '',
       :stroke_color => :black,
       :stroke_width => 2.0,
       :trim => 0,
+      :trim_radius => 38,
       :valign => :top,
       :width => :native,
       :wrap => true,

data/lib/squib/deck.rb

@@ -5,6 +5,7 @@ require 'squib/card'
 require 'squib/progress'
 require 'squib/input_helpers'
 require 'squib/constants'
+require 'squib/layout_parser'
 
 # The project module
 #
@@ -65,7 +66,7 @@ module Squib
       cards.times{ @cards << Squib::Card.new(self, width, height) }
       show_info(config, layout)
       load_config(config)
-      load_layout(layout)
+      @layout = LayoutParser.load_layout(layout)
       if block_given?
         instance_eval(&block)
       end
@@ -85,13 +86,6 @@ module Squib
       @cards.each { |card| block.call(card) }
     end
 
-    # Shows a descriptive place of the location
-    #
-    # @api private
-    def location(opts)
-      opts[:layout] || (" @ #{opts[:x]},#{opts[:y]}")
-    end
-
     # Load the configuration file, if exists, overriding hardcoded defaults
     # @api private
     def load_config(file)
@@ -106,69 +100,6 @@ module Squib
       end
     end
 
-    # Load the layout configuration file, if exists
-    # @api private
-    def load_layout(files)
-      @layout = {}
-      Squib::logger.info { "  using layout(s): #{files}" }
-      Array(files).each do |file|
-        thefile = file
-        thefile = "#{File.dirname(__FILE__)}/layouts/#{file}" unless File.exists?(file)
-        if File.exists? thefile
-          yml = @layout.merge(YAML.load_file(thefile) || {}) #load_file returns false on empty file
-          yml.each do |key, value|
-            @layout[key] = recurse_extends(yml, key, {})
-          end
-        else
-          puts "the file: #{thefile}"
-          Squib::logger.error { "Layout file not found: #{file}" }
-        end
-      end
-    end
-
-    # Process the extends recursively
-    # :nodoc:
-    # @api private
-    def recurse_extends(yml, key, visited )
-      assert_not_visited(key, visited)
-      return yml[key] unless has_extends?(yml, key)
-      visited[key] = key
-      parent_keys = [yml[key]['extends']].flatten
-      h = {}
-      parent_keys.each do |parent_key|
-        from_extends = yml[key].merge(recurse_extends(yml, parent_key, visited)) do |key, child_val, parent_val|
-          if child_val.to_s.strip.start_with?('+=')
-            parent_val + child_val.sub('+=','').strip.to_f
-          elsif child_val.to_s.strip.start_with?('-=')
-            parent_val - child_val.sub('-=','').strip.to_f
-          else
-            child_val #child overrides parent when merging, no +=
-          end
-        end
-        h = h.merge(from_extends) do |key, older_sibling, younger_sibling|
-          younger_sibling #when two siblings have the same entry, the "younger" (lower one) overrides
-        end
-      end
-      return h
-    end
-
-    # Does this layout entry have an extends field?
-    # i.e. is it a base-case or will it need recursion?
-    # :nodoc:
-    # @api private
-    def has_extends?(yml, key)
-      !!yml[key] && yml[key].key?('extends')
-    end
-
-    # Safeguard against malformed circular extends
-    # :nodoc:
-    # @api private
-    def assert_not_visited(key, visited)
-      if visited.key? key
-        raise "Invalid layout: circular extends with '#{key}'"
-      end
-    end
-
     # Use Logger to show more detail on the run
     # :nodoc:
     # @api private

data/lib/squib/graphics/showcase.rb

@@ -0,0 +1,83 @@
+module Squib
+  class Deck
+
+    # So the Cairo people have said over and over again that they won't support the 3x3 matrices that would handle perspective transforms.
+    # Since our perspective transform needs are a bit simpler, we can use a "striping method" that does the job for us.
+    # It's a little bit involved, but it works well enough for limited ranges of our parameters.
+    # These were also helpful:
+    #  http://kapo-cpp.blogspot.com/2008/01/perspective-effect-using-cairo.html
+    #  http://zetcode.com/gui/pygtk/drawingII/
+    # :nodoc:
+    # @api private
+    def render_showcase(range,
+                        trim, trim_radius, scale, offset, fill_color,
+                        reflect_offset, reflect_percent, reflect_strength, margin, face_right,
+                        dir, file_to_save)
+      out_width = range.size * ((@width - 2*trim) * scale * offset) + 2*margin
+      out_height = reflect_offset + (1.0 + reflect_percent) * (@height - 2*trim) + 2*margin
+      out_cc = Cairo::Context.new(Cairo::ImageSurface.new(out_width, out_height))
+      out_cc.set_source_color(fill_color)
+      out_cc.paint
+
+      cards = range.collect { |i| @cards[i] }
+      cards.each_with_index do |card, i|
+        trimmed = trim_rounded(card.cairo_surface, trim, trim_radius)
+        reflected = reflect(trimmed, reflect_offset, reflect_percent, reflect_strength)
+        perspectived = perspective(reflected, scale, face_right)
+        out_cc.set_source(perspectived, margin + i * perspectived.width * offset, margin)
+        out_cc.paint
+      end
+      out_cc.target.write_to_png("#{dir}/#{file_to_save}")
+    end
+
+    # :nodoc:
+    # @api private
+    def trim_rounded(src, trim, radius)
+      trim_cc = Cairo::Context.new(Cairo::ImageSurface.new(src.width-2.0*trim, src.height-2.0*trim))
+      trim_cc.rounded_rectangle(0, 0, trim_cc.target.width, trim_cc.target.height, radius, radius)
+      trim_cc.set_source(src, -1 * trim, -1 * trim)
+      trim_cc.clip
+      trim_cc.paint
+      return trim_cc.target
+    end
+
+    # :nodoc:
+    # @api private
+    def reflect(src, roffset, rpercent, rstrength)
+      tmp_cc = Cairo::Context.new(Cairo::ImageSurface.new(src.width, src.height * (1.0 + rpercent) + roffset))
+      tmp_cc.set_source(src, 0, 0)
+      tmp_cc.paint
+      # Flip affine magic from: http://cairographics.org/matrix_transform/
+      matrix = Cairo::Matrix.new(1, 0, 0, -1, 0, 2 * src.height + roffset)
+      tmp_cc.transform(matrix) # flips the coordinate system
+      top_y    = src.height    # top of the reflection
+      bottom_y = src.height * (1.0 - rpercent) + roffset # bottom of the reflection
+      gradient = Cairo::LinearPattern.new(0,top_y, 0,bottom_y)
+      gradient.add_color_stop_rgba(0.0, 0,0,0, rstrength) # start a little reflected
+      gradient.add_color_stop_rgba(1.0, 0,0,0, 0.0)       # fade to nothing
+      tmp_cc.set_source(src, 0, 0)
+      tmp_cc.mask(gradient)
+      return tmp_cc.target
+    end
+
+    def perspective(src, scale, face_right)
+      dest_cxt = Cairo::Context.new(Cairo::ImageSurface.new(src.width * scale, src.height))
+      in_thickness = 1 # Take strip 1 pixel-width at a time
+      out_thickness = 3 # Scale it to 3 pixels wider to cover any gaps
+      (0..src.width).step(in_thickness) do |i|
+        percentage = i / src.width.to_f
+        i = src.width - i if face_right
+        factor = scale + (percentage * (1.0 - scale)) #linear interpolation
+        dest_cxt.save
+        dest_cxt.translate 0, src.height / 2.0 * (1.0 - factor)
+        dest_cxt.scale factor * scale, factor
+        dest_cxt.set_source src, 0, 0
+        dest_cxt.rounded_rectangle i, 0, out_thickness, src.height, 0,0
+        dest_cxt.fill
+        dest_cxt.restore
+      end
+      return dest_cxt.target
+    end
+
+  end
+end

data/lib/squib/input_helpers.rb

@@ -28,6 +28,7 @@ module Squib
       opts = formatify(opts) if params.include? :formats
       opts = rotateify(opts) if params.include? :rotate
       opts = rowify(opts) if params.include? :rows
+      opts = faceify(opts) if params.include? :face
       opts = convert_units(opts, params)
       opts
     end
@@ -225,5 +226,13 @@ module Squib
       opts
     end
 
+    # Used for showcase - face right if it's :right
+    # :nodoc:
+    # @api private
+    def faceify(opts)
+      opts[:face] = (opts[:face].to_s.downcase == 'right')
+      opts
+    end
+
   end
 end