kangaru 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 04e8f14e4f41534168d56fdc09364a9507553658887f513a1536fe71f6a9c608
+  data.tar.gz: 3af9ce12c3a133964cf66393f0d93339c37ae5329c3bd3ddcd65f53e1f224a28
+SHA512:
+  metadata.gz: 6c9ee4ea2cf630d10e52d9a0a549f0ce77c5751c0469ca523baa91e15aa7eaa2e479e6120a683ad6cfb7aed8a6987cd7209d11a51a1503daa4910721718df1d8
+  data.tar.gz: d7c959405a39a4086409f8e1a739643502ef102b662728dc1859e9bc3f8195cc576b9ee81f93135536141dbbd438e37047be08e1f15048fa18d7a32f1887a883

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--color

data/.rubocop.yml

@@ -0,0 +1,75 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Layout/ExtraSpacing:
+  AllowForAlignment: true
+Layout/LineLength:
+  Max: 80
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+
+Lint/AmbiguousBlockAssociation:
+  AllowedMethods:
+    - change
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - spec/spec_helper.rb
+Lint/MissingSuper:
+  Enabled: false
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - by
+    - to
+    - id
+
+Style/ArgumentsForwarding:
+  Enabled: false
+Style/CharacterLiteral:
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+Style/ExplicitBlockArgument:
+  Enabled: false
+Style/FormatStringToken:
+  EnforcedStyle: template
+Style/FrozenStringLiteralComment:
+  Enabled: false
+Style/RescueStandardError:
+  EnforcedStyle: implicit
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+RSpec/AnyInstance:
+  Enabled: false
+RSpec/ContextWording:
+  Prefixes:
+    - when
+    - with
+    - without
+    - if
+    - unless
+    - and
+    - but
+RSpec/DescribedClass:
+  SkipBlocks: true
+RSpec/ExpectChange:
+  EnforcedStyle: block
+RSpec/FilePath:
+  Exclude:
+    - spec/kangaru/components/**/*.rb
+RSpec/LetSetup:
+  Enabled: false
+RSpec/MultipleMemoizedHelpers:
+  Max: 15
+RSpec/NestedGroups:
+  Enabled: false
+RSpec/SharedExamples:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.2.0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2023-09-05
+
+- Initial release

data/Gemfile

@@ -0,0 +1,14 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "fileutils"
+gem "forwardable"
+gem "pathname"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rubocop", "~> 1.21"
+gem "rubocop-rspec", "~> 2.23"
+gem "steep", "~> 1.5"
+gem "yaml"
+gem "zirconia", "~> 0.1"

data/Gemfile.lock

