doc: using ldoc to generate document site

vm-001 · Feb 5, 2024 · de683c8 · de683c8
1 parent 7dd5ae3
commit de683c8
Show file tree

Hide file tree

Showing 13 changed files with 734 additions and 25 deletions.
diff --git a/.github/workflows/sample.yml → .github/workflows/examples.yml b/.github/workflows/sample.yml → .github/workflows/examples.yml
@@ -1,4 +1,4 @@
-name: sample
+name: examples
 
 on:
   pull_request:
@@ -35,6 +35,7 @@ jobs:
         run: |
           luarocks install radix-router
 
-      - name: samples
+      - name: run examples
         run: |
-          lua samples/1-sample.lua
+          lua examples/example.lua
+          lua examples/custom-matcher.lua
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -44,10 +44,6 @@ jobs:
         run: |
           make test-coverage
 
-      - name: samples
-        run: |
-          lua samples/1-sample.lua
-
       - name: report test coverage
         if: success()
         continue-on-error: true

diff --git a/Makefile b/Makefile
@@ -21,3 +21,7 @@ bench:
 	RADIX_ROUTER_ROUTES=100000 RADIX_ROUTER_TIMES=1000000 $(CMD) benchmark/complex-variable.lua
 	RADIX_ROUTER_ROUTES=100000 RADIX_ROUTER_TIMES=10000000 $(CMD) benchmark/simple-variable-binding.lua
 	RADIX_ROUTER_TIMES=1000000 $(CMD) benchmark/github-routes.lua
