Table of Contents

Text expressions

Back to the function reference.

Choosing a function

  • left and right return the whole value when the requested count exceeds its length.
  • If a delimiter is absent, before returns the original text and after returns empty text.
  • regex extracts the first match or a named/numbered capture. No match returns empty text; it does not replace matches.
  • Regex matching is case-sensitive unless you supply an option such as (?i). Invalid patterns and match timeouts leave the expression unresolved.
  • Arithmetic accepts invariant numeric values. Division by zero leaves the expression unresolved.

Aliases: increment = inc, decrement = dec, subtract = sub, multiply = mul, and divide = div.

Trim and extract text

${trim("  Part A  ")}
${substring("ABC12345", 3)}
${substring("ABC12345", 3, 2)}

Results: Part A, 12345, and 12.

substring starts counting at zero. A start at or beyond the end returns empty text. A length longer than the remaining text returns the remainder; zero length returns empty text. Negative or noninteger arguments leave the expression unchanged.

Regex replacement

For a complete command that extracts a document ID and works in the visual editor, see expressions containing quotes. Enter expressions normally in visual parameter fields; let the editor add command-level escaping when saving.

regexReplace takes exactly three arguments and replaces all matches:

${regexReplace("ABC-123", "([A-Z]+)-([0-9]+)", "$2-$1")}

Result: 123-ABC. Use $1, $2, etc. for numbered captures, ${name} for a named capture, $& for the complete match, and $$ for a literal dollar sign. These follow .NET replacement syntax.

${regexReplace("ABC-123", "(?<prefix>[A-Z]+)-(?<number>[0-9]+)", "${number}-${prefix}")}
${regexReplace("A12 B34", "[0-9]+", "#")}
${regexReplace("Part PART", "(?i)part", "Item")}

Results: 123-ABC, A# B#, and Item Item. Matching is case-sensitive by default. No match returns the original text. An empty replacement deletes matches; an empty pattern inserts the replacement at every character boundary. Invalid patterns, incorrect argument counts, or a one-second regex match timeout leave the expression unresolved instead of returning a partial replacement.

In quoted expression arguments, escape backslashes ("\\d+" for the regex \d+). Apply an additional escaping layer when embedding the expression inside a quoted command or JSON value. For example:

setglobal -name Result -value "${regexReplace(\"ABC-123\", \"([A-Z]+)-([0-9]+)\", \"$2-$1\")}"

Nested expressions and numbers

String functions can be nested when the nested function also uses ${...}:

${left(${replace($value, " ", "_")}, 10)}

For example, if $value is ABC 123 DRAFT, the expression above evaluates to ABC_123_DR.

Arithmetic functions use invariant number parsing. Integer results preserve leading zero padding from the first argument, so ${inc("032")} evaluates to 033. They can also use numeric placeholders, so ${add($id, 5)} adds 5 to the selected file or folder ID.

You can combine regex with arithmetic functions when a value contains counters inside a larger string. For example, if $value is vA4-32(74), this expression increments both counters while preserving the prefix:

${regex($value, "^([^-]+)-(\d+)\((\d+)\)$", 1)}-${inc(${regex($value, "^([^-]+)-(\d+)\((\d+)\)$", 2)})}(${inc(${regex($value, "^([^-]+)-(\d+)\((\d+)\)$", 3)})})

The result is:

vA4-33(75)

Example Usage

Here is an example of how to use placeholders in a command:

Renaming a File

rename -filePath 1.sldprt -value "$fileNameWithoutExtension_$yyyy$mm$dd$extension"

Updating a Variable From Its Current Value

setvar -filePath file1.sldprt -variableName Description -value "${replace($value, \"DRAFT\", \"RELEASED\")}"

Renaming With Nested String Functions

rename -filePath "Part 123 Draft.sldprt" -value "${left(${replace($fileNameWithoutExtension, \" \", \"_\")}, 12)}$extension"

Renaming Everything Before a Separator

rename -filePath "ABC-123.sldprt" -value "${before($fileNameWithoutExtension, \"-\")}$extension"

Renaming With a Regular Expression

rename -filePath "ABC-123.sldprt" -value "${regex($fileNameWithoutExtension, \"^([^-]+)-\", 1)}$extension"
Edit this page