/doc/us/reference.md

  1## Reference Manual
  2
  3This is a short reference of all of Orbit's (and Orbit apps) methods.
  4
  5## Module `orbit`
  6
  7**orbit.new([*app*])** - creates a new Orbit application, returning it (as a module).
  8If *app* is a string this is the application's name, and sets field \_NAME. If *app*
  9is a table it is used instead of a fresh table. This means you can pass `orbit.new`
 10to the `module` function
 11
 12**orbit.htmlify(*func*[, *func*...])** - modifies the environment of *func* to
 13include functions that generate HTML
 14
 15## Orbit apps
 16
 17**app.run(*wsapi\_env*)** - WSAPI entry point for application, generated by Orbit
 18
 19**app.real\_path** - the root of the application in the filesystem, defaults to
 20the path inferred by WSAPI launchers (`wsapi.app\_path`), but can be overridden
 21
 22**app.mapper** - mapper used by `app:model`, defaults to an instance of `orbit.model`,
 23but can be overridden
 24
 25**app.not\_found** - default handler, sends a 404 response to the client, can be overridden.
 26The handler receives a `web` object
 27
 28**app.server\_error** - error handler, sends a 500 response with stack trace to the
 29client, can be overridden. The handler receives a `web` object
 30
 31**app:dispatch\_get(*func*, *patt*[, *patt*...])** - installs *func* as a GET handler for
 32the patterns *patt*. *func* receives a `web` object and the captures; this handler should return
 33the contents of the response or **app.reparse** if you want to hand control back to
 34the dispatcher and let it continue matching;
 35
 36**app:dispatch\_post(*func*, *patt*[, *patt*...])** - installs *func* as a POST handler for
 37the patterns *patt*. *func* receives a `web` object and the captures; this handler should return
 38the contents of the response or **app.reparse** if you want to hand control back to
 39the dispatcher and let it continue matching;
 40
 41**app:dispatch\_put(*func*, *patt*[, *patt*...])** - installs *func* as a PUT handler for
 42the patterns *patt*. *func* receives a `web` object and the captures; this handler should return
 43the contents of the response or **app.reparse** if you want to hand control back to
 44the dispatcher and let it continue matching;
 45
 46**app:dispatch\_delete(*func*, *patt*[, *patt*...])** - installs *func* as a DELETE handler for
 47the patterns *patt*. *func* receives a `web` object and the captures; this handler should return
 48the contents of the response or **app.reparse** if you want to hand control back to
 49the dispatcher and let it continue matching;
 50
 51**app:dispatch\_wsapi(*func*, *patt*[, *patt*...])** - installs *func* as a WSAPI handler for
 52the patterns *patt*. *func* receives the unmodified WSAPI environment
 53
 54**app:dispatch\_static(*patt*[, *patt*...])** - installs a static files handler for
 55the patterns *patt*. This handler assumes the PATH\_INFO is a file relative to
 56`app.real_path` and sends it to the client. The MIME type is detected from
 57the extension (default application/octec-stream)
 58
 59**app:serve\_static(*web*, *filename*)** - returns the content of file *filename* (which can be
 60anywhere in the filesystem), while setting the appropriate headers with the file's MIME
 61type
 62
 63**app:htmlify(*patt*[, *patt*...])** - same as `orbit.htmlify`, but changes all of the
 64app's module functions that match the patterns *patt*
 65
 66**app:model(...)** - calls `app.mapper:new(...)`, so the behaviour depends on the mapper
 67you are using
 68
 69## `web` methods
 70
 71The *web* objects inherit the functions of module `wsapi.util` as methods.
 72
 73**web.status** - status to be sent to server (default: "200 Ok")
 74
 75**web.headers** - headers to be sent to server, a Lua table (default has Content-Type as text/html)
 76
 77**web.response** - body to send to the server (default is blank)
 78
 79**web.vars** - original WSAPI environment
 80
 81**web.prefix** - app's prefix (if set in the app's module) or SCRIPT\_NAME
 82
 83**web.suffix** - app's suffix (if set in the app's module)
 84
 85**web.real\_path** - location of app in filesystem, taken from wsapi\_env.APP\_PATH, or app's module real\_path, or "."
 86 
 87**web.doc\_root, web.path\_info, web.script\_name, web.path\_translated, web.method** - server's document root, PATH\_INFO,
 88SCRIPT\_NAME, PATH\_TRANSLATED, and REQUEST\_METHOD (converted to lowercase)
 89
 90**web.GET, web.POST** - GET and POST variables
 91
 92**web.input** - union of web.GET and web.POST
 93
 94**web.cookies** - cookies sent by the browser
 95
 96**web:set\_cookie(*name*, *value*)** - sets a cookie to be sent back to browser
 97
 98**web:delete\_cookie(*name*)** - deletes a cookie
 99
