Skip to content

Update README regarding --quiet, --debug, --simulate, --sort etc. to close #821 - #838

Merged
mathiasrw merged 7 commits into
mainfrom
fix/821
Oct 23, 2026
Merged

mathiasrw merged 7 commits into
mainfrom
fix/821

Conversation

@mathiasrw

@mathiasrw mathiasrw commented Oct 23, 2026 •

Copy link
Copy Markdown
Owner

Closes #821

Stacked on #837.

Change

Eight things in the README and the help that were not true:

  1. The "Hairy details" example with --name-delimiter now has --sort natural, as without it the order is not fixed.
  2. --quiet hides the names and the warnings, but not the errors, and not the content of --output or the matches of --output-match.
  3. --debug prints the status report and hides the rest, except the content of --output and the matches of --output-match.
  4. The first layer of the replacement now says that escapes like \n and \t are read too.
  5. The help of --sort says ascii is by char code, so B comes before a. It said "alphabetic".
  6. The help of --literal-replacement says it only takes the meaning from the $ signs. The € and § aliases and the escapes are part of what is typed, and are still used.
  7. The help of --simulate: "Execute everything during a run except the changes RexReplace would normally make to the file system. Code from --js still runs, and can change data even with --simulate." It said the content is printed, but only the names are.
  8. The README says --trim-file trims the content, like the line break at the end. It said it only takes away the line break.

Tests

Only docs and help text. yarn test-ci passes.

From the review of 23 October.

