Quds Formula Parser #

Quds Formula Parser is a comprehensive Dart package for parsing, evaluating, and manipulating mathematical, logical, and textual formulas. It enables developers to create dynamic, formula-driven applications with support for a wide range of data types, custom functions, and operators. Whether you're building a spreadsheet engine, a scientific calculator, or a business rules evaluator, this package provides the robust foundation you need.

Key Features #

• Powerful Formula Parsing: Parse mathematical expressions and convert them from infix to postfix notation with full error reporting
• Rich Data Type Support: Work seamlessly with numbers, complex numbers, dates, times, durations, points in 2D/3D space, strings, atoms, and iterables
• Comprehensive Built-in Functions: Access over 100 pre-built mathematical, trigonometric, logical, statistical, and utility functions
• Custom Functions & Operators: Define your own functions and operators tailored to your specific needs
• Formula Simplification: Automatically simplify formulas for optimization and readability
• Variables & Context: Support for dynamic variables with real-time value changes
• Error Handling: Detailed parsing error detection and reporting with position information
• High Performance: Optimized parsing and evaluation for handling millions of operations
• Type Safety: Robust type checking and automatic type conversions where applicable
• Extensible Architecture: Build custom identifiers, functions, and operators by extending core classes

Supported Data Types #

Operators Reference #

Arithmetic Operators #

Comparison Operators #

Logical Operators #

Built-in Functions #

Mathematical Functions #

Trigonometric Functions #

String Functions #

Date & Time Functions #

Logical Functions #

Statistical Functions #

Geometry Functions #

Set Operations #

List Functions #

Atom (Chemistry) Functions #

Type Checking Functions #

Installation #

Add the following to your pubspec.yaml file:

dependencies:
  quds_formula_parser: ^0.0.10

Then run:

flutter pub get

Or for a pure Dart project:

dart pub get

Comprehensive Examples & Demos #

This package includes professional, production-ready examples:

📊 Flutter Interactive Demo (NEW!) #

Complete interactive application with:

• 2D Function Plotter - Real-time graphing with zoom/pan
• 3D Surface Visualization - Parametric 3D plots with rotation
• Visual Calculator - Formula history, symbol insertion, live evaluation
• Performance Metrics - Real-time parsing and evaluation benchmarks

Run the Flutter example:

cd flutter_example
flutter run

See detailed documentation: flutter_example/COMPREHENSIVE_EXAMPLE_README.md

🖥️ Command-Line Examples #

Dart CLI demonstrations of core functionality:

dart example/quds_formula_parser_example.dart

See all examples: example/COMPREHENSIVE_GUIDE.md

Usage #

Basic Parsing and Evaluation #

The simplest way to use Quds Formula Parser is to parse and evaluate a formula string:

import 'package:quds_formula_parser/quds_formula_parser.dart';

void main() {
  FormulaParser parser = FormulaParser();
  
  // Parse and evaluate a simple formula
  var result = parser.parse('5 + 9 / 2').evaluate();
  print('Result: $result'); // Output: 9.5
  
  // Evaluate power operation
  result = parser.parse('6 ^ 3').evaluate();
  print('Result: $result'); // Output: 216
  
  // Boolean operations
  result = parser.parse('true & false').evaluate();
  print('Result: $result'); // Output: false
}

Working with Variables #

Variables allow you to create reusable formulas that can be evaluated with different values:

import 'package:quds_formula_parser/quds_formula_parser.dart';

void main() {
  FormulaParser parser = FormulaParser();
  
  // Define a variable
  parser.insertVariable(NamedValue(symbol: 'x', value: 0));
  
  // Parse the formula once
  parser.parse('power(x, 2) + 3 * x + 5');
  
  // Evaluate with different values
  for (int i = 0; i <= 5; i++) {
    parser.setVariableValue('x', i);
    var result = parser.evaluate();
    print('f($i) = $result');
  }
  // Output:
  // f(0) = 5
  // f(1) = 9
  // f(2) = 15
  // f(3) = 23
  // f(4) = 33
  // f(5) = 45
}

Working with Different Data Types #

Parse and evaluate formulas using various data types supported by the package:

import 'package:quds_formula_parser/quds_formula_parser.dart';

void main() {
  FormulaParser parser = FormulaParser();
  
  // Complex numbers
  var result = parser.parse('5 - (2+7i)').evaluate();
  print('Complex: $result'); // Output: 3.0 + -7.0i
  
  // Dates and time operations
  result = parser.parse('Day(#2024-08-14#)').evaluate();
  print('Day: $result'); // Output: 14
  
  result = parser.parse('WeekDay(#2024-08-14#)').evaluate();
  print('Day of week: $result'); // Output: 3 (Wednesday)
  
  // Points in 2D space
  result = parser.parse('Point.Y({5, -7})').evaluate();
  print('Y coordinate: $result'); // Output: -7
  
  // Distance calculation
  result = parser.parse('Distance({0, 0}, {3, 4})').evaluate();
  print('Distance: $result'); // Output: 5
  
  // String operations
  result = parser.parse('Len("Hello World")').evaluate();
  print('Length: $result'); // Output: 11
  
  // Atomic data (chemistry)
  result = parser.parse('Atom.Weight(\'He)').evaluate();
  print('Helium weight: $result'); // Output: 4.0026
}

