tag_ripper 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f55c43ce02431ffc69bd9284ec5875678d743e3c14544f3ebb0710e440921b8
-  data.tar.gz: 10b1baa79118d897442fd87e49ee7da2b9259172802246f22e0ea5a3b3855d72
+  metadata.gz: 2e80933d8c317438627b041b30bd905ae33ed8d993db4ef149e69f3f71fd30d7
+  data.tar.gz: 7eeb22fc466b8b50da7f6d3e887dfc02c04d0de462abf870f36bf0beda6b3a68
 SHA512:
-  metadata.gz: ab28505f7eb7784a4a90d7613960263251b43f9d8dcbca34570c360828f7c651e3b60d5e518b0d98e6722e0fc214a53e27f8280dfe3713962474c5914074fb5c
-  data.tar.gz: c38bd4b3c85a1a6b02f7fe57ab61e69ea729f031d9f6a04fd40a85e71e978c820d7577d63a060079f3309a704452b779fa994d7fca6cc09d547dbcbdbb8622af
+  metadata.gz: 131915acf06d838e8d5aa62ee92b62eab06743071298aa57fb887975cd9414b825d9929a40349bd6e4607ee5b7475eb41dc205939dc8a86d8c51856880317692
+  data.tar.gz: e7e86cc4d7984e3f05d1743d42892ee235152467a16f64edbc64cfe79d9683a5130aa013ce193084adb3348d509cc06938d78bbf5d2823efcb7a33ef61fbcf89

data/.rubocop.yml

@@ -8,7 +8,10 @@ AllCops:
   TargetRubyVersion: 3.1
   NewCops: enable
   SuggestExtensions: true
-
+  Exclude:
+    - bin/*
+    - test/fixtures/**/*  # These files have particular styles that should be preserved
+    - samples/**/*  # These files have particular styles that should be preserved
 Metrics/AbcSize:
   Exclude:
     - test/**/*
@@ -30,4 +33,3 @@ Style/TrivialAccessors:
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
-

data/.ruby-version

@@ -1 +1 @@
-3.4.2
+3.4.3

data/Guardfile

@@ -0,0 +1,12 @@
+guard :minitest, cli: "--verbose" do
+  watch(%r{^test/(.+)_test\.rb$})
+  watch(%r{^lib/(.+)\.rb$}) { |m| "test/#{m[1]}_test.rb" }
+  watch("test/test_helper.rb") { "test" }
+end
+
+guard :rubocop, all_on_start: false do
+  watch(/^.+\.rb$/)
+  watch(%r{^(config|test)/.+\.rb$})
+  watch("Gemfile")
+  watch(".rubocop.yml")
+end

data/README.md

@@ -5,27 +5,9 @@
 
 Lets you annotate Ruby code with tags that can be parsed and collected in code.
 
-Example:
-
-```ruby
-# @domain: Auth
-class User
-  # @warning: untested
-  def some_method_that_isnt_tested
-    # ...
-  end
-end
-
-TagRipper.new(File.read('user.rb')).taggables
-# => [
-# <id=22040, @name=some_method_that_isnt_tested, tags={"warning" => #<Set: {"untested"}>},parent=#<TagRipper::TaggableEntity:0x00000001203bf468>>,
-#  <id=22224, @name=User, tags={"domain" => #<Set: {"Auth"}>},parent=>nil
-# ]
-```
 
 ## Installation
 
-TODO: Replace `tag_ripper` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
 
 Install the gem and add to the application's Gemfile by executing:
 
@@ -41,7 +23,34 @@ gem install tag_ripper
 
 ## Usage
 
