Variables

Variables enable you to access almost all the data stored in your database. Many IMatch features allow the use of variables to customize the data displayed or processed.

Many IMatch features and functions support variables. Here are some examples:

• File Window Layouts
• File Window Tip
• Renamer
• Batch Processor
• Text Export
• Design & Print
• Slide Show
• Viewer Text Overlay
• ...

Quick Tip: The VarToy App

The Var Toy App allows you to interactively try out variables.

Variables Syntax

A variable is just a bit of text following a specific syntax. All variables look like this:

{Application.DateTime}

This above variable returns the current date and time, formatted using the format configured for the current user the Windows Control Panel.

{File.FullName}

This variable returns the fully qualified file name of a file, e.g. "c:\images\beach.jpg".

Optional Arguments

Some variables support additional arguments, which are appended to the variable name, separated by a pipe | symbol:

{Application.DateTime|format:YYYY}

The argument format:YYYY tells IMatch to output only the year part of the date, e.g. "2012".

Syntax

The general syntax for variables is:

{Variable Name|Arguments}

The surrounding braces { } and the variable name are mandatory, the |Arguments part is optional.

Examples

{Application.Version}
{User.Name}

{File.FullName}
{File.DateTime}
{File.Rating}
{File.Size}

Example output:

2020.11.4
Mario

c:\images\beach
24.05.2023 12:33:11
5,00
36,2 MB

Using Variables

Usually you just enter the variable name using the syntax described above. In most cases you can freely mix variables with literal (free) text:

The name of this file is {File.FullName}.

The output of this statement would be something like this:

The name of this file is c:\images\Beach.jpg.

You don't need to memorize variable names!
You just select them in the Variables Selectors dialog box, which is accessible from all features which allow the use of variables. Look for this button:

Before we go into the details of variables and explain all the details, please look at these example uses. This makes it easier to understand the concept behind variables and shows how you can use them to customize IMatch to your personal requirements.

Using Variables in the Slide Show

In the slide show configuration you use variables to specify the contents of the text overlay:

Use variables to tell the slide show what information you want to see in the text overlay.

The Slide Show offers some dedicated variables which can only be used in the slide show.

Using Variables in the Renamer

In the Renamer you can use variables mixed with literal text to produce file names based on metadata:

In this example, we use the {File.Datetime} variable and append the "format:YYYY" argument to extract only the year. For an image taken in 2012, the variable resolves to _2012 and the resulting file name would be something like "_DSC32728_2012.JPG"

Using Variables in the File Window Tip

The file window tip pops up when you point at the info icon visible in each thumbnail panel. The data shown in the tip is configured using variables.

The first example uses only the file name and the date and time the image was taken:

Standard file window info tip with two rows of information.

The second example uses additional variables and also some formatting attribute to create a much more advanced version of file window tip:

Fancy file window tip with different fonts and colors and sizes.

The Variables Selector Dialog

Depending on which feature you use, different sets of variables are accessible. The Application and User variables are always available. The File variables are also available for features which work with files, and also the Shortcode Variables, which cover most frequently used metadata tags.

Some features provide additional variables, which are available only within that specific feature. One example would be the Renamer or Design & Print, which offer special variables only useable within these features.

In all IMatch features which allow the use of variables you can pick variables from the Variable Selector dialog box. The dialog lists all variables available in the current scope.

Selecting the variable {File.FullName}}

The Variables tab in the dialog shows all standard variables: Application, User, File and Shortcodes. The Last recently used tab list the 50 last recently used variables for quick access.

If the Variable Selector dialog can determine a current file, it shows the actual value of each variable in the tooltip.

ShortCodes

IMatch provides a large number of ShortCodes for all frequently used metadata tags. These variables are shorter and much easier to remember than the actual metadata tag. For example, {File.MD.description} or {File.MD.aperture} or {File.MD.gpslatitude} which produces the same result as {File.MD.XMP::exif\GPSLatitude\GPSLatitude}, but is much shorter.

ShortCodes in the Variables Selector

Always use ShortCodes, where available. They are not only shorter and easier to remember, but they also shield you from potential changes in the actual tag name.

Sometimes ExifTool has to rename a tag and then your variable will not longer produce the correct result. If you use ShortCodes instead of the actual tag name, your variable will work as before - because the change in the tag name is hidden by the ShortCode.

If no ShortCode is available for the tag you want to use in your variable, use the full tag name. For this, the Variables Selector gives you direct access to the Metadata Tag Selector.

Metadata Tag Selector...

Metadata variables give you access to all the metadata stored in the IMatch database. This includes IPTC, EXIF, XMP, ID3, PDF and other metadata tags.

See Introduction to Metadata for more information about metadata.

If you want to use metadata variables (File.MD.), click on the Tag Selector... button. It opens the standard Tag Selector dialog which allows you to select metadata variables comfortably. See below for more information on metadata variables.

You can copy properly formatted metadata variables into the Windows clipboard right from the Tag Selector dialog. Use this to transfer metadata variables from the dialog into the feature where you want to use the variables. Or, copy all the variables you frequently use into a small text file and keep this for reference.

Standard Application Variables

IMatch provides a set of variables which allow you to access the current date and time, special folders locations and more. These variables are available in all contexts and are especially useful in scripts.

User Variables

These variables allow you to retrieve some user-related data:

User-defined Variables

You can configure application variables under Edit > Preferences > Variables.

These user-defined variables enable you to manage frequently used text fragments like your copyright notice, address, agency code etc. in one central place.

You can use them everywhere you can use variables, e.g., in the Renamer, text export modules etc. Keeping stationary data like your copyright notice or studio name in a variable allows you to change all occurrences of this stationary at one single place.

Syntax for User-defined Variables

The syntax for this type of variable is:

{Application.Variables.Name of Variable|Arguments}

Name of Variable is the name of the variable you specified under Edit > Preferences > Variables. The |Arguments part is optional.

For example, if you create two variables MyCopyright and CompanyName, the corresponding variables will be accessible as:

{Application.Variables.MyCopyright}
{Application.Variables.CompanyName}

Variables Returning Multiple Values

Some variables may return multiple values. For example, the variable {File.MD.hierarchicalkeywords} returns the keywords of a file. If the file has multiple keywords, the variable separates them with the IMatch list separator configured under Edit > Preferences > Metadata. This is by default a semicolon and you should not change it under normal conditions.

Example

A file has the hierarchical keywords:

Location|Country|Italy
Motive|Landscape
Motive|Family

The variable {File.MD.hierarchicalkeywords} (which is a short code) returns:

Location|Country|Italy;Motive|Landscape;Motive|Family

Each keyword in the file, separated with the IMatch list separator.
This behavior is the same for all variables which return lists, e.g., {File.Categories}, {File.Pins}, {File.Persons.Label} or {Files.MD.creator}.

Replacing the List Separator Character

You can use the replace: function to replace the default list separator in the variable output. For example:

{File.MD.hierarchicalkeywords|replace:~;==, }

replaces the ; with , to produce:

Location|Country|Italy, Motive|Landscape, Motive|Family

File. Variables

These variables provide information about each file indexed by your IMatch database. You will use these variables frequently. Together with the metadata variables they give you full access to almost all the data contained in your database.

Syntax for File Variables

The syntax for this type of variable is:

{File.Name of Variable|Arguments}

The "File." prefix and the variable name are mandatory, |Arguments is optional.

Examples:

{File.FullName}
{File.DateTime|format:YYYY}

List of File Variables

