Rename Line -> Frame

Also,

Line#number -> Frame#lineno

spec/backtracer/backtrace/frame_spec.cr

@@ -0,0 +1,227 @@
+require "../../spec_helper"
+
+private def parse_frame(line)
+  Backtracer::Backtrace::Frame::Parser.parse(line)
+end
+
+private def with_frame(method, path = nil, lineno = nil, column = nil)
+  line = String.build do |io|
+    if path
+      io << path
+      io << ':' << lineno if lineno
+      io << ':' << column if column
+      io << " in '" << method << '\''
+    else
+      io << method
+    end
+  end
+  yield parse_frame(line)
+end
+
+private def with_foo_frame(
+  method = "foo_bar?",
+  path = "#{__DIR__}/foo.cr",
+  lineno = 1,
+  column = 7
+)
+  with_frame(method, path, lineno, column) do |frame|
+    yield frame
+  end
+end
+
+describe Backtracer::Backtrace::Frame do
+  describe ".parse" do
+    it "fails to parse an empty string" do
+      expect_raises(ArgumentError) { parse_frame("") }
+    end
+
+    context "when --no-debug flag is set" do
+      it "parses frame with any value as method" do
+        backtrace_line = "__crystal_main"
+
+        with_frame(backtrace_line) do |frame|
+          frame.lineno.should be_nil
+          frame.column.should be_nil
+          frame.method.should eq(backtrace_line)
+          frame.file.should be_nil
+          frame.relative_path.should be_nil
+          frame.under_src_path?.should be_false
+          frame.shard_name.should be_nil
+          frame.in_app?.should be_false
+        end
+      end
+    end
+
+    context "with ~proc signature" do
+      it "parses absolute path outside of src/ dir" do
+        backtrace_line = "~proc2Proc(Fiber, (IO::FileDescriptor | Nil))@/usr/local/Cellar/crystal/0.27.2/src/fiber.cr:72"
+
+        with_frame(backtrace_line) do |frame|
+          frame.lineno.should eq(72)
+          frame.column.should be_nil
+          frame.method.should eq("~proc2Proc(Fiber, (IO::FileDescriptor | Nil))")
+          frame.file.should eq("/usr/local/Cellar/crystal/0.27.2/src/fiber.cr")
+          frame.relative_path.should be_nil
+          frame.under_src_path?.should be_false
+          frame.shard_name.should be_nil
+          frame.in_app?.should be_false
+        end
+      end
+
+      it "parses relative path inside of lib/ dir" do
+        backtrace_line = "~procProc(HTTP::Server::Context, String)@lib/kemal/src/kemal/route.cr:11"
+
+        with_frame(backtrace_line) do |frame|
+          frame.lineno.should eq(11)
+          frame.column.should be_nil
+          frame.method.should eq("~procProc(HTTP::Server::Context, String)")
+          frame.file.should eq("lib/kemal/src/kemal/route.cr")
+          frame.relative_path.should eq("lib/kemal/src/kemal/route.cr")
+          frame.under_src_path?.should be_false
+          frame.shard_name.should eq("kemal")
+          frame.in_app?.should be_false
+        end
+      end
+    end
+
+    it "parses absolute path outside of configuration.src_path" do
+      path = "/some/absolute/path/to/foo.cr"
+
+      with_foo_frame(path: path) do |frame|
+        frame.lineno.should eq(1)
+        frame.column.should eq(7)
+        frame.method.should eq("foo_bar?")
+        frame.file.should eq(path)
+        frame.relative_path.should be_nil
+        frame.under_src_path?.should be_false
+        frame.shard_name.should be_nil
+        frame.in_app?.should be_false
+      end
+    end
+
+    context "with in_app? = false" do
+      it "parses absolute path outside of src/ dir" do
+        with_foo_frame do |frame|
+          frame.lineno.should eq(1)
+          frame.column.should eq(7)
+          frame.method.should eq("foo_bar?")
+          frame.file.should eq("#{__DIR__}/foo.cr")
+          frame.relative_path.should eq("spec/backtracer/backtrace/foo.cr")
+          frame.under_src_path?.should be_true
+          frame.shard_name.should be_nil
+          frame.in_app?.should be_false
+        end
+      end
+
+      it "parses relative path outside of src/ dir" do
+        path = "some/relative/path/to/foo.cr"
+
+        with_foo_frame(path: path) do |frame|
+          frame.lineno.should eq(1)
+          frame.column.should eq(7)
+          frame.method.should eq("foo_bar?")
+          frame.file.should eq(path)
+          frame.relative_path.should eq(path)
+          frame.under_src_path?.should be_false
+          frame.shard_name.should be_nil
+          frame.in_app?.should be_false
+        end
+      end
+    end
+
+    context "with in_app? = true" do
+      it "parses absolute path inside of src/ dir" do
+        src_path = File.expand_path("../../../src", __DIR__)
+        path = "#{src_path}/foo.cr"
+
+        with_foo_frame(path: path) do |frame|
+          frame.lineno.should eq(1)
+          frame.column.should eq(7)
+          frame.method.should eq("foo_bar?")
+          frame.file.should eq(path)
+          frame.relative_path.should eq("src/foo.cr")
+          frame.under_src_path?.should be_true
+          frame.shard_name.should be_nil
+          frame.in_app?.should be_true
+        end
+      end
+
+      it "parses relative path inside of src/ dir" do
+        path = "src/foo.cr"
+
+        with_foo_frame(path: path) do |frame|
+          frame.lineno.should eq(1)
+          frame.column.should eq(7)
+          frame.method.should eq("foo_bar?")
+          frame.file.should eq(path)
+          frame.relative_path.should eq(path)
+          frame.under_src_path?.should be_false
+          frame.shard_name.should be_nil
+          frame.in_app?.should be_true
+        end
+      end
+    end
+
+    context "with shard path" do
+      it "parses absolute path inside of lib/ dir" do
+        lib_path = File.expand_path("../../../lib/bar", __DIR__)
+        path = "#{lib_path}/src/bar.cr"
+
+        with_foo_frame(path: path) do |frame|
+          frame.lineno.should eq(1)
+          frame.column.should eq(7)
+          frame.method.should eq("foo_bar?")
+          frame.file.should eq(path)
+          frame.relative_path.should eq("lib/bar/src/bar.cr")
+          frame.under_src_path?.should be_true
+          frame.shard_name.should eq "bar"
+          frame.in_app?.should be_false
+        end
+      end
+
+      it "parses relative path inside of lib/ dir" do
+        path = "lib/bar/src/bar.cr"
+
+        with_foo_frame(path: path) do |frame|
+          frame.lineno.should eq(1)
+          frame.column.should eq(7)
+          frame.method.should eq("foo_bar?")
+          frame.file.should eq(path)
+          frame.relative_path.should eq(path)
+          frame.under_src_path?.should be_false
+          frame.shard_name.should eq "bar"
+          frame.in_app?.should be_false
+        end
+      end
+
+      it "uses only folders for shard names" do
+        with_foo_frame(path: "lib/bar.cr") do |frame|
+          frame.shard_name.should be_nil
+        end
+      end
+    end
+  end
+
+  it "#inspect" do
+    with_foo_frame do |frame|
+      frame.inspect.should match(/Backtrace::Frame(.*)$/)
+    end
+  end
+
+  it "#to_s" do
+    with_foo_frame do |frame|
+      frame.to_s.should eq "`foo_bar?` at #{__DIR__}/foo.cr:1:7"
+    end
+  end
+
+  it "#==" do
+    with_foo_frame do |frame|
+      with_foo_frame do |frame2|
+        frame.should eq(frame2)
+      end
+      with_foo_frame(method: "other_method") do |frame2|
+        frame.should_not eq(frame2)
+      end
+    end
+  end
+end

