vector_salad 0.0.7 → 0.0.8

data/lib/vector_salad/exporters/base_exporter.rb

@@ -1,6 +1,7 @@
 require "stringio"
 
 module VectorSalad
+  # @api private
   module Exporters
     class BaseExporter
       attr_reader :canvas

data/lib/vector_salad/exporters/svg_exporter.rb

@@ -1,13 +1,14 @@
-require_relative 'base_exporter.rb'
-Dir.glob(File.expand_path('../../standard_shapes/*.rb', __FILE__)).each do |file|
-  require file
+require_relative "base_exporter.rb"
+Dir.glob(File.expand_path("../../standard_shapes/*.rb", __FILE__)).each do |f|
+  require f
 end
 
 module VectorSalad
   module Exporters
+    # @api private
     class SvgExporter < BaseExporter
       def header
-        puts <<-END.gsub(/^ {10}/, '')
+        puts <<-END.gsub(/^ {10}/, "")
           <svg version="1.1"
                xmlns="http://www.w3.org/2000/svg"
                width="#{canvas_width}"
@@ -16,13 +17,13 @@ module VectorSalad
       end
 
       def footer
-        puts '</svg>'
+        puts "</svg>"
       end
 
       def self.options(options)
-        out = ''
+        out = ""
         options.each do |k, v|
-          out << " #{k.to_s.gsub(/_/, ?-)}=\"#{v.to_s.gsub(/_/, ?-)}\""
+          out << " #{k.to_s.gsub(/_/, '-')}=\"#{v.to_s.gsub(/_/, '-')}\""
         end
         out
       end
@@ -30,59 +31,62 @@ module VectorSalad
   end
 end
 
-
 module VectorSalad
   module StandardShapes
     class Path
+      # Export the shape to an svg string
       def to_svg
         svg = '<path d="'
         svg << to_svg_d_attribute
         svg << '"'
         svg << VectorSalad::Exporters::SvgExporter.options(@options)
-        svg << '/>'
+        svg << "/>"
       end
 
+      # @api private
       def to_svg_d_attribute
         nodes = to_bezier_path.nodes
-        svg = ''
+        svg = ""
         svg << "M #{nodes[0].x} #{nodes[0].y}"
 
         nodes[1..-1].each_index do |j|
-          i = j+1
+          i = j + 1
 
           n = nodes[i]
           case n.type
           when :cubic
-            if nodes[i-1].type == :node
+            if nodes[i - 1].type == :node
               svg << " C #{n.x} #{n.y}"
-            elsif nodes[i-2].type == :node && nodes[i-1].type == :cubic
+            elsif nodes[i - 2].type == :node && nodes[i - 1].type == :cubic
               svg << ", #{n.x} #{n.y}"
             end
           when :quadratic
             svg << " Q #{n.x} #{n.y}"
           when :node
-            if nodes[i-1].type == :cubic || nodes[i-1].type == :quadratic
+            if nodes[i - 1].type == :cubic || nodes[i - 1].type == :quadratic
               svg << ", #{n.x} #{n.y}"
-            elsif nodes[i-1].type == :node
+            elsif nodes[i - 1].type == :node
               svg << " L #{n.x} #{n.y}"
             end
           else
-            raise "The SVG exporter doesn't support #{n.type} node type."
+            fail "The SVG exporter doesn't support #{n.type} node type."
           end
         end
 
-        svg << ' Z' if @closed
+        svg << " Z" if @closed
         svg
       end
     end
 
     class BasicShape
+      # Export the shape to an svg string
       def to_svg
         to_path.to_svg
       end
     end
 
     class MultiPath
+      # Export the shape to an svg string
       def to_svg
         svg = '<path d="'
         paths.each do |path|
@@ -90,42 +94,46 @@ module VectorSalad
         end
         svg << '"'
         svg << VectorSalad::Exporters::SvgExporter.options(@options)
-        svg << '/>'
+        svg << "/>"
       end
     end
 
     class Circle