File Variables
File.OID	The unique number (OID: object identifier) IMatch assigns to each file. This number is used for internal purposes and may change at any time.
File.LTID	A globally unique identifier (GUID) IMatch assigns to each file when it is first added to the database. This identifier does not change as long as the file remains in the database. It uses the standard GUID format, e.g.: A8215BFA-5AEE-4C23-B463-5E7B7D1E7488
File Names and Folders
File.NameExt	Name and extension of the file: "beach.jpg"
File.FullName	Fully qualified file name: "c:\images\2012\beach.jpg"
File.Name	File name without extension: "beach"
File.Ext	File extension: ".jpg"
File.Folder	Folder name: "2012"
File.Path	Path with trailing backslash: "c:\images\2012\"
File.Folder.FriendlyName	Returns the friendly name of the folder containing the file, or an empty string if the folder has no friendly name.
File.Folder.Description	Returns the description of the folder containing the file.
File.Folder.Media.SerialNumber	Returns the serial number of the media containing the folder.
File.Folder.Media.Label	Returns the label of the media containing the folder.
File.NameExtS	These variables are identical to the variables without the "S", but use the short file names supplied by Windows for FAT-formatted media. See the Windows help for details.
File.FullNameS
File.NameS
File.ExtS
File.FolderS
File.PathS
File.CacheFileName	IMatch maintains cached JPEG files for the files in the IMatch database (see The Cache for details). This variable returns the name of the associated cache file, or an empty string if no cache file exists. The returned cache file is determined applying the appropriate relation rules for visual proxies.
Image Information
File.Class	The class of the file as maintained by IMatch, e.g. "image" or "audio"
File.Format	The format tag associated with the file format, e.g. "MP3" or "JPEG". A file format manages one or multiple file extensions.
File.Size	The size of the file on disk, in bytes.
File.Megapixel	Returns (Width * Height) / (1000 * 1000). For a file with 3000 x 4000 pixels, this variable returns 12. The data type is real so you can use cast and format as needed.
File.CRC	The 32-Bit checksum of the file, e.g. 3.064.782.803.
File.CRC.Hex	The 32-Bit checksum of the file in hexadecimal format, e.g. B6ACDFD3.
File.Width	Width in pixels. This variable returns 0 if the file is not an image.
File.Height	Height in pixels. This variable returns 0 if the file is not an image.
File.LongEdge	Returns the number of pixels for the longest edge. For an image with 800 x 600 pixel, this returns 800.
File.ShortEdge	Returns the number of pixels for the shortest edge. For an image with 800 x 600 pixel, this returns 600.
File.BPP	Bits per pixel (e.g. 24). This variable returns 0 if the file is not an image.
File.AspectRatio	The aspect ratio of the file: 1:1 3:1 3:2 4:3 5:4 5:7 6:7 16:9 16:10 If the dimensions are don't match one of the standard aspect ratios, the variable returns an approximated aspect ratio, like 637:200 for an image with 2548 x 800 pixel. The variable returns 0 if the file if no aspect ratio can be determined (e.g. for text files or other files with width/height 0).
Date and Time
File.Added	Date and time the file was added to the database. This information is extracted from the file history maintained by IMatch.
File.Updated	Date and time the file was last updated in the database. This information is extracted from the file history maintained by IMatch.
File.Created	Date and time the file was created on disk (as reported by the Windows file system). Note: This variable is expensive to calculate because IMatch has to query the file system for this information every time it is requested. It is not cached in the database.
File.Modified	Date and time the file was last modified on disk. This is the same timestamp you see in Windows Explorer.
File.DateTime	Returns the original value of the global File.DateTime timestamp IMatch maintains for all files in the database. The date and time is formatted using the date and time format configured for the current user in Windows. You can change the format with the format function. See How IMatch uses Date and Time for more information.
File.DateTime.TZO	Returns the same timestamp as File.DateTime but with the time zone offset appended. If File.DateTime returns a timestamp like 8/16/2023 12:00:00 and the time zone offset recorded for File.DateTime is +04:00, File.DateTime.TZO returns 8/16/2023 12:00:00+04:00.
File.DateTime.UTC File.DateTime.UTC.TZO	Returns the value of the global File.DateTime timestamp in UTC, with or without the Z indicator.
File.DateTime.UTCOffsetInMinutes	Returns the time zone offset in minutes (positive or negative) used to calculate the global File.DateTime timestamp. This makes the offset easily accessible for custom formatting and calculations. See How IMatch uses Date and Time for more information.
File.DateTime.UTCOffset	Returns the formatted (+/-HH:MM or Z) value of File.DateTime.UTCOffsetInMinutes.
File.DateTime.Original File.DateTime.Original.TZO	Returns the same timestamp as File.DateTime and File.DateTime.TZO, respectively.
File.DateTime.Local File.DateTime.Local.TZO	Converts the global File.DateTime timestamp into the current local time zone (as set in Windows), accounting for daylight saving time (DST). If the .TZO variant is used, the local time zone is appended.
Example: Here is an example that shows the results of all the various File.DateTime.* variables. The file used for this example has the timestamp 30.12.2022 14:00:00+02:00 {File.DateTime} 30.12.2022 14:00:00 {File.DateTime.TZO} 30.12.2022 14:00:00+02:00 {File.DateTime.UTC} 30.12.2022 12:00:00 {File.DateTime.UTC.TZO} 30.12.2022 12:00:00Z {File.DateTime.Original} 30.12.2022 14:00:00 {File.DateTime.Original.TZO} 30.12.2022 14:00:00+02:00 {File.DateTime.Local} 30.12.2022 13:00:00 (assuming the German +01:00 time zone) {File.DateTime.Local.TZO} 30.12.2022 13:00:00+01:00 {File.DateTime.UTCOffsetInMinutes} 120 {File.DateTime.UTCOffset} +02:00
File.MetadataImport	Date and time of the last metadata import in local time.
File.MetadataImport.UTC	Date and time of the last metadata import in UTC.
File.MetadataWriteBack	Date and time of the last write-back in local time. If the file was never written back, this returns 0. Available since IMatch 2023.3.4.
File.MetadataWriteBack.UTC	Date and time of the last metadata import in UTC. If the file was never written back, this returns 0. Available since IMatch 2023.3.4.
File.Duration	This variable returns the duration (play length) of the file in seconds. It is available for many video and audio formats.
File.Duration.HMS	This variable returns the duration (play length) of the file in HH:MM:SS (Hour:Minute:Second) format.
File Status
File.ReadOnly	Returns "No" or "Yes" (translated to your local language), depending on whether the file is read-only on disk or not.
File.PendingUpdate	If the file needs to be refreshed/reloaded, this variable returns "Yes", else "No".
File.MetadataModified	Returns "Yes" if the file has pending metadata updates (pending write-back), else "No".
File.Offline	Returns "Yes" when the file is off-line, else "No".
File.Protected	Returns "Yes" when the file is protected, else "No". See also Application.ProtectedFiles.Visible above.
Collections
File.Bookmark	Returns "Yes" when the file has a bookmark, else "No"
File.Flag	The title of the flag of the file or an empty value if the file has no flag.
File.Dot	The color of the dot or an empty value if the file has no dot.
File.Pins	List of all pins set for the file, separated by ; . Returns an empty value if the file has no pins.
File.Label	The name of the assigned label or an empty value if the file has no label.
File.LabelColor	The color associated with the file label, formatted in the standard HTML color format: #rrggbb, where rr is red, gg is green and bb is blue. Returns #ffffff (white) if the file has no label or no color was configured for the label.
File.Rating	The file rating. -1.0 for rejects, 1.0-5.0 for the corresponding rating, empty value if the file has no rating. The XMP rating tag is a floating point number. It will be formatted with decimals ("3.00") unless you use the cast:int formatting argument to change this ("3"). IMatch formats floating point variables using the settings of the current locale (Windows Control Panel > Regional Settings).
File.Relations	Textual expression of all Relations (master/version) of this file.
File.Versions	List of fully-qualified version file names. Only available for master files.
File.Versions.NameExt	List of version file names (name.ext). Only available for master files.
File.BuddyFiles	List of fully-qualified buddy file names for this file.
File.BuddyFiles.NameExt	List of buddy file names (name.ext) for this file.
File.Relations.IsMaster	True when the file is a master.
File.Relations.IsVersion	True when the file is a version.
File.Relations.Color	The color, if a color was assigned to the file relation. Else Null.
File.Relations.Stack.Count	The number of versions (elements in the version stack, including the master). This variable is only filled for masters.
File.Relations.Stack.State	Returns "expanded" or "collapsed".
File.Stack.IsTop	Returns Yes if this is a stack top.
File.Stack.IsElement	Returns Yes if this file is stacked (but not a stack top).
File.Stack.Color	The color, if a color was assigned to the stack. Else Null.
File.Stack.Count	The number of files in the stack.
File.Stack.State	Returns "expanded" or "collapsed".
File.Annotations	Textual expression of all Annotations of this file.
Categories
File.Categories File.Categories.Direct File.Categories.DirectNoAlias	A list of all categories containing this file, including data-driven categories and categories referencing this file via a formula. The Direct variable only returns the categories to which the file is directly assigned; it ignores data-driven categories and formulas. The DirectNoAlias works the same but ignores Alias categories. This can be very useful, e.g. if you want to extract categories under a parent category (e.g. "Family") and don't want all Alias categories from that hierarchy to be included. if you link the same person into multiple sections of the Family hierarchy, you may want to count it only once. Example: {File.Categories.DirectNoAlias|filter:^People;count:true} This variable counts the number of categories under the @All|People hierarchy a file is assigned to. Alias categories are ignored.
File.Categories|level:root File.Categories.Direct|level:root	Returns the root categories (top-level categories) Location; Style
File.Categories|level:leaf File.Categories.Direct|level:leaf	Returns the bottom-level categories Daytona; Landscape
File.Categories|level:0 File.Categories.Direct|level:0 File.Categories|level:1 File.Categories.Direct|level:1 ...	By specifying a level you can access individual levels of your category hierarchy. Level 0 is identical with root, level 1 is the level below the root and so on. You can also use negative levels to address levels starting at the leaf: level-1 means the level above the leaf, level-2 means the category two levels above the leaf etc. Using an index allows you to address specific levels, even when the total number of levels in your hierarchy is unknown or varies. Example: We use this category hierarchy for this example: Location|Outdoor|Beach|Daytona File.Categories.Direct|level:0 Location File.Categories.Direct|level:1 Outdoor File.Categories.Direct|level:2 Beach File.Categories.Direct|level:-1 Beach File.Categories.Direct|level:-2 Outdoor The VarToy App is a always helpful to run tests with variables and to just try things out.
Filtering Category Variables See the Combining Category level and filter below for important information.
File.Categories|filter:RegExp	The filter function allows you to filter the categories of a file by a regular expression, identical to the @Category[] category formula. For example: {File.Categories.Direct|filter:^Gender} This variable returns only categories matching the regular expression ^Gender, which are all categories starting with the term Gender, e.g. "Gender|Male", "Gender|Female". The following expression returns only categories under the Persons root category, and from here only the leaf level: {File.Categories|filter:^@Keywords;level:leaf;replace:~;==, } This variable emits all leaf-level keywords of a file (only categories beginning with @Keywords) by applying a level:leaf formatting function. It also replaces all ; in the returned text with , <blankk> to allow the list to word-wrap, e.g. in File Window Layouts. {File.Categories.Direct|filter:^Persons;level:leaf} If you have categories like 'Persons|Family|John', 'Persons|Family|Mary', 'Persons|Business|My Company', ... this variable first finds out to which categories starting with Persons the current file is assigned, and then returns the leaf category. This is a very powerful function which can help you solve tricky requirements. For example, you can use this to control which categories you want to see, e.g. in the File Window or the Viewer or a Batch Processor text overlay. Such a construct allows you to output only the Person category to which a file is assigned. It does not matter to how many other categories the file is assigned as well. This can be very useful for situations where you want to output the Family assignment only. Of course this also works with other category names, even on lower levels: {File.Categories.Direct|filter:blue} This variable returns all categories for the current file which contain the word blue somewhere in their fully qualified name. {File.Categories.Direct|filter:blue$} Returns all categories for the current file which end with the word blue. Tip: Counting the number of people in an image Assuming you assign keywords like Persons|Bill or Persons|Mary to your files, you can use this variable to determine the number of Persons categories assigned to an image: {File.Categories|filter:^@Keywords\|Persons;count:true} Then you can use the resulting number e.g., in Metadata Templates or to produce a data-driven category.

