140 lines
5.1 KiB
Plaintext
140 lines
5.1 KiB
Plaintext
SECTION I: Architecture, Memory, and Foundations
|
||
|
||
This section establishes the foundations of how AVAP manages service logic and in-memory data manipulation. Unlike conventional interpreted languages, AVAP uses a hybrid evaluation engine that enables the combination of declarative commands with dynamic expressions.
|
||
|
||
1.1 Endpoint Registration (registerEndpoint)
|
||
|
||
The registerEndpoint command is the atomic configuration unit. It acts as the bridge between the network layer (HTTP) and the application code.
|
||
|
||
Interface
|
||
registerEndpoint(path, method, middleware, description, handler, output)
|
||
Parameter Specification
|
||
|
||
path (String):
|
||
Defines the URL route. Supports static routes and is designed for future implementations of route parameters (variable segments).
|
||
|
||
method (String):
|
||
Specifies the allowed HTTP verb (GET, POST, PUT, DELETE). The server will automatically reject any request that does not match this method (Error 405).
|
||
|
||
middleware (List):
|
||
A list of functions executed sequentially before the handler. Ideal for JWT token validation or maintenance checks. If any middleware function fails, execution stops before reaching the main business logic.
|
||
|
||
description (String):
|
||
Metadata for automatic documentation generation (Swagger/OpenAPI). It does not affect execution but is critical in the development lifecycle.
|
||
|
||
handler (Function):
|
||
The logical entry point. This is the name of the main function where the business logic resides.
|
||
|
||
output (Variable):
|
||
Defines the “master” variable that the engine will automatically return at the end of execution, unless additional results are specified via addResult.
|
||
|
||
1.2 The Variable Assignment Engine (Dynamic Assignment)
|
||
|
||
AVAP allows direct assignment syntax using the = symbol, providing flexibility similar to languages such as Python, but under strict contextual control.
|
||
|
||
Internal Mechanics: The eval Process
|
||
|
||
When the interpreter encounters an instruction of the form variable = expression, it triggers a three-step process:
|
||
|
||
Cleanup and Tokenization:
|
||
The engine determines whether the expression contains references to existing variables (using $), method calls, or literals.
|
||
|
||
Expression Evaluation:
|
||
Operations are resolved in real time. This enables:
|
||
|
||
Boolean Logic:
|
||
is_valid = (age > 18 and has_permission == True)
|
||
|
||
Arithmetic:
|
||
tax = subtotal * 0.21
|
||
|
||
String Formatting:
|
||
query = "SELECT * FROM users WHERE id = %s" % retrieved_id
|
||
|
||
Object and Property Resolution:
|
||
Allows deep access to complex structures returned by database connectors or APIs:
|
||
customer_email = user_list[0].profile.email
|
||
|
||
Memory Impact
|
||
|
||
Unlike addVar, dynamic assignment can transform the variable’s type at runtime (Mutable Type System). If a variable originally contained a number and is later assigned a string after evaluation, the engine automatically updates the variable’s metadata.
|
||
|
||
1.3 State Initialization and References (addVar)
|
||
|
||
addVar is the fundamental command for defining the global script state.
|
||
|
||
Interface
|
||
addVar(targetVarName, varValue)
|
||
Advanced Behavior
|
||
|
||
Intelligent Automatic Typing:
|
||
The engine inspects varValue. If it detects a numeric format (even if provided as a string from configuration), it internally converts it to int or float. It supports both commas and periods interchangeably, normalizing the value for mathematical operations.
|
||
|
||
The $ Reference Prefix:
|
||
This is the dereferencing operator.
|
||
|
||
addVar(copy, $original)
|
||
|
||
Instructs the engine not to assign the literal string "$original", but instead to look up the current value of the variable original in the symbol table and copy it.
|
||
|
||
Scope:
|
||
Variables created with addVar in the main body of the script are considered Request Session Variables. This means they persist throughout the lifecycle of that specific API call execution, but remain isolated from other concurrent requests to ensure data safety (thread-safety).
|
||
|
||
Syntax Summary
|
||
Syntax Usage Description
|
||
name = "John" Direct Assignment Creates a simple string.
|
||
total = $price * 1.10 Dynamic Evaluation Uses the value of price in a calculation and stores the result.
|
||
addVar(status, 200) Initialization Explicit method to ensure creation in the global context.
|
||
data = res[0].info Object Access Extracts a specific property from a JSON object or DB result.
|
||
|
||
Examples
|
||
|
||
1. Hello World
|
||
|
||
(State Initialization – Section 1.3)
|
||
|
||
addVar(message, "Hello world from AVAP")
|
||
addResult(message)
|
||
|
||
2. Mathematical Assignment
|
||
|
||
(Dynamic Assignment & Arithmetic Evaluation – Section 1.2)
|
||
|
||
subtotal = 150.50
|
||
tax = subtotal * 0.21
|
||
total = subtotal + tax
|
||
addResult(total)
|
||
|
||
3. Dynamic String Concatenation
|
||
|
||
(Expression Evaluation – String Formatting – Section 1.2)
|
||
|
||
name = "System"
|
||
log = "Event registered by: %s" % name
|
||
addResult(log)
|
||
|
||
4. Value Reference ($)
|
||
|
||
(State Initialization & Dereferencing – Section 1.3)
|
||
|
||
addVar(base, 1000)
|
||
addVar(copy, $base) // copy takes the value 1000, not the string "$base"
|
||
addResult(copy)
|
||
|
||
5. Boolean Assignment
|
||
|
||
(Boolean Expression Evaluation – Section 1.2)
|
||
|
||
level = 5
|
||
is_admin = level >= 10
|
||
addResult(is_admin) // Returns False
|
||
|
||
6. Multiple Response (JSON Construction)
|
||
|
||
(Global State Initialization – Section 1.3)
|
||
|
||
addVar(code, 200)
|
||
addVar(status, "Success")
|
||
addResult(code)
|
||
addResult(status)
|
||
// Result: {"code": 200, "status": "Success"} |