Skip to content

Commit

Permalink
Better README
Browse files Browse the repository at this point in the history
  • Loading branch information
@mathiasrw
mathiasrw committed Mar 21, 2017
1 parent c71a42f commit 33c3f69
Showing 1 changed file with 37 additions and 20 deletions.
57 changes: 37 additions & 20 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,24 @@

<!--h3 align="center">
<br>
<br>
<img width="350" src="https://cloud.githubusercontent.com/assets/1063454/24127465/ed1a59a2-0e28-11e7-9546-160d7eb1d8b9.png" alt="RexReplace mascot Benny on the RexReplace logo" />
<br>
<br>
<br>
<br>
</h3-->



[![Build Status](https://travis-ci.org/mathiasrw/rexreplace.svg?branch=master)](https://travis-ci.org/mathiasrw/rexreplace)
[![npm version](https://badge.fury.io/js/rexreplace.svg)](https://www.npmjs.com/package/rexreplace)
[![OPEN open source software](https://img.shields.io/badge/Open--OSS-%E2%9C%94-brightgreen.svg)](https://open-oss.surge.sh/)
[![OPEN open source software](https://img.shields.io/badge/Open--OSS-%E2%9C%94-brightgreen.svg)](https://open-oss.com)

# RexReplace


> Commandline search-and-replace as it should be: Simple file selection with globs, flexible patterns with regex and a friendly interface. No more brute forcing the right combination of `find`, `cat`, `sed`, `tr`, and `awk` to replace a text pattern in a bunch of files.
_Commandline search-and-replace as it should be: Simple file selection with globs, flexible patterns with regex and a friendly interface. No more brute forcing the right combination of `find`, `cat`, `sed`, `tr`, and `awk` to replace a text pattern in a bunch of files._

RexReplace gives you a friendly CLI interface to do search-and-replaces in files.
It defaults to global multiline case-insensitive search and includes the possibility to do lookahead and
It defaults to global multiline case-onsensitive search and includes the possibility to do lookahead and
backreference to matching groups in the replacement.
Files can be given as [glob notation](https://www.tcl.tk/man/tcl8.5/tutorial/Tcl16a.html) `docs/*.md` represents each markdown file in your `docs/` dir.

Expand All @@ -30,9 +30,9 @@ Files can be given as [glob notation](https://www.tcl.tk/man/tcl8.5/tutorial/Tcl
```


### Usages
### Usage
```bash
> rexreplace pattern replacement fileA [fileB fileC ...]
> rexreplace pattern replacement [fileGlob|option]+
```

Hard for your fingers to write on your keyboard? We got you covered with the `rr` alias for `rexreplace`.
Expand Down Expand Up @@ -73,23 +73,39 @@ Hard for your fingers to write on your keyboard? We got you covered with the `rr
-d, --debug Print debug info [boolean]
-€, --void-euro Void having '€' as alias for '$' in pattern and
replacement [boolean]
-P, --pattern-file Pattern is a filename from where the pattern will be
generated. Pattern will be defined by each line
trimmed and having newlines removed followed by other
other rules (like -€).) [boolean]
-R, --replacement-file Replacement is a filename from where the replacement
will be generated. Replacement will be defined by each
line trimmed and having newlines removed followed by
other other rules (like -€). [boolean]
-h, --help Show help [boolean]
```

## Good to know

### Limitations
- RexReplace reads each file fully into memory, so working on your 4Gb log files will probably not be ideal.

### Quirks
- Per default `€` is treated as an alias for `$`. The main reason is for you not to worry about how command line tools often have a special relationship with the `$` char. Your can escape your way out of this old love story, but it often pops up in unexpected ways. Use the `-€` flag if you need to search or replace the actual euro char.

- Options can only be set after the replacement parameter. _But I like to put my options as the first thing, so I know what I am doing_ I agree, but we must sometimes sacrifice some habits for the sake of simplicity.



### Priorities
- Flexibillity regarding text pattern matching
- Flexibility regarding text pattern matching
- Easy to filter what files to be treated
- Helpfull interface
- Test (if you know how to do a test cover report on javascript code ran via the command line please open an issue to let me know)
- Helpful interface
- Test (if you know how to do a test cover report on javascript code ran via the command line, please open an issue to let me know)


### Not a priority
- Speed. Obviously speed is important, but to what extent does a 21 millisecond command really satisfy the user compared to a 294 millisecond command?
- Speed. Obviously, speed is important, but to what extent does a 21-millisecond command really satisfy the user compared to a 294-millisecond command? See _test->speed_ for more info.

```bash
> time cat README.md | sed 's/x/y/g' > /dev/null
Expand All @@ -100,8 +116,6 @@ rr x y myfile -o > /dev/null 0,21s user 0,04s system 86% cpu 0,294 total
```


### Quirks
- Per default `€` is treated as an alias for `$`. The main reason is for you not to worry about how command line tools often have a special relationship with the `$` char. Your can escape your way out of this old love story, but it often pops up in unexpected ways. Use the `-€` flag if you need to search or replace the actual euro char.


## Test
Expand All @@ -118,14 +132,14 @@ All tests are defined in [test.sh](https://github.com/mathiasrw/rexreplace/blob/
_**tl;dr**:_
_Files over 5 Mb are faster with `rr` than with `sed` - but - it does not matter as any file under 25 Mb has less than 0.7 seconds in difference._

The speed test is initiated by starting `test/speed/run.sh`. The test takes files in different sizes and compares the processing time for RexReplace (`rr`) and the unix tool `sed`. The test uses the sources of a web site displaying the book _1984_ by George Orwell. The task for the tests is to remove all HTML tags by search and replace so only the final text is left. The source is 888Kb, so all files under 500Kb are generated directly from the source, while larger files are created by combining the first 500Kb several times. Each test runs 10 times to even the results out.
The speed test is initiated by starting `test/speed/run.sh`. The test takes files in different sizes and compares the processing time for RexReplace (`rr`) and the Unix tool `sed`. The test uses the sources of a website displaying the book _1984_ by George Orwell. The task for the tests is to remove all HTML tags by search-and-replace so only the final text is left. The source is 888Kb, so all files under 500Kb are generated directly from the source, while larger files are created by combining the first 500Kb several times. Each test runs 10 times to even out any temporary workload on the computer.
Results from latest test run can always be seen in the [`test/speed/`](https://github.com/mathiasrw/rexreplace/blob/master/test/speed/testlog.speed.md) folder.

<p align="center">
<img src="https://cloud.githubusercontent.com/assets/1063454/24081543/fc237d68-0d09-11e7-8c31-92a550589b53.png" alt="" />
</p>

The graph visualises speed relative to fastest run overall (`sed` on a 1kb file) . This chart also has [an interactive log version](https://plot.ly/~mathiasrw/1.embed) so the details in the low end can be studied better. Interestingly files of 1Kb, 5Kb takes longer for `rr` than 10Kb files.
The graph visualises speed relative to fastest run overall (`sed` on a 1kb file) . This chart also has [an interactive version in log scale](https://plot.ly/~mathiasrw/1.embed), so the details in the low end can be studied better. Interestingly files of 1Kb, 5Kb takes longer for `rr` than 10Kb files.

Now, what is relevant to notice is how `sed` only takes 3.3 seconds longer for the 100Mb file - even if the difference looks drastic on the graph.

Expand All @@ -146,11 +160,11 @@ Bytes sed rr Time it took longer (seconds)
100000 3 1 3,3 <= rr is 3x faster
```

So even though the speed evolves very differently there is little practical use of the focus on speed for most usecases.
So even though the speed evolves very differently there is little practical use of the focus on speed for most use cases.

Please note that the the data might look very differently when the files get so large that the memory starts to get full.
Please note that the data might look very differently when the files get so large that the memory starts to get full.

## Rumers
## Rumours

### Inspiration

Expand Down Expand Up @@ -185,7 +199,10 @@ Please note that the the data might look very differently when the files get so

<img src="https://cloud.githubusercontent.com/assets/1063454/24103435/5a0e3746-0dd3-11e7-9f0e-fd8664348fbe.png" align="right" alt="RexReplace mascot Benny on the RexReplace logBo" />

Please note that RexReplace is an **OPEN Open Source Project**. This means that individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.
Please note that RexReplace is an **OPEN open source project**.
This means that individuals making significant and valuable contributions are given commit access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

[![OPEN open source software](https://img.shields.io/badge/Open--OSS-%E2%9C%94-brightgreen.svg)](https://open-oss.com)


_<small>Icon inspired by <a href="http://www.freepik.com">Freepik</a> from <a href="http://www.flaticon.com">www.flaticon.com</a></small>_

0 comments on commit 33c3f69

Please sign in to comment.