100**web:redirect(*url*)** - sets status and headers to redirect to *url*
101
102**web:link(*part*, [*params*])** - creates intra-app link, using web.prefix and web.suffix, and encoding *params*
103as a query string
104
105**web:static\_link(*part*)** - if app's entry point is a script, instead of path, creates a link to the app's vpath
106(e.g. if app.prefix is /foo/app.ws creates a link in /foo/*part*), otherwise same as web:link
107
108**web:empty(*s*)** - returns true if *s* is nil or an empty string (zero or more spaces)
109
110**web:content\_type(*s*)** - sets the content type of the reponse to *s*
111
112**web:empty\_param(*name*)** - returns true if input parameter *name* is empty (as web:empty)
113
114**web:page(*name*, [*env*])** - loads and renders Orbit page called *name*. If *name* starts with / it's relative to
115the document root, otherwise it's relative to the app's path. Returns rendered page. *env* is an optional environment
116with extra variables.
117
118**web:page_inline(*contents*, [*env*])** - renders an inline Orbit page
119
120## Module `orbit.cache`
121
122**orbit.cache.new(*app*, [*base\_path*])** - creates a page cache for *app*, either in memory or at the filesystem
123path *base\_path* (**not** relative to the app's path!), returns the cache object
124
125**a\_cache(*handler*)** - caches *handler*, returning a new handler; uses the PATH\_INFO as a key to the cache
126
127**a\_cache:get(*key*)** - gets value stored in *key*; usually not used, use the previous function instead
128
129**a\_cache:set(*key*, *val*)** - stores a value in the cache; use a\_cache(*handler*) to encapsulate this behaviour
130
131**a\_cache:invalidate(*key*)** - invalidates a cache value
132
133**a\_cache:nuke()** - clears the cache
134
135## Module `orbit.model`
136
137**orbit.model.new([*table\_prefix*], [*conn*], [*driver*], [*logging*])** - creates a new ORM mapper. *table\_prefix* (default "")
138is a string added to the start of model names to get table names; *conn* is the database connection (can be set
139later); *driver* is the kind of database (currently "sqlite3", the default, and "mysql");  *logging* 
140sets whether you want logging of all queries to `io.stderr`. Returns a mapper instance,
141and all the parameters can be set after this instance is created (via a\_mapper.table\_prefix, a\_mapper.conn, 
142a\_mapper.driver, and a\_mapper.logging)
143
144**orbit.model.recycle(*conn\_builder*, *timeout*)** - creates a connection using *conn\_builder*, a function
145that takes no arguments, and wraps it so a new connection is automatically reopened every *timeout* seconds
146
147**a\_mapper:new(*name*, [*tab*])** - creates a new model object; *name* is used together with a\_mapper.table\_prefix to
148form the DB table's name; fields and types are introspected from the table. *tab* is an optional table that
149is used as the basis for the model object if present
150
151**a\_model.model** - the mapper for this model
152
153**a\_model.name, a\_model.table\_name** - the name of the model and its backing table
154
155**a\_model.driver** - the DB driver used
156
157**a\_model.meta** - metainformation about the model, introspected from the table
158
159**a\_model:find(*id*)** - finds and returns the instance of the model with the passed *id* (keyed using
160the `id` column of the table (must be numeric)
161
162**a\_model:find\_first(*condition*, *args*)** - finds and returns the first instance of the model that
163matches *condition*; *args* can determine the order (args.order), specify which fields should be returned
164(args.fields, default is all of them), and inject fields from other tables
165(args.inject)
166
167Example: `books:find_first("author = ? and year_pub > ?", { "John Doe", 1995, order = "year_pub asc" })`
168
169**a\_model:find\_all(*condition*, *args*)** - finds and returns all instances of the model that
170matches *condition*; *args* can determine the order (args.order), specify which fields should be returned
171(args.fields, default is all of them), limit the number of returned rows (args.count), skip that many rows before beginning to return rows (args.offset),
172return only distinct rows (args.distinct), and inject fields from other tables (args.inject)
173
174Example: `books:find_all("author = ? and year_pub > ?", { "John Doe", 1995, order = "year_pub asc", count = 5, fields = { "id", "title" } })`
175
176**a\_model:new([*tab*])** - creates a fresh instance of the model, optionally using *tab* as initial
177values
178
179**a\_model:find\_by\_xxx(*args*)** - finds and returns the first instance of the model building the
180condition from the method name, a la Rails' ActiveRecord; *args* works the same way as in **find\_first**, above
181
182**a\_model:find\_all\_by\_xxx(*args*)** - finds and returns all instances of the model building the
183condition from the method name, a la Rails' ActiveRecord; *args* works the same way as in **find\_all**, above
184
185Example: `books:find_all_by_author_or_author{ "John Doe", "Jane Doe", order = "year_pub asc" }`
186
187**an\_instance:save([*force\_insert*])** - saves an instance to the DB, commiting changes or creating the backing record if the instance is new; if *force\_insert* is true always do an insert instead of an update
188
189If there's a row called `created_at` this row is set to the creation date of the record; if there's a row
190called `updated_at` this row is set to the last update's date.
191
192**an\_instance:delete()** - deletes an instance from the DB
193
194## Module `orbit.routes`
195
196This module has a single function, **R**, and you can also call the module itself. This function takes a PATH\_INFO pattern where the path segments (the parts of the path separated by `/` or `.`) can be named parameters (`:name`), *splats* (\*), optional parameters (`?:name?`), or literals, and returns a pattern.
197
198A pattern is an object with two methods:
199
200**patt:match(*str*)** - tries to match *str* and returns a hash of named parameters; splats are returned in a `splat` array inside this hash.
201
202**patt:build(*params*)** - builds the original pattern string from a hash of named parameters
203
204Some examples of patterns, what they match, and the parameter hashes:
205
206* '/foo', matches '/foo', empty hash
207* '/foo/:bar/baz' matches '/foo/orbit/baz' or '/foo/xxx.yyy/baz' with hashes { bar = 'orbit' } and { bar = 'xxx.yyy' }
208* '/:name.:ext' matches '/xxx.yyy' or '/filename.ext' with hashes { name = 'xxx', ext = 'yyy' } and { name = 'filename', ext = 'ext' }
209* '/*/foo/*' matches '/bar/foo' or '/bar/foo/bling/baz/boom' with hashes { splat = { 'bar' } } and { splat = { 'bar', 'bling/baz/boom' } }
210* '/?:foo?/?:bar?' matches '/' or '/orbit' or '/orbit/routes' with hashes {} and { foo = 'orbit' } and { foo = 'orbit', bar = 'routes' }
211
212And several more, see `test/test_routes.lua` for a comprehensive test suite.