From 0378f2397016562aca25744a32d9d50c6eda51e5 Mon Sep 17 00:00:00 2001 From: Andre Meyering Date: Wed, 29 Jan 2025 16:06:00 +0100 Subject: [PATCH 1/4] fix(CDL): Fix typos; add literal example for backticks; rephrase note --- cds/cdl.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/cds/cdl.md b/cds/cdl.md index 611806138..dd739b2ee 100644 --- a/cds/cdl.md +++ b/cds/cdl.md @@ -8,9 +8,6 @@ uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/ --- - - - # Conceptual Definition Language (CDL) @@ -61,7 +58,7 @@ entity Authors : entity { In the example above `entity` shows up as a keyword, as well as an identifier of an aspect declaration and references to that. -As indicated by the syntax coloring, `Association` is not a keyword, but a type name identifier, similar to `String`, `Integer`, `Books` and `Authors`. +As indicated by the syntax coloring, `Association`, even though a keyword, can be seen as a type name, similar to `String`, `Books`, or `Authors`. This highlights the fact that `author` is an association type. ::: @@ -76,7 +73,7 @@ type ![Delimited Identifier] : String; ``` ::: warning Avoid using delimited identifiers -Delimited identifiers in general, but in articular non-ansi characters, or keywords as identifiers should be avoided as much as possible, for reasons of interoperability. +Delimited identifiers in general, but in particular non-ASCII characters, or keywords as identifiers should be avoided as much as possible, for reasons of interoperability. ::: @@ -98,6 +95,7 @@ The following literals can be used in CDL (mostly as in JavaScript, Java, and SQ true , false , null // as in all common languages 11 , 2.4 , 1e3, 1.23e-11 // for numbers 'A string''s literal' // for strings +`A string\n paragraph` // for strings with escape sequences { foo:'boo', bar:'car' } // for records [ 1, 'two', {three:4} ] // for arrays ``` @@ -479,7 +477,7 @@ entity Bar { An element definition can be prefixed with modifier keyword `virtual`. This keyword indicates that this element isn't added to persistent artifacts, that is, tables or views in SQL databases. Virtual elements are part of OData metadata. -By default virtual elements are annotated with `@Core.Computed: true`, not writable for the client and will be [silently ignored](../guides/providing-services#readonly). This means also, that they are not accessible in custom event handlers. If you want to make virtual elements writable for the client, you explicitly need to annotate these elements with `@Core.Computed: false`. Still those elements are not persisted and therefore, for example, not sortable or filterable. +By default, virtual elements are annotated with `@Core.Computed: true`, not writable for the client and will be [silently ignored](../guides/providing-services#readonly). This means also, that they are not accessible in custom event handlers. If you want to make virtual elements writable for the client, you explicitly need to annotate these elements with `@Core.Computed: false`. Still those elements are not persisted and therefore, for example, not sortable or filterable. ```cds entity Employees { @@ -729,7 +727,7 @@ Use the `as projection on` variant instead of `as select from` to indicate that entity Foo as projection on Bar {...} ``` -Currently the restrictions of `as projection on` compared to `as select from` are: +Currently, the restrictions of `as projection on` compared to `as select from` are: - no explicit, manual `JOINs` - no explicit, manual `UNIONs` @@ -956,7 +954,7 @@ Essentially, Compositions are the same as _[associations](#associations)_, just ::: warning Limitations of Compositions of one Using of compositions of one for entities is discouraged. There is often no added value of using them as the information can be placed in the root entity. Compositions of one have limitations as follow: - Very limited Draft support. Fiori elements does not support compositions of one unless you take care of their creation in a custom handler. -- No extensive support for modifications over paths if compostions of one are involved. You must fill in foreign keys manually in a custom handler. +- No extensive support for modifications over paths if compositions of one are involved. You must fill in foreign keys manually in a custom handler. ::: ### Managed Compositions of Aspects {#managed-compositions} @@ -1448,7 +1446,7 @@ and a value written as expression `@aValueExpr: ( 11 )`, respectively. #### Propagation [Annotations are propagated](#annotation-propagation) in views/projections, via includes, and along type references. -If the annotation value is an expression, it sometimes is necessary to adapt references inside the expression +If the annotation value is an expression, it is sometimes necessary to adapt references inside the expression during propagation, for example, when a referenced element is renamed in a projection. The compiler automatically takes care of the necessary rewriting. When a reference in an annotation expression is rewritten, the `=` property is set to `true`. From 4dbbe416fd994f485df6998adccb0f52e52fcae4 Mon Sep 17 00:00:00 2001 From: Andre Meyering Date: Fri, 31 Jan 2025 11:36:43 +0100 Subject: [PATCH 2/4] mention CSN --- cds/cdl.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cds/cdl.md b/cds/cdl.md index dd739b2ee..c1ce0246a 100644 --- a/cds/cdl.md +++ b/cds/cdl.md @@ -58,8 +58,8 @@ entity Authors : entity { In the example above `entity` shows up as a keyword, as well as an identifier of an aspect declaration and references to that. -As indicated by the syntax coloring, `Association`, even though a keyword, can be seen as a type name, similar to `String`, `Books`, or `Authors`. This highlights the fact that `author` is an association type. - +As indicated by the syntax coloring, `Association`, even though a keyword, can be seen as a type name, similar to `String`. +This highlights the fact that element `author` is an association, which is characterized by a type `cds.Association` in CSN. ::: Keywords are *case-insensitive*, but are most commonly used in lowercase notation. From 0afadba72678005c5e483365b0e99e818a39369b Mon Sep 17 00:00:00 2001 From: Andre Meyering Date: Mon, 3 Feb 2025 12:33:02 +0100 Subject: [PATCH 3/4] remove box --- cds/cdl.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/cds/cdl.md b/cds/cdl.md index c1ce0246a..fb3234578 100644 --- a/cds/cdl.md +++ b/cds/cdl.md @@ -54,14 +54,6 @@ entity Authors : entity { } ``` -::: details Noteworthy... - -In the example above `entity` shows up as a keyword, as well as an identifier of an aspect declaration and references to that. - -As indicated by the syntax coloring, `Association`, even though a keyword, can be seen as a type name, similar to `String`. -This highlights the fact that element `author` is an association, which is characterized by a type `cds.Association` in CSN. -::: - Keywords are *case-insensitive*, but are most commonly used in lowercase notation. Identifiers are *case-significant*, that is, `Foo` and `foo` would identify different things. From 5bafd9ee930e969f6b679d56299c147e60e3fb9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Jeglinsky?= Date: Tue, 4 Feb 2025 07:22:29 +0100 Subject: [PATCH 4/4] Update cds/cdl.md --- cds/cdl.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/cds/cdl.md b/cds/cdl.md index 1692c9770..d107906b6 100644 --- a/cds/cdl.md +++ b/cds/cdl.md @@ -54,6 +54,11 @@ entity Authors : entity { } ``` +::: details Noteworthy... + +In the example above `entity` shows up as a keyword, as well as an identifier of an aspect declaration and references to that. + +::: Keywords are *case-insensitive*, but are most commonly used in lowercase notation. Identifiers are *case-significant*, that is, `Foo` and `foo` would identify different things.