thor Documentation

File: README.md Copy Chapter

Thor

Description Copy Chapter

Thor is a simple and efficient tool for building self-documenting command line
utilities. It removes the pain of parsing command line options, writing
"USAGE:" banners, and can also be used as an alternative to the Rake
build tool. The syntax is Rake-like, so it should be familiar to most Rake
users.

Please note: Thor, by design, is a system tool created to allow seamless file and url
access, which should not receive application user input. It relies on open-uri,
which, combined with application user input, would provide a command injection attack
vector.

Installation Copy Chapter

gem install thor

Usage and documentation Copy Chapter

Please see the wiki for basic usage and other documentation on using Thor.

Contributing Copy Chapter

If you would like to help, please read the CONTRIBUTING file for suggestions.

License Copy Chapter

Released under the MIT License. See the LICENSE file for further details.

File: CONTRIBUTING.md Copy Chapter

Pull Requests Copy Chapter

Here are some reasons why a pull request may not be merged:

1. It hasn’t been reviewed.
2. It doesn’t include specs for new functionality.
3. It doesn’t include documentation for new functionality.
4. It changes behavior without changing the relevant documentation, comments, or specs.
5. It changes behavior of an existing public API, breaking backward compatibility.
6. It breaks the tests on a supported platform.
7. It doesn’t merge cleanly (requiring Git rebasing and conflict resolution).

If you would like to help in this process, you can start by evaluating open pull requests against the criteria above. For example, if a pull request does not include specs for new functionality, you can add a comment like: “If you would like this feature to be added to Thor, please add specs to ensure that it does not break in the future.” This will help move a pull request closer to being merged.

Include this emoji in the top of your ticket to signal to us that you read this file: 🌈

Specs Copy Chapter

Ensure that all specs and code linting checks pass before submitting a pull request.

To execute the specs locally, run:

bundle exec rspec

Linting checks are done with RuboCop. To run the linter, use:

bundle exec rubocop

File: LICENSE.md Copy Chapter

Copyright (c) 2008 Yehuda Katz, Eric Hodel, et al.

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.

File: .rubocop.yml Copy Chapter

AllCops:
TargetRubyVersion: 2.6
DisabledByDefault: true
SuggestExtensions: false
Exclude:
- spec/sandbox//
- spec/fixtures//
- vendor/bundle//

Style/HashSyntax:
EnforcedStyle: ruby19

No spaces inside hash literals

Layout/SpaceInsideHashLiteralBraces:
EnforcedStyle: no_space

Enforce outdenting of access modifiers (i.e. public, private, protected)

Layout/AccessModifierIndentation:
EnforcedStyle: outdent

Layout/EmptyLinesAroundAccessModifier:
Enabled: true

Align ends correctly

Layout/EndAlignment:
EnforcedStyleAlignWith: variable
Exclude:
- 'lib/thor/actions.rb'
- 'lib/thor/error.rb'
- 'lib/thor/shell/basic.rb'
- 'lib/thor/parser/option.rb'

Indentation of when/else

Layout/CaseIndentation:
EnforcedStyle: end
IndentOneStep: false

Style/StringLiterals:
EnforcedStyle: double_quotes

Lint/AssignmentInCondition:
Exclude:
- 'lib/thor/line_editor/readline.rb'
- 'lib/thor/parser/arguments.rb'

Security/Eval:
Exclude:
- 'spec/helper.rb'

Lint/SuppressedException:
Exclude:
- 'lib/thor/line_editor/readline.rb'

Lint/PercentStringArray:
Exclude:
- 'spec/parser/options_spec.rb'

Lint/UnusedMethodArgument:
Exclude:
- 'lib/thor.rb'
- 'lib/thor/base.rb'
- 'lib/thor/command.rb'
- 'lib/thor/parser/arguments.rb'
- 'lib/thor/shell/html.rb'
- 'spec/actions/empty_directory_spec.rb'
- 'spec/fixtures/invoke.thor'

Naming/AccessorMethodName:
Exclude:
- 'lib/thor/line_editor/basic.rb'
- 'spec/fixtures/group.thor'
- 'spec/sandbox/group.thor'

Style/ClassAndModuleChildren:
Exclude:
- 'lib/thor/group.rb'
- 'lib/thor/runner.rb'
- 'spec/shell_spec.rb'
- 'spec/util_spec.rb'

Style/ClassVars:
Exclude:
- 'lib/thor/util.rb'
- 'spec/util_spec.rb'

Naming/ConstantName:
Exclude:
- 'spec/line_editor_spec.rb'

Style/GlobalVars:
Exclude:
- 'bin/thor'
- 'lib/thor.rb'
- 'lib/thor/base.rb'
- 'lib/thor/shell/basic.rb'
- 'spec/helper.rb'
- 'spec/rake_compat_spec.rb'
- 'spec/register_spec.rb'
- 'spec/thor_spec.rb'

Layout/FirstArrayElementIndentation:
EnforcedStyle: consistent

Lint/MissingSuper:
Exclude:
- 'lib/thor/error.rb'
- 'spec/rake_compat_spec.rb'

Style/MissingRespondToMissing:
Exclude:
- 'lib/thor/core_ext/hash_with_indifferent_access.rb'
- 'lib/thor/runner.rb'
- 'spec/fixtures/script.thor'
- 'spec/sandbox/script.thor'

Style/NumericLiteralPrefix:
Exclude:
- 'spec/actions/file_manipulation_spec.rb'

Style/NumericPredicate:
Exclude:
- 'spec/**/*'
- 'lib/thor/parser/option.rb'

Style/PerlBackrefs:
Exclude:
- 'lib/thor/actions/empty_directory.rb'
- 'lib/thor/core_ext/hash_with_indifferent_access.rb'
- 'lib/thor/parser/arguments.rb'
- 'lib/thor/parser/options.rb'

Style/TrailingUnderscoreVariable:
Exclude:
- 'lib/thor/group.rb'

Layout/TrailingWhitespace:
Exclude:
- 'spec/shell/basic_spec.rb'

File: .devcontainer/devcontainer.json Copy Chapter

{
"name": "thor",
"image": "ghcr.io/rails/devcontainer/images/ruby:4.0.0",

"features": {
"ghcr.io/devcontainers/features/github-cli:1": {}
}

}

File: .github/dependabot.yml Copy Chapter

version: 2
updates:

• package-ecosystem: "github-actions"
  directory: "/"
  schedule:
  interval: "weekly"

File: .github/workflows/lint.yml Copy Chapter

name: Run linters
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: ruby/setup-ruby@v1
with:
ruby-version: 3.1
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
- run: bundle exec rubocop

File: .github/workflows/release.yml Copy Chapter

name: Release

on:
release:
types: [published]

jobs:
release:
permissions:
contents: write
id-token: write

environment: release

runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v7
- name: Set up Ruby
  uses: ruby/setup-ruby@v1
  with:
    bundler-cache: true
    ruby-version: 3.4.4
- name: Configure trusted publishing credentials
  uses: rubygems/[email protected]
- name: Run release rake task
  run: bundle exec thor release
  shell: bash
- name: Wait for release to propagate
  run: gem exec rubygems-await pkg/*.gem
  shell: bash

File: .github/workflows/tests.yml Copy Chapter

name: Run tests
on: [push, pull_request]
permissions:
contents: read

jobs:
test:
strategy:
fail-fast: false
matrix:
ruby: ['2.6', '2.7', '3.0', '3.1', '3.2', '3.3', '3.4', '4.0', 'head']
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: ruby/setup-ruby@v1
with:
ruby-version: ${{ matrix.ruby }}
bundler: ${{ (matrix.ruby < '3' && '2.4.21') || 'latest' }}
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
- run: bundle exec thor spec