add ryuji and saki docs

2023-08-02 21:29:20 -07:00
parent d8bfe2c5ed
commit 192331d27f
4 changed files with 320 additions and 3 deletions
--- a/posts/meta.md
+++ b/posts/meta.md
@@ -34,7 +34,7 @@ All the standard Markdown are supported (headers, bolds, italics, images, links,
 It also has a very cool warnings feature, which isn't used in this project, but can be seen in action if you use the [Makoto Web Editor](https://makoto.prussia.dev).

 ### Ryuji
-Ryuji is a simple templating system that supports `if` statements, `for` loops, components, and inserting variables. It isn't quite as fully featured as Jinja/Nunjucks, but on the upside, Ryuji is around just 200 lines of code, and worked very well for my usecase. I think it's pretty cool.
+Ryuji is a simple templating system that supports `if` statements, `for` loops, components, and inserting variables. It isn't quite as fully featured as Jinja/Nunjucks, but on the upside, Ryuji is less than 280 lines of code, and worked very well for my usecase. I think it's pretty cool.

 Here's a quick overview of the syntax:

--- a/posts/ryuji_docs.md
+++ b/posts/ryuji_docs.md
@@ -1 +1,207 @@
-The Ryuji docs are under construction. Beep beep beep.
+Ryuji is a templating language written in less than 280 lines of code. There are no dependencies besides the builtin Node.js module `fs`. If that is an issue (eg, running in a browser environment), it should be very straightforward to remove the dependency by deleting the `render_template` function and using the `render` function directory.
+
+# Syntax Docs
+
+Ryuji syntax is typically in the format `[[ something ]]` or `[[ some:thing ]]` (with more `:`s if necessary). The spaces matter! Specifically, Ryuji checks for syntax using the regex statement: `/\[\[ [a-zA-Z0-9.:\-_!]+ \]\]/g`.
+
+## Variables
+```html
+<p>Hi [[ employee.name ]],</p>
+<p>You may recently heard some distressing news about your colleague Dave.</p>
+<p>Please rest assured that these reports are <b>false and exaggerated</b>. Although he may be charged with [[ current_manslaughter_count ]] counts of manslaughter, we believe that these charges will be dismissed.</p>
+<p>[[ corporate_slogan ]]</p>
+```
+
+## Non-HTML Escaped Variables
+```html
+<div>
+  [[ html:biography ]]
+</div>
+```
+
+## For Loop Statements
+```html
+<li>
+  [[ for:trees ]]
+    <li>There is a tree.</li>
+  [[ endfor ]]
+</li>
+```
+
+```html
+<ul>
+  [[ for:trees:tree ]]
+    <li>There is a [[ tree.type ]] tree that is [[ tree.height ]] metres tall.</li>
+  [[ endfor ]]
+</ul>
+```
+
+```html
+<ul>
+  [[ for:trees:tree:index ]]
+  <!--index starts at zero, but you get the point-->
+    <li>[[ index ]]. There is a [[ tree.type ]] tree that is [[ tree.height ]] metres tall.</li>
+  [[ endfor ]]
+</ul>
+```
+
+```html
+<ul>
+  [[ for:trees:tree:index:max ]]
+    <!--index starts at zero, and max is length-1 (the max index), but you get the point-->
+    <li>[[ index ]]/[[ max ]] There is a [[ tree.type ]] tree that is [[ tree.height ]] metres tall.</li>
+  [[ endfor ]]
+</ul>
+```
+
+## If Truthy Statements
+```html
+[[ if:trees_are_real ]]
+  <ul>
+    [[ for:trees:tree ]]
+      <li>There is a [[ tree.type ]] tree that is [[ tree.height ]] metres tall. [[ if:tree.old ]]Be warned that this tree is very old and may fall down.[[ endif ]]</li>
+    [[ endfor ]]
+  </ul>
+[[ endif ]]
+```
+
+## If Comparison Statements
+```html
+[[ if:user.lactose_intolerant:user.vegan ]]
+  <p>We don't think you should order the cheeseburger.</p>
+[[ endif ]]
+```
+
+## If Not Comparison Statements
+```html
+[[ if:user.lactose_intolerant:user.vegan ]]
+  <p>We don't think you should order the cheeseburger.</p>
+[[ endif ]]
+```
+
+## Components
+```html
+[[ component:nav-bar ]]
+<p>Blah blah blah blah.</p>
+```
+
+*templates/components/navbar.html*
+
+```html
+<div>
+  <a href="/">Home</a> - <a id="donate-link" href="/donate">Donate to Dave's Bail Fund</a>
+</div>
+<style>
+  #donate-link {
+    color: red;
+  }
+</style>
+```
+
+```html
+[[ for trees:tree ]]
+  [[ component:tree-info ]]
+[[ endfor ]]
+```
+
+*templates/components/tree-info.html*
+
+```html
+<img src="[[ tree.picture ]]"/>
+<h2>[[ tree.type ]], [[ tree.age ]] years old.</h2>
+<p>Favourite song: [[ tree.favourite_song ]], Likes Dave: [[ tree.likes_dave ]]</p>
+```
+
+## Notes
+- For loops can be nested.
+- Components can have other components inside them (but there is a depth limit of 4 or 5 or 6 nested within each other, I forgot).
+
+# API/Library Docs
+
+## Class: Renderer
+
+### `constructor`
+Creates an instance of the `Renderer` class.
+
+**Parameters:**
+- `templates_dir` (`string`): Templates directory.
+- `components_dir` (`string`): Components directory.
+- `file_extension` (`\`.${string}\``, optional, default is `".html"`): File extension of templates.
+
+### `render`
+Render a template given template contents and variables.
+
+**Parameters:**
+- `template_contents` (`string`): Content of template.
+- `vars` (`any`, optional but highly recommended): Dictionary/object of variables to render template with.
+- `recursion_layer` (`number`, optional, defaults to `0`): Used internally to prevent infinite loops when templates circularly refer to each other.
+
+**Returns:** `string` (the rendered template)
+
+### `render_template`
+Render a template given the template name. Basically, gets the contents of the template and then calls `render`.
+
+**Parameters:**
+- `template_name` (`string`): The name of the template.
+- `vars` (`any`, optional but highly recommended): Dictionary/object of variables to render template with.
+- `recursion_layer` (`number`, optional, defaults to `0`): Used internally to prevent infinite loops when templates circularly refer to each other.
+
+**Returns:** `string` (the rendered template)
+
+### `remove_empty_lines` (static)
+Removes empty lines from text.
+
+**Parameters:**
+- `text` (`string`): Text to rid empty lines from.
+
+### `concat_path` (static)
+Adds two paths together. Mostly intended for internal use only.
+
+**Parameters:**
+- `path1` (`string`): First path.
+- `path2` (`string`): Second path.
+
+**Returns:** `string` (`path1` added to `path2`)
+
+### `sanitize` (static)
+Sanitizes text to make sure it cannot render as HTML. It replaces "<" with the HTML entity "&\lt;" and ">" with the HTML entity "&\gt;". Automatically done to 
+
+**Parameters:**
+- `non_html` (`string`): The text to sanitize.
+
+**Returns:** `string` (the sanitized text)
+
+### `check_var_name_legality` (static)
+Checks to make sure a variable name is legal. Intended for internal use.
+
+**Parameters:**
+- `var_name` (`string`): The variable name to check.
+- `dot_allowed` (`boolean`, optional, default is `true`): Whether "." is allowed in the variable name.
+
+**Returns:** `boolean` (`true` is variable name is legal, `false` otherwise)
+
+### `get_var` (static)
+Gets the value of a variable, errors if variable undefined. Intended for internal use.
+
+**Parameters:**
+- `var_name` (`string`): Name of variable.
+- `vars` (`any`, optional but highly recommended): Dictionary/object of variables to get value from.
+
+**Returns:** `any` (the value of the variable)
+
+### Properties
+- `templates_dir`: `string`
+- `components_dir`: `string`
+- `file_extension`: `\`.${string}\`` (see in Types/Interfaces/Consts `file_extension`)
+
+## Types/Interfaces/Consts
+These are exported, but there is no real use for them (outside of the module obviously), with the possible exception of writing an extension to Ryuji. Feel free to skip this section.
+
+- `const SYNTAX_REGEX`: Regex to search for Ryuji syntax.
+- `type file_extension`: Typescript type `\`.${string}\``, that represents... file extensions. Shocker.
+- `interface ForLoopInfo`: Used internally for Ryuji's for loops.
+
+# Usage Examples
+Check Ryuji's [tests](https://github.com/jetstream0/hedgeblog/blob/master/tests.ts) for more examples.
+
+There is a real world example in [hedgeblog's code](https://github.com/jetstream0/hedgeblog). For a syntax example, look in the `templates` [directory](https://github.com/jetstream0/hedgeblog/tree/master/templates), or an API example in `saki.ts` and `index.ts`.
--- a/posts/saki_docs.md
+++ b/posts/saki_docs.md
@@ -1 +1,112 @@
-The Ryuji docs are under construction. Vroom vroom. Oh no daves operating the bulldozer drunk again gimme a second
+Saki is a very simple static build system, written in Typescript. There are no dependencies besides the builtin Node.js modules `fs` and `path`.
+
+# Class: Builder
+
+## `constructor`
+Creates an instance of the `Builder` class.
+
+**Parameters:**
+- `build_dir` (`string`, optional, default is `"/build"`): The directory to output the build to.
+
+## `copy_folder` (static)
+Copies a directory to another directory. Used internally in `serve_static_folder`, there is probably no need to use this.
+
+**Parameters:**
+- `folder_path` (`string`): Path to directory that should be copied.
+- `dest_path` (`string`): Path to directory to copy to.
+
+## `serve_static_folder`
+Adds a static folder to the build directory, meaning that it will be served.
+
+**Parameters:**
+- `static_dir` (`string`): The path to the static directory to serve
+- `dest_path` (`string`, optional, default is `"/"`): The path that the static directory should be served under. For example, if the static directory has a file "example.png", if the `dest_path` is `"/"`, the file will be written to `"/<build dir>/example.png"`, and the url for the file will be `/example.png`. If the `dest_path` is `"/files"`, the file will be written to `"/<build dir>/files/example.png"`, and the url for the file will be `/files/example.png`.
+
+## `serve_content`
+Write HTML to a file in the build directory. In most cases, it is probably more convenient to use `serve_file`, `serve_template` or `serve_templates` instead.
+
+**Parameters:**
+- `content` (`string`): The HTML content.
+- `serve_path` (`string`): The path to serve the file under, inside the build directory. If the `serve_path` does **not** end with ".html", the content will be written to an `index.html` file inside the path as a directory, ensuring that the HTML will be served under that url. For example, if `serve_path` is `"/burgers"`, the HTML will be written to `"/<build dir>/burgers/index.html"`, and can be accessed at the url `/burgers`.
+
+## `serve_file`
+Write a (non-HTML) file to the build directory. If serving multiple non-HTML files, putting those files into one directory and using `serve_static_folder` is probably a good idea.
+
+**Parameters:**
+- `file_path` (`string`): Path to the file.
+- `serve_path` (`string`): The path to serve the file under, inside the build directory.
+
+## `serve_template`
+Render a (probably [Ryuji](/posts/ryuji-docs)) template, and write the result to the build directory.
+
+**Parameters:**
+- `renderer` (`Renderer`): Most likely the Ryuji renderer.
+- `serve_path` (`string`): The path to serve the file under, inside the build directory.
+- `template_name` (`string`): Name of the template to render (see Ryuji docs for more information).
+- `vars` (`any`): The variables as a dictionary/object to render the template with (see Ryuji docs for more information).
+
+## `serve_templates`
+Render multiple templates, and write the results to the build directory.
+
+**Parameters:**
+- `renderer` (`Renderer`): Most likely the Ryuji renderer.
+- `serve_paths` (`string[]`): The paths to serve the files under, inside the build directory.
+- `template_name` (`string`): Name of the template to render (see Ryuji docs for more information).
+- `vars_array` (`any[]`): An array of variables as a dictionary/object to render the templates with (see Ryuji docs for more information).
+
+`serve_paths` and `vars_array` need to have the same length, since the first item of `serve_paths` is rendered with the first item of `vars_array` as the variable, and so on.
+
+# Usage Examples
+```ts
+import { Renderer } from './ryuji.js';
+import { Builder } from './saki.js';
+
+let renderer: Renderer = new Renderer("templates", "components");
+let builder: Builder = new Builder();
+
+builder.serve_static_folder("static");
+
+builder.serve_template(renderer, "/", "index.html", {
+  notices: [
+    "Dave got drunk again and fed the chipmunks. As a result, they are more brazen than usual. Be on your guard!",
+    "Please stop anthropomorphizing the rocks. They WILL come alive.",
+    "Oxygen has decided to retire. Until we find a replacement for him, there will be oxygen and water shortages.",
+  ],
+});
+
+builder.serve_templates(renderer, [
+  "/departments/water",
+  "/departments/energy",
+  "/departments/sanitation",
+  "/departments/permitting",
+  "/departments/human_rights_abuses",
+], "post.html", [
+  {
+    "name": "Department of Water",
+    "employees": 79,
+    "sanctioned_by_ICC": false,
+  },
+  {
+    "name": "Department of Energy",
+    "employees": 140,
+    "sanctioned_by_ICC": false,
+  },
+  {
+    "name": "Department of Sanitation",
+    "employees": 217,
+    "sanctioned_by_ICC": false,
+  },
+  {
+    "name": "Department of Permitting",
+    "employees": 1,
+    "sanctioned_by_ICC": false,
+  },
+  {
+    "name": "Department of Human Rights Abuses",
+    "employees": 9000,
+    "sanctioned_by_ICC": true,
+  },
+]);
+```
+
+If a real world example is preferable, [this blog uses Saki](https://github.com/jetstream0/hedgeblog/blob/master/index.ts) to build as a static site.