Nexial Filter

Description

In dealing with automation, often one finds the necessity to quality a condition from which a specific action or a set of data element would be considered. The ability to articulate such condition gives our automation more flexibility, more resilience against change (intentional or unintentional) and more accuracy. This is main purpose of Nexial Filter.

Specification

Nexial provides a small and simple set of “directives” to express the condition to activate certain action or to filter data elements. Such condition uses the following format:

[subject] [comparator] [controls]

where,

[subject] represents the data variable or data to consider in order to qualify a condition.

[comparator] represents how [subject] is to be compared with [controls]. Currently supported comparisons are:

comparator	description
=	equals, as in “is this the same as that?”. It supports for both text and numeric values as well.
!=	not equals, as in “is this not the same as that?”. It supports for both text and numeric values as well.
>	greater than, as in “is this value greater than that value?” Only applicable to numbers.
>=	greater or equal to, as in “is this value greater or the same as that value?” Only applicable to numbers.
<	less than, as in “is this value less than that value?” Only applicable to numbers.
<=	less or equal to, as in “is that value less or equal to that value?” Only applicable to numbers.
is	is one of …, as in “is this one of the values in that list?”
is not	is not any of …, as in “is this not found in any of the values in that list?”
in	same as is
not in	same as not in
between	between/within, as in “is this value within the range of these two values?” Only applicable to numbers.
not contain	not containing, as in “does this not containing that?”
contain	containing, as in “does this contains that?”
start with	start with, as in “does this starts with that?”
not start with	not start with, as in “does this not starts with that?”
end with	end with, as in “does this ends with that?”
not end with	not end with, as in “does this not ends with that?”
match	match by regular expression, as in “can this be expressed via that regular expression?”
is empty	does the specified data variable contains empty or no value?
is not empty	does the specified data variable contains some value that is NOT empty?
is defined	is the specified data variable defined (such as in a data sheet)?
is undefined	is the specified data variable NOT defined (in a data sheet, project.properties, etc.)?
has length of	does the specified data variable contains value of __ character. Only applicable to text or numeric value.
has file-size	does the specified data variable represents a readable file with a size of at least __ bytes. Only applicable to fully qualified file path.
is readable-file	does the specified data variable represents a valid, readable file (of any size)?
is not readable-file	does the specified data variable NOT represents a valid, readable file?
is readable-path	does the specified data variable represents a valid, readable directory?
is not readable-path	does the specified data variable NOT represents a valid, readable directory?
is empty-path	does the specified data variable represents a valid, readable, but empty directory? (Meaning no files or subdirectories)
is not empty-path	does the specified data variable NOT represents an empty directory?
contain file	does the specified path directory should contain a file named as file name.
contain file pattern	does the specified path directory should contain one or more files that match file pattern.
has file content	does the specified file should contain content at least once.
has file content pattern	does the specified file should match content pattern at least once.
has lastmod >	file should have a “last modified date” greater than that value.
has lastmod <	file should have a “last modified date” lesser than that value.
has lastmod =	file should have a “last modified date” same as of that value.

[controls] represents the variable or data (could be more than one) to consider in order to qualify a condition. It must be separated by pipe ( | ) like ${fruit} in [apple|banana|chicken|shoes].

Multiple conditions are separated by ampersand ( & ). This represents the “AND” conditions, as in “condition 1 AND condition 2”. For example, ${name} contain "Smith" & ${age} between [18|65] would mean “Smith-somebody who is between 18 and 65 years old”.

(Since Nexial 1.8) There is another unique type of filter - the unary filter. This type of filter only has [subject] and it should always evaluate to either true or false. Consider the following uses of the unary filter in the context of Flow Control:

• SkipIf(true): this means to always skip the corresponding step since true is always true.
• ProceedIf(false): this means to always bypass the corresponding step since false is never true.
• ProceedIf(${condition}): this means to proceed with the corresponding step if ${condition} should evaluate to true.
• EndIf(!${stopNow}): this means to end the current execution if ${stopNow} does not evaluate to true (! means “negate”, hence the opposite of false would be true).
• EndIf(not ${stopNow}): same as above.

Example

condition	description
"A" = "A"	is "A" equals to "A"?
${fruit} in [apple|banana|chicken|shoes]	is ${fruit} one of the items in the list apple, banana, chicken, shoes?
${error message} start with "Error: "	does ${error message} starts with the text "Error: "?
${rate} between [7.005|7.8001]	is ${rate} between 7.005 and 7.8001?
${my_age} between [${min_age}|${max_age}]	is ${my_age} between ${min_age} and ${max_age}?
${my_fruit} match [A-Za-z]{5} & ${my_age} > 25	is ${my_fruit} 5 alphabets and ${my_age} greater than 25?
${my_name} end with nathan	Does ${my_name} end with nathan (such as Jonathan)?
${is_login} is false	is ${is_login} false (i.e. NOT true)?
not_a_var is undefined	is there a variable defined as not_a_var? Note that not_a_var is not specified in the format of ${...} since we are referencing the data variable, not the inferred value.
my_age is defined & ${my_age} is not empty & ${my_age} has length of 2	is there a variable defined as my_age, and such variable is not empty and contains 2 characters? Note that my_age is not specified in the format of ${...} in the context of the is defined condition since we are referencing the data variable, not the inferred value. However, with the is not empty and has length of conditions, we would use the ${...} form.
${os.name} not start with "Windows"	the current operating system is NOT a Windows OS
$(syspath|out|fullpath)/myFile.txt has file-size 1024	does the file "myFile.txt" in the "output" directory has at least 1024 bytes?
$(syspath|out|fullpath)/myFile.txt has file content Nexial_version	does the file "myFile.txt" in the "output" directory contains content Nexial_version?
$(syspath|out|fullpath)/myFile.txt has file content pattern .*Nexial.+	does the file "myFile.txt" in the "output" directory matches content with Nexial.*?
$(syspath|data|fullpath) contain file firstScript.data.xlsx	does the project "data" directory contain file with name firstScript.data.xlsx?
$(syspath|data|fullpath)/myFile.txt has lastmod > 19345738	does the file "myFile.txt" in the "data" directory has modified date grater than 19345738 miliseconds

See Also

This filter specification will be used within the following operations:

• CSV » filter(conditions)
• CSV » removeRows(conditions)
• Flow Controls