pax-runtime-api 0.39.1

Userland constructs used at the runtime API boundary of Pax Engine
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
use crate::{
    math::{Transform2, Vector2},
    Color, ColorChannel, Paint, PaxValue, Rotation,
};
use once_cell::sync::Lazy;
use std::{
    collections::HashMap,
    sync::{Arc, RwLock},
};

use super::{CoercionRules, ToPaxValue};

type FunctionType = Arc<dyn Fn(Vec<PaxValue>) -> Result<PaxValue, String> + Send + Sync>;

static FUNCTIONS: Lazy<Arc<RwLock<HashMap<String, HashMap<String, FunctionType>>>>> =
    Lazy::new(|| Arc::new(RwLock::new(HashMap::new())));

// Dumps registered PAXEL helper functions for diagnostics.
pub fn print_all_functions() {
    let functions = FUNCTIONS.read().unwrap();
    log::warn!("Total scopes: {}", functions.len());
    for (scope, funcs) in functions.iter() {
        log::warn!("Scope: {}", scope);
        for (name, _) in funcs.iter() {
            log::warn!("  |{}|", name);
        }
    }
}

// Registers one PAXEL helper function under a scope/name pair.
pub fn register_function(scope: String, name: String, func: FunctionType) {
    let mut functions = FUNCTIONS.write().unwrap();
    functions
        .entry(scope)
        .or_insert_with(HashMap::new)
        .insert(name, func);
}

// Dispatches a registered PAXEL helper function.
pub fn call_function(scope: String, name: String, args: Vec<PaxValue>) -> Result<PaxValue, String> {
    let functions = FUNCTIONS.read().unwrap();
    let scope_funcs = functions
        .get(&scope)
        .ok_or_else(|| format!("Scope {} not found", scope))?;
    let func = scope_funcs
        .get(&name)
        .ok_or_else(|| format!("Function {} not found in scope {}", name, scope))?;
    func(args)
}

/// Helper function for adding two PaxValues
fn add(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function add".to_string());
    }
    let mut itr = args.into_iter();
    Ok(itr.next().unwrap() + itr.next().unwrap())
}

/// Helper function for subtracting two PaxValues
fn sub_or_neg(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() == 1 {
        Ok(-args.into_iter().next().unwrap())
    } else if args.len() == 2 {
        let mut itr = args.into_iter();
        Ok(itr.next().unwrap() - itr.next().unwrap())
    } else {
        Err("Expected 1 or 2 arguments for function sub_or_neg".to_string())
    }
}

/// Helper function for multiplying two PaxValues
fn mul(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function mul".to_string());
    }
    let mut itr = args.into_iter();
    Ok(itr.next().unwrap() * itr.next().unwrap())
}

/// Helper function for dividing two PaxValues
fn div(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function div".to_string());
    }
    let mut itr = args.into_iter();
    Ok(itr.next().unwrap() / itr.next().unwrap())
}

/// Helper function for exponentiating one PaxValue by another
fn exp(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function exp".to_string());
    }
    let mut itr = args.into_iter();
    Ok(itr.next().unwrap().pow(itr.next().unwrap()))
}

/// Helper function for taking the modulus of one PaxValue by another
fn mod_(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function mod_".to_string());
    }
    let mut itr = args.into_iter();
    Ok(itr.next().unwrap() % itr.next().unwrap())
}

/// Helper function for checking if two PaxValues are equal
fn rel_eq(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function rel_eq".to_string());
    }
    Ok(PaxValue::Bool(args[0] == args[1]))
}

/// Helper function for checking if one PaxValue is greater than another
fn rel_gt(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function rel_gt".to_string());
    }
    Ok(PaxValue::Bool(args[0] > args[1]))
}

/// Helper function for checking if one PaxValue is greater than or equal to another
fn rel_gte(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function rel_gte".to_string());
    }
    Ok(PaxValue::Bool(args[0] >= args[1]))
}

/// Helper function for checking if one PaxValue is less than another
fn rel_lt(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function rel_lt".to_string());
    }
    Ok(PaxValue::Bool(args[0] < args[1]))
}

/// Helper function for checking if one PaxValue is less than or equal to another
fn rel_lte(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function rel_lte".to_string());
    }
    Ok(PaxValue::Bool(args[0] <= args[1]))
}