spec/backtracer/backtrace/line_spec.cr

@@ -1,199 +0,0 @@
-require "../../spec_helper"
-
-private def with_line(
-  path = "#{__DIR__}/foo.cr",
-  method = "foo_bar?",
-  line = 1,
-  column = 7
-)
-  line = "#{path}#{line && ":#{line}"}#{column && ":#{column}"} in '#{method}'"
-  yield Backtracer::Backtrace::Line::Parser.parse(line)
-end
-
-describe Backtracer::Backtrace::Line do
-  describe ".parse" do
-    it "fails to parse an empty string" do
-      expect_raises(ArgumentError) { Backtracer::Backtrace::Line::Parser.parse("") }
-    end
-
-    context "when --no-debug flag is set" do
-      it "parses line with any value as method" do
-        backtrace_line = "__crystal_main"
-        line = Backtracer::Backtrace::Line::Parser.parse(backtrace_line)
-
-        line.number.should be_nil
-        line.column.should be_nil
-        line.method.should eq(backtrace_line)
-        line.file.should be_nil
-        line.relative_path.should be_nil
-        line.under_src_path?.should be_false
-        line.shard_name.should be_nil
-        line.in_app?.should be_false
-      end
-    end
-
-    context "with ~proc signature" do
-      it "parses absolute path outside of src/ dir" do
-        backtrace_line = "~proc2Proc(Fiber, (IO::FileDescriptor | Nil))@/usr/local/Cellar/crystal/0.27.2/src/fiber.cr:72"
-        line = Backtracer::Backtrace::Line::Parser.parse(backtrace_line)
-
-        line.number.should eq(72)
-        line.column.should be_nil
-        line.method.should eq("~proc2Proc(Fiber, (IO::FileDescriptor | Nil))")
-        line.file.should eq("/usr/local/Cellar/crystal/0.27.2/src/fiber.cr")
-        line.relative_path.should be_nil
-        line.under_src_path?.should be_false
-        line.shard_name.should be_nil
-        line.in_app?.should be_false
-      end
-
-      it "parses relative path inside of lib/ dir" do
-        backtrace_line = "~procProc(HTTP::Server::Context, String)@lib/kemal/src/kemal/route.cr:11"
-        line = Backtracer::Backtrace::Line::Parser.parse(backtrace_line)
-
-        line.number.should eq(11)
-        line.column.should be_nil
-        line.method.should eq("~procProc(HTTP::Server::Context, String)")
-        line.file.should eq("lib/kemal/src/kemal/route.cr")
-        line.relative_path.should eq("lib/kemal/src/kemal/route.cr")
-        line.under_src_path?.should be_false
-        line.shard_name.should eq("kemal")
-        line.in_app?.should be_false
-      end
-    end
-
-    it "parses absolute path outside of configuration.src_path" do
-      path = "/some/absolute/path/to/foo.cr"
-      with_line(path: path) do |line|
-        line.number.should eq(1)
-        line.column.should eq(7)
-        line.method.should eq("foo_bar?")
-        line.file.should eq(path)
-        line.relative_path.should be_nil
-        line.under_src_path?.should be_false
-        line.shard_name.should be_nil
-        line.in_app?.should be_false
-      end
-    end
-
-    context "with in_app? = false" do
-      it "parses absolute path outside of src/ dir" do
-        with_line do |line|
-          line.number.should eq(1)
-          line.column.should eq(7)
-          line.method.should eq("foo_bar?")
-          line.file.should eq("#{__DIR__}/foo.cr")
-          line.relative_path.should eq("spec/backtracer/backtrace/foo.cr")
-          line.under_src_path?.should be_true
-          line.shard_name.should be_nil
-          line.in_app?.should be_false
-        end
-      end
-
-      it "parses relative path outside of src/ dir" do
-        path = "some/relative/path/to/foo.cr"
-        with_line(path: path) do |line|
-          line.number.should eq(1)
-          line.column.should eq(7)
-          line.method.should eq("foo_bar?")
-          line.file.should eq(path)
-          line.relative_path.should eq(path)
-          line.under_src_path?.should be_false
-          line.shard_name.should be_nil
-          line.in_app?.should be_false
-        end
-      end
-    end
-
-    context "with in_app? = true" do
-      it "parses absolute path inside of src/ dir" do
-        src_path = File.expand_path("../../../src", __DIR__)
-        path = "#{src_path}/foo.cr"
-        with_line(path: path) do |line|
-          line.number.should eq(1)
-          line.column.should eq(7)
-          line.method.should eq("foo_bar?")
-          line.file.should eq(path)
-          line.relative_path.should eq("src/foo.cr")
-          line.under_src_path?.should be_true
-          line.shard_name.should be_nil
-          line.in_app?.should be_true
-        end
-      end
-
-      it "parses relative path inside of src/ dir" do
-        path = "src/foo.cr"
-        with_line(path: path) do |line|
-          line.number.should eq(1)
-          line.column.should eq(7)
-          line.method.should eq("foo_bar?")
-          line.file.should eq(path)
-          line.relative_path.should eq(path)
-          line.under_src_path?.should be_false
-          line.shard_name.should be_nil
-          line.in_app?.should be_true
-        end
-      end
-    end
-
-    context "with shard path" do
-      it "parses absolute path inside of lib/ dir" do
-        lib_path = File.expand_path("../../../lib/bar", __DIR__)
-        path = "#{lib_path}/src/bar.cr"
-        with_line(path: path) do |line|
-          line.number.should eq(1)
-          line.column.should eq(7)
-          line.method.should eq("foo_bar?")
-          line.file.should eq(path)
-          line.relative_path.should eq("lib/bar/src/bar.cr")
-          line.under_src_path?.should be_true
-          line.shard_name.should eq "bar"
-          line.in_app?.should be_false
-        end
-      end
-
-      it "parses relative path inside of lib/ dir" do
-        path = "lib/bar/src/bar.cr"
-        with_line(path: path) do |line|
-          line.number.should eq(1)
-          line.column.should eq(7)
-          line.method.should eq("foo_bar?")
-          line.file.should eq(path)
-          line.relative_path.should eq(path)
-          line.under_src_path?.should be_false
-          line.shard_name.should eq "bar"
-          line.in_app?.should be_false
-        end
-      end
-
-      it "uses only folders for shard names" do
-        with_line(path: "lib/bar.cr") do |line|
-          line.shard_name.should be_nil
-        end
-      end
-    end
-  end
-
-  it "#inspect" do
-    with_line do |line|
-      line.inspect.should match(/Backtrace::Line(.*)$/)
-    end
-  end
-
-  it "#to_s" do
-    with_line do |line|
-      line.to_s.should eq "`foo_bar?` at #{__DIR__}/foo.cr:1:7"
-    end
-  end
-
-  it "#==" do
-    with_line do |line|
-      with_line do |line2|
-        line.should eq(line2)
-      end
-      with_line(method: "other_method") do |line2|
-        line.should_not eq(line2)
-      end
-    end
-  end
-end

