/
index.html
190 lines (150 loc) · 19.8 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
<!DOCTYPE html>
<html><head><link href="css/default.css" rel="stylesheet" type="text/css"><script src="js/jquery.min.js" type="text/javascript"></script><script src="js/page_effects.js" type="text/javascript"></script><title>Ciste-core 0.4.0-SNAPSHOT API documentation</title></head><body><div id="header"><h1><a href="index.html">Ciste-core 0.4.0-SNAPSHOT API documentation</a></h1></div><div class="sidebar" id="namespaces"><h3><span>Namespaces</span></h3><ul><li><a href="ciste.commands.html"><span>ciste.commands</span></a></li><li><a href="ciste.config.html"><span>ciste.config</span></a></li><li><a href="ciste.core.html"><span>ciste.core</span></a></li><li><a href="ciste.debug.html"><span>ciste.debug</span></a></li><li><a href="ciste.filters.html"><span>ciste.filters</span></a></li><li><a href="ciste.formats.html"><span>ciste.formats</span></a></li><li><a href="ciste.formats.default.html"><span>ciste.formats.default</span></a></li><li><a href="ciste.middleware.html"><span>ciste.middleware</span></a></li><li><a href="ciste.model.html"><span>ciste.model</span></a></li><li><a href="ciste.predicates.html"><span>ciste.predicates</span></a></li><li><a href="ciste.routes.html"><span>ciste.routes</span></a></li><li><a href="ciste.runner.html"><span>ciste.runner</span></a></li><li><a href="ciste.sections.html"><span>ciste.sections</span></a></li><li><a href="ciste.sections.default.html"><span>ciste.sections.default</span></a></li><li><a href="ciste.test-helper.html"><span>ciste.test-helper</span></a></li><li><a href="ciste.triggers.html"><span>ciste.triggers</span></a></li><li><a href="ciste.views.html"><span>ciste.views</span></a></li><li><a href="ciste.views.default.html"><span>ciste.views.default</span></a></li><li><a href="ciste.workers.html"><span>ciste.workers</span></a></li></ul></div><div class="namespace-index" id="content"><h2>Ciste-core 0.4.0-SNAPSHOT API documentation</h2><div class="doc">MVC platform for Clojure applications</div><div class="namespace"><h3><a href="ciste.commands.html"><span>ciste.commands</span></a></h3><pre class="doc"></pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.commands.html#var-*command-predicates*"><span>*command-predicates*</span></a></li><li><a href="ciste.commands.html#var-*commands*"><span>*commands*</span></a></li><li><a href="ciste.commands.html#var-add-command%21"><span>add-command!</span></a></li><li><a href="ciste.commands.html#var-command-names"><span>command-names</span></a></li><li><a href="ciste.commands.html#var-parse-command"><span>parse-command</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.config.html"><span>ciste.config</span></a></h3><pre class="doc">Ciste uses the config function in ciste.config to perform all the
configuration. Config takes a variable number of key values and will
either return a non-nil value if that option is defined, or will raise
an exception if it is not.
The config information is read from the file "config.clj" at the base
of the project's directory. The config file should contain a hash-map.
The top-level keys will be the names of environments. The values of
these keys will be an arbitrarily complex structure of hashes,
vectors, and other data.
Example:
(use 'ciste.config)
(load-config)
(set-environment! :default)
(config :option1) => "foo"
(config :option3) => ["foo" "bar" "baz"]
(config :option2 :title) => "BAR"</pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.config.html#var-*doc-maps*"><span>*doc-maps*</span></a></li><li><a href="ciste.config.html#var-*environment*"><span>*environment*</span></a></li><li><a href="ciste.config.html#var-*environments*"><span>*environments*</span></a></li><li><a href="ciste.config.html#var-config"><span>config</span></a></li><li><a href="ciste.config.html#var-config*"><span>config*</span></a></li><li><a href="ciste.config.html#var-config-doc"><span>config-doc</span></a></li><li><a href="ciste.config.html#var-definitializer"><span>definitializer</span></a></li><li><a href="ciste.config.html#var-describe-config"><span>describe-config</span></a></li><li><a href="ciste.config.html#var-environment"><span>environment</span></a></li><li><a href="ciste.config.html#var-get-host-address"><span>get-host-address</span></a></li><li><a href="ciste.config.html#var-get-host-name"><span>get-host-name</span></a></li><li><a href="ciste.config.html#var-load-config"><span>load-config</span></a></li><li><a href="ciste.config.html#var-merge-config"><span>merge-config</span></a></li><li><a href="ciste.config.html#var-run-initializers%21"><span>run-initializers!</span></a></li><li><a href="ciste.config.html#var-set-config%21"><span>set-config!</span></a></li><li><a href="ciste.config.html#var-set-environment%21"><span>set-environment!</span></a></li><li><a href="ciste.config.html#var-with-environment"><span>with-environment</span></a></li><li><a href="ciste.config.html#var-write-config%21"><span>write-config!</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.core.html"><span>ciste.core</span></a></h3><pre class="doc">Any fundamental state changes in your application should take place
through an action. Any time you create, update, or delete a resource,
you should use an action. Actions are analogous to the Controller in a
traditional MVC design.
When an action is executed, if the config path [:print :actions] is
enabled, then the action will be logged.
Actions are simply functions. An Action can take any number of
parameters and should return any logically true value if the action
succeeded.</pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.core.html#var-*format*"><span>*format*</span></a></li><li><a href="ciste.core.html#var-defaction"><span>defaction</span></a></li><li><a href="ciste.core.html#var-with-context"><span>with-context</span></a></li><li><a href="ciste.core.html#var-with-format"><span>with-format</span></a></li><li><a href="ciste.core.html#var-with-serialization"><span>with-serialization</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.debug.html"><span>ciste.debug</span></a></h3><pre class="doc">The ciste.debug namespace contains only a single macro: spy. Spy will
log the code it wraps as well as a pretty-printed version of it's
value. That value will then be returned. This allows you to easily
monitor any bit of code by simply wrapping it with spy.</pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.debug.html#var-spy"><span>spy</span></a></li><li><a href="ciste.debug.html#var-with-time"><span>with-time</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.filters.html"><span>ciste.filters</span></a></h3><pre class="doc">Filters are methods of the multimethod apply-filter. A Filter
dispatches on the Action and the Serialization. A Filter takes 2
arguments: The Action, and the request map.
It is the job of the Filter to parse the request map and produce the
options to be passed to Action. The Filter must call that action with
the appropriate arguments.
While it is possible to modify the response from the Action, it is
recommended that filters not modify responses. (That would belong in
the view.)
Example:
(defaction login
[username password]
;; Perform authentication
)
(deffilter #'login :http
[action request]
(let [{{:keys [username password]} :params}]
(action username password)))</pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.filters.html#var-deffilter"><span>deffilter</span></a></li><li><a href="ciste.filters.html#var-filter-action-dispatch"><span>filter-action-dispatch</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.formats.html"><span>ciste.formats</span></a></h3><pre class="doc"></pre><div class="index"><p>Public variables and functions:</p><ul></ul></div></div><div class="namespace"><h3><a href="ciste.formats.default.html"><span>ciste.formats.default</span></a></h3><pre class="doc"></pre><div class="index"><p>Public variables and functions:</p><ul></ul></div></div><div class="namespace"><h3><a href="ciste.middleware.html"><span>ciste.middleware</span></a></h3><pre class="doc"></pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.middleware.html#var-apply-wrappers"><span>apply-wrappers</span></a></li><li><a href="ciste.middleware.html#var-with-request-logging"><span>with-request-logging</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.model.html"><span>ciste.model</span></a></h3><pre class="doc"></pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.model.html#var-fetch-document"><span>fetch-document</span></a></li><li><a href="ciste.model.html#var-fetch-resource"><span>fetch-resource</span></a></li><li><a href="ciste.model.html#var-implement"><span>implement</span></a></li><li><a href="ciste.model.html#var-query"><span>query</span></a></li><li><a href="ciste.model.html#var-stream-%3Edocument"><span>stream->document</span></a></li><li><a href="ciste.model.html#var-string-%3Edocument"><span>string->document</span></a></li><li><a href="ciste.model.html#var-string-%3Ezip"><span>string->zip</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.predicates.html"><span>ciste.predicates</span></a></h3><pre class="doc"></pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.predicates.html#var-method-matches%3F"><span>method-matches?</span></a></li><li><a href="ciste.predicates.html#var-name-matches%3F"><span>name-matches?</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.routes.html"><span>ciste.routes</span></a></h3><pre class="doc">## Routing
Ciste's routing mechanism can be used in any situation where you have
a request that needs to be processed, possibly changing state,
returning a result that is then transformed into a desired output
format, and then either returned or processed in some other fashion.
'resolve-routes' takes 2 parameters: a sequence of predicates, and a
sequence of matcher pairs. A "handler" function is then returned that
takes a request map and then returns a response.
When a request is being processed, Ciste will iterate over the
sequence of matchers and apply the predicates. The first
matcher to return a non-nil result will then invoke its action.
A matcher pair is a sequence containing 2 maps. The first map contains
data that will be used by the predicates to determine if the request
is valid for the matcher. The section map contains information that
will be used if the matcher is selected.
The predicate sequence is a list of predicate functions. Each function
takes the matcher data as the first argument and the request as the
second. Each predicate will perform some test, possibly using data
contained in the matcher map as its arguments. If the predicate
passes, it returns a map containing the new request map for the next
step in the chain. Usually the request is simply returned unmodified.
## Invoking an Action
When a Ciste route is matched, invoke-action will perform a series of
steps, ultimately returning the final result.
First, the Filter is called. The Filter will extract all of the
necessary parameters from the serialization-specific request and call
the serialization-agnostic Action. The Action will produce a result,
which is then returned by the Filter.
Next, the request map and the returned data are passed to the View
function. Views are specific to the Format in use. The View will
transform the response data to a format acceptable to the downstream
Serializer.
With the response data transformed into a format-specific view, a
template is then called, if enabled. This will attach any additional
markup or perform any processing that is done to every request using
the same format that specifies that a template be used.
The next stage is to call the Formatter. This is the last stage that
is specific to the format. This is where any intermediate data
structures are converted to types that can be used by
serializers. Steps such as converting Hiccup vectors to strings should
be done here.
Finally, the Serializer performs a last stage transform specific to
the Serialization type. Place things that need to apply to every
request here. If Ciste is being used in a Ring application, there is
no need to perform any IO, and the map can simply be returned. It is
possible to write Serializers that will respond to a request by
transmitting the response in any number of ways. (XMPP, Email,
Filesystem, etc.)</pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.routes.html#var-invoke-action"><span>invoke-action</span></a></li><li><a href="ciste.routes.html#var-lazier"><span>lazier</span></a></li><li><a href="ciste.routes.html#var-resolve-route"><span>resolve-route</span></a></li><li><a href="ciste.routes.html#var-resolve-routes"><span>resolve-routes</span></a></li><li><a href="ciste.routes.html#var-try-predicate"><span>try-predicate</span></a></li><li><a href="ciste.routes.html#var-try-predicates"><span>try-predicates</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.runner.html"><span>ciste.runner</span></a></h3><pre class="doc">This is the runner for ciste applications.
Specify this namespace as the main class of your application.</pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.runner.html#var--main"><span>-main</span></a></li><li><a href="ciste.runner.html#var-default-site-config"><span>default-site-config</span></a></li><li><a href="ciste.runner.html#var-default-site-config-filename"><span>default-site-config-filename</span></a></li><li><a href="ciste.runner.html#var-init-services"><span>init-services</span></a></li><li><a href="ciste.runner.html#var-load-site-config"><span>load-site-config</span></a></li><li><a href="ciste.runner.html#var-read-site-config"><span>read-site-config</span></a></li><li><a href="ciste.runner.html#var-require-modules"><span>require-modules</span></a></li><li><a href="ciste.runner.html#var-require-namespaces"><span>require-namespaces</span></a></li><li><a href="ciste.runner.html#var-start-services%21"><span>start-services!</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.sections.html"><span>ciste.sections</span></a></h3><pre class="doc">Sections are a series of multimethods for generically transforming
records into the most appropriate format.
A Section dispatches on a Vector containing the type of the first
argument or the type of the first element of the first argument if the
Section has been defined as a :seq type, the Format, and
the Serialization. If no match is found, the final value is removed
and tried again. This repeats until there is only the type.
Example:
(declare-section show-section)
(declare-section index-section :seq)
(defsection show-section [User :html :http]
[user & options]
[:div
[:p "Name: " (:name user)]
[:p "Email: " (:email user)]])
(defsection index-section [User :html :http]
[users & options]
[:ul
(map
(fn [user]
[:li (show-section user)])
users)])</pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.sections.html#var-declare-section"><span>declare-section</span></a></li><li><a href="ciste.sections.html#var-record-class"><span>record-class</span></a></li><li><a href="ciste.sections.html#var-record-class-format"><span>record-class-format</span></a></li><li><a href="ciste.sections.html#var-record-class-seq"><span>record-class-seq</span></a></li><li><a href="ciste.sections.html#var-record-class-seq-format"><span>record-class-seq-format</span></a></li><li><a href="ciste.sections.html#var-record-class-seq-serialization"><span>record-class-seq-serialization</span></a></li><li><a href="ciste.sections.html#var-record-class-serialization"><span>record-class-serialization</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.sections.default.html"><span>ciste.sections.default</span></a></h3><pre class="doc"></pre><div class="index"><p>Public variables and functions:</p><ul></ul></div></div><div class="namespace"><h3><a href="ciste.test-helper.html"><span>ciste.test-helper</span></a></h3><pre class="doc"></pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.test-helper.html#var-test-environment-fixture"><span>test-environment-fixture</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.triggers.html"><span>ciste.triggers</span></a></h3><pre class="doc">Triggers allow you to have functions called as part of a seperate
thread pool whenever a matching action is invoked.
A Trigger is a function that takes 3 arguments: The action, the
request map, and the response from invoking the action.
All of the dynamic bindings from the original request are coppied to
the trigger.
Example:
(defaction my-action
[request]
{:foo 23, :bar 42})
(defn my-trigger
[action request record]
"Do something in a different thread")
(ciste.trigger/add-trigger! #'my-action #'my-trigger)</pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.triggers.html#var-add-trigger%21"><span>add-trigger!</span></a></li><li><a href="ciste.triggers.html#var-run-triggers"><span>run-triggers</span></a></li><li><a href="ciste.triggers.html#var-set-thread-pool%21"><span>set-thread-pool!</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.views.html"><span>ciste.views</span></a></h3><pre class="doc">A View is a pair of multi-methods: apply-view, and default-format. The
apply-view method dispatches on a vector containing the Action and the
Format. If no match is found this value, then default-format tries
using only Format.
A View accepts two parameters: the request, and the response from
invoking the action. A View should render the supplied data into a
structure appropriate to the Format. It is not required, but this is
most commonly a map.
Example:
(defview #'show :html
[request user]
{:status 200
:body [:div.user
[:p (:name user)]]})</pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.views.html#var-apply-view"><span>apply-view</span></a></li><li><a href="ciste.views.html#var-apply-view-by-format"><span>apply-view-by-format</span></a></li><li><a href="ciste.views.html#var-defview"><span>defview</span></a></li></ul></div></div><div class="namespace"><h3><a href="ciste.views.default.html"><span>ciste.views.default</span></a></h3><pre class="doc"></pre><div class="index"><p>Public variables and functions:</p><ul></ul></div></div><div class="namespace"><h3><a href="ciste.workers.html"><span>ciste.workers</span></a></h3><pre class="doc">Workers are tasks functions that run on their own thread p for a time,
sleep, and then run again. Generally, tasks that will repeatedly run. A
worker can be started and stopped by any thread. When a worker is
stopped, it will continue until the next time that it exits. You can
check if it's stopping within your code if you wish to exit earlier.
(defworker :queue-checker
[queue-name]
(check-and-process-queue queue-name))
(start-worker! :queue-checker) => 1
(stop-worker! 1) => nil
(stop-all-workers!) => nil</pre><div class="index"><p>Public variables and functions:</p><ul><li><a href="ciste.workers.html#var-current-worker"><span>current-worker</span></a></li><li><a href="ciste.workers.html#var-defworker"><span>defworker</span></a></li><li><a href="ciste.workers.html#var-stop-all-workers%21"><span>stop-all-workers!</span></a></li><li><a href="ciste.workers.html#var-stop-worker%21"><span>stop-worker!</span></a></li><li><a href="ciste.workers.html#var-worker-keys"><span>worker-keys</span></a></li></ul></div></div></div></body></html>