I've used the Evaluator a little and it looks like it can do a lot of useful stuff and I'd like to use it more, but I'm struggling a bit with where and how. The examples page in the manual is still to be completed. I'm particularly confused by where to use {= =} and I've seen ':=' and '=' both used for assigning a variable to a function result. Return seems optional from evaluator functions. Is there a tutorial somewhere (I've been through the manual quite a few times) or perhaps a few examples of where to use {= =} and ':=' vs '='. Many thanks in advance.
{= ... =} is used to insert the output of an Evaluator expression into a normal line, similar to how {filepath} might insert a path into the line.
A line can also start with = to say the entire line is an Evaluator expression, where whatever is returns is run as its own line.
As far as I can think, := isn't used on its own. That's more likely to be @modifier:= for some @modifier, where the : and = are part of separate things.
Optional returns are documented in Evaluator Grammar [Directory Opus Manual]
Oh, so @modifier: and @modifier are the same, eg @filesonly: and @filesonly are equivalent? I've been writing some stuff in Delphi and seeing := made me think it was an assignment.
What would happen without the leading = if the line was an Evaluator expression?
An example of using {= .. =} would be great. So far I haven't been able to make it do anything useful.
Thank you for your reply.
You'd only use @filesonly: if there was something else after it on the same line, giving further parameters to the modifier, which I don't think ever happens with that one.
The expression would be run as if it was a normal command, which would probably result in an error.
There are some in Directory Opus 13 - Detailed release notes: Miscellaneous Commands.
Very useful. Thank you.
I think this was my first ever working Evaluator project. Still proud 
Copy MOVE HERE CREATEFOLDER={=UCase(Left(Trim(file), 1))=} WHENEXISTS=replace
4 Likes
That's a perfect example. Thank you, Alexander.
Here's a bunch of notes and examples I made for myself (so I can't guarantee the accuracy) in regards to using variables and stuff in evaluator and functions that might come in handy.
It's all in standard function syntax (as opposed to javascript/vbscript), so you can copy it all into a user command and run it with logging to see it work.
// Setting evaluator variable values
@evalalways:=value1="Some value1";value2="Another value2";
// Another method to assign evaluator variables within evaluator
@evalalways:{value3="ExampleThree"};
@evalalways:{value4="ExampleFour"};
// See this for info about evaluator in functions: https://docs.dopus.com/doku.php?id=evaluator:applicable_contexts:functions:evaluation_clauses
// Variables set via @eval can only be seen by other modifiers.
// Variables set by @evalalways can also been seen by the main function itself, when it is run. That means they can also be accessed via evaluation insertion code or by generated command lines.
// Using evaluator variables in line
@Output -------- Inline Examples -----------
@output {=value1=} {=value2=}
@Output {=value3=} {=value4=}
@output Explicit return inline {=return value2;=}
// WARNING - Unless it's a return clause, putting a semicolon after the last clause/expression will return a blank value! Because the engine expects a clause after that
@output With Semicolon: {=value1;=}
// Setting regular (non-evaluator) local variable with regular command
@Set testvar=Test Variable
// Setting regular local variable with inline evaluator - Note the semicolon here prevents an error because it makes the evaluator return a blank, otherwise it would return a value to try and run as a command
// So a semicolon can be used to put an inline evaluator without returning anything but still running the evaluator code within
{=$testvar2="Test variable 2";=}
@Output
@Output --------- Local Variables ------------
// Using regular local command in Output (Not sure when colon is necessary)
@Output Test Value is {$testvar}
@Output Test Value again is {=$testvar=}
@Output:With a colon {=$testvar=}
@Output Test Value 2 is {$testvar2}
@Output Test Value 2 is &testvar2&
// Using variables - Example with dialog which returns value assigned to the selection (which we will set with variables)
//@Output Dialog value is {dlgchoose|Example Message to Show|ExampleOption1={$testvar}+ExampleOption2={=value2=}+ExampleOption3=ExampleString}
// Complex button example
//@evalalways:if (IsChecked("Set SORTBY=modified")) { setCommand="SORTBY=name"; labelText="Sorting Modified"; iconName="setDate"; } elseif (IsChecked("Set SORTBY=name")) {setCommand="SORTBY=modified"; labelText="Sorting Name"; iconName="savedlayoutsedit";} else {setCommand="SORTBY=name"; labelText="Sort Name/Modified"; iconName="sort_alpha";}
//@icon: =iconName
//@label: =labelText
//Set {=setCommand=}
@Output
// Multi line evaluator, setting locla variable and returning something different, then using variable later
@Output Random Evaluator Example Return: {=
$test="Blah";
return "Hello";
=}
@Output Variable Value: {$test}
//These would both run the value of the 'value1' variable as a function command. The one using the Output evaluator function is just more roundabout since the variable value is already a string
//=return value1;
//=return Output(value1);
And my notes on using arguments in functions mostly with evaluator:
// PossibleValue1 and PossibleValue2 will be shown if the user puts ARG1= after the command
// Template:
// ARG1/K[PossibleValue1,PossibleValue2], ARG2/O[<Arg2DefaultValue>]
// EXAMPLE USAGE:
// This_Command_Name ARG1=PossibleValue1 ARG2
// For optional arguments (/O), if the first possible value is put in <brackets>, it will be the default value - only if the arg is used but not with a value
// If no default value is assigned to optional arg, if it is used without a value, it will just have the value "1"
// How to reference argument in standard function. Seems to be case insensitive
@Output &ARG1& and &arg2&
// Setting a local variable from an argument
@Set testVar=&ARG1&
@Output Variable From Arg: {$testVar}
// If going to use in an evaluator, might need to put it in quotes to use it as a string. Here, it tries to run it as a function without quotes around it
{=Output("&ARG1&");=}
@Output
@Output ------------------------------------------------
// These would output the Argument value to the script log.
// Note: In the 3rd one it will show an extra line above the output for the evaluator, since the evaluator had the output while running. But it also returns that since it was the last result or whatever
@Output 1: {=Arg("ARG1")=}
@Output 2: {=return Arg("ARG1")=}
@Output 3: {=Output("Arg1 Value is: " + Arg("ARG1"))=}
@Output
// WARNING: Using semicolons might prevent return of the value unless it's an explicit return. I guess because the semicolon moves onto a next non-existant evaluator clause which then returns a blank result
// It still returns if you do an explicit return, I guess because that occurrs before ite gets to the semicolon
// It will still run the evaluator clauses though, notice that the evaluator log prints for the 3rd one, it just doesn't preint to the main script log.
@Output Alt 1: {=Arg("ARG1");=}
@Output Alt 2: {=return Arg("ARG1");=}
@Output Alt 3: {=Output(Arg("ARG1"));=}
@Output
// This would have the effect of running the argument value as a command I think, note the lack of semicolon
//{=Arg("ARG1")=}
2 Likes
Thank you!