Add query language manual

SanderMertens · May 20, 2024 · b7272e6 · b7272e6
1 parent 972a9ee
commit b7272e6
Show file tree

Hide file tree

Showing 11 changed files with 562 additions and 63 deletions.
diff --git a/docs/FlecsQueryLanguage.md b/docs/FlecsQueryLanguage.md
diff --git a/docs/Manual.md b/docs/Manual.md
@@ -1099,7 +1099,7 @@ ecs_entity_t e = ecs_new_w_pair(world, EcsIsA, Base);
 The combination of instancing, overriding and OVERRIDE is one of the fastest and easiest ways to create an entity with a set of initialized components. The OVERRIDE relationship can also be specified inside type expressions. The following example is equivalent to the previous one:
 
 ```c
-ECS_ENTITY(world, Base, Position, OVERRIDE | Position);
+ECS_ENTITY(world, Base, Position, auto_override | Position);
 
 ecs_set(world, Base, Position, {10, 20});
 

diff --git a/docs/Queries.md b/docs/Queries.md
@@ -1411,10 +1411,10 @@ flecs::query<> f = world.query_builder()
 ```
 
 #### Query DSL
-To create a query with the `AndFrom`, `OrFrom` and `NotFrom` operators in the C API, use `AND`, `OR` and `NOT` in combination with the bitwise OR operator (`|`):
+To create a query with the `AndFrom`, `OrFrom` and `NotFrom` operators in the C API, use `and`, `or` and `not` in combination with the bitwise OR operator (`|`):
 
 ```
-AND | type_list, OR | type_list, NOT | type_list
+and | type_list, or | type_list, not | type_list
 ```
 
 ### Query scopes

diff --git a/docs/Relationships.md b/docs/Relationships.md
@@ -2192,7 +2192,7 @@ inst.Has<TagB>(); // false
 The builtin `Prefab`, `Disabled`, `Identifier` and `ChildOf` tags/relationships are marked as `DontInherit`.
 
 ### AlwaysOverride property
-The `AlwaysOverride` property ensures that a component is always automatically overridden when an inheritance (`IsA`) relationship is added. The behavior of this property is as if `OVERRIDE | Component` is always added together with `Component`.
+The `AlwaysOverride` property ensures that a component is always automatically overridden when an inheritance (`IsA`) relationship is added. The behavior of this property is as if `auto_override | Component` is always added together with `Component`.
 
 <div class="flecs-snippet-tabs">
 <ul>