Conditional and Logical Operations #

Build intelligent formulas with conditions and logical operations:

import 'package:quds_formula_parser/quds_formula_parser.dart';

void main() {
  FormulaParser parser = FormulaParser();
  
  // Simple condition
  var result = parser.parse('If(5 > 3, "Yes", "No")').evaluate();
  print('Result: $result'); // Output: Yes
  
  // Complex condition for leap year check
  result = parser.parse(
    'If(And(Year(Today())%4=0,Year(Today())%100<>0),"Leap year","Not leap year")'
  ).evaluate();
  print('Result: $result'); // Output: Leap year or Not leap year
  
  // Set operations
  result = parser.parse('Intersect(Set(2,5,9),Set(5,7,2))').evaluate();
  print('Intersection: $result'); // Output: [2, 5]
}

Working with Lists and Collections #

Create and manipulate lists within formulas:

import 'package:quds_formula_parser/quds_formula_parser.dart';

void main() {
  FormulaParser parser = FormulaParser();
  
  // Create a list of days
  parser.parse(
    'SetVariable("days",List("Saturday","Sunday","Monday","Tuesday","Wednesday","Thursday","Friday"))'
  ).evaluate();
  
  // Get current day of week
  parser.parse('ElementAt(days,WeekDay(Today()))');
  var result = parser.evaluate();
  print('Today is: $result');
  
  // Find index of a specific day
  parser.parse('"Tuesday is day " + (IndexOf(days,"Tuesday") + 1)');
  result = parser.evaluate();
  print(result); // Output: Tuesday is day 3
}

Formula Simplification #

Automatically simplify mathematical formulas for readability and optimization:

import 'package:quds_formula_parser/quds_formula_parser.dart';

void main() {
  FormulaParser parser = FormulaParser();
  parser.setVariableValue('x', 0);
  
  List<String> formulas = [
    'x + x',           // Simplifies to: 2 * x
    'x * 1',           // Simplifies to: x
    'x * 0',           // Simplifies to: 0
    'x^2 + x^2',       // Simplifies to: 2 * x ^ 2
    '2 * x + 3 * x',   // Simplifies to: 5 * x
    'x + x * 2',       // Simplifies to: 3 * x
  ];
  
  for (String formula in formulas) {
    var result = parser.parse(formula);
    print('$formula => ${result.formulaString}');
  }
}

Creating Custom Functions #

Extend the library with domain-specific functions:

import 'package:quds_formula_parser/quds_formula_parser.dart';
import 'dart:math';

void main() {
  // Create a custom provider
  FormulaProvider provider = FormulaProvider();
  provider.identifiers.addAll([
    BracketIdentifier(),
    NamedValuesIdentifier(provider: provider),
  ]);
  
  // Register a custom function
  provider.registerFunction(
    notations: ['Randomize', 'Custom.Rnd'],
    checkParameters: (params) => params.length == 1 && params.first is num,
    evaluator: (params) {
      return params.first * Random().nextInt(100);
    }
  );
  
  // Another custom function with result manipulation
  provider.registerFunction(
    notations: ['SinX'],
    checkParameters: (params) => params.length == 1 && params.first is num,
    evaluator: (params) => sin(params.first),
    manipulateResult: (r) => r.abs() < 1e-6 ? 0.0 : r,
  );
  
  // Use the parser with custom functions
  var parser = FormulaParser(provider: provider);
  provider.setVariableValue('x', 0);
  
  parser.parse('Randomize(x)');
  for (int i = 0; i < 5; i++) {
    provider.setVariableValue('x', i);
    print('Random(x=$i): ${parser.evaluate()}');
  }
}

Setting Variables Dynamically #

Change variable values using formulas:

import 'package:quds_formula_parser/quds_formula_parser.dart';

void main() {
  FormulaParser parser = FormulaParser();
  
  // Set a variable using a formula string
  parser.parse('SetVariable("y", 8)').evaluate();
  
  // Use the variable in another formula
  parser.parse('power(y, 2)').evaluate();
  var result = parser.evaluate();
  print('Result: $result'); // Output: 64
}

Error Handling #

Properly handle parsing errors with detailed information:

import 'package:quds_formula_parser/quds_formula_parser.dart';