+
+ldoc:
+	@rm -rf docs/*
+	@ldoc .
diff --git a/README.md b/README.md
@@ -1,10 +1,10 @@
-# Lua-Radix-Router [![Build Status](https://github.com/vm-001/lua-radix-router/actions/workflows/test.yml/badge.svg)](https://github.com/vm-001/lua-radix-router/actions/workflows/test.yml) [![Build Status](https://github.com/vm-001/lua-radix-router/actions/workflows/sample.yml/badge.svg)](https://github.com/vm-001/lua-radix-router/actions/workflows/sample.yml) [![Coverage Status](https://coveralls.io/repos/github/vm-001/lua-radix-router/badge.svg)](https://coveralls.io/github/vm-001/lua-radix-router) ![Lua Versions](https://img.shields.io/badge/Lua-%205.2%20|%205.3%20|%205.4-blue.svg)
+# Lua-Radix-Router [![Build Status](https://github.com/vm-001/lua-radix-router/actions/workflows/test.yml/badge.svg)](https://github.com/vm-001/lua-radix-router/actions/workflows/test.yml) [![Build Status](https://github.com/vm-001/lua-radix-router/actions/workflows/examples.yml/badge.svg)](https://github.com/vm-001/lua-radix-router/actions/workflows/examples.yml) [![Coverage Status](https://coveralls.io/repos/github/vm-001/lua-radix-router/badge.svg)](https://coveralls.io/github/vm-001/lua-radix-router) ![Lua Versions](https://img.shields.io/badge/Lua-%205.2%20|%205.3%20|%205.4-blue.svg)
 
 English | [中文](README.zh.md)
 
 
 
-Lua-Radix-Router is a lightweight high-performance router library written in pure Lua. It's easy to use with only two exported functions, `Router.new()` and `router:match()`. 
+Lua-Radix-Router is a lightweight high-performance router library written in pure Lua. It's easy to use with only two exported functions, `Router.new()` and `router:match()`.
 
 The router is optimized for high performance. It combines HashTable(O(1)) and Compressed Trie(or Radix Tree, O(m) where m is the length of path being searched) for efficient matching. Some of the utility functions have the LuaJIT version for better performance, and will automatically switch when running in LuaJIT. It also scales well even with long paths and a large number of routes.
 
@@ -86,7 +86,7 @@ assert(params.year == "2023")
 assert(params.format == "pdf")
 ```
 
-For more usage samples, please refer to the [/samples](/samples) directory. For more use cases, please check out https://github.com/vm-001/lua-radix-router-use-cases.
+For more usage samples, please refer to the [/examples](/examples) directory. For more use cases, please check out [lua-radix-router-use-cases](https://github.com/vm-001/lua-radix-router-use-cases).
 
 ## 📄 Methods
 
@@ -111,8 +111,8 @@ local router, err = Router.new(routes, opts)
     | trailing_slash_match | boolean | false              | whether to enable the trailing slash match behavior |
     | matcher_names        | table   | {"method", "host"} | enabled built-in macher list                        |
     | matchers             | table   | { }                | custom matcher list                                 |
-    
-    
+
+
 
 Route defines the matching conditions for its handler.
 
@@ -203,7 +203,7 @@ router.static = {
   [/api/login] = { *<table 1> }
 }
 
-              TrieNode.path       TrieNode.value                   
+              TrieNode.path       TrieNode.value
 router.trie = /                   nil
               ├─people/           nil
               │ └─{wildcard}      nil
@@ -229,7 +229,7 @@ $ make bench
 
 #### Environments
 
-- Apple MacBook Pro(M1 Pro), 32GB 
+- Apple MacBook Pro(M1 Pro), 32GB
 - LuaJIT 2.1.1700008891
 
 #### Results

diff --git a/README.zh.md b/README.zh.md
@@ -1,4 +1,4 @@
-# Lua-Radix-Router [![Build Status](https://github.com/vm-001/lua-radix-router/actions/workflows/test.yml/badge.svg)](https://github.com/vm-001/lua-radix-router/actions/workflows/test.yml) [![Coverage Status](https://coveralls.io/repos/github/vm-001/lua-radix-router/badge.svg)](https://coveralls.io/github/vm-001/lua-radix-router)
+# Lua-Radix-Router [![Build Status](https://github.com/vm-001/lua-radix-router/actions/workflows/test.yml/badge.svg)](https://github.com/vm-001/lua-radix-router/actions/workflows/test.yml) [![Build Status](https://github.com/vm-001/lua-radix-router/actions/workflows/examples.yml/badge.svg)](https://github.com/vm-001/lua-radix-router/actions/workflows/examples.yml) [![Coverage Status](https://coveralls.io/repos/github/vm-001/lua-radix-router/badge.svg)](https://coveralls.io/github/vm-001/lua-radix-router) ![Lua Versions](https://img.shields.io/badge/Lua-%205.2%20|%205.3%20|%205.4-blue.svg)
 
 [English](README.md) | 中文 (Translated by ChatGPT)
 

diff --git a/config.ld b/config.ld
@@ -0,0 +1,6 @@
+project = 'Radix-Router'
+description = 'A lightweight high-performance and radix tree based router for Lua/LuaJIT.'
+full_description = ''
+examples = { './examples' }
+file='./src/router.lua'
+dir = 'docs'
diff --git a/docs/examples/custom-matcher.lua.html b/docs/examples/custom-matcher.lua.html
@@ -0,0 +1,110 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+<head>
+    <title>Reference</title>
+    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
+</head>
+<body>
+
+<div id="container">
+
+<div id="product">
+	<div id="product_logo"></div>
+	<div id="product_name"><big><b></b></big></div>
+	<div id="product_description"></div>
+</div> <!-- id="product" -->
+
+
+<div id="main">
+
+
+<!-- Menu -->
+
+<div id="navigation">
+<br/>
+<h1>Radix-Router</h1>
+
+
+
+
+
+<h2>Examples</h2>
+<ul class="nowrap">
+  <li><strong>custom-matcher.lua</strong></li>
+  <li><a href="../examples/example.lua.html">example.lua</a></li>
+</ul>
+<h2>Modules</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">radix-router</a></li>
+</ul>
+
+</div>
+
+<div id="content">
+
+    <h2>custom-matcher.lua</h2>
+<pre>
+<span class="keyword">local</span> Router = <span class="global">require</span> <span class="string">"radix-router"</span>
+
+<span class="keyword">local</span> ip_matcher = {
+  process = <span class="keyword">function</span>(route)
+    <span class="comment">-- builds a table for O(1) access
+</span>    <span class="keyword">if</span> route.ips <span class="keyword">then</span>
+      <span class="keyword">local</span> ips = {}
+      <span class="keyword">for</span> _, ip <span class="keyword">in</span> <span class="global">ipairs</span>(route.ips) <span class="keyword">do</span>
+        ips[ip] = <span class="keyword">true</span>
+      <span class="keyword">end</span>
+      route.ips = ips
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>,
+  match = <span class="keyword">function</span>(route, ctx, matched)
+    <span class="keyword">if</span> route.ips <span class="keyword">then</span>
+      <span class="keyword">local</span> ip = ctx.ip
+      <span class="keyword">if</span> <span class="keyword">not</span> route.ips[ip] <span class="keyword">then</span>
+        <span class="keyword">return</span> <span class="keyword">false</span>
+      <span class="keyword">end</span>
+      <span class="keyword">if</span> matched <span class="keyword">then</span>
+        matched[<span class="string">"ip"</span>] = ip
+      <span class="keyword">end</span>
+    <span class="keyword">end</span>
+    <span class="keyword">return</span> <span class="keyword">true</span>
+  <span class="keyword">end</span>
+}
+
+<span class="keyword">local</span> opts = {
+  matchers = { ip_matcher }, <span class="comment">-- register custom ip_matcher
+</span>  matcher_names = { <span class="string">"method"</span> }, <span class="comment">-- host is disabled
+</span>}
+
+<span class="keyword">local</span> router = Router.<span class="function-name">new</span>({
+  {
+    paths = { <span class="string">"/"</span> },
+    methods = { <span class="string">"GET"</span>, <span class="string">"POST"</span> },
+    ips = { <span class="string">"127.0.0.1"</span>, <span class="string">"127.0.0.2"</span> },
+    handler = <span class="string">"1"</span>,
+  },
+  {
+    paths = { <span class="string">"/"</span> },
+    methods = { <span class="string">"GET"</span>, <span class="string">"POST"</span> },
+    ips = { <span class="string">"192.168.1.1"</span>, <span class="string">"192.168.1.2"</span> },
+    handler = <span class="string">"2"</span>,
+  }
+}, opts)
+<span class="global">assert</span>(<span class="string">"1"</span> == router:<span class="function-name">match</span>(<span class="string">"/"</span>, { method = <span class="string">"GET"</span>, ip = <span class="string">"127.0.0.2"</span> }))
+<span class="keyword">local</span> matched = {}
+<span class="global">assert</span>(<span class="string">"2"</span> == router:<span class="function-name">match</span>(<span class="string">"/"</span>, { method = <span class="string">"GET"</span>, ip = <span class="string">"192.168.1.2"</span> }, <span class="keyword">nil</span>, matched))
+<span class="global">print</span>(matched.method) <span class="comment">-- GET
+</span><span class="global">print</span>(matched.ip) <span class="comment">-- 192.168.1.2</span></pre>
+
+
+</div> <!-- id="content" -->
+</div> <!-- id="main" -->
+<div id="about">
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2024-02-05 16:00:23 </i>
+</div> <!-- id="about" -->
+</div> <!-- id="container" -->
+</body>
+</html>
diff --git a/docs/examples/example.lua.html b/docs/examples/example.lua.html
@@ -0,0 +1,96 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+<head>
+    <title>Reference</title>
+    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
+</head>
+<body>
+
+<div id="container">
+
+<div id="product">
+	<div id="product_logo"></div>
+	<div id="product_name"><big><b></b></big></div>
+	<div id="product_description"></div>
+</div> <!-- id="product" -->
+
+
+<div id="main">
+
+
+<!-- Menu -->
+
+<div id="navigation">
+<br/>
+<h1>Radix-Router</h1>
+
+
+
+
+
+<h2>Examples</h2>
+<ul class="nowrap">
+  <li><a href="../examples/custom-matcher.lua.html">custom-matcher.lua</a></li>
+  <li><strong>example.lua</strong></li>
+</ul>
+<h2>Modules</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">radix-router</a></li>
+</ul>
+
+</div>
+
+<div id="content">
+
+    <h2>example.lua</h2>
+<pre>
+<span class="keyword">local</span> Router = <span class="global">require</span> <span class="string">"radix-router"</span>
+<span class="keyword">local</span> router, err = Router.<span class="function-name">new</span>({
+  {
+    paths = { <span class="string">"/foo"</span>, <span class="string">"/foo/bar"</span>, <span class="string">"/html/index.html"</span> },
+    handler = <span class="string">"1"</span> <span class="comment">-- handler can be any non-nil value. (e.g. boolean, table, function)
+</span>  },
+  {
+    <span class="comment">-- variable path
+</span>    paths = { <span class="string">"/users/{id}/profile-{year}.{format}"</span> },
+    handler = <span class="string">"2"</span>
+  },
+  {
+    <span class="comment">-- prefix path
+</span>    paths = { <span class="string">"/api/authn/{*path}"</span> },
+    handler = <span class="string">"3"</span>
+  },
+  {
+    <span class="comment">-- methods
+</span>    paths = { <span class="string">"/users/{id}"</span> },
+    methods = { <span class="string">"POST"</span> },
+    handler = <span class="string">"4"</span>
+  }
+})
+<span class="keyword">if</span> <span class="keyword">not</span> router <span class="keyword">then</span>
+  <span class="global">error</span>(<span class="string">"failed to create router: "</span> .. err)
+<span class="keyword">end</span>
+
+<span class="global">assert</span>(<span class="string">"1"</span> == router:<span class="function-name">match</span>(<span class="string">"/html/index.html"</span>))
+<span class="global">assert</span>(<span class="string">"2"</span> == router:<span class="function-name">match</span>(<span class="string">"/users/100/profile-2023.pdf"</span>))
+<span class="global">assert</span>(<span class="string">"3"</span> == router:<span class="function-name">match</span>(<span class="string">"/api/authn/token/genreate"</span>))
+<span class="global">assert</span>(<span class="string">"4"</span> == router:<span class="function-name">match</span>(<span class="string">"/users/100"</span>, { method = <span class="string">"POST"</span> }))
+
+<span class="comment">-- parameter binding
+</span><span class="keyword">local</span> params = {}
+router:<span class="function-name">match</span>(<span class="string">"/users/100/profile-2023.pdf"</span>, <span class="keyword">nil</span>, params)
+<span class="global">assert</span>(params.year == <span class="string">"2023"</span>)
+<span class="global">assert</span>(params.format == <span class="string">"pdf"</span>)</pre>
+
+
+</div> <!-- id="content" -->
+</div> <!-- id="main" -->
+<div id="about">
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2024-02-05 16:00:23 </i>
+</div> <!-- id="about" -->
+</div> <!-- id="container" -->
+</body>
+</html>