-TODO: Write usage instructions here
+
+```ruby
+# @domain: Auth
+class User
+  # @warning: untested
+  def some_method_that_isnt_tested
+    # ...
+  end
+end
+
+TagRipper.new(File.read('user.rb')).taggables
+# (Beautified output)
+# ---
+# - 
+#   id: 2221
+#   name: some_method_that_isnt_tested
+#   tags:
+#     warning:
+#       - "untested
+#   parent: 22224,
+# - 
+#   id: 22224
+#   name: User
+#   tags:
+#     domain: 
+#       - "Auth"
+#    parent: nil
+```
 
 ## Development
 
@@ -51,7 +60,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/bodacious/tag-ripper. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/bodacious/tag-ripper/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/bodacious/tag_ripper. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/bodacious/tag_ripper/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -59,4 +68,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Tag::Ripper project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/bodacious/tag-ripper/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Tag::Ripper project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/bodacious/tag_ripper/blob/master/CODE_OF_CONDUCT.md).

data/lib/tag_ripper/lexical_token.rb

@@ -3,8 +3,22 @@ module TagRipper
     require "forwardable"
     extend Forwardable
 
-    TAG_REGEX = /#\s@(?<tag_name>[\w_-]+):\s(?<tag_value>.+)/
-    END_TOKEN = "end".freeze
+    TAG_REGEX = /#\s@(?<tag_name>[\w-]+):\s(?<tag_value>.+)/
+
+    ##
+    # = Operators =
+
+    DOUBLE_COLON = "::".freeze
+    SINGLETON_CLASS = "<<".freeze
+
+    ##
+    # = Keywords =
+
+    KEYWORD_CONST = "const".freeze
+    KEYWORD_CLASS = "class".freeze
+    KEYWORD_DEF = "def".freeze
+    KEYWORD_END = "end".freeze
+    KEYWORD_MODULE = "module".freeze
 
     class Location
       attr_reader :col
@@ -49,12 +63,20 @@ module TagRipper
       comment? && token.match?(TAG_REGEX)
     end
 
+    def double_colon?
+      token == DOUBLE_COLON
+    end
+
+    def singleton_class?
+      token == SINGLETON_CLASS
+    end
+
     def keyword?
       type == :on_kw
     end
 
     def end?
-      keyword? && token == END_TOKEN
+      keyword? && token == KEYWORD_END
     end
 
     def tag_name
@@ -72,13 +94,10 @@ module TagRipper
     def on_kw_type
       return nil unless keyword?
 
-      case token
-      when "const" then :class
-      when "module" then :module
-      when "def" then :instance_method
-      else
-        :unknown
-      end
+      const_lookup = "KEYWORD_#{token.upcase}"
+      return :unknown unless self.class.const_defined?(const_lookup)
+
+      self.class.const_get(const_lookup).to_sym
     end
   end
 end

data/lib/tag_ripper/taggable_entity.rb

@@ -9,22 +9,43 @@ module TagRipper
   # entity is spawned. This creates a sort of recursion that allows a taggable
   # entity to be flexible to any amount of code nesting.
   class TaggableEntity
+    # Unable to move transition from one state to another
     class IllegalStateTransitionError < StandardError
       def initialize(from:, to:)
         super("Cannot transition from #{from} to #{to}")
       end
     end
 
-    def initialize(name: nil, parent: nil)
+    # Attempting to set status to an unknown value
+    class InvalidStatusError < ArgumentError; end
+
+    # TODO: define naming state, to represent a partial name token
+    # The valid statuses that a TaggableEntity can move through.
+    # @return [Array<Symbol>]
+    VALID_STATUSES = %i[
+      pending
+      tagged
+      awaiting_name
+      named
+      closed
+    ].freeze
+
+    # Statuses that represent an open lexical scope.
+    # @return [Array<Symbol>]
+    OPENED_STATUSES = %i[tagged awaiting_name named].freeze
+
+    def initialize(name: nil, parent: nil, type: nil)
       @name = name
       @tags = Hash.new { |hash, key| hash[key] = Set.new }
       @parent = parent
-      @type = nil
-      @status = :pending
+      @type = type
+      self.status = :pending
     end
 