diff --git a/flecs.c b/flecs.c
@@ -57008,23 +57008,23 @@ const char* flecs_query_parse_term_flags(
     ecs_term_t *term = parser->term;
 
     // AND
-    if      (!ecs_os_strcmp(token_0, "AND"))      oper = EcsAndFrom;
-    else if (!ecs_os_strcmp(token_0, "OR"))       oper = EcsOrFrom;
-    else if (!ecs_os_strcmp(token_0, "NOT"))      oper = EcsNotFrom;
-    else if (!ecs_os_strcmp(token_0, "OVERRIDE")) flag = ECS_AUTO_OVERRIDE;
-    else if (!ecs_os_strcmp(token_0, "TOGGLE"))   flag = ECS_TOGGLE;
+    if      (!ecs_os_strcmp(token_0, "and"))      oper = EcsAndFrom;
+    else if (!ecs_os_strcmp(token_0, "or"))       oper = EcsOrFrom;
+    else if (!ecs_os_strcmp(token_0, "not"))      oper = EcsNotFrom;
+    else if (!ecs_os_strcmp(token_0, "auto_override")) flag = ECS_AUTO_OVERRIDE;
+    else if (!ecs_os_strcmp(token_0, "toggle"))   flag = ECS_TOGGLE;
     else {
         // Position
         term->first.name = token_0;
         return flecs_query_parse_term_id(parser, pos);
     }
 
     if (oper || flag) {
-        // AND |
+        // and |
         //     ^
         Parse_1('|', 
             Parse(
-                // AND | Position
+                // and | Position
                 //     ^
                 case EcsTokTermIdentifier: { 
                     if (oper) {
@@ -57038,7 +57038,7 @@ const char* flecs_query_parse_term_flags(
                     return flecs_query_parse_term_id(parser, pos);
                 }
 
-                // AND | (
+                // and | (
                 //     ^
                 case '(': {
                     return flecs_query_parse_term_pair(parser, pos);

diff --git a/src/addons/script/query_parser.c b/src/addons/script/query_parser.c
@@ -344,23 +344,23 @@ const char* flecs_query_parse_term_flags(
     ecs_term_t *term = parser->term;
 
     // AND
-    if      (!ecs_os_strcmp(token_0, "AND"))      oper = EcsAndFrom;
-    else if (!ecs_os_strcmp(token_0, "OR"))       oper = EcsOrFrom;
-    else if (!ecs_os_strcmp(token_0, "NOT"))      oper = EcsNotFrom;
-    else if (!ecs_os_strcmp(token_0, "OVERRIDE")) flag = ECS_AUTO_OVERRIDE;
-    else if (!ecs_os_strcmp(token_0, "TOGGLE"))   flag = ECS_TOGGLE;
+    if      (!ecs_os_strcmp(token_0, "and"))      oper = EcsAndFrom;
+    else if (!ecs_os_strcmp(token_0, "or"))       oper = EcsOrFrom;
+    else if (!ecs_os_strcmp(token_0, "not"))      oper = EcsNotFrom;
+    else if (!ecs_os_strcmp(token_0, "auto_override")) flag = ECS_AUTO_OVERRIDE;
+    else if (!ecs_os_strcmp(token_0, "toggle"))   flag = ECS_TOGGLE;
     else {
         // Position
         term->first.name = token_0;
         return flecs_query_parse_term_id(parser, pos);
     }
 
     if (oper || flag) {
-        // AND |
+        // and |
         //     ^
         Parse_1('|', 
             Parse(
-                // AND | Position
+                // and | Position
                 //     ^
                 case EcsTokTermIdentifier: { 
                     if (oper) {
@@ -374,7 +374,7 @@ const char* flecs_query_parse_term_flags(
                     return flecs_query_parse_term_id(parser, pos);
                 }
 
-                // AND | (
+                // and | (
                 //     ^
                 case '(': {
                     return flecs_query_parse_term_pair(parser, pos);

diff --git a/test/addons/src/SystemPeriodic.c b/test/addons/src/SystemPeriodic.c
@@ -1888,7 +1888,7 @@ void SystemPeriodic_and_type(void) {
     ECS_COMPONENT(world, Velocity);
     ECS_PREFAB(world, MyType, Position, Velocity);
 
-    ECS_SYSTEM(world, TypeSystem, EcsOnUpdate, AND | MyType);
+    ECS_SYSTEM(world, TypeSystem, EcsOnUpdate, and | MyType);
 
     ecs_new_w(world, Position);
     ecs_new_w(world, Velocity);
@@ -1919,7 +1919,7 @@ void SystemPeriodic_or_type(void) {
     ECS_COMPONENT(world, Velocity);
     ECS_PREFAB(world, MyType, Position, Velocity);
 
-    ECS_SYSTEM(world, TypeSystem, EcsOnUpdate, OR | MyType);
+    ECS_SYSTEM(world, TypeSystem, EcsOnUpdate, or | MyType);
 
     ecs_entity_t e1 = ecs_new_w(world, Position);
     ecs_entity_t e2 = ecs_new_w(world, Velocity);

diff --git a/test/core/src/Prefab.c b/test/core/src/Prefab.c
@@ -143,7 +143,7 @@ void Prefab_new_w_type_w_prefab(void) {
     ecs_add_pair(world, ecs_id(Position), EcsOnInstantiate, EcsInherit);
     ECS_COMPONENT(world, Velocity);
     ecs_add_pair(world, ecs_id(Velocity), EcsOnInstantiate, EcsInherit);
-    ECS_PREFAB(world, Prefab, Position, OVERRIDE | Velocity);
+    ECS_PREFAB(world, Prefab, Position, auto_override | Velocity);
 
     ecs_set(world, Prefab, Position, {10, 20});
 
@@ -460,7 +460,7 @@ void Prefab_new_type_w_1_override(void) {
     ecs_add_pair(world, ecs_id(Position), EcsOnInstantiate, EcsInherit);
     ECS_COMPONENT(world, Velocity);
     ecs_add_pair(world, ecs_id(Velocity), EcsOnInstantiate, EcsInherit);
-    ECS_PREFAB(world, Prefab, Position, Velocity, OVERRIDE | Position);
+    ECS_PREFAB(world, Prefab, Position, Velocity, auto_override | Position);
 
     ecs_set(world, Prefab, Position, {10, 20});
     ecs_set(world, Prefab, Velocity, {30, 40});
@@ -508,7 +508,7 @@ void Prefab_new_type_w_2_overrides(void) {
     ecs_add_pair(world, ecs_id(Position), EcsOnInstantiate, EcsInherit);
     ECS_COMPONENT(world, Velocity);
     ecs_add_pair(world, ecs_id(Velocity), EcsOnInstantiate, EcsInherit);
-    ECS_PREFAB(world, Prefab, Position, Velocity, OVERRIDE | Position, OVERRIDE | Velocity);
+    ECS_PREFAB(world, Prefab, Position, Velocity, auto_override | Position, auto_override | Velocity);
 
     ecs_set(world, Prefab, Position, {10, 20});
     ecs_set(world, Prefab, Velocity, {30, 40});
@@ -794,7 +794,7 @@ void Prefab_new_w_count_w_override(void) {
     ecs_add_pair(world, ecs_id(Position), EcsOnInstantiate, EcsInherit);
     ECS_COMPONENT(world, Velocity);
     ecs_add_pair(world, ecs_id(Velocity), EcsOnInstantiate, EcsInherit);
-    ECS_PREFAB(world, Prefab, Position, Velocity, OVERRIDE | Velocity);
+    ECS_PREFAB(world, Prefab, Position, Velocity, auto_override | Velocity);
 
     ecs_set(world, Prefab, Position, {10, 20});
     ecs_set(world, Prefab, Velocity, {30, 40});
@@ -838,7 +838,7 @@ void Prefab_override_2_components_different_size(void) {
     ecs_add_pair(world, ecs_id(Velocity), EcsOnInstantiate, EcsInherit);
     ECS_COMPONENT(world, Color);
     ecs_add_pair(world, ecs_id(Color), EcsOnInstantiate, EcsInherit);
-    ECS_PREFAB(world, Prefab, Position, Velocity, Color, OVERRIDE | Velocity, OVERRIDE | Color);
+    ECS_PREFAB(world, Prefab, Position, Velocity, Color, auto_override | Velocity, auto_override | Color);
 
     ecs_set(world, Prefab, Position, {10, 20});
     ecs_set(world, Prefab, Velocity, {30, 40});
@@ -1595,7 +1595,7 @@ void Prefab_copy_from_prefab_in_progress(void) {
     ECS_COMPONENT(world, Velocity);
     ecs_add_pair(world, ecs_id(Velocity), EcsOnInstantiate, EcsInherit);
 
-    ECS_PREFAB(world, Prefab, Velocity, OVERRIDE | Velocity);
+    ECS_PREFAB(world, Prefab, Velocity, auto_override | Velocity);
     ecs_set(world, Prefab, Velocity, {1, 2});
 
     ECS_SYSTEM(world, NewInProgress, EcsOnUpdate, Position, Prefab());
@@ -1633,7 +1633,7 @@ void Prefab_copy_from_prefab_first_instance_in_progress(void) {
     ECS_COMPONENT(world, Velocity);
     ecs_add_pair(world, ecs_id(Velocity), EcsOnInstantiate, EcsInherit);
 
-    ECS_PREFAB(world, Prefab, Velocity, OVERRIDE | Velocity);
+    ECS_PREFAB(world, Prefab, Velocity, auto_override | Velocity);
     ecs_set(world, Prefab, Velocity, {1, 2});
 
     ECS_SYSTEM(world, NewInProgress, EcsOnUpdate, Position, Prefab());
@@ -2324,7 +2324,7 @@ void Prefab_override_from_nested(void) {
     ECS_PREFAB(world, BasePrefab, Position);
     ecs_set(world, BasePrefab, Position, {10, 20});
 
-    ECS_PREFAB(world, SubPrefab, (IsA, BasePrefab), Velocity, OVERRIDE | Position, OVERRIDE | Velocity);
+    ECS_PREFAB(world, SubPrefab, (IsA, BasePrefab), Velocity, auto_override | Position, auto_override | Velocity);
     ecs_set(world, SubPrefab, Velocity, {30, 40});
 
     ecs_entity_t e1 = ecs_new_w_pair(world, EcsIsA, SubPrefab);
@@ -2561,7 +2561,7 @@ void Prefab_auto_override(void) {
     ECS_COMPONENT(world, Velocity);
     ecs_add_pair(world, ecs_id(Velocity), EcsOnInstantiate, EcsInherit);
 
-    ECS_PREFAB(world, Prefab, Position, Velocity, OVERRIDE | Position);
+    ECS_PREFAB(world, Prefab, Position, Velocity, auto_override | Position);
 
     ecs_entity_t e = ecs_new_w_pair(world, EcsIsA, Prefab);
     test_assert(ecs_has(world, e, Position));
@@ -2580,7 +2580,7 @@ void Prefab_auto_override_2(void) {
     ECS_COMPONENT(world, Velocity);
     ecs_add_pair(world, ecs_id(Velocity), EcsOnInstantiate, EcsInherit);
 
-    ECS_PREFAB(world, Prefab, Position, Velocity, OVERRIDE | Position, OVERRIDE | Velocity);
+    ECS_PREFAB(world, Prefab, Position, Velocity, auto_override | Position, auto_override | Velocity);
 
     ecs_entity_t e = ecs_new_w_pair(world, EcsIsA, Prefab);
     test_assert(ecs_has(world, e, Position));
@@ -2599,7 +2599,7 @@ void Prefab_auto_override_nested(void) {
     ECS_COMPONENT(world, Velocity);
     ecs_add_pair(world, ecs_id(Velocity), EcsOnInstantiate, EcsInherit);
 
-    ECS_PREFAB(world, Prefab, Position, Velocity, OVERRIDE | Position);
+    ECS_PREFAB(world, Prefab, Position, Velocity, auto_override | Position);
     ECS_PREFAB(world, Prefab_2, (IsA, Prefab));
 
     ecs_entity_t e = ecs_new_w_pair(world, EcsIsA, Prefab_2);

diff --git a/test/core/src/TriggerOnSet.c b/test/core/src/TriggerOnSet.c
@@ -400,7 +400,7 @@ void TriggerOnSet_on_set_after_override_w_new(void) {
     ECS_COMPONENT(world, Position);
     ecs_add_pair(world, ecs_id(Position), EcsOnInstantiate, EcsInherit);
 
-    ECS_PREFAB(world, Prefab, Position, OVERRIDE | Position);
+    ECS_PREFAB(world, Prefab, Position, auto_override | Position);
     ecs_set(world, Prefab, Position, {1, 3});
 
     Probe ctx = {0};
@@ -437,7 +437,7 @@ void TriggerOnSet_on_set_after_override_w_new_w_count(void) {
     ECS_COMPONENT(world, Position);
     ecs_add_pair(world, ecs_id(Position), EcsOnInstantiate, EcsInherit);
 
-    ECS_PREFAB(world, Prefab, Position, OVERRIDE | Position);
+    ECS_PREFAB(world, Prefab, Position, auto_override | Position);
     ecs_set(world, Prefab, Position, {1, 3});
 
     ECS_OBSERVER(world, OnSet, EcsOnSet, Position);
@@ -475,7 +475,7 @@ void TriggerOnSet_on_set_after_override_1_of_2_overridden(void) {
     ECS_COMPONENT(world, Position);
     ecs_add_pair(world, ecs_id(Position), EcsOnInstantiate, EcsInherit);
 
-    ECS_PREFAB(world, Prefab, Position, OVERRIDE | Position);
+    ECS_PREFAB(world, Prefab, Position, auto_override | Position);
     ecs_set(world, Prefab, Position, {1, 3});
 
     ECS_OBSERVER(world, OnSet, EcsOnSet, Position);

diff --git a/test/query/src/Operators.c b/test/query/src/Operators.c
@@ -8214,7 +8214,7 @@ void Operators_and_from_fixed_src(void) {
     ecs_entity_t e = ecs_entity(world, { .name = "e" });
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "AND | Type(e)",
+        .expr = "and | Type(e)",
         .cache_kind = cache_kind
     });
 
@@ -8257,7 +8257,7 @@ void Operators_not_from_fixed_src(void) {
     ecs_entity_t e = ecs_entity(world, { .name = "e" });
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "NOT | Type(e)",
+        .expr = "not | Type(e)",
         .cache_kind = cache_kind
     });
 
@@ -8317,7 +8317,7 @@ void Operators_or_from_fixed_src(void) {
     ecs_entity_t e = ecs_entity(world, { .name = "e" });
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "OR | Type(e)",
+        .expr = "or | Type(e)",
         .cache_kind = cache_kind
     });
 
@@ -8383,7 +8383,7 @@ void Operators_and_from_this(void) {
     ecs_add(world, e2, TagC);
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "AND | Type",
+        .expr = "and | Type",
         .cache_kind = cache_kind
     });
 
@@ -8445,7 +8445,7 @@ void Operators_not_from_this(void) {
     ecs_add(world, e2, TagC);
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "NOT | Type",
+        .expr = "not | Type",
         .cache_kind = cache_kind
     });
 
@@ -8557,7 +8557,7 @@ void Operators_or_from_this(void) {
     ecs_add(world, e2, TagC);
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "OR | Type",
+        .expr = "or | Type",
         .cache_kind = cache_kind
     });
 
@@ -8664,7 +8664,7 @@ void Operators_and_from_this_written(void) {
     ecs_add(world, e2, TagD);
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "TagD, AND | Type",
+        .expr = "TagD, and | Type",
         .cache_kind = cache_kind
     });
 
@@ -8731,7 +8731,7 @@ void Operators_not_from_this_written(void) {
     ecs_add(world, e2, TagD);
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "TagD, NOT | Type",
+        .expr = "TagD, not | Type",
         .cache_kind = cache_kind
     });
 
@@ -8861,7 +8861,7 @@ void Operators_or_from_this_written(void) {
     ecs_add(world, e2, TagD);
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "TagD, OR | Type",
+        .expr = "TagD, or | Type",
         .cache_kind = cache_kind
     });
 
@@ -8966,7 +8966,7 @@ void Operators_and_from_empty(void) {
     ecs_entity(world, { .name = "Type" });
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "AND | Type",
+        .expr = "and | Type",
         .cache_kind = cache_kind
     });
 
@@ -8986,7 +8986,7 @@ void Operators_not_from_empty(void) {
     ecs_entity(world, { .name = "Type" });
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "NOT | Type",
+        .expr = "not | Type",
         .cache_kind = cache_kind
     });
 
@@ -9006,7 +9006,7 @@ void Operators_or_from_empty(void) {
     ecs_entity(world, { .name = "Type" });
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "OR | Type",
+        .expr = "or | Type",
         .cache_kind = cache_kind
     });
 
@@ -9030,7 +9030,7 @@ void Operators_and_from_empty_w_tag(void) {
     ecs_entity_t e = ecs_new_w(world, TagA);
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "AND | Type, TagA",
+        .expr = "and | Type, TagA",
         .cache_kind = cache_kind
     });
 
@@ -9060,7 +9060,7 @@ void Operators_not_from_empty_w_tag(void) {
     ecs_entity_t e = ecs_new_w(world, TagA);
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "NOT | Type, TagA",
+        .expr = "not | Type, TagA",
         .cache_kind = cache_kind
     });
 
@@ -9090,7 +9090,7 @@ void Operators_or_from_empty_w_tag(void) {
     ecs_entity_t e = ecs_new_w(world, TagA);
 
     ecs_query_t *q = ecs_query(world, {
-        .expr = "OR | Type, TagA",
+        .expr = "or | Type, TagA",
         .cache_kind = cache_kind
     });