rake-commander 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 79568da769a6523e7024fa641eb8d792b2fd4dfcc600f11f0cbf56e6bb1f45d9
+  data.tar.gz: e8e55e77085b67e37fd9befdb1b0b77cd0f8403ff1c0ab939160c3659c0cd67f
+SHA512:
+  metadata.gz: fe77e58170a2e2bed3c9d52202e8deaa039422bda0ded1284f0d8fb316c83a6609fffb6753d2387d573b0ed70c7d5a2c74b5d868e8a89f5ba96dfa2d472b8587
+  data.tar.gz: f75fa6017995dd942cd37cc6494db0a0c9d5273eb28e1b9ef9fe7d909fa39abffc25b6aa681c05ba1dce868b2265fb0bf54f01c55a31fd4298aaf6f70f3b435c

data/.gitignore

@@ -0,0 +1,20 @@
+# it's a gem, ignore the lockfile
+Gemfile.lock
+
+# build artifacts
+*.gem
+/.bundle/
+/vendor/bundle
+/spec/reports/
+/tmp/
+/pkg/
+
+# docs
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+
+# rspec failure tracking
+.rspec_status
+scratch.rb

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,74 @@
+AllCops:
+  TargetRubyVersion: 2.7.2
+  Exclude:
+    - 'config/routes.rb'
+
+Naming/VariableNumber:
+  EnforcedStyle: snake_case
+Naming/FileName:
+  Enabled: false
+
+Metrics/LineLength:
+  Enabled: false
+Metrics/BlockLength:
+  ExcludedMethods: [context, describe]
+  Max: 50
+Metrics/MethodLength:
+  Max: 50
+Metrics/ClassLength:
+  Max: 200
+Metrics/AbcSize:
+  Max: 50
+Metrics/CyclomaticComplexity:
+  Max: 15
+Metrics/PerceivedComplexity:
+  Max: 15
+
+ParameterLists:
+  Max: 5
+  CountKeywordArgs: false
+
+Style/StringLiterals:
+  Enabled: false
+Style/FrozenStringLiteralComment:
+  Enabled: false
+Style/CommentedKeyword:
+  Enabled: false
+Style/MultilineBlockChain:
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+Style/StringLiteralsInInterpolation:
+  Enabled: false
+Style/AndOr:
+  Enabled: false
+Style/SlicingWithRange:
+  Enabled: false
+Style/ClassAndModuleChildren:
+  Enabled: false
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+Layout/SpaceInsideHashLiteralBraces:
+  Enabled: false
+Layout/SpaceInsideBlockBraces:
+  Enabled: false
+Layout/SpaceAroundOperators:
+  Enabled: false
+Layout/ExtraSpacing:
+  AllowForAlignment: true
+Layout/AccessModifierIndentation:
+  EnforcedStyle: indent
+Layout/DotPosition:
+  EnforcedStyle: trailing
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+Layout/FirstHashElementIndentation:
+  Enabled: false
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+Layout/LeadingCommentSpace:
+  Enabled: false
+
+Lint/AssignmentInCondition:
+  Enabled: false

data/.yardopts

