vector_salad 0.0.7 → 0.0.8

data/lib/vector_salad/standard_shapes/difference.rb

@@ -1,21 +1,20 @@
-require 'vector_salad/standard_shapes/clip'
-require 'vector_salad/standard_shapes/multi_path'
+require "vector_salad/standard_shapes/clip"
+require "vector_salad/standard_shapes/multi_path"
 
 module VectorSalad
   module StandardShapes
+    # Subtract the contained shapes.
     class Difference < Clip
-      # Subtract paths.
       # The first path is used as the subject, subsequent paths are subtracted
       # from the first.
       #
-      # Examples:
-      #
+      # @example
       #   Difference.new do
       #     canvas << Path.new([0,0], [90,90], [0,90])
       #     canvas << Path.new([50,0], [95,0], [50, 70])
       #   end
       #
-      #   # Using DSL:
+      # @example Using DSL:
       #   difference do
       #     path([0,0], [90,90], [0,90])
       #     path([50,0], [95,0], [50, 70])

data/lib/vector_salad/standard_shapes/exclusion.rb

@@ -1,21 +1,20 @@
-require 'vector_salad/standard_shapes/clip'
-require 'vector_salad/standard_shapes/multi_path'
+require "vector_salad/standard_shapes/clip"
+require "vector_salad/standard_shapes/multi_path"
 
 module VectorSalad
   module StandardShapes
+    # Exclude the contained shapes.
     class Exclusion < Clip
-      # Exclude paths.
       # The first path is used as the subject, subsequent paths are excluded
       # from the first.
       #
-      # Examples:
-      #
+      # @example
       #   Exclusion.new do
       #     canvas << Path.new([0,0], [90,90], [0,90])
       #     canvas << Path.new([50,0], [95,0], [50, 70])
       #   end
       #
-      #   # Using DSL:
+      # @example Using DSL:
       #   exclusion do
       #     path([0,0], [90,90], [0,90])
       #     path([50,0], [95,0], [50, 70])

data/lib/vector_salad/standard_shapes/flip.rb

@@ -1,12 +1,18 @@
-require 'vector_salad/standard_shapes/transform'
+require "vector_salad/standard_shapes/transform"
 
 module VectorSalad
   module StandardShapes
+    # Flip the contained shapes.
     class Flip < Transform
       # Flip the contained shapes on the specified axis.
       #
-      # Examples:
+      # @example
+      #   Flip.new(:x) do
+      #     canvas << Triangle.new(30, at: [50, -50])
+      #     canvas << Pentagon.new(40, at: [50, -100])
+      #   end
       #
+      # @example Using DSL:
       #   flip(:x) do
       #     triangle(30, at: [50, -50])
       #     pentagon(40, at: [50, -100])

data/lib/vector_salad/standard_shapes/heart.rb

@@ -2,6 +2,7 @@ require "vector_salad/standard_shapes/polygon"
 
 module VectorSalad
   module StandardShapes
+    # Perfect heart shape.
     class Heart < BasicShape
       # Create a perfect heart
       Contract Pos, {} => Heart
@@ -16,13 +17,14 @@ module VectorSalad
           circle(r)[-r, 0]
           circle(r)[r, 0]
           difference do
-            square(l)[-l/2, -l/2].rotate(45).move(0, r2 / 2)
+            square(l)[-l / 2, -l / 2].rotate(45).move(0, r2 / 2)
             square(l * 2)[-l, -l * 2]
           end
         end
         self
       end
 
+      # Convert the shape to a path
       def to_path
         @shape
       end

data/lib/vector_salad/standard_shapes/hexagon.rb

@@ -1,11 +1,12 @@
-require 'vector_salad/standard_shapes/polygon'
+require "vector_salad/standard_shapes/polygon"
 
 module VectorSalad
   module StandardShapes
+    # Regular hexagon shape.
     class Hexagon < Polygon
       # Create a regular hexagon.
       #
-      # Examples:
+      # @example
       #   new(100)
       def initialize(radius, **options)
         super(6, radius, **options)

