CEL Reference
=============

Collection Expression Language (CEL) is a generalized grammar for selecting 
subsets of objects organized within hierarchies. 

In Katana, CEL statements are most often used specify the scene graph locations
on which an operation or assignment will act. CEL statements can also be used
to define "collections" which may then be referenced in other CEL statements. 

Katana tries to represent the most common CEL operations within the GUI for CEL
parameters or attributes. It also allows direct access to the full capabilities
of the language with its "Custom" CEL statement pane.

Selecting Objects by Name
-------------------------

A path within CEL is called a "Pattern List". Any name within a path may 
contain a wildcard "*" and may be specified as recursive. 

Explicitly select the object at a path::

   /root/world/cam_main

Select all immediate children of ``/root/world`` whose names start with "lgt"::

   /root/world/lgt*

Select all objects recursively beneath ``/root/materials``::

   /root/materials//*

Select all objects named "shape" anywhere within the scene::

   //shape

Combining Sets
--------------

The result of a Pattern List is a set of objects or a "Set". Sets are combined
in CEL with union (+), difference (-) and intersection (^) operations. 

Adjacent sets without any operator are implicity unioned. This statement
selects both of those paths::

   /root/world/lgt_key /root/world/lgt_fill

This statement is equivalent to the last::

   /root/world/lgt_key + /root/world/lgt_fill

Select all of the immediate children of /root/world except for "lgt_rim"::

   /root/world/lgt* - /root/world/lgt_rim

This example demonstrates that set operations are evaluated from left to right. 
This results in only ``/root/world/b``::

   /root/world/a + /root/world/b - /root/world/a

Parentheses may be used to control the order of evaluation. This example 
results in all immediate children of ``/root/world`` whose names begin with 
"cam" or "lgt" but which aren't named "cam_main", "cam_taco" or "lgt_rim"::

   (/root/world/cam* - (/root/world/cam_main /root/world/cam_taco)) + 
   (/root/world/lgt* - /root/world/lgt_rim) 

Select all immediate children of ``/root/world`` whose name contains both "a" 
and  "b" in any order::

   /root/world/*a* ^ /root/world/*b*

Value Expressions
-----------------

The results of any Pattern within a Pattern List or any set may be filtered 
through a "value expression." Value Expressions may query information and 
attributes about each object in order to include or exclude it from the set. 

Selects all immediate children of ``/root/world`` whose "type" attribute has a 
value of "camera"::

   /root/world/*{ attr( "type" ) == "camera" } 

Select all objects recursively beneath ``/root/world`` which have a local 
attribute named "textures.Colmap"::

   /root/world//*{ hasattr("textures.ColMap") }

Select all objects recursively beneath ``/root/materials`` whose names contain
either "cheese" or "taco" and who have or inherit an attribute named 
"material.surfaceParams.Kd" with a value which is greater than 0.5 and less 
than 0.75. This demonstrates that groupings of sets may be filtered in the same
way as individual patterns::

   ( /root/materials*cheese* /root/materials*taco* ){ 
   globalattr("material.surfaceParams.Kd") > 0.5 and 
   globalattr("material.surfaceParams.Kd") < 0.75 } 

Collections
-----------

All CEL statements search within the context of and are defined relative to an
object within the scene. A Collection is a CEL selection (often a CEL statement
itself) stored on the scene graph. It may reference things at or below the
object on which it's defined. In Katana, Collections which live at the root of
the scene are represented as scene graph locations beneath
``/root/collections``. This can be thought of as "global" or "scene-wide" 
Collections. Collections are typically defined with a 
:kat:node:`CollectionCreate` node in Katana. 

A Collection (and its contents) may be referenced by any CEL statement. 

Reference the contents of a global collection named "my_collection". This would
appear in the scene graph as /root/collections/my_collection::

   /$my_collection/*

Collections may also be defined at arbitrary locations of the scene graph. 
Their paths are expressed relative to the object in which their defined. 
For example, in a scene with this topology::

    root
    `-- world
        `-- taco
            |-- a
            |-- b
            `-- c
                `-- d

A CEL statement which defines a Collection at ``/root/world/taco`` that 
selected ``/root/world/taco/a`` and ``/root/world/taco/c/d`` could be expressed
as: ``/a c/d``

Assuming that Collection was named "my_collection", it could be referenced in
an assignment node with ``/root/world/taco/$my_collection/*``.