From feb93167ad7930b8121dbd0018a338d4cdd5a88f Mon Sep 17 00:00:00 2001 From: Rylan Polster Date: Tue, 4 Jan 2022 23:29:12 -0500 Subject: [PATCH] Rename and fix `Formatter:wrap` to `Formatter.format_help_text` --- Library/Homebrew/cli/parser.rb | 6 +-- Library/Homebrew/cmd/update.sh | 12 +++--- Library/Homebrew/help.rb | 2 +- Library/Homebrew/test/formatter_spec.rb | 55 +++++++++++++++++++++++++ Library/Homebrew/utils/formatter.rb | 12 ++++-- manpages/brew.1 | 2 +- 6 files changed, 74 insertions(+), 15 deletions(-) diff --git a/Library/Homebrew/cli/parser.rb b/Library/Homebrew/cli/parser.rb index 159f3ddf85..b440514fc0 100644 --- a/Library/Homebrew/cli/parser.rb +++ b/Library/Homebrew/cli/parser.rb @@ -9,7 +9,7 @@ require "set" require "utils/tty" COMMAND_DESC_WIDTH = 80 -OPTION_DESC_WIDTH = 43 +OPTION_DESC_WIDTH = 45 HIDDEN_DESC_PLACEHOLDER = "@@HIDDEN@@" module Homebrew @@ -351,7 +351,7 @@ module Homebrew end def generate_help_text - Formatter.wrap(@parser.to_s, COMMAND_DESC_WIDTH) + Formatter.format_help_text(@parser.to_s, width: COMMAND_DESC_WIDTH) .gsub(/\n.*?@@HIDDEN@@.*?(?=\n)/, "") .sub(/^/, "#{Tty.bold}Usage: brew#{Tty.reset} ") .gsub(/`(.*?)`/m, "#{Tty.bold}\\1#{Tty.reset}") @@ -503,7 +503,7 @@ module Homebrew end def wrap_option_desc(desc) - Formatter.wrap(desc, OPTION_DESC_WIDTH).split("\n") + Formatter.format_help_text(desc, width: OPTION_DESC_WIDTH).split("\n") end def set_constraints(name, depends_on:, required_for:) diff --git a/Library/Homebrew/cmd/update.sh b/Library/Homebrew/cmd/update.sh index 8dd610a604..6e6693c829 100644 --- a/Library/Homebrew/cmd/update.sh +++ b/Library/Homebrew/cmd/update.sh @@ -2,12 +2,12 @@ #: #: Fetch the newest version of Homebrew and all formulae from GitHub using `git`(1) and perform any necessary migrations. #: -#: --merge Use `git merge` to apply updates (rather than `git rebase`). -#: --preinstall Run on auto-updates (e.g. before `brew install`). Skips some slower steps. -#: -f, --force Always do a slower, full update check (even if unnecessary). -#: -v, --verbose Print the directories checked and `git` operations performed. -#: -d, --debug Display a trace of all shell commands as they are executed. -#: -h, --help Show this message. +#: --merge Use `git merge` to apply updates (rather than `git rebase`). +#: --preinstall Run on auto-updates (e.g. before `brew install`). Skips some slower steps. +#: -f, --force Always do a slower, full update check (even if unnecessary). +#: -v, --verbose Print the directories checked and `git` operations performed. +#: -d, --debug Display a trace of all shell commands as they are executed. +#: -h, --help Show this message. # HOMEBREW_CURLRC, HOMEBREW_DEVELOPER, HOMEBREW_GIT_EMAIL, HOMEBREW_GIT_NAME # HOMEBREW_UPDATE_CLEANUP, HOMEBREW_UPDATE_TO_TAG are from the user environment diff --git a/Library/Homebrew/help.rb b/Library/Homebrew/help.rb index 817d83160e..fba154d8e0 100644 --- a/Library/Homebrew/help.rb +++ b/Library/Homebrew/help.rb @@ -118,7 +118,7 @@ module Homebrew help_lines = command_help_lines(path) return if help_lines.blank? - Formatter.wrap(help_lines.join, COMMAND_DESC_WIDTH) + Formatter.format_help_text(help_lines.join, width: COMMAND_DESC_WIDTH) .sub("@hide_from_man_page ", "") .sub(/^\* /, "#{Tty.bold}Usage: brew#{Tty.reset} ") .gsub(/`(.*?)`/m, "#{Tty.bold}\\1#{Tty.reset}") diff --git a/Library/Homebrew/test/formatter_spec.rb b/Library/Homebrew/test/formatter_spec.rb index 95e87ea486..ddb8804e16 100644 --- a/Library/Homebrew/test/formatter_spec.rb +++ b/Library/Homebrew/test/formatter_spec.rb @@ -56,4 +56,59 @@ describe Formatter do it { is_expected.to eq("\n") } end end + + describe "::format_help_text" do + it "indents subcommand descriptions" do + # The following example help text was carefully crafted to test all five regular expressions in the method. + # Also, the text is designed in such a way such that options (e.g. `--foo`) would be wrapped to the + # beginning of new lines if normal wrapping was used. This is to test that the method works as expected + # and doesn't allow options to start new lines. Be careful when changing the text so these checks aren't lost. + text = <<~HELP + Usage: brew command [] ... + + This is a test command. + Single line breaks are removed, but the entire line is still wrapped at the correct point. + + Paragraphs are preserved but + are also wrapped at the right point. Here's some more filler text to get this line to be long enough. + Options, for example: --foo, are never placed at the start of a line. + + `brew command` [`state`]: + Display the current state of the command. + + `brew command` (`on`|`off`): + Turn the command on or off respectively. + + -f, --foo This line is wrapped with a hanging indent. --test. The --test option isn't at the start of a line. + -b, --bar The following option is not left on its own: --baz + -h, --help Show this message. + HELP + + expected = <<~HELP + Usage: brew command [] ... + + This is a test command. Single line breaks are removed, but the entire line is + still wrapped at the correct point. + + Paragraphs are preserved but are also wrapped at the right point. Here's some + more filler text to get this line to be long enough. Options, for + example: --foo, are never placed at the start of a line. + + `brew command` [`state`]: + Display the current state of the command. + + `brew command` (`on`|`off`): + Turn the command on or off respectively. + + -f, --foo This line is wrapped with a hanging + indent. --test. The --test option isn't at + the start of a line. + -b, --bar The following option is not left on its + own: --baz + -h, --help Show this message. + HELP + + expect(described_class.format_help_text(text, width: 80)).to eq expected + end + end end diff --git a/Library/Homebrew/utils/formatter.rb b/Library/Homebrew/utils/formatter.rb index 1d88df0540..eabd47549a 100644 --- a/Library/Homebrew/utils/formatter.rb +++ b/Library/Homebrew/utils/formatter.rb @@ -45,15 +45,19 @@ module Formatter # with a hanging indent, without breaking any words that overflow # 4. wrap any remaining description lines that need wrapping with the same indent # 5. wrap all lines to the given width. + # + # Note that an option (e.g. `--foo`) may not be at the beginning of a line, + # so we always wrap one word before an option. + # @see https://github.com/Homebrew/brew/pull/12672 # @see https://macromates.com/blog/2006/wrapping-text-with-regular-expressions/ - def wrap(s, width = 172) + def format_help_text(s, width: 172) desc = OPTION_DESC_WIDTH indent = width - desc s.gsub(/(?<=\S) *\n(?=\S)/, " ") .gsub(/([`>)\]]:) /, "\\1\n ") - .gsub(/^( +-.+ +(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)\n?/, "\\1\\2\n#{" " * indent}") - .gsub(/^( {#{indent}}(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)\n?/, "\\1\\2\n#{" " * indent}") - .gsub(/(.{1,#{width}})( +|$)\n?/, "\\1\n") + .gsub(/^( +-.+ +(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)(?!-)\n?/, "\\1\\2\n#{" " * indent}") + .gsub(/^( {#{indent}}(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)(?!-)\n?/, "\\1\\2\n#{" " * indent}") + .gsub(/(.{1,#{width}})( +|$)(?!-)\n?/, "\\1\n") end def url(string) diff --git a/manpages/brew.1 b/manpages/brew.1 index 640949ff8f..bfb54dfe0f 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "BREW" "1" "December 2021" "Homebrew" "brew" +.TH "BREW" "1" "January 2022" "Homebrew" "brew" . .SH "NAME" \fBbrew\fR \- The Missing Package Manager for macOS (or Linux)