# @fnet/expression

## Introduction
The `@fnet/expression` project is designed to help users parse and analyze structured expressions that consist of processor and statement components. This tool can be particularly useful for those who need to dissect complex expressions into more manageable parts, allowing for easier understanding and processing.

## How It Works
The project works by taking a structured expression and breaking it down into its basic components: processors and statements. It uses a recursive parsing method to handle nested expressions while respecting a maximum depth to prevent too deep recursion. The expression is analyzed to extract all processors, presenting a clear hierarchy and order of the components.

## Key Features
- **Recursive Parsing**: Efficiently breaks down expressions into individual components, even handling nested structures.
- **Processor Extraction**: Gathers all processor elements from the expression, providing an ordered list.
- **Depth Management**: Prevents overly deep recursion by setting a limit, ensuring performance and reliability.

## Conclusion
The `@fnet/expression` project is a straightforward and practical tool for parsing and analyzing structured expressions. It offers users a reliable method to dissect intricate expressions into simpler parts, making them easier to work with and understand.


# @fnet/expression Developer Guide

## Overview

The `@fnet/expression` library is designed to parse and dissect custom string expressions into their respective components, allowing developers to easily manage structured data expressions. The library's primary functionality allows users to break down expressions into processors and statements, even supporting nested expressions up to a specified depth. This enables structured parsing of expressions for various use cases such as data processing pipelines, configuration management, or templating systems.

## Installation

To use `@fnet/expression` in your project, you can install it via npm or yarn:

### Using npm

```bash
npm install @fnet/expression
```

### Using yarn

```bash
yarn add @fnet/expression
```

## Usage

Here's a practical example of how to use the `@fnet/expression` library to parse a custom expression format and retrieve its components:

```javascript
import parseExpression from '@fnet/expression';

// Example expression string
const myExpression = 'filter::sort::capitalize::Transform this text';

// Parse the expression
const parsedData = parseExpression({ expression: myExpression });

// Display the parsed components
console.log(parsedData);
```

## Examples

Below are some examples demonstrating common use cases of the library:

### Parsing an Expression

```javascript
import parseExpression from '@fnet/expression';

const expression = 'process1::step2::finalize::Process the data fully';
const result = parseExpression({ expression });

console.log(result);

// Expected Output
// {
//   processor: 'process1',
//   statement: 'step2::finalize::Process the data fully',
//   expression: 'process1::step2::finalize::Process the data fully',
//   process: {
//     statement: 'Process the data fully',
//     order: ['process1', 'step2', 'finalize']
//   },
//   next: {
//     processor: 'step2',
//     ...
//   }
// }
```

### Handling Nested Expressions

The library can handle nested expressions and limit recursion depth to maintain performance and avoid infinite loops:

```javascript
import parseExpression from '@fnet/expression';

const nestedExpression = 'outer::inner::deepest::Execute the chain';
const parsedResult = parseExpression({ expression: nestedExpression, depth: 3 });

console.log(parsedResult);

// Expected Output includes structured breakdown of each level,
// showing processors and statements for each nested level
```

## Acknowledgement

The development of `@fnet/expression` was guided by community-driven requirements and contributions. The structure and approach for parsing expressions are inspired by best practices in data parsing and processing.



# Input Schema

```yaml
$schema: https://json-schema.org/draft/2020-12/schema
title: Expression Parsing
type: object
properties:
  expression:
    type: string
    description: The expression to be parsed.
required:
  - expression

```



# Output Schema

```yaml
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  processor:
    type: string
    description: The top-level processor extracted from the expression.
  statement:
    type: string
    description: The top-level statement part of the expression.
  expression:
    type: string
    description: The original expression that was parsed.
  process:
    type: object
    properties:
      statement:
        type: string
        description: The statement from the deepest nested expression.
      order:
        type: array
        items:
          type: string
        description: An array containing the order of processors from the outermost to
          the innermost.
    required:
      - statement
      - order
    description: Details of the processing order and final statement.
  next:
    $ref: "#"
    description: The next nested parsed expression, if applicable.
required:
  - processor
  - statement
  - expression
  - process

```