From f92cfdecd44a4857955be21c44303c2843c2667d Mon Sep 17 00:00:00 2001 From: Luke Gessler Date: Mon, 20 Nov 2023 20:43:03 -0500 Subject: [PATCH] update html --- index.html | 132 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 112 insertions(+), 20 deletions(-) diff --git a/index.html b/index.html index 5dcf617..65f6b6f 100644 --- a/index.html +++ b/index.html @@ -4,7 +4,7 @@ - + Glam Manual @@ -86,10 +86,10 @@ ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} ul,ol{margin-left:1.5em} ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0} -ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit} -ul.square{list-style-type:square} ul.circle{list-style-type:circle} ul.disc{list-style-type:disc} +ul.square{list-style-type:square} +ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit} ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} dl dt{margin-bottom:.3125em;font-weight:bold} dl dd{margin-bottom:1.25em} @@ -195,7 +195,8 @@ #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221} details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} details{margin-left:1.25rem} -details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;-webkit-tap-highlight-color:transparent} +details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent} +details>summary::-webkit-details-marker{display:none} details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)} details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)} details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem} @@ -209,13 +210,10 @@ .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere} .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} .exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px} -.exampleblock>.content>:first-child{margin-top:0} -.exampleblock>.content>:last-child{margin-bottom:0} .sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px} -.sidebarblock>:first-child{margin-top:0} -.sidebarblock>:last-child{margin-bottom:0} .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} -.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} +.exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0} +.exampleblock>.content>:last-child,.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} .literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em} @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}} @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}} @@ -237,9 +235,8 @@ table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none} table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal} table.linenotable td.code{padding-left:.75em} -table.linenotable td.linenos{border-right:1px solid;opacity:.35;padding-right:.5em} -pre.pygments .lineno{border-right:1px solid;opacity:.35;display:inline-block;margin-right:.75em} -pre.pygments .lineno::before{content:"";margin-right:-.125em} +table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none} +pre.pygments span.linenos{display:inline-block;margin-right:.75em} .quoteblock{margin:0 1em 1.25em 1.5em;display:table} .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em} .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify} @@ -276,7 +273,7 @@ table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0} table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0} table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0} -table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd),table.stripes-even tr:nth-of-type(even),table.stripes-hover tr:hover{background:#f8f8f7} +table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7} th.halign-left,td.halign-left{text-align:left} th.halign-right,td.halign-right{text-align:right} th.halign-center,td.halign-center{text-align:center} @@ -292,10 +289,11 @@ ul li ol{margin-left:1.5em} dl dd{margin-left:1.125em} dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} -ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} +li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none} ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em} ul.unstyled,ol.unstyled{margin-left:0} +li>p:empty:only-child::before{content:"";display:inline-block} ul.checklist>li>p:first-child{margin-left:-1em} ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em} ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em} @@ -338,8 +336,6 @@ #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em} #footnotes .footnote:last-of-type{margin-bottom:0} #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} -.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0} -.gist .file-data>table td.line-data{width:99%} div.unbreakable{page-break-inside:avoid} .big{font-size:larger} .small{font-size:smaller} @@ -396,7 +392,7 @@ dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em} p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} -p,blockquote,dt,td.content,span.alt,summary{font-size:1.0625rem} +p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem} p{margin-bottom:1.25rem} .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc} @@ -480,7 +476,11 @@

Glam Manual

  • 4.2. Project Configuration
    • -
  • 5. Developer’s Guide
    • +
  • 5. Developer’s Guide + +
    • @@ -828,15 +828,107 @@

    +
    +

    5.1. Code Atlas

    +
    +

    Glam’s code is divided into Clojure namespaces. +If you’re not familiar, a Clojure namespace is like a Python module in that it is a contained unit of code that lives in a single file, and the path of the file (relative to the root directory) determines the name of the namespace. +For example, a file at glam/xtdb/span_layer.clj holds code the for namespace glam.xtdb.span-layer.

    +
    +
    + + + + + +
    +
    Warning
    +    		 +Note that for historical reasons a _ in the file name corresponds to a - in the namespace name and vice versa. Clojure will complain if this condition is not met. +
    +
    +
    +

    Most of Glam’s code is in the src/main root directory. +(There are two other root directories: src/test, which contains tests, and src/dev, which contains a small amount code that is only used during development.) +Here is a high-level view of some important namespaces under src/main:

    +
    +
    +
    glam.server
    +

    This namespace contains the heart of the backend. +All the components of the backend that are stateful live here. +These include:

    +
    +
    +
      +
    • +

      glam.server.main: the programmatic entry point

      +
      • +
    • +

      glam.server.config: the object that holds the configuration object for the backend

      +
      • +
    • +

      glam.server.http-server: the HTTP server which serves the app and handles requests

      +
      • +
    • +

      glam.server.pathom-parser: the setup required for the Pathom 2 resolvers defined in glam.models (see below)

      +
      • +
    • +

      glam.server.xtdb: the separate XTDB databases that are used to manage session information and the rest of all the application’s data

      +
      • +
    • +

      glam.server.middleware: the middleware that lets the HTTP server interact with the other major components of the application in order to fulfill requests, i.e. the Pathom parser, the database, and a couple other things.

      +
      • +
    +
    -

    TODO

    +
    glam.xtdb
    +

    Each namespace under this one (aside from access, common, and util) contains functions which help you read from and write to the database for the entity whose name is on the namespace. +Think of this as analogous to where your SQL queries would go if you were using a SQL database. +Beware: these functions require you to have a more or less complete understanding of both Glam’s data model and XTDB before you can write or modify them successfully.

    +
    +
    +
    glam.models
    +

    This is perhaps a bit of an uninformative name. +glam.models contains all the functions for the backend which clients invoke when they want to read or write data from the server. +For example, glam.models.span/create-span is invoked by clients whenever a client wants to create a span on the server. +Typically, each function under glam.models will correspond to a single function under the glam.xtdb namespace (e.g. glam.xtdb.span/create).

    +
    +
    +

    Why have glam.models, then? +Because glam.models is where validation happens: arguments are checked for validity, users are checked for proper authentication and authorization, and additionally, clients are given helpful error or success messages in response to the glam.xtdb function’s success. +glam.xtdb do not attempt to check any of these things before executing.

    +
    +
    +

    Additionally, the glam.models namespace sometimes contains validation logic related to certain fields. +For example, glam.models.document has a validation function that checks whether the name of the document is between 1 and 80 characters in length. +For this reason, many of the files in this namespace end with the .cljc extension, which indicates to the Clojure[Script] compilers that the file can be read both as valid Clojure and ClojureScript. +This helps us write validation logic exactly once, precluding inconsistency on client and server.

    +
    +
    +
    glam.client
    +

    This is the namespace that almost all of the ClojureScript code lives under. +The majority of this code by volume is under glam.client.ui, but the namespaces which are not under that contain important bureaucratic information, mostly for Fulcro (glam.client.application), but also for the router (glam.client.router).

    +
    +
    +
    glam.client.ui
    +

    This is where all of the Fulcro components live. +A Fulcro component is a React component with some extra bits specific to Fulcro. +Fulcro is too much of a thing to even try to explain here, so consult the documents if you need to understand it. +However, note that it is possible for this code to interoperate with plain React components written in JavaScript. +As of the writing of this section, this has not been done yet, but this may change soon.

    +
    +
    +
    glam.algos
    +

    There are some data operations that are quite complicated (e.g. taking two versions of a string and finding the shortest sequence of string edits that can produce one from the other) that have been separate out into this namespace to keep the places where they are consumed from being overrun by their length. +This is where they live.

    +