### ----------------------------------------------------
### -- RakuRename
### -- Licenses: Artistic-2.0
### -- Authors: stuart-little
### -- File: README.md
### ----------------------------------------------------
# RakuRename

A file-rename tool inspired by Perl's [File::Rename](https://metacpan.org/dist/File-Rename/view/rename.PL).

## Installation

If you have [zef](https://github.com/ugexe/zef), there are a number of options:

- just run `zef install RakuRename`;
- or clone this repo and issue `zef install <path-to-cloned-repo>`;
- as yet another variation, after cloning it, `cd` into the repo and `zef install .` (note the dot at the end).

Additionally, since all there is here, really, is the executable `bin/rrnm`, you can just download that and use it.

## Usage

The distribution only provides the `rrnm` binary. In general:

- Run `rrnm --help` to see information on the possible command-line switches / options.

- The first positional argument should be a substitution or transliteration operator, as documented under `Raku`'s [substitution-operators](https://docs.raku.org/language/operators#Substitution_operators) doc section.

- The positional arguments following that should be the files you want to move / copy / whatever (see the examples below).

- The regex syntax is whatever `Raku` [will recognize](https://docs.raku.org/language/regexes).

## Examples

Some usage examples follow, all of which are to be run in a terminal where you have access to `zef`-installed binaries.
```
rrnm 's/^a/b/' <DIRECTORY>/a*
```
will rename every file / directory of the form `<DIRECTORY>/a<BLAH>` to `<DIRECTORY>/b<BLAH>`.

On the other hand,
```
rrnm -c='cp' 's/^a/b/' <DIRECTORY>/a*
```
will take every file of the form `<DIRECTORY>/a<BLAH>` and *copy* it to `<DIRECTORY>/b<BLAH>`. It will complain about not being able to copy directories among those (because the [cp command](https://linux.die.net/man/1/cp) behaves this way), but you can fix that with
```
rrnm -c='cp -r' 's/^a/b/' <DIRECTORY>/a*
```
You can even do the following in a `git` repo, to effect a regex-based [git-mv](https://git-scm.com/docs/git-mv):

```
rrnm -c='git mv' 's/^(\d)/0$0/' [0-9]* 
```
or equivalently, using [lookahead assertions](https://docs.raku.org/language/regexes#Lookahead_assertions),
```
rrnm -c='git mv' 's/^<?before \d>/0/' [0-9]*
```
That will perform a `git mv` on every file whose name starts with a digit, prepending a `0` (if you wanted to do this for some reason).

The `--dry` option just *shows* you the command that would be run. So in a git repo that contains files `1.txt` and `2.txt` (and nothing else starting with a digit), 

```
rrnm -c='git mv' 's/^(\d)/0$0/' [0-9]* --dry
```
would simply show you

```
git mv 1.txt ./01.txt
git mv 2.txt ./02.txt
```
in the terminal.

I use this all the time: first run what you *think* will work with `--dry`, then recall the last command and remove the `--dry` option.


