[FEATURE] Chronicles API

Chronicles module describes the API of the gem.

== Addons

* Chronicles#chronicles
* Chronicles#start_chronicles
* Chronicles#stop_chronicles

lib/chronicles.rb

@@ -8,4 +8,73 @@
 # The module adds features to keep chronicles of object's methods calls
 module Chronicles
 
+  # @!attribute [r] chronicles
+  # Returns the array of object methods having been called
+  #
+  # @return [Array<Symbol>]
+  def chronicles
+    @chronicles ||= []
+  end
+
+  # Starts registation of calls of the selected methods of the object
+  #
+  # @example
+  #   class Test
+  #     include Chronicles
+  #   end
+  #
+  #   test = Test.new
+  #   test.start_chronicles only: :foo
+  #   test.foo
+  #   test.bar
+  #   test.baz
+  #   test.foo
+  #   test.chronicles # => [:foo, :foo]
+  #
+  # @param [Hash] options
+  #   describes the selection of methods to include to chronicles
+  # @option options [Boolean] :public (true)
+  #   whether public methods should be looked after
+  # @option options [Boolean] :protected (true)
+  #   whether protected methods should be looked after
+  # @option options [Boolean] :private (true)
+  #   whether private methods should be looked after
+  # @option options [Array<#to_sym>] :except ([])
+  #   the whitelist of methods that shouldn't be looked after
+  # @option options [Array<#to_sym>] :only ([])
+  #   the whitelist of methods that should be looked after
+  #
+  # @return [undefined]
+  def start_chronicles(**options)
+    Injector.new(self, "chronicles << __method__", options).run
+  end
+
+  # Stops registation of calls of the selected methods of the object
+  #
+  # @example
+  #   class Test
+  #     include Chronicles
+  #   end
+  #
+  #   test = Test.new
+  #   test.start_chronicles
+  #   test.foo
+  #   test.bar
+  #   test.baz
+  #   test.chronicles # => [:foo, :bar, :baz]
+  #
+  #   test.stop_chronicles except: :foo
+  #   test.foo
+  #   test.bar
+  #   test.baz
+  #   test.chronicles # => [:foo, :bar, :baz, :foo]
+  #
+  # @param  (see #start_chronicles)
+  # @option (see #start_chronicles)
+  #
+  # @return [undefined]
+  def stop_chronicles(**options)
+    Injector.new(self, options).run
+  end
+
 end # module Chronicles

spec/tests/chronicles_spec.rb

@@ -0,0 +1,197 @@
+# encoding: utf-8
+
+describe Chronicles do
+
+  let(:test_class) do
+    Class.new do
+      include Chronicles
+
+      attr_reader :foo
+
+      protected
+
+      attr_reader :bar
+
+      private
+
+      attr_reader :baz
+    end
+  end
+
+  subject { test_class.new }
+
+  describe "#chronicles" do
+
+    it "returns an empty array" do
+      expect(subject.chronicles).to eq []
+    end
+
+  end # describe #chronicles
+
+  describe "#start_chronicles" do
+
+    context "by default" do
+
+      before do
+        subject.start_chronicles
+        %i(foo bar baz foo).each(&subject.method(:send))
+      end
+
+      it "starts looking for all methods" do
+        expect(subject.chronicles).to eq %i(foo bar baz foo)
+      end
+
+    end # context
+
+    context "public: false" do
+
+      before do
+        subject.start_chronicles public: false
+        %i(foo bar baz foo).each(&subject.method(:send))
+      end
+
+      it "starts looking for proper methods" do
+        expect(subject.chronicles).to eq %i(bar baz)
+      end
+
+    end # context
+
+    context "protected: false" do
+
+      before do
+        subject.start_chronicles protected: false
+        %i(foo bar baz foo).each(&subject.method(:send))
+      end
+
+      it "starts looking for proper methods" do
+        expect(subject.chronicles).to eq %i(foo baz foo)
+      end
+
+    end # context
+
+    context "private: false" do
+
+      before do
+        subject.start_chronicles private: false
+        %i(foo bar baz foo).each(&subject.method(:send))
+      end
+
+      it "starts looking for proper methods" do
+        expect(subject.chronicles).to eq %i(foo bar foo)
+      end
+
+    end # context
+
+    context "except: foo" do
+
+      before do
+        subject.start_chronicles except: :foo
+        %i(foo bar baz foo).each(&subject.method(:send))
+      end
+
+      it "starts looking for proper methods" do
+        expect(subject.chronicles).to eq %i(bar baz)
+      end
+
+    end # context
+
+    context "only: foo" do
+
+      before do
+        subject.start_chronicles only: :foo
+        %i(foo bar baz foo).each(&subject.method(:send))
+      end
+
+      it "starts looking for proper methods" do
+        expect(subject.chronicles).to eq %i(foo foo)
+      end
+
+    end # context
+
+  end # describe #start_chronicles
+
+  describe "#stop_chronicles" do
+
+    before { subject.start_chronicles }
+
+    context "by default" do
+
+      before do
+        subject.stop_chronicles
+        %i(foo bar baz foo).each(&subject.method(:send))
+      end
+
+      it "stops looking for all methods" do
+        expect(subject.chronicles).to eq []
+      end
+
+    end # context
+
+    context "public: false" do
+
+      before do
+        subject.stop_chronicles public: false
+        %i(foo bar baz foo).each(&subject.method(:send))
+      end
+
+      it "stops looking for proper methods" do
+        expect(subject.chronicles).to eq %i(foo foo)
+      end
+
+    end # context
+
+    context "protected: false" do
+
+      before do
+        subject.stop_chronicles protected: false
+        %i(foo bar baz foo).each(&subject.method(:send))
+      end
+
+      it "stops looking for proper methods" do
+        expect(subject.chronicles).to eq %i(bar)
+      end
+
+    end # context
+
+    context "private: false" do
+
+      before do
+        subject.stop_chronicles private: false
+        %i(foo bar baz foo).each(&subject.method(:send))
+      end
+
+      it "stops looking for proper methods" do
+        expect(subject.chronicles).to eq %i(baz)
+      end
+
+    end # context
+
+    context "except: foo" do
+
+      before do
+        subject.stop_chronicles except: :foo
+        %i(foo bar baz foo).each(&subject.method(:send))
+      end
+
+      it "stops looking for proper methods" do
+        expect(subject.chronicles).to eq %i(foo foo)
+      end
+
+    end # context
+
+    context "only: foo" do
+
+      before do
+        subject.stop_chronicles only: :foo
+        %i(foo bar baz foo).each(&subject.method(:send))
+      end
+
+      it "stops looking for proper methods" do
+        expect(subject.chronicles).to eq %i(bar baz)
+      end
+
+    end # context
+
+  end # describe #stop_chronicles
+
+end # describe Chronicles