void main() {
  FormulaParser parser = FormulaParser();
  
  List<String> formulas = [
    '5 + 9 / 2',       // Valid
    '4 + w5',          // Error: undefined term
    '4 +',             // Error: missing operand
    '4 + ()',          // Error: empty brackets
    '(4) + ((54)',     // Error: missing closing bracket
  ];
  
  for (String formula in formulas) {
    var result = parser.parse(formula);
    
    if (result.hasParsingError) {
      print('Error in "$formula":');
      print('  Position: ${result.errorParsingPosition}');
      print('  Type: ${result.errorCode?.name}');
    } else {
      var evaluated = parser.evaluate();
      print('$formula => $evaluated');
    }
  }
}

Performance Optimization #

For high-performance scenarios, parse formulas once and evaluate many times:

import 'package:quds_formula_parser/quds_formula_parser.dart';

void main() {
  FormulaParser parser = FormulaParser();
  parser.insertVariable(NamedValue(symbol: 'x', value: 0));
  
  // Parse the formula once
  String formulaStr = 'power(x, 2)';
  parser.parse(formulaStr);
  
  // Evaluate 1 million times with different values
  Stopwatch stopwatch = Stopwatch();
  stopwatch.start();
  
  const int times = 1000000;
  for (int i = 0; i < times; i++) {
    parser.setVariableValue('x', i);
    parser.evaluate();
  }
  
  stopwatch.stop();
  print('Evaluated $times times in ${stopwatch.elapsedMilliseconds}ms');
  print('Average time per evaluation: ${stopwatch.elapsedMilliseconds / times}ms');
}

Advanced: Custom Identifiers and Operators #

For advanced use cases, extend the library with custom identifiers:

import 'package:quds_formula_parser/quds_formula_parser.dart';

void main() {
  // Create custom provider with specific identifiers
  FormulaProvider provider = FormulaProvider();
  provider.identifiers.addAll([
    BracketIdentifier(),
    NamedValuesIdentifier(provider: provider),
    FunctionIdentifier(functions: []) // Add custom functions if needed
  ]);
  
  var parser = FormulaParser(provider: provider);
  
  // Parse and evaluate
  var result = parser.parse('(10 + 5) * 2').evaluate();
  print('Result: $result'); // Output: 30
}

Real-World Examples #

Example 1: Grade Calculator #

FormulaParser parser = FormulaParser();
parser.setVariables({'midterm': 75, 'final': 85, 'project': 90});
parser.parse('(midterm * 0.3) + (final * 0.5) + (project * 0.2)');
var grade = parser.evaluate();
print('Overall grade: $grade'); // Output: 82.5

Example 2: Financial Calculation #

FormulaParser parser = FormulaParser();
// Calculate compound interest: A = P(1 + r/n)^(nt)
parser.setVariables({
  'principal': 1000,
  'rate': 0.05,      // 5%
  'periods': 12,     // monthly
  'years': 5
});
parser.parse('principal * (1 + rate/periods) ^ (periods * years)');
var amount = parser.evaluate();
print('Final amount: \$$amount');

Example 3: Geometric Calculations #

FormulaParser parser = FormulaParser();
// Calculate area of triangle given three points
var area = parser.parse('Abs(((x1*(y2-y3) + x2*(y3-y1) + x3*(y1-y2))/2))').evaluate();
print('Triangle area: $area');

Advanced Topics #

Extending with Custom Types #

The package supports adding custom data types through custom identifiers and wrapper classes. You can register your own types by extending the identifier system and providing appropriate evaluation handlers.

Performance Considerations #

• Parse Once, Evaluate Many: For formulas used repeatedly, parse once and evaluate multiple times for optimal performance
• Variable Caching: Use the variable system to avoid re-parsing formulas with changing values
• Function Registration: Register frequently-used custom functions to avoid lookup overhead
• Pre-compilation: The package automatically optimizes formula representation during parsing

Thread Safety #

The FormulaParser and FormulaProvider classes maintain state. For multi-threaded applications, create separate parser instances for each thread or use appropriate synchronization mechanisms.

API Reference #

Core Classes #

• FormulaParser: Main class for parsing and evaluating formulas
• FormulaProvider: Manages functions, variables, and identifiers
• FormulaInfixToPostfixConvertor: Converts infix notation to postfix and evaluates
• Formula: Represents a parsed formula with error information
• NamedValue: Represents a variable with symbol and value

Key Methods #

• parse(String formula): Parse a formula string
• evaluate(): Evaluate the last parsed formula
• setVariableValue(String symbol, dynamic value): Set variable value
• insertVariable(NamedValue variable): Define a new variable
• registerFunction(...): Register a custom function

Testing #

The package includes comprehensive tests covering:

• Formula parsing and simplification
• All built-in functions and operators
• Custom function registration
• Variable operations
• Error handling and edge cases
• Performance benchmarks

Run tests with:

dart test

Contributing #

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch for your changes
3. Add tests for new functionality
4. Submit a pull request with a clear description of your changes

Please ensure all tests pass before submitting a pull request.

License #

This package is licensed under the MIT License. See the LICENSE file for more information.

Support #

For issues, feature requests, or questions, please visit the GitHub repository.

Changelog #

See the CHANGELOG.md file for version history and release notes.