raf.1

.\" Manpage for raf.
.\" Report errors or typos at github.com/sapessi/raf.
.TH RAF 1 "20 Nov 2020"

.SH NAME
raf \- rename all files 

.SH SYNOPSIS
\fBraf\fP [undo] [ -p \fI"propertyName=regex"\fP ] [ -o \fI'output_definition'\fP ] [ -d -v ] FILES

.SH DESCRIPTION
\fBraf\fP makes it easy to rename multiple files in one folder. The output file names are generated 
using values extracted from the original name (properties), intrinsic variables such as counters, 
and literal strings. \fBraf\fP can be executed in dry-run mode with the \fI-d\fP option. In dry-run
mode \fBraf\fP prints out the file names it would generate and reports errors and warnings without 
actually renaming files.

\fBraf\fP saves the log of an execution in the working folder in a file called \fI.raf\fP and can use
the log to undo its changes using the \fIundo\fP command. The \fIundo\fP command also supports the 
dry-run execution mode. The \fI-p\fP and \fI-o\fP options are not used when undoing changes.

.SS Options
.TP
\fB-p|--prop <prop matcher>\fP 
Extract a named property from the original file name so that it can be used in the generation of the
output file name. For example, the option \fB-p "title=\\d\\ \\-\\ ([A-Za-z0-9]+)\\_\\("\fP would extract
the title \fIWedding\fP from a file named \fB[UnionStudio]Video 1 - Wedding_(Audio_10bit_BD1080p_x265).mp4\fP
and make it available for output generation with the name \fB$title\fP. \fBraf\fP can accept any number
of \fI-p\fP properties.
.TP
\fB-o|--output <output pattern>\fP
Specify the pattern used to generate the new file name based on a combination of properties and literal
strings. Properties can be declared using the \fI-p\fP option or can be intrinsics (see INTRINSICS section). 
The output is declared as a string that the \fBraf\fP command parses upon execution: 
\fB-o 'WeddingVideo - $cnt[%03] - $title.mp4'\fP. In this example, we used the intrinsic \fI$cnt\fP variable
with an additional formatter \fI[%03]\fP (see FORMATTERS section), the \fI$title\fP property extracted from 
the original file name, and literal strings such as the starting \fB"WeddingVideo - "\fP.
.TP
\fB-d|--dryrun\fP
The dry-run option tells \fBraf\fP not to change file names and instead only print the changes it would make
to the standard output. In dry-run mode, \fBraf\fP also checks for conflicts in the new file names or missing
properties that cannot be extracted from the original file name and prints out a summary of all warnings and 
errors.
.TP
\fB-v|--verbose\fP
Verbose logging during execution

.SH INTRINSICS
During the execution \fBraf\fP makes a number of properties available by default to the name generation 
routine. The values are scoped to the current file being processed.
.TP
\fB$cnt\fP
A counter of the current file being processed starting from 1. File are processed in the same order in which 
they are passed as input.
.TP
\fB$fname\fP
Full name of the original file, excluding the path but including the extension
.TP
\fB$ext\fP
Extension of the original file

.SH FORMATTERS
Formatters can be applied to properties during output generation. The value of one property can be passed through
multiple formatters in a pipeline. Formatters follow the property name in-between square brackets \fI$cnt[%03]\fP.
Each formatter is identified by a special symbol and receives a number of paramters. Multiple formatters are chained
using \fI,\fP. For example, the property \fI$title[/\\./ /,>:11]\fP contains a replacing formatter that swaps dots 
for spaces and a slice formatter that trims the length to 11 characters, when applied to the string "my.home.video" 
would result in the following string as output: "my home vid".

.TP
\fB%[char][length] - padding formatter\fP
The padding formatter makes it eaasy to create strings of a fixed \fIlength\fP left-padded with a \fIchar\fP. For 
example, this expression zero-pads the numeric counter variable to 3 characters in length: \fI$cnt[%03]\fP and will
results in the following output for the first file: \fI001\fP. 

.TP
\fB>[start]:[end] - slice formatter\fP
The slice formatter makes it easy to trim strings. The \fIstart\fP parameter is an integer indicating the first 
character that should be considered and the \fIend\fP parameter is an integer indicating the maximum length of the
string. Either parameter can be elided in which case \fIstart\fP will default to 0 and \fIend\fP will default to
the length of the string itself. For example, \fI$title[>:3]\fP would trim a string to a maximum of 10 characters and
the value "Home" would be reduced to "Hom"; using \fI$title[>2:4]\fP would result in "me"; and using \fI$title[>1:]\fP
would result in "ome". If the \fIstart\fP parameter is greater than the length of the value to trim the formatter
returns an empty string. For example, applying \fI$title[>5:10]\fP to "Home" would return "". 

.TP
\fB/[find]/[replace]/ - replacing formatter\fP
The replacing formatter makes it easy to replace portions of a string. The \fIfind\fP parameter can be a literal
string or a regular expression - including capturing groups - that raf will use to search for content in a property's
value. The \fIreplace\fP string is the value that raf will replace for the matched portions of the value. For example,
the property \fI$title[/\\./ /]\fP on the test "my.home.video" would return "my home video".

.SH BUGS
Report bugs on the GitHub repository at https://github.com/sapessi/raf

.SH COPYRIGHT
Copyright 2020 Stefano Buliani

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.