Predicates

Predicates are the part of your filter that actually checks something about a findable:

# -title is a predicate which checks if movie titles match some regular expression.
flam find movies -title star.wars

# -every-movie is a predicate which checks if every movie the people were in passes some subfilter.
# -release-year is a subfilter, in this case we check if the movie was released not before the year 2000.
flam find cast -every-movie -release-year +2000

There are general predicates which are valid in any filter, and there’s predicates specific to some findable type, which may only be used in filters for object of that type.

Tip

Flam supports implementing custom predicates.

Predicate arguments

Most predicates have arguments. Below is a list of some common arguments predicates may have:

ATTRIBUTE

The name of some attribute:

# Find only movies you've personally rated. my-rating is an ATTRIBUTE.
flam find movies -has my-rating

CMPTO

CmpTo’s express a comparison of some attribute’s values to a constant, using a comparison operator of your choice.

CmpTo’s look like <operator><value>, as in “compare to <value> using <operator>”. The <operator> is optional; every attribute has a default operator. For example:

# '1980' is a CMPTO. It checks for equality by default.
flam find movies -release-year 1980

# Same as above but the operator is explicit. '=1980' is a CMPTO.
flam find movies -release-year =1980

Below are all supported operators:

- : Less or equal

+ : Greater or equal

= : Exactly equal

.- : Strictly less than

.+ : Strictly greater than

~ : Matches regular expression

CTGM (crew type + group mode)

CTGMs are a combination of a crew type and a group mode.

CTGMs look like <crew type>:<group mode>. The <group mode> is optional; every crew type has a default group mode. For example:

# Find movies that Brad Pitt acted in. 'cast' is a CTGM.
flam find movies -any-role cast -name brad.pitt

# Same as above. Castmembers are separate by default.
flam find movies -any-role cast:separate -name brad.pitt

# Find the writer duo of Peter Jackson and Frash Walsh. 'writer:group' is a CTGM.
flam find movies -any-role writer:group [ -name peter.jackson -name fran.walsh ]

SUBFILTER

Some predicates accept an argument which is itself an entire filter. If the subfilter is made up of more than one predicate it must be parenthesized:

# Find movies where every actor has an "e" in their name. '-name e' is a subfilter.
flam find movies -every-role cast -name e

# Find people who were in movies released between 1939 and 1945.
# The subfilter is complex so it must be parenthesized.
flam find people -any-movie [ -release-year +1939 -release-year -1945 ]

LISTDEF

Reference to some other movie list. See Listdefs.

`...` : List arguments

Some predicates are documented like:

-in-list LISTDEF...

The ... means that it accepts a variable number of LISTDEF arguments. If you want to pass more than one, you’ll have to parenthesize it:

# Only one LISTDEF, no need to parenthesize.
flam find movies -in-list cool-movies

# Multiple LISTDEFs, must parenthesize.
flam find movies -in-list [ cool-movies chill-movies ]

List of builtin predicates

Attribute predicates

Every attribute in flam can also be used as a predicate to compare the attribute to a value. They look like -<attribute> CMPTO:

# Check if the 'title' attribute matches a regular expression.
flam find movies -title lord.of.the.rings

# Check if the 'height' attribute is at least 180cm.
flam find people -height +180

Note

If an attribute returns a list, this will actually check if any element in the list matches this value.

General predicates

These predicates don’t have a specific findable type. They may be used in any filter of any type.

-true: Always true.
-false: Always false.
-every ATTRIBUTE CMPTO: For list attributes, check if every list element compares true.
-has ATTRIBUTE: True if we have some value populated for this attribute (i.e. not none or empty).
-index ATTRIBUTE INDEX CMPTO: True if the attribute compares true at the given index.
-has-index ATTRIBUTE INDEX: True if the attribute has a not-None value at this index.
-superset ATTRIBUTE CMPTO…: True if every list element in the attribute matches at least one of CMPTOs.
-subset ATTRIBUTE CMPTO…: True if every CMPTO matches at least one list element in the attribute.
-sameset ATTRIBUTE CMPTO…: True if every CMPTO matches at least one list element in the attribute and every list element in the attribute matches at least one CMPTO.
-in-list LISTDEF…: True if the findable is also in the list defined by LISTDEFs.

Movie predicates

-any-role CTGM… ROLES_SUBFILTER: Scan the movie’s crew according to CTGMs for a group which passes the filter ROLES_SUBFILTER.
-every-role CTGM… ROLES_SUBFILTER: Scan the movie’s crew according to CTGMs to see if every group passes the filter ROLES_SUBFILTER.

People predicates

-any-movie MOVIES_SUBFILTER: Scan the people’s associated movies for one which passes the filter MOVIES_SUBFILTER.
-every-movie MOVIES_SUBFILTER: Scan the people’s associated movies to see if they all pass the filter MOVIES_SUBFILTER.
-as CREW_TYPE PEOPLE_SUBFILTER: Check if the people pass the filter PEOPLE_SUBFILTER when they are another crew type.
-any-person PEOPLE_SUBFILTER: Separate the people if they are grouped and check if any of the split people pass the filter PEOPLE_SUBFILTER.
-every-person PEOPLE_SUBFILTER: Separate the people if they are grouped and check if every split person passes the filter PEOPLE_SUBFILTER.

Role predicates

There are currently no role-specific builtin predicates, but all movie and people predicates are also valid role predicates!