basic_assumption 0.3.3 → 0.3.4

Sign up to get free protection for your applications and to get access to all the features.
data/README.rdoc CHANGED
@@ -1,7 +1,8 @@
1
1
  == BasicAssumption
2
2
 
3
3
  A clone of DecentExposure with a psuedo-modular interface for providing
4
- custom defaults.
4
+ custom defaults. It provides a declarative interface for specifying helper
5
+ methods that is useful in Rails applications.
5
6
 
6
7
  === What is DecentExposure?
7
8
 
@@ -13,8 +14,8 @@ It represents an idiom for writing certain kinds of code in a declarative way.
13
14
  Particularly in your Rails apps, it's worth checking out. BasicAssumption is
14
15
  another implementation of the idiom. It exists largely because I felt like
15
16
  practicing writing a gem, though it does have a differentiating feature or two.
16
- Check the +Configuration+ options for enabling compatibility with the
17
- DecentExposure API.
17
+ Check the BasicAssumption::Configuration options for enabling compatibility
18
+ with the DecentExposure API.
18
19
 
19
20
  == Install BasicAssumption
20
21
 
@@ -84,7 +85,26 @@ And then inside of the 'widgets/purchase_complete.html.haml' view:
84
85
 
85
86
  By calling +assume+ with the symbol :widget and passing it a block, an instance
86
87
  method is created on the controller class that is also exposed as a helper
87
- inside views. For more details, please see the +Railtie+ documentation.
88
+ inside views. For more details on how BasicAssumption is wired into your Rails
89
+ app, please see the BasicAssumption::Railtie documentation.
90
+
91
+ === When to use it
92
+
93
+ Whenever you find yourself writing a +before_filter+ in a Rails controller
94
+ that sets instance variables as part of the context of your request, you should
95
+ probably use an assumption instead. Because BasicAssumption is written to use
96
+ lazy evaluation, there's no need to worry about avoiding calls on actions that
97
+ don't need some particular setup.
98
+
99
+ If a controller has protected or hidden methods that find or create instance
100
+ variables used in actions and/or views, it might be cleaner to use an
101
+ assumption instead.
102
+
103
+ BasicAssumption allows for a simple, declarative, and very lightweight approach
104
+ to RESTful controllers.
105
+
106
+ It also can make for a cleaner, more testable interface for controller or view
107
+ testing. There may even be uses outside of Rails apps. Give it a shot.
88
108
 
89
109
  === Defaults
90
110
 
@@ -130,7 +150,7 @@ Default assumptions are inherited by derived classes.
130
150
  === Supplying custom default behavior classes
131
151
 
132
152
  There is an ability to provide custom, modular default extensions to
133
- BasicAssumption and then use them by passing a symbol, like so:
153
+ BasicAssumption and then use them by passing a symbol, as in the following:
134
154
 
135
155
  class WidgetController < ActionController::Base
136
156
  default_assumption :my_custom_default_class
@@ -145,19 +165,30 @@ BasicAssumption::DefaultAssumption namespace. Please see the documentation for
145
165
 
146
166
  There are a couple of simple configuration settings that can be set inside of
147
167
  a configuration block that can be used in places such as Rails initializer
148
- blocks. For more information, see +Configuration+.
168
+ blocks. For more information, see BasicAssumption::Configuration.
149
169
 
150
170
  == Issues
151
171
 
152
172
  === Memoization
153
173
 
154
- Methods that are created by +assume+ memoize the result of the block the invoke
155
- when they're called. Because of that, the block is only evaluated once during
156
- the lifespan of each object of the class that used +assume+. This means that
157
- a method created by assuming can be used multiple times inside of a Rails
158
- controller object and associated view(s), but it also means that any behavior
159
- of the block that is meant to vary over multiple invocations will not be
160
- observerd.
174
+ Methods that are created by BasicAssumption#assume memoize the result of the
175
+ block the invoke when they're called. Because of that, the block is only
176
+ evaluated once during the lifespan of each object of the class that used
177
+ +assume+. This means that a method created by assuming can be used multiple
178
+ times inside of a Rails controller object and associated view(s) without
179
+ invoking the associated block multiple times, but it also means that any
180
+ behavior of the block that is meant to vary over multiple invocations will not
181
+ be observed.
182
+
183
+ === Exceptions
184
+
185
+ Using BasicAssumption may change the exception handling strategy inside your
186
+ classes. In Rails, the +rescue_from+ method may be useful.
187
+
188
+ === Other
189
+
190
+ There are probably others, and when I remember what they were, I'll write them
191
+ up.
161
192
 
162
193
  == Hacking/running specs
163
194
 
@@ -168,3 +199,14 @@ manager. For example, if RubyGems:
168
199
  export RUBYOPT=rubygems
169
200
 
170
201
  Other than that, please feel free to fork and send back pull requests! Thanks.
202
+
203
+ == But should I use it?
204
+
205
+ Sure! Absolutely. I think it's a cool idea that lets you cut down on line
206
+ noise, particularly in your Rails controllers. You may want to consider going
207
+ with {DecentExposure}[http://github.com/voxdolo/decent_exposure], simply
208
+ because it's used by much of {Hashrocket}[http://www.hashrocket.com/]
209
+ and BasicAssumption is used, so far as I know, only by me. But so far as I know
210
+ BasicAssumption is pretty solid, and I'm happy to accept bug fixes and field
211
+ feature requests. If you use it, feel free to let me know! Email mby [at]
212
+ mattyoho [dot] com with questions, comments, or non-sequiters.
@@ -1,3 +1,3 @@
1
1
  module BasicAssumption
2
- VERSION = '0.3.3'
2
+ VERSION = '0.3.4'
3
3
  end
metadata CHANGED
@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
5
5
  segments:
6
6
  - 0
7
7
  - 3
8
- - 3
9
- version: 0.3.3
8
+ - 4
9
+ version: 0.3.4
10
10
  platform: ruby
11
11
  authors:
12
12
  - Matt Yoho