data/lib/vector_salad/standard_shapes/intersection.rb

@@ -1,21 +1,20 @@
-require 'vector_salad/standard_shapes/clip'
-require 'vector_salad/standard_shapes/multi_path'
+require "vector_salad/standard_shapes/clip"
+require "vector_salad/standard_shapes/multi_path"
 
 module VectorSalad
   module StandardShapes
+    # Intersect the contained shapes.
     class Intersection < Clip
-      # Intersect paths.
       # The first path is used as the subject, subsequent paths are intersected
       # with the first.
       #
-      # Examples:
-      #
+      # @example
       #   Intersection.new do
       #     canvas << Path.new([0,0], [90,90], [0,90])
       #     canvas << Path.new([50,0], [95,0], [50, 70])
       #   end
       #
-      #   # Using DSL:
+      # @example Using DSL:
       #   intersection do
       #     path([0,0], [90,90], [0,90])
       #     path([50,0], [95,0], [50, 70])

data/lib/vector_salad/standard_shapes/iso_tri.rb

@@ -4,6 +4,7 @@ require "vector_salad/mixins/at"
 
 module VectorSalad
   module StandardShapes
+    # Isosceles or right-angle triangle shape.
     class IsoTri < BasicShape
       include VectorSalad::Mixins::At
 
@@ -11,8 +12,7 @@ module VectorSalad
 
       # Create an isosceles or right-angle triangle.
       #
-      # Examples:
-      #
+      # @example
       #   new(100)
       #   new(100, 150)
       #
@@ -26,6 +26,7 @@ module VectorSalad
         self
       end
 