Combining Category level and filter

If you use both filter and level, the order in which these appear in the variable matters.
If filter appears before level, the filter expression is applied to the entire category path. And then the requested level is returned. If level appears first, the filter expression is only applied to the selected level.

Example:

Consider a category name like WHERE|Outdoor|Beach.

The second variable uses level before filter and the filter expression is thus applied to the word Outdoor, which does not match beach.

Persons. Variables

These variables return information about persons shown in the image. Using these variables allows you to display the names of these persons, their age (relative to the date of the image) and other useful data.

Repeatable Values

All File.Persons.* variables may return zero to many values. If a file has no face data or none of the faces has a person assigned, the variables return nothing. If a file has two or more persons, the variables return the data as a list, separated with a semicolon: Peter;Paul;Mary. You can use the index function to access data of specific persons in that list.

{File.Persons.Age}

{File.Persons.Age.Verbose}

{File.Persons.Age.Remainder}

Using Persons Variables

A typical use-case for this type of variable is to list the persons in an image in a File Window layout or to print them as a caption next to the image with Design & Print.

Listing all Persons

{File.Persons.Tag|replace:~;==, }

This variable enumerates all persons in the image and lists them. The ; separator used in case there are multiple persons in the image is replaced with a comma and a space.

Example Output

Peter, Paul, Mary

{File.Persons.Tag|foreach:{value} ({File.Persons.Age.Years|index:{index}}) }

For each person the tag and, in (), the age in years is printed.

Example Output

Peter (33) Paul(35) Mary (28)

To separate the individual tokens produced by the foreach function, we can add some more code:

{File.Persons.Tag|foreach:{value} ({File.Persons.Age|index:{index}}){remaining|is:0,,{remaining|is:1, and ,+ ;replace:+==,}}}

This variable lists all persons in the image. For each person the age is added in (). All persons are separated with , except for the last person, which uses and.

Example Output

Peter (33), Paul(35) and Mary (28)

Faces. Variables

These variables give access to the faces detected in the image. They may be helpful in certain situations.

All variables return a list of zero to n values, separated with a semicolon. You can use functions like foreach, count and similar to access individual faces.

Events. Variables

If you use IMatch Events to organize files, you can use event variables to access the event(s) a file is associated with. This makes it possible to display the event name in a file window, use it for Batch Processing, Design & Print and more.

{Files.Events.Title}

Attribute Variables

When you work with Attributes in your database, IMatch makes all Attribute contents available via dedicated variables. This allows you to use Attribute data wherever you can use variables.

Syntax for Attribute Variables

Attribute variables use the following syntax:

{File.AT.Set Name.Attribute Name|Arguments}

The File.AT. prefix is mandatory. Set Name is the name of the Attribute Set and Attribute Name is the name of the Attribute. The |Arguments part is optional.

If you have an Attribute Set named 'Submissions' and you want to display the contents of the 'Revenue' Attribute in that set, the variable name would be:

{File.AT.Submissions.Revenue}

Attribute variables can be selected comfortably from the Variables Selector dialog.

Examples

{File.AT.Info.Note}
{File.AT.Submissions.Revenue|sum:true}

Global Sets

If your per-file attribute set contains reference attributes, you access them like any other attribute variable. But you can also access individual attributes of the global set. Consider the following example: You have a per-file Attribute Set named Info, and one global Attribute Set named Client:

This allows you to use variables like

{File.AT.Info.Note}
{File.AT.Info.Date}
{File.AT.Info.Client}

The last variable above returns the Name attribute of the record to which the Info record links in the global set. This is also what you will see in the Attributes Panel.

In addition, you can also access other attributes in the global se as follows:

{File.AT.Info.Client.Name}  ' This is the same as {File.AT.Info.Client}
{File.AT.Info.Client.Email}
{File.AT.Info.Client.City}
{File.AT.Info.Client.Street}

Metadata Variables

These variables give you full access to all metadata stored in the database, including IPTC, EXIF, XMP, PDF and ID3 data. They use the same tags which are also used for the metadata panel.

Syntax for Metadata Variables

Metadata variables use the following syntax:

{File.MD.Tag|Arguments}

The File.MD. prefix is mandatory. Tag is the full tag name of the metadata value you want to access. The |Arguments part is optional.

Metadata variables can be selected comfortably from the Variables Selector dialog.

For example, the standard tag "Model" contains the name of the camera model used to take a photo. The corresponding variable is:

{File.MD.Exif::Main\272\Model\0}

If you want to display the description you have entered for a file, you would use:

{File.MD.XMP::dc\description\Description\0}

Don't let yourself get confused about the long and sometimes cryptic names of these variables. You don't need to memorize them. Just select the variable you need in the Variables Selector dialog.

Repeatable Tags

Some metadata tags allow for multiple values, e.g. IPTC/XMP keywords or the Creator/Authors. Metadata variables for these tags return a list with all values, separated by the list separator specified for the current locale in the Windows control panel.

For example, the output of a variable for a keyword tag looks similar to this:

location|beach;outdoor;sun;sand;vacation;holiday

You can change the separator used by a replace: formatting argument. See below for details.

Instead of the full tag key, you can use ShortCodes for many frequently used tags. See Table of Available ShortCodes.

File Window Variables

There is a set of variables which can be used in File Window Layouts for custom templates.
See File Window Variables in the File Window Layouts help topic for more information and examples.

Formatting Variables

The optional arguments you can append to a variable allow you to format or change the variable contents. Not all variables support formatting arguments and all variables ignore unknown or unsupported formatting arguments.

Formatting arguments are specified as key:value pairs after a separating pipe | character. The general syntax is:

{Variable|key:value; key:value; ...}

