Command line help
rxedit is a folding “batch editor” for source code, inspired by IBM’s XEDIT editor, optimized for source code discovery and with optional editing capabilities.
Commands progressively show or hide lines, using regular expressions.
Editing operations - loosely modelled on sed - affect only visible lines and
can include user confirmation.
For supported languages, tree-sitter provides added functionality.
Edits are not persisted until requested by the user.
Example: show all lines containing TODO and 2 lines afterwards, using the A2 flag (similar to a grep -A 2)
, hide “low priority” lines and show case-insentitive “urgent”:
rxedit myfile.txt all::TODO::A2 'less::low priority' more::urgent::i
Visibility commands:
allshow only matching linesmoreshow more matching lineslesshide matching linesinvertinvert visibilitylinesdisplays lines within ranges, similar to a posix head or tail
Editing commands:
deletedelete visible, matching, lineschangeregex replacement on visible lines. Supports the full Rust regex syntax.prependadd a line before the matching lineappendadd a line after the matching line
Language-dependent commands (will become no-ops if the language is not supported)
(currently supports: .py and .rs extensions)
declarationslook for class, struct or function names that match.importslook for include, import or use lines that match the name
Utility commands:
macroloads commands from a given file, allowing predefinition of search and exclusion patternsexplainstderr what rxedit has understood, and rejected, from user input.
Flags (not all commands support all flags, see their individual help)
icase insensitive.Ffixed string, meaning that “string contains” will be used, rather than a regex match.A10,B2,C1- similar to usinggrep -A 10 -B 2…oowner flag - shows the function or class signature to which a matching lines belongsbbody flag - only avaiable ondeclarationscommands, shows all lines for a function or class.wt=fs. Fordeclarationsonly: filters the types of definitions we are interested in. On Rust,fswould matchfnorstruct.uuser confirmation, match by match, ondeleteorchangecommands.sk=debug.Setskey=debugon matching lines. This can be used to constrain further commands usingwk.wk=debug.In addition to any match conditions, the command will only affect lines withkey=debugset.ln=1..10.In addition to any match conditions the command will only affect the first 10 lines.
Flags are designed to be mixed freely together in any order:
more::debug::A2sk=devonly.i will recognize A2, case insensitive and setting key=devonly on matching lines.
Error handling
Unknown commands, malformed flags, and unsupported language-specific operations are treated as no-ops to allow for quicker experimentation.
Use explain to see how rxedit interpreted your command sequence. And fine-tune your visible lines
before adding editing commands,
Command line syntax:
Usage: rxedit [OPTIONS] [FILE_PATH] [COMMANDS]...
Arguments:
[FILE_PATH]
[COMMANDS]...
Options:
-h, --help [<TOPIC>] Print help (optionally for a topic)
-f, --commands-file <COMMANDS_FILE> prepend commands from the given file
-F, --commands-file-after <COMMANDS_FILE_AFTER> append commands from the given file
-o, --output-file <OUTPUT_FILE> write buffer to the given output file. Note that everything gets written, not just the visible lines.
-R, --report-file <REPORT_FILE> write only visibles to file.
-O, --in-place-output modify file directly
-s, --spacer separate blocks of displayed lines
-n, --line-number show line numbers (those will diverge from the source file change on [`delete`](./commands/delete.md), [`append`](./commands/append.md) or [`prepend`](./commands/prepend.md) use)
-N, --suppress-line-number don't show line numbers (those will diverge from the source file change on [`delete`](./commands/delete.md), [`append`](./commands/append.md) or [`prepend`](./commands/prepend.md) use)
-v, --verbose
--debug debug messages
--dump-json print the parsed hashtree JSON and exit
-g, --grep-shortcodes expands shortcodes (`..`→`.*`,`~~s.`→` +` ...)
-G, --no-grep-shortcodes does not expand grep shortcodes
--gen-config generate user config file if it does not exist
-c, --config <FILE> load config from the given file
--no-empty-write don't write outputs with -o -O or -R flags if empty
Common workflow:
- Show lines (all, more)
- Hide lines (less)
- Edit/delete (change, delete)
- Save (-O or -o)
Commands use: COMMAND::PATTERN::FLAGS
Examples:
Show all lines containing TODO and 2 lines afterwards, using the A2 flag
Equivalent to grep -A 2 TODO myfile.txt
rxedit myfile.txt all::TODO::A2
Show all lines with error, hide those with log, also show those with print in upper or lower case.
explain prints how rxedit interpreted the commands out to stderr.
rxedit myfile.txt -n a::error:: less::log more::print::i explain
Show all fn, trait… with a name matching regex m[ay] which are not under a parent tests
as in mod tests {...}). The trailing ::b is the flag that shows those functions’ bodies.
The quotes are necessary to avoid shell interactions.
rxedit main.rs 'd::-tests/m[ay]::b'
Shows all lines with dbg! or print and deletes visible lines matching dbg!.
The -O flag modifies the file in place, use it after getting the command sequence right.
rxedit formatters.rs 'm::dbg!|print' 'delete::dbg!' -O
Shows all lines with dbg! and uses change via regex group names to comment them out.
there is no -O yet, so you can fine tune what you are commenting out first.
rxedit formatters.rs 'm::dbg!' 'change::([\s]*)([^\s].*$)::$1//$2'
Uses a macro:: file to show user-determined indicators of “chattiness” in Python
rxedit pysample.py macro ./showpychatty.rxi
showpychatty.rxi contents:
````
#these are typical debugging prints to console
m::^\s*(print|debug|pp|inspect)\(
#and these will hide lines that are already commented out.
less::^\s*#
````
Same as above, after user has hidden lines 32 and 35 that they want to keep after all, delete and overwrite the file
rxedit pysample.py macro ./showpychatty.rxi less::::ln=32,35 delete -O
Extract all the active log calls to a report file. Note the use of the invert before delete: first we
identify all the lines we want to extract, then we invert the visibility in order to delete all those we don’t want.
rxedit main.py 'm::log\.[a-z]+\(' 'less:: *//' invert delete -o logging.rpt
Keep in mind:
-
By default, nothing is saved, but
-Oallows modifying the file in place while-o <path>allows writing to a file.-
Both types of outputs write everything that is in the buffer, visible or not.
-
rxedit makes no assumption about the correctness of code changes. Deleting or commenting out code may cause errors. Preferably, use it on version-controlled files.
-
-
Tree-sitter is used to recognize functions, classes and imports, provided the file extension matches a known language (currently, .rs and .py). Commands like
declarations::will result in no-ops when there is no matching grammar. -
As much as possible, user error in entering commands and command flags will be ignored and will result in do-nothing operations and ignored flag directives.
-
Use the
explaincommand to get feedback on what it understood or not. -
Risk: If you display lots of lines, then want to use
lessto hide some before editing what’s left this could be a problem. For example, if you mistypedless:keep-this!(notice the mistyped::field separator) , immediately followed by adelete.
-
─────────────────────────────
REMINDER
Visibility: all replace visible set more add matches less remove matches invert invert visible set
Editing: change regex replace delete delete visible lines
Language-specific: declarations search for class, function or struct definitions by name. imports show include, import or use, depending on language.
Safety: explain shows how your commands were interpreted or ignored. writes use -O only after verifying output and preferably use on version-controlled files.
Examples: rxedit file ‘all::TODO’ ‘more::print::i’
Final Example with sample output:
rxedit pysample.py declarations d::add::b less::__init__ more::print less::history::i
000005 def do_init(func):
000009 class Calculator:
000017 def add(self, a: int, b: int) -> int:
000018 """Add two numbers ."""
000019 result_add = a + b
000021 return result_add
000023 def multiply(self, a: int,
000024 b: int) -> int:
000037 print(f" {entry}")
Command All - [a]ll
Hides everything, then shows matching lines.
show lines matching Greet, case-insentive:
(equivalent to grep -i Greet sample.rs)
rxedit sample.rs a::Greet::i
Output
trait Greeter {
fn greet(&self, name: &str) -> String;
impl Greeter for HelloApp {
fn greet(&self, name: &str) -> String {
app.greet("world")
More examples:
rxedit sample.rs a::Greet::Fiwould do the same thing, but match as a fixed, case-insentive, stringrxedit sample.rs a::Greeter::A1will work likegrep -A 1 Greeter sample.rs
Search flags
| Name | Format | Example | Description |
|---|---|---|---|
| insensitive | i | ::i | case-insentive search |
| after | A(\d+) | ::A16 | Show NUM lines after each match. |
| before | B(\d+) | ::B5 | Show NUM lines before each match. |
| context | C(\d+) | ::C5 | Show NUM lines before and after each match. |
| fixed_string | F | ::F | treat search as regular string, not a regex |
| use_grep_shortcodes | g | ::g | expands shortcodes (..→.*, ~~s.→ +) |
| no_use_grep_shortcodes | G | ::G | does not expand grep shortcodes |
| show_owner | o | ::o | show “owner” of the line |
| set key | sk=([a-z]+)(?:.|/|$) | ::sk=importan | / set key to a value that can be used with wk= |
| where_key | wk=([a-z]+)(?:.|/|$) | ::wk=mykey/ | puts an extra criteria to other commands |
| where_linenum | wl=([-0-9A-Ca-chtHT,.]+) | ::wl=..5,8,-1/ | limit line number range |
SEE ALSO
Command more - [m]ore
Shows matching lines.
Example: show ‘message’
rxedit sample.rs more::message::o
more::messageshows lines matchingmessage.::ofor a supported language, the “owner” (class, function, struct, etc…) gets shown
Output
fn make_message() -> String {
fn print_message(message: &str) {
println!("{message}");
fn main() {
let message = make_message();
print_message(&message);
More examples:
rxedit sample.rs m::message::oFisame thing, but match as a fixed, case-insentive stringrxedit sample.rs m::message::A2likegrep -A 2 message sample.rsrxedit sample.rs 'm::print..\(::g'uses..shortcode to show any line matchingprint*(
Search flags
| Name | Format | Example | Description |
|---|---|---|---|
| insensitive | i | ::i | case-insentive search |
| after | A(\d+) | ::A16 | Show NUM lines after each match. |
| before | B(\d+) | ::B5 | Show NUM lines before each match. |
| context | C(\d+) | ::C5 | Show NUM lines before and after each match. |
| fixed_string | F | ::F | treat search as regular string, not a regex |
| use_grep_shortcodes | g | ::g | expands shortcodes (..→.*, ~~s.→ +) |
| no_use_grep_shortcodes | G | ::G | does not expand grep shortcodes |
| show_owner | o | ::o | show “owner” of the line |
| set key | sk=([a-z]+)(?:.|/|$) | ::sk=importan | / set key to a value that can be used with wk= |
| where_key | wk=([a-z]+)(?:.|/|$) | ::wk=mykey/ | puts an extra criteria to other commands |
| where_linenum | wl=([-0-9A-Ca-chtHT,.]+) | ::wl=..5,8,-1/ | limit line number range |
SEE ALSO
Command less - [l]ess
Hides matching lines.
Example: hide “print_”
rxedit sample.rs 'a::fn.*_message' less::print_
a::fn.*_messageonly lines matching the regexfn.*_messageare shown.- This regex is quoted because the shell may interpret special characters.
less::print_hides lines that containprint_.
Output
fn make_message() -> String {
fn always_pass_message(){
Search flags
| Name | Format | Example | Description |
|---|---|---|---|
| insensitive | i | ::i | case-insentive search |
| after | A(\d+) | ::A16 | Show NUM lines after each match. |
| before | B(\d+) | ::B5 | Show NUM lines before each match. |
| context | C(\d+) | ::C5 | Show NUM lines before and after each match. |
| fixed_string | F | ::F | treat search as regular string, not a regex |
| use_grep_shortcodes | g | ::g | expands shortcodes (..→.*, ~~s.→ +) |
| no_use_grep_shortcodes | G | ::G | does not expand grep shortcodes |
| show_owner | o | ::o | show “owner” of the line |
| set key | sk=([a-z]+)(?:.|/|$) | ::sk=importan | / set key to a value that can be used with wk= |
| where_key | wk=([a-z]+)(?:.|/|$) | ::wk=mykey/ | puts an extra criteria to other commands |
| where_linenum | wl=([-0-9A-Ca-chtHT,.]+) | ::wl=..5,8,-1/ | limit line number range |
SEE ALSO
Remark:
The [A]fter / [B]efore / [C]ontext flags don’t work for now. They’re there because the intent is to hide matching lines and then hide before/after lines.
Command invert
Flips visibility for every line. Anything that was visible becomes invisible
and vice versa. Useful to extract matching lines for a report. First show
everything you want, then invert, then delete.
Example: extract the public API from a rust file.
rxedit lib.rs d::--tests 'and::^pub ' invert delete all
d::-tests/shows all declarations, not undermod tests'and::^pub 'keep only those lines withpubkeywordinvertflips visibility.delete::removes currently visible lines, i.e. not a public definitionallshow all lines. (In practice use something like-o signatures.outto write to a report file)
Output:
pub trait CommandActions {
pub enum Command {
pub fn make_command(arg: &str) -> Command {
pub fn commands_factory(args: &[String]) -> Vec<Command> {
Invert flags:
| Name | Forma | Exampl | Description |
|---|
Notes:
invert has no flags or payload
SEE ALSO
Command lines
Show lines within the given ranges. Similar to head - <number> or tail - <number>, with a number of possible specifier.
Example: show lines between 2 and 5, inclusive
rxedit pysample.py lines::2..5 -n
Output
000002 from pathlib import Path
000003
000004
000005 def do_init(func):
Supported format, for lines and as used in the wl= flag.
x..ymeans a from x - to y range. Omitting x means “from the start”, omitting y means “to the end”. x has to be <= y.- all numbers are 1-based, inclusive
,separates different groups,/indicates the end of the specifier (when used as a flag)- negative indexing means count from the end, with -1 being the last line, -2 next to last, similar to Python’s use
handtact likeheadandtailcommand, whileA,B,Cbehave like they do ingrep
Examples
| Specifier | Meaning |
|---|---|
| lines::2..5 | skip line 1, then display up to line 5 |
| lines::-1 | last line |
| lines::t5 | last 5 lines |
| lines::-5.. | last 5 lines |
| lines::h3 | first 3 lines |
| lines::-5..-3 | same as tail -5, but skip the last 2 |
| lines::30C5 | display lines 25-35 |
| lines::..2,t5 | first 2, last 5 |
| lines::.. | all lines |
Sample use of line ranges in other commands:
rxedit pysample.py all::DEF::wl=30C5i
Note that it wasn’t necessary to terminate the flag with / because this flag always ends with . or a digit anyway. So i meant case-insensitive.
Output
000031 def show_history(self) -> None:
More examples:
-
rxedit pysample.py lines::h5,30..show lines 1-5 and 30 to the end of the file -
rxedit pysample.py lines::1,3,5show lines 1,3 and 5
Lines flags
| Name | Format | Example | Description |
|---|---|---|---|
| set key | sk=([a-z]+)(?:.|/| | ) ::sk=importan | / set key to a value that can be used with wk= |
| where_key | wk=([a-z]+)(?:.|/| | ) ::wk=mykey/ | puts an extra criteria to other commands |
Command and
Hide already visible lines that do not match the pattern/conditions given.
Python example: show only classes and special __ methods.
rxedit pysample.py d:: 'and::__|class '
Output
class Calculator:
def __init__(self, name: str):
Using wk=... where key
rxedit pysample.py d:: d::_::sk=underscores and::::wk=underscores
This is a bit contrived, but the second d:: is setting key=underscores to all
declarations that have _ in their name.
and will then remove any lines that do NOT have key=underscores set.
Output
def do_init(func):
def __init__(self, name: str):
def show_history(self) -> None:
keep classes as well, but only within first 20 lines
rxedit pysample.py d:: d::_::sk=keep d::::wt=c.sk=keep and::::wk=keep.wl=..20
d::- show all declarationsd::_::sk=keep- set any declarations with_in their names as key=keepd::::wt=c.sk=keep- usewt=ci..e where type = class to set any class to key=keepand::::wk=keep.wl=..20only show visible lines where key=keep and within lines 1 to 20.
Output:
def do_init(func):
class Calculator:
def __init__(self, name: str):
and flags
| Name | Format | Example | Description |
|---|---|---|---|
| after | A(\d+) | ::A16 | Show NUM lines after each match. |
| before | B(\d+) | ::B5 | Show NUM lines before each match. |
| context | C(\d+) | ::C5 | Show NUM lines before and after each match. |
| insensitive | i | ::i | case-insentive search |
| fixed_string | F | ::F | treat search as regular string, not a regex |
| use_grep_shortcodes | g | ::g | expands shortcodes (..→.*, ~~s.→ +) |
| no_use_grep_shortcodes | G | ::G | does not expand grep shortcodes |
| set key | sk=([a-z]+)(?:.|/|$) | ::sk=importan | / set key to a value that can be used with wk= |
| where_key | wk=([a-z]+)(?:.|/|$) | ::wk=mykey/ | puts an extra criteria to other commands |
| where_linenum | wl=([-0-9A-Ca-chtHT,.]+) | ::wl=..5,8,-1/ | limit line number range |
SEE ALSO
Command Delete - [del]ete
Deletes visible lines matching pattern.
Example delete visible lines containing “debug”
rxedit sample.rs a::debug delete:debug
Details
deleteremoves lines from the output entirely (not just hiding them).- use
lessor set key / where key (sk=,wk=) to constraint the scope.
delete flags
| Name | Format | Example | Description |
|---|---|---|---|
| insensitive | i | ::i | case-insentive search |
| after | A(\d+) | ::A16 | Show NUM lines after each match. |
| before | B(\d+) | ::B5 | Show NUM lines before each match. |
| context | C(\d+) | ::C5 | Show NUM lines before and after each match. |
| fixed_string | F | ::F | treat search as regular string, not a regex |
| use_grep_shortcodes | g | ::g | expands shortcodes (..→.*, ~~s.→ +) |
| no_use_grep_shortcodes | G | ::G | does not expand grep shortcodes |
| show_owner | o | ::o | show “owner” of the line |
| set key | sk=([a-z]+)(?:.|/|$) | ::sk=importan | / set key to a value that can be used with wk= |
| where_key | wk=([a-z]+)(?:.|/|$) | ::wk=mykey/ | puts an extra criteria to other commands |
| where_linenum | wl=([-0-9A-Ca-chtHT,.]+) | ::wl=..5,8,-1/ | limit line number range |
Notes about commands that modify the text
- Nothing gets saved until you use the
-Omodify in place flag or the-o <some path>output flag. - Those commands only apply to matching visible lines, unlike say a
sedinsert or delete. append,prepend,deletewill throw off the line numbers used inwhere lineflags- When modifying a source code file, the result may not be syntaxically correct, so be careful.
- rxedit is designed on the expectation that modification commands will be used on version-controlled files.
- but you could use the
-o myfile.bakflag to save and diff your changes first.
- Use
explainto make sure all previous commands to show/hide lines went as expected. - Modification commands support the
::uuser confirmation flag, which will prompt the user for confirmation.- Use of that flag will, by design, trigger an immediate error in batch mode.
- rxedit will “follow” symlinks so it will affect the actual file if you modify it.
SEE ALSO
shortcodes, chaining, noop, flags
Command Change - [c]hange
Change contents visible lines matching pattern, similar to sed.
Example: remove “//v2help” comments.
First step is to make lines visible, via rxedit help_utilities.rs m:://v2help::o
pub fn print_topic_help(topic: &str, config_path: &str) -> Result<(), String> {
"explain" => { //v2help
"all" => { //v2help
"and" => { //v2help
...(more lines)...
Then change them:
rxedit help_utilities.rs m:://v2help::o change:://v2help::::
The -O flag will modify the file in place, when you use it.
pub fn print_topic_help(topic: &str, config_path: &str) -> Result<(), String> {
"explain" => {
"all" => {
"and" => {
...(more lines)...
Example: comment out source code
change really ends up calling Rust’s Regex crate under the cover, so things that are
syntaxically correct for that crate work here as well.
rxedit -n pysample.py m::print::osk=tocomment
Show all lines with “print” and their owner. Set key=tocomment.
Output pass 1
000031 def show_history(self) -> None:
000035 print(f"\n{self.name}'s History:")
000037 print(f" {entry}")
rxedit -n pysample.py m::print::osk=tocomment less::::wl=35 'c::([\s]*)([^\s].*$)::$1#$2::wk=tocomment'
Remove line 35 from scope and then use regex implicit group names to comment things out.
Note how “show_history” was not affected, because ::wk=tocomment filtered it out on the change
Output pass 2
000031 def show_history(self) -> None:
000037 #print(f" {entry}")
Since that “comment out” is complicated to remember, you can save it in a macro file instead.
(Be mindful about setting sk=tocomment if you keep wk=tocomment in the macro.)
rxedit -n pysample.py m::print::osk=tocomment less::::wl=35 macro pycommentout.rxi
prepend/append flags
| Name | Format | Example | Description |
|---|---|---|---|
| change_all | a | ::a | user confirmation |
| insensitive | i | ::i | case-insentive search |
| fixed_string | F | ::F | treat search as regular string, not a regex |
| use_grep_shortcodes | g | ::g | expands shortcodes (..→.*, ~~s.→ +) |
| no_use_grep_shortcodes | G | ::G | does not expand grep shortcodes |
| where_key | wk=([a-z]+)(?:.|/| | ) ::wk=myke | / puts an extra criteria to other commands |
| user_confirm | u | ::u | user confirmation |
Notes about commands that modify the text
- Nothing gets saved until you use the
-Omodify in place flag or the-o <some path>output flag. - Those commands only apply to matching visible lines, unlike say a
sedinsert or delete. append,prepend,deletewill throw off the line numbers used inwhere lineflags- When modifying a source code file, the result may not be syntaxically correct, so be careful.
- rxedit is designed on the expectation that modification commands will be used on version-controlled files.
- but you could use the
-o myfile.bakflag to save and diff your changes first.
- Use
explainto make sure all previous commands to show/hide lines went as expected. - Modification commands support the
::uuser confirmation flag, which will prompt the user for confirmation.- Use of that flag will, by design, trigger an immediate error in batch mode.
- rxedit will “follow” symlinks so it will affect the actual file if you modify it.
SEE ALSO
shortcodes, chaining, noop, flags
Commands prepend and append
These two commands behave much like a sed i and sed a, respectively.
i.e. when the condition matches a new line will be inserted before or after the match line.
Unlike sed however, this command only affects visible lines.
Take note of the -I [indent_keep] flag.
Example: show definitions matching “init”, then add a hello comment before them.
rxedit pysample.py d::/init 'prepend::init::#hello'
class Calculator:
#hello
def __init__(self, name: str):
Example: Match the existing indentation
rxedit pysample.py d::/init::A2 'append::init:: "init function"::I'
Note how using A2 on the initial declarations command can allow the user
to determine how much leading whitespace to use.
class Calculator:
def __init__(self, name: str):
"init function"
# a comment
self.name = name
prepend/append flags
| Name | Format | Example | Description |
|---|---|---|---|
| insensitive | i | ::i | case-insentive search |
| indent_keep | I | ::I | keep matching line’s indentation |
| fixed_string | F | ::F | treat search as regular string, not a regex |
| use_grep_shortcodes | g | ::g | expands shortcodes (..→.*, ~~s.→ +) |
| no_use_grep_shortcodes | G | ::G | does not expand grep shortcodes |
| where_key | wk=([a-z]+)(?:.|/| | ) ::wk=myke | / puts an extra criteria to other commands |
| user_confirm | u | ::u | user confirmation |
Notes about commands that modify the text
- Nothing gets saved until you use the
-Omodify in place flag or the-o <some path>output flag. - Those commands only apply to matching visible lines, unlike say a
sedinsert or delete. append,prepend,deletewill throw off the line numbers used inwhere lineflags- When modifying a source code file, the result may not be syntaxically correct, so be careful.
- rxedit is designed on the expectation that modification commands will be used on version-controlled files.
- but you could use the
-o myfile.bakflag to save and diff your changes first.
- Use
explainto make sure all previous commands to show/hide lines went as expected. - Modification commands support the
::uuser confirmation flag, which will prompt the user for confirmation.- Use of that flag will, by design, trigger an immediate error in batch mode.
- rxedit will “follow” symlinks so it will affect the actual file if you modify it.
SEE ALSO
shortcodes, chaining, noop, flags
Commands prepend and append
These two commands behave much like a sed i and sed a, respectively.
i.e. when the condition matches a new line will be inserted before or after the match line.
Unlike sed however, this command only affects visible lines.
Take note of the -I [indent_keep] flag.
Example: show definitions matching “init”, then add a hello comment before them.
rxedit pysample.py d::/init 'prepend::init::#hello'
class Calculator:
#hello
def __init__(self, name: str):
Example: Match the existing indentation
rxedit pysample.py d::/init::A2 'append::init:: "init function"::I'
Note how using A2 on the initial declarations command can allow the user
to determine how much leading whitespace to use.
class Calculator:
def __init__(self, name: str):
"init function"
# a comment
self.name = name
prepend/append flags
| Name | Format | Example | Description |
|---|---|---|---|
| insensitive | i | ::i | case-insentive search |
| indent_keep | I | ::I | keep matching line’s indentation |
| fixed_string | F | ::F | treat search as regular string, not a regex |
| use_grep_shortcodes | g | ::g | expands shortcodes (..→.*, ~~s.→ +) |
| no_use_grep_shortcodes | G | ::G | does not expand grep shortcodes |
| where_key | wk=([a-z]+)(?:.|/| | ) ::wk=myke | / puts an extra criteria to other commands |
| user_confirm | u | ::u | user confirmation |
Notes about commands that modify the text
- Nothing gets saved until you use the
-Omodify in place flag or the-o <some path>output flag. - Those commands only apply to matching visible lines, unlike say a
sedinsert or delete. append,prepend,deletewill throw off the line numbers used inwhere lineflags- When modifying a source code file, the result may not be syntaxically correct, so be careful.
- rxedit is designed on the expectation that modification commands will be used on version-controlled files.
- but you could use the
-o myfile.bakflag to save and diff your changes first.
- Use
explainto make sure all previous commands to show/hide lines went as expected. - Modification commands support the
::uuser confirmation flag, which will prompt the user for confirmation.- Use of that flag will, by design, trigger an immediate error in batch mode.
- rxedit will “follow” symlinks so it will affect the actual file if you modify it.
SEE ALSO
shortcodes, chaining, noop, flags
Command declarations - [d]eclarations (supported languages only)
Shows declarations/definitions, for supported languages and allows searching by name, as well as parent-level filtering.
::othe “owner” flag can show the declaration it belongs to, for example the class a matched method belongs to.::bthe “body” flag shows the lines that belong to the declaration.
Example: declarations matching init.
rxedit pysample.py d::__init__::
Output:
def do_init(func):
def __init__(self, name: str):
show the owner and filter only function declarations with wt=f.
rxedit sample.rs d::message::wt=f.o
Output:
fn make_message() -> String {
fn print_message(message: &str) {
mod tests {
fn always_pass_message(){
same as above, but filter out functions that belong to parents matching test
rxedit sample.rs d::--test/message::wt=f.o
Output:
fn make_message() -> String {
fn print_message(message: &str) {
You could also have a positive parent test using d::test/message::.
Declarations
| Name | Format | Example | Description |
|---|---|---|---|
| show_body | b | d::::b | body of the definition |
| show_owner | o | ::o | show “owner” of the line |
| where_type | wt=([a-z]+)(?:.|/|$) | ::wt=f/ (shows only function | ) only show some types of declarations |
| insensitive | i | ::i | case-insentive search |
| after | A(\d+) | ::A16 | Show NUM lines after each match. |
| before | B(\d+) | ::B5 | Show NUM lines before each match. |
| context | C(\d+) | ::C5 | Show NUM lines before and after each match. |
| fixed_string | F | ::F | treat search as regular string, not a regex |
| use_grep_shortcodes | g | ::g | expands shortcodes (..→.*, ~~s.→ +) |
| no_use_grep_shortcodes | G | ::G | does not expand grep shortcodes |
| show_owner | o | ::o | show “owner” of the line |
| set key | sk=([a-z]+)(?:.|/|$) | ::sk=important/ | set key to a value that can be used with wk= |
| where_key | wk=([a-z]+)(?:.|/|$) | ::wk=mykey/ | puts an extra criteria to other commands |
| where_linenum | wl=([-0-9A-Ca-chtHT,.]+) | ::wl=..5,8,-1/ | limit line number range |
Notes:
Declarations are available when the file extension is recognized as a supported language. If not,
this will become a noop.
Source parsing is done via tree-sitter which provides contextual knowledge such as:
- whether a declaration is nested under a parent.
- which lines of code “belong” to a given declaration, giving the same capabilities as a folding editor.
- multi-line function signatures are displayed as a block
- the ability to filter by parent name, using
!or--for negation and/for level.
Search matching
Note that only the name of the declaration is matched against.
Since names are alphanumeric this means grep shortcodes are limited to OR (using | or ,) and WILDCARD (..).
But also that the searching is also clever enough to support both positive and negative matching,
so 'd::split--regex,nega' looks for names with split but not regex or nega.
Standard search flags like A2 or sk=mykey. are also supported by declarations.
where type, wt=xyz flag
Each language also supports filtering by declaration type using the wt= flag.::wt=fs on rust means search only fn and struct names,
whereas d::::wt=c would show only Python class definitions.
SEE ALSO
shortcodes, chaining, languages, noop
Command imports - [i]imports (supported languages only)
Find imports/uses/includes that match the search term.
Example: search for imports that match co, but not std or regex.
rxedit utilities.rs i::co--std,regex
Output:
use crate::common::{CheckLineRange, LineStatus};
use crate::constants::{DEBUGGING, RE_SPLIT_NEGATIVES_NAMES};
use crate::common::ConditionResult;
use crate::common::GetLine;
use crate::common::StopOrAddChecker;
use crate::constants::Direction;
use crate::common::LineStatus;
use crate::constants::Direction;
Example: search for imports “far in the file”
Another example if we want to look for imports that are past the reasonable start of the file, line 100 in
the example below.
Sometimes however, with Python, this is done to avoid circular import dependencies, so we’ll use the ::o
“show owner” flag as well.
rxedit utils.py i::::wl=100../o
Search flags
| Name | Format | Example | Description |
|---|---|---|---|
| insensitive | i | ::i | case-insentive search |
| after | A(\d+) | ::A16 | Show NUM lines after each match. |
| before | B(\d+) | ::B5 | Show NUM lines before each match. |
| context | C(\d+) | ::C5 | Show NUM lines before and after each match. |
| fixed_string | F | ::F | treat search as regular string, not a regex |
| use_grep_shortcodes | g | ::g | expands shortcodes (..→.*, ~~s.→ +) |
| no_use_grep_shortcodes | G | ::G | does not expand grep shortcodes |
| show_owner | o | ::o | show “owner” of the line |
| set key | sk=([a-z]+)(?:.|/|$) | ::sk=importan | / set key to a value that can be used with wk= |
| where_key | wk=([a-z]+)(?:.|/|$) | ::wk=mykey/ | puts an extra criteria to other commands |
| where_linenum | wl=([-0-9A-Ca-chtHT,.]+) | ::wl=..5,8,-1/ | limit line number range |
Notes:
Imports are available when the file extension is recognized as a supported language. If not,
this will become a noop.
The search mechanism behaves like declarations name matching, because
the names are basically expected to be alphanumeric.
Name matching is a bit complicated (AND A WORK IN PROGRESS).
Imports names are matched against each level but the last.
That’s because this is matching against the modules imported rather than what is imported from a module.
So i::std would match use std::fs; but i::fs would not because fs is the last bit.
SEE ALSO
shortcodes, chaining, languages, noop
Command explain
Prints how rxedit processed your command arguments at the very end, to stderr.
This is useful because rxedit will silently ignore most mistyped commands or flags rather than stopping execution.
For example, let’s say you want to show all Python __init__ constructors and their owner, which will be a class.
rxedit pysample.py d::__init__::O -n
giving
def __init__(self, name: str):
what happened? you were expecting ::o to show the owner.
rxedit pysample.py d::__init__::O explain
in addition to the stdout output you had before you now get extra stuff on stderr
-----------------------------------------
[explain] / processing for these arguments...
Global configuration:
space between blocks=false, show line numbers=false, grep shortcode substitution:true
file=pysample.py
d::__init__::O /?ignored: `O` => [declare] regex: `__init__`
use_grep_shortcodes
The important part is ?ignored: 'O'. It turns out you didn’t use lower case o so O, which means
nothing for a declaration command, was silently ignored. Correcting that, you get the expected output
rxedit pysample.py d::__init__::o
class Calculator:
def __init__(self, name: str):
Or you want to show all print calls, with 2 lines surrounding them:
rxedit pysample.py more::print:C2
but it gives you no output. Adding explain gives extra information
-----------------------------------------
[explain] / processing for these arguments...
Global configuration:
space between blocks=false, show line numbers=false, grep shortcode substitution:true
file=pysample.py
more::print:C2 => [more] regex: `print:C2`
use_grep_shortcodes
That regex is very fishy and that’s because you only specified one :. Using more::print::C2 fixes the problem.
SEE ALSO
Command macro :
Allows the execution of saved commands in succession against a target.
Example:
Suppose you want to find bits of your code that are “chatty”, perhaps with log calls or print statement and similar things put in during development.
You might start out with
rxedit pysample.py m::print m::pp\(
but you don’t want to flag lines that were already commented out so
rxedit pysample.py m::print m::pp\( 'less::^ *#%'
but now you also have to retype all of this on each new file you are scanning. That’s where macro files come in, which allow you to save those commands for re-use and add comments:
So you can run this instead:
rxedit pysample.py macro ./showpychatty.rxi
giving
000035 print(f"\n{self.name}'s History:")
000037 print(f" {entry}")
then hide line 37…
rxedit pysample.py macro ./showpychatty.rxi less::::wl=37
000035 print(f"\n{self.name}'s History:")
and call another Python-specific macro file to comment visible lines out
rxedit pysample.py macro ./showpychatty.rxi less::::wl=37 macro ./pycommentout.rxi
000035 #print(f"\n{self.name}'s History:")
Sample macro file contents
Comments start with # and empty lines are ignored.
file rxedit/regression_tests/samples/showpychatty.rxi
#things that considered "noisy"
m::^ *(print|debug|pp|ppp|rin|rindebug)\(
more::log\.(info|debug)
more::log\(..level="w
#hide commented-out stuff
less::^ *#
file rxedit/regression_tests/samples/pycommentout.rxi
Note that rxedit’s Change is just a passthrough to the standard Rust Regex crate which supports the use of
groups.
# put all leading space in match group1, rest in group2. then prefix group2 with a `#`
'c::([\s]*)([^\s].*$)::$1#$2'
No-operation / noop
This isn’t a command, but rather it is what happens when rxedit can’t figure out what to do.
Rather than erroring out, it will just “do nothing” and pass on the lines to the next command.
-
explainwill try to tell why you ended up with No-operation. -
If the only command present is a No-operation, rxedit will ask you to specify at least one valid command.
-
Be careful when you are using rxedit to modify a file with
changeordelete. A preceding No-operation may mean that you are not modifying just the lines you intended to.
Why chaining commands is so powerful.
That’s rxedit’s superpower, otherwise it would be a less capable grep or sed.
The idea is to make lines selectively visible by either adding to, or hiding, lines that were
made visible by previous commands.
Except for more and all only visible lines are affected by any commands. This applies
specifically to delete and change. invert can be used to “flip” the visibility.
For example, to extract only lines of interest to a report (using the `-o
rxedit myjava.java all::public invert delete -o myreport.out
- show
alllines you care about - optionally, apply an appropriate
lessto remove commented out lines or invertthe visibilitydeleteeverything-o myreport.txtwould then save only lines with lines of interest.- (No, you certainly wouldn’t want want to use the
-Omodify in place option here).
- (No, you certainly wouldn’t want want to use the
You could also search for lines that indicate debugging code, hide some of the ones you want to keep
and then run a macro with predefined language-specific change commands to comment out those debugging lines.
Workflow Help
- Start with broad match commands to reveal relevant lines, possibly using existing macro files.
- Narrow progressively using additional commands.
- Add -n for line numbers and -s for visual spacing.
- Make sure your visible lines match your expections.
If modifying the file
- If modifying the file with
prepend/append,changeordelete, make doubly sure the results are as expected. - When satisfied, use -O to modify the file in place (best to do it on a version-controlled directory)
SEE ALSO
rxedit --help change shows a fairly complex chaining example to comment “print” statements.
Config
rxedit reads user configuration from:
~/.config/rxedit/config.toml
The file is optional. If it is missing, rxedit uses built-in defaults.
Generate a starter file with:
rxedit --gen-config
If the file already exists, it is not overwritten.
Supported keys (all optional, boolean values):
spacerline_numbergrep_shortcodes
Example config.toml:
spacer = false
line_number = true
grep_shortcodes = true
Environment variable overrides (all optional):
rxedit_spacerrxedit_line_numberrxedit_grep_shortcodes
Language plugin directory precedence:
rxedit_plugins_directory[plugins].directoryinconfig.toml
Accepted boolean values for env vars:
- true forms:
true,1,yes,on - false forms:
false,0,no,off
Using flags
This covers a few special flags available on many commands separately
sk= set_key and wk= where_key
set key sk=<value>. and where key wk=<value>.
Set key allows to mark affected lines with a “key” of some value, which can be referred to by later commands as an additional criterion. An example of how it works:
rxedit pysample.py more::init::sk=mykey
All lines matching “init” are shown and set to key=mykey
def do_init(func):
def __init__(self, name: str):
@do_init
next, declarations will show all class and method lines.
rxedit pysample.py more::init::sk=mykey declarations
giving
def do_init(func):
class Calculator:
def __init__(self, name: str):
def add(self, a: int, b: int) -> int:
def multiply(self, a: int,
b: int) -> int:
@do_init
def show_history(self) -> None:
let’s now use ::wk=mykey to hide only lines with that key set.
rxedit pysample.py more::init::sk=mykey declarations less::o::wk=mykey
that less will match any line with “o” in it, but only if had been marked with key=mykey. So “show_history” is kept, but not “do_init”.
class Calculator:
def __init__(self, name: str):
def add(self, a: int, b: int) -> int:
def multiply(self, a: int,
b: int) -> int:
def show_history(self) -> None:
Setting the value for the flag.
For these types of arbitrary value flags, value is whatever comes after the =, until a . or the end of the flag.
more::init::sk=mykey.A1 and more::init::sk=mykey will both set the key to “mykey”.
Note that the lines made visible by A1 are made visible, but are not set to “mykey”.
wl= where linenum flag
This add the extra criterion that the lines must be in the specified line range(s).
rxedit -n pysample.py d::::wl=..10,30..
000005 def do_init(func):
000009 class Calculator:
000031 def show_history(self) -> None:
u user confirmation flag
For potentially dangerous commands or when you want to handle lines one by one, the u user confirmation flag asks you to confirm.
rxedit pysample.py d::init delete::::u
> delete def do_init(func): Yes
? delete def __init__(self, name: str): (Y/n)
...
Using this flag triggers an abort if rxedit sees it is executed in a batch, rather than interactively.
Supported languages
Out of the box, Rust and Python are supported. Adding a new language consists of finding a crate that delivers a
librxedit_language_<extension> shared library and then symlinking to it in a directory indicated by environment variable $rxedit_plugins_directory or specified in
~/.config/rxedit/config.toml
[plugins]
directory = "~/.config/rxedit/plugins"
[tree_sitter.extensions]
sh = "zsh"
Here we tell it two things, the location of the plugins directory and also that .sh files should use the zsh parser.
Detecting the language is automatic, based on the file extension. If the language is not supported,
most rxedit commands will continue as before, but specific options,
like the ::o “show owner”, flag will be ignored. Basically, it falls back to doing anything
grep can do, but treats the file as just text as it has no understanding of code syntax.
declarations commands will be entirely ignored however, as an explain will show.
Grep macro shortcodes.
Shortcodes can be applied to all regex searches, using the -g flag to turn it on (-G turns shortcodes off ).
They facilitate some common regex use cases and avoid clashing with shell substitutions.
Examples:
rxedit sample.rs 'm::impl.*for'can be replaced withrxedit -g sample.rs m::impl..for. Note that quotes aren’t needed anymore.rxedit sample.rs 'm::fn|struct'withrxedit sample.rs -g m::fn~~o.struct
Available shortcuts:
| Key | Macro | Expa | sion Description |
|---|---|---|---|
| wildcard | .. | .* | matches any string |
| spaces | ~~s. | + | matches one or more space character |
| or | ~~o. | | | standard grep OR/pipe a|b |
| quotes | ~~q. | [’“] | matches either a single or double quote character |
| less_than | ~~lt. | < | matches < |
| left_parenthesis | ~~pl. | ( | matches ( |
| right_parenthesis | ~~pr. | ) | matches ) |
| field_separator | ~~~ | :: | matches :: |
| colon | ~~colon. | : | matches : |
Remarks:
- Searching on identifier names, via the
declarecommand only supports thewildcardandorshortcodes because identifiers are basically alphanumeric only. Sodeclare::foo..bar>::is valid butdeclare::foo~~s.bar>::will remain unexpanded. - They don’t work with fixed string matching, only with regexes.
m::..::Fwilll match only a literal..whilem::..::will match everything.
samples files in help examples
Contents of files used for examples.
Sample Rust file: sample.rs
use log::debug;
trait Greeter {
fn greet(&self, name: &str) -> String;
}
struct HelloApp;
impl Greeter for HelloApp {
fn greet(&self, name: &str) -> String {
format!("Hello, {name}!")
}
}
fn make_message() -> String {
let app = HelloApp;
app.greet("world")
}
fn print_message(message: &str) {
println!("{message}");
}
/// a doc
fn fixture_signature_with_colon_colon_in_body() {
// and a comment
let marker = "::B5";
debug!("yo!")
println!("{marker}");
}
fn main() {
let message = make_message();
print_message(&message);
}
mod tests {
fn always_pass_message(){
println!("always passing");
}
}
Sample Python file: pysample.py
import os, sys
from pathlib import Path
def do_init(func):
return func
class Calculator:
"A simple calculator class to demonstrate Python basics."
def __init__(self, name: str):
# a comment
self.name = name
self.history = []
def add(self, a: int, b: int) -> int: # inline comment
"""Add two numbers ."""
result_add = a + b
self.history.append(f"{a} + {b} = {result_add}")
return result_add
def multiply(self, a: int,
b: int) -> int:
"""Multiply two numbers."""
result_multiply = a * b
self.history.append(f"{a} * {b} = {result_multiply}")
return result_multiply
@do_init
def show_history(self) -> None:
"""Display calculation history
."""
# commented out
print(f"\n{self.name}'s History:")
for entry in self.history:
print(f" {entry}")
# Usage example
if __name__ == "__main__":
calc = Calculator("MyCalc")
calc.add(5, 3)
calc.multiply(4, 7)
calc.show_history()
error codes
User messages
| Key | Code | Body |
|---|---|---|
| declarations_hashtree_key_not_found | RXE-ERR-0001 | hashtree_key={} not found |
This error means a declarations hit referenced a tree-sitter key that was not found in the parsed declarations map.
This usually indicates declarations state got out of sync between parsing and filtering.
declarations_showowner_extension_unsupported RXE-WARN-0001 apply:showowner extension did not match supported languages
This warning means the programming language extension for the provided file does not have an rxedit tree-sitter grammar defined yet. Basic commands like more/all/less still work, but syntax-aware features such as declarations and show owner are unavailable for that extension.
treesitter_name_field_missing RXE-WARN-0002 Could not find name field for node kind: {} : {}
This warning means rxedit found a declarations node that does not expose the expected name field in the current grammar, so that declarations is skipped when building the declaration index.