Skip to content

Commit

Permalink
update html
Browse files Browse the repository at this point in the history
  • Loading branch information
@lgessler
lgessler committed Nov 21, 2023
1 parent aaa9fa5 commit f92cfde
Showing 1 changed file with 112 additions and 20 deletions.
132 changes: 112 additions & 20 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.16">
<meta name="generator" content="Asciidoctor 2.0.20">
<meta name="author" content="Luke Gessler">
<link rel="icon" type="image/x-icon" href="favicon.ico">
<title>Glam Manual</title>
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -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}
Expand All @@ -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}}
Expand All @@ -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}
Expand Down Expand Up @@ -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}
Expand All @@ -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}
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -480,7 +476,11 @@ <h1>Glam Manual</h1>
<li><a href="#_project_configuration">4.2. Project Configuration</a></li>
</ul>
</li>
<li><a href="#_developers_guide">5. Developer&#8217;s Guide</a></li>
<li><a href="#_developers_guide">5. Developer&#8217;s Guide</a>
<ul class="sectlevel2">
<li><a href="#_code_atlas">5.1. Code Atlas</a></li>
</ul>
</li>
</ul>
</div>
</div>
Expand Down Expand Up @@ -828,15 +828,107 @@ <h2 id="_developers_guide"><a class="anchor" href="#_developers_guide"></a><a cl
</tr>
</table>
</div>
<div class="sect2">
<h3 id="_code_atlas"><a class="anchor" href="#_code_atlas"></a><a class="link" href="#_code_atlas">5.1. Code Atlas</a></h3>
<div class="paragraph">
<p>Glam&#8217;s code is divided into <a href="https://clojure.org/reference/namespaces">Clojure namespaces</a>.
If you&#8217;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 <code>glam/xtdb/span_layer.clj</code> holds code the for namespace <code>glam.xtdb.span-layer</code>.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
Note that for historical reasons a <code>_</code> in the file name corresponds to a <code>-</code> in the namespace name and vice versa. Clojure will complain if this condition is not met.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Most of Glam&#8217;s code is in the <code>src/main</code> root directory.
(There are two other root directories: <code>src/test</code>, which contains tests, and <code>src/dev</code>, which contains a small amount code that is only used during development.)
Here is a high-level view of some important namespaces under <code>src/main</code>:</p>
</div>
<div class="paragraph">
<div class="title">glam.server</div>
<p>This namespace contains the heart of the backend.
All the components of the backend that are stateful live here.
These include:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>glam.server.main</code>: the programmatic entry point</p>
</li>
<li>
<p><code>glam.server.config</code>: the object that holds the configuration object for the backend</p>
</li>
<li>
<p><code>glam.server.http-server</code>: the HTTP server which serves the app and handles requests</p>
</li>
<li>
<p><code>glam.server.pathom-parser</code>: the setup required for the <a href="https://blog.wsscode.com/pathom/v2/pathom/2.2.0/introduction.html">Pathom 2</a> resolvers defined in <code>glam.models</code> (see below)</p>
</li>
<li>
<p><code>glam.server.xtdb</code>: the separate <a href="https://xtdb.com/">XTDB databases</a> that are used to manage session information and the rest of all the application&#8217;s data</p>
</li>
<li>
<p><code>glam.server.middleware</code>: 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.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>TODO</p>
<div class="title">glam.xtdb</div>
<p>Each namespace under this one (aside from <code>access</code>, <code>common</code>, and <code>util</code>) 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&#8217;s data model and XTDB before you can write or modify them successfully.</p>
</div>
<div class="paragraph">
<div class="title">glam.models</div>
<p>This is perhaps a bit of an uninformative name.
<code>glam.models</code> contains all the functions for the backend which clients invoke when they want to read or write data from the server.
For example, <code>glam.models.span/create-span</code> is invoked by clients whenever a client wants to create a span on the server.
Typically, each function under <code>glam.models</code> will correspond to a single function under the <code>glam.xtdb</code> namespace (e.g. <code>glam.xtdb.span/create</code>).</p>
</div>
<div class="paragraph">
<p>Why have <code>glam.models</code>, then?
Because <code>glam.models</code> 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 <code>glam.xtdb</code> function&#8217;s success.
<code>glam.xtdb</code> do not attempt to check any of these things before executing.</p>
</div>
<div class="paragraph">
<p>Additionally, the <code>glam.models</code> namespace sometimes contains validation logic related to certain fields.
For example, <code>glam.models.document</code> 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 <code>.cljc</code> 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.</p>
</div>
<div class="paragraph">
<div class="title">glam.client</div>
<p>This is the namespace that almost all of the ClojureScript code lives under.
The majority of this code by volume is under <code>glam.client.ui</code>, but the namespaces which are not under that contain important bureaucratic information, mostly for Fulcro (<code>glam.client.application</code>), but also for the router (<code>glam.client.router</code>).</p>
</div>
<div class="paragraph">
<div class="title">glam.client.ui</div>
<p>This is where all of the <a href="https://fulcro.fulcrologic.com/">Fulcro</a> 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.</p>
</div>
<div class="paragraph">
<div class="title">glam.algos</div>
<p>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.</p>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2022-01-14 14:13:16 -0500
Last updated 2023-11-20 20:29:38 -0500
</div>
</div>
</body>
Expand Down

0 comments on commit f92cfde

Please sign in to comment.