OutlineAlgorithm 1.0.0

OutlineAlgorithm

OutlineAlgorithm is a library designed to process a sequence of headings (e.g., h1, h2, h3) with explicit nesting levels into a hierarchical tree structure. This library is compatible with both F# and C#, making it accessible to developers from both ecosystems.

The library operates in two stages:

1. Token and Parenthesis Generation: The input sequence of headings is first converted into a sequence of tokens and parentheses. This intermediate representation captures the nesting structure of the headings.
2. Tree Construction: The sequence of tokens and parentheses is then parsed to construct a hierarchical tree structure.

This two-step process allows the library to handle cases where the nesting levels change abruptly, such as skipping levels (e.g., from h2 to h5) or returning to a shallower level (e.g., from h5 to h2).

Whether you're working in F# or C#, OutlineAlgorithm provides a straightforward API to process documents with deeply nested structures, such as HTML or OOXML documents, efficiently.

Features

• Token and Parenthesis Parsing: Converts a sequence of tokens and parentheses into a structured tree.
• Handles Deep Nesting: Automatically inserts dummy tokens (DummyToken) to handle cases where the hierarchy deepens significantly (e.g., jumping from level H2 to H4).
• Inspired by Lisp's read Function: Implements functionality similar to Lisp's read function, which parses S-expressions into tree-like structures.

Key Functions

1. CreateTokenOrParenthesisSeq

   • Converts a sequence of headings (e.g., H1, H2, H3) into a sequence of tokens and parentheses based on a ranking function.
   • This function ensures that the nesting structure is accurately represented, even when the hierarchy deepens or skips levels (e.g., jumping from H2 to H4).
   • Example:

     var input = new List<string> { "H1", "H2", "H4", "H3" };
     Func<string, int> getRank = element => element switch
     {
         "H1" => 1,
         "H2" => 2,
         "H3" => 3,
         "H4" => 4,
         _ => 0
     };
     var tokenSeq = Interop.CreateTokenOrParenthesisSeq(input, getRank);
     

2. ParseToTree

   • Parses a sequence of tokens and parentheses into a hierarchical tree structure.
   • This function processes the intermediate token sequence generated by CreateTokenOrParenthesisSeq and constructs a tree (InteropTree<T>), which can be easily traversed or visualized.
   • Example:

     var trees = Interop.ParseToTree(tokenSeq);
     foreach (var tree in trees)
     {
         PrintTree(tree, 0);
     }
     
     static void PrintTree<T>(InteropTree<T> tree, int level)
     {
         if (tree.Value == null)
         {
             Console.WriteLine(new string(' ', level * 2) + "@");
         }
         else
         {
             Console.WriteLine(new string(' ', level * 2) + tree.Value);
         }
         foreach (var child in tree.Children)
         {
             PrintTree(child, level + 1);
         }
     }
     

Example Usage

C# Example

The following example demonstrates how to use the library in C# to process a sequence of tokens and construct a tree structure:

using Microsoft.FSharp.Core;
using OutlineAlgorithm.Interop;
using System;

class Program
{
    static void Main()
    {
        // Input sequence
        var input = new List<string> { "H1", "H2", "H5", "H3", "H6" };

        // Rank function
        Func<string, int> getRank = element => element switch
        {
            "H1" => 1,
            "H2" => 2,
            "H3" => 3,
            "H4" => 4,
            "H5" => 5,
            "H6" => 6,
            _ => 0
        };

        // Generate token and parenthesis sequence
        var tokenSeq = Interop.CreateTokenOrParenthesisSeq(input, getRank);

        // Parse to tree
        var trees = Interop.ParseToTree(tokenSeq); // ParseToTree returns an array of InteropTree<T>

        // Print each tree in the array
        foreach (var tree in trees)
        {
            PrintTree(tree, 0);
        }
    }

    static void PrintTree<T>(InteropTree<T> tree, int level)
    {
        var value = tree.ValueOrDefault; // Use ValueOrDefault to get the value or default
        if (value == null)
        {
            Console.WriteLine(new string(' ', level * 2) + "@");
        }
        else
        {
            Console.WriteLine(new string(' ', level * 2) + value);
        }

        foreach (var child in tree.Children)
        {
            PrintTree(child, level + 1);
        }
    }
}
}

F# Example

The following example demonstrates how to use the library in F# to process a sequence of tokens and construct a tree structure:

open System
open OutlineAlgorithm.Interop

[<EntryPoint>]
let main argv =
    // Input sequence
    let input = ["H1"; "H2"; "H5"; "H3"; "H6"]

    // Rank function
    let getRank (element: string) =
        match element with
        | "H1" -> 1
        | "H2" -> 2
        | "H3" -> 3
        | "H4" -> 4
        | "H5" -> 5
        | "H6" -> 6
        | _ -> 0

    // Convert F# function to System.Func
    let rankFunc = Func<string, int>(getRank)

    // Generate token and parenthesis sequence using Interop
    let tokenSeq = Interop.CreateTokenOrParenthesisSeq(input, rankFunc)

    // Parse to tree using Interop
    let trees = Interop.ParseToTree(tokenSeq)

    // Print each tree in the sequence
    let rec printTree (tree: InteropTree<string>) (level: int) =
        match tree.Value with
        | None ->
            printfn "%s@" (String.replicate (level * 2) " ")
        | Some(v)  ->
            printfn "%s%s" (String.replicate (level * 2) " ") v
        for child in tree.Children do
            printTree child (level + 1)

    for tree in trees do
        printTree tree 0

    0 // Return an integer exit code

Output

Both versions provide the same result:

H1
  H2
    @
      @
        H5
    H3
      @
        @
          H6

Installation

This project is written in F#. To set it up, follow these steps:

1. Clone the repository:

2. Restore dependencies (requires .NET SDK):

API documentation

See OutlineAlgorithm.

Contributing

Contributions are welcome! If you encounter any issues or have feature requests, please open an issue. Pull requests are also appreciated.

License

This project is licensed under the MIT License. See the LICENSE file for details.