Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

  • all show only matching lines
  • more show more matching lines
  • less hide matching lines
  • invert invert visibility
  • lines displays lines within ranges, similar to a posix head or tail

Editing commands:

  • delete delete visible, matching, lines
  • change regex replacement on visible lines. Supports the full Rust regex syntax.
  • prepend add a line before the matching line
  • append add 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)

  • declarations look for class, struct or function names that match.
  • imports look for include, import or use lines that match the name

Utility commands:

  • macro loads commands from a given file, allowing predefinition of search and exclusion patterns
  • explain stderr what rxedit has understood, and rejected, from user input.

Flags (not all commands support all flags, see their individual help)

  • i case insensitive.
  • F fixed string, meaning that “string contains” will be used, rather than a regex match.
  • A10, B2, C1 - similar to using grep -A 10 -B 2…
  • o owner flag - shows the function or class signature to which a matching lines belongs
  • b body flag - only avaiable on declarations commands, shows all lines for a function or class.
  • wt=fs. For declarations only: filters the types of definitions we are interested in. On Rust, fs would match fn or struct.
  • u user confirmation, match by match, on delete or change commands.
  • sk=debug. Sets key=debug on matching lines. This can be used to constrain further commands using wk.
  • wk=debug. In addition to any match conditions, the command will only affect lines with key=debug set.
  • 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:

  1. Show lines (all, more)
  2. Hide lines (less)
  3. Edit/delete (change, delete)
  4. 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 -O allows 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 explain command to get feedback on what it understood or not.

    • Risk: If you display lots of lines, then want to use less to hide some before editing what’s left this could be a problem. For example, if you mistyped less:keep-this! (notice the mistyped :: field separator) , immediately followed by a delete.

─────────────────────────────

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::Fi would do the same thing, but match as a fixed, case-insentive, string
  • rxedit sample.rs a::Greeter::A1 will work like grep -A 1 Greeter sample.rs

Search flags

NameFormatExampleDescription
insensitivei::icase-insentive search
afterA(\d+)::A16Show NUM lines after each match.
beforeB(\d+)::B5Show NUM lines before each match.
contextC(\d+)::C5Show NUM lines before and after each match.
fixed_stringF::Ftreat search as regular string, not a regex
use_grep_shortcodesg::gexpands shortcodes (..→.*, ~~s.→ +)
no_use_grep_shortcodesG::Gdoes not expand grep shortcodes
show_ownero::oshow “owner” of the line
set keysk=([a-z]+)(?:.|/|$)::sk=importan/ set key to a value that can be used with wk=. in later commands
where_keywk=([a-z]+)(?:.|/|$)::wk=mykey/puts an extra criteria to other commands
where_linenumwl=([-0-9A-Ca-chtHT,.]+)::wl=..5,8,-1/limit line number range

SEE ALSO

shortcodes, chaining, noop

Command more - [m]ore

Shows matching lines.

Example: show ‘message’

