forked from riak-ripple/ripple
-
Notifications
You must be signed in to change notification settings - Fork 1
/
index.html
163 lines (144 loc) · 16 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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta name="Content-Type" content="text/html; charset=UTF-8" />
<title>Documentation by YARD 0.5.3</title>
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
<link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
<script type="text/javascript" charset="utf-8">
relpath = '';
if (relpath != '') relpath += '/';
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<script type="text/javascript" charset="utf-8">
if (window.top.frames.main) document.body.className = 'frames';
</script>
<div id="header">
<div id="menu">
<a href="_index.html" title="Index">Index</a> »
<span class="title">File: README</span>
<div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
</div>
<div id="search">
<a id="class_list_link" href="#">Class List</a>
<a id="method_list_link" href="#">Method List</a>
<a id ="file_list_link" href="#">File List</a>
</div>
<div class="clear"></div>
</div>
<iframe id="search_frame"></iframe>
<div id="content"><div id='filecontents'><h1>ripple</h1>
<p>ripple is a rich Ruby client for Riak, Basho’s distributed database. It includes two namespaces:</p>
<ul>
<li><code>Riak</code> contains a basic wrapper around typical operations, including bucket manipulation, object <span class="caps">CRUD</span>, link-walking, and map-reduce.</li>
<li><code>Ripple</code> contains an ActiveModel-compatible modeling layer that is inspired by ActiveRecord, DataMapper, and MongoMapper.</li>
</ul>
<h2>Dependencies</h2>
<p>ripple requires Ruby 1.8.7 or later and versions 3 or above of ActiveModel and ActiveSupport (and their dependencies, including i18n). Please see the Rails 3 beta release notes for installing those gems. I highly recommend the <a href="http://curb.rubyforge.org/">curb</a> gem for better <span class="caps">HTTP</span> client performance.</p>
<p>In development, you will also need these gems:</p>
<ul>
<li>jeweler</li>
<li>rspec >= 1.3</li>
<li>fakeweb >= 1.2</li>
<li>curb >= 0.6</li>
<li>rack >= 1.0</li>
<li>yard >= 0.5.2</li>
</ul>
<h2>Basic Example</h2>
<pre class="code"><span class='id require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>riak</span><span class='tstring_end'>'</span></span>
<span class='comment'># Create a client interface
</span><span class='id client'>client</span> <span class='op'>=</span> <span class='const'>Riak</span><span class='op'>::</span><span class='const'>Client</span><span class='period'>.</span><span class='id new'>new</span>
<span class='comment'># Retrieve a bucket
</span><span class='id bucket'>bucket</span> <span class='op'>=</span> <span class='id client'>client</span><span class='period'>.</span><span class='id bucket'>bucket</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>doc</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span> <span class='comment'># a Riak::Bucket
</span>
<span class='comment'># Get an object from the bucket
</span><span class='id object'>object</span> <span class='op'>=</span> <span class='id bucket'>bucket</span><span class='period'>.</span><span class='id get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>index.html</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span> <span class='comment'># a Riak::RObject
</span>
<span class='comment'># Change the object's data and save
</span><span class='id object'>object</span><span class='period'>.</span><span class='id data'>data</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'><html><body>Hello, world!</body></html></span><span class='tstring_end'>"</span></span>
<span class='id object'>object</span><span class='period'>.</span><span class='id store'>store</span>
<span class='comment'># Reload an object you already have
</span><span class='id object'>object</span><span class='period'>.</span><span class='id reload'>reload</span> <span class='comment'># Works if you have the key and vclock, using conditional GET
</span><span class='id object'>object</span><span class='period'>.</span><span class='id reload'>reload</span> <span class='symbol'>:force</span> <span class='op'>=></span> <span class='kw'>true</span> <span class='comment'># Reloads whether you have the vclock or not
</span>
<span class='comment'># Access more like a hash, client[bucket][key]
</span><span class='id client'>client</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>doc</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>index.html</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span> <span class='comment'># the Riak::RObject
</span>
<span class='comment'># Create a new object
</span><span class='id new_one'>new_one</span> <span class='op'>=</span> <span class='const'>Riak</span><span class='op'>::</span><span class='const'>RObject</span><span class='period'>.</span><span class='id new'>new</span><span class='lparen'>(</span><span class='id bucket'>bucket</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>application.js</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span>
<span class='id new_one'>new_one</span><span class='period'>.</span><span class='id content_type'>content_type</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>application/javascript</span><span class='tstring_end'>"</span></span> <span class='comment'># You must set the content type.
</span><span class='id new_one'>new_one</span><span class='period'>.</span><span class='id data'>data</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>alert('Hello, World!')</span><span class='tstring_end'>"</span></span>
<span class='id new_one'>new_one</span><span class='period'>.</span><span class='id store'>store</span></pre><h2>Map-Reduce Example</h2>
<pre class="code">
<span class='comment'># Assuming you've already instantiated a client, get the album titles for The Beatles
</span><span class='id results'>results</span> <span class='op'>=</span> <span class='const'>Riak</span><span class='op'>::</span><span class='const'>MapReduce</span><span class='period'>.</span><span class='id new'>new</span><span class='lparen'>(</span><span class='id client'>client</span><span class='rparen'>)</span><span class='period'>.</span>
<span class='id add'>add</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>artists</span><span class='tstring_end'>"</span></span><span class='comma'>,</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Beatles</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span><span class='period'>.</span>
<span class='id link'>link</span><span class='lparen'>(</span><span class='symbol'>:bucket</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>albums</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span><span class='period'>.</span>
<span class='id map'>map</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>function(v){ return [JSON.parse(v.values[0].data).title]; }</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='symbol'>:keep</span> <span class='op'>=></span> <span class='kw'>true</span><span class='rparen'>)</span><span class='period'>.</span><span class='id run'>run</span>
<span class='id p'>p</span> <span class='id results'>results</span> <span class='comment'># => ["Please Please Me", "With The Beatles", "A Hard Day's Night",
</span> <span class='comment'># "Beatles For Sale", "Help!", "Rubber Soul",
</span> <span class='comment'># "Revolver", "Sgt. Pepper's Lonely Hearts Club Band", "Magical Mystery Tour",
</span> <span class='comment'># "The Beatles", "Yellow Submarine", "Abbey Road", "Let It Be"]</span></pre><h2>Document model Example</h2>
<pre class="code">
<span class='id require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>ripple</span><span class='tstring_end'>'</span></span>
<span class='kw'>class</span> <span class='const'>Email</span>
<span class='id include'>include</span> <span class='const'>Ripple</span><span class='op'>::</span><span class='const'>Document</span>
<span class='id property'>property</span> <span class='symbol'>:from</span><span class='comma'>,</span> <span class='const'>String</span><span class='comma'>,</span> <span class='symbol'>:presence</span> <span class='op'>=></span> <span class='kw'>true</span>
<span class='id property'>property</span> <span class='symbol'>:to</span><span class='comma'>,</span> <span class='const'>String</span><span class='comma'>,</span> <span class='symbol'>:presence</span> <span class='op'>=></span> <span class='kw'>true</span>
<span class='id property'>property</span> <span class='symbol'>:sent</span><span class='comma'>,</span> <span class='const'>Time</span><span class='comma'>,</span> <span class='symbol'>:default</span> <span class='op'>=></span> <span class='id proc'>proc</span> <span class='lbrace'>{</span> <span class='const'>Time</span><span class='period'>.</span><span class='id now'>now</span> <span class='rbrace'>}</span>
<span class='id property'>property</span> <span class='symbol'>:body</span><span class='comma'>,</span> <span class='const'>String</span>
<span class='kw'>end</span>
<span class='id email'>email</span> <span class='op'>=</span> <span class='const'>Email</span><span class='period'>.</span><span class='id find'>find</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>37458abc752f8413e</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span> <span class='comment'># GET /riak/emails/37458abc752f8413e
</span><span class='id email'>email</span><span class='period'>.</span><span class='id from'>from</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>someone@nowhere.net</span><span class='tstring_end'>"</span></span>
<span class='id email'>email</span><span class='period'>.</span><span class='id save'>save</span> <span class='comment'># PUT /riak/emails/37458abc752f8413e
</span>
<span class='id reply'>reply</span> <span class='op'>=</span> <span class='const'>Email</span><span class='period'>.</span><span class='id new'>new</span>
<span class='id reply'>reply</span><span class='period'>.</span><span class='id from'>from</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>justin@bashoooo.com</span><span class='tstring_end'>"</span></span>
<span class='id reply'>reply</span><span class='period'>.</span><span class='id to'>to</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>sean@geeemail.com</span><span class='tstring_end'>"</span></span>
<span class='id reply'>reply</span><span class='period'>.</span><span class='id body'>body</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Riak is a good fit for scalable Ruby apps.</span><span class='tstring_end'>"</span></span>
<span class='id reply'>reply</span><span class='period'>.</span><span class='id save'>save</span> <span class='comment'># POST /riak/emails (Riak-assigned key)
</span></pre><h2>How to Contribute</h2>
<ul>
<li>Fork the project on <a href="http://github.com/seancribbs/ripple">Github</a>. If you have already forked, use <code>git pull --rebase</code> to reapply your changes on top of the mainline. Example:
<pre class="code">$ git checkout master
$ git pull --rebase seancribbs master</pre></li>
<li>Create a topic branch. If you’ve already created a topic branch, rebase it on top of changes from the mainline “master” branch. Examples:
<ul>
<li>New branch:
<pre class="code">$ git checkout -b topic</pre></li>
<li>Existing branch:
<pre class="code">$ git rebase master</pre></li>
</ul></li>
<li>Write an RSpec example, set of examples, and/or Cucumber story that demonstrate the necessity and validity of your changes. <strong>Patches without specs will most often be ignored. Just do it, you’ll thank me later.</strong> Documentation patches need no specs, of course.</li>
<li>Make your feature addition or bug fix. Make your specs and stories pass (green).</li>
<li>Run the suite using multiruby or rvm to ensure cross-version compatibility.</li>
<li>Cleanup any trailing whitespace in your code (try <code>whitespace-mode</code> in Emacs, or “Remove Trailing Spaces in Document” in the “Text” bundle in Textmate).</li>
<li>Commit, do not mess with Rakefile or <span class="caps">VERSION</span>. If related to an existing issue in the <a href="http://github.com/seancribbs/ripple/issues">tracker</a>, include “Closes #X” in the commit message (where X is the issue number).</li>
<li>Send me a pull request.</li>
</ul>
<h2>License & Copyright</h2>
<p>Copyright ©2010 Sean Cribbs, Sonian Inc., and Basho Technologies, Inc.</p>
<p>Licensed under the Apache License, Version 2.0 (the “License”);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</p>
<p><a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/<span class="caps">LICENSE</span>-2.0</a></p>
<p>Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an “AS IS” <span class="caps">BASIS</span>,
<span class="caps">WITHOUT</span> <span class="caps">WARRANTIES</span> OR <span class="caps">CONDITIONS</span> OF <span class="caps">ANY</span> <span class="caps">KIND</span>, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.</p>
<h2>Auxillary Licenses</h2>
<p>The included photo (spec/fixtures/cat.jpg) is Copyright ©2009 <a href="http://seancribbs.com/">Sean Cribbs</a>, and is
licensed under the <a href="http://creativecommons.org/licenses/by-nc/3.0">Creative Commons Attribution Non-Commercial 3.0</a> license. <img src="http://i.creativecommons.org/l/by-nc/3.0/88x31.png" alt="" /></p>
<p>The “Poor Man’s Fibers” implementation (lib/riak/util/fiber1.8.rb) is Copyright ©2008 Aman Gupta.</p></div></div>
<div id="footer">
Generated on Fri Mar 5 13:45:38 2010 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool">yard</a>
0.5.3 (ruby-1.9.1).
</div>
</body>
</html>