rake_options 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d64b8c9debd762394889c921fc5a3c52f23618f3e1d33448c5f6337ab942edc
+  data.tar.gz: d24b0d7525cbb407047c86b61abca35ed3646a4f414272f1521900267a15673d
+SHA512:
+  metadata.gz: b896b635679be32725e5f480441fed874e4a853d3af99ce45b234d4dc5c42ed68ac1bc866879aa434fca4b04fad33b76db825ad9303580d997c8a58c8184fa19
+  data.tar.gz: 2d89ac0871af10c498ebfc23d2bc73c7644923fe14e8e2de2005c3195ff9ad995848e22e496da5f632e165a674b07bcf604b94cec14e5a808923a6c67c23d3d6

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RakeCommander Contributors
+
+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,277 @@
+# RakeOptions
+
+RakeOptions is a Ruby gem that simplifies command line argument handling for rake tasks. It provides an intuitive API for parsing arguments with support for multiple notation styles and automatic help documentation generation.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rake_options'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install rake_options
+```
+
+## Usage
+
+### Basic CLI-Style Arguments
+
+```ruby
+require 'rake_options'
+
+desc "Build with custom options"
+task :build do
+  config = {
+    "with-mysql-lib" => "--with-mysql-lib $path",
+    "enable-feature" => "--enable-feature $name"
+  }
+  
+  options = RakeOptions.command_line_args(config)
+  
+  puts "MySQL lib path: #{options['with-mysql-lib']}"
+  puts "Feature: #{options['enable-feature']}"
+end
+```
+
+Run with:
+```bash
+rake build -- --with-mysql-lib "/usr/local/mysql/lib" --enable-feature "caching"
+```
+
+### Bracket-Style Arguments
+
+```ruby
+require 'rake_options'
+
+desc "Deploy with bracket notation"
+task :deploy do
+  config = {
+    "environment" => "[environment=$env]",
+    "region" => "[region=$region]"
+  }
+  
+  options = RakeOptions.command_line_args(config, notation: :bracket)
+  
+  puts "Deploying to #{options['environment']} in #{options['region']}"
+end
+```
+
+Run with:
+```bash
+rake deploy [environment=production] [region=us-west-2]
+```
+
+### Multiple Variables in One Template
+
+```ruby
+config = {
+  "database" => "--config $file --env $environment"
+}
+
+options = RakeOptions.command_line_args(config)
+# Extracts both file and environment from: --config database.yml --env production
+```
+
+### Automatic Help Documentation
+
+```ruby
+require 'rake_options'
+
+readme_content = <<~HELP
+  Build Task Help
+  
+  Available options:
+    --with-mysql-lib PATH    Specify MySQL library path
+    --enable-feature NAME    Enable a specific feature
+HELP
+
+RakeOptions.initialize_readme(readme_content)
+
+desc "Build with help support"
+task :build do
+  config = {
+    "with-mysql-lib" => "--with-mysql-lib $path",
+    "enable-feature" => "--enable-feature $name"
+  }
+  
+  options = RakeOptions.command_line_args(config)
+  # Your build logic here
+end
+```
+
+Run with:
+```bash
+rake build -- --help
+```
+
+### Hash Access with Strings or Symbols
+
+The returned options hash supports both string and symbol key access:
+
+```ruby
+options = RakeOptions.command_line_args(config)
+
+# Both work:
+options['with-mysql-lib']
+options[:with_mysql_lib]
+```
+
+## Configuration Format
+
+The configuration hash maps symbolic names to template patterns:
+
+```ruby
+{
+  "key-name" => "template pattern with $variables"
+}
+```
+
+- **Key**: The name you'll use to access the parsed value
+- **Value**: A template string that defines how to extract the argument
+- **Variables**: Prefixed with `$` to indicate where values should be extracted
+
+### Template Examples
+
+```ruby
+# Single variable
+"mysql-path" => "--with-mysql-lib $path"
+
+# Multiple variables
+"database" => "--config $file --env $environment"
+
+# Bracket notation
+"region" => "[region=$value]"
+```
+
+## Notation Styles
+
+### CLI Notation (default)
+
+```ruby
+options = RakeOptions.command_line_args(config, notation: :cli)
+```
+
+Supports:
+- `--flag value`
+- `--flag "value with spaces"`
+- Multiple flags in one command
+
+### Bracket Notation
+
+```ruby
+options = RakeOptions.command_line_args(config, notation: :bracket)
+```
+
+Supports:
+- `[key=value]`
+- `[key="value with spaces"]`
+- Multiple bracket arguments
+
+## Error Handling
+
+RakeOptions provides clear error messages:
+
+```ruby
+# Invalid notation
+RakeOptions.command_line_args(config, notation: :invalid)
+# => InvalidNotationError: Invalid notation ':invalid'. Supported notations: :cli, :bracket
+
+# Missing optional arguments return nil
+options['missing-arg']  # => nil
+```
+
+## Troubleshooting
+
+### Arguments not being parsed
+
+**Problem**: Your arguments aren't being recognized.
+
+**Solution**: Make sure you're using `--` to separate rake arguments from your custom arguments:
+```bash
+rake task -- --your-flag value
+```
+
+### Symbol vs String keys
+
+**Problem**: Can't access values with symbol keys.
+
+**Solution**: RakeOptions returns a `HashWithIndifferentAccess` that supports both:
+```ruby
+options[:key]        # Works
+options['key']       # Also works
+options[:key_name]   # Converts underscores to dashes automatically
+options['key-name']  # Same value
+```
+
+### Help not displaying
+
+**Problem**: `--help` flag doesn't show help.
+
+**Solution**: Ensure `--help` is in ARGV before calling `command_line_args`:
+```bash
+rake task -- --help
+```
+
+### Quoted values not working
+
+**Problem**: Values with spaces aren't being captured correctly.
+
+**Solution**: Use quotes around values with spaces:
+```bash
+rake task -- --path "/path/with spaces"
+```
+
+### Template not matching
+
+**Problem**: Template variables aren't extracting values.
+
+**Solution**: Ensure your template matches the command line format exactly:
+```ruby
+# Template
+"option" => "--option $value"
+
+# Command line must match
+rake task -- --option myvalue
+```
+
+## Requirements
+
+- Ruby 2.7 or higher
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+Run tests:
+
+```bash
+rake spec
+```
+
+Build the gem:
+
+```bash
+gem build rake_options.gemspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/rake_options/argument_parser.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "cli_parser"
+require_relative "bracket_parser"
+require_relative "errors"
+
+module RakeOptions
+  class ArgumentParser
+    VALID_NOTATIONS = [:cli, :bracket].freeze
+
+    def initialize(config, notation)
+      @config = config
+      @notation = notation
+      validate_notation
+    end
+
+    # Parse ARGV and return structured options
+    # @return [Hash] Parsed options
+    def parse
+      parser = select_parser
+      parser.parse
+    end
+
+    private
+
+    # Select appropriate parser based on notation
+    # @return [CLIParser, BracketParser] Parser instance
+    def select_parser
+      case @notation
+      when :cli
+        CLIParser.new(@config)
+      when :bracket
+        BracketParser.new(@config)
+      end
+    end
+
+    # Validate notation parameter
+    # @raise [InvalidNotationError] if notation is invalid
+    def validate_notation
+      return if VALID_NOTATIONS.include?(@notation)
+
+      raise InvalidNotationError,
+            "Invalid notation ':#{@notation}'. Supported notations: #{VALID_NOTATIONS.map { |n| ":#{n}" }.join(', ')}"
+    end
+  end
+end