+    alias id object_id
+
     def send_event(event_name, lex)
-      puts "send_event: #{event_name} - #{lex} #(#{@status})"
+      debug_event(event_name, lex) if ENV["DEBUG_TAG_RIPPER"]
       if respond_to?(event_name, true)
         send(event_name, lex)
       else
@@ -32,6 +53,13 @@ module TagRipper
       end
     end
 
+    def debug_event(event_name, lex)
+      puts <<~OUTPUT.chomp
+        Sending #{event_name} to #{self} with #{lex.token.inspect}
+        #{inspect}"
+      OUTPUT
+    end
+
     def module?
       (type == :module) | (type == :class)
     end
@@ -39,8 +67,11 @@ module TagRipper
     def type
       @type
     end
+
+    # The fully-qualified name of this entity (e.g. +"Foo::Bar::MyClass"+)
+    # @return [String]
     def fqn
-      return nil unless named?
+      return nil unless name?
       return name if fqn_names.size == 1
 
       if type == :instance_method
@@ -51,14 +82,10 @@ module TagRipper
     end
     alias fully_qualified_name fqn
 
-    def pending? = @status == :pending
-
-    def tagged? = @status == :tagged
-
-    def awaiting_name? = @status == :awaiting_name
-
-    OPENED_STATUSES = %i[tagged awaiting_name named].freeze
-
+    # Have we opened a new lexical scope? (e.g. evaluating within the body
+    # of a class, rather than comments before the class)
+    #
+    # @return [Boolean]
     def open?
       OPENED_STATUSES.include?(@status)
     end
@@ -68,7 +95,7 @@ module TagRipper
         raise IllegalStateTransitionError.new(from: @status, to: :tagged)
       end
 
-      @status = :tagged
+      self.status = :tagged
 
       add_tag(tag_name, tag_value)
     end
@@ -78,7 +105,11 @@ module TagRipper
         raise IllegalStateTransitionError.new(from: @status, to: :awaiting_name)
       end
 
-      @status = :awaiting_name
+      self.status = :awaiting_name
+    end
+
+    def name?
+      !!@name
     end
 
     def name=(name)
@@ -87,17 +118,19 @@ module TagRipper
       end
 
       @name = name.to_s
-      @status = :named
+      self.status = :named
     end
 
     def close!
       @open = false
-      @status = :closed
+      self.status = :closed
       freeze
     end
 
-    def closed?
-      @status == :closed
+    VALID_STATUSES.each do |status|
+      define_method(:"#{status}?") do
+        @status == status
+      end
     end
 
     def may_tag?
@@ -116,10 +149,20 @@ module TagRipper
       named?
     end
 
+    def parent_id
+      parent&.id
+    end
+
     def inspect
-      "<id=#{id},@name=#{@name},tags=#{@tags},parent=#{@parent}>"
+      exposed_properties = %i[object_id name fqn type parent_id status tags]
+      inner_string = exposed_properties.map do |property|
+        "#{property}=#{public_send(property)}"
+      end.join(", ")
+      "<#{inner_string}>"
     end
 
+    alias to_s inspect
+
     def tags
       @tags.dup
     end
@@ -128,13 +171,32 @@ module TagRipper
       @name.to_s.dup
     end
 
-    def type=(type)
-      @type = type.to_sym
+    def parent
+      @parent
+    end
+
+    def status
+      @status
     end
 
     protected
 
-    alias id object_id
+    def append_name!(string)
+      raise StandardError, "Cannot append #{string} to nil" unless @name
+
+      @name.concat(string.to_s)
+    end
+
+    def status=(status)
+      status = status.to_sym
+      raise InvalidStatusError unless VALID_STATUSES.include?(status)
+
+      @status = status
+    end
+
+    def type=(type)
+      @type = type.to_sym
+    end
 
     def fqn_names
       return [name] if parent.nil?