@@ -0,0 +1,139 @@
+PATH
+  remote: .
+  specs:
+    kangaru (0.1.0)
+      colorize (~> 1.1)
+      erb (~> 4.0)
+      sequel (~> 5.72)
+      sqlite3 (~> 1.6)
+      zeitwerk (~> 2.6)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (7.0.7.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    ast (2.4.2)
+    base64 (0.1.1)
+    bigdecimal (3.1.4)
+    cgi (0.3.6)
+    colorize (1.1.0)
+    concurrent-ruby (1.2.2)
+    csv (3.2.7)
+    diff-lcs (1.5.0)
+    erb (4.0.3)
+      cgi (>= 0.3.3)
+    ffi (1.15.5)
+    fileutils (1.7.1)
+    forwardable (1.3.3)
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
+    json (2.6.3)
+    language_server-protocol (3.17.0.3)
+    listen (3.8.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.5.3)
+    minitest (5.19.0)
+    parallel (1.23.0)
+    parser (3.2.2.3)
+      ast (~> 2.4.1)
+      racc
+    pathname (0.2.1)
+    racc (1.7.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rbs (3.2.1)
+    regexp_parser (2.8.1)
+    rexml (3.2.6)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+    rubocop (1.56.2)
+      base64 (~> 0.1.1)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.2.2.3)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.28.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.29.0)
+      parser (>= 3.2.1.0)
+    rubocop-capybara (2.18.0)
+      rubocop (~> 1.41)
+    rubocop-factory_bot (2.23.1)
+      rubocop (~> 1.33)
+    rubocop-rspec (2.23.2)
+      rubocop (~> 1.33)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+    ruby-progressbar (1.13.0)
+    securerandom (0.2.2)
+    sequel (5.72.0)
+      bigdecimal
+    sqlite3 (1.6.0-arm64-darwin)
+    sqlite3 (1.6.0-x86_64-linux)
+    steep (1.5.3)
+      activesupport (>= 5.1)
+      concurrent-ruby (>= 1.1.10)
+      csv (>= 3.0.9)
+      fileutils (>= 1.1.0)
+      json (>= 2.1.0)
+      language_server-protocol (>= 3.15, < 4.0)
+      listen (~> 3.0)
+      logger (>= 1.3.0)
+      parser (>= 3.1)
+      rainbow (>= 2.2.2, < 4.0)
+      rbs (>= 3.1.0)
+      securerandom (>= 0.1)
+      strscan (>= 1.0.0)
+      terminal-table (>= 2, < 4)
+    strscan (3.0.6)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.4.2)
+    yaml (0.2.1)
+    zeitwerk (2.6.11)
+    zirconia (0.1.2)
+
+PLATFORMS
+  arm64-darwin-21
+  x86_64-linux
+
+DEPENDENCIES
+  fileutils
+  forwardable
+  kangaru!
+  pathname
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+  rubocop-rspec (~> 2.23)
+  steep (~> 1.5)
+  yaml
+  zirconia (~> 0.1)
+
+BUNDLED WITH
+   2.4.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Chris Welham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,49 @@
+# Kangaru - A Ruby Framework for Building Command Line Applications
+
+Kangaru is an open-source framework written in Ruby for building powerful and efficient command line applications. This project aims to make it easier for developers to create complex CLI programs with minimal effort, by providing a set of useful tools and libraries in a configurable ecosystem.
+
+## Features
+
+- MVC architecture drawing heavy inspiration from Rails
+- ERB rendering of view templates with embedded Ruby capabilities
+- SQLite and Sequel integration allowing databases to be created and used by your CLI
+- A powerful command parser that routes terminal requests to their controller
+- Zeitwerk-based autoloading of gem files
+- Simple installation, integration and configuration
+
+
+## Quick Setup
+
+It is recommended to create a new Ruby gem for each Kangaru CLI application. This can be executed through `bundler` with the following command:
+
+```sh
+bundle gem gem_name
+```
+
+Next add Kangaru to your Gem's Gemfile and bundle install:
+
+```ruby
+# Gemfile
+gem "kangaru"
+```
+```sh
+bundle install
+```
+
+Kangaru's set up is bundled up into a single Ruby module that must be extended from the entry file for your Gem application. Conventionally this will be the Ruby file at `/gem_name/lib/gem_name.rb`, where `gem_name` is the name of the application specified with the `bundle gem` command.
+
+For example:
+
+```ruby
+# gem_name/lib/gem_name.rb
+require "kangaru"
+
+module GemName
+  extend Kangaru::Initialiser
+end
+```
+
+This extension will set up Kangaru in the context of your Gem, including setting up processes such as the autoloader and config.
+
+## Documentation
+- TBC

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/Steepfile

@@ -0,0 +1,12 @@
+target :lib do
+  signature "sig"
+
+  check "lib"
+
+  configure_code_diagnostics do |hash|
+    hash[Steep::Diagnostic::Ruby::FallbackAny] = nil
+    hash[Steep::Diagnostic::Ruby::UnknownConstant] = :error
+    hash[Steep::Diagnostic::Ruby::MethodDefinitionMissing] = nil
+    hash[Steep::Diagnostic::Ruby::UnsupportedSyntax] = :hint
+  end
+end

data/kangaru.gemspec

