|
| 1 | ++++ |
| 2 | +title = 'CScript DSL' |
| 3 | +date = 2024-01-25T09:38:53+06:00 |
| 4 | +weight = 8 |
| 5 | ++++ |
| 6 | + |
| 7 | +# CScript Domain-Specific Language |
| 8 | +CScript, a domain-specific scripting language, designed specifically for JSchema document. This lightweight, interpreted, and dynamically typed C-style language seamlessly integrates with the foundational principles of the existing JSchema architecture. With the use of dynamic typing and programming constructs similar to both JSON and JavaScript, streamlines the process of writing concise, user-friendly, and flexible logic for constraint or validation functions. |
| 9 | + |
| 10 | +Although CScript is similar to JavaScript in many aspects, the CScript interpreter is designed to quickly halt (fail-fast) and report errors instead of trying to continue with potentially corrupted or unexpected data. This ensures a seamless alignment with the validation requirements of modern web services, significantly enhancing readability and productivity in both documentation and implementation, as well as reducing the potential for bugs. |
| 11 | + |
| 12 | +## Keywords & Reserved Words |
| 13 | +Here is a list of keywords (reserved words) in the CScript language. You cannot use any of the following words as identifiers in your scripts. Some keywords are reserved for future extensions and are not currently in use. |
| 14 | + |
| 15 | +| Description | Current Keyword (Reserved Word) | |
| 16 | +|---------------------------|--------------------------------------------------| |
| 17 | +| Variable Declaration | `var`; (`const`) | |
| 18 | +| Conditional Flow Control | `if`; `else`; (`switch`; `case`; `default`) | |
| 19 | +| Iterative Flow Control | `for`; `foreach`; `while`; (`do`) | |
| 20 | +| Jump Control | `break`; (`continue`) | |
| 21 | +| Membership Management | `in` | |
| 22 | +| Function Declaration | `function`; `constraint`; `future`; `subroutine` | |
| 23 | +| Function Data & Control | `return`; `target`; `caller` | |
| 24 | +| Literals Value | `true`; `false`; `null`; `undefined` | |
| 25 | +| Exception Management | `tryof`; `throw` | |
| 26 | +| Class & Object Management | (`class`; `new`; `super`; `this`) | |
| 27 | +| Script Modularization | (`import`) | |
| 28 | + |
| 29 | +## Data Types |
| 30 | +Data types play a pivotal role in specifying the fundamental structure of values that serve as the foundational components for data manipulation within CScript. In the dynamically typed CScript language, data types are classified into two main categories: primitive immutable value types and composite reference types. |
| 31 | + |
| 32 | +Composite types include `#array` and `#object`, while the remaining types fall under the category of primitive types. Both primitive values and composite references of schema accessible from CScript are readonly and unmodifiable nodes. The following table lists CScript data types: |
| 33 | + |
| 34 | +| SN | Type Name | Example | |
| 35 | +|----|--------------|--------------------------------------------| |
| 36 | +| 1 | `#array` | `[1, 2, 3]`; `["item1", [2.5, 5.8]]`; `[]` | |
| 37 | +| 2 | `#boolean` | `true`; `false` | |
| 38 | +| 3 | `#double` | `10.5`; `20E-5`; `5E+5` | |
| 39 | +| 4 | `#integer` | `10`; `20`; `100`; `500` | |
| 40 | +| 5 | `#null` | `null` | |
| 41 | +| 6 | `#object` | `{ k1: "text", k2: { "k11" : 10 } }`; `{}` | |
| 42 | +| 7 | `#range` | `1..10`; `-10..-5`; `-10..`; `..100` | |
| 43 | +| 8 | `#string` | `"any text"`; `""` | |
| 44 | +| 9 | `#undefined` | `undefined` | |
| 45 | +| 10 | `#void` | Used only for internal purposes | |
| 46 | + |
| 47 | +The `#void` type is reserved for internal operations, including initializing unassigned l-values (variables, properties, and array elements) to the default state, among other cases. To explicitly represent the absence of a value in your script, use the `undefined` or `null` literal. |
| 48 | + |
| 49 | +## Operators & Precedences |
| 50 | +CScript operators are symbols that are used to perform operations on variables and values. The direct operation of any operator that requires a modifiable l-value including `++`, `--` or `=` will raise an exception for the readonly schema nodes. The following table lists the operators according to their precedences from the highest to the lowest: |
| 51 | + |
| 52 | +| SN | Category | Operator | |
| 53 | +|----|-----------------------------|----------------------| |
| 54 | +| 1 | Member Access & Parentheses | `.`; `[]`; `()` | |
| 55 | +| 2 | Unary Minus & Logical Not | `-`; `!` | |
| 56 | +| 3 | Postfix Increment/Decrement | `i++`; `i--` | |
| 57 | +| 4 | Prefix Increment/Decrement | `++i`; `--i` | |
| 58 | +| 5 | Arithmetic Multiplicative | `*`; `/` | |
| 59 | +| 6 | Arithmetic Additive | `+`; `-` | |
| 60 | +| 7 | Sequence Range | `..` | |
| 61 | +| 8 | Relational Comparison | `>`; `<`; `>=`; `<=` | |
| 62 | +| 9 | Equality Comparison | `==`; `!=` | |
| 63 | +| 10 | Logical And (Short-Circuit) | `&&` | |
| 64 | +| 11 | Logical Or (Short-Circuit) | `\|\|` | |
| 65 | +| 12 | Assignment | `=` | |
| 66 | + |
| 67 | +## Function Types |
| 68 | +Function types are essential for specifying the executable units that serve as the building-blocks of validation process within CScript. All function types can also accept variable number of arguments, specified by an ellipsis `...` after the last parameter name which is then bound to an array containing the remaining arguments. |
| 69 | + |
| 70 | +Additionally, all types of functions can be overloaded with varying numbers of fixed parameters, along with one that includes a variable argument parameter. A function name can be overloaded with only one variable argument definition, regardless of the number of required arguments preceding it. Fixed argument functions always take precedence or priority over variable argument functions when arguments match both definitions. Below are the various kinds of functions, each with distinct purposes, used in the CScript language: |
| 71 | + |
| 72 | +### Constraint Function |
| 73 | +The constraint function defines conditions for the target JSON value. They assess whether the target JSON value satisfies the conditions specified by the functions. The function should return true if the conditions are met; otherwise, it should return false. Even if the function exits without returning any value, it is assumed that all conditions are met since any early return from the function usually implies that the conditions are not satisfied. |
| 74 | + |
| 75 | +Within the scope including nested scopes of a constraint function, the `target` keyword refers to the JSON value or node to which the constraint function is applied, and the `caller` keyword refers to the schema node that invokes this constraint function. The subsequent example illustrates various alternative forms of the definition of a constraint function named `example` with the main keyword `constraint`: |
| 76 | +```js |
| 77 | +constraint example(param1, param2, param3) { } |
| 78 | +constraint function example(param1, param2, params...) { } |
| 79 | +``` |
| 80 | + |
| 81 | +### Future Constraint Function |
| 82 | +The future constraint function extends the utility of the constraint function by also considering receiver values. They ensure that the validations are deferred until the receivers of the schema have received their anticipated values, thus evaluating the specified conditions imposed by the functions at a delayed phase. The subsequent example illustrates various alternative forms of the definition of a future constraint function named `example` with the main keyword `future`: |
| 83 | +```js |
| 84 | +future example(param1, param2, param3) { } |
| 85 | +future constraint example(param1, param2, param3) { } |
| 86 | +future function example(param1, param2, param3) { } |
| 87 | +future constraint function example(param1, param2, params...) { } |
| 88 | +``` |
| 89 | + |
| 90 | +### Subroutine Function |
| 91 | +The subroutine function supports the constraint function by promoting code reusability, readability, and modularization. These functions serve as auxiliary units, enhancing the organization and maintainability of validation in CScript, and are not available in the schema context for invocation. Conversely, the constraint function, as well as the future function, are special functions available in the schema context, and are not invocable from the script context without the `target` and `caller` information, thereby preventing any potential overloading conflicts between subroutine and constraint functions. The subsequent example illustrates various alternative forms of the definition of a subroutine function named `example` with the main keyword `subroutine`: |
| 92 | +```js |
| 93 | +subroutine example(param1, param2, param3) { } |
| 94 | +subroutine function example(param1, param2, params...) { } |
| 95 | +``` |
| 96 | + |
| 97 | +The CScript language provides a wide range of functions, data types, and programming constructs that can be used to implement diverse validation logic. This allows for the handling of complex validation requirements, both at the level of individual JSON values and groups of values received across different parts of the JSON document, ultimately ensuring the structural integrity of the entire JSON document. |
0 commit comments