ronin-core 0.1.0.beta1

data/lib/ronin/core/metadata/authors/author.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Core
+    module Metadata
+      module Authors
+        class Author
+
+          # The author's name.
+          #
+          # @return [String]
+          attr_reader :name
+
+          # The author's email.
+          #
+          # @return [String, nil]
+          attr_reader :email
+
+          # The author's PGP Key ID.
+          #
+          # @return [String, nil]
+          attr_reader :pgp
+
+          # The author's website
+          #
+          # @return [String, nil]
+          attr_reader :website
+
+          # The author's blog.
+          #
+          # @return [String, nil]
+          attr_reader :blog
+
+          # The author's GitHub user name.
+          #
+          # @return [String, nil]
+          attr_reader :github
+
+          # The author's GitLab user name.
+          #
+          # @return [String, nil]
+          attr_reader :gitlab
+
+          # The author's Twitter handle.
+          #
+          # @return [String, nil]
+          attr_reader :twitter
+
+          # The author's Discord handle.
+          #
+          # @return [String, nil]
+          attr_reader :discord
+
+          #
+          # Initializes the author.
+          #
+          # @param [String] name
+          #   The author's name.
+          #
+          # @param [String, nil] email
+          #   The author's email.
+          #
+          # @param [String, nil] pgp
+          #   The author's PGP Key ID.
+          #
+          # @param [String, nil] website
+          #   The author's website.
+          #
+          # @param [String, nil] blog
+          #   The author's blog.
+          #
+          # @param [String, nil] github
+          #   The author's GitHub user name.
+          #
+          # @param [String, nil] gitlab
+          #   The author's GitLab user name.
+          #
+          # @param [String, nil] twitter
+          #   The author's Twitter handle.
+          #
+          # @param [String, nil] discord
+          #   The author's Discord handle.
+          #
+          def initialize(name, email:   nil,
+                               pgp:     nil,
+                               website: nil,
+                               blog:    nil,
+                               github:  nil,
+                               gitlab:  nil,
+                               twitter: nil,
+                               discord: nil)
+            @name  = name
+            @email = email
+            @pgp   = pgp
+
+            @website = website
+            @blog    = blog
+            @github  = github
+            @gitlab  = gitlab
+            @twitter = twitter
+            @discord = discord
+          end
+
+          #
+          # Determines if the author has an {#email} set.
+          #
+          # @return [Boolean]
+          #
+          def email?
+            @email != nil
+          end
+
+          #
+          # Determines if the author has a {#pgp} Key ID set.
+          #
+          # @return [Boolean]
+          #
+          def pgp?
+            @pgp != nil
+          end
+
+          #
+          # Determines if the author has a {#website} set.
+          #
+          # @return [Boolean]
+          #
+          def website?
+            @website != nil
+          end
+
+          #
+          # Determines if the author has a {#blog} set.
+          #
+          # @return [Boolean]
+          #
+          def blog?
+            @blog != nil
+          end
+
+          #
+          # Determines if the author has a {#github} user name set.
+          #
+          # @return [Boolean]
+          #
+          def github?
+            @github != nil
+          end
+
+          #
+          # Determines if the author has a {#gitlab} user name set.
+          #
+          # @return [Boolean]
+          #
+          def gitlab?
+            @gitlab != nil
+          end
+
+          #
+          # Determines if the author has a {#twitter} handle set.
+          #
+          # @return [Boolean]
+          #
+          def twitter?
+            @twitter != nil
+          end
+
+          #
+          # Determines if the author has a {#discord} handle set.
+          #
+          # @return [Boolean]
+          #
+          def discord?
+            @discord != nil
+          end
+
+          #
+          # Returns the URL to the author's GitHub profile.
+          #
+          # @return [String, nil]
+          #   Returns the URL to the author's GitHub profile, or `nil`
+          #   if no {#github} user name has been set.
+          #
+          def github_url
+            "https://github.com/#{@github.sub(/\A@/,'')}" if @github
+          end
+
+          #
+          # Returns the URL to the author's GitLab profile.
+          #
+          # @return [String, nil]
+          #   Returns the URL to the author's GitLab profile, or `nil`
+          #   if no {#gitlab} user name has been set.
+          #
+          def gitlab_url
+            "https://gitlab.com/#{@gitlab.sub(/\A@/,'')}" if @gitlab
+          end
+
+          #
+          # Returns the URL to the author's Twitter profile.
+          #
+          # @return [String, nil]
+          #   Returns the URL to the author's Twitter profile, or `nil`
+          #   if no {#twitter} user name has been set.
+          #
+          def twitter_url
+            "https://twitter.com/#{@twitter.sub(/\A@/,'')}" if @twitter
+          end
+
+          #
+          # Converts the author to a String.
+          #
+          # @return [String]
+          #   The author's name and/or email.
+          #
+          def to_s
+            if @email then "#{@name} <#{@email}>"
+            else           @name
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/metadata/authors.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/metadata/authors/author'
+
+module Ronin
+  module Core
+    module Metadata
+      #
+      # Adds {Authors::ClassMethods#author authors} metadata attribute to a
+      # class.
+      #
+      # ### Example
+      #
+      #     class MyModule
+      #     
+      #       include Ronin::Core::Metadata::Authors
+      #     
+      #       author 'John Doe'
+      #       author 'John Smith', email: 'john.smith@example.com'
+      #     
+      #     end
+      #
+      #     puts MyModule.authors
+      #     # John Doe
+      #     # John Smith <john.smith@example.com>
+      #
+      module Authors
+        #
+        # Adds {ClassMethods} to the class.
+        #
+        # @param [Class] base
+        #   The base class which is including {Authors}.
+        #
+        # @api private
+        #
+        def self.included(base)
+          base.extend ClassMethods
+        end
+
+        module ClassMethods
+          #
+          # The authors associated with the class.
+          #
+          # @return [Array<Authors::Author>]
+          #
+          # @api semipublic
+          #
+          def authors
+            @authors ||= if superclass.kind_of?(ClassMethods)
+                           superclass.authors.dup
+                         else
+                           []
+                         end
+          end
+
+          #
+          # Adds an author.
+          #
+          # @param [String, nil] name
+          #   The new author name to add.
+          #
+          # @param [Hash{Symbol => Object}] kwargs
+          #   Additional keyword arguments for {Author#initialize}.
+          #
+          # @option kwargs [String, nil] :email
+          #   The author's email.
+          #
+          # @option kwargs [String, nil] :pgp
+          #   The author's PGP Key ID.
+          #
+          # @option kwargs [String, nil] :website
+          #   The author's website.
+          #
+          # @option kwargs [String, nil] :blog
+          #   The author's blog.
+          #
+          # @option kwargs [String, nil] :github
+          #   The author's GitHub user name.
+          #
+          # @option kwargs [String, nil] :gitlab
+          #   The author's GitLab user name.
+          #
+          # @option kwargs [String, nil] :twitter
+          #   The author's Twitter handle.
+          #
+          # @option kwargs [String, nil] :discord
+          #   The author's Discord handle.
+          #
+          # @example Adds an author name:
+          #   author 'John Smith'
+          #
+          # @example Adds an author name and email:
+          #   author 'John Smith', email: 'john.smith@example.com'
+          #
+          # @api public
+          #
+          def author(name,**kwargs)
+            authors << Ronin::Core::Metadata::Authors::Author.new(name,**kwargs)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/metadata/description.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Core
+    module Metadata
+      #
+      # Adds a {Description::ClassMethods#description description} metadata
+      # attribute to a class.
+      #
+      # ### Example
+      #
+      #     class MyModule
+      #     
+      #       include Ronin::Core::Metadata::Description
+      #     
+      #       description <<~DESC
+      #         Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+      #         eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      #
+      #         Ut enim ad minim veniam, quis nostrud exercitation ullamco
+      #         laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure
+      #         dolor in reprehenderit in voluptate velit esse cillum dolore eu
+      #
+      #         fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+      #         proident, sunt in culpa qui officia deserunt mollit anim id est
+      #         laborum.
+      #       DESC
+      #     
+      #     end
+      #
+      module Description
+        #
+        # Adds {ClassMethods} to the class.
+        #
+        # @param [Class] base
+        #   The base class which is including {Description}.
+        #
+        # @api private
+        #
+        def self.included(base)
+          base.extend ClassMethods
+        end
+
+        module ClassMethods
+          #
+          # Gets or sets the description.
+          #
+          # @param [String, nil] new_description
+          #   The optional new description text to set.
+          #
+          # @return [String, nil]
+          #   The previously set description text.
+          #
+          # @example Setting the description:
+          #   description <<~DESC
+          #     Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+          #     eiusmod tempor incididunt ut labore et dolore magna aliqua.
+          #
+          #     Ut enim ad minim veniam, quis nostrud exercitation ullamco
+          #     laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure
+          #     dolor in reprehenderit in voluptate velit esse cillum dolore eu
+          #
+          #     fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+          #     proident, sunt in culpa qui officia deserunt mollit anim id est
+          #     laborum.
+          #   DESC
+          #
+          # @example Getting the description:
+          #   MyModule.description
+          #
+          def description(new_description=nil)
+            if new_description
+              @description = new_description
+            else
+              @description || if superclass.kind_of?(ClassMethods)
+                                superclass.description
+                              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/metadata/id.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Core
+    module Metadata
+      #
+      # Adds a {ID::ClassMethods#id id} metadata attribute to a class.
+      #
+      # ### Example
+      #
+      #     class MyClass
+      #     
+      #       include Ronin::Core::Metadata::ID
+      #
+      #       id 'my_class'
+      #
+      #     end
+      #     
+      module ID
+        #
+        # Adds {ClassMethods} to the class.
+        #
+        # @param [Class] base
+        #   The base class which is including {ID}.
+        #
+        # @private
+        #
+        def self.included(base)
+          base.extend ClassMethods
+        end
+
+        module ClassMethods
+          #
+          # Gets or sets the class `id`.
+          #
+          # @param [String, nil] new_id
+          #   The optional new class `id` to set.
+          #
+          # @return [String, nil]
+          #   The previously set class `id`.
+          #
+          # @example Setting the class `id`:
+          #   class MyClass
+          #     include Ronin::Core::Metadata::ID
+          #     id 'my_class'
+          #   end
+          #
+          # @example Getting the class `id`:
+          #   MyClass.id
+          #   # => "my_class"
+          #
+          def id(new_id=nil)
+            if new_id then @id = new_id
+            else           @id
+            end
+          end
+        end
+
+        #
+        # The {ClassMethods#id id} of the class.
+        #
+        # @return [String, nil]
+        #
+        # @see ClassMethods#id
+        #
+        def class_id
+          self.class.id
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/metadata/references.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Core
+    module Metadata
+      #
+      # Adds a {References::ClassMethods#references references} metadata
+      # attribute to a class.
+      #
+      # ### Example
+      #
+      #     class MyModule
+      #     
+      #       include Ronin::Core::Metadata::References
+      #     
+      #       references [
+      #         "https://...",
+      #         ...
+      #       ]
+      #     
+      #     end
+      #
+      module References
+        #
+        # Adds {ClassMethods} to the class.
+        #
+        # @param [Class] base
+        #   The base class which is including {References}.
+        #
+        # @api private
+        #
+        def self.included(base)
+          base.extend ClassMethods
+        end
+
+        module ClassMethods
+          #
+          # Gets or sets the reference links.
+          #
+          # @param [Array<String>, nil] new_references
+          #   The optional new reference links to set.
+          #
+          # @return [Array<String>]
+          #   The previously set reference links.
+          #
+          # @example Set the references:
+          #   references [
+          #     "https://...",
+          #     ...
+          #   ]
+          #
+          # @example Get the reference links:
+          #   MyModule.references
+          #   # => ["https://...", ...]
+          #
+          def references(new_references=nil)
+            if new_references
+              @references = references() + new_references
+            else
+              @references || if superclass.kind_of?(ClassMethods)
+                               superclass.references
+                             else
+                               []
+                             end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/metadata/summary.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Core
+    module Metadata
+      #
+      # Adds a {Summary::ClassMethods#summary summary} metadata
+      # attribute to a class.
+      #
+      # ### Example
+      #
+      #     class MyModule
+      #     
+      #       include Ronin::Core::Metadata::Summary
+      #     
+      #       summary "Lorem ipsum dolor sit amet, consectetur adipiscing elit"
+      #     
+      #     end
+      #
+      module Summary
+        #
+        # Adds {ClassMethods} to the class.
+        #
+        # @param [Class] base
+        #   The base class which is including {Summary}.
+        #
+        # @api private
+        #
+        def self.included(base)
+          base.extend ClassMethods
+        end
+
+        module ClassMethods
+          #
+          # Gets or sets the summary.
+          #
+          # @param [String, nil] new_summary
+          #   The optional new summary text to set.
+          #
+          # @return [String, nil]
+          #   The previously set summary text.
+          #
+          # @example Setting the summary:
+          #   summary "Lorem ipsum dolor sit amet, consectetur adipiscing elit" 
+          #
+          # @example Getting the summary:
+          #   MyModule.summary
+          #
+          def summary(new_summary=nil)
+            if new_summary
+              @summary = new_summary
+            else
+              @summary || if superclass.kind_of?(ClassMethods)
+                                superclass.summary
+                          end
+            end
+          end
+        end
+      end
+    end
+  end
+end