annotate website/src/goodjava.html.luan @ 1653:418b610e887b

docs work
author Franklin Schmidt <fschmidt@gmail.com>
date Thu, 31 Mar 2022 22:12:40 -0600
parents 5b8f056527a3
children 8066b8882732
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
1 local Luan = require "luan:Luan.luan"
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
2 local error = Luan.error
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
3 local Io = require "luan:Io.luan"
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
4 local Http = require "luan:http/Http.luan"
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
5 local Shared = require "site:/lib/Shared.luan"
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
6 local head = Shared.head or error()
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
7 local header = Shared.header or error()
1653
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
8 local show_toc = Shared.show_toc or error()
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
9 local show_content = Shared.show_content or error()
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
10
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
11
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
12 local content = {
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
13 intro = {
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
14 title = "Introduction"
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
15 content = function()
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
16 %>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
17 <p>The <a href="https://hg.luan.software/luan/file/default/src/goodjava">goodjava</a> library is independent of Luan. Luan calls goodjava but goodjava never calls Luan code. So goodjava can be used as a Java library. goodjava is included in the Luan jar file.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
18
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
19 <p>As western programming became depraved, it became more and more difficult to find good libraries. So rather than use modern depraved libraries, I wrote my own. I will describe the most important libraries.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
20 <%
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
21 end
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
22 }
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
23 logger = {
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
24 title = "goodjava.logger"
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
25 content = function()
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
26 %>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
27 <p>This includes <a href="https://hg.luan.software/luan/file/default/src/goodjava/logger">goodjava.logger</a> which replaces <a href="https://logging.apache.org/log4j/1.2/">log4j</a>, and <a href="https://hg.luan.software/luan/file/default/src/goodjava/logging">goodjava.logging</a> which replaces <a href="http://www.slf4j.org/">slf4j</a>. You can see <a href="https://hg.luan.software/luan/file/default/src/goodjava/logger/examples">some examples</a> of how to use my logger. Configuration is in Java, where it should be.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
28
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
29 <p>slf4j is a typical modern mess. Just look at <a href="http://www.slf4j.org/apidocs/org/slf4j/Logger.html">slf4j's logger</a> and compare to the interface of <a href="https://hg.luan.software/luan/file/default/src/goodjava/logging/Logger.java">my logger</a>. log4j isn't horrible but has significant problems. This project was abandoned by its author so that he could create a horrible depraved logger called <a href="http://logback.qos.ch/">Logback</a> to fit with his depraved culture. log4j biggest problem is that it doesn't handle logging separation properly. It's <a href="https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/spi/RepositorySelector.html">RepositorySelector</a> is a hack. goodjava.logger's <a href="https://hg.luan.software/luan/file/default/src/goodjava/logger/ThreadLocalAppender.java">ThreadLocalAppender</a> solves the problem properly.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
30
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
31 <p>I implemented full bridging with slf4j, both slf4j to goodjava.logging and goodjava.logging to slf4j. This way my code is completely compatible with depraved modern code.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
32 <%
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
33 end
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
34 }
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
35 parser = {
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
36 title = "goodjava.parser"
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
37 content = function()
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
38 %>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
39 <p>In computer science, parsing is a big deal. They make it complicated, of course. But it shouldn't be. I developed a new approach to parsing which is implemented <a href="https://hg.luan.software/luan/file/default/src/goodjava/parser/">here</a>. It is based on a simple stack of integers that are positions in what is effectively recursive descent parsing. I use this idea to compile Luan but also to parse <a href="https://hg.luan.software/luan/file/default/src/goodjava/json/JsonParser.java">JSON</a>, <a href="https://hg.luan.software/luan/file/default/src/goodjava/lucene/queryparser/GoodQueryParser.java">Lucene queries</a>, <a href="https://hg.luan.software/luan/file/default/src/goodjava/webserver/RequestParser.java">HTTP requests</a>, <a href="https://hg.luan.software/luan/file/default/src/luan/modules/parsers/BBCode.java">BBCode</a>, <a href="https://hg.luan.software/luan/file/default/src/luan/modules/parsers/Css.java">CSS</a>, <a href="https://hg.luan.software/luan/file/default/src/luan/modules/parsers/Csv.java">CSV</a>, <a href="https://hg.luan.software/luan/file/default/src/luan/modules/parsers/Html.java">HTML</a>, and other things.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
40
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
41 <p>When I wrote the <a href="https://hg.luan.software/luan/file/default/src/goodjava/json/JsonParser.java">JSON parser</a>, it worked on the first run. It is so much simpler than any other JSON parser. I dare you to look for any JSON parser as simple as this one. All my other parsers are similar. My approach to parsing reflects my anti-modern values. I hate theoretical nonsense and I hate needless complexity. Think deeply about a problem (like parsing) until you see the essence of it. Then write clean simple code to solve the problem.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
42 <%
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
43 end
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
44 }
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
45 json = {
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
46 title = "goodjava.json"
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
47 content = function()
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
48 %>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
49 <p>Found <a href="https://hg.luan.software/luan/file/default/src/goodjava/json">here</a>, this lets you parse or create JSON easily.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
50 <%
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
51 end
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
52 }
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
53 xml = {
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
54 title = "goodjava.xml"
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
55 content = function()
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
56 %>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
57 <p>Yet another case where all existing libraries are horrible, so I wrote <a href="https://hg.luan.software/luan/file/default/src/goodjava/xml">my own</a>.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
58 <%
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
59 end
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
60 }
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
61 rpc = {
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
62 title = "goodjava.rpc"
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
63 content = function()
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
64 %>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
65 <p>Most RPCs (remote procedure calls) these days use REST which is really absurd because HTTP was never meant for this, so it is inefficient. So I made a simple socket-based RPC that just uses JSON <a href="https://hg.luan.software/luan/file/default/src/goodjava/rpc">here</a>. I use this to manage my luan hosting service.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
66 <%
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
67 end
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
68 }
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
69 queryparser = {
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
70 title = "goodjava.lucene.queryparser"
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
71 content = function()
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
72 %>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
73 <p>This is a better implementation of <a href="https://lucene.apache.org/core/4_9_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package_description">Lucene's QueryParser</a> which has serious defects like only being able to query text fields. <a href="https://hg.luan.software/luan/file/default/src/goodjava/lucene/queryparser">My implementation</a> fixes all the defects.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
74 <%
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
75 end
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
76 }
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
77 webserver = {
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
78 title = "goodjava.webserver"
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
79 content = function()
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
80 %>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
81 <p>This is the first part of the library that I wrote. I wrote it after studying all available java webservers and being horrified by them. My hatred of modern software and modern culture was fully developed by this time, so I wrote this code intending to violate every rule of modern software, and I am rather pleased with the result. The code is very clean and simple. <a href="https://hg.luan.software/luan/file/default/src/goodjava/webserver/">Here</a> is the source.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
82
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
83 <p>The core interface is <a href="https://hg.luan.software/luan/file/default/src/goodjava/webserver/Handler.java">Handler</a>. Note the simplicity. This takes a <a href="https://hg.luan.software/luan/file/default/src/goodjava/webserver/Request.java">Request</a> and returns a <a href="https://hg.luan.software/luan/file/default/src/goodjava/webserver/Response.java">Response</a> (or null if the request wasn't handled). Note how these classes are simple structs with no "get" and "set" methods. They are structs that directly represent the true underlying data in the HTTP protocol. No stupid obscuring layers (like servlets). Keep it raw and simple.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
84
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
85 <p>To write a server, write your own Handler or chain together existing handlers. See this <a href="https://hg.luan.software/luan/file/default/src/goodjava/webserver/examples/Example.java">example</a>.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
86
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
87 <p>I use this webserver by itself for development, and behind nginx for production. I have only implemented what I need as I need it. I haven't tried to make this a production-ready stand-alone webserver. That is much more work.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
88 <%
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
89 end
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
90 }
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
91 mail = {
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
92 title = "goodjava.mail"
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
93 content = function()
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
94 %>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
95 <p>The last horrible modern library that I replaced is <a href="https://javaee.github.io/javamail/">java.mail</a>. <a href="https://hg.luan.software/luan/file/default/src/goodjava/mail">My code</a> to send mail is a little over 200 lines. It is a thin layer on top of SMTP and MIME.</p>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
96 <%
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
97 end
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
98 }
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
99 }
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
100
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
101
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
102 return function()
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
103 Io.stdout = Http.response.text_writer()
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
104 %>
1524
7902e74bfe5c add goodjava.html
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
105 <!doctype html>
7902e74bfe5c add goodjava.html
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
106 <html>
7902e74bfe5c add goodjava.html
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
107 <head>
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
108 <% head() %>
1524
7902e74bfe5c add goodjava.html
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
109 <title>The goodjava Library</title>
7902e74bfe5c add goodjava.html
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
110 </head>
7902e74bfe5c add goodjava.html
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
111 <body>
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
112 <% header() %>
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
113 <div content>
1653
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
114 <h1><a href="goodjava.html">The goodjava Library</a></h1>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
115 <hr>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
116 <h2>Contents</h2>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
117 <div toc>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
118 <% show_toc(content) %>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
119 </div>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
120 <hr>
418b610e887b docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1651
diff changeset
121 <% show_content(content,2) %>
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
122 </div>
1524
7902e74bfe5c add goodjava.html
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
123 </body>
7902e74bfe5c add goodjava.html
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
124 </html>
1651
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
125 <%
5b8f056527a3 docs work
Franklin Schmidt <fschmidt@gmail.com>
parents: 1593
diff changeset
126 end