data/lib/rake_options/bracket_parser.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RakeOptions
+  class BracketParser
+    def initialize(config)
+      @config = config
+    end
+
+    # Parse bracket-style arguments from ARGV
+    # @param argv [Array] Command line arguments (defaults to ARGV)
+    # @return [Hash] Parsed values
+    def parse(argv = ARGV)
+      result = {}
+      
+      # Extract all bracket arguments from argv
+      bracket_args = extract_bracket_args(argv)
+      
+      # Match bracket args to config keys
+      @config.each do |key, _template|
+        # Look for matching bracket key
+        if bracket_args.key?(key)
+          result[key] = bracket_args[key]
+        else
+          result[key] = nil
+        end
+      end
+      
+      result
+    end
+
+    private
+
+    # Find all [key=value] patterns in argv
+    # @param argv [Array] Command line arguments
+    # @return [Hash] Extracted key-value pairs
+    def extract_bracket_args(argv)
+      result = {}
+      
+      argv.each do |arg|
+        # Match [key=value] or [key="value"]
+        match = arg.match(/^\[([^=]+)=(.+)\]$/)
+        next unless match
+        
+        key = match[1]
+        value = parse_bracket_value(match[2])
+        result[key] = value
+      end
+      
+      result
+    end
+
+    # Handle quoted and unquoted values in brackets
+    # @param value [String] Value from bracket
+    # @return [String] Parsed value
+    def parse_bracket_value(value)
+      # Remove surrounding quotes if present
+      if value.start_with?('"') && value.end_with?('"')
+        value[1..-2]
+      else
+        value
+      end
+    end
+  end
+end