spec/backtracer/backtrace_spec.cr

@@ -3,8 +3,8 @@ require "../spec_helper"
 describe Backtracer::Backtrace do
   backtrace = Backtracer.parse(caller)
 
-  it "#lines" do
+  it "#frames" do
-    backtrace.lines.should be_a(Array(Backtracer::Backtrace::Line))
+    backtrace.frames.should be_a(Array(Backtracer::Backtrace::Frame))
   end
 
   it "#inspect" do
@@ -18,7 +18,7 @@ describe Backtracer::Backtrace do
   {% end %}
 
   it "#==" do
-    backtrace2 = Backtracer::Backtrace.new(backtrace.lines)
+    backtrace2 = Backtracer::Backtrace.new(backtrace.frames)
     backtrace2.should eq(backtrace)
   end
 end

src/backtracer/backtrace.cr

@@ -1,19 +1,19 @@
 module Backtracer
   class Backtrace
-    getter lines : Array(Line)
+    getter frames : Array(Frame)
 
-    def initialize(@lines = [] of Line)
+    def initialize(@frames = [] of Frame)
     end
 
-    def_equals_and_hash @lines
+    def_equals_and_hash @frames
 
     def to_s(io : IO) : Nil
-      @lines.join(io, '\n')
+      @frames.join(io, '\n')
     end
 
     def inspect(io : IO) : Nil
       io << "#<Backtrace: "