/// Helper function for checking if two PaxValues are not equal
fn rel_neq(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function rel_neq".to_string());
    }
    Ok(PaxValue::Bool(args[0] != args[1]))
}

/// Helper function for performing a boolean AND operation on two PaxValues
fn bool_and(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function bool_and".to_string());
    }
    let mut itr = args.into_iter();
    Ok(itr.next().unwrap().op_and(itr.next().unwrap()))
}

/// Helper function for performing a boolean OR operation on two PaxValues
fn bool_or(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function bool_or".to_string());
    }
    let mut itr = args.into_iter();
    Ok(itr.next().unwrap().op_or(itr.next().unwrap()))
}

/// Helper function for performing a boolean NOT operation on a PaxValue
fn bool_not(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 1 {
        return Err("Expected 1 argument for function bool_not".to_string());
    }
    Ok(args.into_iter().next().unwrap().op_not())
}

/// Helper function for taking the minimum of two PaxValues
fn min(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function min".to_string());
    }
    let mut itr = args.into_iter();
    Ok(itr.next().unwrap().min(itr.next().unwrap()))
}

/// Helper function for taking the maximum of two PaxValues
fn max(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 2 {
        return Err("Expected 2 arguments for function max".to_string());
    }
    let mut itr = args.into_iter();
    Ok(itr.next().unwrap().max(itr.next().unwrap()))
}

/// Helper function for getting the length of a PaxValue vector
fn len(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 1 {
        return Err("len function takes a single argument".to_string());
    }
    match args.into_iter().next().unwrap() {
        PaxValue::Vec(vec) => Ok(vec.len().to_pax_value()),
        e => Err(format!("can't get length of {e:?}")),
    }
}

/// Helper function for creating an RGB color from three PaxValues representing the red, green, and blue channels
fn rgb(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 3 {
        return Err("Expected 3 arguments for function rgb".to_string());
    }
    let mut itr = args.into_iter();
    let r = ColorChannel::try_coerce(itr.next().unwrap())?;
    let g = ColorChannel::try_coerce(itr.next().unwrap())?;
    let b = ColorChannel::try_coerce(itr.next().unwrap())?;
    Ok(Color::rgb(r, g, b).to_pax_value())
}

/// Helper function for creating an RGBA color from four PaxValues representing the red, green, blue, and alpha channels
fn rgba(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 4 {
        return Err("Expected 4 arguments for function rgba".to_string());
    }
    let mut itr = args.into_iter();
    let r = ColorChannel::try_coerce(itr.next().unwrap())?;
    let g = ColorChannel::try_coerce(itr.next().unwrap())?;
    let b = ColorChannel::try_coerce(itr.next().unwrap())?;
    let a = ColorChannel::try_coerce(itr.next().unwrap())?;
    Ok(Color::rgba(r, g, b, a).to_pax_value())
}

/// Helper function for creating an HSL color from three PaxValues representing the hue, saturation, and lightness channels
fn hsl(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 3 {
        return Err("Expected 3 arguments for function hsl".to_string());
    }
    let mut itr = args.into_iter();
    let h = Rotation::try_coerce(itr.next().unwrap())?;
    let s = ColorChannel::try_coerce(itr.next().unwrap())?;
    let l = ColorChannel::try_coerce(itr.next().unwrap())?;
    Ok(Color::hsl(h, s, l).to_pax_value())
}

/// Helper function for creating an HSLA color from four PaxValues representing the hue, saturation, lightness, and alpha channels
fn hsla(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 4 {
        return Err("Expected 4 arguments for function hsla".to_string());
    }
    let mut itr = args.into_iter();
    let h = Rotation::try_coerce(itr.next().unwrap())?;
    let s = ColorChannel::try_coerce(itr.next().unwrap())?;
    let l = ColorChannel::try_coerce(itr.next().unwrap())?;
    let a = ColorChannel::try_coerce(itr.next().unwrap())?;
    Ok(Color::hsla(h, s, l, a).to_pax_value())
}

