npm package: @je-es/parser
Description: A robust parser that performs syntactic analysis and constructs an Abstract Syntax Tree (AST).
Author: Maysara Elshewehy
Latest version: 0.1.7

<!----------------------------------- BEG ----------------------------------->
<br>
<div align="center">
    <p>
        <img src="./assets/img/logo.png" alt="parser" style="" height="50" />
    </p>
</div>


<div align="center">
    <p align="center" style="font-style:italic; color:gray;">
        A robust tool for syntactic analysis.<br>
        It consumes tokens generated by a lexer and constructs an Abstract Syntax Tree (AST) for interpretation or compilation.
        <br>
    </p>
    <img src="https://img.shields.io/badge/Version-0.1.7-black"/>
    <a href="https://github.com/je-es"><img src="https://img.shields.io/badge/Part_of-@je--es-black"/></a>
    <a href="https://github.com/kemet-lang"><img src="https://img.shields.io/badge/Built_for-@kemet--lang-black"/></a>
</div>


<div align="center">
    <img src="./assets/img/line.png" alt="line" style="display: block; margin-top:20px;margin-bottom:20px;width:500px;"/>
    <br>
</div>

<!--------------------------------------------------------------------------->



<!----------------------------------- --- ----------------------------------->

- ### Install

    ```bash
    npm install @je-es/parser
    ```

    ```ts
    import * as Parser from "@je-es/parser";
    ```

    <div align="center"> <br> <img src="./assets/img/line.png" alt="line" style="display: block; margin-top:20px;margin-bottom:20px;width:500px;"/> <br> </div>

- ### Usage

    ```ts
    // [1] create parser rules
    const parser_rules : Parser.Rules = [

        Parser.createRule('Root',
            Parser.oneOrMore(Parser.rule('Stmt')),
            {
                build: (data: Parser.Result) => {
                    const arr   = data.getRepeatResult()!;
                    const stmts = arr.map((x) => x.getCustomData()! as AST.StmtNode);
                    return Parser.Result.createAsCustom('passed', 'root', stmts, data.span);
                }
            }
        ),

        Parser.createRule('Ident',
            Parser.token('ident'),
            {
                build: (data: Parser.Result) => {
                    const identResult = data.getTokenData()!;

                    return Parser.Result.createAsCustom('passed', 'ident',
                        AST.IdentNode.create( identResult.span, identResult.value!, false),
                        data.span
                    );
                },

                errors: [ Parser.error(0, "Expected identifier") ]
            }
        ),

        // Include required rules
        ...Type,
        ...Expr,
        ...Stmt,
    ];
    ```

    ```ts
    // [2] create parser settings
    const parser_settings : Parser.ParserSettings = {
        startRule       : 'Root',
        errorRecovery   : { mode: 'resilient', maxErrors: 99 },
        ignored         : ['ws', 'comment'],
        debug           : 'off',
        maxDepth        : 9999,
        maxCacheSize    : 1024, // 1GB
    };
    ```

    ```ts
    // [3] parse tokens using your rules
    const parser_result = Parser.parse([<tokens>], parser_rules, parser_settings);

    // Hint: to get tokens use `@je-es/lexer`
    ```

    <div align="center"> <br> <img src="./assets/img/line.png" alt="line" style="display: block; margin-top:20px;margin-bottom:20px;width:500px;"/> <br> </div>


- ### Related

    - #### [kemet-lang (MVP)](https://github.com/kemet-lang/.github/blob/main/profile/roadmap/MVP.md)

        > #### 1. [@je-es/lexer](https://github.com/je-es/lexer)

        > #### 2. [`@je-es/parser`](https://github.com/je-es/parser)

        > #### 3. [@je-es/syntax](https://github.com/je-es/syntax)

        > #### 4. [@je-es/ast](https://github.com/je-es/ast)

        > #### 5. [@je-es/ast-analyzer](https://github.com/je-es/ast-analyzer)

        > #### 6. [@je-es/project](https://github.com/je-es/project)

        > #### 7. [@je-es/lsp](https://github.com/je-es/lsp)

        > #### 8. [@je-es/codegen](https://github.com/je-es/codegen)

        > #### 9. [@je-es/compiler](https://github.com/je-es/compiler)



<!--------------------------------------------------------------------------->



<!----------------------------------- END ----------------------------------->

<br>
<div align="center">
    <img src="./assets/img/line.png" alt="line" style="display: block; margin-top:20px;margin-bottom:20px;width:500px;"/>
</div>
<br>

<div align="center">
    <a href="https://github.com/maysara-elshewehy">
        <img src="https://img.shields.io/badge/by-Maysara-blue"/>
    </a>
</div>

<!-------------------------------------------------------------------------->