+      # Export the shape to an svg string
       def to_svg
         svg = "<circle cx=\"#{at[0]}\" cy=\"#{at[1]}\" r=\"#{radius}\""
         svg << VectorSalad::Exporters::SvgExporter.options(@options)
-        svg << '/>'
+        svg << "/>"
       end
     end
 
     class Oval
+      # Export the shape to an svg string
       def to_svg
         svg = "<ellipse cx=\"#{at[0]}\" cy=\"#{at[1]}\""
         svg << " rx=\"#{width}\" ry=\"#{height}\""
         svg << VectorSalad::Exporters::SvgExporter.options(@options)
-        svg << '/>'
+        svg << "/>"
       end
     end
 
     class Square
+      # Export the shape to an svg string
       def to_svg
         svg = "<rect x=\"#{at[0]}\" y=\"#{at[1]}\""
         svg << " width=\"#{size}\" height=\"#{size}\""
         svg << VectorSalad::Exporters::SvgExporter.options(@options)
-        svg << '/>'
+        svg << "/>"
       end
     end
 
     class Rect
+      # Export the shape to an svg string
       def to_svg
         svg = "<rect x=\"#{at[0]}\" y=\"#{at[1]}\""
         svg << " width=\"#{width}\" height=\"#{height}\""
         svg << VectorSalad::Exporters::SvgExporter.options(@options)
-        svg << '/>'
+        svg << "/>"
       end
     end
   end

data/lib/vector_salad/interpolate.rb

@@ -1,11 +1,12 @@
-# Code adapted from:
-# http://jeremykun.com/2013/05/11/bezier-curves-and-picasso/
-#
-# Interpolate a cubic bezier spline into straight line segments,
-# using the De Casteljau algorithm.
 module VectorSalad
+  # Code adapted from:
+  # http://jeremykun.com/2013/05/11/bezier-curves-and-picasso/
+  #
+  # Interpolate a cubic bezier spline into straight line segments,
+  # using the De Casteljau algorithm.
+  #
+  # @api private
   class Interpolate
-    #TOLERANCE = 10 # anything below 50 is roughly good-looking
     TOLERANCE = 0.2 # anything below 50 is roughly good-looking
 
     def initialize
@@ -25,10 +26,10 @@ module VectorSalad
     # Early stopping function for the Casteljau algorithm.
     # Is the curve flat enough for visual purposes?
     def flat_enough?(curve)
-      ax = (3.0*curve[1][0] - 2.0*curve[0][0] - curve[3][0])**2
-      ay = (3.0*curve[1][1] - 2.0*curve[0][1] - curve[3][1])**2
-      bx = (3.0*curve[2][0] - curve[0][0] - 2.0*curve[3][0])**2
-      by = (3.0*curve[2][1] - curve[0][1] - 2.0*curve[3][1])**2
+      ax = (3.0 * curve[1][0] - 2.0 * curve[0][0] - curve[3][0])**2
+      ay = (3.0 * curve[1][1] - 2.0 * curve[0][1] - curve[3][1])**2
+      bx = (3.0 * curve[2][0] - curve[0][0] - 2.0 * curve[3][0])**2
+      by = (3.0 * curve[2][1] - curve[0][1] - 2.0 * curve[3][1])**2
 
       [ax, bx].max + [ay, by].max <= TOLERANCE
     end
@@ -40,7 +41,7 @@ module VectorSalad
     def midpoints(points)
       midpoints = Array.new(points.length - 1)
       midpoints.each_index do |i|
-        midpoints[i] = midpoint(points[i], points[i+1])
+        midpoints[i] = midpoint(points[i], points[i + 1])
       end
       midpoints
     end
@@ -51,7 +52,7 @@ module VectorSalad
       third = midpoints(second)
 
       [[curve[0], first[0], second[0], third[0]],
-      [third[0], second[1], first[2], curve[3]]]
+       [third[0], second[1], first[2], curve[3]]]
     end
   end
 end