data/lib/rake_options/cli_parser.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "template_engine"
+
+module RakeOptions
+  class CLIParser
+    def initialize(config)
+      @config = config
+      @parsed_templates = {}
+      
+      # Pre-parse all templates
+      @config.each do |key, template_str|
+        @parsed_templates[key] = TemplateEngine.parse_template(template_str)
+      end
+    end
+
+    # Parse CLI-style arguments from ARGV
+    # @param argv [Array] Command line arguments (defaults to ARGV)
+    # @return [Hash] Parsed values
+    def parse(argv = ARGV)
+      result = {}
+      
+      @config.each do |key, _template_str|
+        parsed_template = @parsed_templates[key]
+        extracted = TemplateEngine.extract_values(argv, parsed_template)
+        
+        if extracted && !extracted.empty?
+          # For single variable templates, store the value directly
+          if extracted.size == 1
+            result[key] = extracted.values.first
+          else
+            # For multiple variables, store the hash
+            result[key] = extracted
+          end
+        else
+          result[key] = nil
+        end
+      end
+      
+      result
+    end
+  end
+end

data/lib/rake_options/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RakeOptions
+  class Error < StandardError; end
+  class InvalidNotationError < Error; end
+  class TemplateParseError < Error; end
+  class ArgumentParseError < Error; end
+end

data/lib/rake_options/hash_with_indifferent_access.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RakeOptions
+  class HashWithIndifferentAccess < Hash
+    def initialize(hash = {})
+      super()
+      hash.each do |key, value|
+        self[key] = value
+      end
+    end
+
+    # Override [] to handle both string and symbol keys
+    def [](key)
+      super(convert_key(key))
+    end
+
+    # Override []= to store with string keys
+    def []=(key, value)
+      super(convert_key(key), value)
+    end
+
+    # Override fetch to handle both string and symbol keys
+    def fetch(key, *args, &block)
+      super(convert_key(key), *args, &block)
+    end
+
+    # Override key? to handle both string and symbol keys
+    def key?(key)
+      super(convert_key(key))
+    end
+
+    alias_method :has_key?, :key?
+    alias_method :include?, :key?
+
+    private
+
+    # Convert key to string and normalize dashes/underscores
+    def convert_key(key)
+      key_str = key.to_s
+      # Try exact match first
+      return key_str if Hash.instance_method(:key?).bind(self).call(key_str)
+      
+      # Try with underscores converted to dashes
+      dashed = key_str.tr("_", "-")
+      return dashed if Hash.instance_method(:key?).bind(self).call(dashed)
+      
+      # Try with dashes converted to underscores
+      underscored = key_str.tr("-", "_")
+      return underscored if Hash.instance_method(:key?).bind(self).call(underscored)
+      
+      # Return original if no match
+      key_str
+    end
+  end
+end