@@ -0,0 +1,10 @@
+--readme README.md
+--charset utf-8
+--markup-provider=redcarpet
+--markup=markdown
+--no-private
+--output-dir ./doc
+'lib/**/*.rb'
+-
+CHANGELOG.md
+LICENSE

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+
+## TO DO
+  - Rake task parameters (see: https://stackoverflow.com/a/825832/4352306)
+  - `OptionParser#parse` result (what to do with unknown ARGV `leftovers`)
+
+## [0.1.2] - 2023-04-19
+
+### Added
+  - First commit
+
+### Fixed
+### Changed

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in ecoportal-api.gemspec
+gemspec

data/README.md

@@ -0,0 +1,28 @@
+# Ecoportal::API
+
+Another way to define re-usable rake tasks and samples.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rake-commander', require: %w[rake-commander]
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rake-commander
+
+## Usage
+
+
+## Development
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+For more info on available `Rake` tasks: `rake -T`

data/Rakefile

@@ -0,0 +1,32 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+require "redcarpet"
+
+desc "run the specs"
+RSpec::Core::RakeTask.new(:spec)
+
+desc "run rspec showing backtrace"
+RSpec::Core::RakeTask.new(:spec_trace) do |task|
+  task.rspec_opts = ['--backtrace']
+end
+
+desc "run rspec stopping on first fail, and show backtrace"
+RSpec::Core::RakeTask.new(:spec_fast) do |task|
+  task.rspec_opts = ['--fail-fast', '--backtrace']
+end
+
+# default task name is yard
+desc "Yard: generate all the documentation"
+YARD::Rake::YardocTask.new(:doc) do |t|
+  #t.files = ['lib/**/*.rb']
+end
+
+desc "Examples: Run examples (rake examples[basic] -- -h)"
+task :examples, [:sample] do |t, args|
+  require_relative "examples/#{args[:sample]}"
+end
+
+task default: [:spec]
+task rspec_trace: :spec_trace
+task rspec_fast: :spec_fast

data/examples/basic.rb

@@ -0,0 +1,30 @@
+require_relative File.join(__dir__, '../lib/rake-commander')
+class RakeCommander::Custom::Basic < RakeCommander
+  namespace :examples
+
+  desc 'A simple example to get started'
+  task :basic
+
+  #banner "Usage: basic:example -- [options]"
+  option '-s', '--say [SOMETHING]', "It says 'something'", default: %q(I don't know what to "say"...)
+  option :d, '--folder NAME', default: '.', desc: 'Source local folder', required: true
+  option '-e', '--enviro ENV', 'The target environment to run this task', required: true
+  option '-t', :show_time, TrueClass, desc: 'Displays the local time'
+  option :v, :debug, TrueClass, 'Shows the parsed options'
+
+  def task(*_args)
+    if options[:v]
+      puts 'We got these options:'
+      pp options
+    end
+    puts Time.now.strftime('%d %b at %H:%M') if options[:t]
+    puts options[:s] if options.key?(:s)
+  end
+end
+
+RakeCommander.self_load
+Rake::Task[:'examples:basic'].invoke
+# ruby basic.rb -- -v -d /some/folder -t
+
+#RakeCommander::Custom::Basic.parse_options %w[--help]
+#RakeCommander::Custom::Basic.parse_options %w[-d]

data/lib/rake-commander/base/class_auto_loader.rb

@@ -0,0 +1,112 @@
+class RakeCommander
+  module Base
+    # Helpers for dynamic object loading based on class declaration
+    # @note
+    #   - this helpers aim to boost the usage of the ruby language in complex api configurations.
+    module ClassAutoLoader
+      include RakeCommander::Base::ClassHelpers
+
+      # To enable the class autoloader, you should use this  method
+      def autoloads_children_of(klass)
+        class_resolver :autoloader_class, klass
+        @autoloaded_class = klass
+      end
+
+      # Resolves the class `autoloader_class` if it has been defined via `autoloads_children_of`
+      def autoloaded_class
+        return nil unless @autoloaded_class
+        autoloader_class
+      end
+
+      # To which restricted namespaces this class autoloads from
+      def autoloaded_namespaces(type = :include)
+        @autoloaded_namespaces       ||= {}
+        @autoloaded_namespaces[type] ||= []
+      end
+
+      # To restrict which namespaces it is allowed to load from
+      def autoload_namespace(*namespaces)
+        _autoload_namespace(:include, *namespaces)
+      end
+
+      # To ignore certain namespaces this class should not autoload from
+      def autoload_namespace_ignore(*namespaces)
+        _autoload_namespace(:ignore, *namespaces)
+      end
+
+      def _autoload_namespace(type, *namespaces)
+        autoloaded_namespaces(type).concat(namespaces) unless namespaces.empty?
+      end
+
+      # @param constant [Class, String] a class or namespace we want to check auto-load entitlement thereof.
+      # @return [Boolean] determines if a given namespace is entitled for autoloading
+      def autoload_class?(constant)
+        constants = constant.to_s.split("::").compact
+        autoload = true
+        unless autoloaded_namespaces(:include).empty?
+          autoload = autoloaded_namespaces(:include).any? do |ns|
+            ns.to_s.split("::").compact.zip(constants).all? {|(r, c)| r == c}
+          end
+        end
+        unless autoloaded_namespaces(:ignore).empty?
+          autoload &&= autoloaded_namespaces(:ignore).none? do |ns|
+            ns.to_s.split("::").compact.zip(constants).all? {|(r, c)| r == c}
+          end
+        end
+        autoload
+      end
+
+      # As children are loaded as they are declared, we should not load twice same children.
+      def autoloaded_children
+        @autoloaded_children ||= []
+      end
+
+      # Children classes of `autoloader_class` that have not been created an instance of.
+      def unloaded_children
+        return [] unless autoloaded_class
+        new_detected = new_classes
+        known_class!(*new_detected)
+        descendants(parent_class: autoloaded_class, scope: new_detected).select do |child_class|
+          !autoloaded_children.include?(child_class) && autoload_class?(child_class)
+        end.sort
+      end
+
+      # It loads/creates a new instance of children classes pending to be loaded.
+      # @return [Boolean] `true` if there were children loaded, `false` otherwise.
+      def autoload_children(object = nil)
+        return false if !autoloaded_class || @loading_children
+        pending_children = unloaded_children
+        return false if pending_children.empty?
+        @loading_children = true
+        pending_children.each do |klass|
+          child = object ? klass.new(object) : klass.new
+          yield(child) if block_given?
+
+        rescue TypeError
+          # Can't create from this class (must be the singleton class)
+          # Just ignore
+        ensure
+          autoloaded_children.push(klass)
+        end
+        @loading_children = false
+        true
+      end
+
+      # Known namespaces serves the purpose to discover recently added namespaces
+      #   provided that the namespace discovery is optimized
+      def known_classes
+        @known_classes ||= []
+      end
+
+      # Add to known namespaces
+      def known_class!(*classes)
+        known_classes.concat(classes)
+      end
+
+      # List all new namespaces
+      def new_classes
+        ObjectSpace.each_object(::Class).to_a - known_classes
+      end
+    end
+  end
+end

data/lib/rake-commander/base/class_helpers.rb

@@ -0,0 +1,168 @@
+class RakeCommander
+  module Base
+    module ClassHelpers
+      NOT_USED = 'no_used!'.freeze
+
+      # Helper to determine if a paramter has been used
+      # @note to effectivelly use this helper, you should initialize your target
+      #  paramters with the constant `NOT_USED`
+      # @param val [] the value of the paramter
+      # @return [Boolean] `true` if value other than `NOT_USED`, `false` otherwise
+      def used_param?(val)
+        val != NOT_USED
+      end
+
+      # Redefines constant `const` with `value` without triggering a warning.
+      def redef_without_warning(const, value)
+        self.class.send(:remove_const, const) if self.class.const_defined?(const)
+        self.class.const_set(const, value)
+      end
+
+      # Defines a class and instance method for lazy resolving a class.
+      def class_resolver(name, klass)
+        define_singleton_method(name) { resolve_class(klass) }
+        define_method(name) { self.class.resolve_class(klass) }
+      end
+
+      # Class resolver
+      # @note it caches the resolved `klass`es
+      # @raise [Exception] when could not resolve if `exception` is `true`
+      # @param klass [Class, String, Symbol] the class to resolve
+      # @param source_class [Class] when the reference to `klass` belongs to a different inheritance chain.
+      # @param exception [Boolean] if it should raise exception when could not resolve
+      # @return [Class] the `Class` constant
+      def resolve_class(klass, source_class: self, exception: true)
+        @resolved ||= {}
+        @resolved[klass] ||=
+          case klass
+          when Class
+            klass
+          when String
+            begin
+              Kernel.const_get(klass)
+            rescue NameError
+              raise if exception
+            end
+          when Symbol
+            source_class.resolve_class(source_class.send(klass))
+          when Hash
+            referrer, referred = klass.first
+            resolve_class(referred, source_class: referrer, exception: exception)
+          else
+            raise "Unknown class: #{klass}" if exception
+          end
+      end
+
+      # Helper to normalize `key` into a correct `ruby` **constant name**
+      # @note it removes namespace syntax `::`
+      # @param key [String, Symbol] to be normalized
+      # @return [String] a correct constant name
+      def to_constant(key)
+        key.to_s.strip.split(/::/).compact.map do |str|
+          str.slice(0).upcase + str.slice(1..-1)
+        end.join("").split(/[-_ :]+/i).compact.map do |str|
+          str.slice(0).upcase + str.slice(1..-1)
+        end.join("")
+      end
+
+      # Helper to create an instance variable `name`
+      # @param [String, Symbol] the name of the variable
+      # @reutrn [String] the name of the created instance variable
+      def instance_variable_name(name)
+        str = name.to_s
+        str = "@#{str}" unless str.start_with?("@")
+        str
+      end
+
+      # If the class for `name` exists, it returns it. Otherwise it generates it.
+      # @param name [String, Symbol] the name of the new class
+      # @param inherits [Class] the parent class to _inherit_ from
+      # @param namespace [Class, String] an existing `constant` (class or module) the new class will be namespaced on
+      # @yield [child_class] configure the new class
+      # @yieldparam child_class [Class] the new class
+      # @return [Class] the new generated class
+      def new_class(name = "Child#{uid}", inherits: self, namespace: inherits)
+        name            = name.to_s.to_sym.freeze
+        class_name      = to_constant(name)
+
+        unless target_class = resolve_class("#{namespace}::#{class_name}", exception: false)
+          target_class = Class.new(inherits)
+          Kernel.const_get(namespace.to_s).const_set class_name, target_class
+        end
+
+        target_class.tap do |klass|
+          yield(klass) if block_given?
+        end
+      end
+
+      # Finds all child classes of the current class.
+      # @param parent_class [Class] the parent class we want to find children of.
+      # @param direct [Boolean] it will only include direct child classes.
+      # @param scope [nil, Array] to only look for descendants among the ones in `scope`.
+      # @return [Arrary<Class>] the child classes in hierarchy order.
+      def descendants(parent_class: self, direct: false, scope: nil)
+        scope ||= ObjectSpace.each_object(::Class)
+        return [] if scope.empty?
+        scope.select do |klass|
+          klass < parent_class
+        end.sort do |k_1, k_2|
+          next -1 if k_2 < k_1
+          next  1 if k_1 < k_2
+          0
+        end.tap do |siblings|
+          if direct
+            siblings.reject! do |si|
+              siblings.any? {|s| si < s}
+            end
+          end
+        end
+      end
+
+      # @param parent_class [Class] the parent class we want to find children of.
+      # @param direct [Boolean] it will only include direct child classes.
+      # @return [Boolean] `true` if the current class has child classes, and `false` otherwise.
+      def descendants?(parent_class: self, direct: false)
+        !descendants(parent_class: parent_class, direct: direct).empty?
+      end
+
+      # Keeps track on class instance variables that should be inherited by child classes.
+      # @note
+      #   - subclasses will inherit the value as is at that moment
+      #   - any change afterwards will be only on the specific class (in line with class instance variables)
+      #   - adapted from https://stackoverflow.com/a/10729812/4352306
+      # TODO: this separates the logic of the method to the instance var. Think if would be possible to join them somehow.
+      def inheritable_class_vars(*vars)
+        @inheritable_class_vars ||= [:inheritable_class_vars]
+        @inheritable_class_vars += vars
+      end
+
+      # Builds the attr_reader and attr_writer of `attrs` and registers the associated instance variable as inheritable.
+      def inheritable_attrs(*attrs, add_accessors: false)
+        if add_accessors
+          attrs.each do |attr|
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              class << self; attr_accessor :#{attr} end
+            RUBY
+          end
+        end
+        inheritable_class_vars(*attrs)
+      end
+
+      # This callback method is called whenever a subclass of the current class is created.
+      # @note
+      #   - values of the instance variables are copied as they are (no dups or clones)
+      #   - the above means: avoid methods that change the state of the mutable object on it
+      #   - mutating methods would reflect the changes on other classes as well
+      #   - therefore, `freeze` will be called on the values that are inherited.
+      def inherited(subclass)
+        super.tap do
+          inheritable_class_vars.each do |var|
+            instance_var = instance_variable_name(var)
+            value        = instance_variable_get(instance_var)
+            subclass.instance_variable_set(instance_var, value.freeze)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rake-commander/base.rb

@@ -0,0 +1,29 @@
+require_relative 'base/class_helpers'
+require_relative 'base/class_auto_loader'
+require_relative 'rake_task'
+require_relative 'options'
+
+class RakeCommander
+  module Base
+    class << self
+      def included(base)
+        super(base)
+        base.extend RakeCommander::Base::ClassHelpers
+        base.extend RakeCommander::Base::ClassAutoLoader
+        base.autoloads_children_of RakeCommander
+
+        base.extend ClassMethods
+        base.send :include, RakeTask
+
+        base.send :include, Options
+        #autoload_namespace_ignore "RakeCommander::Samples"
+      end
+    end
+
+    module ClassMethods
+      def self_load
+        autoload_children
+      end
+    end
+  end
+end

data/lib/rake-commander/custom.rb

@@ -0,0 +1,3 @@
+# Provides a namespace to declare rake tasks classes
+module RakeCommander::Custom
+end