data/lib/vector_salad/magic.rb

@@ -1,10 +1,11 @@
-require 'vector_salad/canvas'
-require 'vector_salad/dsl'
-Dir.glob(File.expand_path('../standard_shapes/*.rb', __FILE__)).each do |file|
+require "vector_salad/canvas"
+require "vector_salad/dsl"
+Dir.glob(File.expand_path("../standard_shapes/*.rb", __FILE__)).each do |file|
   require file
 end
 
 module VectorSalad
+  # @api private
   module Magic
     def canvas
       @vs_canvas ||= VectorSalad::Canvas.new

data/lib/vector_salad/mixins/at.rb

@@ -1,5 +1,6 @@
 module VectorSalad
   module Mixins
+    # Mixin for positioning shapes.
     module At
       include Contracts
 

data/lib/vector_salad/mixins/mixins.rb

@@ -0,0 +1,5 @@
+module VectorSalad
+  # Common methods for mixing in to shapes.
+  module Mixins
+  end
+end

data/lib/vector_salad/monkeypatches.rb

@@ -1,10 +1,14 @@
+# Monkeypatches to core Ruby Fixnum class
 class Fixnum
+  # Multiply number self by UNIT constant
   def ~
     self * UNIT
   end
 end
 
+# Monkeypatches to core Ruby Float class
 class Float
+  # Multiply number self by UNIT constant
   def ~
     self * UNIT
   end

data/lib/vector_salad/shape_proxy.rb

@@ -1,4 +1,5 @@
 module VectorSalad
+  # @api private
   class ShapeProxy
     attr_reader :shape
 

data/lib/vector_salad/standard_shapes/basic_shape.rb

@@ -1,29 +1,37 @@
-require 'forwardable'
-require 'contracts'
-require 'contracts_contracts'
+require "forwardable"
+require "contracts"
+require "contracts_contracts"
 
 module VectorSalad
   module StandardShapes
+    # All shapes must inherit from BasicShape,
+    # with the exception of N node.
+    # It alows many usefulmethods in {Path} to be called on the shape
+    # by delegating them, so see {Path} for more information on all the
+    # methods that shapes can use.
+    #
+    # You can't use BasicShape directly.
     class BasicShape
       extend Forwardable
       include Contracts
 
       attr_accessor :options
 
-      delegate [
-        :flip,
-        :flip_x,
-        :flip_y,
-        :rotate,
-        :move,
-        :jitter,
-        :scale,
-        :to_simple_path,
-        :to_bezier_path,
-        :to_cubic_path,
-        :to_multi_path,
-        :to_a
-      ] => :to_path
+      # @!macro [attach] property
+      #   @!method $2
+      #     @see Path#$2
+      def_instance_delegator :to_path, :flip
+      def_instance_delegator :to_path, :flip_x
+      def_instance_delegator :to_path, :flip_y
+      def_instance_delegator :to_path, :rotate
+      def_instance_delegator :to_path, :move
+      def_instance_delegator :to_path, :jitter
+      def_instance_delegator :to_path, :scale
+      def_instance_delegator :to_path, :to_simple_path
+      def_instance_delegator :to_path, :to_bezier_path
+      def_instance_delegator :to_path, :to_cubic_path
+      def_instance_delegator :to_path, :to_multi_path
+      def_instance_delegator :to_path, :to_a
     end
   end
 end

data/lib/vector_salad/standard_shapes/circle.rb

@@ -4,13 +4,14 @@ require "vector_salad/mixins/at"
 
 module VectorSalad
   module StandardShapes
-    class Circle < Path
+    # Perfect circle shape.
+    class Circle < BasicShape # Used to inherit from Path, check still works
       include VectorSalad::Mixins::At
       attr_reader :radius
 
       # Create a perfectly round circle.
       #
-      # Examples do
+      # @example
       #   new(100)
       Contract Pos, {} => Circle
       def initialize(radius, **options)
