{"id":31559544,"url":"https://github.com/hamed-rezaee/fn_express","last_synced_at":"2025-10-05T01:53:57.773Z","repository":{"id":317725733,"uuid":"1068045341","full_name":"hamed-rezaee/fn_express","owner":"hamed-rezaee","description":"A Dart package for parsing and evaluating mathematical expressions with support for variables, functions, and constants.","archived":false,"fork":false,"pushed_at":"2025-10-02T17:01:25.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-02T17:55:46.731Z","etag":null,"topics":["dart","dartlang","math-expression-evaluator","math-expressions","math-interpreter","mathematics","parsing-engine"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/fn_express","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hamed-rezaee.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T19:14:50.000Z","updated_at":"2025-10-02T17:03:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hamed-rezaee/fn_express","commit_stats":null,"previous_names":["hamed-rezaee/fn_express"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hamed-rezaee/fn_express","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamed-rezaee%2Ffn_express","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamed-rezaee%2Ffn_express/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamed-rezaee%2Ffn_express/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamed-rezaee%2Ffn_express/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hamed-rezaee","download_url":"https://codeload.github.com/hamed-rezaee/fn_express/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamed-rezaee%2Ffn_express/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278399690,"owners_count":25980332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dart","dartlang","math-expression-evaluator","math-expressions","math-interpreter","mathematics","parsing-engine"],"created_at":"2025-10-05T01:53:52.690Z","updated_at":"2025-10-05T01:53:57.766Z","avatar_url":"https://github.com/hamed-rezaee.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fn Express\n\nA comprehensive Dart package for parsing and evaluating mathematical expressions with extensive support for variables, functions, constants, and complex numbers. Features a robust expression parser, rich mathematical function library, and interactive REPL environment.\n\n## Table of Contents\n\n- [Features](#features)\n- [Quick Start Example](#quick-start-example)\n- [Installation](#installation)\n- [Mathematical Functions](#mathematical-functions)\n- [Constants](#constants)\n- [Usage Examples](#usage-examples)\n- [Interactive REPL](#interactive-repl)\n- [Error Handling](#error-handling)\n- [Architecture](#architecture)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n- **Complete Arithmetic Support**: Basic operations (+, -, \\*, /, %, ^) with proper operator precedence\n- **Variable Management**: Define and use variables with assignment operations\n- **Rich Function Library**: Extensive collection of mathematical functions including sign and clamp\n- **Mathematical Constants**: Built-in constants (π, e, i, φ, τ)\n- **Multiple Number Types**: Integers, doubles, and complex numbers with automatic type promotion\n- **Expression Parsing**: Robust lexer and parser with error handling\n- **Implicit Multiplication**: Natural syntax like `2x`, `3(x+1)`, `(a+b)(c+d)`\n- **Interactive REPL**: Full-featured Read-Eval-Print Loop with help system, variable management, and command history\n\n## Mathematical Functions\n\n### Basic Functions\n\n- `sqrt(x)` - Square root (returns complex for negative inputs)\n- `abs(x)` - Absolute value (magnitude for complex numbers)\n- `ln(x)` - Natural logarithm\n- `exp(x)` - Exponential function (e^x)\n\n### Trigonometric Functions\n\n- `sin(x)`, `cos(x)`, `tan(x)` - Standard trigonometric functions\n- `asin(x)`, `acos(x)`, `atan(x)` - Inverse trigonometric functions\n\n### Hyperbolic Functions\n\n- `sinh(x)` - Hyperbolic sine\n- `cosh(x)` - Hyperbolic cosine\n- `tanh(x)` - Hyperbolic tangent\n- `asinh(x)` - Inverse hyperbolic sine\n- `acosh(x)` - Inverse hyperbolic cosine (domain: x ≥ 1)\n- `atanh(x)` - Inverse hyperbolic tangent (domain: -1 \u003c x \u003c 1)\n\n### Rounding Functions\n\n- `floor(x)` - Largest integer ≤ x\n- `ceil(x)` - Smallest integer ≥ x\n- `round(x)` - Nearest integer\n- `trunc(x)` - Integer part (truncation towards zero)\n\n### Special Functions\n\n- `fact(x)` - Factorial (for non-negative integers)\n- `factorial2(x)` - Double factorial (x!! = x*(x-2)*(x-4)...1 or 2)\n- `gamma(x)` - Gamma function (generalization of factorial for real numbers \u003e 0)\n- `sign(x)` - Sign function (returns -1, 0, or 1)\n\n### Multi-Argument Functions\n\n- `complex(real, imag)` - Create complex numbers\n- `log(value, base)` - Logarithm with custom base\n- `pow(base, exponent)` - Power function\n- `min(a, b, c, ...)` - Minimum of multiple values\n- `max(a, b, c, ...)` - Maximum of multiple values\n- `fraction(numerator, denominator)` - Create fractions\n- `clamp(value, min, max)` - Clamp value between minimum and maximum bounds\n\n### Number Theory Functions\n\n- `gcd(a, b)` - Greatest common divisor\n- `lcm(a, b)` - Least common multiple\n\n### Statistical Functions\n\n- `average(a, b, c, ...)` - Average (arithmetic mean) of multiple values\n- `median(a, b, c, ...)` - Median of multiple values\n- `mode(a, b, c, ...)` - Mode of multiple values (most frequent)\n- `stdev(a, b, c, ...)` - Sample standard deviation of multiple values (minimum 2 required)\n- `variance(a, b, c, ...)` - Sample variance of multiple values (minimum 2 required)\n\n### Random Number Generation\n\n- `random()` - Generate random number between 0 and 1\n\n## Constants\n\n- `pi` - Mathematical constant π (3.14159...)\n- `e` - Mathematical constant e (2.71828...)\n- `i` - Imaginary unit (√-1)\n- `phi` - Golden ratio φ (1.61803...)\n- `tau` - Mathematical constant τ = 2π (6.28318...)\n\n## Quick Start Example\n\n```dart\nimport 'package:fn_express/fn_express.dart';\n\nfinal interpreter = Interpreter();\n\n// Basic arithmetic and variables\ninterpreter.eval('x = 10');\nprint(interpreter.eval('2 * x + sqrt(16)'));  // 24.0\n\n// Mathematical functions\nprint(interpreter.eval('sin(pi/2) + cos(0)'));  // 2.0\n\n// Complex numbers\nprint(interpreter.eval('(3 + 4i) * (1 + i)'));  // -1.0 + 7.0i\n\n// Statistical functions\nprint(interpreter.eval('average(1, 2, 3, 4, 5)'));  // 3.0\n```\n\n## Installation\n\nAdd this package to your `pubspec.yaml`:\n\n```yaml\ndependencies:\n  fn_express: \u003clatest version\u003e\n```\n\nThen import the package:\n\n```dart\nimport 'package:fn_express/fn_express.dart';\n```\n\n## Usage Examples\n\n### Basic Arithmetic\n\n```dart\nfinal interpreter = Interpreter();\n\n// Simple calculations\nprint(interpreter.eval('2 + 3 * 4'));        // 14\nprint(interpreter.eval('(10 + 5) * 2'));     // 30\nprint(interpreter.eval('2^3^2'));            // 512 (right-associative)\n\n// Modulo operation\nprint(interpreter.eval('17 % 5'));           // 2\nprint(interpreter.eval('10.5 % 3'));         // 1.5\n```\n\n### Variables\n\n```dart\nfinal interpreter = Interpreter();\n\n// Variable assignment\ninterpreter.eval('x = 10');\ninterpreter.eval('y = 2 * x + 5');\n\nprint(interpreter.eval('x + y'));            // 35\n\n// Reassignment\ninterpreter.eval('x = x + 1');\n\nprint(interpreter.eval('x'));                // 11\n```\n\n### Mathematical Functions\n\n```dart\nfinal interpreter = Interpreter();\n\n// Basic functions\nprint(interpreter.eval('sqrt(16)'));         // 4.0\nprint(interpreter.eval('sqrt(-4)'));         // 2.0i (complex result)\nprint(interpreter.eval('abs(-5)'));          // 5.0\n\n// Trigonometric functions\nprint(interpreter.eval('sin(pi/2)'));        // 1.0\nprint(interpreter.eval('cos(0)'));           // 1.0\nprint(interpreter.eval('atan(1)'));          // 0.7854 (π/4)\n\n// Rounding functions\nprint(interpreter.eval('floor(3.7)'));       // 3\nprint(interpreter.eval('ceil(3.2)'));        // 4\nprint(interpreter.eval('round(3.7)'));       // 4\n\n// Factorial and sign\nprint(interpreter.eval('fact(5)'));          // 120\nprint(interpreter.eval('fact(0)'));          // 1\nprint(interpreter.eval('sign(-3.5)'));       // -1\nprint(interpreter.eval('sign(0)'));          // 0\n\n// Constants\nprint(interpreter.eval('phi'));              // 1.618... (golden ratio)\nprint(interpreter.eval('tau'));              // 6.283... (2π)\nprint(interpreter.eval('phi^2 - phi'));      // 1.0 (golden ratio property)\n```\n\n### Complex Numbers\n\n```dart\nfinal interpreter = Interpreter();\n\n// Creating complex numbers\nprint(interpreter.eval('complex(3, 4)'));    // 3.0 + 4.0i\nprint(interpreter.eval('2 + 3i'));           // 2.0 + 3.0i\n\n// Complex arithmetic\nprint(interpreter.eval('(2 + 3i) + (1 - 2i)')); // 3.0 + 1.0i\nprint(interpreter.eval('(2 + 3i) * (1 + i)'));  // -1.0 + 5.0i\nprint(interpreter.eval('abs(3 + 4i)'));         // 5.0 (magnitude)\n```\n\n### Advanced Functions\n\n```dart\nfinal interpreter = Interpreter();\n\n// Logarithms\nprint(interpreter.eval('ln(e)'));             // 1.0\nprint(interpreter.eval('log(100, 10)'));      // 2.0\nprint(interpreter.eval('log(8, 2)'));         // 3.0\n\n// Min/Max/Clamp with variable arguments\nprint(interpreter.eval('min(5, 3)'));              // 3\nprint(interpreter.eval('min(5, 2, 8, 1, 9)'));      // 1\nprint(interpreter.eval('max(2.5, 3.7)'));          // 3.7\nprint(interpreter.eval('max(5, 2, 8, 1, 9)'));      // 9\nprint(interpreter.eval('clamp(15, 0, 10)'));       // 10\nprint(interpreter.eval('clamp(-5, 0, 10)'));       // 0\n\n// Power functions\nprint(interpreter.eval('pow(2, 8)'));         // 256.0\nprint(interpreter.eval('2^8'));               // 256 (same as above)\n```\n\n### Implicit Multiplication\n\n```dart\nfinal interpreter = Interpreter();\n\ninterpreter.eval('x = 5');\nprint(interpreter.eval('2x'));               // 10 (2 * x)\nprint(interpreter.eval('3(x + 1)'));         // 18 (3 * (x + 1))\nprint(interpreter.eval('(x + 1)(x - 1)'));   // 24 ((x + 1) * (x - 1))\n```\n\n### Multi-Parameter Functions\n\n```dart\nfinal interpreter = Interpreter();\n\n// Statistical functions with multiple arguments\nprint(interpreter.eval('average(1, 2, 3, 4, 5)'));    // 3.0\nprint(interpreter.eval('median(1, 2, 3, 4, 5)'));     // 3.0\nprint(interpreter.eval('median(10, 5, 15, 20)'));     // 12.5\nprint(interpreter.eval('stdev(1, 2, 3, 4, 5)'));      // 1.58...\nprint(interpreter.eval('variance(2, 4, 6, 8)'));      // 6.67...\n\n// Min/Max with multiple values\nprint(interpreter.eval('min(5, 2, 8, 1, 9, 3)'));     // 1\nprint(interpreter.eval('max(5, 2, 8, 1, 9, 3)'));     // 9\n\n// Mode with multiple occurrences\nprint(interpreter.eval('mode(1, 2, 2, 3, 2, 4)'));    // 2\n```\n\n### Real-World Examples\n\n```dart\nfinal interpreter = Interpreter();\n\n// Physics: Kinetic energy calculation\ninterpreter.eval('mass = 10');      // kg\ninterpreter.eval('velocity = 25');  // m/s\nprint(interpreter.eval('0.5 * mass * velocity^2'));  // 3125 Joules\n\n// Geometry: Circle area and circumference\ninterpreter.eval('radius = 5');\nprint(interpreter.eval('pi * radius^2'));      // Area: 78.54\nprint(interpreter.eval('2 * pi * radius'));    // Circumference: 31.42\n\n// Statistics: Data analysis\ninterpreter.eval('data = average(23, 45, 56, 78, 12, 67, 89, 34)');\nprint(interpreter.eval('data'));                        // 50.5\nprint(interpreter.eval('stdev(23, 45, 56, 78, 12, 67, 89, 34)'));  // Standard deviation\n\n// Finance: Compound interest\ninterpreter.eval('principal = 1000');\ninterpreter.eval('rate = 0.05');\ninterpreter.eval('time = 10');\nprint(interpreter.eval('principal * (1 + rate)^time'));  // 1628.89\n\n// Engineering: Pythagorean theorem in 3D\ninterpreter.eval('x = 3; y = 4; z = 12');\nprint(interpreter.eval('sqrt(x^2 + y^2 + z^2)'));      // 13.0\n```\n\n### Advanced Mathematical Operations\n\n```dart\nfinal interpreter = Interpreter();\n\n// Complex number calculations (electrical engineering)\ninterpreter.eval('z1 = 3 + 4i');\ninterpreter.eval('z2 = 1 - 2i');\nprint(interpreter.eval('z1 * z2'));          // 11.0 - 2.0i\nprint(interpreter.eval('abs(z1)'));          // 5.0 (magnitude)\n\n// Trigonometric identities verification\nprint(interpreter.eval('sin(pi/3)^2 + cos(pi/3)^2'));   // 1.0\nprint(interpreter.eval('tan(pi/4)'));                    // 1.0\n\n// Logarithmic and exponential relationships\nprint(interpreter.eval('ln(exp(5))'));       // 5.0\nprint(interpreter.eval('log(10^3, 10)'));    // 3.0\n\n// Statistical analysis\nfinal data = 'stdev(12, 15, 18, 22, 25, 28, 31, 34, 37, 40)';\nprint(interpreter.eval(data));               // Sample standard deviation\n```\n\n### Interactive REPL\n\nThe package includes a powerful REPL (Read-Eval-Print Loop) for interactive mathematical expression evaluation. The REPL provides:\n\n- **Comprehensive Help System**: Built-in documentation for all operators, functions, and constants\n- **Variable Management**: Persistent variables across expressions with viewing and clearing capabilities\n- **Error Handling**: Clear error messages for invalid expressions or operations\n- **Command History**: Easy access to previously entered expressions\n- **Categorized Documentation**: Separate help sections for operators, functions, constants, and examples\n- **Clean Interface**: User-friendly command-line interface with clear prompts and formatting\n\n#### Usage\n\nTo use the REPL:\n\n```dart\nvar isRunning = true;\n\nfinal repl = Repl(\n  (output, {newline = true}) =\u003e\n      newline ? stdout.writeln(output) : stdout.write(output),\n);\n\nwhile (isRunning) {\n  stdout.write('\u003e\u003e ');\n  final input = stdin.readLineSync();\n\n  (input == null || input.toLowerCase() == 'exit')\n      ? isRunning = false\n      : repl(input);\n}\n```\n\n```\n╭─────────────────────────────────────╮\n│          Fn Express REPL            │\n│   Mathematical Expression Parser    │\n╰─────────────────────────────────────╯\n\nEnter mathematical expressions or type \"help\" for assistance.\nType \"exit\" to quit.\n\n\u003e\u003e x = 10\n10\n\u003e\u003e y = 2 * x + sqrt(16)\n24\n\u003e\u003e sin(pi/2) + cos(0)\n2.0\n\u003e\u003e fact(5) % 7\n1\n\u003e\u003e help\n═══════════════════ HELP ═══════════════════\n\nCOMMANDS:\n  help              Show this help message\n  help operators    Show available operators\n  help functions    Show available functions\n  help constants    Show available constants\n  help examples     Show usage examples\n  variables         Show defined variables\n  clear             Clear all variables\n  version           Show version info\n  exit              Exit the REPL\n\nBASIC USAGE:\n  • Enter expressions: 2 + 3 * 4\n  • Assign variables: x = 10\n  • Use functions: sin(pi/2)\n  • Implicit multiplication: 2x, 3(x+1)\n\n\u003e\u003e exit\n\nThanks for using Fn Express REPL! Goodbye!\n```\n\n#### REPL Commands\n\nThe REPL supports the following special commands:\n\n- `help` or `?` - Show general help information\n- `help operators` - Display all available operators with examples\n- `help functions` - Show all mathematical functions and their usage\n- `help constants` - List all built-in constants\n- `help examples` - Show comprehensive usage examples\n- `variables` or `vars` - Display all currently defined variables\n- `clear` - Clear all defined variables\n- `version` - Show REPL version information\n- `exit` - Exit the REPL\n\n## Error Handling\n\nThe package provides comprehensive error handling:\n\n```dart\nfinal interpreter = Interpreter();\n\ntry {\n  interpreter.eval('10 / 0');\n} catch (e) {\n  print(e); // ArgumentError: Division by zero\n}\n\ntry {\n  interpreter.eval('asin(2)');\n} catch (e) {\n  print(e); // ArgumentError: Arcsine domain error\n}\n\ntry {\n  interpreter.eval('fact(-1)');\n} catch (e) {\n  print(e); // ArgumentError: Factorial only defined for non-negative integers\n}\n```\n\n## Architecture\n\nThe package consists of several key components working together:\n\n- **Lexer**: Tokenizes mathematical expressions into meaningful symbols\n- **Parser**: Converts infix notation to postfix (RPN) using the Shunting Yard algorithm\n- **Evaluator**: Evaluates postfix expressions using an efficient stack-based approach\n- **Interpreter**: Coordinates the entire process and manages variables/functions\n- **NumberValue**: Flexible type system supporting integers, doubles, and complex numbers\n- **REPL**: Interactive environment with comprehensive help and command system\n\n### Type System\n\nThe package uses automatic type promotion to handle different number types seamlessly:\n\n```\nInteger → Double  → Complex\n5       → 5.0     → 5.0 + 0.0i\n```\n\nThis ensures that operations always produce mathematically correct results while maintaining performance.\n\n## Use Cases\n\nFn Express is ideal for:\n\n- **Educational Software**: Teaching mathematical concepts with interactive calculations\n- **Scientific Applications**: Complex mathematical computations in research\n- **Engineering Tools**: Formula-based calculations and simulations\n- **Financial Software**: Interest calculations, statistical analysis\n- **Game Development**: Mathematical systems, physics calculations\n- **Data Analysis**: Statistical computations and data processing\n- **Calculator Applications**: Building advanced calculator functionality\n\n```dart\nfinal interpreter = Interpreter();\n\nfor (final expression in expressions) {\n  try {\n    final result = interpreter.eval(expression);\n    print('$expression = $result');\n  } catch (e) {\n    print('Error evaluating $expression: $e');\n  }\n}\n```\n\n## Contributing\n\nWe welcome contributions! Here's how you can help:\n\n1. **Bug Reports**: Open an issue with detailed reproduction steps\n2. **Feature Requests**: Suggest new mathematical functions or features\n3. **Code Contributions**: Submit pull requests with tests and documentation\n4. **Documentation**: Improve examples, fix typos, or add use cases\n\n### Development Setup\n\n```bash\ngit clone https://github.com/hamed-rezaee/fn_express.git\ncd fn_express\ndart pub get\ndart test\n```\n\nFor major changes, please open an issue first to discuss the proposed changes.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](/LICENSE) file for details.\n\n## Resources\n\n- **Package Homepage**: [pub.dev](https://pub.dev/packages/fn_express)\n- **Source Code**: [GitHub Repository](https://github.com/hamed-rezaee/fn_express)\n- **Issue Tracker**: [GitHub Issues](https://github.com/hamed-rezaee/fn_express/issues)\n- **API Documentation**: [pub.dev documentation](https://pub.dev/documentation/fn_express)\n- **Changelog**: [CHANGELOG.md](CHANGELOG.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamed-rezaee%2Ffn_express","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhamed-rezaee%2Ffn_express","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamed-rezaee%2Ffn_express/lists"}