Skip to content

FOR eval

Evaluates a short piece of Perl that produces a list, then runs the ops nested underneath it once per element, with the current element in a stash variable you name.

The op is deprecated. It still works and existing rules keep running, but it appears struck through and marked DEPRECATED in the palette, and new rules should not use it. The replacement is to build the list with Server CODE into a stash variable and walk that variable with the FOREACH stash[ variable ] op, or with FOREACH CI when the entries are resources. That splits the code from the loop and keeps the code in the editor that supports both Perl and JavaScript.

Code runs once, before the first pass one element in the Stash Variable run the nested ops next element an empty list, the default, means the body never runs and nothing is logged

Fields

Stash Variable

The name of the variable each element is placed in. The field arrives holding x, which is worth replacing with something you will recognise in the body. Clearing the field does not bring x back: the loop still runs, but each element lands in a stash entry with no name and the body has nothing to read it by.

A bare name, not ${x}. The variable lives for the duration of the loop and reverts to whatever it held before once the last pass ends, so anything you want to keep has to be copied into another variable with PUSH VAR or SET VAR.

Rule quality analysis does not know this variable is created here, so nested ops that read it are reported as using an unknown variable. The report is wrong in this case; see Rule quality analysis.

Code

A Perl expression evaluated in list context. Whatever it produces is the list the loop walks.

It is evaluated once, before the first pass. Adding to the source list from inside the body does not extend the loop.

The default is an empty list, (). Left that way, or replaced with anything else that yields no elements, the body runs zero times, nothing is logged and nothing fails. That silence is the first thing to check when a FOR eval block appears to be skipped.

This field takes code, not a template. ${bar} is not expanded here, it is read as Perl. Reach into the stash directly instead.

The code is pasted into the rule as written. A syntax error is caught when the rule is built rather than when this op is reached, so the whole rule refuses to start and no op in it runs at all. The message you get is the raw Perl complaint with a line number that counts lines of generated code, not lines of your snippet, and it does not name the op. A runtime error stops the job.

The editor is the same in-page code editor used elsewhere, with a plain text box as the fallback on older browsers.

Behaviour worth knowing

Anything that yields a list works: a range, an array from the stash, the values or keys of a hash, the return of a function.

1 .. 5
@{ $$stash{bar_files} || [] }
sort keys %{ $$stash{baz_map} || {} }

A single scalar gives a one-element loop rather than an error, which is easy to do by accident when a stash value turns out not to be a list.

The code runs on the Clarive server as part of the rule, with the full stash in reach. Treat it as privileged: anything the rule can do, this field can do.

Return Key on the Options tab has no effect on this op. A failure inside the body ends the loop as well as the job; use TRY statement with CATCH statement inside the body when one element failing should not stop the rest. Nothing in the job log marks a pass, so add LOG Message in the body when you want to follow progress.

Combining with other ops

Server CODE is the op to move this logic into. Compute the list there, store it under Return Key, and loop over the stored variable.

Inside the body, SET VAR and SET EXPR build values from the element, and PUSH VAR accumulates results that outlive the loop.

FOREACH file/item already knows how to walk a directory, and FOREACH CI already knows how to walk resources. Neither needs code.

Examples

Walk a list another op left in the stash, guarding against it being unset.

Stash Variable   myfile
Code             @{ $$stash{bar_files} || [] }
  -> Ship File Remotely    from ${myfile}

Repeat a block a fixed number of times.

Stash Variable   attempt
Code             1 .. 3
  -> LOG Message    pass ${attempt}