@@ -20,6 +21,7 @@ module VectorSalad
         self
       end
 
+      # Convert the shape to a path
       def to_path
         # http://stackoverflow.com/a/13338311
         # c = 4 * (Math.sqrt(2) - 1) / 3
@@ -46,8 +48,12 @@ module VectorSalad
         )
       end
 
+      # Flatten the circle into many small straight line segments.
+      #
+      # @param fn The number of segments
+      Contract Maybe[Num] => Path
       def to_simple_path(fn = nil)
-        fn ||= (@radius * 2).ceil
+        fn ||= (@radius * 4).ceil
 
         nodes = []
         arc = (2.0 * Math::PI) / fn

data/lib/vector_salad/standard_shapes/clip.rb

@@ -1,21 +1,20 @@
-require 'clipper'
+require "clipper"
 
-require 'vector_salad/dsl'
-require 'vector_salad/canvas'
-require 'vector_salad/standard_shapes/multi_path'
+require "vector_salad/dsl"
+require "vector_salad/canvas"
+require "vector_salad/standard_shapes/multi_path"
 
 module VectorSalad
   module StandardShapes
+    # Perform a clipping operation on the contained paths or shapes.
+    # It's easier to use one of the subclasses;
+    # (see {Difference}, {Intersection}, {Union}, {Exclusion}).
     class Clip < BasicShape
       include VectorSalad::DSL
       include VectorSalad::StandardShapes
 
-      # Perform a clipping operation on a set of paths or shapes.
       # The first path is used as the subject, subsequent paths are applied to
       # the first using the specified operation.
-      #
-      # It's easier to use one of the subclasses;
-      # (see {Difference}, {Intersection}, {Union}, {Exclusion}).
       Contract Or[*%i(difference intersection union xor)], {}, Proc => MultiPath
       def initialize(operation, **options, &block)
         instance_eval(&block) # canvas is populated
@@ -24,7 +23,7 @@ module VectorSalad
 
         i = 0
         canvas.each do |shape|
-          method = i == 0 ? 'subject' : 'clip'
+          method = i == 0 ? "subject" : "clip"
           path = shape.to_simple_path.to_a
           if path[0][0].instance_of? Array # MultiPath
             clipper.send("add_#{method}_polygons".to_sym, path)
@@ -39,10 +38,12 @@ module VectorSalad
         )
       end
 
+      # The canvas the clipping is done on.
       def canvas
         @canvas ||= VectorSalad::Canvas.new
       end
 
+      # Convert the shape to a path
       def to_path
         @path
       end

data/lib/vector_salad/standard_shapes/custom.rb

@@ -1,11 +1,30 @@
-require 'vector_salad/standard_shapes/path'
-require 'vector_salad/standard_shapes/n'
-require 'vector_salad/dsl'
-require 'vector_salad/canvas'
+require "vector_salad/standard_shapes/path"
+require "vector_salad/standard_shapes/n"
+require "vector_salad/dsl"
+require "vector_salad/canvas"
 
 module VectorSalad
   module StandardShapes
+    # Make your own custom shape.
     class Custom < BasicShape
+      # You must name your custom shape to be able to use it later.
+      # The block passed to custom shape is what will create your shape,
+      # it should create just a single shape or MultiPath.
+      # This means you should use {MultiPath} or one of the {Clip} operations
+      # which return MultiPaths to create complex shapes.
+      #
+      # @example Using DSL:
+      #   custom(:donut) do |size| # name shape and specify parameters
+      #     difference do # return a single shape
+      #       circle(size / 2)
+      #       circle(size / 3)
+      #     end
+      #   end
+      #
+      #   donut(100)
+      #
+      # @param name The name of your shape in snake_case
+      Contract Symbol, {}, Proc => Custom
       def initialize(name, **options, &block)
         ::VectorSalad::StandardShapes.const_set(name.to_s.capitalize.to_sym, Class.new(BasicShape) do
           include VectorSalad::DSL