💡 Project: Developing a Basic Web Server Route Matcher

A core task for any web server is routing: mapping an incoming URL path like /users/123 to the correct application logic (a "handler") and extracting any dynamic parameters (like the user ID 123). This project will guide you through building a simple but powerful route matcher using the declarative patterns of the uCalc Transformer.

The Goal: A Simple Routing DSL

We'll create a Domain-Specific Language (DSL) for defining routes that is common in modern web frameworks like Express.js or Flask. Placeholders for dynamic segments are enclosed in curly braces.

• /users/{id}
• /products/{category}/{id}

The Strategy: Transformer Rules

The core idea is to treat routing as a text transformation problem. We'll take an incoming URL path and transform it into a string that represents the action to take.

• Input: /users/42
• Rule: FromTo("/users/{id}", "Handler: UserProfile, id: {id}")
• Output: "Handler: UserProfile, id: 42"

The application can then easily parse this output string to call the correct function with the extracted parameters.

Step 1: Setting Up the Transformer

First, we need a Transformer instance. This will be our router. We will define all our route patterns on this object.

using uCalcSoftware;

var uc = new uCalc();

using (var router = new uCalc.Transformer()) {
   // ... rules will go here ...
}

Step 2: Defining the Routes

Each route is a FromTo rule. The pattern matches the URL structure, and the replacement string defines the output.

• Static Route: A simple, fixed path. router.FromTo("/about", "Handler: AboutPage");

• Dynamic Route: A path with one or more variable placeholders. router.FromTo("/users/{id}", "Handler: UserProfile, id: {id}");

Step 3: Precedence Matters (LIFO)

What happens if you have two similar routes, like /users/new and /users/{id}? A request for /users/new could technically match both patterns. To resolve this, the Transformer uses a LIFO (Last-In, First-Out) precedence rule: the most recently defined rule is checked first.

Therefore, you must define your most specific rules last to give them higher priority.

using uCalcSoftware;

var uc = new uCalc();

// General rule defined first (lower priority)
router.FromTo("/users/{id}", "Handler: UserProfile, id: {id}");

// Specific rule defined last (higher priority)
router.FromTo("/users/new", "Handler: CreateUserPage");

Step 4: Matching an Incoming URL

To process a request, simply call Transform() on the incoming URL string. If the result is different from the original URL, a match was found. If it's unchanged, it's a "404 Not Found."

⚖️ Why uCalc? (Comparative Analysis)

• vs. Regex: Building a router with regular expressions is common but can be complex. Each route requires a carefully crafted regex, and managing their precedence can be tricky. uCalc's patterns are more readable (/users/{id} vs. /users/(\w+)), and the LIFO precedence is a clear, built-in system.
• vs. Manual String Splitting: Splitting the URL by / is brittle and doesn't handle complex patterns or constraints well.

uCalc provides a declarative, token-aware, and extensible way to define a routing system that is both powerful and easy to maintain.