Add: readme.org

1 files changed, 102 insertions, 0 deletions

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..ebab6d8
--- /dev/null
+++ b/README.org
@@ -0,0 +1,102 @@
+* What
+
+~lazybones~ is a small HTTP routing framework.
+
+Features include: 
+
+- Different server backends. (At the moment only Hunchentoot is supported)
+- Modular and "installable" applications.
+- Handy macros for provisioning apps and defining endpoints.
+- In particular, endpoint routes may contain variables and include
+  parsers for variables and for query parameters
+- customizable errors.
+- Livecoding supported for your endpoint handlers and application configurations.
+- Automatic documentation generation for ~lazybones:app~ instances.
+
+Although lazybones can be used to develop and serve page-oriented web
+sites, it has been written to help me develop "self documenting" HTTP
+APIs.
+
+** Main Components 
+
+The main components in ~lazybones~ are the two classes: ~lazybones:app~
+and ~lazybones:endpoint~.  
+
+Endpoints are objects that represent everything required to handle an
+HTTP request.  Endpoints are collected into groups called apps.  
+
+Apps, in addition to being collections of endpoints, are the main unit
+of development for larger lazybones projects. Apps can be installed to
+running servers on the fly as whole units. If desired, they can also
+be uninstalled.  Apps are meant to be devolped in a
+one-app-per-package manner.  That is, although you can create and work
+with multiple apps in a single Common Lisp package, ~lazybones~
+encourages you to limit yourself to one per package.  
+
+See the example below for more.
+
+** A Hello World Example 
+
+#+begin_src lisp
+
+(asdf:load-system "lazybones-hunchentoot")
+
+(defpackage #:hello-lazybones
+  (:use #:cl)
+  (:local-nicknames (#:lzb #:lazybones))
+  (:import-from #:lazybones #:defendpoint* #:http-ok))
+
+(in-package :hello-lazybones)
+
+(defendpoint* :get "/hello/:name:" () ()
+  "Responds with a greeting to NAME" 
+  (format nil "Welcome to Lazybones, ~a" name))
+
+(defvar *my-server* (lzb:create-server))
+(lzb:install-app *my-server* (lzb:app))
+(lzb:start-server *my-server*)
+#+end_src
+
+
+Go ahead and test this sever out with curl:
+
+#+begin_src shell
+$ curl -v http://localhost:8888/hello/colin
+Trying 127.0.0.1:8888...
+Connected to localhost (127.0.0.1) port 8888 (#0)
+> GET /hello/colin HTTP/1.1
+> Host: localhost:8888
+> User-Agent: curl/7.74.0
+> Accept: */*
+> 
+Mark bundle as not supporting multiuse
+< HTTP/1.1 200 OK
+< Content-Length: 27
+< Date: Wed, 09 Feb 2022 12:26:01 GMT
+< Server: Hunchentoot 1.3.0
+< Content-Type: text/html; charset=utf-8
+< 
+Connection #0 to host localhost left intact
+Welcome to Lazybones, colin
+#+end_src
+
+Check the ~example~ directory in this repository for a more elaborate example. 
+
+** Documentation Generation 
+
+You can generate Markdown documentation for an instance of
+~layzbones:app~ using ~lazybones:generate-app-documentation~.  For an
+example API and example documentation, see the ~example~ directory in
+this repository.
+
+** Backends 
+
+**WARNING** Users can mostly ignore thissection. The API for alternate backends is in
+flux.
+
+To implement a new backend for lazybones, consult the
+~lazybones.backend~ package. Define a new system and a new package
+that ~uses~ the lazybones.backend package. Implement functions for
+each symbol.  Consult the ~lazybones-hunchentoot~ system for an
+example backend.  
+