feat: new funcs to see variables

New function and new data file from running the converter.

Author: ryepup

examples/autocomplete/index.ts

@@ -1,4 +1,9 @@
-import { getDirectives, Format, Directive } from '@nginx/reference-lib'
+import {
+  getDirectives,
+  Format,
+  Directive,
+  getVariables,
+} from '@nginx/reference-lib'
 type autocomplete = {
   /** name of the NGINX module */
   m: string
@@ -10,10 +15,10 @@ type autocomplete = {
    * nginx config */
   v?: string
   /** markdown CSV for valid contexts */
-  c: string
+  c?: string
   /** markdown-formatted syntax specifications, including directive name.
    * Multiple syntaxes are seperated by newlines */
-  s: string
+  s?: string
 }
 
 function toAutocomplete(d: Directive): autocomplete {
@@ -32,5 +37,10 @@ function toAutocomplete(d: Directive): autocomplete {
   return ret
 }
 
-const formatted = getDirectives(Format.Markdown).map(toAutocomplete)
-console.log(JSON.stringify(formatted, undefined, 4))
+const directives = getDirectives(Format.Markdown).map(toAutocomplete)
+const variables = getVariables(Format.Markdown).map((v) => ({
+  m: v.module,
+  n: v.name,
+  d: v.description,
+}))
+console.log(JSON.stringify(directives.concat(variables), undefined, 4))

reference-lib/index.ts

@@ -1,13 +1,19 @@
 import reference from './src/reference.json'
 
 export interface Directive {
-    name: string
-    module: string
-    description: string
-    syntax: string[]
-    contexts: string[]
-    isBlock: boolean
-    default: string
+  name: string
+  module: string
+  description: string
+  syntax: string[]
+  contexts: string[]
+  isBlock: boolean
+  default: string
+}
+
+export interface Variable {
+  name: string
+  module: string
+  description: string
 }
 
 export enum Format {
@@ -41,37 +47,63 @@ for (const modules of reference.modules) {
  * Returns all the nginx directives
  *
  *  @param: format: format of the return type HTML or markdown
- *
  *  @return: an array of Directives
  */
-export function getDirectives(format=Format.HTML): Directive[] {
-    const directives = reference.modules.flatMap((m) =>
-      m.directives.map((d) => ({...d, module: m.name})))
-    .map ((d) => ({
-        name: d.name,
-        module: d.module,
-        description: format === Format.HTML ? d.description_html : d.description_md,
-        syntax: format === Format.HTML ? d.syntax_html : d.syntax_md,
-        contexts: d.contexts,
-        isBlock: d.isBlock,
-        default: d.default
-    } as Directive))
-    return directives
+export function getDirectives(format = Format.HTML): Directive[] {
+  const directives = reference.modules
+    .flatMap((m) => m.directives.map((d) => ({ ...d, module: m.name })))
+    .map(
+      (d) =>
+        ({
+          name: d.name,
+          module: d.module,
+          description:
+            format === Format.HTML ? d.description_html : d.description_md,
+          syntax: format === Format.HTML ? d.syntax_html : d.syntax_md,
+          contexts: d.contexts,
+          isBlock: d.isBlock,
+          default: d.default,
+        } as Directive)
+    )
+  return directives
+}
+
+/**
+ * Returns all variables defined by any moduled
+ *
+ *  @param: format: format of the return type HTML or markdown
+ *  @return: an array of Variables
+ */
+export function getVariables(format = Format.HTML): Variable[] {
+  return reference.modules.flatMap(
+    (m) =>
+      m.variables?.map((v) => ({
+        name: v.name,
+        description:
+          format === Format.HTML ? v.description_html : v.description_md,
+        module: m.name,
+      })) ?? []
+  )
 }
 
 /**
- * Returns the description corresponding to the directive name
+ * Returns the description corresponding to the directive or variable name
  *
  *  @param: directive: directive name to find
  *  @param: module: optional name of module
  *  @param: format: format of the return type HTML or markdown
  *
  *  @return: a string containing the description of the directive in xml or markdown format
  */
-export function find(directive: string, module: string | undefined, format=Format.HTML): string | undefined {
-  const data =
-    module
-      ? refDirectives.get(directive)?.find((d) => d.module.toUpperCase() === module.toUpperCase())
-      : refDirectives.get(directive)?.at(0)
-  return (format === Format.HTML ? data?.description_html : data?.description_md)
+export function find(
+  directive: string,
+  module: string | undefined,
+  format = Format.HTML
+): string | undefined {
+  const data = module
+    ? refDirectives
+        .get(directive)
+        ?.find((d) => d.module.toUpperCase() === module.toUpperCase())
+    : refDirectives.get(directive)?.at(0)
+  return format === Format.HTML ? data?.description_html : data?.description_md
 }

reference-lib/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nginx/reference-lib",
-  "version": "1.0.14",
+  "version": "1.1.0",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

reference-lib/src/__mocks__/reference_mock.json

@@ -1,26 +1,29 @@
-{"modules": [
+{
+  "modules": [
     {
       "id": "/en/docs/http/ngx_http_access_module.html",
       "name": "ngx_http_access_module",
       "directives": [
         {
           "name": "allow",
           "default": "",
-          "contexts": [
-            "http",
-            "server",
-            "location",
-            "limit_except"
-          ],
-          "syntax_md": [
-            "*`address`* | *`CIDR`* | `unix:` | `all`"
-          ],
+          "contexts": ["http", "server", "location", "limit_except"],
+          "syntax_md": ["*`address`* | *`CIDR`* | `unix:` | `all`"],
           "syntax_html": [
             "<p><em><code>address</code></em> | <em><code>CIDR</code></em> | <code>unix:</code> | <code>all</code></p>\n"
           ],
           "isBlock": false,
           "description_md": "Allows access for the specified network or address.",
           "description_html": "\u003cp\u003eAllows access for the specified network or address\u003c/p\u003e"
-        }]
-    }]
-  }
+        }
+      ],
+      "variables": [
+        {
+          "name": "$gzip_ratio",
+          "description_md": "achieved compression ratio, computed as the ratio between the\noriginal and compressed response sizes.",
+          "description_html": "<p>achieved compression ratio, computed as the ratio between the\noriginal and compressed response sizes.</p>\n"
+        }
+      ]
+    }
+  ]
+}