math-engine 0.5.0__tar.gz → 0.6.0__tar.gz

{math_engine-0.5.0 → math_engine-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: math-engine
-Version: 0.5.0
+Version: 0.6.0
 Summary: A fast and secure mathematical expression evaluator.
 Author-email: Jan Teske <jan.teske.06@gmail.com>
 Project-URL: Homepage, https://github.com/JanTeske06/math_engine
@@ -14,7 +14,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 
 
-# Math Engine 0.5.0
+# Math Engine v0.6.0
 
 [![PyPI Version](https://img.shields.io/pypi/v/math-engine.svg)](https://pypi.org/project/math-engine/)
 [![License: MIT](https://img.shields.io/pypi/l/math-engine.svg)](https://opensource.org/licenses/MIT)
@@ -354,7 +354,6 @@ All bitwise functions:
 - support overflow/wrap-around behavior  
 - fully support binary, hex, decimal, and octal inputs  
 - participate in the AST just like standard operators  
-- support underscores in non-decimal literals (`0b1111_0000`)  
 
 This makes Math Engine behave like a full-featured programmer’s calculator with CPU-like precision control.
 
@@ -393,6 +392,8 @@ preset = {
     # New in 0.3.0
     "word_size": 0,        # 0 = unlimited, or 8, 16, 32, 64
     "signed_mode": True,   # True = Two's Complement, False = Unsigned
+    # New in 0.6.0
+    "readable_error": False
 }
 
 math_engine.load_preset(preset)
@@ -412,70 +413,83 @@ decimal_places = math_engine.load_one_setting("decimal_places")
 
 -----
 
-# Error Handling
 
-Every error is a custom exception with:
+# Error Handling (v0.6.0: Visual & Precise)
 
-  * Human-readable message
-  * Machine-readable error code
-  * Position (if applicable)
-  * The original expression
+Math Engine 0.6.0 introduces a dual-mode error handling system designed for both interactive use and strict library integration.
 
-Example:
+## 1\. Visual Feedback (Default Behavior)
+
+By default (`readable_error = True`), the engine catches syntax errors internally and prints a visual diagnostic to the console. This is perfect for CLI tools or quick debugging, as it points exactly to the issue without crashing the program.
 
 ```python
 import math_engine
-from math_engine import error as E
 
-try:
-    math_engine.evaluate("1/0")
-except E.CalculationError as e:
-    print(e.code)      # 3003
-    print(e.message)   # "Division by zero"
-    print(e.equation)  # "1/0"
+# readable_error is True by default
+math_engine.evaluate("sin(5") 
 ```
 
-### Example Error Codes
+**Console Output:**
 
-| Code | Meaning                     |
-| ---- | --------------------------- |
-| 3003 | Division by zero            |
-| 3034 | Empty input                 |
-| 3036 | Multiple = signs            |
-| 3032 | Multiple-character variable |
-| 8000 | Conversion to int failed    |
-| 8006 | Output conversion error     |
+```text
+Errormessage: Unbalanced parenthesis.
+Code: 2010
+Equation: sin(5
+             ^ HERE IS THE PROBLEM (Position: 5)
+```
 
-For a complete list of all error codes and their meanings, please see the **[Error Codes Reference](https://github.com/JanTeske06/math_engine/blob/master/ERRORS.md)**.
+## 2\. Programmatic Handling (Exceptions)
 
------
+If you are building an application or running unit tests, you likely want to catch exceptions instead of printing to stdout. You can disable `readable_error` to raise standard `MathError` exceptions.
 
-# Testing and Reliability
+The exception object carries **precise start and end indices**:
 
-math\_engine is designed with testing in mind:
+  * `e.position_start` (int): Index where the error begins.
+  * `e.position_end` (int): Index where the error ends.
 
-  * Full error-code consistency
-  * Strict syntax rules
-  * Unit-test friendly behavior
-  * No reliance on Python’s runtime execution
+<!-- end list -->
 
-Example with `pytest`:
+```python
+import math_engine
+from math_engine import error as E
+
+# Disable visual printing to catch exceptions
+math_engine.change_setting("readable_error", False)
+
+try:
+    math_engine.evaluate("10.5 + 4.2.1")
+except E.SyntaxError as e:
+    print(f"Error Code: {e.code}")
+    print(f"Location: {e.position_start} to {e.position_end}")
+    
+    # You can use these indices to highlight the error in your own UI
+    bad_part = e.equation[e.position_start : e.position_end + 1]
+    print(f"Invalid segment: '{bad_part}'")
+
+```
+
+## Testing and Reliability
+
+To write unit tests with `pytest`, ensure you set `readable_error` to `False` so that exceptions are raised and can be asserted.
 
 ```python
 import pytest
 import math_engine
 from math_engine import error as E
 
-def test_division_by_zero_error_code():
+def test_division_by_zero():
+    # Ensure exceptions are raised
+    math_engine.change_setting("readable_error", False)
+    
     with pytest.raises(E.CalculationError) as exc:
-        math_engine.evaluate("1/0")
+        math_engine.evaluate("10 / 0")
+        
+    # Assert the error is Division by Zero (3003)
     assert exc.value.code == "3003"
+    # Assert the error points exactly to the zero/operator
+    assert exc.value.position_start == 3 
 ```
-
-You can also test more advanced behavior (non-decimal, strict modes, bitwise operations, etc.) in the same way.
-
------
-
+---
 # Performance
 
   * No use of Python `eval()`

{math_engine-0.5.0 → math_engine-0.6.0}/README.md

@@ -1,5 +1,5 @@
 
-# Math Engine 0.5.0
+# Math Engine v0.6.0
 
 [![PyPI Version](https://img.shields.io/pypi/v/math-engine.svg)](https://pypi.org/project/math-engine/)
 [![License: MIT](https://img.shields.io/pypi/l/math-engine.svg)](https://opensource.org/licenses/MIT)
@@ -339,7 +339,6 @@ All bitwise functions:
 - support overflow/wrap-around behavior  
 - fully support binary, hex, decimal, and octal inputs  
 - participate in the AST just like standard operators  
-- support underscores in non-decimal literals (`0b1111_0000`)  
 
 This makes Math Engine behave like a full-featured programmer’s calculator with CPU-like precision control.
 
@@ -378,6 +377,8 @@ preset = {
     # New in 0.3.0
     "word_size": 0,        # 0 = unlimited, or 8, 16, 32, 64
     "signed_mode": True,   # True = Two's Complement, False = Unsigned
+    # New in 0.6.0
+    "readable_error": False
 }
 
 math_engine.load_preset(preset)
@@ -397,70 +398,83 @@ decimal_places = math_engine.load_one_setting("decimal_places")
 
 -----
 
-# Error Handling
 
-Every error is a custom exception with:
+# Error Handling (v0.6.0: Visual & Precise)
 
-  * Human-readable message
-  * Machine-readable error code
-  * Position (if applicable)
-  * The original expression
+Math Engine 0.6.0 introduces a dual-mode error handling system designed for both interactive use and strict library integration.
 
-Example:
+## 1\. Visual Feedback (Default Behavior)
+
+By default (`readable_error = True`), the engine catches syntax errors internally and prints a visual diagnostic to the console. This is perfect for CLI tools or quick debugging, as it points exactly to the issue without crashing the program.
 
 ```python
 import math_engine
-from math_engine import error as E
 
-try:
-    math_engine.evaluate("1/0")
-except E.CalculationError as e:
-    print(e.code)      # 3003
-    print(e.message)   # "Division by zero"
-    print(e.equation)  # "1/0"
+# readable_error is True by default
+math_engine.evaluate("sin(5") 
 ```
 
-### Example Error Codes
+**Console Output:**
 
-| Code | Meaning                     |
-| ---- | --------------------------- |
-| 3003 | Division by zero            |
-| 3034 | Empty input                 |
-| 3036 | Multiple = signs            |
-| 3032 | Multiple-character variable |
-| 8000 | Conversion to int failed    |
-| 8006 | Output conversion error     |
+```text
+Errormessage: Unbalanced parenthesis.
+Code: 2010
+Equation: sin(5
+             ^ HERE IS THE PROBLEM (Position: 5)
+```
 
-For a complete list of all error codes and their meanings, please see the **[Error Codes Reference](https://github.com/JanTeske06/math_engine/blob/master/ERRORS.md)**.
+## 2\. Programmatic Handling (Exceptions)
 
------
+If you are building an application or running unit tests, you likely want to catch exceptions instead of printing to stdout. You can disable `readable_error` to raise standard `MathError` exceptions.
 
-# Testing and Reliability
+The exception object carries **precise start and end indices**:
 
-math\_engine is designed with testing in mind:
+  * `e.position_start` (int): Index where the error begins.
+  * `e.position_end` (int): Index where the error ends.
 
-  * Full error-code consistency
-  * Strict syntax rules
-  * Unit-test friendly behavior
-  * No reliance on Python’s runtime execution
+<!-- end list -->
 
-Example with `pytest`:
+```python
+import math_engine
+from math_engine import error as E
+
+# Disable visual printing to catch exceptions
+math_engine.change_setting("readable_error", False)
+
+try:
+    math_engine.evaluate("10.5 + 4.2.1")
+except E.SyntaxError as e:
+    print(f"Error Code: {e.code}")
+    print(f"Location: {e.position_start} to {e.position_end}")
+    
+    # You can use these indices to highlight the error in your own UI
+    bad_part = e.equation[e.position_start : e.position_end + 1]
+    print(f"Invalid segment: '{bad_part}'")
+
+```
+
+## Testing and Reliability
+
+To write unit tests with `pytest`, ensure you set `readable_error` to `False` so that exceptions are raised and can be asserted.
 
 ```python
 import pytest
 import math_engine
 from math_engine import error as E
 
-def test_division_by_zero_error_code():
+def test_division_by_zero():
+    # Ensure exceptions are raised
+    math_engine.change_setting("readable_error", False)
+    
     with pytest.raises(E.CalculationError) as exc:
-        math_engine.evaluate("1/0")
+        math_engine.evaluate("10 / 0")
+        
+    # Assert the error is Division by Zero (3003)
     assert exc.value.code == "3003"
+    # Assert the error points exactly to the zero/operator
+    assert exc.value.position_start == 3 
 ```
-
-You can also test more advanced behavior (non-decimal, strict modes, bitwise operations, etc.) in the same way.
-
------
-
+---
 # Performance
 
   * No use of Python `eval()`

{math_engine-0.5.0 → math_engine-0.6.0}/math_engine/AST_Node_Types.py

@@ -8,11 +8,13 @@ from . import error as E
 class Number:
     """AST node for numeric literal backed by Decimal."""
 
-    def __init__(self, value):
+    def __init__(self, value, position_start=-1, position_end=-1):
         # Always normalize input to Decimal via string to avoid float artifacts
         if not isinstance(value, Decimal):
             value = str(value)
         self.value = Decimal(value)
+        self.position_start = position_start
+        self.position_end = position_end
 
     def evaluate(self):
         """Return Decimal value for this literal."""
@@ -23,11 +25,9 @@ class Number:
         return (0, self.value)
 
     def __repr__(self):
-        # Helpful for debugging/printing the AST
         try:
             display_value = self.value.to_normal_string()
         except AttributeError:
-            # Fallback for older Decimal versions
             display_value = str(self.value)
         return f"Number({display_value})"
 
@@ -35,21 +35,21 @@ class Number:
 class Variable:
     """AST node representing a single symbolic variable (e.g. 'var0')."""
 
-    def __init__(self, name):
+    def __init__(self, name, position_start=-1, position_end=-1):
         self.name = name
+        self.position_start = position_start
+        self.position_end = position_end
 
     def evaluate(self):
         """Variables cannot be directly evaluated without solving."""
-        raise E.SolverError(f"Non linear problem.", code="3005")
+        raise E.SolverError(f"Non linear problem.", code="3005", position_start=self.position_start)
 
     def collect_term(self, var_name):
         """Return (1, 0) if this variable matches var_name; else error."""
         if self.name == var_name:
             return (1, 0)
         else:
-            # Only one variable supported in the linear solver
-            raise E.SolverError(f"Multiple variables found: {self.name}", code="3002")
-            return (0, 0)
+            raise E.SolverError(f"Multiple variables found: {self.name}", code="3002", position_start=self.position_start)
 
     def __repr__(self):
         return f"Variable('{self.name}')"
@@ -58,15 +58,20 @@ class Variable:
 class BinOp:
     """AST node for a binary operation: left <operator> right."""
 
-    def __init__(self, left, operator, right):
+    def __init__(self, left, operator, right, position_start=-1, position_end=-1):
         self.left = left
         self.operator = operator
         self.right = right
+        self.position_start = position_start
+        self.position_end = position_end
 
     def evaluate(self):
         """Evaluate numeric subtree and apply the binary operator."""
         left_value = self.left.evaluate()
         right_value = self.right.evaluate()
+        def check_int(val_l, val_r):
+            if val_l % 1 != 0 or val_r % 1 != 0:
+                raise E.CalculationError(f"Operator '{self.operator}' requires integers.", code="3042", position_start=self.position_start)
 
         if self.operator == '+':
             return left_value + right_value
@@ -75,28 +80,23 @@ class BinOp:
             return left_value - right_value
 
         elif self.operator == '&':
-            if left_value % 1 != 0 or right_value % 1 != 0:
-                raise E.CalculationError("Bitwise AND requires integers.", code="3042")
+            check_int(left_value, right_value)
             return Decimal(int(left_value) & int(right_value))
 
         elif self.operator == '|':
-            if left_value % 1 != 0 or right_value % 1 != 0:
-                raise E.CalculationError("Bitwise OR requires integers.", code="3042")
+            check_int(left_value, right_value)
             return Decimal(int(left_value) | int(right_value))
 
         elif self.operator == '^':
-            if left_value % 1 != 0 or right_value % 1 != 0:
-                raise E.CalculationError("XOR requires integers.", code="3042")
+            check_int(left_value, right_value)
             return Decimal(int(left_value) ^ int(right_value))
 
         elif self.operator == '<<':
-            if left_value % 1 != 0 or right_value % 1 != 0:
-                raise E.CalculationError("Bitshift requires integers.", code="3041")
+            check_int(left_value, right_value)
             return Decimal(int(left_value) << int(right_value))
 
         elif self.operator == '>>':
-            if left_value % 1 != 0 or right_value % 1 != 0:
-                raise E.CalculationError("Bitshift requires integers.", code="3041")
+            check_int(left_value, right_value)
             return Decimal(int(left_value) >> int(right_value))
 
         elif self.operator == '*':
@@ -107,78 +107,55 @@ class BinOp:
 
         elif self.operator == '/':
             if right_value == 0:
-                raise E.CalculationError("Division by zero", code="3003")
+                raise E.CalculationError("Division by zero", code="3003", position_start=self.position_start)
             return left_value / right_value
 
         elif self.operator == '=':
-            # Equality is evaluated to a boolean (used for "= True/False" responses)
             return left_value == right_value
         else:
-            raise E.CalculationError(f"Unknown operator: {self.operator}", code="3004")
+            raise E.CalculationError(f"Unknown operator: {self.operator}", code="3004", position_start=self.position_start)
 
     def collect_term(self, var_name):
-        """Collect linear terms on this subtree into (factor_of_var, constant).
-
-        Only linear combinations are allowed; non-linear forms raise Solver/Syntax errors.
-        """
+        """Collect linear terms on this subtree into (factor_of_var, constant)."""
         (left_factor, left_constant) = self.left.collect_term(var_name)
         (right_factor, right_constant) = self.right.collect_term(var_name)
 
         if self.operator == '+':
-            result_factor = left_factor + right_factor
-            result_constant = left_constant + right_constant
-            return (result_factor, result_constant)
+            return (left_factor + right_factor, left_constant + right_constant)
 
         elif self.operator == '-':
-            result_factor = left_factor - right_factor
-            result_constant = left_constant - right_constant
-            return (result_factor, result_constant)
+            return (left_factor - right_factor, left_constant - right_constant)
 
         elif self.operator == '*':
-            # Only constant * (A*x + B) is allowed. (A*x + B)*(C*x + D) would be non-linear.
+            # Only constant * (A*x + B) is allowed.
             if left_factor != 0 and right_factor != 0:
-                raise E.SyntaxError("x^x Error.", code="3005")
+                raise E.SyntaxError("x^x Error (Non-linear).", code="3005", position_start=self.position_start)
 
             elif left_factor == 0:
-                # B * (C*x + D) = (B*C)*x + (B*D)
-                result_factor = left_constant * right_factor
-                result_constant = left_constant * right_constant
-                return (result_factor, result_constant)
+                return (left_constant * right_factor, left_constant * right_constant)
 
             elif right_factor == 0:
-                # (A*x + B) * D = (A*D)*x + (B*D)
-                result_factor = right_constant * left_factor
-                result_constant = right_constant * left_constant
-                return (result_factor, result_constant)
+                return (right_constant * left_factor, right_constant * left_constant)
 
             elif left_factor == 0 and right_factor == 0:
-                # Pure constant multiplication
-                result_factor = 0
-                result_constant = right_constant * left_constant
-                return (result_factor, result_constant)
+                return (0, right_constant * left_constant)
 
         elif self.operator == '/':
-            # (A*x + B) / D is allowed; division by (C*x + D) is non-linear
             if right_factor != 0:
-                raise E.SolverError("Non-linear equation. (Division by x)", code="3006")
+                raise E.SolverError("Non-linear equation (Division by variable).", code="3006", position_start=self.position_start)
             elif right_constant == 0:
-                raise E.SolverError("Solver: Division by zero", code="3003")
+                raise E.SolverError("Solver: Division by zero", code="3003", position_start=self.position_start)
             else:
-                # (A*x + B) / D = (A/D)*x + (B/D)
-                result_factor = left_factor / right_constant
-                result_constant = left_constant / right_constant
-                return (result_factor, result_constant)
+                return (left_factor / right_constant, left_constant / right_constant)
 
         elif self.operator == '**':
-            # Powers generate non-linear terms (e.g., x^2)
-            raise E.SolverError("Powers are not supported by the linear solver.", code="3007")
+            raise E.SolverError("Powers are not supported by the linear solver.", code="3007", position_start=self.position_start)
 
         elif self.operator == '=':
-            # '=' only belongs at the root for solving; not inside collection
-            raise E.SolverError("Should not happen: '=' inside collect_terms", code="3720")
+            raise E.SolverError("Should not happen: '=' inside collect_terms", code="3720", position_start=self.position_start)
 
         else:
-            raise E.CalculationError(f"Unknown operator: {self.operator}", code="3004")
+            raise E.CalculationError(f"Unknown operator: {self.operator}", code="3004", position_start=self.position_start)
 
     def __repr__(self):
-        return f"BinOp({self.operator!r}, left={self.left}, right={self.right})"
+        return f"BinOp({self.operator!r}, left={self.left}, right={self.right})"