Skip to content

Commit

Permalink
Reorganize RuboCop help into sections for better clarity.
Browse files Browse the repository at this point in the history
  • Loading branch information
@dvandersluis @bbatsov
dvandersluis authored and bbatsov committed Sep 28, 2021
1 parent eed36a1 commit 1ea71be
Show file tree
Hide file tree
Showing 2 changed files with 202 additions and 177 deletions.
237 changes: 125 additions & 112 deletions lib/rubocop/options.rb
View file
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

0 comments on commit 1ea71be

Please sign in to comment.