/// Helper function for creating a color from a hexadecimal string representation
fn hex(args: Vec<PaxValue>) -> Result<PaxValue, String> {
    if args.len() != 1 {
        return Err("Expected 1 argument for function hex".to_string());
    }
    let hex = String::try_coerce(args.into_iter().next().unwrap())?;
    Ok(Color::from_hex(&hex).to_pax_value())
}

/// Registers helper functions made available to PAXEL scopes.
pub trait HelperFunctions {
    /// Registers all helper functions for this type.
    fn register_all_functions() {}
}

/// Registry bootstrap for built-in PAXEL helper functions.
pub struct Functions;

impl Functions {
    /// Registers built-in math, color, and transform helper functions.
    pub fn register_all_functions() {
        // Math
        register_function("Math".to_string(), "+".to_string(), Arc::new(add));
        register_function("Math".to_string(), "-".to_string(), Arc::new(sub_or_neg));
        register_function("Math".to_string(), "*".to_string(), Arc::new(mul));
        register_function("Math".to_string(), "/".to_string(), Arc::new(div));
        register_function("Math".to_string(), "^".to_string(), Arc::new(exp));
        register_function("Math".to_string(), "%%".to_string(), Arc::new(mod_));
        register_function("Math".to_string(), "==".to_string(), Arc::new(rel_eq));
        register_function("Math".to_string(), ">".to_string(), Arc::new(rel_gt));
        register_function("Math".to_string(), ">=".to_string(), Arc::new(rel_gte));
        register_function("Math".to_string(), "<".to_string(), Arc::new(rel_lt));
        register_function("Math".to_string(), "<=".to_string(), Arc::new(rel_lte));
        register_function("Math".to_string(), "!=".to_string(), Arc::new(rel_neq));
        register_function("Math".to_string(), "&&".to_string(), Arc::new(bool_and));
        register_function("Math".to_string(), "||".to_string(), Arc::new(bool_or));
        register_function("Math".to_string(), "!".to_string(), Arc::new(bool_not));
        register_function("Math".to_string(), "min".to_string(), Arc::new(min));
        register_function("Math".to_string(), "max".to_string(), Arc::new(max));
        register_function("Math".to_string(), "len".to_string(), Arc::new(len));
        // Colors
        register_function("Color".to_string(), "rgb".to_string(), Arc::new(rgb));
        register_function("Color".to_string(), "rgba".to_string(), Arc::new(rgba));
        register_function("Color".to_string(), "hsl".to_string(), Arc::new(hsl));
        register_function("Color".to_string(), "hsla".to_string(), Arc::new(hsla));
        register_function("Color".to_string(), "#".to_string(), Arc::new(hex));
        // Transform2D
        crate::Transform2D::register_all_functions();
    }

    /// Returns true if a helper function exists in the named scope.
    pub fn has_function(scope: &str, name: &str) -> bool {
        let functions = FUNCTIONS.read().unwrap();
        if let Some(scope_funcs) = functions.get(scope) {
            scope_funcs.contains_key(name)
        } else {
            false
        }
    }
}

impl HelperFunctions for crate::Size {}

impl HelperFunctions for crate::Color {}

impl HelperFunctions for crate::Rotation {}

impl HelperFunctions for crate::Duration {}

impl HelperFunctions for String {}

impl HelperFunctions for crate::Numeric {}

impl HelperFunctions for crate::UnitValue {}

impl HelperFunctions for bool {}

impl HelperFunctions for Paint {}
impl HelperFunctions for crate::MeshPoint {}
impl HelperFunctions for crate::MeshGradient {}
impl<A, B> HelperFunctions for (A, B) {}
impl HelperFunctions for crate::Fill {}

impl HelperFunctions for crate::PaxValue {}

impl HelperFunctions for crate::ColorChannel {}

impl HelperFunctions for crate::Opacity {}

impl HelperFunctions for crate::Stroke {}

impl HelperFunctions for crate::PathSmoothing {}

impl HelperFunctions for crate::StrokeCap {}

impl HelperFunctions for crate::StrokeJoin {}

impl HelperFunctions for u8 {}
impl HelperFunctions for u16 {}
impl HelperFunctions for u32 {}
impl HelperFunctions for u64 {}
impl HelperFunctions for u128 {}
impl HelperFunctions for usize {}