+      # Convert the shape to a path
       def to_path
         Path.new(
           N.n(@x, @y),

data/lib/vector_salad/standard_shapes/jitter.rb

@@ -1,18 +1,21 @@
-require 'vector_salad/standard_shapes/transform'
+require "vector_salad/standard_shapes/transform"
 
 module VectorSalad
   module StandardShapes
+    # Jitter the position of nodes in the contained shapes randomly.
     class Jitter < Transform
-      # Moves the contained shapes by the specified x and y amounts relatively.
-      #
-      # Examples:
+      # @example
+      #   Jitter.new(5) do
+      #     canvas << Triangle.new(30, at: [50, -50])
+      #     canvas << Pentagon.new(40, at: [50, -100])
+      #   end
       #
-      #   move(50, -10) do
+      # @example Using DSL:
+      #   jitter(5) do
       #     triangle(30, at: [50, -50])
       #     pentagon(40, at: [50, -100])
       #   end
-
-      # Jitter the position of nodes in a Path randomly.
+      #
       # @param max The maximum offset
       # @param min The minimum offset (default 0)
       # @param fn The quantization number of sides

data/lib/vector_salad/standard_shapes/move.rb

@@ -2,11 +2,17 @@ require "vector_salad/standard_shapes/transform"
 
 module VectorSalad
   module StandardShapes
+    # Move the contained shapes.
     class Move < Transform
       # Moves the contained shapes by the specified x and y amounts relatively.
       #
-      # Examples:
+      # @example
+      #   Move.new do
+      #     canvas << Triangle.new(30, at: [50, -50])
+      #     canvas << Pentagon.new(40, at: [50, -100])
+      #   end
       #
+      # @example Using DSL:
       #   move(50, -10) do
       #     triangle(30, at: [50, -50])
       #     pentagon(40, at: [50, -100])

data/lib/vector_salad/standard_shapes/multi_path.rb

@@ -1,21 +1,22 @@
-require 'vector_salad/standard_shapes/basic_shape'
-require 'vector_salad/standard_shapes/n'
-require 'vector_salad/interpolate'
+require "vector_salad/standard_shapes/basic_shape"
+require "vector_salad/standard_shapes/n"
+require "vector_salad/interpolate"
 
 module VectorSalad
   module StandardShapes
+    # MultiPath shape is a collection of Paths.
+    # It is mainly to store the result of {Clip} operations.
     class MultiPath < BasicShape
       attr_reader :paths, :closed
 
-      # A MultiPath is a collection of Paths.
-      # It is mainly the result of {Clip} operations.
       # See {Path} for details on constructing paths.
       #
-      # Examples:
+      # @example
       #   new(
       #     Path.n([0,0], [0,300], [300,300], [300,0], [0,0]),
       #     Path.n([100,100], [200,100], [200,200], [100,200], [100,100])
       #   )
+      # @example
       #   new(
       #     [[0,0], [0,300], [300,300], [300,0], [0,0]],
       #     [[100,100], [200,100], [200,200], [100,200], [100,100]]
@@ -56,22 +57,32 @@ module VectorSalad
         each_send(:scale, multiplier)
       end
 
+      # Convert the shape to a path
       def to_path
         self
       end
 
+      # Convert the complex paths in the MultiPath to bezier paths.
+      def to_bezier_path
+        self.class.new(*@paths.map(&:to_bezier_path), **@options)
+      end
+
+      # Convert the complex paths in the MultiPath to cubic bezier paths only.
       def to_cubic_path
         self.class.new(*@paths.map(&:to_cubic_path), **@options)
       end
 
+      # Convert the complex paths in the MultiPath to simple paths.
       def to_simple_path
         self.class.new(*@paths.map(&:to_simple_path), **@options)
       end
 
+      # Returns self
       def to_multi_path
         self
       end
 
+      # Return an array of paths that are and array of node coordinates.
       def to_a
         @paths.map(&:to_a)
       end

data/lib/vector_salad/standard_shapes/n.rb

@@ -2,6 +2,9 @@ require "vector_salad/mixins/at"
 
 module VectorSalad
   module StandardShapes
+    # N node. A node is the simplest primitive but useless on its own.
+    # Use nodes to build up a path (see Path).
+    # A node is a point in space with x and y coordinates.
     class N
       include VectorSalad::Mixins::At
       include Contracts
@@ -14,9 +17,9 @@ module VectorSalad
         self
       end
 
-      # A node is the simplest primitive but useless on its own. Use nodes to
-      # build up a path (see Path). A node is a point in space with x and y
-      # coordinates. The coordinates must be nil if the node type is :mirror,
+      # Create an N node.
+      #
+      # The coordinates must be nil if the node type is :mirror,
       # else they must be numeric.
       #
       # A node also has a type, the simplest is :node for corners.

data/lib/vector_salad/standard_shapes/oval.rb

@@ -4,13 +4,14 @@ require "vector_salad/mixins/at"
 
 module VectorSalad
   module StandardShapes
+    # Oval shape.
     class Oval < BasicShape
       include VectorSalad::Mixins::At
       attr_reader :width, :height
 
       # Create an oval.
       #
-      # Examples:
+      # @example
       #   new(100, 200)
       Contract Pos, Pos, {} => Oval
       def initialize(width, height, **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

data/lib/vector_salad/standard_shapes/path.rb

@@ -1,19 +1,19 @@
-require 'spiro'
+require "spiro"
 
-require 'vector_salad/standard_shapes/basic_shape'
-require 'vector_salad/standard_shapes/n'
-require 'vector_salad/interpolate'
+require "vector_salad/standard_shapes/basic_shape"
+require "vector_salad/standard_shapes/n"
+require "vector_salad/interpolate"
 
 module VectorSalad
   module StandardShapes
+    # The simplest shape primitive, all shapes can be represented as a Path.
     class Path < BasicShape
       attr_reader :nodes, :closed
 
-      # The simplest shape primitive, all shapes can be represented as a Path.
       # A path is made up of N nodes and these nodes can have different types
       # (see N).
       #
-      # Examples:
+      # @example
       #   new([0,0], [0,1], [1,1])
       #
       # @param nodes x,y coordinate arrays or N node instances
@@ -24,17 +24,17 @@ module VectorSalad
         nodes.each_index do |i|
           node = nodes[i].class == Array ? N.new(*nodes[i]) : nodes[i]
           if i == 0 && ![:node, :g2, :g4, :left, :right].include?(node.type)
-            fail 'First node in a path must be :node or :spiro type.'
+            fail "First node in a path must be :node or :spiro type."
           end
           case node.type
           when :cubic
             unless nodes[i - 1].type == :node ||
                   (nodes[i - 2].type == :node && nodes[i - 1].type == :cubic)
-              fail ':cubic nodes must follow a :node and at most 1 other :cubic.'
+              fail ":cubic node must follow a :node and at most 1 other :cubic."
             end
           when :quadratic
             unless nodes[i - 1].type == :node
-              fail ':quadratic nodes must follow a :node.'
+              fail ":quadratic nodes must follow a :node."
             end
           when :mirror
             if nodes[i - 1].type == :node &&
@@ -48,8 +48,8 @@ module VectorSalad
 
               node.type = source.type
             else
-              fail ':reflect nodes must be preceeded by a :node with a
-                :quadratic or :cubic before that.'
+              fail ":reflect nodes must be preceeded by a :node with a
+                :quadratic or :cubic before that."
             end
           when :node
           end
@@ -96,8 +96,9 @@ module VectorSalad
 
       # Flips the path on the specified axis.
       #
-      # Examples:
+      # @example
       #   flip(:x)
+      # @example
       #   flip(:y)
       Contract Or[:x, :y] => Path
       def flip(axis)
@@ -111,8 +112,10 @@ module VectorSalad
       end
 
       # Rotates the Path by the specified angle about the origin.
-      # Examples:
+      #
+      # @example
       #   rotate(90)
+      # @example
       #   rotate(-45)
       Contract Num => Path
       def rotate(angle)
@@ -135,6 +138,7 @@ module VectorSalad
       # Scale a Path by multiplier about the origin.
       # Supply just 1 multiplier to scale evenly, or x and y multipliers
       # to stretch or squash the axies.
+      #
       # @param x_multiplier 1 is no change, 2 is double size, 0.5 is half, etc.
       Contract Num, Maybe[Num] => Path
       def scale(x_multiplier, y_multiplier = x_multiplier)
@@ -150,6 +154,7 @@ module VectorSalad
       end
 
       # Jitter the position of nodes in a Path randomly.
+      #
       # @param max The maximum offset
       # @param min The minimum offset (default 0)
       # @param fn The quantization number of sides
@@ -166,10 +171,13 @@ module VectorSalad
         )
       end
 
+      # Convert the path to a path (it returns self)
       def to_path
         self
       end
 
+      # Convert the complex path to a bezier path.
+      # This will convert any Spiro curve nodes into beziers.
       def to_bezier_path
         path = to_path
         spiro = false
@@ -180,7 +188,7 @@ module VectorSalad
         if spiro
           flat_spline_path = Spiro.spiros_to_splines(flat_path, @closed)
           if flat_spline_path.nil?
-            fail 'Spiro failed, try different coordinates or using G2 nodes.'
+            fail "Spiro failed, try different coordinates or using G2 nodes."
           else
             path = Path.new(*flat_spline_path.map do |n|
               N.new(n[0], n[1], n[2])
@@ -190,6 +198,9 @@ module VectorSalad
         path
       end
 
+      # Convert the path into a cubic bezier path (no quadratics).
+      # This will convert any Spiro curve nodes into beziers and
+      # any quadratic beziers into cubics.
       def to_cubic_path
         path = to_bezier_path.nodes
         cubic_path = []
@@ -223,6 +234,7 @@ module VectorSalad
         Path.new(*cubic_path, closed: @closed, **@options)
       end
 
+      # Flatten any curves in the path into many small straight line segments.
       def to_simple_path(*_)
         # convert bezier curves and spiro splines
         path = to_cubic_path.nodes
@@ -246,10 +258,12 @@ module VectorSalad
         Path.new(*nodes, closed: @closed, **@options)
       end
 
+      # Wrap the path in a multi_path.
       def to_multi_path
         MultiPath.new(self)
       end
 
+      # Return the nodes as an array of coordinates.
       def to_a
         nodes.map(&:at)
       end