- Installation
- Builtin documentation
- Modes of operation
- Template syntax
- Filtering
- Template-based sorting
- Conflict resolution strategies
- Ad-hoc tags
- Tag aliases
- Various options
tempren can be found on the snapcraft store.
To install it, you can use graphical package manager or command:
snap install tempren
Snap packages are updated automatically so no additional configuration is necessary.
If pip is installed on the target system,
tempren can be installed as any other Python package:
pip install [--user] 'tempren[video]'
pip doesn't automatically update packages so to keep tempren up-to-date, another command have to be used each time new version is released:
# Update already installed package to the latest version:
pip install [--user] --upgrade 'tempren[video]'
Note:
[video]part of the package name indicates that optionalVideotags should be installed. If you don't plan to work with video files, you can safely omit this part.
Some tags under Video category may not be available if there is no MediaInfo library installed on the system. This library is used to extract the metadata out of various media container formats.
As this dependency cannot be installed via pip, user is expected to deal with it manually.
Most often, a distribution-specific package manager can be used to install version of libmediainfo package.
For example:
# Install MediaInfo library on distros using `apt` package manager:
sudo apt install libmediainfo0v5
To eliminate the need for accessing external resources like websites or manpages while working with this tool, tempren comes in with extensive build-in documentation that is the main source of knowledge about installed tags and command line options.
Short documentation for all command line arguments can always be retrieved via --help/-h flag:
tempren --help
Note: Options which description starts with a
(default)clause, do not have to be specified explicitly on the command line.
--help/-h flag can also be used to display tag-specific documentation when a tag name is given as an argument:
tempren --help [Category.]TagName
To find out which tags are available to use in the templates, --list-tags/-l flag can be used:
tempren --list-tags
The output of this command will list all available tag names sorted by name and grouped by category they belong to.
tempren have three main modes of operation: name, directory and path.
In the (default) name mode (represented by --name/-n flag), the template is used for filename generation only.
This mode is used most often as it doesn't alter directory structure and focuses just on the files. In this mode, if a path separator (i.e. /) is present in the generated path, an error will be reported.
Name mode is used mostly when operating on a single directory or files specified directly in the command-line arguments.
Similarly, with directory mode selected (by --directory/-d flag), template generates new names for directories only - without changing filesystem hierarchy.
Note: In directory mode only contextual and directory-enabled tags are available
Note: Currently sorting is not available in the directory mode
In the path mode (enabled by --path/-p flag), for each processed file, the template generates a whole, new path (relative to the input directory).
This way you can move (sort) files into dynamically generated catalogues.
The input directory is important for the path mode because all generated paths are relative to it. What is used as the input directory depends on how you pass the arguments to the tempren:
- For file paths passed directly (in the command line), their input directory will be the directory they are currently in - i.e.
dirname <processed-file> - Directory paths passed directly will be considered input directories on their own - files contained within will have them as input directory
Note: When using recursive file discovery, only the top-most directory (the one passed in the command line) is considered as input directory.
By default, tempren will not descend into subdirectories of specified input directory.
To allow recursive file discovery, --recurse/-r flag have to be used.
Note: If
--include-hiddenflag is used, hidden directories will also be scanned.
Template pattern consist of a raw text interleaved with tag invocations:
Raw text with a %TagCategory.TagName() in it
Raw text is treated as a constant - it doesn't change across template evaluations.
Tag invocation starts with % symbol followed by the tag name, argument list and (optionally) its context.
A fully qualified tag name consists of a category and tag name separated by a single dot ..
The tag name is case-sensitive and conforms to CamelCase naming convention.
The category name is case-insensitive but to keep convention consistent it is also presented in the same (CamelCase) manner.
If the tag name is unique across categories it can be used without explicit category specification (and separating dot) like this:
Raw text with a %UniqueTag() in it
When non-unique tag name (present in more than one category) is used this way, tempren will report an error about tag ambiguity.
Some tags might or have to be configured before they can do their work. To do so, the user must pass configuration arguments in the tag argument list. What arguments are expected and in what order can be found by looking at tag signature in the built-in tag documentation.
The argument list follows tag name and is contained between parentheses: ().
Each argument value is separated by a single coma , (with optional white spaces) and can be one of three types:
intfor integer numbers (that match-?[0-9]+regex)strfor quoted string literals (both single'and double"quotation marks can be used)boolfor boolean flags
Numbers can be accepted only in decimal (base 10) representation without fractional part: %Count(0, 1, 4)
String literals may contain any character except for the used quote mark - if the quote mark needs to be passed,
it should be escaped (prefixed) with a single backslash character, i.e. \' or \".
Boolean flags can accept two types of values: True/true or False/false.
Additionally, a shortcut exists for setting the flag argument to True - just use the flag name as an argument value (similar to explicit argument names in programming languages).
Therefore, the following invocations are equivalent:
%Trim(-2, left=True)
%Trim(-2, true)
%Trim(-2, left)
The tag prototype (which can be found in tag build-in documentation) describes the names and types of every argument the tag configuration expects:
%Trim(width: int, left: bool = False, right: bool = False){...}
The above prototype indicates that this tag accepts up to 3 arguments named width, left and right. The last two are optional as they have default False value.
User can prefix argument value with its name and = symbol to explicitly specify values just for the named arguments: %Trim(-2, right=True). This way, arguments can be passed out of (defined in the prototype) order: %Trim(left, width=-1)
Order of arguments is important if explicit names are not used: %Trim(-1, True) will set left flag because it's second in the argument list.
Similar to arguments, some tags can (or have to) operate on the context which is another way to pass the data to the tag. In contrast to the arguments, which have to stay the same during the entire renaming operation, contexts can change between each tag invocation. They might be considered a dynamic argument.
To pass a context to the tag invocation, use curly braces {} with template expression embedded between.
The curly braces can be placed directly after the argument list:
%Trim(5, left){Long text}
or (if the argument list is empty) directly after the tag name:
%Upper{small text}
The most important feature of contexts is their dynamic nature - they can contain entire sub-templates.
In the following example, the Lower tag receives context containing the processed file extension and makes it lowercase:
%Lower(){%Ext()}
To check if the tag might operate on a context, check build-in documentation. The symbol after the tag name indicates context requirements:
- No symbol - when prototype ends with just argument list (
(...)) - indicates that the tag doesn't operate on contexts and passing one will result in an error. {...}symbol indicates that this tag requires some context to be passed[{...}]symbol denotes that the tag can use the context if one is passed to it
Note: Currently pipe list syntax is limited as it has to be the last element of the whole (sub)template. This might change in the future.
Sometimes it is desirable to create a chain of context invocations such as:
%Lower{%Collapse{%Strip{%Name()}}}
To streamline such operations, pipe list syntax sugar can be used and above expression can be written as:
%Name()|%Strip()|%Collapse()|%Lower()
In the pipe list, there can be no contexts (therefore no curly braces) as the context is passed directly from the previous tag - from left to right.
Note: For pipe list syntax, an empty argument list is required to denote the end of the tag name. This behaviour might change in the future.
Filtering allows for inclusion/exclusion of specific files from the renaming operation.
There are three types of filtering expressions supported:
template- tag-template evaluated Python predicate expression, e.g.:%Size() > 10*1024glob- globbing expression, e.g.:*.mp3,IMG_????.jpgregex- python-flavored regular expressions, e.g.:.*\.jpe?g
Template-based filtering is the most powerful and allows for the inclusion/exclusion of files based on their metadata.
A filter expression can be passed with --filter-template/-ft flag.
Filter expression tag template is rendered for each file and evaluated as Python expression.
If the result of evaluation is truthy, the file is considered for renaming.
For example, the following filtering template will exclude files larger than 1024 bytes:
%Size() <= 1024
Standard Python boolean operators (and, or, not) and built-in functions can be used to chain multiple conditions.
For example, to include only image files that are not PNGs, the following filter expression can be used:
%IsMime("image") and not %Ext().endswith("png")
Note: Filtering templates are evaluated a bit differently from the ones used for name generation - values generated from the tags are escaped to create valid Python literals. Therefore, above expression could be rendered as:
True and not ".png".endswith("png")
Glob filtering allows to include/exclude files based on the glob expression matching their filenames. People used to the terminal should be familiar with this kind of filtering as it's the same one used by most *nix shells.
For example, to rename only files with an Image_ as a prefix, the following pattern can be used:
Image_*
Regular expression filtering allows to include/exclude files based on regex expression matching their filenames.
For example, to rename only files that start with a digit, following pattern can be used:
^\d.*
This feature uses Python-flavored regular expressions.
Note: Regular expressions are infamous for their complexity. It is always better to prefer a simpler solution if it can accomplish the same result.
Sometimes it might be easier to specify a filter for files which should not be included.
To negate/invert any filtering expression you can use --filter-invert/-fi flag.
In some cases (i.e. when Count tag is used), files should be processed in specific order to make renaming useful.
--sort/-s flag can be used to order files based on their metadata.
Sort expression is similar to the filter template in a way that it is also used to generate a Python expression which, after evaluation, is used to order the files considered for renaming.
For example, to order files based on their original name, the following expression can be used:
%Name()
In contrast to filtering expressions, the sorting expression has to be evaluated into a valid Python tuple literal (excluding parenthesis). So, to add another sorting criteria (for cases where the first key may repeat across files), a comma , should be used as a sorting criteria separator.
For example, to order files based on their extension the first and then their size, the following expression can be used:
%Ext(), %Size()
Note: Sorting templates are evaluated a bit differently from the ones used for name generation - values generated from the tags are escaped to create valid Python literals. Therefore, above expression could be rendered as:
(".png", 12345)
By default, the sorting expression order files in ascending order.
To change this behaviour, --sort-invert/-si flag can be used.
File conflict arises when a template generates the same path for two different files or the generated path already exists in the filesystem.
tempren supports the following conflict resolution strategies:
stop- Reports an error and stops program execution (default, indicated by--conflict-stop/-csflag)ignore- Reports problem as a warning and continues renaming leaving source file name intact (enabled with--conflict-ignore/-ciflag)override- Replaces destination file with the one being processed (enabled with--conflict-override/-coflag)manual- Interactively prompts the user to select one of the above conflict resolutions (enabled with--conflict-manual/-cmflag)
If the built-in tag library doesn't contain the tag appropriate for the user problem, tempren allows importing external executables as new, ad-hoc tags.
To create an ad-hoc tag, you will need to provide an executable path as an argument to the --ad-hoc/-ah flag. After doing so, a new tag will be placed under Adhoc category, and you will be able to see its documentation (i.e. invocation details) with the help of --help/-h flag:
tempren --ad-hoc awk --help awk
Note: When executing the ad-hoc tags, even with
--dry-run/-drflag,temprendoesn't have control of the behaviour of the invoked executables. Care should be taken to make sure that the user-provided program doesn't create any undesirable side effects upon template execution.
There are two ways in which an executable associated with an ad-hoc tag can be invoked. If no context is provided in the tag template, the relative path to the processed file is appended as the last parameter to the command line.
For example, to count lines of the processed text file, an awk utility can be used as such:
tempren --ad-hoc Awk=awk '%Base()_%Awk("END {print NR}")%Ext()' *.txt
This invocation will result in the execution of awk 'END {print NR}' <processed-file-path> command for each processed file.
Explicit naming (Awk= part in the above example) can be skipped. This will result in the base name of the executable being used as a tag name.
If the context is provided, it will be passed to the command's standard input (stdin) and the command will not receive the processed file path.
For example, tr utility can be used to remove some characters from the base file name by passing it to its standard input (context) as such:
tempren --ad-hoc Tr=tr '%Tr(" _\\-.@~", "-"){%Base()}%Ext()' --help Tr
Regardless of how the underlying ad-hoc executable will be invoked, any data sent to the stdout by it will be used as a tag output
and any data sent to the stderr channel will be ignored.
If the invoked command returns a non-zero error code, tempren will report this as an error.
Program arguments can be passed in the ad-hoc tag arguments but care should be taken to
separate them correctly as spaces do not delimit the arguments like in the shell environment.
For example, to pass two parameters to the ad-hoc Program, the following syntax should be used:
%Program("--flag", "flag-argument")
Tag aliases are templates that can be reused as standalone tags.
To create a new alias, --alias/-a flag can be used:
tempren --alias 'Normalized=%Lower{%Name()}' --help Normalized
Tags created from the aliases cannot receive any arguments or context - they are simply placeholders where the underlying template will be inserted.
To facilitate discovery-based usage learning, tempren's --dry-run/-dr flag can be used to disable the actual file renaming stage of the pipeline. This way, users can test their templates without making changes to the filesystem.
Note: While dry-run is active, side effects from filtering/sorting template expressions (which are valid Python code), ad-hoc tags or even tags themselves may still affect the file system.
Be careful not to copy-paste templates that look suspicious.
The number of messages produced by the tool can be increased with --verbose/-v flag
and decreased by --quiet/-q flag.
Normal messages are directed to the standard output (stdout) while warnings and errors are sent to stderr.
Hidden files handling
By default, tempren won't consider hidden files or directories for renaming.
To include such files in the renaming process, --include-hidden/-ih flag can be used.
Note:
--include-hiddenin combination with--recursiveflag, changes how file discovery is performed. When both flags are specified, hidden directories and any files in them will be considered for renaming.
If the command line argument starts with a @ symbol, tempren will assume that it is a file containing the desired program arguments, and it will load it (treating each line as a separate argument).
This is especially useful in the case of reusing the same pattern (or program arguments in general) over and over.