Formatting arguments are separated with a semicolon ; . The last argument does not need a terminating semicolon.

Examples:

{File.DateTime|format:YYYY}

Extracts only the year from the datetime variable.

{File.Rating|cast:int; replace:0==No Rating}

Treat the rating of the file as an integer ("3" instead of "3.00") and to output the text "No Rating" if the rating is "0".

Casting Variables

These formatting arguments are available for numeric variables:

{File.Rating}            => 1,00
    {File.Rating|cast:int}   => 1

{File.Bookmark|cast:int;is:0,Nope!;is:1,Yippee!} 

1  => 1
    10 => A
    15 => F

1  => I
    10 => X
    15 => XV

If your numeric settings (Windows control panel) use the same character for the list separator and the thousand grouping symbol or decimal comma/point, (e.g, a comma ,), the cast operator no longer processes lists of values and assumes that the value to cast is not a list. There is no way to tell if 1,234,567 is the number 1234567 or a list of numbers 1 234 567 in this case.

Metadata Variables: Formatted and Raw

Metadata variables give you access to metadata like IPTC, EXIF or XMP. IMatch uses the default formatting as provided by ExifTool.

For all metadata values imported via ExifTool, IMatch, caches both the formatted value and the so-called raw value (numerical value) if delivered by ExifTool. A raw value is a numerical value stored inside the metadata block which has a textual representation or translation.

Not all metadata tags have a raw value. ExifTool also does not deliver a raw/numerical value when it is identical to the formatted value.

Some examples are:

By default, all metadata variables return a value formatted using the data type of the metadata tag. This is the best choice for almost all situations. But sometimes you may want to access the raw value instead, or the unmodified formatted value as delivered by ExifTool.

To access the raw value, you can use the raw and rawfrm formatting arguments:

{File.MD.XMP::exif\GPSLongitude\GPSLongitude\0}                => 8 deg 31' 30.72"
    {File.MD.XMP::exif\GPSLongitude\GPSLongitude\0|value:rawfrm}   => 8.525201
    

To access the original formatted value, you can use the value:formatted formatting argument:

{File.MD.Composite\Exif-ShutterSpeed\ShutterSpeed\0}                   => 0.01
    {File.MD.Composite\Exif-ShutterSpeed\ShutterSpeed\0|value:formatted}   => 1/160

Exif-Shutterspeed has a data type of real (a floating point number) so the value returned by IMatch will be 0.01 (rounded from 0.00625) using the numeric format as defined in the Windows Control Panel. To override this and to use the text value produced by ExifTool, use the value:formatted attribute.

Supported value: Attributes:

Note that the formatted and raw/numerical value may differ until the file is written back. ExifTool produces the formatted value for tags when IMatch ingests metadata (during the initial ingest, when the file is changed or when metadata is written back). IMatch in some cases (e.g. for GPS coordinates) works with and modifies the raw value and this may result in an empty formatted value or a mismatch between the raw and formatted value until metadata is written to the file.

See also Metadata Panel Layouts for additional info.

Note: Date and Time Format

IMatch and ExifTool use a standardized ISO format for working with date and time data. This avoids issues caused by country-specific date- and time formats. The format used is:

YYYY:MM:DD hh:mm:ss{time zone +/- hh:mm or Z}

where the time zone is optional.

Examples: 2020:12:01 12:11:10 or 2020:01:29 17:52:19+02:00 or 2021:03:17 19:18:17Z

Date- and time variables in IMatch are by default formatted in your local date and time format. For example:

{File.DateTime}

returns 13.07.2021 18:14:31 for a German user but 13/07/2021 06:14:31pm or 2021-07-13 06:14:31pm in the US.

When you use a variable to fill a date- and time metadata tag (for example you copy date and time data from one tag into another or you use Attributes variables) you have to make sure that you format the date correctly. ExifTool expects the standard ISO format YYYY:MM:DD HH:MM:SS (with an optional time-zone offset or Z).

To create this format, just add a format instruction to your variable:

{File.DateTime|format:YYYY:MM:DD hh:mm:ss}

Local Time vs. Time-zone Offsets

Keep in mind that variables for date and time tags by default return the localized time, applying time-zone offsets as needed before returning the value. This can be important.

For example, consider the value 2020:08:07 09:42:55+04:00 stored in a tag like XMP::photoshop\DateCreated\DateCreated (the date subject created tag). Depending on how you use the variable, you get different results. We used the time-zone GMT+01:00 (Germany) and the German date and time format for this example:

z or Z

Both the z and Z token used with a time format string make the variable emit the time-zone offset and prevent conversion into the local time-zone. The difference between the two tokens comes into play when the time has no time-zone offset or the zero offset 00:00.

Assuming the source time is 08:32:51: if you use z, no time-zone offset is emitted in this case and you get 08:32:51. If Z is used, the variable emits 08:32:51Z to indicate that this time value is assumed to be at UTC+00:00. For a time value with a time-zone offset like 08:32:51+02:00, both tokens produce 08:32:51+02:00.

Formatting Functions

IMatch provides some functional arguments which allow you to extract parts of the variable content, replace contents or supply default values.

