strings-inflection 0.1.0

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 56350abef180f65e710bcffdb405afece3208f16f233af6dc6c7e7cb038b9837
4
+ data.tar.gz: d64806234e1c4c918a7ae1a0b9921aeb1eadf04e098db7156b242567aeddd1f6
5
+ SHA512:
6
+ metadata.gz: 74c2ecc96107c84c714acd500ec65d9d02182521f880aa74c3fd25d0c972d6b49e0a996f285aac25f18b5a6a1f8cac654bc781f10c7670b33cae06d5eebf10f3
7
+ data.tar.gz: 458b8e233e0d34f6ba79acc5b9af25cf69e5a4db97a1736685352fed160eee53495696a86a34494d4f5e8ba27861ebc0c1b0c552baf8cb738460fcb60b986314
@@ -0,0 +1,7 @@
1
+ # Change log
2
+
3
+ ## [v0.1.0] - 2019-12-03
4
+
5
+ * Initial implementation and release
6
+
7
+ [v0.1.0]: https://github.com/piotrmurach/strings-inflection/compare/v0.1.0
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2019 Piotr Murach
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
@@ -0,0 +1,424 @@
1
+ <div align="center">
2
+ <img width="225" src="https://github.com/piotrmurach/strings/blob/master/assets/strings_logo.png" alt="strings logo" />
3
+ </div>
4
+
5
+ # Strings::Inflection
6
+
7
+ [![Gem Version](https://badge.fury.io/rb/strings-inflection.svg)][gem]
8
+ [![Build Status](https://secure.travis-ci.org/piotrmurach/strings-inflection.svg?branch=master)][travis]
9
+ [![Build status](https://ci.appveyor.com/api/projects/status/huj82599jbk2quv2?svg=true)][appveyor]
10
+ [![Maintainability](https://api.codeclimate.com/v1/badges/f7ecb5bf87696e522ccb/maintainability)][codeclimate]
11
+ [![Coverage Status](https://coveralls.io/repos/github/piotrmurach/strings-inflection/badge.svg?branch=master)][coverage]
12
+ [![Inline docs](http://inch-ci.org/github/piotrmurach/strings-inflection.svg?branch=master)][inchpages]
13
+
14
+ [gem]: http://badge.fury.io/rb/strings-inflection
15
+ [travis]: http://travis-ci.org/piotrmurach/strings-inflection
16
+ [appveyor]: https://ci.appveyor.com/project/piotrmurach/strings-inflection
17
+ [codeclimate]: https://codeclimate.com/github/piotrmurach/strings-inflection/maintainability
18
+ [coverage]: https://coveralls.io/github/piotrmurach/strings-inflection?branch=master
19
+ [inchpages]: http://inch-ci.org/github/piotrmurach/strings-inflection
20
+
21
+ > Inflects English nouns and verbs.
22
+
23
+ **Strings::Inflection** provides English inflections of nouns and verbs component for [Strings](https://github.com/piotrmurach/strings).
24
+
25
+ ## Motivation
26
+
27
+ The goal is to provide a comprehensive way to inflect most nouns and verbs in English. The algorithms that this gem uses are based on the analysis of 7,000 most frequently used nouns and 6,000 most used verbs in English language. Because of this you will get correct inflections for most words:
28
+
29
+ ```ruby
30
+ Strings::Inflection.pluralize("cod") # => "cod"
31
+ Strings::Inflection.pluralize("codex") # => "codices"
32
+ Strings::Inflection.pluralize("criterion") # => "criteria"
33
+ Strings::Inflection.pluralize("vertebra") # => "vertebrae"
34
+ ```
35
+
36
+ ## Installation
37
+
38
+ Add this line to your application's Gemfile:
39
+
40
+ ```ruby
41
+ gem 'strings-inflection'
42
+ ```
43
+
44
+ And then execute:
45
+
46
+ $ bundle
47
+
48
+ Or install it yourself as:
49
+
50
+ $ gem install strings-inflection
51
+
52
+ ## Contents
53
+
54
+ * [1. Usage](#1-usage)
55
+ * [2. API](#2-api)
56
+ * [2.1 inflect](#21-inflect)
57
+ * [2.1.1 template](#211-template)
58
+ * [2.2 singularize](#22-singularize)
59
+ * [2.3 singular?](#23-singular)
60
+ * [2.4 pluralize](#24-pluralize)
61
+ * [2.5 plural?](#25-plural)
62
+ * [2.6 join_words](#26-join_words)
63
+ * [2.7 configure](#27-configure)
64
+ * [3. Extending String class](#3-extending-string-class)
65
+
66
+ ## 1. Usage
67
+
68
+ **Strings::Inflection** provides a generic `inflect` method for transforming noun or verb inflections. In the most common case, it assumes that you wish to transform a noun to another form based on count:
69
+
70
+ ```ruby
71
+ Strings::Inflection.inflect("error", 3)
72
+ # => "errors"
73
+ ```
74
+
75
+ As a shortcut, when you wish to always convert a word to singular form use `singularize` or `pluralize` for the opposite:
76
+
77
+ ```ruby
78
+ Strings::Inflection.singularize("errors") # => "error"
79
+ Strings::Inflection.pluralize("error") # => "errors"
80
+ Strings::Inflection.singularize("try", term: :verb) # => "tries"
81
+ Strings::Inflection.pluralize("tries", term: :verb) # => "try"
82
+ ```
83
+
84
+ Alternatively, you can convert words into a noun or verb object. This way you gain access to `singular`and `plural` methods:
85
+
86
+ ```ruby
87
+ Strings::Inflection::Noun("errors").singular # => "error"
88
+ Strings::Inflection::Noun("error").plural # => "errors"
89
+ Strings::Inflection::Verb("try").singular # => "tries"
90
+ Strings::Inflection::Verb("tries").plural # => "try"
91
+ ```
92
+
93
+ The `inflect` method also accepts a mustache-like template to inflect more complex phrases and sentences:
94
+
95
+ ```ruby
96
+ Strings::Inflection.inflect("{{#:count}} {{N:error}} {{V:was}} found", 3)
97
+ # => "3 errors were found"
98
+ ```
99
+
100
+ To change any inflection rules, you can change them using `configure`. By default the rules only apply to nouns.
101
+
102
+ ```ruby
103
+ Strings::Inflection.configure do |config|
104
+ config.plural "index", "indexes"
105
+ config.singular "axes", "ax"
106
+ end
107
+ ```
108
+
109
+ Then the inflection will behave like this:
110
+
111
+ ```ruby
112
+ Strings::Inflection.pluralize("index") # => "indexes"
113
+ Strings::Inflection.singularize("axes") # => "ax"
114
+ ```
115
+
116
+ ## 2. API
117
+
118
+ ### 2.1 inflect
119
+
120
+ In the most common case, to change a noun's inflection use `inflect` method with the word and a count. By default `inflect` assumes a noun.
121
+
122
+ For example, to inflect the noun `error` to its plural form do:
123
+
124
+ ```ruby
125
+ Strings::Inflection.inflect("error", 2) # => "errors"
126
+ ```
127
+
128
+ And to inflect a verb, use the `:term` option:
129
+
130
+ ```ruby
131
+ Strings::Inflection.inflect("tries", 2, term: :verb) # => "try"
132
+ ```
133
+
134
+ For more complex cases when you want to inflect parts of a sentence, the `inflect` provides tags in a template.
135
+
136
+ For example, you can inflect a noun and a verb to display information based on the count:
137
+
138
+ ```ruby
139
+ Strings::Inflection.inflect("{{#:count}} {{N:error}} {{V:was}} found", 2)
140
+ # => "2 errors were found"
141
+ ```
142
+
143
+ #### 2.1.1 template
144
+
145
+ The template inflects any content inside mustache-like braces `{{...}}`. The general form of content inside tag is `{{Xmod:word}}` where:
146
+
147
+ * `X` informs a grammatical function to apply to word out of `N` or `V` and `#`.
148
+ * `mod` apply zero or more modifiers to word transformation.
149
+ * `word` represents the string to inflect.
150
+
151
+ The available tags are:
152
+
153
+ `{{#: count }}`
154
+
155
+ The first type of tag is the count tag. By default, this tag will display the count inside the evaluated string.
156
+
157
+ ```ruby
158
+ String::Inflection.inflect("{{#:count}} found", 2)
159
+ # => "2 found"
160
+ ```
161
+
162
+ There is an `f` option that will provide a fuzzy estimation of the count:
163
+
164
+ ```ruby
165
+ String::Inflection.inflect("{{#f:count}}", 0) # => "no"
166
+ String::Inflection.inflect("{{#f:count}}", 1) # => "one"
167
+ String::Inflection.inflect("{{#f:count}}", 2) # => "a couple of"
168
+ String::Inflection.inflect("{{#f:count}}", 3) # => "a few"
169
+ String::Inflection.inflect("{{#f:count}}", 6) # => "several"
170
+ String::Inflection.inflect("{{#f:count}}", 12) # => "many"
171
+ ```
172
+
173
+ `{{N: word }}`
174
+
175
+ This tag inflects a noun into a singular or plural form based on the provided count.
176
+
177
+ ```ruby
178
+ Strings::Inflection.inflect("{{#:count}} {{N:error}} found", 3)
179
+ # => "3 errors found"
180
+ ```
181
+
182
+ You can supply `s` or `p` options to always force a noun to be singular or plural form.
183
+
184
+ ```ruby
185
+ Strings::Inflection.inflect("{{#:count}} {{Ns:error}} found", 3)
186
+ # => "3 error found"
187
+ ```
188
+
189
+ `{{V: word }}`
190
+
191
+ This tag inflects a verb into appropriate form based on the provided count.
192
+
193
+ ```ruby
194
+ Strings::Inflection.inflect("There {{V:were}} {{#:count}} {{N:match}} found", 1)
195
+ # => "There was 1 match found"
196
+ ```
197
+
198
+ ### 2.2 singularize
199
+
200
+ You can transform a noun or a verb into singular form with `singularize` method. By default it assumes a noun but you can change this with `:term` option:
201
+
202
+ ```ruby
203
+ Strings::Inflection.singularize("errors") # => "error"
204
+ Strings::Inflection.singularize("indices") # => "index"
205
+ Strings::Inflection.singularize("index", term: :verb) # => "indexes"
206
+ Strings::Inflection.singularize("try", term: :verb) # => "tries"
207
+ ```
208
+
209
+ It will handle inflecting irregular nouns or verbs as well:
210
+
211
+ ```ruby
212
+ Strings::Inflection.singularize("feet") # => "foot"
213
+ Strings::Inflection.singularize("are", term: :verb) # => "is"
214
+ Strings::Inflection.singularize("go", term: :verb) # => "goes"
215
+ ```
216
+
217
+ This method won't change inflection if it already is in the correct form:
218
+
219
+ ```ruby
220
+ Strings::Inflection.singularize("index") # => "index"
221
+ Strings::Inflection.singularize("sees") # => "sees"
222
+ ```
223
+
224
+ ### 2.3 singular?
225
+
226
+ To check if a noun or a verb is in a singular form use `singular?`:
227
+
228
+ ```ruby
229
+ Strings::Inflection.singular?("errors") # => false
230
+ Strings::Inflection.singular?("index") # => true
231
+ Strings::Inflection.singular?("try", term: :verb) # => false
232
+ Strings::Inflection.singular?("goes", term: :verb) # => true
233
+ ```
234
+
235
+ You can also convert a word to a noun or verb object:
236
+
237
+ ```ruby
238
+ Strings::Inflection::Noun("errors").singular? # => false
239
+ Strings::Inflection::Noun("index").singular? # => true
240
+ Strings::Inflection::Verb("try").singular? # => false
241
+ Strings::Inflection::Verb("goes").singular? # => true
242
+ ```
243
+
244
+ ### 2.4 pluralize
245
+
246
+ You can transform a noun or a verb into plural form with `pluralize` method. By default it assumes a noun but you can change this with `:term` option:
247
+
248
+ ```ruby
249
+ Strings::Inflection.pluralize("error") # => "errors"
250
+ Strings::Inflection.pluralize("index") # => "indices"
251
+ Strings::Inflection.pluralize("indexes", term: :verb) # => "index"
252
+ Strings::Inflection.pluralize("tries", term: :verb) # => "try"
253
+ ```
254
+
255
+ It will handle inflecting irregular nouns or verbs as well:
256
+
257
+ ```ruby
258
+ Strings::Inflection.pluralize("foot") # => "feet"
259
+ Strings::Inflection.pluralize("is", term: :verb) # => "are"
260
+ Strings::Inflection.pluralize("goes", term: :verb) # => "go"
261
+ ```
262
+
263
+ This method won't change inflection if it already is in the correct form:
264
+
265
+ ```ruby
266
+ Strings::Inflection.pluralize("indices") # => "indices"
267
+ Strings::Inflection.pluralize("go") # => "go"
268
+ ```
269
+
270
+ ### 2.5 plural?
271
+
272
+ To check if a noun or a verb is in a plural form use `plural?`:
273
+
274
+ ```ruby
275
+ Strings::Inflection.plural?("errors") # => true
276
+ Strings::Inflection.plural?("index") # => false
277
+ Strings::Inflection.plural?("try", term: :verb) # => true
278
+ Strings::Inflection.plural?("goes", term: :verb) # => false
279
+ ```
280
+
281
+ You can also convert a word to a noun or verb object:
282
+
283
+ ```ruby
284
+ Strings::Inflection::Noun("errors").plural? # => true
285
+ Strings::Inflection::Noun("index").plural? # => false
286
+ Strings::Inflection::Verb("try").plural? # => true
287
+ Strings::Inflection::Verb("goes").plural? # => false
288
+ ```
289
+
290
+ ### 2.6 join_words
291
+
292
+ To join an array of words into a single sentence use `join_words` method.
293
+
294
+ For example, to join three words:
295
+
296
+ ```ruby
297
+ Strings::Inflection.join_words("one", "two", "three")
298
+ # => "one, two, and three"
299
+ ```
300
+
301
+ To join words without Oxford style comma use `:final_separator`:
302
+
303
+ ```ruby
304
+ Strings::Inflection.join_words("one", "two", "three", final_separator: "")
305
+ # => "one, two and three"
306
+ ```
307
+
308
+ To join words with custom separators:
309
+
310
+ ```ruby
311
+ options = {
312
+ separator: " or ",
313
+ final_separator: " or at least ",
314
+ conjunctive: ""
315
+ }
316
+ Strings::Inflection.join_words("one", "two", "three", **options)
317
+ # => "one or two or at least three"
318
+ ```
319
+
320
+ You can also use noun objects to join words. We could do the above:
321
+
322
+ ```ruby
323
+ N = Strings::Inflection::Noun
324
+ (N("one") + "two" + "three").join_words
325
+ # => "one, two, and three"
326
+ ```
327
+
328
+ ### 2.7 configure
329
+
330
+ To change any inflection rules use `configure` with a block. By default the rules only apply to nouns.
331
+
332
+ Inside the block, the configuration exposes few methods:
333
+
334
+ * `plural` - add plural form inflection rule
335
+ * `singular` - add singular form inflection rule
336
+ * `rule` - add singular and plural form inflection rule
337
+ * `uncountable` - add uncountable nouns
338
+
339
+ For example, to add new plural and singular rules for the `index` and `ax` nouns do:
340
+
341
+ ```ruby
342
+ Strings::Inflection.configure do |config|
343
+ config.plural "index", "indexes"
344
+ config.singular "axes", "ax"
345
+ end
346
+ ```
347
+
348
+ To add a rule for both singular and plural inflections do:
349
+
350
+ ```ruby
351
+ Strings::Inflection.configure do |config|
352
+ config.rule "ax", "axes"
353
+ end
354
+ ```
355
+
356
+ To add an uncountable noun do:
357
+
358
+ ```ruby
359
+ Strings::Inflection.configure do |config|
360
+ config.uncountable "east", "earnings"
361
+ end
362
+ ```
363
+
364
+ Now, no inflection will be applied:
365
+
366
+ ```ruby
367
+ Strings::Inflection.inflect("earnings", 1) # => "earnings"
368
+ Strings::Inflection.inflect("east", 2) # => "east"
369
+ ```
370
+
371
+ ## 3. Extending String class
372
+
373
+ Though it is highly discouraged to pollute core Ruby classes, you can add the required methods to `String` class by using refinements.
374
+
375
+ For example, if you wish to only extend strings with `inflect` method do:
376
+
377
+ ```ruby
378
+ module MyStringExt
379
+ refine String do
380
+ def inflect(*args, **options)
381
+ Strings::Inflection.inflect(self, *args, **options)
382
+ end
383
+ end
384
+ end
385
+ ```
386
+
387
+ Then `inflect` method will be available for any strings where refinement is applied:
388
+
389
+ ```ruby
390
+ using MyStringExt
391
+
392
+ "error".inflect(2) # => "errors"
393
+ "are".inflect(1, term: :verb) # => "is"
394
+ ```
395
+
396
+ However, if you want to include all the **Strings::Inflection** methods, you can use provided extensions file:
397
+
398
+ ```ruby
399
+ require "strings/inflect/extensions"
400
+
401
+ using Strings::Inflection::Extensions
402
+ ```
403
+
404
+ ## Development
405
+
406
+ After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
407
+
408
+ To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
409
+
410
+ ## Contributing
411
+
412
+ Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/strings-inflect. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
413
+
414
+ ## License
415
+
416
+ The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
417
+
418
+ ## Code of Conduct
419
+
420
+ Everyone interacting in the Strings::Inflection project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/strings-inflect/blob/master/CODE_OF_CONDUCT.md).
421
+
422
+ ## Copyright
423
+
424
+ Copyright (c) 2019 Piotr Murach. See LICENSE for further details.