@@ -142,18 +204,10 @@ module TagRipper
       [*parent.fqn_names, name]
     end
 
-    def parent
-      @parent
-    end
-
     def add_tag(name, value)
       @tags[name].add(value)
     end
 
-    def named?
-      !!@name
-    end
-
     def build_child
       self.class.new(parent: self)
     end
@@ -178,11 +232,13 @@ module TagRipper
       send(event_token_method_name, lex)
     end
 
+    ##
+    # Lex is a keyword (e.g. def, class, module)
     def on_new_taggable_context_kw(lex)
       returnable_entity = named? ? build_child : self
 
       returnable_entity.await_name!
-      self.type = lex.on_kw_type
+      returnable_entity.type = lex.on_kw_type
 
       returnable_entity
     end
@@ -191,21 +247,59 @@ module TagRipper
     alias on_kw_module on_new_taggable_context_kw
     alias on_kw_class on_new_taggable_context_kw
 
-    IGNORED_IDENT_KEYWORDS = %w[require private class_eval instance_eval define_method].freeze
+    IGNORED_IDENT_KEYWORDS = %w[require private class_eval instance_eval
+                                define_method].freeze
     private_constant :IGNORED_IDENT_KEYWORDS
 
-    def name_from_lex(lex)
+    def name_from_lex(lex) # rubocop:disable Metrics
       return self if IGNORED_IDENT_KEYWORDS.include?(lex.token)
-      return self if named?
-      return self unless may_name?
+      # TODO: Simplify this logic
+      return self if named? && !@name.end_with?("::")
+      return self unless may_name? || (name? && @name.end_with?("::"))
+
+      # self.status = :awaiting_name # TODO: Fix this with a proper state
+      if named? && @name.to_s.end_with?("::")
+        append_name!(lex.token)
+      else
+        self.name = "#{name}#{lex.token}"
+      end
 
-      self.name = lex.token
       self
-    end
+    end # rubocop:enable Metrics
 
+    ##
+    # Matches names of constants: module names, const names, etc.
     alias on_const name_from_lex
+
+    ##
+    # Matches tokens like: private, method names, argument names
     alias on_ident name_from_lex
 
+    def on_op(lex)
+      if lex.double_colon?
+        append_name!(lex.token)
+      end
+
+      # return name_from_op(lex) if lex.singleton_class?
+      self
+    end
+
+    def on_kw_self(lex)
+      if module? && awaiting_name?
+        self.name = lex.token
+        return self
+      end
+
+      self
+    end
+
+    ##
+    # Name the current entity 'self' based on an operator (e.g. +class << self+)
+    def name_from_kw(lex)
+      self.name = lex.token
+      self
+    end
+
     def on_kw_end(_lex)
       close!
       parent

data/lib/tag_ripper/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TagRipper
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: tag_ripper
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Gavin Morrice
 bindir: exe
 cert_chain: []
-date: 2025-04-03 00:00:00.000000000 Z
+date: 2025-07-02 00:00:00.000000000 Z
 dependencies: []
 description: Add tags to your Ruby code comments and then Rip the as lexical tokens
 email:
@@ -21,6 +21,7 @@ files:
 - ".ruby-version"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -30,13 +31,13 @@ files:
 - lib/tag_ripper/ripper.rb
 - lib/tag_ripper/taggable_entity.rb
 - lib/tag_ripper/version.rb
-homepage: https://github.com/Bodacious/tag-ripper/
+homepage: https://github.com/Bodacious/tag_ripper/
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/Bodacious/tag-ripper/
-  source_code_uri: https://github.com/Bodacious/tag-ripper/
-  changelog_uri: https://github.com/Bodacious/tag-ripper/
+  homepage_uri: https://github.com/Bodacious/tag_ripper/
+  source_code_uri: https://github.com/Bodacious/tag_ripper/
+  changelog_uri: https://github.com/Bodacious/tag_ripper/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: