Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Reorganize RuboCop help into sections for better clarity #10132

Merged
merged 1 commit into from Sep 28, 2021
Merged

Reorganize RuboCop help into sections for better clarity #10132

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
237 changes: 125 additions & 112 deletions lib/rubocop/options.rb
View file
Open in desktop
Expand Up @@ -59,86 +59,111 @@ def args_from_env

def define_options
OptionParser.new do |opts|
opts.banner = 'Usage: rubocop [options] [file1, file2, ...]'
opts.banner = rainbow.wrap('Usage: rubocop [options] [file1, file2, ...]').bright

add_list_options(opts)
add_only_options(opts)
add_configuration_options(opts)
add_formatting_options(opts)

option(opts, '-r', '--require FILE') { |f| require_feature(f) }

add_severity_option(opts)
add_flags_with_optional_args(opts)
add_check_options(opts)
add_cache_options(opts)
add_boolean_flags(opts)
add_aliases(opts)
add_output_options(opts)
add_autocorrection_options(opts)
add_config_generation_options(opts)
add_additional_modes(opts)
add_general_options(opts)
end
end

def add_check_options(opts) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
section(opts, 'Basic Options') do
option(opts, '-l', '--lint') do
@options[:only] ||= []
@options[:only] << 'Lint'
end
option(opts, '-x', '--fix-layout') do
@options[:only] ||= []
@options[:only] << 'Layout'
@options[:auto_correct] = true
end
option(opts, '--safe')
add_cop_selection_csv_option('except', opts)
add_cop_selection_csv_option('only', opts)
option(opts, '--only-guide-cops')
option(opts, '-F', '--fail-fast')
option(opts, '--disable-pending-cops')
option(opts, '--enable-pending-cops')
option(opts, '--ignore-disable-comments')
option(opts, '--force-exclusion')
option(opts, '--only-recognized-file-types')
option(opts, '--ignore-parent-exclusion')
option(opts, '--force-default-config')
option(opts, '-s', '--stdin FILE')
option(opts, '-P', '--[no-]parallel')
add_severity_option(opts)
end
end

def add_only_options(opts)
add_cop_selection_csv_option('except', opts)
add_cop_selection_csv_option('only', opts)
option(opts, '--only-guide-cops')
end
def add_output_options(opts) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
section(opts, 'Output Options') do
option(opts, '-f', '--format FORMATTER') do |key|
@options[:formatters] ||= []
@options[:formatters] << [key]
end

def add_cop_selection_csv_option(option, opts)
option(opts, "--#{option} [COP1,COP2,...]") do |list|
unless list
message = "--#{option} argument should be [COP1,COP2,...]."
option(opts, '-D', '--[no-]display-cop-names')
option(opts, '-E', '--extra-details')
option(opts, '-S', '--display-style-guide')

raise OptionArgumentError, message
option(opts, '-o', '--out FILE') do |path|
if @options[:formatters]
@options[:formatters].last << path
else
@options[:output_path] = path
end
end

@options[:"#{option}"] = list.empty? ? [''] : list.split(',')
option(opts, '--stderr')
option(opts, '--display-time')
option(opts, '--display-only-failed')
option(opts, '--display-only-fail-level-offenses')
end
end

def add_configuration_options(opts)
option(opts, '-c', '--config FILE')
option(opts, '--force-exclusion')
option(opts, '--only-recognized-file-types')
option(opts, '--ignore-parent-exclusion')
option(opts, '--force-default-config')
add_auto_gen_options(opts)
end

def add_auto_gen_options(opts)
option(opts, '--auto-gen-config')

option(opts, '--regenerate-todo') do
@options.replace(ConfigRegeneration.new.options.merge(@options))
def add_autocorrection_options(opts)
section(opts, 'Auto-correction') do
option(opts, '-a', '--auto-correct') { @options[:safe_auto_correct] = true }
option(opts, '--safe-auto-correct') do
warn '--safe-auto-correct is deprecated; use --auto-correct'
@options[:safe_auto_correct] = @options[:auto_correct] = true
end
option(opts, '-A', '--auto-correct-all') { @options[:auto_correct] = true }
option(opts, '--disable-uncorrectable')
end
end

option(opts, '--exclude-limit COUNT') { @validator.validate_exclude_limit_option }
def add_config_generation_options(opts)
section(opts, 'Config Generation') do
option(opts, '--auto-gen-config')

option(opts, '--disable-uncorrectable')
option(opts, '--regenerate-todo') do
@options.replace(ConfigRegeneration.new.options.merge(@options))
end

option(opts, '--[no-]offense-counts')
option(opts, '--[no-]auto-gen-only-exclude')
option(opts, '--[no-]auto-gen-timestamp')
option(opts, '--exclude-limit COUNT') { @validator.validate_exclude_limit_option }

option(opts, '--init')
option(opts, '--[no-]offense-counts')
option(opts, '--[no-]auto-gen-only-exclude')
option(opts, '--[no-]auto-gen-timestamp')
end
end

def add_formatting_options(opts)
option(opts, '-f', '--format FORMATTER') do |key|
@options[:formatters] ||= []
@options[:formatters] << [key]
end
def add_cop_selection_csv_option(option, opts)
option(opts, "--#{option} [COP1,COP2,...]") do |list|
unless list
message = "--#{option} argument should be [COP1,COP2,...]."

option(opts, '-o', '--out FILE') do |path|
if @options[:formatters]
@options[:formatters].last << path
else
@options[:output_path] = path
raise OptionArgumentError, message
end
end

option(opts, '--display-time')
option(opts, '--display-only-failed')
@options[:"#{option}"] = list.empty? ? [''] : list.split(',')
end
end

def add_severity_option(opts)
Expand All @@ -148,62 +173,50 @@ def add_severity_option(opts)
table) do |severity|
@options[:fail_level] = severity
end
option(opts, '--display-only-fail-level-offenses')
end

def add_flags_with_optional_args(opts)
option(opts, '--show-cops [COP1,COP2,...]') do |list|
@options[:show_cops] = list.nil? ? [] : list.split(',')
def add_cache_options(opts)
section(opts, 'Caching') do
option(opts, '-C', '--cache FLAG')
option(opts, '--cache-root DIR') { @validator.validate_cache_enabled_for_cache_root }
end
end

def add_cache_options(opts)
option(opts, '-C', '--cache FLAG')
option(opts, '--cache-root DIR') { @validator.validate_cache_enabled_for_cache_root }
end

# rubocop:disable Metrics/MethodLength, Metrics/AbcSize
def add_boolean_flags(opts)
option(opts, '-F', '--fail-fast')
option(opts, '-d', '--debug')
option(opts, '-D', '--[no-]display-cop-names')
option(opts, '-E', '--extra-details')
option(opts, '-S', '--display-style-guide')
option(opts, '-a', '--auto-correct') { @options[:safe_auto_correct] = true }
option(opts, '--safe-auto-correct') do
warn '--safe-auto-correct is deprecated; use --auto-correct'
@options[:safe_auto_correct] = @options[:auto_correct] = true
def add_additional_modes(opts)
section(opts, 'Additional Modes') do
option(opts, '-L', '--list-target-files')
option(opts, '--show-cops [COP1,COP2,...]') do |list|
@options[:show_cops] = list.nil? ? [] : list.split(',')
end
end
option(opts, '-A', '--auto-correct-all') { @options[:auto_correct] = true }
option(opts, '--disable-pending-cops')
option(opts, '--enable-pending-cops')
option(opts, '--ignore-disable-comments')

option(opts, '--safe')

option(opts, '--stderr')
option(opts, '--[no-]color')

option(opts, '-v', '--version')
option(opts, '-V', '--verbose-version')
option(opts, '-P', '--[no-]parallel')
end
# rubocop:enable Metrics/MethodLength, Metrics/AbcSize

def add_aliases(opts)
option(opts, '-l', '--lint') do
@options[:only] ||= []
@options[:only] << 'Lint'
def add_general_options(opts)
section(opts, 'General Options') do
option(opts, '--init')
option(opts, '-c', '--config FILE')
option(opts, '-d', '--debug')
option(opts, '-r', '--require FILE') { |f| require_feature(f) }
option(opts, '--[no-]color')
option(opts, '-v', '--version')
option(opts, '-V', '--verbose-version')
end
option(opts, '-x', '--fix-layout') do
@options[:only] ||= []
@options[:only] << 'Layout'
@options[:auto_correct] = true
end

def rainbow
@rainbow ||= begin
rainbow = Rainbow.new
rainbow.enabled = false if ARGV.include?('--no-color')
rainbow
end
end

def add_list_options(opts)
option(opts, '-L', '--list-target-files')
# Creates a section of options in order to separate them visually when
# using `--help`.
def section(opts, heading, &_block)
heading = rainbow.wrap(heading).bright
opts.separator("\n#{heading}:\n")
yield
end

# Sets a value in the @options hash, based on the given long option and its
Expand Down Expand Up @@ -403,7 +416,7 @@ module OptionsHelp
only: 'Run only the given cop(s).',
only_guide_cops: ['Run only cops for rules that link to a',
'style guide.'],
except: 'Disable the given cop(s).',
except: 'Exclude the given cop(s).',
require: 'Require Ruby file.',
config: 'Specify configuration file.',
auto_gen_config: ['Generate a configuration file acting as a',
Expand All @@ -422,29 +435,29 @@ module OptionsHelp
'when running --auto-gen-config, except if the',
'number of files with offenses is bigger than',
'exclude-limit. Default is false.'],
exclude_limit: ['Used together with --auto-gen-config to',
'set the limit for how many Exclude',
"properties to generate. Default is #{MAX_EXCL}."],
exclude_limit: ['Set the limit for how many files to explicitly exclude.',
'If there are more files than the limit, the cop will',
"be disabled instead. Default is #{MAX_EXCL}."],
disable_uncorrectable: ['Used with --auto-correct to annotate any',
'offenses that do not support autocorrect',
'with `rubocop:todo` comments.'],
force_exclusion: ['Force excluding files specified in the',
'configuration `Exclude` even if they are',
'explicitly passed as arguments.'],
force_exclusion: ['Any files excluded by `Exclude` in configuration files',
'will be excluded, even if given explictly as arguments.'],
only_recognized_file_types: ['Inspect files given on the command line only if',
'they are listed in AllCops/Include parameters',
'they are listed in `AllCops/Include` parameters',
'of user configuration or default configuration.'],
ignore_disable_comments: ['Run cops even when they are disabled locally',
'with a comment.'],
ignore_parent_exclusion: ['Prevent from inheriting AllCops/Exclude from',
'by a `rubocop:disable` directive.'],
ignore_parent_exclusion: ['Prevent from inheriting `AllCops/Exclude` from',
'parent folders.'],
force_default_config: ['Use default configuration even if configuration',
'files are present in the directory tree.'],
format: ['Choose an output formatter. This option',
'can be specified multiple times to enable',
'multiple formatters at the same time.',
'[p]rogress is used by default',
*FORMATTER_OPTION_LIST.map { |item| " #{item}" },
*FORMATTER_OPTION_LIST.map do |item|
" #{item}#{' (default)' if item == '[p]rogress'}"
end,
' custom formatter class name'],
out: ['Write output to a file instead of STDOUT.',
'This option applies to the previously',
Expand Down