-      @lines.join(io, ", ", &.inspect(io))
+      @frames.join(io, ", ", &.inspect(io))
       io << '>'
     end
   end

src/backtracer/backtrace/frame.cr

@@ -1,38 +1,38 @@
 module Backtracer
-  # Handles backtrace parsing line by line
+  # An object representation of a stack frame.
-  struct Backtrace::Line
+  struct Backtrace::Frame
-    # The method of the line (such as `User.find`).
+    # The method of the frame (such as `User.find`).
     getter method : String
 
-    # The file portion of the line (such as `app/models/user.cr`).
+    # The file portion of the frame (such as `app/models/user.cr`).
     getter file : String?
 
-    # The line number portion of the line.
+    # The line number portion of the frame.
-    getter number : Int32?
+    getter lineno : Int32?
 
-    # The column number portion of the line.
+    # The column number portion of the frame.
     getter column : Int32?
 
     protected getter(configuration) { Backtracer.configuration }
 
-    def initialize(@method, @file = nil, @number = nil, @column = nil, *,
+    def initialize(@method, @file = nil, @lineno = nil, @column = nil, *,
                    @configuration = nil)
     end
 
-    def_equals_and_hash @method, @file, @number, @column
+    def_equals_and_hash @method, @file, @lineno, @column
 
-    # Reconstructs the line in a readable fashion
+    # Reconstructs the frame in a readable fashion
     def to_s(io : IO) : Nil
       io << '`' << @method << '`'
       if @file
         io << " at " << @file
-        io << ':' << @number if @number
+        io << ':' << @lineno if @lineno
         io << ':' << @column if @column
       end
     end
 
     def inspect(io : IO) : Nil
-      io << "Backtrace::Line("
+      io << "Backtrace::Frame("
       to_s(io)
       io << ')'
     end
@@ -73,7 +73,7 @@ module Backtracer
       context_lines ||= configuration.context_lines
 
       return unless context_lines && (context_lines > 0)
-      return unless (lineno = @number) && (lineno > 0)
+      return unless (lineno = @lineno) && (lineno > 0)
       return unless (filename = @file) && File.readable?(filename)
 
       lines = File.read_lines(filename)
@@ -88,7 +88,7 @@ module Backtracer
 
     def context_hash(context_lines : Int32? = nil) : Hash(Int32, String)?
       return unless context = self.context(context_lines)
-      return unless lineno = self.number
+      return unless lineno = self.lineno
 
       pre_context, context_line, post_context = context
 

src/backtracer/backtrace/frame/parser.cr

@@ -1,26 +1,26 @@
 module Backtracer
-  module Backtrace::Line::Parser
+  module Backtrace::Frame::Parser
     extend self
 
     # Parses a single line of a given backtrace, where *unparsed_line* is
     # the raw line from `caller` or some backtrace.
     #
-    # Returns the parsed backtrace line on success or `nil` otherwise.
+    # Returns the parsed backtrace frame on success or `nil` otherwise.
-    def parse?(line : String, **options) : Backtrace::Line?
+    def parse?(line : String, **options) : Backtrace::Frame?
       return unless Configuration::LINE_PATTERNS.any? &.match(line)
 
       method = $~["method"]?.presence
       file = $~["file"]?.presence
-      number = $~["line"]?.try(&.to_i?)
+      lineno = $~["line"]?.try(&.to_i?)
       column = $~["col"]?.try(&.to_i?)
 
       return unless method
 
-      Backtrace::Line.new method, file, number, column,
+      Backtrace::Frame.new method, file, lineno, column,
         configuration: options[:configuration]?
     end
 
-    def parse(line : String, **options) : Backtrace::Line
+    def parse(line : String, **options) : Backtrace::Frame
       parse?(line, **options) ||
         raise ArgumentError.new("Error parsing line: #{line.inspect}")
     end

src/backtracer/backtrace/parser.cr

@@ -11,13 +11,16 @@ module Backtracer
       end
 
       lines = backtrace.compact_map do |line|
-        line = filters.reduce(line) do |nested_line, filter|
+        filters.reduce(line) do |nested_line, filter|
           filter.call(nested_line) || break
         end
-        Line::Parser.parse(line, configuration: configuration) if line
       end
 
-      Backtrace.new(lines)
+      frames = lines.map do |line|
+        Frame::Parser.parse(line, configuration: configuration)
+      end
+
+      Backtrace.new(frames)
     end
 
     def parse(backtrace : String, **options) : Backtrace

src/backtracer/configuration.cr

@@ -61,7 +61,7 @@ module Backtracer
     # to set this to something like `/(src|engines)/`
     property app_dirs_pattern = /src/
 
-    # `Regex` pattern matched against `Backtrace::Line#file`.
+    # `Regex` pattern matched against `Backtrace::Frame#file`.
     property in_app_pattern : Regex { /^(#{src_path}\/)?(#{app_dirs_pattern})/ }
 
     # Path pattern matching directories to be recognized as your app modules.