RakeOptions is a Ruby gem that simplifies command line argument handling for rake tasks. It provides an intuitive API for parsing CLI-style arguments with automatic type casting, required/optional validation, and automatic help documentation generation.
Add this line to your application's Gemfile:
gem 'rake_options'And then execute:
bundle installOr install it yourself as:
gem install rake_optionsrequire 'rake_options'
desc "Build with custom options"
task :build do
# Configuration: [flag_name, type, requirement, description]
config = [
["with-mysql-lib", :string, :required, "Path to MySQL library"],
["enable-feature", :string, :optional, "Feature to enable"],
["port", :integer, :optional, "Port number"]
]
options = RakeOptions.command_line_args(config)
puts "MySQL lib path: #{options['with-mysql-lib']}"
puts "Feature: #{options['enable-feature']}"
puts "Port: #{options['port']}" # Automatically cast to integer
endRun with:
rake build -- --with-mysql-lib=/usr/local/mysql/lib --enable-feature=caching --port=3000For values with spaces, use quotes:
rake build -- --with-mysql-lib="/path/with spaces/lib"Note: Required arguments will raise an error if not provided.
RakeOptions automatically casts values to the specified type and validates required arguments:
config = [
["port", :integer, :required, "Server port number"],
["enabled", :boolean, :optional, "Enable feature flag"],
["ratio", :float, :optional, "Scaling ratio"],
["name", :string, :required, "Application name"]
]
options = RakeOptions.command_line_args(config)
# Values are automatically cast:
options['port'] # => 3000 (Integer)
options['enabled'] # => true (Boolean)
options['ratio'] # => 1.5 (Float)
options['name'] # => "myapp" (String)Supported types:
:string- String values:integeror:int- Integer values:float- Float values:booleanor:bool- Boolean values (true/false)
Requirements:
:required- Must be provided or raises ArgumentError:optional- Can be omitted (returns nil)
require 'rake_options'
# Set a brief summary for the help display
RakeOptions.initialize_readme_summary(<<~SUMMARY)
Build Task - Compile and configure the application
Usage: rake build -- [options]
SUMMARY
desc "Build with help support"
task :build do
config = [
["with-mysql-lib", :string, :required, "Path to MySQL library"],
["enable-feature", :string, :optional, "Feature to enable"],
["port", :integer, :optional, "Port number"]
]
options = RakeOptions.command_line_args(config)
# Your build logic here
endRun with:
rake build -- --helpOutput:
Build Task - Compile and configure the application
Usage: rake build -- [options]
Available Options:
--with-mysql-lib=VALUE (string) [REQUIRED]
Path to MySQL library
--enable-feature=VALUE (string)
Feature to enable
--port=VALUE (integer)
Port number
The returned options hash supports both string and symbol key access:
options = RakeOptions.command_line_args(config)
# Both work:
options['with-mysql-lib']
options[:with_mysql_lib]The configuration is an array of tuples with 4 elements:
[
["flag-name", :type, :requirement, "description"],
["another-flag", :type, :requirement, "description"]
]- flag-name: The CLI flag name (will become
--flag-name) - type: The data type (
:string,:integer,:float,:boolean) - requirement: Either
:requiredor:optional - description: Help text describing the option
# Required string value
["mysql-path", :string, :required, "Path to MySQL installation"]
# Optional integer value
["port", :integer, :optional, "Server port number"]
# Required boolean flag
["enabled", :boolean, :required, "Enable the feature"]
# Optional float value
["ratio", :float, :optional, "Scaling ratio"]Short format (for backward compatibility):
["flag-name", :type] # Defaults to :optional with no descriptionRakeOptions uses standard CLI flag format:
options = RakeOptions.command_line_args(config)Supports:
--flag=value--flag="value with spaces"- Multiple flags in one command
RakeOptions provides clear error messages:
# 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'] # => nilProblem: Your arguments aren't being recognized.
Solution: Make sure you're using -- to separate rake arguments from your custom arguments:
rake task -- --your-flag valueProblem: Can't access values with symbol keys.
Solution: RakeOptions returns a HashWithIndifferentAccess that supports both:
options[:key] # Works
options['key'] # Also works
options[:key_name] # Converts underscores to dashes automatically
options['key-name'] # Same valueProblem: --help flag doesn't show help.
Solution: Ensure --help is in ARGV before calling command_line_args:
rake task -- --helpProblem: Values with spaces aren't being captured correctly.
Solution: Use quotes around values with spaces:
rake task -- --path="/path/with spaces"Problem: Arguments aren't being recognized.
Solution: Ensure the flag name in ARGV matches the config:
# Config
["my-option", :string]
# Command line must match exactly
rake task -- --my-option=myvalue- Ruby 2.7 or higher
After checking out the repo, run:
bundle installRun tests:
rake specBuild the gem:
gem build rake_options.gemspecBug reports and pull requests are welcome on GitHub.
The gem is available as open source under the terms of the MIT License.