impl HelperFunctions for i8 {}
impl HelperFunctions for i16 {}
impl HelperFunctions for i32 {}
impl HelperFunctions for i64 {}
impl HelperFunctions for i128 {}
impl HelperFunctions for isize {}

impl HelperFunctions for f32 {}
impl HelperFunctions for f64 {}
impl<T> HelperFunctions for Vec<T> {}

impl<T: HelperFunctions> HelperFunctions for Option<T> {}

impl HelperFunctions for crate::Transform2D {
    fn register_all_functions() {
        register_function(
            "Transform2D".to_string(),
            "scale".to_string(),
            Arc::new(|args| {
                if args.len() != 2 {
                    return Err("Expected 2 arguments for function scale".to_string());
                }
                let mut itr = args.into_iter();
                let x = crate::Size::try_coerce(itr.next().unwrap())?;
                let y = crate::Size::try_coerce(itr.next().unwrap())?;
                Ok(crate::Transform2D::scale(x, y).to_pax_value())
            }),
        );
        register_function(
            "Transform2D".to_string(),
            "rotate".to_string(),
            Arc::new(|args| {
                if args.len() != 1 {
                    return Err("Expected 1 argument for function rotate".to_string());
                }
                let z = crate::Rotation::try_coerce(args.into_iter().next().unwrap())?;
                Ok(crate::Transform2D::rotate(z).to_pax_value())
            }),
        );
        register_function(
            "Transform2D".to_string(),
            "translate".to_string(),
            Arc::new(|args| {
                if args.len() != 2 {
                    return Err("Expected 2 arguments for function translate".to_string());
                }
                let mut itr = args.into_iter();
                let x = crate::Size::try_coerce(itr.next().unwrap())?;
                let y = crate::Size::try_coerce(itr.next().unwrap())?;
                Ok(crate::Transform2D::translate(x, y).to_pax_value())
            }),
        );
        register_function(
            "Transform2D".to_string(),
            "anchor".to_string(),
            Arc::new(|args| {
                if args.len() != 2 {
                    return Err("Expected 2 arguments for function anchor".to_string());
                }
                let mut itr = args.into_iter();
                let x = crate::Size::try_coerce(itr.next().unwrap())?;
                let y = crate::Size::try_coerce(itr.next().unwrap())?;
                Ok(crate::Transform2D::anchor(x, y).to_pax_value())
            }),
        );
    }
}

impl HelperFunctions for Transform2 {
    fn register_all_functions() {
        register_function(
            "Transform2".to_string(),
            "identity".to_string(),
            Arc::new(|args| {
                if args.len() != 0 {
                    return Err("Expected 0 arguments for function identity".to_string());
                }
                Ok(Transform2::identity().to_pax_value())
            }),
        );
        register_function(
            "Transform2".to_string(),
            "scale".to_string(),
            Arc::new(|args| {
                if args.len() != 1 {
                    return Err("Expected 1 argument for function scale".to_string());
                }
                let s = f64::try_coerce(args.into_iter().next().unwrap())?;
                Ok(Transform2::scale(s).to_pax_value())
            }),
        );

        register_function(
            "Transform2".to_string(),
            "translate".to_string(),
            Arc::new(|args| {
                if args.len() != 1 {
                    return Err("Expected 1 argument for function scale".to_string());
                }
                let s = Vector2::try_coerce(args.into_iter().next().unwrap())?;
                Ok(Transform2::translate(s).to_pax_value())
            }),
        );

        register_function(
            "Transform2".to_string(),
            "rotate".to_string(),
            Arc::new(|args| {
                if args.len() != 1 {
                    return Err("Expected 1 argument for function rotate".to_string());
                }
                let s = f64::try_coerce(args.into_iter().next().unwrap())?;
                Ok(Transform2::rotate(s).to_pax_value())
            }),
        );
        register_function(
            "Transform2".to_string(),
            "skew".to_string(),
            Arc::new(|args| {
                if args.len() != 1 {
                    return Err("Expected 1 argument for function skew".to_string());
                }
                let s = Vector2::try_coerce(args.into_iter().next().unwrap())?;
                Ok(Transform2::skew(s).to_pax_value())
            }),
        );
    }
}