# Negative Number Handling

## Overview

This document describes how negative numbers are handled in the scripting language, including the parser precedence rules and best practices for working with negative values.

## The Core Rule

**Negative numbers always require parentheses in expressions.**

This is a fundamental language feature, not a bug. The parser requires explicit parentheses around negative numbers to avoid precedence ambiguity.

## Why This Exists

The parser needs to distinguish between two different uses of the `-` symbol:

1. **Unary minus** (negative numbers): `-5`
2. **Binary minus** (subtraction): `5 - 3`

Without parentheses, expressions like `-5 + 3` are ambiguous and cause parsing errors.

## Examples

### ❌ Incorrect Usage

```plaintext
/* These will cause parsing errors */
result1 : -5 + 3;
result2 : -5 >= 0;
result3 : f -5;
result4 : -5 * 2;
result5 : (-5 >= 0) and (-5 <= 120);
```

### ✅ Correct Usage

```plaintext
/* These work correctly */
result1 : (-5) + 3;
result2 : (-5) >= 0;
result3 : f (-5);
result4 : (-5) * 2;
result5 : ((-5) >= 0) and ((-5) <= 120);
```

## Common Patterns

### Function Calls

```plaintext
/* Function calls with negative numbers */
double : x -> x * 2;
result : double (-5);  /* ✅ Correct */

/* Higher-order functions */
numbers : {-3, -2, -1, 0, 1, 2, 3};
abs_values : map (x -> if x < 0 then (-x) else x) numbers;
```

### Comparisons

```plaintext
/* Comparisons with negative numbers */
is_negative : x -> x < 0;
test1 : is_negative (-5);  /* ✅ Correct */

/* Range validation */
validate_age : age -> (age >= 0) and (age <= 120);
test2 : validate_age (-5);  /* ✅ Correct */
```

### Arithmetic Operations

```plaintext
/* Basic arithmetic */
sum : (-5) + 3;        /* ✅ Correct */
product : (-5) * 2;    /* ✅ Correct */
difference : 10 - (-5); /* ✅ Correct (binary minus) */
```

### Logical Expressions

```plaintext
/* Complex boolean logic */
complex_check : x -> ((-5) >= 0) and ((-5) <= 120);  /* ✅ Correct */

/* Step-by-step approach (recommended) */
step1 : (-5) >= 0;     /* false */
step2 : (-5) <= 120;   /* true */
result : step1 and step2;  /* false */
```

### Pattern Matching

```plaintext
/* Pattern matching with negative numbers */
classify : x ->
  when x is
    (-5) then "negative five"
    0 then "zero"
    5 then "positive five"
    _ then "other";
```

## Best Practices

### 1. Always Use Parentheses

When in doubt, add parentheses around negative numbers. It's better to be explicit than to encounter parsing errors.

### 2. Break Complex Expressions

For complex expressions involving negative numbers, consider breaking them into smaller steps:

```plaintext
/* Instead of this complex expression */
complex : ((-5) >= 0) and ((-5) <= 120) and ((-5) != 0);

/* Do this */
step1 : (-5) >= 0;
step2 : (-5) <= 120;
step3 : (-5) != 0;
result : step1 and step2 and step3;
```

### 3. Use Helper Functions

Create helper functions for common operations involving negative numbers:

```plaintext
/* Helper functions for validation */
is_positive : x -> x > 0;
is_negative : x -> x < 0;
is_zero : x -> x = 0;

/* Use them in complex expressions */
validate_input : x -> (is_positive x) or (is_negative x) or (is_zero x);
```

## Error Messages

When you forget parentheses, you'll see errors like:

- `"Expected ")" after expression"`
- `"Unexpected token in parsePrimary: PLUS"`
- `"Unexpected token in parsePrimary: GREATER_EQUAL"`

These errors indicate that the parser encountered an operator after a negative number without proper parentheses.

## Historical Context

This behavior was documented in the `PARSER_PRECEDENCE_FIX.md` file as part of the language's design. Rather than implementing complex precedence handling that could lead to logic loops, the language requires explicit parentheses for clarity and consistency.

## Related Documentation

- [Juxtaposition Tutorial](tutorials/01_Juxtaposition_Function_Application.md#negative-numbers-and-parentheses) - Detailed examples and patterns
- [Introduction Tutorial](tutorials/00_Introduction.md) - Basic overview
- [Parser Precedence Fix](design/HISTORY/PARSER_PRECEDENCE_FIX.md) - Historical context

## Summary

**Remember**: Negative numbers require parentheses in all expressions. This is a language feature designed for clarity and consistency, not a limitation to be worked around.

**Rule of thumb**: When you see a negative number in an expression, wrap it in parentheses: `(-5)` instead of `-5`.