After the review of 24 October

  • The first layer of the replacement says that the escapes are read in typed text, but in --js code javascript reads them, and the path of --replacement-file is used as it is, with no aliases or escapes (Use the path of --replacement-file as it is, with no escapes and no aliases to close #817 #834).
  • The list of what the aliases never touch has the path of --replacement-file too.
  • The help and README of --quiet say what it does: it hides the names and the warnings, and the errors, the content of --output and the matches of --output-match are still shown. It said "Only display errors".
  • The devguide no longer says that --debug prints only the status report.

Follow-up

The README line of --js says it shorter, the same as the help in #830: "For speed, the code runs once per file unless it names the match, a group, $m or $M."

Follow-up

The README line on named groups says it shorter, the same as the help in #832: "Access a named group via the name prepended with rr_. (?<year>...) gives you rr_year. A named group name can not end with _."

Follow-up

Shorter help and README lines for --literal-replacement, --quiet, --simulate and --sort.

@mathiasrw
mathiasrw marked this pull request as draft October 23, 2026 13:05
@mathiasrw
mathiasrw marked this pull request as ready for review October 23, 2026 13:26
mathiasrw added a commit that referenced this pull request Oct 23, 2026
@mathiasrw
mathiasrw added this pull request to stack #841 October 23, 2026 13:56
@mathiasrw
mathiasrw marked this pull request as draft October 23, 2026 14:59
@mathiasrw
mathiasrw marked this pull request as ready for review October 23, 2026 15:03
@mathiasrw
mathiasrw marked this pull request as draft October 23, 2026 15:10
@mathiasrw
mathiasrw marked this pull request as ready for review October 23, 2026 15:13
@mathiasrw
mathiasrw marked this pull request as draft October 23, 2026 15:42
@mathiasrw mathiasrw changed the title Make the README and the help true about --quiet, --debug, --simulate, --sort and more to close #821 Update README regarding --quiet, --debug, --simulate, --sort etc. to close #821 Oct 23, 2026
@mathiasrw
mathiasrw marked this pull request as ready for review October 23, 2026 15:45
@mathiasrw
mathiasrw removed this pull request from stack #841 October 23, 2026 15:57
@mathiasrw
mathiasrw added this pull request to stack #849 October 23, 2026 16:12
@mathiasrw
mathiasrw removed this pull request from stack #849 October 23, 2026 16:12
@mathiasrw
mathiasrw added this pull request to stack #850 October 23, 2026 16:17
@mathiasrw
mathiasrw marked this pull request as draft October 23, 2026 16:29
@mathiasrw
mathiasrw marked this pull request as ready for review October 23, 2026 16:31
mathiasrw added a commit that referenced this pull request Oct 23, 2026
* Give a panic and not a stack trace when a path can not be looked at

* Stop starting new files after a panic with --halt

* Read the piped paths of --glob-pipe as UTF-8

* Remove control characters from the new names of --rename

* Give a message and not a crash when --js code throws something that is not an error

* Name a thrown error whose message can not be read, and cut a big thrown object short

* Tell where --js code failed in a module with --verbose

* Read each line of the stack, skip what is not the code of the user, and never crash on it

* Only make the --js numbers the code uses, and only count files for $i and $c

* Tell in the help that only the numbers the code names are made

* Leave the README line of --js to #838, so the stack can be rebased without a conflict

* Shorter --js help on which numbers are made and when the code runs per match

* Give the code of --js all the numbers as values, and count the files for $i without a search of their own
@mathiasrw
mathiasrw removed this pull request from stack #850 October 23, 2026 16:47
@mathiasrw
mathiasrw added this pull request to stack #853 October 23, 2026 16:51
mathiasrw added a commit that referenced this pull request Oct 23, 2026
* Give a panic and not a stack trace when a path can not be looked at

* Stop starting new files after a panic with --halt

* Read the piped paths of --glob-pipe as UTF-8

* Remove control characters from the new names of --rename

* Give a message and not a crash when --js code throws something that is not an error

* Name a thrown error whose message can not be read, and cut a big thrown object short

* Tell where --js code failed in a module with --verbose

* Read each line of the stack, skip what is not the code of the user, and never crash on it

* Only make the --js numbers the code uses, and only count files for $i and $c

* Tell in the help that only the numbers the code names are made

* Leave the README line of --js to #838, so the stack can be rebased without a conflict

* Let --js code declare the names of the numbers and groups with let and const

* Test --js code that declares a cousin with const, a number with var, and a function
mathiasrw added a commit that referenced this pull request Oct 23, 2026
* Give a panic and not a stack trace when a path can not be looked at

* Stop starting new files after a panic with --halt

* Read the piped paths of --glob-pipe as UTF-8

* Remove control characters from the new names of --rename

* Give a message and not a crash when --js code throws something that is not an error

* Name a thrown error whose message can not be read, and cut a big thrown object short

* Tell where --js code failed in a module with --verbose

* Read each line of the stack, skip what is not the code of the user, and never crash on it

* Only make the --js numbers the code uses, and only count files for $i and $c

* Tell in the help that only the numbers the code names are made

* Leave the README line of --js to #838, so the stack can be rebased without a conflict

* Let --js code declare the names of the numbers and groups with let and const

* Use the prefix rr_ for named groups in --js, and panic on a name that ends with _

* Do not panic on a group name that ends with _ under --output-match

* Test named groups with uppercase, numbers, $ and the space cousin, and say the rr_ help shorter
@mathiasrw
mathiasrw force-pushed the fix/821 branch 4 times, most recently from 5871def to 721aa9f Compare October 23, 2026 17:02
Base automatically changed from fix/820 to main October 23, 2026 17:03
@mathiasrw
mathiasrw merged commit 40a4e57 into main Oct 23, 2026
6 of 7 checks passed
@mathiasrw
mathiasrw deleted the fix/821 branch October 23, 2026 17:12
mathiasrw added a commit that referenced this pull request Oct 23, 2026
* Give a panic and not a stack trace when a path can not be looked at

* Stop starting new files after a panic with --halt

* Read the piped paths of --glob-pipe as UTF-8

* Remove control characters from the new names of --rename

* Give a message and not a crash when --js code throws something that is not an error

* Name a thrown error whose message can not be read, and cut a big thrown object short

* Tell where --js code failed in a module with --verbose

* Read each line of the stack, skip what is not the code of the user, and never crash on it

* Only make the --js numbers the code uses, and only count files for $i and $c

* Tell in the help that only the numbers the code names are made

* Leave the README line of --js to #838, so the stack can be rebased without a conflict

* Let --js code declare the names of the numbers and groups with let and const

* Use the prefix rr_ for named groups in --js, and panic on a name that ends with _

* Do not panic on a group name that ends with _ under --output-match

* Find named groups with letters that are not ASCII in --js

* Read the named groups from the regex, and see rr_year_ on its own

* Use the path of --replacement-file as it is, with no escapes and no aliases

* Tell why a replacement file can not be read, and only once

* Show the reason in words, and the path as it is unless it hides a char

* Sort a file that is gone before the sort last, and do not crash

* Only sort a deleted file last, and give other stat errors their reason

* Make the natural order the same on Node and Bun, and in every locale

* Run the test of the natural order with --sort

* Make the README and the help true about --quiet, --debug, --simulate, --sort and more

* Make the README and help true about --quiet, --debug and the escapes

* Tell in the README that only the --js numbers the code names are made

* End the run as usual when the reader of a pipe stops early

* Put the detail of an error on its own line under the message
mathiasrw added a commit that referenced this pull request Oct 23, 2026
* Give a panic and not a stack trace when a path can not be looked at

* Stop starting new files after a panic with --halt

* Read the piped paths of --glob-pipe as UTF-8

* Remove control characters from the new names of --rename

* Give a message and not a crash when --js code throws something that is not an error

* Name a thrown error whose message can not be read, and cut a big thrown object short

* Tell where --js code failed in a module with --verbose

* Read each line of the stack, skip what is not the code of the user, and never crash on it

* Only make the --js numbers the code uses, and only count files for $i and $c

* Tell in the help that only the numbers the code names are made

* Leave the README line of --js to #838, so the stack can be rebased without a conflict

* Let --js code declare the names of the numbers and groups with let and const

* Use the prefix rr_ for named groups in --js, and panic on a name that ends with _

* Do not panic on a group name that ends with _ under --output-match

* Find named groups with letters that are not ASCII in --js

* Read the named groups from the regex, and see rr_year_ on its own

* Use the path of --replacement-file as it is, with no escapes and no aliases

* Tell why a replacement file can not be read, and only once

* Show the reason in words, and the path as it is unless it hides a char

* Sort a file that is gone before the sort last, and do not crash

* Only sort a deleted file last, and give other stat errors their reason

* Make the natural order the same on Node and Bun, and in every locale

* Run the test of the natural order with --sort

* Make the README and the help true about --quiet, --debug, --simulate, --sort and more

* Make the README and help true about --quiet, --debug and the escapes

* Tell in the README that only the --js numbers the code names are made

* End the run as usual when the reader of a pipe stops early

* Take in the newest commits of the PRs below, so the cleanup is made on the code that will be merged

* Simplify the engine, split the status from the output, and name functions by what they do
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fix things in the README and help that are not true

1 participant