@@ -0,0 +1,27 @@
+require_relative "lib/kangaru/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "kangaru"
+  spec.version = Kangaru::VERSION
+  spec.authors = ["Chris Welham"]
+  spec.email = ["71787007+apexatoll@users.noreply.github.com"]
+
+  spec.summary = "A lightweight framework for building command line interfaces"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files`.split("\n").reject do |f|
+      f == __FILE__ || f.match?(/\A(bin|sig|spec|\.git|\.github)/)
+    end
+  end
+  spec.bindir = "bin"
+  spec.executables = []
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "colorize", "~> 1.1"
+  spec.add_dependency "erb", "~> 4.0"
+  spec.add_dependency "sequel", "~> 5.72"
+  spec.add_dependency "sqlite3", "~> 1.6"
+  spec.add_dependency "zeitwerk", "~> 2.6"
+end

data/lib/kangaru/application.rb

@@ -0,0 +1,73 @@
+module Kangaru
+  class Application
+    extend Forwardable
+
+    attr_reader :paths, :namespace, :database
+
+    def initialize(source:, namespace:)
+      @paths = Paths.new(source:)
+      @namespace = namespace
+
+      autoloader.setup
+    end
+
+    # Lazy-loaded to allow defaults to be set after application is created.
+    def config
+      @config ||= Config.new
+    end
+
+    # If called with no env, the config will be applied regardless of current
+    # env. If multiple configure calls matching the current env are made, the
+    # most recent calls will overwrite older changes.
+    def configure(env = nil, &block)
+      block.call(config) if current_env?(env)
+    end
+
+    def configured?
+      @configured == true
+    end
+
+    def apply_config!
+      raise "config already applied" if configured?
+
+      config.import_external_config!
+
+      @database = setup_database!
+      @configured = true
+    end
+
+    def run!(*argv)
+      request = RequestBuilder.new(argv).build
+
+      Router.new(request, namespace:).resolve
+    end
+
+    def_delegators :paths, :view_path
+
+    private
+
+    # Returns true if nil as this is represents all envs.
+    def current_env?(env)
+      return true if env.nil?
+
+      Kangaru.env?(env)
+    end
+
+    def autoloader
+      @autoloader ||= Zeitwerk::Loader.new.tap do |loader|
+        loader.inflector = Zeitwerk::GemInflector.new(paths.source.to_s)
+        loader.collapse(paths.collapsed_dirs)
+        loader.push_dir(paths.lib_path.to_s)
+      end
+    end
+
+    def setup_database!
+      return unless config.database.adaptor
+
+      Database.new(**config.database.serialise).tap do |database|
+        database.setup!
+        database.migrate!
+      end
+    end
+  end
+end

data/lib/kangaru/argument_parser.rb

@@ -0,0 +1,34 @@
+module Kangaru
+  class ArgumentParser
+    using Patches::Inflections
+
+    attr_reader :tokens
+
+    def initialize(*tokens)
+      @tokens = tokens
+    end
+
+    def parse
+      grouped_argument_tokens.to_h do |tokens|
+        key   = parse_key(tokens.shift || raise)
+        value = parse_value(tokens)
+
+        [key, value]
+      end
+    end
+
+    private
+
+    def grouped_argument_tokens
+      tokens.slice_before(/^-/).to_a
+    end
+
+    def parse_key(key)
+      key.gsub(/^-+/, "").to_snakecase.to_sym
+    end
+
+    def parse_value(tokens)
+      tokens.empty? || tokens.join(" ")
+    end
+  end
+end

data/lib/kangaru/components/component.rb

@@ -0,0 +1,19 @@
+module Kangaru
+  class Component
+    using Patches::Inflections
+    using Patches::Source
+
+    def render
+      Renderer.new(view_file).render(binding)
+    end
+
+    private
+
+    def view_file
+      dir = File.dirname(self.class.source)
+      name = File.basename(self.class.source, ".rb")
+
+      Pathname.new(dir).join("#{name}.erb")
+    end
+  end
+end

data/lib/kangaru/concerns/attributes_concern.rb

@@ -0,0 +1,31 @@
+module Kangaru
+  module Concerns
+    module AttributesConcern
+      extend Concern
+
+      class_methods do
+        def attributes
+          instance_methods.grep(/\w=$/).map do |attribute|
+            attribute.to_s.delete_suffix("=").to_sym
+          end
+        end
+
+        def set_default(**attributes)
+          defaults.merge!(**attributes)
+        end
+
+        def defaults
+          @defaults ||= {}
+        end
+      end
+
+      def initialize(**attributes)
+        attributes = self.class.defaults.merge(**attributes)
+
+        attributes.slice(*self.class.attributes).each do |attr, value|
+          instance_variable_set(:"@#{attr}", value)
+        end
+      end
+    end
+  end
+end

data/lib/kangaru/concerns/concern.rb

@@ -0,0 +1,33 @@
+module Kangaru
+  module Concerns
+    module Concern
+      def append_features(base)
+        super
+        evaluate_concern_blocks!(base)
+      end
+
+      def class_methods(&)
+        if const_defined?(:ClassMethods)
+          const_get(:ClassMethods)
+        else
+          const_set(:ClassMethods, Module.new)
+        end.module_eval(&)
+      end
+
+      def included(base = nil, &block)
+        super base if base
+        return if block.nil?
+
+        @included = block
+      end
+
+      private
+
+      def evaluate_concern_blocks!(base)
+        base.extend(const_get(:ClassMethods)) if const_defined?(:ClassMethods)
+
+        base.class_eval(&@included) if instance_variable_defined?(:@included)
+      end
+    end
+  end
+end

data/lib/kangaru/concerns/configurable.rb

@@ -0,0 +1,22 @@
+module Kangaru
+  module Concerns
+    module Configurable
+      extend Concern
+
+      using Patches::Constantise
+
+      class_methods do
+        def configurator_name
+          (name || raise("class name not set"))
+            .gsub(/^(.*?)::/, "\\1::Configurators::")
+            .concat("Configurator")
+        end
+      end
+
+      def config
+        Kangaru.application.config.for(self.class.configurator_name) ||
+          raise("inferred configurator not set by application")
+      end
+    end
+  end
+end

data/lib/kangaru/concerns/validatable.rb

@@ -0,0 +1,46 @@
+module Kangaru
+  module Concerns
+    module Validatable
+      extend Concern
+
+      class_methods do
+        def validation_rules
+          @validation_rules ||= {}
+        end
+
+        def validates(attribute, **validations)
+          validation_rules[attribute] ||= {}
+          validation_rules[attribute].merge!(**validations)
+        end
+      end
+
+      def errors
+        @errors ||= []
+      end
+
+      def validate
+        self.class.validation_rules.each do |attribute, validations|
+          validator = validator_for(attribute)
+
+          validations.each do |validator_name, params|
+            params = {} if params == true
+
+            validator.validate(validator_name, **params)
+          end
+        end
+      end
+
+      def valid?
+        validate
+
+        errors.empty?
+      end
+
+      private
+
+      def validator_for(attribute)
+        Validation::AttributeValidator.new(model: self, attribute:)
+      end
+    end
+  end
+end

data/lib/kangaru/config.rb

@@ -0,0 +1,45 @@
+module Kangaru
+  class Config
+    attr_reader :configurators
+
+    def initialize
+      @configurators = set_configurators!
+    end
+
+    def serialise
+      configurators.transform_values(&:serialise)
+    end
+
+    def import_external_config!
+      return unless external_config_exists?
+
+      @external = Configurators::ExternalConfigurator
+                    .from_yaml_file(application.config_path)
+    end
+
+    # Returns the configurator instance with the given class name.
+    def for(configurator_name)
+      configurators.values.find do |configurator|
+        configurator.class.name == configurator_name # rubocop:disable Style
+      end
+    end
+
+    private
+
+    def set_configurators!
+      Configurators.classes.to_h do |configurator_class|
+        self.class.class_eval { attr_reader configurator_class.key }
+
+        configurator = configurator_class.new
+
+        instance_variable_set(:"@#{configurator_class.key}", configurator)
+
+        [configurator_class.key, configurator]
+      end
+    end
+
+    def external_config_exists?
+      application.config_path && File.exist?(application.config_path)
+    end
+  end
+end

data/lib/kangaru/configurators/application_configurator.rb

@@ -0,0 +1,7 @@
+module Kangaru
+  module Configurators
+    class ApplicationConfigurator < Configurator
+      attr_accessor :config_path
+    end
+  end
+end