vector2d 2.3.0 → 3.0.0

data/spec/spec_helper.rb

@@ -5,3 +5,5 @@ SimpleCov.start
 
 require "vector2d"
 require "rspec/its"
+
+Dir[File.expand_path("support/**/*.rb", __dir__)].each { |file| require file }

data/spec/support/doc_examples/comments.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module DocExamples
+  # The examples in the doc comments under lib/. An example is an
+  # indented line inside a comment, and one comment is one block, named
+  # after the method it sits above.
+  #
+  # Tag blocks are skipped. A block runs from the first tag at the left
+  # margin of the comment to the next blank comment line, so the type
+  # lists in @param and @return are not mistaken for examples.
+  module Comments
+    COMMENT = /\A\s*#(?:\s|\z)/
+    INDENTED = /\A\s*#\s{3}(\s*\S.*)\z/
+    DEFINITION = /\A\s*def\s+(self\.)?([^\s(]+)/
+    TAG = /\A\s*#\s@/
+    BLANK = /\A\s*#\s*\z/
+
+    class << self
+      def blocks
+        Dir[File.join(ROOT, "lib/**/*.rb")].flat_map { |path| parse(path) }
+      end
+
+      private
+
+      def parse(path)
+        chunks = File.readlines(path, chomp: true).each_with_index.to_a
+                     .chunk { |line, _| line.match?(COMMENT) }.to_a
+        chunks.each_with_index.filter_map do |(comment, lines), index|
+          block(path, lines, chunks.dig(index + 1, 1)) if comment
+        end
+      end
+
+      def block(path, lines, following)
+        DocExamples.block(path.delete_prefix("#{ROOT}/"), lines.first[1] + 1,
+                          name(following), code(lines))
+      end
+
+      def code(lines)
+        untagged(lines).filter_map do |line, index|
+          body = line[INDENTED, 1]
+          [body, index] if body
+        end
+      end
+
+      # Drops the tag blocks, each running from its first tag to the
+      # next blank comment line.
+      def untagged(lines)
+        tagged = false
+        lines.reject do |line, _|
+          tagged = true if line.match?(TAG)
+          tagged &&= !line.match?(BLANK)
+        end
+      end
+
+      # The method a doc comment sits above, for naming the example.
+      def name(following)
+        code = Array(following).map(&:first).find { |line| !line.strip.empty? }
+        match = code&.match(DEFINITION)
+        return "the examples" unless match
+
+        "#{match[1] ? '.' : '#'}#{match[2]}"
+      end
+    end
+  end
+end

data/spec/support/doc_examples/markdown.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module DocExamples
+  # The examples in the fenced Ruby blocks in the README.
+  #
+  # One section, from a heading to the next, is one block. The fenced
+  # blocks under a heading share a binding, the way the README reads,
+  # where a vector set up in one paragraph is used by the next.
+  module Markdown
+    FILE = "README.md"
+    HEADING = /\A##\s+(.+)\z/
+    FENCE = /\A```/
+    RUBY_FENCE = /\A```ruby\s*\z/
+
+    class << self
+      def blocks
+        lines = File.readlines(File.join(ROOT, FILE), chomp: true)
+        sections(lines.each_with_index.to_a)
+          .filter_map { |section| block(section) }
+      end
+
+      private
+
+      def sections(lines)
+        lines.slice_before { |line, _| line.match?(HEADING) }
+      end
+
+      def block(section)
+        DocExamples.block(FILE, section.first[1] + 1, name(section),
+                          code(section))
+      end
+
+      def name(section)
+        heading = section.first[0][HEADING, 1]
+        heading ? "the #{heading} section" : "the examples"
+      end
+
+      # The lines inside the ```ruby fences, with the blank ones dropped.
+      def code(section)
+        fenced(section).reject { |line, _| line.strip.empty? }
+      end
+
+      def fenced(lines)
+        lines.slice_before { |line, _| line.match?(FENCE) }
+             .select { |chunk| chunk.first[0].match?(RUBY_FENCE) }
+             .flat_map { |chunk| chunk.drop(1) }
+      end
+    end
+  end
+end

data/spec/support/doc_examples.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "ripper"
+
+# Extracts the runnable examples from the documentation.
+#
+# The doc comments under lib/ and the fenced Ruby blocks in the README
+# are read the same way. Lines carrying a "# =>" marker assert on the
+# value of the expression to their left, the rest are setup, and the
+# examples in one block share a binding:
+#
+#   v = Vector2d(2, 3)
+#   v.length # => 3.6055..
+#
+# A marker on a line of its own applies to the line above it. A
+# trailing ".." stands in for any digits, and an exception class means
+# the expression is expected to raise. An example spanning several
+# lines, like a class definition, is evaluated as one expression.
+module DocExamples
+  ROOT = File.expand_path("../..", __dir__)
+  MARKER = /\A(.*?)\s*#\s*=>\s*(.+)\z/
+  EXCEPTION = /\A(?:[A-Z]\w*::)*[A-Z]\w*Error\z/
+  HASH_ROCKET = /:(\w+)=>/
+
+  # A single line of an example. Setup lines have no expectation.
+  Example = Struct.new(:location, :code, :expected) do
+    def expectation? = !expected.nil?
+
+    # Appends a line to an example that is not a complete expression yet.
+    def continue(line, expected)
+      self.code = "#{code}\n#{line}"
+      self.expected = expected
+    end
+
+    def raises? = expected.match?(EXCEPTION)
+
+    def exception = Object.const_get(expected)
+
+    def pattern
+      escaped = Regexp.escape(normalize(expected))
+      Regexp.new("\\A#{escaped.gsub('\.\.') { '\d*' }}\\z")
+    end
+
+    def inspected(value) = normalize(value.inspect)
+
+    private
+
+    # Values are compared with whitespace removed, so the documentation
+    # is free to align the markers, and with hashes in the {key: value}
+    # form Ruby 3.4 and up print.
+    def normalize(inspected)
+      inspected.delete(" ").gsub(HASH_ROCKET) { "#{Regexp.last_match(1)}:" }
+    end
+  end
+
+  # The examples from a single doc comment or README section.
+  Block = Struct.new(:file, :line, :name, :examples)
+
+  class << self
+    def blocks = Comments.blocks + Markdown.blocks
+
+    # A block built from its code lines, or nil if none of them assert
+    # on anything.
+    def block(file, line, name, lines)
+      examples = examples(file, lines)
+      return unless examples.any?(&:expectation?)
+
+      Block.new(file, line, name, examples)
+    end
+
+    private
+
+    def examples(file, lines)
+      lines.each_with_object([]) do |(body, index), found|
+        append(found, "#{file}:#{index + 1}", body)
+      end
+    end
+
+    def append(found, location, body)
+      expression, expected = body.match(MARKER)&.captures
+      if expected && expression.empty?
+        found.last.expected = expected
+      elsif continues?(found.last)
+        found.last.continue(expression || body, expected)
+      else
+        found << Example.new(location, expression || body, expected)
+      end
+    end
+
+    def continues?(example) = example && !complete?(example.code)
+
+    def complete?(code) = !Ripper.sexp(code).nil?
+  end
+end

data/spec/support/doc_tags.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "yard"
+
+# The type vocabulary the doc tags are written in.
+#
+# YARD tags are the only place a type is declared, so a union that
+# loses a member in one comment is a silent error. These are the
+# canonical spellings, and the checks below hold every tag to them.
+module DocTags
+  ROOT = File.expand_path("../..", __dir__)
+
+  # Coordinates are the concrete real classes. Numeric is wrong: to_i,
+  # to_f and nan? are defined on these four, not on Numeric.
+  COORDINATE = %w[Integer Float Rational BigDecimal].freeze
+
+  # Everything Vector2d.parse accepts, written out once in the
+  # +coercible+ macro in lib/vector2d.rb.
+  COERCIBLE = %w[Vector2d Array String Hash Integer Float Rational
+                 BigDecimal ::Vector ::Matrix].freeze
+
+  # The members of the parse union that are not coordinates. Naming
+  # two of them is what marks a parameter as taking the whole union.
+  SHAPES = %w[Vector2d Array String Hash ::Vector ::Matrix].freeze
+
+  # Numeric spans Complex, which is not a coordinate, and misses the
+  # methods the coordinate types are used for.
+  FORBIDDEN = %w[Numeric].freeze
+  TYPE_NAME = /(?:::)?[A-Z]\w*/
+  TAG = /\A\s*#\s@/
+  DEPRECATED = /\A\s*#\s@deprecated\b/
+  CONTINUATION = /\A\s*#\s{2,}\S/
+  COMMENT = /\A\s*#(?:\s|\z)/
+
+  # One tag, with its type list flattened to the names it mentions.
+  Tag = Struct.new(:path, :kind, :name, :types) do
+    def to_s = [path, "@#{kind}", name].compact.join(" ")
+
+    def count(union) = (union & types).size
+
+    def missing(union) = union - types
+  end
+
+  class << self
+    def methods
+      load_registry
+      YARD::Registry.all(:method)
+                    .select { |m| m.visibility == :public }
+                    .sort_by(&:path)
+    end
+
+    # Every parameter the method takes, keywords included.
+    def parameters(method)
+      method.parameters.map { |name, _| name.to_s.delete("*&:") }
+            .reject(&:empty?)
+    end
+
+    # The parameters with no @param, counting the ones inside an
+    # @overload.
+    def undocumented_parameters(method)
+      documented = method.tags(:param) +
+                   method.tags(:overload).flat_map { |o| o.tags(:param) }
+      parameters(method) - documented.map(&:name)
+    end
+
+    def tags(method)
+      collect(method, method) +
+        method.tags(:overload).flat_map { |o| collect(method, o) }
+    end
+
+    # The tags naming more than one coordinate type, which have to
+    # name all four. One on its own is a type in its own right, as the
+    # Integer #ceil rounds to is.
+    def coordinate_tags(method)
+      tags(method).select { |tag| tag.count(COORDINATE) > 1 }
+    end
+
+    # The tags taking anything Vector2d.parse accepts, which have to
+    # name the whole union.
+    def parse_union_tags(method)
+      tags(method).select do |tag|
+        tag.kind == :param && tag.count(SHAPES) > 1
+      end
+    end
+
+    # Methods warning about their own deprecation without saying so in
+    # a tag.
+    def untagged_deprecations
+      load_registry
+      YARD::Registry.all(:method).select do |method|
+        method.name != :warn_deprecated &&
+          method.source.to_s.include?("warn_deprecated") &&
+          method.tag(:deprecated).nil?
+      end.map(&:path)
+    end
+
+    # Comment lines that come after the tag block of their doc
+    # comment. Tags close a comment, and the example extractor reads
+    # them as running to the end of it, so prose after them would go
+    # missing and type lists before them would be read as code.
+    # @deprecated is the exception, and opens a comment.
+    def prose_after_tags
+      sources.flat_map do |file, lines|
+        comment_blocks(lines).flat_map { |block| stray(file, block) }
+      end
+    end
+
+    private
+
+    def comment_blocks(lines)
+      lines.each_with_index.chunk { |line, _| line.match?(COMMENT) }
+           .select(&:first).map(&:last)
+    end
+
+    def stray(file, block)
+      start = block.index { |line, _| line.match?(TAG) && !line.match?(DEPRECATED) }
+      return [] unless start
+
+      block[start..]
+        .reject { |line, _| line.match?(TAG) || line.match?(CONTINUATION) }
+        .map { |_, index| "#{file}:#{index + 1}" }
+    end
+
+    def collect(method, holder)
+      %i[param return].flat_map do |kind|
+        holder.tags(kind).map do |tag|
+          Tag.new(method.path, kind, tag.name,
+                  Array(tag.types).join(",").scan(TYPE_NAME).uniq)
+        end
+      end
+    end
+
+    def sources
+      files.map { |path| [path.delete_prefix("#{ROOT}/"), File.readlines(path, chomp: true)] }
+    end
+
+    # lib/vector2d.rb first, so the macros it defines are known by the
+    # time the modules using them are parsed.
+    def files
+      Dir[File.join(ROOT, "lib/**/*.rb")].sort_by { |path| [path.count("/"), path] }
+    end
+
+    def load_registry
+      return if @loaded
+
+      YARD::Registry.clear
+      YARD.parse(files, [], YARD::Logger::ERROR)
+      @loaded = true
+    end
+  end
+end

data/spec/support/shared_examples/class_preserving_method.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples "a class preserving method" do |method, *args|
+  describe "##{method}" do
+    it "returns an instance of the receiver's class" do
+      expect(vector.public_send(method, *args))
+        .to be_an_instance_of(vector.class)
+    end
+  end
+end

data/spec/support/shared_examples/deprecated_method.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples "a deprecated method" do |name, replacement|
+  around do |example|
+    enabled = Warning[:deprecated]
+    Warning[:deprecated] = true
+    example.run
+    Warning[:deprecated] = enabled
+  end
+
+  it "warns that the method is deprecated" do
+    expect { vector }
+      .to output(/Vector2d##{name} is deprecated/).to_stderr
+  end
+
+  it "points at the replacement" do
+    expect { vector }
+      .to output(/#{Regexp.escape(replacement)}/).to_stderr
+  end
+
+  it "is silent when deprecation warnings are disabled" do
+    Warning[:deprecated] = false
+    expect { vector }.not_to output.to_stderr
+  end
+end

data/spec/support/shared_examples/parsed_vector.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples "a parsed vector" do |x, y|
+  it "receives the x property" do
+    expect(subject.x).to eq(x)
+  end
+
+  it "receives the y property" do
+    expect(subject.y).to eq(y)
+  end
+end

data/vector2d.gemspec

@@ -20,10 +20,11 @@ Gem::Specification.new do |s|
                     .map { |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.required_ruby_version = ">= 3.2.0"
+  s.required_ruby_version = ">= 3.4.0"
 
   s.metadata = {
     "bug_tracker_uri" => "https://github.com/elektronaut/vector2d/issues",
+    "changelog_uri" => "https://github.com/elektronaut/vector2d/blob/main/CHANGELOG.md",
     "documentation_uri" => "https://www.rubydoc.info/gems/vector2d",
     "rubygems_mfa_required" => "true",
     "source_code_uri" => "https://github.com/elektronaut/vector2d"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vector2d
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Inge Jørgensen
@@ -23,7 +23,7 @@ files:
 - ".release-please-manifest.json"
 - ".rubocop.yml"
 - ".tool-versions"
-- ".travis.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
@@ -32,27 +32,56 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- benchmark/vector_comparison.rb
 - lib/vector2d.rb
-- lib/vector2d/calculations.rb
-- lib/vector2d/coercions.rb
-- lib/vector2d/fitting.rb
-- lib/vector2d/properties.rb
-- lib/vector2d/transformations.rb
+- lib/vector2d/angles.rb
+- lib/vector2d/arithmetic.rb
+- lib/vector2d/comparison.rb
+- lib/vector2d/componentwise.rb
+- lib/vector2d/constructors.rb
+- lib/vector2d/conversions.rb
+- lib/vector2d/coordinates.rb
+- lib/vector2d/deprecation.rb
+- lib/vector2d/dimensions.rb
+- lib/vector2d/interpolation.rb
+- lib/vector2d/lengths.rb
+- lib/vector2d/matrix_interop.rb
+- lib/vector2d/parsing.rb
+- lib/vector2d/projection.rb
 - lib/vector2d/version.rb
 - release-please-config.json
-- spec/lib/vector2d/calculations_spec.rb
-- spec/lib/vector2d/coercions_spec.rb
-- spec/lib/vector2d/fitting_spec.rb
-- spec/lib/vector2d/properties_spec.rb
-- spec/lib/vector2d/transformations_spec.rb
+- spec/lib/vector2d/angles_spec.rb
+- spec/lib/vector2d/arithmetic_spec.rb
+- spec/lib/vector2d/comparison_spec.rb
+- spec/lib/vector2d/componentwise_spec.rb
+- spec/lib/vector2d/constructors_spec.rb
+- spec/lib/vector2d/conversions_spec.rb
+- spec/lib/vector2d/dimensions_spec.rb
+- spec/lib/vector2d/interpolation_spec.rb
+- spec/lib/vector2d/lengths_spec.rb
+- spec/lib/vector2d/matrix_interop_spec.rb
+- spec/lib/vector2d/parsing_spec.rb
+- spec/lib/vector2d/projection_spec.rb
+- spec/lib/vector2d_documentation_spec.rb
+- spec/lib/vector2d_immutability_spec.rb
 - spec/lib/vector2d_spec.rb
+- spec/lib/vector2d_subclassing_spec.rb
+- spec/lib/vector2d_tags_spec.rb
 - spec/spec_helper.rb
+- spec/support/doc_examples.rb
+- spec/support/doc_examples/comments.rb
+- spec/support/doc_examples/markdown.rb
+- spec/support/doc_tags.rb
+- spec/support/shared_examples/class_preserving_method.rb
+- spec/support/shared_examples/deprecated_method.rb
+- spec/support/shared_examples/parsed_vector.rb
 - vector2d.gemspec
 homepage: https://github.com/elektronaut/vector2d
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/elektronaut/vector2d/issues
+  changelog_uri: https://github.com/elektronaut/vector2d/blob/main/CHANGELOG.md
   documentation_uri: https://www.rubydoc.info/gems/vector2d
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/elektronaut/vector2d
@@ -63,7 +92,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/.travis.yml

@@ -1,10 +0,0 @@
-language: ruby
-sudo: false
-cache: bundler
-dist: bionic
-rvm:
-  - 2.4.5
-  - 2.6.3
-  - 2.7.1
-script:
-  - bundle exec rspec spec

data/lib/vector2d/calculations.rb

@@ -1,141 +0,0 @@
-# frozen_string_literal: true
-
-class Vector2d
-  module Calculations
-    module ClassMethods
-      # Calculates cross product of two vectors.
-      #
-      #   v1 = Vector2d(2, 1)
-      #   v2 = Vector2d(2, 3)
-      #   Vector2d.cross_product(v1, v2) # => 4
-      #
-      def cross_product(vector1, vector2)
-        (vector1.x * vector2.y) - (vector1.y * vector2.x)
-      end
-
-      # Calculates dot product of two vectors.
-      #
-      #   v1 = Vector2d(2, 1)
-      #   v2 = Vector2d(2, 3)
-      #   Vector2d.dot_product(v1, v2) # => 10
-      #
-      def dot_product(vector1, vector2)
-        (vector1.x * vector2.x) + (vector1.y * vector2.y)
-      end
-
-      # Calculates angle between two vectors in radians.
-      #
-      #   v1 = Vector2d(2, 3)
-      #   v2 = Vector2d(4, 5)
-      #   Vector2d.angle_between(v1, v2) # => 0.0867..
-      #
-      def angle_between(vector1, vector2)
-        one = vector1.normalized? ? vector1 : vector1.normalize
-        two = vector2.normalized? ? vector2 : vector2.normalize
-        Math.acos(dot_product(one, two))
-      end
-    end
-
-    # Multiplies vectors.
-    #
-    #   Vector2d(1, 2) * Vector2d(2, 3) # => Vector2d(2, 6)
-    #   Vector2d(1, 2) * 2              # => Vector2d(2, 4)
-    #
-    def *(other)
-      calculate_each(:*, other)
-    end
-
-    # Divides vectors.
-    #
-    #   Vector2d(4, 2) / Vector2d(2, 1) # => Vector2d(2, 2)
-    #   Vector2d(4, 2) / 2              # => Vector2d(2, 1)
-    #
-    def /(other)
-      calculate_each(:/, other)
-    end
-
-    # Adds vectors.
-    #
-    #   Vector2d(1, 2) + Vector2d(2, 3) # => Vector2d(3, 5)
-    #   Vector2d(1, 2) + 2              # => Vector2d(3, 4)
-    #
-    def +(other)
-      calculate_each(:+, other)
-    end
-
-    # Subtracts vectors.
-    #
-    #   Vector2d(2, 3) - Vector2d(2, 1) # => Vector2d(0, 2)
-    #   Vector2d(4, 3) - 1              # => Vector2d(3, 2)
-    #
-    def -(other)
-      calculate_each(:-, other)
-    end
-
-    # Calculates the distance between two vectors.
-    #
-    #   v1 = Vector2d(2, 3)
-    #   v2 = Vector2d(5, 6)
-    #   v1.distance(v2) # => 1.4142..
-    #
-    def distance(other)
-      Math.sqrt(squared_distance(other))
-    end
-
-    # Calculate squared distance between vectors.
-    #
-    #   v1 = Vector2d(2, 3)
-    #   v2 = Vector2d(5, 6)
-    #   v1.distance_squared(v2) # => 18
-    #
-    def squared_distance(other)
-      v, = coerce(other)
-      dx = v.x - x
-      dy = v.y - y
-      (dx * dx) + (dy * dy)
-    end
-
-    # Dot product of this vector and another vector.
-    #
-    #   v1 = Vector2d(2, 1)
-    #   v2 = Vector2d(2, 3)
-    #   v1.dot_product(v2) # => 10
-    #
-    def dot_product(other)
-      v, = coerce(other)
-      self.class.dot_product(self, v)
-    end
-
-    # Cross product of this vector and another vector.
-    #
-    #   v1 = Vector2d(2, 1)
-    #   v2 = Vector2d(2, 3)
-    #   v1.cross_product(v2) # => 4
-    #
-    def cross_product(other)
-      v, = coerce(other)
-      self.class.cross_product(self, v)
-    end
-
-    # Angle in radians between this vector and another vector.
-    #
-    #   v1 = Vector2d(2, 3)
-    #   v2 = Vector2d(4, 5)
-    #   v1.angle_between(v2) # => 0.0867..
-    #
-    def angle_between(other)
-      v, = coerce(other)
-      self.class.angle_between(self, v)
-    end
-
-    private
-
-    def calculate_each(method, other)
-      v, = coerce(other)
-      self.class.new(
-        x.send(method, v.x),
-        y.send(method, v.y)
-      )
-    end
-  end
-end