aether/builtins/
mod.rs

1// src/builtins/mod.rs
2//! Built-in functions standard library
3
4use crate::evaluator::RuntimeError;
5use crate::value::Value;
6use std::collections::HashMap;
7
8// Module declarations
9pub mod array;
10pub mod dict;
11pub mod filesystem;
12pub mod help;
13pub mod io;
14pub mod json;
15pub mod math;
16pub mod network;
17pub mod payroll;
18pub mod precise;
19pub mod report;
20pub mod string;
21pub mod types;
22
23/// Type alias for built-in function implementations
24pub type BuiltInFn = fn(&[Value]) -> Result<Value, RuntimeError>;
25
26/// 函数文档信息
27#[derive(Debug, Clone)]
28pub struct FunctionDoc {
29    /// 函数名称
30    pub name: String,
31    /// 函数描述
32    pub description: String,
33    /// 参数列表（参数名和描述）
34    pub params: Vec<(String, String)>,
35    /// 返回值描述
36    pub returns: String,
37    /// 使用示例
38    pub example: Option<String>,
39}
40
41/// IO 权限配置
42#[derive(Debug, Clone)]
43pub struct IOPermissions {
44    /// 是否允许文件系统操作
45    pub filesystem_enabled: bool,
46    /// 是否允许网络操作
47    pub network_enabled: bool,
48}
49
50impl Default for IOPermissions {
51    fn default() -> Self {
52        Self {
53            filesystem_enabled: false, // 默认禁用，确保安全
54            network_enabled: false,    // 默认禁用，确保安全
55        }
56    }
57}
58
59impl IOPermissions {
60    /// 创建启用所有权限的配置
61    pub fn allow_all() -> Self {
62        Self {
63            filesystem_enabled: true,
64            network_enabled: true,
65        }
66    }
67
68    /// 创建禁用所有权限的配置
69    pub fn deny_all() -> Self {
70        Self::default()
71    }
72}
73
74/// Registry of all built-in functions
75pub struct BuiltInRegistry {
76    functions: HashMap<String, (BuiltInFn, usize)>, // (function, arity)
77    docs: HashMap<String, FunctionDoc>,             // 函数文档
78    #[allow(dead_code)]
79    permissions: IOPermissions,
80}
81
82impl BuiltInRegistry {
83    /// Create a new registry with all built-in functions (默认禁用IO)
84    pub fn new() -> Self {
85        Self::with_permissions(IOPermissions::default())
86    }
87
88    /// Create a new registry with custom permissions
89    pub fn with_permissions(permissions: IOPermissions) -> Self {
90        let mut registry = Self {
91            functions: HashMap::new(),
92            docs: HashMap::new(),
93            permissions: permissions.clone(),
94        };
95
96        // Help function
97        registry.register("HELP", help::help, 0); // Variadic: 0-1 args
98
99        // IO functions
100        registry.register("PRINT", io::print, 1);
101        registry.register("PRINTLN", io::println, 1);
102        registry.register("INPUT", io::input, 1);
103
104        // Array functions
105        registry.register("RANGE", array::range, 1); // Variadic: 1-3 args
106        registry.register("LEN", types::len, 1);
107        registry.register("PUSH", array::push, 2);
108        registry.register("POP", array::pop, 1);
109        registry.register("MAP", array::map, 2);
110        registry.register("FILTER", array::filter, 2);
111        registry.register("REDUCE", array::reduce, 3);
112        registry.register("JOIN", array::join, 2);
113        registry.register("REVERSE", array::reverse, 1);
114        registry.register("SORT", array::sort, 1);
115        registry.register("SUM", array::sum, 1);
116        registry.register("MAX", array::max, 1);
117        registry.register("MIN", array::min, 1);
118
119        // Dict functions
120        registry.register("KEYS", dict::keys, 1);
121        registry.register("VALUES", dict::values, 1);
122        registry.register("HAS", dict::has, 2);
123        registry.register("MERGE", dict::merge, 2);
124
125        // String functions
126        registry.register("SPLIT", string::split, 2);
127        registry.register("UPPER", string::upper, 1);
128        registry.register("LOWER", string::lower, 1);
129        registry.register("TRIM", string::trim, 1);
130        registry.register("CONTAINS", string::contains, 2);
131        registry.register("STARTS_WITH", string::starts_with, 2);
132        registry.register("ENDS_WITH", string::ends_with, 2);
133        registry.register("REPLACE", string::replace, 3);
134        registry.register("REPEAT", string::repeat, 2);
135        registry.register("STRSLICE", string::substr, 3);
136        registry.register("STRLEN", string::strlen, 1);
137        registry.register("INDEXOF", string::index_of, 2);
138        registry.register("CHARAT", string::char_at, 2);
139
140        // Math functions - Basic
141        registry.register("ABS", math::abs, 1);
142        registry.register("FLOOR", math::floor, 1);
143        registry.register("CEIL", math::ceil, 1);
144        registry.register("ROUND", math::round, 1);
145        registry.register("SQRT", math::sqrt, 1);
146        registry.register("POW", math::pow, 2);
147
148        // Math functions - Trigonometry
149        registry.register("SIN", math::sin, 1);
150        registry.register("COS", math::cos, 1);
151        registry.register("TAN", math::tan, 1);
152        registry.register("ASIN", math::asin, 1);
153        registry.register("ACOS", math::acos, 1);
154        registry.register("ATAN", math::atan, 1);
155        registry.register("ATAN2", math::atan2, 2);
156        registry.register("SINH", math::sinh, 1);
157        registry.register("COSH", math::cosh, 1);
158        registry.register("TANH", math::tanh, 1);
159
160        // Math functions - Logarithms & Exponentials
161        registry.register("LOG", math::log, 1);
162        registry.register("LN", math::ln, 1);
163        registry.register("LOG2", math::log2, 1);
164        registry.register("EXP", math::exp, 1);
165        registry.register("EXP2", math::exp2, 1);
166        registry.register("EXPM1", math::expm1, 1);
167        registry.register("LOG1P", math::log1p, 1);
168
169        // Math functions - Special
170        registry.register("FACTORIAL", math::factorial, 1);
171        registry.register("GAMMA", math::gamma, 1);
172        registry.register("ERF", math::erf, 1);
173        registry.register("HYPOT", math::hypot, 2);
174        registry.register("SIGN", math::sign, 1);
175        registry.register("CLAMP", math::clamp, 3);
176
177        // Math functions - Statistics
178        registry.register("MEAN", math::mean, 1);
179        registry.register("MEDIAN", math::median, 1);
180        registry.register("VARIANCE", math::variance, 1);
181        registry.register("STD", math::std, 1);
182        registry.register("QUANTILE", math::quantile, 2);
183
184        // Math functions - Vector Operations
185        registry.register("DOT", math::dot, 2);
186        registry.register("NORM", math::norm, 1);
187        registry.register("CROSS", math::cross, 2);
188        registry.register("DISTANCE", math::distance, 2);
189        registry.register("NORMALIZE", math::normalize, 1);
190
191        // Math functions - Matrix Operations
192        registry.register("MATMUL", math::matmul, 2);
193        registry.register("TRANSPOSE", math::transpose, 1);
194        registry.register("DETERMINANT", math::determinant, 1);
195        registry.register("INVERSE", math::matrix_inverse, 1);
196
197        // Math functions - Statistics & Regression
198        registry.register("LINEAR_REGRESSION", math::linear_regression, 2);
199
200        // Math functions - Probability Distributions
201        registry.register("NORMAL_PDF", math::normal_pdf, 1); // Variadic: 1 or 3
202        registry.register("NORMAL_CDF", math::normal_cdf, 1); // Variadic: 1 or 3
203        registry.register("POISSON_PMF", math::poisson_pmf, 2);
204
205        // Math constants
206        registry.register("PI", math::pi, 0);
207        registry.register("E", math::e, 0);
208        registry.register("TAU", math::tau, 0);
209        registry.register("PHI", math::phi, 0);
210
211        // Precision arithmetic functions
212        registry.register("ROUND_TO", math::round_to, 2);
213        registry.register("ADD_WITH_PRECISION", math::add_with_precision, 3);
214        registry.register("SUB_WITH_PRECISION", math::sub_with_precision, 3);
215        registry.register("MUL_WITH_PRECISION", math::mul_with_precision, 3);
216        registry.register("DIV_WITH_PRECISION", math::div_with_precision, 3);
217        registry.register("SET_PRECISION", math::set_precision, 2);
218
219        // Precise (Fraction) arithmetic functions
220        registry.register("TO_FRACTION", precise::to_fraction, 1);
221        registry.register("TO_FLOAT", precise::to_float, 1);
222        registry.register("SIMPLIFY", precise::simplify, 1);
223        registry.register("FRAC_ADD", precise::frac_add, 2);
224        registry.register("FRAC_SUB", precise::frac_sub, 2);
225        registry.register("FRAC_MUL", precise::frac_mul, 2);
226        registry.register("FRAC_DIV", precise::frac_div, 2);
227        registry.register("NUMERATOR", precise::numerator, 1);
228        registry.register("DENOMINATOR", precise::denominator, 1);
229        registry.register("GCD", precise::gcd, 2);
230        registry.register("LCM", precise::lcm, 2);
231
232        // Type functions
233        registry.register("TYPE", types::type_of, 1);
234        registry.register("TO_STRING", types::to_string, 1);
235        registry.register("TO_NUMBER", types::to_number, 1);
236        registry.register("CLONE", types::clone, 1);
237
238        // JSON functions
239        registry.register("JSON_PARSE", json::json_parse, 1);
240        registry.register("JSON_STRINGIFY", json::json_stringify, 1); // Variadic: 1-2 args
241
242        // Payroll functions - Basic salary calculations (7个)
243        registry.register("CALC_HOURLY_PAY", payroll::basic::calc_hourly_pay, 2);
244        registry.register("CALC_DAILY_PAY", payroll::basic::calc_daily_pay, 2);
245        registry.register(
246            "CALC_MONTHLY_FROM_HOURLY",
247            payroll::basic::calc_monthly_from_hourly,
248            1,
249        );
250        registry.register("CALC_ANNUAL_SALARY", payroll::basic::calc_annual_salary, 1);
251        registry.register("CALC_BASE_SALARY", payroll::basic::calc_base_salary, 1);
252        registry.register("CALC_GROSS_SALARY", payroll::basic::calc_gross_salary, 2);
253        registry.register("CALC_NET_SALARY", payroll::basic::calc_net_salary, 2);
254
255        // Payroll functions - Overtime pay (5个)
256        registry.register("CALC_OVERTIME_PAY", payroll::overtime::calc_overtime_pay, 2);
257        registry.register(
258            "CALC_WEEKDAY_OVERTIME",
259            payroll::overtime::calc_weekday_overtime,
260            2,
261        );
262        registry.register(
263            "CALC_WEEKEND_OVERTIME",
264            payroll::overtime::calc_weekend_overtime,
265            2,
266        );
267        registry.register(
268            "CALC_HOLIDAY_OVERTIME",
269            payroll::overtime::calc_holiday_overtime,
270            2,
271        );
272        registry.register(
273            "CALC_TOTAL_OVERTIME",
274            payroll::overtime::calc_total_overtime,
275            4,
276        );
277
278        // Payroll functions - Personal income tax (6个)
279        registry.register("CALC_PERSONAL_TAX", payroll::tax::calc_personal_tax, 1);
280        registry.register("CALC_TAXABLE_INCOME", payroll::tax::calc_taxable_income, 1);
281        registry.register(
282            "CALC_ANNUAL_BONUS_TAX",
283            payroll::tax::calc_annual_bonus_tax,
284            1,
285        );
286        registry.register(
287            "CALC_EFFECTIVE_TAX_RATE",
288            payroll::tax::calc_effective_tax_rate,
289            2,
290        );
291        registry.register("CALC_GROSS_FROM_NET", payroll::tax::calc_gross_from_net, 1);
292        registry.register("CALC_TAX_REFUND", payroll::tax::calc_tax_refund, 2);
293
294        // Payroll functions - Social insurance (10个)
295        registry.register(
296            "CALC_PENSION_INSURANCE",
297            payroll::insurance::calc_pension_insurance,
298            1,
299        );
300        registry.register(
301            "CALC_MEDICAL_INSURANCE",
302            payroll::insurance::calc_medical_insurance,
303            1,
304        );
305        registry.register(
306            "CALC_UNEMPLOYMENT_INSURANCE",
307            payroll::insurance::calc_unemployment_insurance,
308            1,
309        );
310        registry.register(
311            "CALC_HOUSING_FUND",
312            payroll::insurance::calc_housing_fund,
313            1,
314        );
315        registry.register(
316            "CALC_SOCIAL_INSURANCE",
317            payroll::insurance::calc_social_insurance,
318            1,
319        );
320        registry.register(
321            "ADJUST_SOCIAL_BASE",
322            payroll::insurance::adjust_social_base,
323            3,
324        );
325        registry.register(
326            "CALC_SOCIAL_BASE_LOWER",
327            payroll::insurance::calc_social_base_lower,
328            2,
329        );
330        registry.register(
331            "CALC_SOCIAL_BASE_UPPER",
332            payroll::insurance::calc_social_base_upper,
333            2,
334        );
335        registry.register(
336            "CALC_INJURY_INSURANCE",
337            payroll::insurance::calc_injury_insurance,
338            1,
339        );
340        registry.register(
341            "CALC_MATERNITY_INSURANCE",
342            payroll::insurance::calc_maternity_insurance,
343            1,
344        );
345
346        // Payroll functions - Attendance (7个)
347        registry.register(
348            "CALC_ATTENDANCE_RATE",
349            payroll::attendance::calc_attendance_rate,
350            2,
351        );
352        registry.register(
353            "CALC_LATE_DEDUCTION",
354            payroll::attendance::calc_late_deduction,
355            1,
356        );
357        registry.register(
358            "CALC_EARLY_LEAVE_DEDUCTION",
359            payroll::attendance::calc_early_leave_deduction,
360            1,
361        );
362        registry.register(
363            "CALC_ABSENT_DEDUCTION",
364            payroll::attendance::calc_absent_deduction,
365            2,
366        );
367        registry.register(
368            "CALC_LEAVE_DEDUCTION",
369            payroll::attendance::calc_leave_deduction,
370            2,
371        );
372        registry.register(
373            "CALC_SICK_LEAVE_PAY",
374            payroll::attendance::calc_sick_leave_pay,
375            3,
376        );
377        registry.register(
378            "CALC_UNPAID_LEAVE_DEDUCTION",
379            payroll::attendance::calc_unpaid_leave_deduction,
380            2,
381        );
382
383        // Payroll functions - Bonus (6个)
384        registry.register(
385            "CALC_PERFORMANCE_PAY",
386            payroll::bonus::calc_performance_pay,
387            2,
388        );
389        registry.register("CALC_ANNUAL_BONUS", payroll::bonus::calc_annual_bonus, 1);
390        registry.register(
391            "CALC_ATTENDANCE_BONUS",
392            payroll::bonus::calc_attendance_bonus,
393            2,
394        );
395        registry.register(
396            "CALC_SALES_COMMISSION",
397            payroll::bonus::calc_sales_commission,
398            2,
399        );
400        registry.register("CALC_PROJECT_BONUS", payroll::bonus::calc_project_bonus, 2);
401        registry.register("CALC_13TH_SALARY", payroll::bonus::calc_13th_salary, 2);
402
403        // Payroll functions - Allowance (7个)
404        registry.register(
405            "CALC_MEAL_ALLOWANCE",
406            payroll::allowance::calc_meal_allowance,
407            2,
408        );
409        registry.register(
410            "CALC_TRANSPORT_ALLOWANCE",
411            payroll::allowance::calc_transport_allowance,
412            2,
413        );
414        registry.register(
415            "CALC_COMMUNICATION_ALLOWANCE",
416            payroll::allowance::calc_communication_allowance,
417            2,
418        );
419        registry.register(
420            "CALC_HOUSING_ALLOWANCE",
421            payroll::allowance::calc_housing_allowance,
422            2,
423        );
424        registry.register(
425            "CALC_HIGH_TEMP_ALLOWANCE",
426            payroll::allowance::calc_high_temp_allowance,
427            2,
428        );
429        registry.register(
430            "CALC_NIGHT_SHIFT_ALLOWANCE",
431            payroll::allowance::calc_night_shift_allowance,
432            2,
433        );
434        registry.register(
435            "CALC_POSITION_ALLOWANCE",
436            payroll::allowance::calc_position_allowance,
437            2,
438        );
439
440        // Payroll functions - Conversion (12个)
441        registry.register(
442            "ANNUAL_TO_MONTHLY",
443            payroll::conversion::annual_to_monthly,
444            1,
445        );
446        registry.register(
447            "MONTHLY_TO_ANNUAL",
448            payroll::conversion::monthly_to_annual,
449            1,
450        );
451        registry.register("DAILY_TO_MONTHLY", payroll::conversion::daily_to_monthly, 1);
452        registry.register("MONTHLY_TO_DAILY", payroll::conversion::monthly_to_daily, 1);
453        registry.register(
454            "HOURLY_TO_MONTHLY",
455            payroll::conversion::hourly_to_monthly,
456            1,
457        );
458        registry.register(
459            "MONTHLY_TO_HOURLY",
460            payroll::conversion::monthly_to_hourly,
461            1,
462        );
463        registry.register(
464            "PRORATE_BY_NATURAL_DAYS",
465            payroll::conversion::prorate_by_natural_days,
466            3,
467        );
468        registry.register(
469            "PRORATE_BY_LEGAL_DAYS",
470            payroll::conversion::prorate_by_legal_days,
471            2,
472        );
473        registry.register(
474            "PRORATE_BY_WORKDAYS",
475            payroll::conversion::prorate_by_workdays,
476            3,
477        );
478        registry.register(
479            "CALC_ONBOARDING_SALARY",
480            payroll::conversion::calc_onboarding_salary,
481            4,
482        );
483        registry.register(
484            "CALC_RESIGNATION_SALARY",
485            payroll::conversion::calc_resignation_salary,
486            4,
487        );
488        registry.register("CALC_14TH_SALARY", payroll::conversion::calc_14th_salary, 2);
489
490        // Payroll functions - DateTime (12个)
491        registry.register("CALC_NATURAL_DAYS", payroll::datetime::calc_natural_days, 2);
492        registry.register(
493            "GET_LEGAL_PAY_DAYS",
494            payroll::datetime::get_legal_pay_days,
495            0,
496        );
497        registry.register("CALC_WORKDAYS", payroll::datetime::calc_workdays, 2);
498        registry.register("CALC_WEEKEND_DAYS", payroll::datetime::calc_weekend_days, 2);
499        registry.register("CALC_HOLIDAY_DAYS", payroll::datetime::calc_holiday_days, 1);
500        registry.register("IS_WORKDAY", payroll::datetime::is_workday, 2);
501        registry.register("IS_WEEKEND", payroll::datetime::is_weekend, 1);
502        registry.register("IS_HOLIDAY", payroll::datetime::is_holiday, 2);
503        registry.register("CALC_WORK_HOURS", payroll::datetime::calc_work_hours, 1);
504        registry.register(
505            "CALC_MONTHLY_WORK_HOURS",
506            payroll::datetime::calc_monthly_work_hours,
507            0,
508        );
509        registry.register(
510            "CALC_ANNUAL_WORKDAYS",
511            payroll::datetime::calc_annual_workdays,
512            0,
513        );
514        registry.register(
515            "CALC_ANNUAL_PAY_DAYS",
516            payroll::datetime::calc_annual_pay_days,
517            0,
518        );
519
520        // Payroll functions - Statistics (6个)
521        registry.register(
522            "CALC_SALARY_AVERAGE",
523            payroll::statistics::calc_salary_average,
524            1,
525        );
526        registry.register(
527            "CALC_SALARY_MEDIAN",
528            payroll::statistics::calc_salary_median,
529            1,
530        );
531        registry.register(
532            "CALC_SALARY_RANGE",
533            payroll::statistics::calc_salary_range,
534            1,
535        );
536        registry.register("CALC_PERCENTILE", payroll::statistics::calc_percentile, 2);
537        registry.register(
538            "CALC_SALARY_STD_DEV",
539            payroll::statistics::calc_salary_std_dev,
540            1,
541        );
542        registry.register(
543            "CALC_SALARY_DISTRIBUTION",
544            payroll::statistics::calc_salary_distribution,
545            2,
546        );
547
548        // Filesystem functions (根据权限注册)
549        if permissions.filesystem_enabled {
550            registry.register("READ_FILE", filesystem::read_file, 1);
551            registry.register("WRITE_FILE", filesystem::write_file, 2);
552            registry.register("APPEND_FILE", filesystem::append_file, 2);
553            registry.register("DELETE_FILE", filesystem::delete_file, 1);
554            registry.register("FILE_EXISTS", filesystem::file_exists, 1);
555            registry.register("LIST_DIR", filesystem::list_dir, 1);
556            registry.register("CREATE_DIR", filesystem::create_dir, 1);
557        }
558
559        // Network functions (根据权限注册)
560        if permissions.network_enabled {
561            registry.register("HTTP_GET", network::http_get, 1);
562            registry.register("HTTP_POST", network::http_post, 2); // Variadic: 2-3 args
563            registry.register("HTTP_PUT", network::http_put, 2); // Variadic: 2-3 args
564            registry.register("HTTP_DELETE", network::http_delete, 1);
565        }
566
567        // Report functions - Data formatting (always enabled)
568        registry.register("FORMAT_NUMBER", report::format_number, 1); // Variadic: 1-3 args
569        registry.register("FORMAT_CURRENCY", report::format_currency, 1); // Variadic: 1-3 args
570        registry.register("FORMAT_PERCENT", report::format_percent, 1); // Variadic: 1-2 args
571        registry.register("FORMAT_DATE", report::format_date, 1); // Variadic: 1-2 args
572
573        // Report functions - Excel operations (根据权限注册)
574        if permissions.filesystem_enabled {
575            registry.register("EXCEL_CREATE", report::excel_create, 0);
576            registry.register("EXCEL_WRITE_CELL", report::excel_write_cell, 5);
577            registry.register("EXCEL_WRITE_ROW", report::excel_write_row, 4);
578            registry.register("EXCEL_WRITE_COLUMN", report::excel_write_column, 4);
579            registry.register("EXCEL_WRITE_TABLE", report::excel_write_table, 5);
580            registry.register("EXCEL_SAVE", report::excel_save, 2);
581            registry.register("EXCEL_READ_SHEET", report::excel_read_sheet, 2);
582            registry.register("EXCEL_READ_CELL", report::excel_read_cell, 4);
583            registry.register("EXCEL_READ_RANGE", report::excel_read_range, 6);
584            registry.register("EXCEL_GET_SHEETS", report::excel_get_sheets, 1);
585        }
586
587        registry
588    }
589
590    /// Register a built-in function
591    fn register(&mut self, name: &str, func: BuiltInFn, arity: usize) {
592        self.functions.insert(name.to_string(), (func, arity));
593    }
594
595    /// 注册带文档的函数
596    #[allow(dead_code)]
597    fn register_with_doc(&mut self, name: &str, func: BuiltInFn, arity: usize, doc: FunctionDoc) {
598        self.functions.insert(name.to_string(), (func, arity));
599        self.docs.insert(name.to_string(), doc);
600    }
601
602    /// Get a built-in function by name
603    pub fn get(&self, name: &str) -> Option<(BuiltInFn, usize)> {
604        self.functions.get(name).copied()
605    }
606
607    /// Check if a function exists
608    pub fn has(&self, name: &str) -> bool {
609        self.functions.contains_key(name)
610    }
611
612    /// Get all function names
613    pub fn names(&self) -> Vec<String> {
614        self.functions.keys().cloned().collect()
615    }
616
617    /// 获取函数文档
618    pub fn get_doc(&self, name: &str) -> Option<&FunctionDoc> {
619        self.docs.get(name)
620    }
621
622    /// 获取所有文档
623    pub fn all_docs(&self) -> &HashMap<String, FunctionDoc> {
624        &self.docs
625    }
626}
627
628impl Default for BuiltInRegistry {
629    fn default() -> Self {
630        Self::new()
631    }
632}
aether/builtins/mod.rs

aether/builtins/
mod.rs
