Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the oook Reference Manual, version 0.2.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Thu Mar 11 14:21:28 2021 GMT+0.
• Introduction | What oook is all about | |
• Systems | The systems documentation | |
• Modules | The modules documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
OOOK
is some data manipulation magic on top of the venerable CL-SQL
package, which has been providing a solid SQL abstraction in Common Lisp for
years.
The goal of OOOK
is to greatly decrease "standard" database-driven web
application development time with the trade-off of slightly less flexiblity.
With that in mind, some of the features include:
Note: Database design should be driven by the data, not by the code that
uses it! To encourage this, OOOK
will never have functionality to manipulate
the database schema.
Also, OOOK
is still under development and the API is changing fairly
frequently. It is regularly used in its present state, however, and is mostly
stable.
Create models of tables in the database with defmodel
:
(oook:defmodel post (:belongs-to user)
"Some interesting prose, full of wisdom"
(date_published :type clsql:wall-time)
(title :column "post-title")
content)
(oook:defmodel user (:has-many posts)
"Someone who writes posts"
name
(level :type integer :documentation "Skill level"))
This creates two CLOS classes which model the "post" and "user" database tables, including the relationship between the two. The models have brief dostrings, custom slots (including types) and associations with other models.
Note: the defmodel
macro creates two CLSQL
view-classes, using
clsql:def-view-class
, containing the specified slots and a number of
additional slots for managing the joins.
Create a new user using the standard CLOS make-instance
:
(defvar wizzard
(make-instance 'user :name "Rincewind" :level 0))
Create a new post and add it to the user:
(push (posts wizzard) (make-instance 'post :title "On Staying Alive")))
Save the new user (and post) in the database:
(oook:save wizzard) ; Will save both the user and his post
Find something, either by ID with the built-in find-by-id
helper, or construct
a CLSQL
statement for more complex queries (OOOK
provides a few other
helpers, see the documentation).
(oook:find-by-id 'post 2) ; Find the post row with ID == 2
(clsql:select 'user) ; Select all users
OOOK
makes it simple to build a model instance given a set of POST data, as
long as the POST data is constructed according to a few rules. If you use the
HTML generation helpers below, this is handled automatically!
More documentation coming soon... But have a look at serialise.lisp
!
OOOK provides some utilties for viewing and editing model data. In the simplest form, you can generate an HTML form to modify a model with a few lines:
(let ((the-post (make-instance 'post :title "New Post")))
(oook:get-edit-form the-post "/save"))
With the previous definition of post
, this returns the following HTML.
<form class="ui form" action=/save method=POST>
<div class=field>
<label>Content</label>
<input type=text name=post[content]>
</div>
<div class=field>
<label>Title</label>
<input type=text name=post[title] value="New Post">
</div>
<div class=field>
<label>Date_Published</label>
<input type=date name=post[date_published]>
</div>
<div class=field>
<label>User Id</label>
<input type=number name=post[user_id]>
</div>
<button class="ui primary button" type=submit>Save</button>
</form>
Things to note
post
is passed in, and its values used to pre-populate the
formOOOK
serialisation functionsOOOK
provides a context manager, with-record-type
to make it easier to build
custom forms.
Documentation coming soon... But have a look at html.lisp
!
Use oook:def-enhanced-printer
to quickly enhance the printed representations
of models.
CL-USER> (oook:def-enhanced-printer post :slot 'title)
...
CL-USER> (format t (oook:find-by-id 'post 5))
#<POST "The Joys of Boredom">
Like another well known library, all tables are expected to have at least these three columns:
id
: A unique (for this model type) ID for the row (the table's primary key)created-at
: Time of creationlast-modified
: Time of last modificationThese have historically been found to be useful in typical web applications. The
id
field is always required, and will be an index into the table. The second
two can be disabled by passing :timestamped nil
to defmodel
.
In addition, models you define will typically have a number of other fields, corresponding to columns in the table, and possibly a number of associated models.
A model can be associated to other models in a number of ways.
Models are selected exactly as you would with CL-SQL
, and, by default, the
joins are lazily loaded (i.e. a "join" slot is only populated from the DB when
it is accessed).
The fun part is saving.
oook:save
will save any associated models that belong to the instance it is
called with. New rows will be created as necessary.
Left requires one instance of Right, but Right doesn't care or know about this relationship. (e.g. ingredient -> unit).
Left owns one Right, and Right knows it. Left cannot have more than one Right. (e.g. user <- config)
Left is owned by one Right. Left cannot have more than one owner. (e.g. config <- user). However Right might have more than one Left (e.g. step* <- recipe)
Left has many Rights, and the Rights know which Left they belong to. (e.g. recipe <- step*)
Not implemented yet
Left references many instances of Right, and Right might be referenced by many instances of Left. (e.g. programmer <-> project, a programmer is part of many projects and a project has many programmers)
Get: do not try to resolve the parent relation (circular dep)
MIT License
Copyright (c) 2017 Ricardo M. H. da Silva
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The oook system |
Ric da Silva <ric@rmhsilva.com>
MIT
Some magic on the shoulders of CLSQL
0.2.0
oook.asd (file)
src (module)
Modules are listed depth-first from the system components tree.
• The oook/src module |
oook (system)
src/
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
Next: The oook/src/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
oook.asd
oook (system)
Next: The oook/src/utils․lisp file, Previous: The oook․asd file, Up: Lisp files [Contents][Index]
src (module)
src/package.lisp
Next: The oook/src/serialise․lisp file, Previous: The oook/src/package․lisp file, Up: Lisp files [Contents][Index]
src (module)
src/utils.lisp
Next: The oook/src/html․lisp file, Previous: The oook/src/utils․lisp file, Up: Lisp files [Contents][Index]
src (module)
src/serialise.lisp
get-slot-type (function)
Next: The oook/src/methods․lisp file, Previous: The oook/src/serialise․lisp file, Up: Lisp files [Contents][Index]
src (module)
src/html.lisp
Next: The oook/src/macro․lisp file, Previous: The oook/src/html․lisp file, Up: Lisp files [Contents][Index]
src (module)
src/methods.lisp
Previous: The oook/src/methods․lisp file, Up: Lisp files [Contents][Index]
src (module)
src/macro.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The oook.serialise package | ||
• The oook.macro package | ||
• The oook.utils package | ||
• The oook package | ||
• The oook.methods package |
Next: The oook․macro package, Previous: Packages, Up: Packages [Contents][Index]
A set of serialisation utilities, including to/from alists, to json (using jonathan)
package.lisp (file)
common-lisp
Next: The oook․utils package, Previous: The oook․serialise package, Up: Packages [Contents][Index]
Defines the ‘defmodel’ macro, and the associated functions
package.lisp (file)
macro
common-lisp
Next: The oook package, Previous: The oook․macro package, Up: Packages [Contents][Index]
package.lisp (file)
common-lisp
Next: The oook․methods package, Previous: The oook․utils package, Up: Packages [Contents][Index]
package.lisp (file)
common-lisp
Previous: The oook package, Up: Packages [Contents][Index]
package.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported special variables | ||
• Exported macros | ||
• Exported functions | ||
• Exported generic functions |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
macro.lisp (file)
Options that control how objects are serialised
serialise.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Enhances ‘print-object’ for ‘type’, adding the ‘slot’ attribute to it
utils.lisp (file)
Define a class that models DB structure
macro.lisp (file)
html.lisp (file)
Execute ‘body’ with json options set to ‘options’
serialise.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Delete ‘inst’ and associated models
methods.lisp (file)
methods.lisp (file)
Find a model with ‘id’
methods.lisp (file)
Create an instance of ‘class’, given ‘alist’ containing mapping of slots to values, in caveman2 parsed params format.
serialise.lisp (file)
Print an HTML table listing the data in ‘records’
html.lisp (file)
html.lisp (file)
Try to parse ‘type’ from input ‘value’
utils.lisp (file)
Pretty print ‘inst’
serialise.lisp (file)
Save ‘inst’ and associated models
methods.lisp (file)
Search the DB for ‘model’ using LIKE to match column. If ‘singlep’ is t, only one result is returned
utils.lisp (file)
Make ‘symbol’ suitable for SQL name
utils.lisp (file)
Return an a-list representation of ‘inst’
serialise.lisp (file)
Previous: Exported functions, Up: Exported definitions [Contents][Index]
macro.lisp (file)
macro.lisp (file)
Read the ‘id’ attribute
macro.lisp (file)
Return the foreign keys for models in has-one and belongs-to
macro.lisp (file)
macro.lisp (file)
macro.lisp (file)
macro.lisp (file)
Return the slots in ‘inst’ that will be included when ‘to-alist’ is called
macro.lisp (file)
macro.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal macros | ||
• Internal functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
For each model in the owns-many relation of ‘inst’, execute ‘body’ with the symbol ‘right’ bound to the model type, and the symbol ‘value’ bound to the current slot-value of the relation
methods.lisp (file)
Create form to ensure that ‘slot’ in ‘inst’ is of type ‘type’
utils.lisp (file)
Previous: Internal macros, Up: Internal definitions [Contents][Index]
Check everything in ‘records’ is the same type
html.lisp (file)
Return ‘thing’ as an integer
utils.lisp (file)
html.lisp (file)
html.lisp (file)
html.lisp (file)
Get the type of ‘slot’ in ‘class’
serialise.lisp (file)
Create a clsql base slot form from ‘slot’
macro.lisp (file)
macro.lisp (file)
Create a clsql foreign key slot form from ‘slot’
macro.lisp (file)
Create a foreign key (append _id) for symbol
macro.lisp (file)
Return T if ‘inst’ does not have a row in the DB
methods.lisp (file)
If a slot type is something like (OR NULL BOOLEAN), return just BOOLEAN
html.lisp (file)
Make ‘symbol’ suitable for a field name as a keyword
utils.lisp (file)
Remove all olds that are no longer in new, and add the new!
methods.lisp (file)
Update the ‘created-at’ and ‘last-modified’ timestamps in ‘inst’
methods.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | F L M O |
---|
Jump to: | F L M O |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | A C D E F G I J L M N O P S T U W |
---|
Jump to: | A C D E F G I J L M N O P S T U W |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | *
S |
---|
Jump to: | *
S |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | O P S |
---|
Jump to: | O P S |
---|