assistance-engine/ingestion/docs/19_Control_logic_decision_structures.txt

SECTION III: Control Logic and Decision Structures

This section details how AVAP manages execution flow. The language uses explicitly closed block structures that enable clear sequential reading, simplifying the debugging of complex APIs.

3.1 The Conditional Block (if / else / end)

The if structure in AVAP is a versatile tool that allows atomic comparisons or the evaluation of complex logical expressions processed by the dynamic evaluation engine.

Standard Interface
if(variable_A, value_B, operator)
Available Operators
Operator	Description	Example
=	Strict equality (or numeric equivalence).	if(role, "admin", "=")
!=	Inequality.	if(status, 200, "!=")
> / <	Numeric magnitude comparison.	if(age, 18, ">")
in	Checks whether an element belongs to a list or string.	if(user, blacklist, "in")
Complex Expression Evaluation

AVAP allows omission of comparison parameters to evaluate a complete logical expression directly in the third parameter.

Example:

if(None, None, "age >= 18 and balance > 100")
Block Closure Structure

An if block may include an optional else() block and must always terminate with the end() command.

3.2 Iterations and Loops (startLoop / endLoop)

For collection processing (such as database rows or parameter lists), AVAP implements an index-controlled loop structure.

Interface
startLoop(counter, start, end)
Execution Mechanics

Initialization:
The engine creates the counter variable with the start value.

Increment:
On each iteration, the counter automatically increases by 1.

Exit Condition:
The loop terminates when the counter exceeds the end value.

Practical Example: List Processing
// Retrieve the length of a list captured in Section II
getListLen(received_items, total)

startLoop(i, 0, total)
    current_item = received_items[i]
    // Processing logic for each item...
endLoop()
3.3 Error Handling and Robustness (try / exception)

AVAP is designed for production environments where external failures (database timeouts, third-party API outages) are expected realities. The try block allows capturing such events without stopping the server.

Interface
try ... exception(error_variable) ... end()
Technical Operation

try Block:
The engine attempts to execute the contained instructions. If a critical failure occurs, execution of that block stops immediately.

exception Block:
If an error is detected, control passes to this block. The error_variable is automatically populated with a string describing the failure (simplified stack trace).

end() Block:
Closes the structure and allows the script to continue normal execution after error handling.

Connector Safety Example
try
    // Attempt a query to an external connector (Section V)
    result = db.query("SELECT * FROM payments")
exception(failure_detail)
    // If it fails, log the error and notify
    addVar(_status, 500)
    addVar(message, "Persistence error: %s" % failure_detail)
    addResult(message)
end()
3.4 Early Exit Control (return)

The return() command is a control instruction that immediately terminates execution of the current context (either a function or the main script).

If used inside a function, it returns control (and optionally a value) to the caller.

If used in the main flow, it terminates API execution and triggers automatic delivery of the JSON response constructed up to that point.

Examples

1. Simple Comparison

Code snippet

addParam("lang", l)
if(l, "es", "=")
    addVar(msg, "Hello")
end()
addResult(msg)

2. Standard Else

Code snippet

if(balance, 0, ">")
    allow = True
else()
    allow = False
end()
addResult(allow)

3. Complex Expression (Dynamic Evaluation)

Code snippet

if(None, None, "user_type == 'VIP' or purchases > 100")
    addVar(discount, 0.20)
end()
addResult(discount)

4. Loop from 1 to 10 (ID Generation)

Code snippet

startLoop(i, 1, 10)
    AddvariableToJSON("item_${i}", "generated_value", my_json)
endLoop()
addResult(my_json)

5. HTTP Request Try-Catch

Code snippet

try
    RequestGet("https://api.test.com/data", 0, 0, response)
exception(e)
    addVar(error_trace, "Connection failure: %s" % e)
    addResult(error_trace)
end()

6. Proper Loop Exit (Using Control Variable)

Code snippet

found = False
startLoop(i, 1, 10)
    if(i, 5, "==")
        found = True
        // In AVAP, to exit you can force the index beyond the limit
        i = 11
    end()
endLoop()
addResult(found)

7. 'in' Validation (Membership Check)

Code snippet

addParam("role", r)
if(r, ["admin", "editor", "root"], "in")
    access = True
end()
addResult(access)

8. Loop Over Data Length

Code snippet

getListLen(records, total)
startLoop(idx, 0, total)
    current = records[idx]
    // processing logic
endLoop()

9. Inequality If

Code snippet

if(new_password, old_password, "!=")
    addVar(change, "Password updated")
end()
addResult(change)

10. Critical SQL Error Handling

Code snippet

try
    ormDirect("UPDATE nonexistent_table SET a=1", res)
exception(e)
    addVar(_status, 500)
    addResult("Database error")
end()