prefix:Text postfix:Text	This functions allows you to specify a text to prepend (prefix) or append (postfix) to the variable content. Both functions are only evaluated when the variable has content. This makes it possible to display text before and after the variable, but only if the variable is filled. Examples: {File.Label|prefix:Label:<Bold>; postfix:</Bold>} Produces Label: "<Bold>{File.Label}</Bold>", which results in: Label: Yellow if the file has a yellow label. If the variable is empty, no text is emitted. The postfix function is executed after all other functions have been processed. This means you cannot use functions (e.g., replace) to modify the results of postfix.
default:Text	Allows you to specify a default value. This value will be returned if the variable is NULL or an empty string. default behaves differently from other functions: it is a shortcut evaluation function. If it exists and is applied, no other variable functions are executed. You can use defaultex as an alternative. it does not perform escaping on the default value. Characters unsafe for XAML are not escaped. You can use variables for the default value. Examples: {File.Label|default:No Label} If the file has no label, the text "No Label" is returned, else the label name of the file.
defaultex:Text	This function is used for the same purpose as default, but behaves differently in two ways: It is integrated into the normal variable processing, which means that other functions are processed even if defaultex is used. It performs normal escape processing to strip unsafe characters from the defaultex text.
hasvalue:Text	If the variable has a value (not NULL, not empty), it will be replaced with Text. This function is useful if you want to display/emit a specific value (or another tag) if a tag contains data. Examples: {File.Label|hasvalue:This file has a label} If the Label tag contains data, the text "This file has a label" is returned instead. You can use a variable for Text, which allows you to return the value of a different tag if one tag has data, or a mix of text and other variables etc. Combine it with default to create if then else statements. For example:   {File.MD.XMP::exif\GPSLatitude\GPSLatitude|default:No GPS data;hasvalue:Has GPS data} which returns "Has GPS data" if the file has a non-empty latitude, and "No GPS data" if the latitude tag is empty. You can also nest this if you want, to check for multiple variables.
length	Returns the length of the variable in characters. Examples: {File.FullName|length} Returns the length of the file name. {File.MD.description|length} Returns the length of the XMP description.
is:Value,TV,FV,case	This function compares the contents of the variable with the Value parameter. If there is a match, TV is returned, else FV. If case is true, the comparison is case-sensitive (default: false). FV and case are optional parameters. If you don't specify FV and the function evaluates to false, the original variable content is returned. Examples: {File.MD.XMP::dc\creator\Creator}|is:John,Photo taken by John} If the value of the variable is 'John', the text 'Photo taken by John' is returned. {File.Label|is:Green,File is finished,File needs processing} If the file label is 'Green', the text 'File is finished' is returned, else 'File needs processing' {File.Label|is:Final,Finished: {File.Modified|format:YYYY-MM-DD}} Since we can use variables for the TV and FV arguments, we can construct neat expressions. This variable emits something like 'Finished on 2013-08-17' when the file label is 'Final'
contains:Value,TV,FV,case	This function searches the contents of the variable for the term Value. If found, TV is returned, else FV. If case is true, the comparison is case-sensitive. Both FV and case are optional. If you don't specify FV and Value does not match, the original content of the variable is returned.  Examples: {File.MD.creator|contains:photools,Created by photools.com,Unknown} If the creator tag contains 'photools', the text 'Created by photools.com' is returned, else the word 'Unknown'. {File.MD.headline|contains:Summer,#ffff00,#000000} This could be used to set a HTML color. If the headline contains the word Summer, the value #ffff00 is returned (HTML for bright yellow). Otherwise #000000 is returned, which is black.
regexp:Regular Expression//!,TV,FV,case	This function performs a regular expression match and returns TV when there is a match or FV otherwise. If case has the value true, the comparison is performed case-sensitive. Default is false. Everything between the first : and the closing //!, (no blank between //! and ,) is considered part of the regular expression, including : ; ~ and ,. This makes it easier to write complex expressions which often include one or more of these characters that also have special meanings in variables. Examples {File.Name|regexp:^[0-9]//!,Yes,No} Returns Yes if the file name starts with a digit. {File.Name|regexp:print$//!,Print,No Print} Returns Print if the file name ends with print. {File.MD.headline|regexp:^At the beach//!,Y,N} Returns Y when the headline tag starts with At the beach. {File.MD.hierarchicalkeywords|regexp:\bsun\b//!,T,F} Returns Y when the file contains the keyword sun. This expression uses a word boundary \b to match only sun but not sunny or sunbath. See Regular Expressions for more information.
find:Value,case	This function searches the contents of the variable for first occurrence of Value. If found, it returns the 0-based position of the term, else it returns -1. If the optional case parameter is true, the comparison is case-sensitive. Examples: {File.MD.title|find:Blue} For a title tag like Blue Sky, the find function returns 0. {File.MD.title|find:Green} For a title tag like Blue Sky, the find function returns -1. {File.MD.title|find:Sky} For a title tag like Blue Sky, the find function returns 5. If you expect the function to return a value >= 1000, optionally apply the cast:int function if you plan to use the result as input for some other function.
findreverse:Value,case	This function searches the contents of the variable from the back for first occurrence of Value. If found, it returns the 0-based position of the term, else it returns -1. If the optional case parameter is true, the comparison is case-sensitive. Examples: {File.MD.title|find:Blue} For a title tag like Blue Blue Sky, the find function returns 5. If you expect the function to return a value >= 1000, optionally apply the cast:int function if you plan to use the result as input for some other function.
numcomp:Op,Value,TV,FV,Mode	This function performs a numerical comparison between the variable and the term Value. It does this by first converting the variable value and the value specified as the second parameter into floating point numbers (real). Then it uses the given operator to determine the result. When Value is a number with digits (real), you must format it using a decimal point, not a decimal comma. 123.45 is correct, 123,45 is wrong. If you get the Value from another variable, you need to make sure that the result of the variable has the correct format (e.g., by using a cast). Depending on whether the result is true or false, the TV or FV values are returned. Supported operators (Op): eq equal  ne not equal lt less lte less than or equal gt greater gte greater than or equal Mode The optional Mode parameter can be specified as length. If you do this, numcomp does not use the value (content) of the variable, but calculates its length instead and uses that for the comparison. For example, a variable has the value "Duck". If you specify the mode as length, numcomp will use 4 when doing the comparison (the length of Duck). numcomp and Mode length can be used to limit the output length of a variable intelligently! Imagine you want to limit the output length of a variable to, say, 30 characters to prevent your file window layout to become cluttered. Or maybe you want to limit the text length used in the Batch Processor. To indicate that the text has been shortened you want to add an ellipsis (...). The following statement does this for the XMP description tag (we here use the tag shortcode instead of the long name): {File.MD.description|numcomp:gt,30,{File.MD.description|substr:0,30}...,{File.MD.description},length} We specify length as the last parameter. numcomp hence calculates the length of File.MD.description. If it is longer than 30 (gt 30) the TV is emitted, else the FV. We use {File.MD.description|substr:0,30}...  as the TV (true value). This means that when the description is longer than 30 characters, we only emit the first 30 characters and append a ... FV (false value) is set to {File.MD.description} and this means that if the condition is not met (length of the description is <= 30) we emit the full description. Try it out in the VarToy App. More Examples: {File.Rating|numcomp:eq,1,true,false} Returns 'true' when the file has a rating of 1, else 'false'. {File.Width|numcomp:lt,800,Small File,Big File} Compares the value File.Width with 800 using the < (less) operator. If File.Width is less than 800, the variable returns 'Small File' else it returns 'Big File'. {File.MD.iso|numcomp:gte,1000,Noisy,Clean} If the ISO value of the file is >= 1000, the variable returns 'Noisy' else 'Clean'. {File.MD.description|numcomp:gt,30,Long,Short,length} In this example, numcomp calculates the length of the XMP description. If it is longer than 30, it returns 'Long', else 'Short'.
datecomp:Op,Value,TV,FV	This function compares two dates using the specified operator. Depending on whether the result is true or false, the TV or FV values are returned. The supported date and time formats are: "YYYY-MM-DD HH:MM:SS" and "YYYY-MM-DD". You must use the format function to produce one of these date and time formats (use format before you use datecomp!). Supported operators (Op): eq equal  ne not equal lt less lte less than or equal gt greater gte greater than or equal Examples: {File.DateTime|format:YYYY-MM-DD;datecomp:lt,2015-06-01,Old,New} Returns 'Old' if the file date and time are < June 1. 2015. {File.MD.modifydate|format:YYYY-MM-DD;datecomp:gte,2015-01-01,Modified this year,} Returns 'Modified this year' when the file was modified on or after January 1. 2015. {File.DateTime|format:YYYY-MM-DD hh:mm:ss;datecomp:eq, {File.Modified|format:YYYY-MM-DD hh:mm:ss},SAME,DIFFERENT} Returns SAME when the DateTime and Modified timestamps are identical, else DIFFERENT.
duration: CompareDate,unit,singular, plural,zero	This function compares the variable value with CompareDate and returns the difference in units. The variable must be in the format: YYYY-MM-DD HH:MM:SS. Use the format function to produce this format. For CompareDate you can use the special token now to refer to the current date and time, or you use another variable in YYYY-MM-DD HH:MM:SS format or a hard-coded value. Supported Units: years months days hours minutes seconds singular, plurals, zero These optional parameters allow you to control the output of the variable, depending on the value. If you don't want numeric output, but prefer human-readable text, supply these parameters. singular is used when the result of the function is 1. plural is used when the result is 2 or more. zero is used when the result is 0. All parameters can contain embedded variables. The $ token can be used in these expressions. It is replaced with the numerical result. {File.DateTime|format:YYYY:MM:DD hh:mm:ss;duration:now,years,one year, $ years, less than a year} is a typical example for these 3 parameters. Examples: {File.DateTime|format:YYYY:MM:DD hh:mm:ss;duration:now,years} Calculate the duration between the current date and time ('now') and the File.DateTime in years. Returns a numerical value between 0 and n, where n is the number of years. {File.DateTime|format:YYYY:MM:DD hh:mm:ss;duration:now,days} Calculate the duration between the current date and time ('now') and the File.DateTime in days. Returns a numerical value between 0 and n, where n is the number of days. {File.DateTime|format:YYYY:MM:DD hh:mm:ss;duration:now,years,one year, $ years, less than a year} Calculates the duration in years. Depending on the number of years, returns: Number of years Output 1 one year 2-n n years 0 less than a year {File.DateTime|format:YYYY:MM:DD hh:mm:ss;duration:now,years,Ein Jahr, $ Jahre, Weniger als ein Jahr} Same as above, but using German text: Number of years Output 1 Ein Jahr 2-n n Jahre 0 Weniger als ein Jahr This variable uses nested variables to output the number of years, months or days, depending on the duration. If the duration is less than a year, it falls back to output months. If the duration is less than a month, it outputs days. If the duration is less than a day, it outputs the text less than a day. {File.DateTime|format:YYYY:MM:DD hh:mm:ss;duration:now,years,one year,$ years,{File.DateTime|format:YYYY:MM:DD hh:mm:ss;duration:now,months,one month,$ months,{File.DateTime|format:YYYY:MM:DD hh:mm:ss;duration:now,days,one day,$ days,less than a day}}} You can use the math: function with mod to divide months by 12 and get the reminder. {File.DateTime|format:YYYY:MM:DD hh:mm:ss;duration:now,months;math:mod,12} for example returns 2 when months is 38 (3 years and 2 months). You can do the same for days: {File.DateTime|format:YYYY:MM:DD hh:mm:ss;duration:now,days;math:mod,356} divides the total days by 365 to get an approximate result. See also math: timediff.
between:Lower,Upper,TV,FV,Mode	Tests if the numerical value of the variable is >= Lower and <= Upper (less than or qual Lower and greater than or equal Upper). Returns TV if this the condition is met, else FV. When Lower/Upper are numbers with digits (real), you must format them using a decimal point, not a decimal comma. 123.45 is correct, 123,45 is wrong. If you get the Value from another variable, you need to make sure that the result of the variable has the correct format (e.g., by using a cast). The optional parameter Mode has the same meaning as with numcomp above. If set to length, between uses the length of the variable in characters instead of it's value. Examples: {File.MD.rating|between:3,5,Good,Not so good} If the rating of the file is between 3 and 5, the variable returns 'Good' else 'Not so good'. {File.Height|between:0,120,Icon Size} If the height of the file is between 0 and 120, the variable returns 'Icon Size' else an empty string.
strcomp:Value,LV,EV,GV,Mode	This method compares the string value of the variable with the given Value. Depending on the result of the comparison it returns LV (less than), EV (equal) or GV (greater than). The optional parameter mode allows you to control how the comparison is performed. Supported Modes (Mode): normal Case-sensitive string comparison. This is also the default if no mode is given. nocase Non case-sensitive comparison. logical Logical string compare. This mode is able to handle numbers embedded in the string (similar to how Windows Explorer sorts files with names containing numbers). logicalnocase Non case-sensitive logical string comparison. Examples: {File.Label|strcomp:Red,less-string,equal-string,greater-string} Compares the file label with 'Red'. {File.Name|strcomp:Beach,less,equal,greater} Compares the variable value to 'Beach' and returns 'less, 'equal' or 'greater', depending on the outcome. {File.MD.title|strcomp:News,no news,news,whatever} If the title is < News the variable returns 'no news', else 'news' or 'whatever', respectively.
substr:Start,Length	This function allows you to extract a part of the variable value. The first parameter is the 0-based index of the first character to extract; the optional length specifies how many characters to extract. If no length is given, the remainder of the value is returned. Examples: {File.FullName|substr:0,10} Extracts the first 10 characters of the file name.  "A very long file name" => "A very lon" {File.FullName|substr:4} Extracts the file name after the first four characters. "_DSC1234.RAW" => "1234.RAW" {File.MD.XMP::dc\description\Description\0:substr:0,50} Extracts the first 50 characters of the description. Such a statement can be useful for file window tips or slide show overlays when you don't want to fill the screen with too long descriptions.
substrr:Start,Length	This function works like substr, but from the end of the variable value. Using substrr allows you to extract a part of the variable text from the end. Start is the 0-based index of the first character you want to extract from the end. The optional Length specifies how many characters you want to extract. If you want to extract all characters from Start to the beginning of the string don't specify Length. Examples: Variable contains: 1234567890 substrr:0,3 Result: 890 substrr:1,3 Result: 789 substrr:3,2 Result: 67 substrr:3 Result: 1234567 Variable contains: _DSC123456.RAW    substrr: 4 Result: _DSC123456
right:Length	Extracts Length characters from the end of the variable content. Examples: Variable contains:     1234567890 right:3 Result: 890 right:5 Result: 67890
limitstr:MaxLength,Postfix	This function allows you to limit the output length of a string and to optionally add a postfix. If the string exceeds the MaxLength, it is shortened and the optional postfix is appended. Examples: {File.MD.description|limitstr:50} Returns the first 50 characters of the description. {File.MD.description|limitstr:50,...} If the description is longer than 50 characters, the first 50 characters are returned and ... is appended. If the description is shorter than or equal 50 characters, the entire description is returned and the postfix is ignored.
splitlist:Split char,Index	This function splits the variable value at Split char into 1 to many elements and returns the element at the specified Index. Index can be first, last or a number >= 0. Examples: Variable contains: beach;sun;family;vacation splitlist:~;,first beach splitlist:~;,last vacation splitlist:~;,0 beach splitlist:~;,1 sun splitlist:~;,2 family Variable contains: Motive|Vehicle|Car splitlist:|,first Motive splitlist:|,last Car This can be used together with the foreach formatting function to extract selected elements, e.g. of keywords: {File.MD.hierarchicalkeywords|foreach:{value|splitlist:|,last}, } returns the leaf (bottom-most) keyword of all keywords assigned to a file.
splicelist:Split char{,Prefix}{,Postfix}{,trimdupes}	This function splits the variable value at each of the provided split characters and then recombines them using the optional prefix and postfix literals. If trimdupes is provided, duplicates are removed. This variable can be very helpful if you work with hierarchical keywords and you want to flatten or transform them in any way. Examples: Variable contains two hierarchical keywords separated with a ;: location|beach|daytona;motive|portrait splicelist:~;,,{cr}{lf} location|beach|daytona motive|portrait In this example we simply split the keyword list at the ; (note that we have to escape the ; with ~) and then append a carriage-return / linefeed to reach keyword using the special {cr} and {lf} tokens. splicelist:~;|,,{cr}{lf} location beach daytona motive portrait In this example we simply split the keyword list at the ; and the | and then append a carriage-return / linefeed to reach keyword using the special {cr} and {lf} tokens. The first splice extracts the individual hierarchical keywords from the list and the second extracts the individual levels from each hierarchical keyword. splicelist:~;|,-keywords=,{cr}{lf} -keywords=location -keywords=beach -keywords=daytona -keywords=motive -keywords=portrait This example uses a prefix -keywords= and produces a list that can e.g. be used in the IMatch Batch Processor to produce a list of flat keywords to write to the output file. Variable contains: Motive|Vehicle|Car splitstr:|,first Motive splitstr:|,last Car This can be used together with the foreach formatting function to extract selected elements, e.g. of keywords: {File.MD.hierarchicalkeywords|foreach:{value|splitlist:|,last}, } returns the leaf (bottom-most) keyword of all keywords assigned to a file.
filter:Regexp	This function allows you to filter the metadata tag value or Attribute value. The non case-sensitive regular expression is applied to the value. If the value does not match the regular expression, the value is returned as an empty string. If this is a multi-value metadata tag (e.g., keywords) or an Attribute, each value is matched separately against the regular expression. This means you can restrict the output of variables to certain values. Examples: {File.MD.hierarchicalkeywords|filter:^Persons} Returns all keywords for the given file which start with Person. If a file has the keywords: location|beach;family;Person|Susan the variable returns Person|Susan only because this matches the regular expression. {File.MD.hierarchicalkeywords|filter:^Persons;hasvalue:Has Person Keyword} This variable returns the text 'Has Person Keyword' if at least one of the keywords of the file starts with Person. {File.MD.hierarchicalkeywords|filter:^Persons\|;count:true} This tricky variable counts the number of keywords starting with Person| If you assign a Person keyword to any person in an image, you can use this variable to group files by the number of persons shown. {File.AT.Notes.Note|filter:red} This expression returns the value of the Note Attribute in the Notes Attribute set. It filters out all values which don't contain the word red somewhere. You can combine the filter: function with many other functions. Not only count but also is, length or hasvalue. This opens many possibilities for applying this function.
replace:This==That	This function allows you to replace text. You can add multiple replace: arguments if needed. You can use a variable for the That text. Special Tokens: For some situations you may need to replace special non-printable characters like carriage return or line feed. For this purpose, IMatch supports the following tokens: {cr} Carriage Return (13hex) {lf} Carriage Return (10hex) {t} Tabulator (07hex) Examples: {File.FullName|replace:\==\ } Replaces all backslashes in the file name with a backslash and a blank. This enables IMatch to wrap file names into multiple lines, e.g. in a file window tip. {File.Categories|filter:^@Keywords;level:leaf;replace:~;==, } Lists the leaf keywords (lowest level) of a file in a list separated with a comma and a space. This is very handy if you want to output all leaf keywords of a file, e.g. in a File Window Layout or in the Batch Processor or Design & Print. {File.Rating|cast:int; replace:0==Not Rated} After converting the XMP Rating to an int, the function replace is used to output the text "Not Rated" instead of the rating 0. {File.Rating|cast:int; replace:-1==Rejected;replace:0==None} Displays the text "Rejected" instead of the value -1 for files with a reject rating, and 0 with "None". replace:{cr}{lf}==<LineBreak/> Replace carriage return / linefeed pairs with the XAML <LineBreak>. A statement like this allows you to make text wrap inside a XAML render window, e.g. the File Window Tip. replace:{cr}{lf}==<br/> Replace carriage return / linefeed pairs with the HTML <br/> tag. A statement like this allows you to make text wrap inside a HTML document. replace: =={t} Replaces each space with a tabulator character. This can be useful if you use variables in scripts, or for creating text output. replace: ~;==, Replaces ; with , Note the use of the ~ to override the meaning of ; which is normally used as a separator in the replace expression. {File.Categories|filter:@Keywords;replace:~;=={cr}{lf}} Produces a list of all @Keyword categories for a file, with one keyword per row by replacing ; with carriage-return/line-feed.
replacefirst:This==That	Replaces the first occurrence of This with That.
replacelast:This==That	Replaces the last occurrence of This with That.
pereplace:This==That	This function is a variation of the replace function above. The difference is that this replace function does not escape potentially unsafe characters like < or &. You can use this replace variant if you want to add XAML or HTML contents. Pereplace works on already escaped text, after IMatch has replaced unsupported characters like & with their corresponding escape codes, e.g. &amp; for & or lt; for < If you use this replace function, IMatch has no control over the result and invalid XAML code may break the formatting or cause unwanted side effects. Make sure that only valid XMAL code is used as on the replacement side. Special Tokens: For some situations you may need to replace special non-printable characters like carriage return or line feed. For this purpose, IMatch supports the following tokens: {cr} Carriage Return (13hex) {lf} Carriage Return (10hex) {t} Tabulator (07hex) Examples: {File.Categories|pereplace:|==<LineBreak/>} Replaces the | IMatch uses to separate categories in lists with a XAML line break. This allows you to break categories (or other metadata elements with multiple values) in multiple lines, e.g. in the File Window Info tip. pereplace:~;==<br/> Replaces ; with <br/> to make the lines wrap in HTML. pereplace: ~;==<LineBreak/> Replaces ; with <LineBreak/> Note the use of the ~ to override the meaning of ; which is normally used as a separator in the replace expression. {File.MD.hierarchicalkeywords:hasvalue=AAA;pereplace:AAA==<Image Source="c:\images\icon.png"/>} Replaces AAA with the XAML markup to load an image (when the file has keywords). This allows you to produce XAML markup in variables and work around the automatic escaping performed by IMatch. A Note about replacing semicolons ';' and XML/HTML pereplace uses the already escaped text for input. This means that a text initially containing unsafe HTML/XML characters like ' or < will contain the corresponding escape codes before it is handed over to pereplace. If your pereplace code replaces semicolons with something else, this will cause unwanted effects or even invalid XML/HTML code. Example: Your input text is: The name of the town is D'Hanis Since ' has a special meaning in XML/HTML IMatch has to escape it with the corresponding escape sequence: The name of the town is D&apos;Hanis This text is now the input for your pereplace statement. No problem so far. But if you now replace ; with something else, you won't get what you expect: pereplace:~;==<LineBreak/> results in The name of the town is D&apos<LineBreak>Hanis which is not what you want, clearly. If you find yourself in the situation where you a) have to process text for XML/HTML which may contain escape sequences like &apos; or lt; and you want to pereplace ; with something else, you must ensure that the text does not contain escape codes before it reaches pereplace. For the case used here, you should add a replace:'==´ at the very beginning (before pereplace). This will replace all ' in the original text with the very similar ´ character. This prevents IMatch from inserting &apos; into the text and the pereplace does not produce unwanted side effects. Phew! Sorry for this but it had to be said. ;-)
escape:boolean	This function escapes characters unsafe for XML usage. This means characters like < or > in the variable which are not allowed in XML are replaced with their corresponding escape codes. Use this function if you want to write out variables to an XML document or web service. If you use this with false as the value, the method only escapes unsafe characters. If you use true as the value, the method also converts carriage-return and linefeed into the XAML <LineBreak/> token. This allows you to wrap text in features which use XAML for formatting. IMatch already escapes variables in features which use XML or XAML (e.g. file window tip or slide show overlays or text export). Examples: {File.FullName|escape:false} Escapes unsafe characters for XML/HTML. {File.FullName|escape:true} Activates escaping for XML and also replaces linefeeds with the XAML <LineBreak/> token. If you work with HTML, you can use pereplace to replace {cr}{lf} with <br/> to get the same result for HTML code. This function is designed to be used for XAML output like in the Batch Processor or the File Window Info Tip: The File Window Tip automatically escapes the contents of variables in case they contain unsafe characters. This is identical to using escape:false so there is no difference between the first and second line. The third line uses escape:true to convert CRLF (carriage return / line feed pairs) in metadata into the XAML <LineBreak/> tag. If you work with text containing CRLF (newlines), you can use this to make the text wrap inside the File Window Tip or the Batch Processor text fields.
htmlescape:boolean	Same as escape above, but for HTML. This method escapes characters unsafe for HTML usage and (if you set it to true) also converts carriage-return and linefeed into the HTML <br/> token. This allows you to add line breaks to HTML output.
to_upper	Converts the variable content into upper case (abc => ABC). This function has no parameters. Just append it to your variable expression. Examples: e.g.: {File.Name|to_upper} or {File.Name|substr:0,2;to_upper}
to_lower	Converts the variable content into lower case (AbC => abc). This function has no parameters.
capitalize	Converts the first letter into upper case (london => London). This function has no parameters.
reverse	Reverses the variable content (ABC => CBA). This function has no parameters.
trim:type	This method removes (trims) white-space characters from the string. It also removes new line, space, and tab characters. Possible values for type are: left Remove white-space from the left side of the string. trim:left right Remove white-space characters from the right side of the string. trim:right both Remove white-space characters from both sides of the string. trim:both alpha Remove anything that is not a digit (0..9). This can be very useful when cleaning up file names, to extract only the numerical part of something like _DSC_12345. trim:alpha nonalpha Remove anything that is not considered an alphanumeric wide (UNICODE) character in the current locale. Also removes blanks (space, horizontal tabulator). This can be useful if you want to remove all digits and - and blanks from a text. trim:nonalpha nonalphakeepspace Same as nonalpha but keeps spaces and tabulators. trim:nonalphakeepspace Example: {File.Name} returns: "My family_123" {File.Name|alpha} returns: "123" {File.Name|nonalpha} returns: "Myfamily" {File.Name|nonalphakeepspace} returns: "My family"
index:type	For variables with multiple values, e.g. categories, collections, persons, Attributes, keywords. This function allows you to access a specific element in the enumeration, e.g. the first or last keyword. Possible values for type are: first Access the first element. index:first last Access the last element. index:last number A positive number starting with 0. E.g. to access the second element, use index:1
limit:positive number	For variables with multiple values, e.g. categories, Attributes, keywords. This function allows you to limit the output to a specific number of elements. This can be very useful if you have many keywords or categories and you want to ensure that a layout, File Window Info Tip etc. does not exceed a certain size. Examples: {File.Categories|limit:5} Emit maximum 5 categories.
sort:direction	For tag-based variables {File.MD.*} and Attributes {File.AT.*} with multiple values. Uses a text sort before returning the values. The sort is applied before index and limit. Possible values for direction are: asc Ascending sort order desc Descending sort order ascnc Ascending sort order, ignore case. descnc Descending sort order, ignore case.
foreach:expression	This is a very powerful function for variables with repeatable content (keywords, categories, persons, ...). The function iterates over each individual value in the variable and evaluates expression (which can contain variables). Another way to say this: foreach loops over each element in the variable and evaluates expression once for each element. foreach splits values by looking for the list separator character configured for the current user in the Windows control panel. If this character differs from the default separator character IMatch uses for repeatable tags like keywords (configured under Edit > Preferences > Metadata), you may need to put a replace in front of the foreach to e.g. replace ; with , if needed. There are several special variables which are only valid when used together with foreach. We assume that the variable contains the values Peter;Paul;Mary in the following section. Since the variable has 3 values, foreach loops 3 times. {value} The current value. This changes for each loop iteration. For our example, this variable returns Peter for the first iteration, Paul for the second and Mary for the third iteration. {remaining} This number indicates how many iterations are left. In our example it returns 2, 1, 0. This can be used with functions like is to apply formatting or to produce conditional output. {index} The 0-based index for the current iteration. In our example, this variable returns 0, 1 and 2. Examples: {File.MD.hierarchicalkeywords|foreach:[{value}]} Output the keywords of the file, wrapped in [] {File.Persons.Tag|foreach:-{value}} This outputs -Peter-Paul-Mary {File.Persons.Tag|foreach:-{value}⎵({index})⎵} This outputs -Peter⎵(0)⎵-Paul⎵(1)-Mary⎵(2)⎵ {File.Persons.Tag|foreach:{value} ({File.Persons.Age.Years|index:{index}}) } This outputs Peter (30) Paul (35) Mary (28) {File.Persons.Tag|foreach:{value} ({File.Persons.Age.Years|index:{index}}) {remaining|is:0,,{remaining|is:1, and ,+ ;replace:+==,}}}. This outputs Peter (30), Paul (35) and Mary (28). Write all 3 lines shown above in one single line for your expression. We had to wrap it here for layout purposes. {File.MD.hierarchicalkeywords|foreach:{value|substr:{value|findreverse:|;math:add,1}},} This variable returns the leaf keywords. For a file with the keywords: Location|beach|Daytona; Motive|portrait it returns Daytona and portrait.
count:boolean	This function counts the elements in the given variable. Useful for all variables which return multiple values. e.g. categories, keywords, Attributes. The only useful value for the Boolean argument is true. Examples: {File.Categories|count:true} Counts the number of categories and returns that number.
sum:boolean	This function calculates the sum of the elements in the given variable. Used mostly with numerical Attributes of type Real or Int. Examples: {File.AT.Submissions:Revenue|sum:true} Calculates the total revenue by calculating the sum of all Revenue Attributes of a file.
avg:boolean	This function calculates the average of the elements in the given variable. Used mostly with numerical Attributes of type Real or Int. Examples: {File.AT.Submissions:Revenue|avg:true} Calculates the average revenue for a given file by analyzing all Revenue Attributes in the Submissions Attribute Set.
math:Op, Value {,Decimals}	This function performs mathematical operations on the variable. This is designed for variables with numerical values. Or you use one of the other formatting functions first to extract numerical data from the variable content. If the value of the variable cannot be converted into a valid number, it is treated as 0. Note: If this is not the first function used, you must use the cast function to ensure that the value of the variable is numeric, either real or int. And that it does not contain any formatting or grouping characters (e.g. 1,000.45 must be real casted to 1000.45 before using this function.) IMatch formats all numerical values using the system settings for decimal places and thousand groupings and by using cast you can remove this formatting. If you use this as the first function (directly after the |) the math function accesses the original variable value and if is is a real or integer number, it uses the value directly. Else it uses parses the string value. Use math as the first function after the | if possible. This produces the best numerical precision with real values. Use cast:real or cast:int before math if the variable value is not a numeric type. Parameters: Op add Add Value to the numerical content of the variable. sub Subtract Value from the numerical content of the variable. mul Multiply Value with the numerical content of the variable. div Divide the variable by Value. Value must be != 0 or the result will be 0. mod Divide the variable by Value and return the reminder. Value must be != 0 or the result will be 0. Example: 5 mod 3 = 2 timediff This operation calculates the difference in seconds between the variable value and the specified value. The variable value and the supplied literal value or variable must be formatted in ISO8601 format: YYYY-MM-DD HH:MM:SS (2019-12-24 12:00:00). Value The second operand. This can be an integer, a floating point number (real) or a Variable. If this is a floating point number it must use a decimal point, not a comma. For timediff this is a datetime variable or a literal datetime value in the format YYYY-MM-DD HH:MM:SS. Decimals add/sub/mul/div: If the variable produces a floating point number, this optional parameter controls the number of decimal digits. By default, no decimals are emitted. If you work with real/floating point numbers, specify digits as 2 or more. Else the decimals will be trimmed and, for example, a result like 3.1415926 is returned as 3. With 2 digits you'll get 3.14 and with 4 digits you'll get 3.1416. Examples: {File.Height|cast:int;math:add,1000} Adds 1000 to the height of the file. The cast to int removes the thousand grouping (6,400 => 6400). {File.AT.Notes.Value|cast:real;math:add,50,2} Adds 50 to the value of the real Attribute Notes.Value. The cast:real ensures that the number can be processed correctly. The result is rounded to 2 decimal places. {File.AT.Notes.Value|cast:real;math:mul,1.19,2} Adds 19% to the value of the real Attribute Notes.Value. {File.AT.Notes.Value|cast:real;math:mul,{File.AT.Notes.Factor|cast:real},2} Multiplies the value of Notes.Value with the value of Notes.Factor. Note that both operands are casted to real to ensure proper processing. {File.DateTime|format:YYYY-MM-DD hh:mm:ss;math:timediff,2019-03-04 12:00:00} Returns the difference between the content of the variable and the fixed value 2019-03-04 12:00:00 date in seconds (positive or negative). {File.DateTime|format:YYYY-MM-DD hh:mm:ss;math:timediff,{File.MD.XMP::exif\GPSTimeStamp\GPSDateTime|format:YYYY-MM-DD hh:mm:ss}} Compares the file date and time with the GPS timestamp. You can use this trick to find files which need offsets when mapping GPS coordinates to a GPX track log, for example.
cast:Type	This function is used to ensure a specific numerical format. See Casting Variables for more information.
numformat:Type, Width {,Decimals}	This function allows you to cast (convert) the contents of a variable into an int or float numerical data type, and to format the resulting number. This function is useful when you want to produce a specific number of digits from a numerical variable, e.g., in the Renamer or when using one of the export modules. This variable always works with the raw numerical value (if available and this function is the first variable function). This guarantees that you can access the full numeric precision available for a given tag. For example, if you work with floating point variables like EXIF shutter speed, you may get values like 0.00313 (1/320s). If this value is formatted using the standard user-specific numeric prevision (2 digits), it will be formatted as 0,00. If you use a numformat with a width of 1 and a precision of 5, you get five digits after the decimal point: 0.00313. Parameters: Type This is how the input value is interpreted. Supported values: int Integer number, e.g. 1 float Floating point number, e.g. 1.99 hex Hexadecimal number, e.g. 01FC Width The number of digits to use for the output and some optional flags: - Left align the result within the given field width. By default, values are right aligned. + Prefix the output value with a sign (+ or –). 0 Prefix the output with zeros up to the specified width. If this is not given, the output is prefixed with blanks. roman The number is formatted as roman numeral (I,II, III....). hex The number is formatted as a hexadecimal number. Decimals (optional) For float values only. Specifies the number of digits after the decimal point. If you use decimals, the Width parameter must include these decimals as well. If you have an numformat:int,03 you get output values like "007". If you want to output the number as a float with two decimals, you need to increase the width accordingly: numformat:float,06,2 which gives in this output: "007.00". Examples: Assumed text in variable: 7.26 ...|numformat:int,1 7 ...|numformat:int,2  7 ...|numformat:int,02 07 ...|numformat:int,04 0007 ...|numformat:int,+04 +007 ...|numformat:float,02 07 ...|numformat:float,05,2 07.26 ...|numformat:float,05,1 07.3 {File.MD.Composite\Exif-ShutterSpeed\ShutterSpeed\0|numformat:float,1,5} (1/320s) 0.00313 Formatting EXIF sub-seconds: A good usage example for numformat is the EXIF sub-second metadata tag. If you want to use this, e.g., in the Renamer to produce a unique output file name, you usually want to produce output with two digits: {File.MD.Exif::Main\37520\SubSecTime\0|numformat:int,02} When you use the variable with this numformat, you get values like 02, 07, 14, 99. If the sub second value is less than 10, it will be prefixed with a zero. Roman and Hexadecimal Output The special width tokens roman and hex enable you to produce roman numerals or hexadecimal numbers. For a file with a rating of 4 {File.MD.XMP::xmp\Rating\Rating|numformat:int,roman} returns the value IV.

