repository·main·Indexed 26 days ago
https://github.com/rails/thorThor is a Ruby toolkit for building self-documenting command-line interfaces (CLIs). It provides tools for option parsing, usage banner generation, and can serve as an alternative to Rake. Key features include support for subcommands, command aliases, exclusive/at-least-one option enforcement, and a directory action for copying files and templates.
Thor is a tool for building self-documenting command line utilities. It automates the parsing of command line options and the generation of "USAGE:" banners. It can also serve as an alternative to the Rake build tool, utilizing a similar Rake-like syntax.
Security Warning: Thor is designed as a system tool to allow seamless file and URL access via open-uri. It should not receive direct application user input, as this can create command injection attack vectors.
Install the Thor library using the RubyGems package manager.
gem install thorWhen using the %method_name% syntax in filenames within a directory being processed by the directory action, Thor attempts to call method_name on the class instance to resolve the filename.
If the method being called is defined as private, Thor will raise a PrivateMethodEncodedError. To fix this, ensure the method used for path encoding is a public method.
Thor uses a specific hierarchy of error classes to handle user-facing command-line errors. When a Thor::Error (or one of its subclasses) is raised, Thor suppresses the backtrace and displays a clean error message to the user.
Note: If you are a developer and encounter an error caused by your implementation (e.g., overwriting a Thor keyword), you should allow standard errors to propagate so you can see the full backtrace. Use Thor::Error specifically for errors caused by incorrect end-user usage of your CLI.
By default, a Thor command invokes a method in the Thor class with the same name. If you need to change this behavior (e.g., to route commands to different objects or implement custom dispatch logic), you can override the run method in a custom command class inheriting from Thor::Command.
When overriding run(instance, args = []), the instance is the Thor class instance and args is the array of arguments passed to the command.
stop_on_unknown_option!. This tells Thor to stop parsing options as soon as it encounters an unknown one or a regular argument, passing the rest through to the command.You can nest Thor classes as subcommands within a parent Thor class using register or subcommand.
register: Used to register a Thor::Group as a command or a standard Thor subclass as a subcommand. It requires a class, a subcommand name, usage, and description.subcommand: A simpler way to attach a Thor subclass to a specific name.default_command (or default_task) to specify which command should run when the CLI is executed without an explicit command name. Passing :none will make it default to the help command.The directory method copies files recursively from a source directory to a destination. It supports several specialized behaviors for file handling:
.tt are treated as templates. They are copied to the destination with the .tt extension removed..empty_directory are used to ensure a directory is created in the destination, but the file itself is not copied.%app_name%.rb) are treated as method calls. Thor will execute the method named inside the % signs and replace the filename with the method's return value. Note: The method must be public; if the method is private, Thor will raise a PrivateMethodEncodedError.source (String): The relative path to the source directory.destination (String, optional): The relative path to the destination directory. If omitted, the source is used as the destination.config (Hash, optional): Configuration options::verbose => false: Disables status logging.:recursive => false: Disables recursive searching.:mode => :preserve: Preserves the file mode from the source.:exclude_pattern => /regexp/: Prevents copying files that match the provided regular expression.Thor allows you to define relationships between options to enforce CLI logic:
exclusive: Ensures that only one of the specified options is provided. If multiple are provided, an ExclusiveArgumentsError is raised.at_least_one: Ensures that at least one of the specified options is provided. If none are provided, an AtLeastOneRequiredArgumentError is raised.These can be used with a block or by passing arguments to the method.
package_name to change the name displayed in the help output when listing commands.map to create shortcuts or aliases for existing commands. You can map a single string to a command or an array of strings to a single command.