Skip to content

Commit ca30add

Browse files
dblockdblock
committed
Use OrderState throughout README.
1 parent 5a57aec commit ca30add

File tree

1 file changed

+90
-96
lines changed

1 file changed

+90
-96
lines changed

‎README.md‎

Lines changed: 90 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Ruby::Enum
55
[![Build Status](https://github.com/dblock/ruby-enum/workflows/test/badge.svg?branch=master)](https://github.com/dblock/ruby-enum/actions)
66
[![Code Climate](https://codeclimate.com/github/dblock/ruby-enum.svg)](https://codeclimate.com/github/dblock/ruby-enum)
77

8-
Enum-like behavior for Ruby, heavily inspired by [this](http://www.rubyfleebie.com/enumerations-and-ruby) and improved upon [another blog post](http://code.dblock.org/how-to-define-enums-in-ruby).
8+
Enum-like behavior for Ruby, heavily inspired by [this](http://www.rubyfleebie.com/enumerations-and-ruby), and improved upon [another blog post](http://code.dblock.org/how-to-define-enums-in-ruby).
99

1010
## Table of Contents
1111

@@ -23,65 +23,65 @@ Enum-like behavior for Ruby, heavily inspired by [this](http://www.rubyfleebie.c
2323
- [Mapping keys to values](#mapping-keys-to-values)
2424
- [Mapping values to keys](#mapping-values-to-keys)
2525
- [Duplicate enumerator keys or duplicate values](#duplicate-enumerator-keys-or-duplicate-values)
26-
- [Inheritance behavior](#inheritance-behavior)
26+
- [Inheritance](#inheritance)
2727
- [Contributing](#contributing)
2828
- [Copyright and License](#copyright-and-license)
2929
- [Related Projects](#related-projects)
3030

3131
## Usage
3232

33-
Enums can be defined and accessed either as constants or class methods, which is a matter of preference.
33+
Enums can be defined and accessed either as constants, or class methods, which is a matter of preference.
3434

3535
### Constants
3636

37-
Define enums and reference them as constants.
37+
Define enums, and reference them as constants.
3838

3939
``` ruby
40-
class Colors
40+
class OrderState
4141
include Ruby::Enum
4242

43-
define :RED, "red"
44-
define :GREEN, "green"
43+
define :CREATED, 'created'
44+
define :PAID, 'paid'
4545
end
4646
```
4747

4848
``` ruby
49-
Colors::RED # "red"
50-
Colors::GREEN # "green"
51-
Colors::UNDEFINED # raises Ruby::Enum::Errors::UninitializedConstantError
52-
Colors.keys # [ :RED, :GREEN ]
53-
Colors.values # [ "red", "green" ]
54-
Colors.to_h # { :RED => "red", :GREEN => "green" }
49+
OrderState::CREATED # 'created'
50+
OrderState::PAID # 'paid'
51+
OrderState::UNKNOWN # raises Ruby::Enum::Errors::UninitializedConstantError
52+
OrderState.keys # [ :CREATED, :PAID ]
53+
OrderState.values # [ 'created', 'paid' ]
54+
OrderState.to_h # { :CREATED => 'created', :PAID => 'paid' }
5555
```
5656

5757
### Class Methods
5858

59-
Define enums reference them as class methods.
59+
Define enums, and reference them as class methods.
6060

6161
``` ruby
6262
class OrderState
6363
include Ruby::Enum
6464

65-
define :created, 'Created'
66-
define :paid, 'Paid'
65+
define :created, 'created'
66+
define :paid, 'paid'
6767
end
6868
```
6969

7070
```ruby
71-
OrderState.created # "Created"
72-
OrderState.paid # "Paid"
71+
OrderState.created # 'created'
72+
OrderState.paid # 'paid'
7373
OrderState.undefined # NoMethodError is raised
7474
OrderState.keys # [ :created, :paid ]
75-
OrderState.values # ["Created", "Paid"]
76-
OrderState.to_h # { :created => 'Created', :paid => 'Paid' }
75+
OrderState.values # ['created', 'paid']
76+
OrderState.to_h # { :created => 'created', :paid => 'paid' }
7777
```
7878

7979
### Default Value
8080

8181
The value is optional. If unspecified, the value will default to the key.
8282

8383
``` ruby
84-
class Defaults
84+
class OrderState
8585
include Ruby::Enum
8686

8787
define :UNSPECIFIED
@@ -90,68 +90,69 @@ end
9090
```
9191

9292
``` ruby
93-
Defaults::UNSPECIFIED # :UNSPECIFIED
94-
Defaults.unspecified # :unspecified
93+
OrderState::UNSPECIFIED # :UNSPECIFIED
94+
OrderState.unspecified # :unspecified
9595
```
9696

9797
### Enumerating
9898

99-
All `Enumerable` methods are supported.
99+
Enums support all `Enumerable` methods.
100100

101101
#### Iterating
102102

103103
``` ruby
104-
Colors.each do |key, enum|
105-
# key and enum.key is :RED, :GREEN
106-
# enum.value is "red", "green"
104+
OrderState.each do |key, enum|
105+
# key and enum.key are :CREATED, :PAID
106+
# enum.value is 'created', 'paid'
107107
end
108108
```
109109

110110
``` ruby
111-
Colors.each_key do |key|
112-
# :RED, :GREEN
111+
OrderState.each_key do |key|
112+
# :CREATED, :PAID
113113
end
114114
```
115115

116116
``` ruby
117-
Colors.each_value do |value|
118-
# "red", "green"
117+
OrderState.each_value do |value|
118+
# 'created', 'paid'
119119
end
120120
```
121121

122122
#### Mapping
123123

124124
``` ruby
125-
Colors.map do |key, enum|
126-
# key and enum.key is :RED, :GREEN
127-
# enum.value is "red", "green"
125+
OrderState.map do |key, enum|
126+
# key and enum.key are :CREATED, :PAID
127+
# enum.value is 'created', 'paid'
128128
[enum.value, key]
129129
end
130130

131-
# => [ ['red', :RED], ['green', :GREEN] ]
131+
# => [ ['created', :CREATED], ['paid', :PAID] ]
132132
```
133133

134134
#### Reducing
135135

136136
``` ruby
137-
Colors.reduce([]) do |arr, (key, enum)|
138-
# key and enum.key is :RED, :GREEN
139-
# enum.value is "red", "green"
137+
OrderState.reduce([]) do |arr, (key, enum)|
138+
# key and enum.key are :CREATED, :PAID
139+
# enum.value is 'created', 'paid'
140140
arr << [enum.value, key]
141141
end
142142

143-
# => [ ['red', :RED], ['green', :GREEN] ]
143+
# => [ ['created', :CREATED], ['paid', :PAID] ]
144144
```
145145

146146
#### Sorting
147+
147148
``` ruby
148-
Colors.sort_by do |key, enum|
149-
# key and enum.key is :RED, :GREEN
150-
# enum.value is "red", "green"
151-
enum.value
149+
OrderState.sort_by do |key, enum|
150+
# key and enum.key are :CREATED, :PAID
151+
# enum.value is 'created', 'paid'
152+
enum.value.length
152153
end
153154

154-
# => [ [:GREEN, #<Colors:...>], [:RED, #<Colors:...>] ]
155+
# => [[:PAID, #<OrderState:0x0 @key=:PAID, @value="paid">], [:CREATED, #<OrderState:0x1 @key=:CREATED, @value="created">]]
155156
```
156157

157158
### Hashing
@@ -161,113 +162,106 @@ Several hash-like methods are supported.
161162
#### Retrieving keys and values
162163

163164
``` ruby
164-
Colors.keys
165-
# => [:RED, :GREEN]
165+
OrderState.keys
166+
# => [:CREATED, :PAID]
166167

167-
Colors.values
168-
# => ["red", "green"]
168+
OrderState.values
169+
# => ['created', 'paid']
169170
```
170171

171172
#### Mapping keys to values
172173

173174
``` ruby
174-
Colors.key?(:RED)
175+
OrderState.key?(:CREATED)
175176
# => true
176177

177-
Colors.value(:RED)
178-
# => "red"
178+
OrderState.value(:CREATED)
179+
# => 'created'
179180

180-
Colors.key?(:BLUE)
181+
OrderState.key?(:FAILED)
181182
# => false
182183

183-
Colors.value(:BLUE)
184+
OrderState.value(:FAILED)
184185
# => nil
185186
```
186187

187188
#### Mapping values to keys
188189

189190
``` ruby
190-
Colors.value?('green')
191+
OrderState.value?('paid')
191192
# => true
192193

193-
Colors.key('green')
194-
# => :GREEN
194+
OrderState.key('paid')
195+
# => :PAID
195196

196-
Colors.value?('yellow')
197+
OrderState.value?('failed')
197198
# => false
198199

199-
Colors.key('yellow')
200+
OrderState.key('failed')
200201
# => nil
201202
```
202203

203204
### Duplicate enumerator keys or duplicate values
204205

205-
Defining duplicate enums will raise a `Ruby::Enum::Errors::DuplicateKeyError`. Moreover a duplicate
206-
value is not allowed. Defining a duplicate value will raise a `Ruby::Enum::Errors::DuplicateValueError`.
207-
The following declarations will both raise an exception:
206+
Defining duplicate enums raises `Ruby::Enum::Errors::DuplicateKeyError`.
208207

209208
```ruby
210-
class Colors
211-
include Ruby::Enum
209+
class OrderState
210+
include Ruby::Enum
212211

213-
define :RED, "red"
214-
define :RED, "my red" # will raise a DuplicateKeyError exception
215-
end
212+
define :CREATED, 'created'
213+
define :CREATED, 'recreated' # raises DuplicateKeyError
214+
end
215+
```
216216

217-
# The following will raise a DuplicateValueError
218-
class Colors
219-
include Ruby::Enum
217+
Defining a duplicate value raises `Ruby::Enum::Errors::DuplicateValueError`.
220218

221-
define :RED, 'red'
222-
define :SOME, 'red' # Boom
223-
end
219+
```ruby
220+
class OrderState
221+
include Ruby::Enum
222+
223+
define :CREATED, 'created'
224+
define :RECREATED, 'created' # raises DuplicateValueError
225+
end
224226
```
225227

226-
The `DuplicateValueError` exception is thrown to be consistent with the unique key constraint.
227-
Since keys are unique there is no way to map values to keys using `Colors.value('red')`
228+
The `DuplicateValueError` exception is raised to be consistent with the unique key constraint. Since keys are unique, there needs to be a way to map values to keys using `OrderState.value('created')`.
228229

229-
### Inheritance behavior
230+
### Inheritance
230231

231-
Inheriting from a `Ruby::Enum` class, all defined enums in the parent class will be accessible in sub classes as well.
232-
Sub classes can also provide extra enums as usual.
232+
When inheriting from a `Ruby::Enum` class, all defined enums in the parent class will be accessible in sub classes as well. Sub classes can also provide extra enums, as usual.
233233

234234
``` ruby
235-
class PrimaryColors
235+
class OrderState
236236
include Ruby::Enum
237237

238-
define :RED, 'RED'
239-
define :GREEN, 'GREEN'
240-
define :BLUE, 'BLUE'
238+
define :CREATED, 'CREATED'
239+
define :PAID, 'PAID'
241240
end
242241

243-
class RainbowColors < PrimaryColors
244-
define :ORANGE, 'ORANGE'
245-
define :YELLOW, 'YELLOW'
246-
define :INIDGO, 'INIDGO'
247-
define :VIOLET, 'VIOLET'
242+
class ShippedOrderState < OrderState
243+
define :PREPARED, 'PREPARED'
244+
define :SHIPPED, 'SHIPPED'
248245
end
249246
```
250247

251248
``` ruby
252-
RainbowColors::RED # 'RED'
253-
RainbowColors::ORANGE # 'ORANGE'
254-
RainbowColors::YELLOW # 'YELLOW'
255-
RainbowColors::GREEN # 'GREEN'
256-
RainbowColors::BLUE # 'BLUE'
257-
RainbowColors::INIDGO # 'INIDGO'
258-
RainbowColors::VIOLET # 'VIOLET'
249+
ShippedOrderState::CREATED # 'CREATED'
250+
ShippedOrderState::PAID # 'PAID'
251+
ShippedOrderState::PREPARED # 'PREPARED'
252+
ShippedOrderState::SHIPPED # 'SHIPPED'
259253
```
260254

261255
The `values` class method will enumerate the values from all base classes.
262256

263257
``` ruby
264-
PrimaryColors.values # ['RED', 'GREEN', 'BLUE']
265-
RainbowColors.values # ['RED', 'ORANGE', 'YELLOW', 'GREEN', 'BLUE', 'INIDGO', 'VIOLET']
258+
OrderState.values # ['CREATED', 'PAID']
259+
ShippedOrderState.values # ['CREATED', 'PAID', 'PREPARED', SHIPPED']
266260
```
267261

268262
## Contributing
269263

270-
You're encouraged to contribute to this gem. See [CONTRIBUTING](CONTRIBUTING.md) for details.
264+
You're encouraged to contribute to ruby-enum. See [CONTRIBUTING](CONTRIBUTING.md) for details.
271265

272266
## Copyright and License
273267

0 commit comments

Comments
 (0)