data/lib/rake_options/help_generator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RakeOptions
+  class HelpGenerator
+    def initialize(config, readme_content = nil)
+      @config = config
+      @readme_content = readme_content
+    end
+
+    # Display help and exit
+    # @return [void]
+    def display_and_exit
+      puts generate_help_text
+      exit(0)
+    end
+
+    private
+
+    # Create formatted help text
+    # @return [String] Formatted help text
+    def generate_help_text
+      if @readme_content
+        @readme_content
+      else
+        auto_generate_help
+      end
+    end
+
+    # Auto-generate help from config
+    # @return [String] Auto-generated help text
+    def auto_generate_help
+      help_text = "Available Options:\n\n"
+      
+      @config.each do |key, template|
+        help_text += format_option(key, template)
+      end
+      
+      help_text
+    end
+
+    # Format individual option for display
+    # @param key [String] Option key
+    # @param template [String] Template string
+    # @return [String] Formatted option line
+    def format_option(key, template)
+      "  #{template.ljust(40)} (#{key})\n"
+    end
+  end
+end

data/lib/rake_options/template_engine.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RakeOptions
+  class TemplateEngine
+    # Parse a template string into components
+    # @param template [String] Template like "--flag $variable"
+    # @return [Hash] Template structure with flag, variables, and pattern
+    def self.parse_template(template)
+      variables = identify_variables(template)
+      pattern = build_pattern(template, variables)
+      
+      {
+        template: template,
+        variables: variables,
+        pattern: pattern
+      }
+    end
+
+    # Extract values from input based on template
+    # @param input [Array] Input tokens (ARGV)
+    # @param parsed_template [Hash] Parsed template structure
+    # @return [Hash, nil] Extracted variable values or nil if no match
+    def self.extract_values(input, parsed_template)
+      input_str = input.join(" ")
+      match = parsed_template[:pattern].match(input_str)
+      
+      return nil unless match
+
+      result = {}
+      # Each variable creates 2 capture groups (quoted and unquoted)
+      # We need to pick the non-nil one
+      capture_index = 1
+      parsed_template[:variables].each do |var|
+        # Get both possible captures (quoted or unquoted)
+        quoted_value = match[capture_index]
+        unquoted_value = match[capture_index + 1]
+        
+        result[var] = quoted_value || unquoted_value
+        capture_index += 2
+      end
+      
+      result
+    end
+
+    private
+
+    # Find $variable placeholders in template
+    # @param template [String] Template string
+    # @return [Array<String>] List of variable names
+    def self.identify_variables(template)
+      template.scan(/\$(\w+)/).flatten
+    end
+
+    # Create regex pattern from template
+    # @param template [String] Template string
+    # @param variables [Array<String>] Variable names
+    # @return [Regexp] Regex pattern for matching
+    def self.build_pattern(template, variables)
+      # Replace $variables with capture groups that match:
+      # - Quoted strings: "value with spaces"
+      # - Unquoted values: value (non-whitespace)
+      pattern_str = template.gsub(/\$\w+/, '(?:"([^"]+)"|(\S+))')
+      
+      # Escape special regex characters except our capture groups
+      pattern_str = pattern_str.gsub(/\s+/, '\s+')
+      
+      Regexp.new(pattern_str)
+    end
+  end
+end

data/lib/rake_options/version.rb

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

data/lib/rake_options.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "rake_options/version"
+require_relative "rake_options/errors"
+require_relative "rake_options/argument_parser"
+require_relative "rake_options/help_generator"
+require_relative "rake_options/hash_with_indifferent_access"
+
+module RakeOptions
+  class << self
+    attr_accessor :readme_content
+
+    # Parse command line arguments based on configuration
+    # @param config [Hash] Argument configuration mapping
+    # @param notation [Symbol] Notation style (:cli or :bracket)
+    # @return [HashWithIndifferentAccess] Parsed arguments with indifferent access
+    def command_line_args(config, notation: :cli)
+      # Check for --help flag
+      if ARGV.include?("--help")
+        help_generator = HelpGenerator.new(config, readme_content)
+        help_generator.display_and_exit
+      end
+
+      # Parse arguments
+      parser = ArgumentParser.new(config, notation)
+      result = parser.parse
+
+      # Wrap in HashWithIndifferentAccess
+      HashWithIndifferentAccess.new(result)
+    end
+
+    # Initialize help documentation
+    # @param readme_content [String] Help text or README content
+    # @return [void]
+    def initialize_readme(content)
+      self.readme_content = content
+    end
+  end
+end