Date and Time Variables

Metadata variables like {File.MD.XMP::photoshop\DateCreated\DateCreated\0} (Note: this is the Standard Tag Date Subject Created) are formatted in the standard ExifTool Format: YYYY:MM:DD hh:mm:ss, e.g. "2012:02:01 12:00:42". While this format is ideal for communication between IMatch, ExifTool and the metadata stored in your files, it is not the best for display or export purposes.

If you display metadata date and time values in file window tip, the slide show or export it to a text file, you usually want to use the default format for your country, or a specific format required by the export. Or you want to extract only the year or calendar week from date. All this can be achieved by using date and time formatting arguments.

Only date and time variables support these formatting arguments.
If you use them with a variable of a different type or the contents of the variable cannot be transformed into a valid date and time value, IMatch returns the unmodified contents of the variable.

Literal Text

You can mix these special tokens with normal text to separate the individual parts of your date or to create custom formats. For example:

{File.DateTime|format:XLD}          => 24.12.2011
{File.DateTime|format:YYYY-MM-DD}   => 2011-12-24
{File.DateTime|format:YYYY/MM/DD}   => 2011/12/24
{File.DateTime|format:hh.mm.ss}     => 12.11.42

The semicolon ; is used to separate multiple formatting arguments and cannot be used as literal text. If your text contains a ; you must escape it with a ~, as in ~;

Examples:

Tip: Accessing the Raw Tag Value

To get the raw metadata value for a date/time tag, you can use the value:rawfrm function, e.g. {File.MD.XMP::photoshop\DateCreated\DateCreated|value:rawfrm}

Most features for which you can use variables also support custom formatting. See the corresponding topic for more information.