Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 169 lines (116 sloc) 5.234 kb
fa09533 Lee Hambley first commit
authored
1 # Emotions
2
3 **Store emotions in Redis.** *Emotions* allows the storage of emotions in
4 Redis, a fast and atomic structured data store. If one's users *hate*, *love*,
5 *appreciate*, *despise* or *just-don-t-care*, one can store that easily via a
6 simple API.
7
84cf30a Lee Hambley Green tests, almost having a useable library.
authored
8 It is not bound to *ActiveRecord*, or any other big libraries, any class exposing a
9 public `id` method can be used. The `id` method is not required to be
10 numerical.
fa09533 Lee Hambley first commit
authored
11
12 ``` ruby
13 class CatPicture < ActiveRecord::Base
14
15 include Emotions::Emotive
16 emotions :like, :dislike
17
18 end
19 ```
20
21 This simple example shows that in our logical model cat pictures can either be
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
22 liked, or disliked. The following methods are available to all instances of `CatPicture`:
23
24 * `number_of_like`
25 * `number_of_likes` (if `ActiveSupport::Inclector` is available.)
26 * `emotion_summary` Returns a hash such as: `{like: 456, dislike: 3}`
fa09533 Lee Hambley first commit
authored
27
28 On the flip-side, one needs a way to share one's feelings, from the model representing
29 a user, or rater, or similar, one can easily use the opposite:
30
31 ``` ruby
32 class User < ActiveRecord::Base
84cf30a Lee Hambley Green tests, almost having a useable library.
authored
33
fa09533 Lee Hambley first commit
authored
34 include Emotions::Emotional
35
36 end
37 ```
38
39 This module will mix-into the `User` the following methods:
40
41 * `like(something_likeable)`
42 * `cancel_like(something_likeable)`
43 * `dislike(something_dislikeable)`
44 * `cancel_dislike(something_dislikeable)`
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
45 * `like?(something_likeable)`
fa09533 Lee Hambley first commit
authored
46
47 These methods can be passed instances of any class which has those emotions defined.
48
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
49 **Passing anything else will cause undefined behaviour.**
50
fa09533 Lee Hambley first commit
authored
51 ## Inspiration
52
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
53 *Emotions* is inspired by [`schneems/likeable`](https://github.com/schneems/Likeable). A few
54 things concerned me about that project, so I wrote *emotions* after contributing
fa09533 Lee Hambley first commit
authored
55 significant fixes to *likeable*.
56
84cf30a Lee Hambley Green tests, almost having a useable library.
authored
57 ### What's different from *Likeable*?
fa09533 Lee Hambley first commit
authored
58
59 * There are no hard-coded assumptions about which emotions you'll be using, that's
60 up to your project needs.
61
84cf30a Lee Hambley Green tests, almost having a useable library.
authored
62 * There are no callbacks, these are better handled with observers, either in the
fa09533 Lee Hambley first commit
authored
63 classical OOP meaning of the word, or your framework's pattern. (In Rails they're
84cf30a Lee Hambley Green tests, almost having a useable library.
authored
64 the same thing)
fa09533 Lee Hambley first commit
authored
65
84cf30a Lee Hambley Green tests, almost having a useable library.
authored
66 * A *very* comprehensive test suite, written with *MiniTest*. *Likeable* is quite
fa09533 Lee Hambley first commit
authored
67 simple, and has about ~35 tests, that might be OK for you, and Gowalla, but I'd
68 feel better with real unit, functional and integration tests.
69
70 * It's not *totally* bound to Redis. Internally there's a Key/Value store proxy, this
71 uses Redis out of the box, but it should be easy for someone to replace this with
72 MongoDB, Riak, DynamoDB, SQLite, etc.
73
84cf30a Lee Hambley Green tests, almost having a useable library.
authored
74 * It does not depend on *ActiveSupport*, *likeable* depends on *keytar*, which depends
75 on `ActiveSupport` for inflection and *ActiveSupport::Concern.*
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
76
84cf30a Lee Hambley Green tests, almost having a useable library.
authored
77 * It does not depend on `Keytar`, Keytar is a handy tool for building NoSQL keys for
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
78 objects, however it's a little bit over-featured for this use-case.
79
84cf30a Lee Hambley Green tests, almost having a useable library.
authored
80 * *Likeable* stores timestamps as floating point numbers, I'm confused
81 by this. Sub-second resoltion seems unusual here, and isn't easy for a
82 human being to read. *Emotions* uses the time format: `%Y-%m-%d %H:%M:%S %z`.
83
84 * *Likeable* doesn't store *symetrical* relationships, using *Likeable*
85 it's only possible to have one type of object sharing opinions on any
86 other (*Users*). *Emotions* stores the relationship symetrically, so
87 many kinds of objects can store many kinds of emotions.
88
89 * *Likeable* stores the class name unaltered, this can cause problems
90 with namespaced classes as the class namespace separator in Ruby is
91 `::`, this conflicts with the sepatator traditionally used in Redis.
92 *Emotions* stores the class names processed with an *ActiveSupport*
93 inspired `underscore` method which uses the forward slash character to
94 represent a namespace delimiter.
95
96 ## Migrating from *Likeable*
97
98 Unfortunately the key structure is sufficiently different that you'll
99 need to explicitly migrate, there's no shortcut. The key to migrating
100 sucessfully is that the `emote(target)` and `emote_by(object)` methods
101 take an optional time parameter in the second position. If this is
102 passed then it will
103
fa09533 Lee Hambley first commit
authored
104 ## Installation
105
106 Add this line to your application's Gemfile:
107
108 gem 'emotions'
109
110 And then execute:
111
112 $ bundle
113
114 Or install it yourself as:
115
116 $ gem install emotions
117
118 ## Usage
119
120 TODO: Write usage instructions here
121
122 ## Contributing
123
124 1. Fork it
125 2. Create your feature branch (`git checkout -b my-new-feature`)
126 3. Commit your changes (`git commit -am 'Added some feature'`)
127 4. Push to the branch (`git push origin my-new-feature`)
128 5. Create new Pull Request
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
129
130
c813f37 Lee Hambley Refactor the key structure, @WIP.
authored
131 ## Sample Key Structure
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
132
84cf30a Lee Hambley Green tests, almost having a useable library.
authored
133 Given the following example, the key
c813f37 Lee Hambley Refactor the key structure, @WIP.
authored
134 structure would be:
135
136 ``` ruby
137 class Recommendation
138 iclude Emotions::Emotive
139 emotions :like
140 end
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
141
142 class User
c813f37 Lee Hambley Refactor the key structure, @WIP.
authored
143 include Emotions::Emotional
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
144 end
145
c813f37 Lee Hambley Refactor the key structure, @WIP.
authored
146 User.find(123).like(Recommendation.find(789)
147 User.find(123).like(Recommendation.find(987)
148
149 User.find(321).like(Recommendation.find(789)
150 ```
151
152 The resulting Redis structure would be something like this:
153
154 ``` text
155 user:like:123:recommendation
156 "789" "2012-11-13 00:01:02 +01:00"
157 "987" "2011-02-01 00:03:01 +01:00"
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
158
c813f37 Lee Hambley Refactor the key structure, @WIP.
authored
159 user:like:321:recommendation
160 "789" "2014-02-01 17:15:01 +01:00"
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
161
c813f37 Lee Hambley Refactor the key structure, @WIP.
authored
162 recommendation:like:789:user
163 "123" "2012-11-13 00:01:02 +01:00"
164 "321" "2014-02-01 17:15:01 +01:00"
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
165
c813f37 Lee Hambley Refactor the key structure, @WIP.
authored
166 recommendation:like:987:user
167 "123" "2011-02-01 00:03:01 +01:00"
1eda0da Lee Hambley Introduce a lot of the groundwork. Good tests.
authored
168 ```
Something went wrong with that request. Please try again.