admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

Better man page formatting

Browse Source
This commit is contained in:
Gautham Goli 2018-09-08 22:21:04 +05:30
parent 83e7cbe5c5
commit c7bf79407a
No known key found for this signature in database
GPG Key ID: 6A9ABBC284468364
8 changed files with 181 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
Library/Homebrew/cli_parser.rb
View File

@ -5,6 +5,8 @@ require "set"
module Homebrew
module CLI
class Parser
attr_reader :processed_options
def self.parse(args = ARGV, &block)
new(&block).parse(args)
end
@ -16,32 +18,31 @@ module Homebrew
Homebrew.args.instance_eval { undef tap }
@constraints = []
@conflicts = []
@processed_options = []
@desc_line_length = 48
instance_eval(&block)
post_initialize
end
def post_initialize
@parser.on_tail("-h", "--help", "Show this message") do
puts @parser
xyz = @parser.summarize([], 8, 44, " "*8).map do |r|
if r.match?(/^\s{12}\S/)
"\n" + r.gsub(" "*12, " "*8)
elsif r.start_with?(" "*17)
r.gsub(" "*17, " "*11)
else
"\n" + r
puts @parser.to_s.sub(/^/, "#{Tty.bold}Usage: brew#{Tty.reset} ")
.gsub(/`(.*?)`/, "#{Tty.bold}\\1#{Tty.reset}")
.gsub(%r{<([^\s]+?://[^\s]+?)>}) { |url| Formatter.url(url) }
.gsub(/<(.*?)>/, "#{Tty.underline}\\1#{Tty.reset}")
end
end
puts xyz
exit
end
def wrap_option_desc(desc)
Formatter.wrap(desc, @desc_line_length).split("\n")
end
def switch(*names, description: nil, env: nil, required_for: nil, depends_on: nil)
global_switch = names.first.is_a?(Symbol)
names, env, description = common_switch(*names) if global_switch
description = option_to_description(*names) if description.nil?
@parser.on(*names, *description.split("\n")) do
process_option(*names, description)
@parser.on(*names, *wrap_option_desc(description)) do
enable_switch(*names)
end
@ -52,13 +53,18 @@ module Homebrew
enable_switch(*names) if !env.nil? && !ENV["HOMEBREW_#{env.to_s.upcase}"].nil?
end
def banner(text)
def usage_banner(text)
@parser.banner = text
end
def usage_banner_text
@parser.banner
end
def comma_array(name, description: nil)
description = option_to_description(name) if description.nil?
@parser.on(name, OptionParser::REQUIRED_ARGUMENT, Array, *description.split("\n")) do |list|
process_option(name, description)
@parser.on(name, OptionParser::REQUIRED_ARGUMENT, Array, *wrap_option_desc(description)) do |list|
Homebrew.args[option_to_name(name)] = list
end
end
@ -71,7 +77,8 @@ module Homebrew
required = OptionParser::OPTIONAL_ARGUMENT
end
description = option_to_description(name) if description.nil?
@parser.on(name, *description.split("\n"), required) do |option_value|
process_option(name, description)
@parser.on(name, *wrap_option_desc(description), required) do |option_value|
Homebrew.args[option_to_name(name)] = option_value
end
@ -122,10 +129,10 @@ module Homebrew
# These are common/global switches accessible throughout Homebrew
def common_switch(name)
case name
when :quiet then [["-q", "--quiet"], :quiet, "Suppress warnings."]
when :verbose then [["-v", "--verbose"], :verbose, "Verbose mode."]
when :debug then [["-d", "--debug"], :debug, "Display debug info."]
when :force then [["-f", "--force"], :force, "Override any warnings/validations."]
when :quiet then [["-q", "--quiet"], :quiet, "Suppress any warnings."]
when :verbose then [["-v", "--verbose"], :verbose, "Make some output more verbose."]
when :debug then [["-d", "--debug"], :debug, "Display any debugging information."]
when :force then [["-f", "--force"], :force, "Override warnings and enable potentially unsafe operations."]
else name
end
end
@ -187,6 +194,11 @@ module Homebrew
check_conflicts
check_constraints
end
def process_option(*args)
option, = @parser.make_switch(args)
@processed_options << [option.short.first, option.long.first, option.arg, option.desc.first]
end
end
class OptionConstraintError < RuntimeError

44
Library/Homebrew/dev-cmd/audit.rb
View File

@ -54,8 +54,8 @@ module Homebrew
def audit_args
Homebrew::CLI::Parser.new do
banner <<~EOS
Usage: brew audit [options] [<formulae>]
usage_banner <<~EOS
`audit` [<options>] [<formulae>]:
Check <formulae> for Homebrew coding style violations. This should be
run before submitting a new formula.
@ -63,17 +63,37 @@ module Homebrew
If no <formulae> are provided, all of them are checked.
EOS
switch "--strict", description: "Run additional style checks, including Rubocop style checks."
switch "--online", description: "Run additional slower style checks that require a\nnetwork connection."
switch "--new-formula", description: "Run various additional style checks to determine if a new formula \nis eligible for Homebrew. This should be used when creating \nnew formula and implies --strict and --online."
switch "--fix", description: "Fix style violations automatically using\nRuboCop's auto-correct feature."
switch "--display-cop-names", description: "Include the RuboCop cop name for each violation\nin the output."
switch "--display-filename", description: "Prefix everyline of output with name of the file or\nformula being audited, to make output easy to grep."
switch "--strict", description: "Run additional style checks, "\
"including Rubocop style checks."
switch "--online", description: "Run additional slower style checks "\
"that require a network connection."
switch "--new-formula", description: "Run various additional style checks "\
"to determine if a new formula is eligible "\
"for Homebrew. This should be used when "\
"creating new formula and implies "\
"`--strict` and `--online`."
switch "--fix", description: "Fix style violations automatically using "\
"RuboCop's auto-correct feature."
switch "--display-cop-names", description: "Include the RuboCop cop name for each "\
"violation in the output."
switch "--display-filename", description: "Prefix everyline of output with name of "\
"the file or formula being audited, to "\
"make output easy to grep."
switch "-D", "--audit-debug", description: "Activates debugging and profiling"
comma_array "--only", description: "Passing --only=method will run only the methods named audit_method,\n`method` should be a comma-separated list."
comma_array "--except", description: "Passing --except=method will run only the methods named audit_method,\n`method` should be a comma-separated list."
comma_array "--only-cops", description: "Passing --only-cops=cops will check for violations of only the listed\nRuboCop cops. `cops` should be a comma-separated list of cop names."
comma_array "--except-cops", description: "Passing --except-cops=cops will skip checking the listed\nRuboCop cops violations. `cops` should be a comma-separated list of cop names."
comma_array "--only", description: "Passing `--only`=<method> will run only the"\
"methods named audit_method, `method` should "\
"be a comma-separated list."
comma_array "--except", description: "Passing `--except`=<method> will run only the "\
"methods named audit_method, `method` should "\
"be a comma-separated list."
comma_array "--only-cops", description: "Passing `--only-cops`=<cops> will check for "\
"violations of only the listed RuboCop cops."\
"`cops` should be a comma-separated list of "\
"cop names."
comma_array "--except-cops", description: "Passing `--except-cops`=<cops> will "\
"skip checking the listed RuboCop cops "\
"violations. `cops` should be a "\
"comma-separated list of cop names."
switch :verbose
switch :debug
end

22
Library/Homebrew/dev-cmd/man.rb
View File

@ -69,7 +69,7 @@ module Homebrew
variables = OpenStruct.new
variables[:commands] = path_glob_commands("#{HOMEBREW_LIBRARY_PATH}/cmd/*.{rb,sh}")
variables[:developer_commands] = [Homebrew.send(:audit_args).summary] + path_glob_commands("#{HOMEBREW_LIBRARY_PATH}/dev-cmd/*.{rb,sh}")
variables[:developer_commands] = generate_cmd_manpage(Homebrew.send(:audit_args)) + path_glob_commands("#{HOMEBREW_LIBRARY_PATH}/dev-cmd/*.{rb,sh}")
readme = HOMEBREW_REPOSITORY/"README.md"
variables[:lead_maintainer] =
readme.read[/(Homebrew's lead maintainer .*\.)/, 1]
@ -150,4 +150,24 @@ module Homebrew
odie "Failed to infer output format from '#{target.basename}'."
end
end
def generate_cmd_manpage(cmd_parser)
lines = [cmd_parser.usage_banner_text]
lines += cmd_parser.processed_options.map do |short, long, _, desc|
generate_option_doc(short, long, desc)
end
lines
end
def generate_option_doc(short, long, desc)
"* #{format_short_opt(short)} #{format_long_opt(long)}:" + "\n" + desc + "\n"
end
def format_short_opt(opt)
"`#{opt}`, " unless opt.nil?
end
def format_long_opt(opt)
"`#{opt}`".ljust(30)
end
end

1
Library/Homebrew/dev-cmd/release-notes.rb
View File

@ -15,6 +15,7 @@ module Homebrew
switch "--markdown"
end
end
def release_notes
release_notes_args.parse

1
Library/Homebrew/dev-cmd/tests.rb
View File

@ -33,6 +33,7 @@ module Homebrew
flag "--seed="
end
end
def tests
tests_args.parse

4
Library/Homebrew/utils/formatter.rb
View File

@ -31,6 +31,10 @@ module Formatter
label(label, string, :red)
end
def wrap(s, width = 172)
s.gsub(/(.{1,#{width}})(\s+|\Z)/, "\\1\n")
end
def url(string)
"#{Tty.underline}#{string}#{Tty.no_underline}"
end

65
docs/Manpage.md
View File

@ -663,37 +663,52 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
## DEVELOPER COMMANDS
Usage: brew audit [options] [`formulae`]
`audit` [`options`] [`formulae`]:
Check `formulae` for Homebrew coding style violations. This should be
run before submitting a new formula.
If no `formulae` are provided, all of them are checked.
--strict Run additional style checks, including Rubocop style checks.
--online Run additional slower style checks that require a
network connection.
--new-formula Run various additional style checks to determine if a new formula
is eligible for Homebrew. This should be used when creating
new formula and implies --strict and --online.
--fix Fix style violations automatically using
RuboCop's auto-correct feature.
--display-cop-names Include the RuboCop cop name for each violation
in the output.
--display-filename Prefix everyline of output with name of the file or
formula being audited, to make output easy to grep.
-D, --audit-debug Activates debugging and profiling
--only Passing --only=method will run only the methods named audit_method,
`method` should be a comma-separated list.
--except Passing --except=method will run only the methods named audit_method,
`method` should be a comma-separated list.
--only-cops Passing --only-cops=cops will check for violations of only the listed
RuboCop cops. `cops` should be a comma-separated list of cop names.
--except-cops Passing --except-cops=cops will skip checking the listed
RuboCop cops violations. `cops` should be a comma-separated list of cop names.
-v, --verbose Verbose mode.
-d, --debug Display debug info.
-h, --help Show this message
* `--strict` :
Run additional style checks, including Rubocop style checks.
* `--online` :
Run additional slower style checks that require a network connection.
* `--new-formula` :
Run various additional style checks to determine if a new formula is eligible for Homebrew. This should be used when creating new formula and implies `--strict` and `--online`.
* `--fix` :
Fix style violations automatically using RuboCop's auto-correct feature.
* `--display-cop-names` :
Include the RuboCop cop name for each violation in the output.
* `--display-filename` :
Prefix everyline of output with name of the file or formula being audited, to make output easy to grep.
* `-D`, `--audit-debug` :
Activates debugging and profiling
* `--only` :
Passing `--only`=`method` will run only themethods named audit_method, `method` should be a comma-separated list.
* `--except` :
Passing `--except`=`method` will run only the methods named audit_method, `method` should be a comma-separated list.
* `--only-cops` :
Passing `--only-cops`=`cops` will check for violations of only the listed RuboCop cops.`cops` should be a comma-separated list of cop names.
* `--except-cops` :
Passing `--except-cops`=`cops` will skip checking the listed RuboCop cops violations. `cops` should be a comma-separated list of cop names.
* `-v`, `--verbose` :
Make some output more verbose.
* `-d`, `--debug` :
Display any debugging information.
* `audit` [`--strict`] [`--fix`] [`--online`] [`--new-formula`] [`--display-cop-names`] [`--display-filename`] [`--only=``method`|`--except=``method`] [`--only-cops=``cops`|`--except-cops=``cops`] [`formulae`]:
Check `formulae` for Homebrew coding style violations. This should be

80
manpages/brew.1
View File

@ -601,7 +601,7 @@ If the command\'s output is sent through a pipe and no shell is specified, the l
.IP "" 0
.
.SH "DEVELOPER COMMANDS"
Usage: brew audit [options] [\fIformulae\fR]
\fBaudit\fR [\fIoptions\fR] [\fIformulae\fR]:
.
.P
Check \fIformulae\fR for Homebrew coding style violations\. This should be run before submitting a new formula\.
@ -609,38 +609,57 @@ Check \fIformulae\fR for Homebrew coding style violations\. This should be run b
.P
If no \fIformulae\fR are provided, all of them are checked\.
.
.IP "" 4
.TP
\fB\-\-strict\fR
Run additional style checks, including Rubocop style checks\.
.
.nf
\-\-strict Run additional style checks, including Rubocop style checks\.
\-\-online Run additional slower style checks that require a
network connection\.
\-\-new\-formula Run various additional style checks to determine if a new formula
is eligible for Homebrew\. This should be used when creating
new formula and implies \-\-strict and \-\-online\.
\-\-fix Fix style violations automatically using
RuboCop\'s auto\-correct feature\.
\-\-display\-cop\-names Include the RuboCop cop name for each violation
in the output\.
\-\-display\-filename Prefix everyline of output with name of the file or
formula being audited, to make output easy to grep\.
\-D, \-\-audit\-debug Activates debugging and profiling
\-\-only Passing \-\-only=method will run only the methods named audit_method,
`method` should be a comma\-separated list\.
\-\-except Passing \-\-except=method will run only the methods named audit_method,
`method` should be a comma\-separated list\.
\-\-only\-cops Passing \-\-only\-cops=cops will check for violations of only the listed
RuboCop cops\. `cops` should be a comma\-separated list of cop names\.
\-\-except\-cops Passing \-\-except\-cops=cops will skip checking the listed
RuboCop cops violations\. `cops` should be a comma\-separated list of cop names\.
\-v, \-\-verbose Verbose mode\.
\-d, \-\-debug Display debug info\.
\-h, \-\-help Show this message
.TP
\fB\-\-online\fR
Run additional slower style checks that require a network connection\.
.
.fi
.TP
\fB\-\-new\-formula\fR
Run various additional style checks to determine if a new formula is eligible for Homebrew\. This should be used when creating new formula and implies \fB\-\-strict\fR and \fB\-\-online\fR\.
.
.IP "" 0
.TP
\fB\-\-fix\fR
Fix style violations automatically using RuboCop\'s auto\-correct feature\.
.
.TP
\fB\-\-display\-cop\-names\fR
Include the RuboCop cop name for each violation in the output\.
.
.TP
\fB\-\-display\-filename\fR
Prefix everyline of output with name of the file or formula being audited, to make output easy to grep\.
.
.TP
\fB\-D\fR, \fB\-\-audit\-debug\fR
Activates debugging and profiling
.
.TP
\fB\-\-only\fR
Passing \fB\-\-only\fR=\fImethod\fR will run only themethods named audit_method, \fBmethod\fR should be a comma\-separated list\.
.
.TP
\fB\-\-except\fR
Passing \fB\-\-except\fR=\fImethod\fR will run only the methods named audit_method, \fBmethod\fR should be a comma\-separated list\.
.
.TP
\fB\-\-only\-cops\fR
Passing \fB\-\-only\-cops\fR=\fIcops\fR will check for violations of only the listed RuboCop cops\.\fBcops\fR should be a comma\-separated list of cop names\.
.
.TP
\fB\-\-except\-cops\fR
Passing \fB\-\-except\-cops\fR=\fIcops\fR will skip checking the listed RuboCop cops violations\. \fBcops\fR should be a comma\-separated list of cop names\.
.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Make some output more verbose\.
.
.TP
\fB\-d\fR, \fB\-\-debug\fR
Display any debugging information\.
.
.TP
\fBaudit\fR [\fB\-\-strict\fR] [\fB\-\-fix\fR] [\fB\-\-online\fR] [\fB\-\-new\-formula\fR] [\fB\-\-display\-cop\-names\fR] [\fB\-\-display\-filename\fR] [\fB\-\-only=\fR\fImethod\fR|\fB\-\-except=\fR\fImethod\fR] [\fB\-\-only\-cops=\fR\fIcops\fR|\fB\-\-except\-cops=\fR\fIcops\fR] [\fIformulae\fR]
@ -945,6 +964,7 @@ If \fB\-\-to\-tag\fR is passed, set \fBHOMEBREW_UPDATE_TO_TAG\fR to test updatin
.
.IP
If \fB\-\-keep\-tmp\fR is passed, retain the temporary directory containing the new repository clone\.
.
.SH "OFFICIAL EXTERNAL COMMANDS"
.