rxedit sample.rs more::message::o

  • more::message shows lines matching message.
  • ::o for 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::oFi same thing, but match as a fixed, case-insentive string
  • rxedit sample.rs m::message::A2 like grep -A 2 message sample.rs
  • rxedit sample.rs 'm::print..\(::g' uses .. shortcode to show any line matching print*(

Search flags

NameFormatExampleDescription
insensitivei::icase-insentive search
afterA(\d+)::A16Show NUM lines after each match.
beforeB(\d+)::B5Show NUM lines before each match.
contextC(\d+)::C5Show NUM lines before and after each match.
fixed_stringF::Ftreat search as regular string, not a regex
use_grep_shortcodesg::gexpands shortcodes (..→.*, ~~s.→ +)
no_use_grep_shortcodesG::Gdoes not expand grep shortcodes
show_ownero::oshow “owner” of the line
set keysk=([a-z]+)(?:.|/|$)::sk=importan/ set key to a value that can be used with wk=. in later commands
where_keywk=([a-z]+)(?:.|/|$)::wk=mykey/puts an extra criteria to other commands
where_linenumwl=([-0-9A-Ca-chtHT,.]+)::wl=..5,8,-1/limit line number range

SEE ALSO

shortcodes, chaining, noop

Command less - [l]ess

Hides matching lines.

Example: hide “print_”

rxedit sample.rs 'a::fn.*_message' less::print_

  • a::fn.*_message only lines matching the regex fn.*_message are shown.
    • This regex is quoted because the shell may interpret special characters.
  • less::print_ hides lines that contain print_.

Output

fn make_message() -> String {
    fn always_pass_message(){

Search flags

NameFormatExampleDescription
insensitivei::icase-insentive search
afterA(\d+)::A16Show NUM lines after each match.
beforeB(\d+)::B5Show NUM lines before each match.
contextC(\d+)::C5Show NUM lines before and after each match.
fixed_stringF::Ftreat search as regular string, not a regex
use_grep_shortcodesg::gexpands shortcodes (..→.*, ~~s.→ +)
no_use_grep_shortcodesG::Gdoes not expand grep shortcodes
show_ownero::oshow “owner” of the line
set keysk=([a-z]+)(?:.|/|$)::sk=importan/ set key to a value that can be used with wk=. in later commands
where_keywk=([a-z]+)(?:.|/|$)::wk=mykey/puts an extra criteria to other commands
where_linenumwl=([-0-9A-Ca-chtHT,.]+)::wl=..5,8,-1/limit line number range

SEE ALSO

shortcodes, chaining, noop

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 under mod tests
  • 'and::^pub ' keep only those lines with pub keyword
  • invert flips visibility.
  • delete:: removes currently visible lines, i.e. not a public definition
  • all show all lines. (In practice use something like -o signatures.out to 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:

NameFormaExamplDescription

Notes:

invert has no flags or payload

SEE ALSO

chaining

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..y means 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
  • h and t act like head and tail command, while A, B, C behave like they do in grep

Examples

SpecifierMeaning
lines::2..5skip line 1, then display up to line 5
lines::-1last line
lines::t5last 5 lines
lines::-5..last 5 lines
lines::h3first 3 lines
lines::-5..-3same as tail -5, but skip the last 2
lines::30C5display lines 25-35
lines::..2,t5first 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,5 show lines 1,3 and 5

Lines flags

NameFormatExampleDescription
set keysk=([a-z]+)(?:.|/|) ::sk=importan/ set key to a value that can be used with wk=. in later commands
where_keywk=([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 declarations
  • d::_::sk=keep - set any declarations with _ in their names as key=keep
  • d::::wt=c.sk=keep - use wt=c i..e where type = class to set any class to key=keep
  • and::::wk=keep.wl=..20 only 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

NameFormatExampleDescription
afterA(\d+)::A16Show NUM lines after each match.
beforeB(\d+)::B5Show NUM lines before each match.
contextC(\d+)::C5Show NUM lines before and after each match.
insensitivei::icase-insentive search
fixed_stringF::Ftreat search as regular string, not a regex
use_grep_shortcodesg::gexpands shortcodes (..→.*, ~~s.→ +)
no_use_grep_shortcodesG::Gdoes not expand grep shortcodes
set keysk=([a-z]+)(?:.|/|$)::sk=importan/ set key to a value that can be used with wk=. in later commands
where_keywk=([a-z]+)(?:.|/|$)::wk=mykey/puts an extra criteria to other commands
where_linenumwl=([-0-9A-Ca-chtHT,.]+)::wl=..5,8,-1/limit line number range

SEE ALSO

shortcodes, chaining, noop

Command Delete - [del]ete

Deletes visible lines matching pattern.

Example delete visible lines containing “debug”

rxedit sample.rs a::debug delete:debug

Details

  • delete removes lines from the output entirely (not just hiding them).
  • use less or set key / where key (sk=,wk=) to constraint the scope.

delete flags

NameFormatExampleDescription
insensitivei::icase-insentive search
afterA(\d+)::A16Show NUM lines after each match.
beforeB(\d+)::B5Show NUM lines before each match.
contextC(\d+)::C5Show NUM lines before and after each match.
fixed_stringF::Ftreat search as regular string, not a regex
use_grep_shortcodesg::gexpands shortcodes (..→.*, ~~s.→ +)
no_use_grep_shortcodesG::Gdoes not expand grep shortcodes
show_ownero::oshow “owner” of the line
set keysk=([a-z]+)(?:.|/|$)::sk=importan/ set key to a value that can be used with wk=. in later commands
where_keywk=([a-z]+)(?:.|/|$)::wk=mykey/puts an extra criteria to other commands
where_linenumwl=([-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 -O modify in place flag or the -o <some path> output flag.
  • Those commands only apply to matching visible lines, unlike say a sed insert or delete.
  • append,prepend,delete will throw off the line numbers used in where line flags
  • 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.bak flag to save and diff your changes first.
  • Use explain to make sure all previous commands to show/hide lines went as expected.
  • Modification commands support the ::u user 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

NameFormatExampleDescription
change_alla::auser confirmation
insensitivei::icase-insentive search
fixed_stringF::Ftreat search as regular string, not a regex
use_grep_shortcodesg::gexpands shortcodes (..→.*, ~~s.→ +)
no_use_grep_shortcodesG::Gdoes not expand grep shortcodes
where_keywk=([a-z]+)(?:.|/|) ::wk=myke/ puts an extra criteria to other commands
user_confirmu::uuser confirmation

Notes about commands that modify the text

  • Nothing gets saved until you use the -O modify in place flag or the -o <some path> output flag.
  • Those commands only apply to matching visible lines, unlike say a sed insert or delete.
  • append,prepend,delete will throw off the line numbers used in where line flags
  • 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.bak flag to save and diff your changes first.
  • Use explain to make sure all previous commands to show/hide lines went as expected.
  • Modification commands support the ::u user 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

NameFormatExampleDescription
insensitivei::icase-insentive search
indent_keepI::Ikeep matching line’s indentation
fixed_stringF::Ftreat search as regular string, not a regex
use_grep_shortcodesg::gexpands shortcodes (..→.*, ~~s.→ +)
no_use_grep_shortcodesG::Gdoes not expand grep shortcodes
where_keywk=([a-z]+)(?:.|/|) ::wk=myke/ puts an extra criteria to other commands
user_confirmu::uuser confirmation

Notes about commands that modify the text

  • Nothing gets saved until you use the -O modify in place flag or the -o <some path> output flag.
  • Those commands only apply to matching visible lines, unlike say a sed insert or delete.
  • append,prepend,delete will throw off the line numbers used in where line flags
  • 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.bak flag to save and diff your changes first.
  • Use explain to make sure all previous commands to show/hide lines went as expected.
  • Modification commands support the ::u user 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

NameFormatExampleDescription
insensitivei::icase-insentive search
indent_keepI::Ikeep matching line’s indentation
fixed_stringF::Ftreat search as regular string, not a regex
use_grep_shortcodesg::gexpands shortcodes (..→.*, ~~s.→ +)
no_use_grep_shortcodesG::Gdoes not expand grep shortcodes
where_keywk=([a-z]+)(?:.|/|) ::wk=myke/ puts an extra criteria to other commands
user_confirmu::uuser confirmation

Notes about commands that modify the text

  • Nothing gets saved until you use the -O modify in place flag or the -o <some path> output flag.
  • Those commands only apply to matching visible lines, unlike say a sed insert or delete.
  • append,prepend,delete will throw off the line numbers used in where line flags
  • 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.bak flag to save and diff your changes first.
  • Use explain to make sure all previous commands to show/hide lines went as expected.
  • Modification commands support the ::u user 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.

  • ::o the “owner” flag can show the declaration it belongs to, for example the class a matched method belongs to.
  • ::b the “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

NameFormatExampleDescription
show_bodybd::::bbody of the definition
show_ownero::oshow “owner” of the line
where_typewt=([a-z]+)(?:.|/|$)::wt=f/ (shows only function) only show some types of declarations
insensitivei::icase-insentive search
afterA(\d+)::A16Show NUM lines after each match.
beforeB(\d+)::B5Show NUM lines before each match.
contextC(\d+)::C5Show NUM lines before and after each match.
fixed_stringF::Ftreat search as regular string, not a regex
use_grep_shortcodesg::gexpands shortcodes (..→.*, ~~s.→ +)
no_use_grep_shortcodesG::Gdoes not expand grep shortcodes
show_ownero::oshow “owner” of the line
set keysk=([a-z]+)(?:.|/|$)::sk=important/set key to a value that can be used with wk=. in later commands
where_keywk=([a-z]+)(?:.|/|$)::wk=mykey/puts an extra criteria to other commands
where_linenumwl=([-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

NameFormatExampleDescription
insensitivei::icase-insentive search
afterA(\d+)::A16Show NUM lines after each match.
beforeB(\d+)::B5Show NUM lines before each match.
contextC(\d+)::C5Show NUM lines before and after each match.
fixed_stringF::Ftreat search as regular string, not a regex
use_grep_shortcodesg::gexpands shortcodes (..→.*, ~~s.→ +)
no_use_grep_shortcodesG::Gdoes not expand grep shortcodes
show_ownero::oshow “owner” of the line
set keysk=([a-z]+)(?:.|/|$)::sk=importan/ set key to a value that can be used with wk=. in later commands
where_keywk=([a-z]+)(?:.|/|$)::wk=mykey/puts an extra criteria to other commands
where_linenumwl=([-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

noop

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.

  • explain will 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 change or delete. 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 command line flag), you would:

rxedit myjava.java all::public invert delete -o myreport.out

  • show all lines you care about
  • optionally, apply an appropriate less to remove commented out lines or
  • invert the visibility
  • delete everything
  • -o myreport.txt would then save only lines with lines of interest.
    • (No, you certainly wouldn’t want want to use the -O modify in place option here).

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

  1. Start with broad match commands to reveal relevant lines, possibly using existing macro files.
  2. Narrow progressively using additional commands.
  3. Add -n for line numbers and -s for visual spacing.
  4. Make sure your visible lines match your expections.

If modifying the file

  1. If modifying the file with prepend/append, change or delete, make doubly sure the results are as expected.
  2. 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):

  • spacer
  • line_number
  • grep_shortcodes

Example config.toml:

spacer = false
line_number = true
grep_shortcodes = true

Environment variable overrides (all optional):

  • rxedit_spacer
  • rxedit_line_number
  • rxedit_grep_shortcodes

Language plugin directory precedence:

  • rxedit_plugins_directory
  • [plugins].directory in config.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 with rxedit -g sample.rs m::impl..for. Note that quotes aren’t needed anymore.
  • rxedit sample.rs 'm::fn|struct' with rxedit sample.rs -g m::fn~~o.struct
Available shortcuts:
KeyMacroExpasion 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 declare command only supports the wildcard and or shortcodes because identifiers are basically alphanumeric only. So declare::foo..bar>:: is valid but declare::foo~~s.bar>:: will remain unexpanded.
  • They don’t work with fixed string matching, only with regexes. m::..::F willl match only a literal .. while m::..:: 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

KeyCodeBody
declarations_hashtree_key_not_foundRXE-ERR-0001hashtree_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.