filterparams 0.9.1 → 0.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. checksums.yaml +4 -4
  2. metadata +4 -202
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: eccbf86937a65862760d9b9856f638b9fbcfba53
4
- data.tar.gz: 9421ba18a6af48111c5da4983d1339afde31dc61
3
+ metadata.gz: 4d82dc362a305f822045eb821bd97bc969a63f92
4
+ data.tar.gz: b2d1063e5eae7d3944c5502d91baf0099d6f8722
5
5
  SHA512:
6
- metadata.gz: dc6bcb9a1600115563e86a1da14c7238fe284284875c90d624a8982428c01fa9ddc040e78a3b51bb09f2f81042d6338b2de7502814ba63040995dc3b7d448add
7
- data.tar.gz: 9823903da6ba5dfea2c80a6fc3a00a54778dc361d7bf955930df967f408c5e67e9d5b6a601c48e8ce4dd8872893de12cd8b9f27fb07b3382b62eac12c4f2f8f6
6
+ metadata.gz: 683f2c252435e5d8bb6cf30405326a535b1eff2ca0a5b07b1b7c4f98e8049f939ddbacc1f6a07507320c718e7e973907378f00204b0cb1f0f163386da2dc7407
7
+ data.tar.gz: 2f4a75c49cf62af306496b5f08769b0297ec1cc0ecaa5db1f7bd86d5db6cdc805daeff9088f69c0db8fdd5012ac16837b38266ba2aa3c731dc72e57692b5fd90
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: filterparams
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.9.1
4
+ version: 0.9.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Christoph Brand
@@ -128,207 +128,9 @@ dependencies:
128
128
  - - ">="
129
129
  - !ruby/object:Gem::Version
130
130
  version: 1.6.0
131
- description: |
132
- # Ruby Filterparams #
133
-
134
- Filterparams is a library for specifying filters through a REST API
135
- on collection resources on top of HTTP. It provides the capability
136
- to specify SQL-like syntax on top of query parameters.
137
-
138
- Due to it's intended use of building [JSONAPI](http://jsonapi.org/)
139
- libraries with this definition, it is compatible with the definition
140
- and encapsulates it's syntax through the prefixed `filter` parameters.
141
-
142
- ## Installation ##
143
-
144
- The library is available through the `filterparams` gem on [RubyGems](https://rubygems.org/gems/filterparams)
145
- and thus can be installed through the command line or by adding the package to
146
- your Gemfile.
147
-
148
- ```
149
- gem install filterparams
150
- ```
151
-
152
- ## Example ##
153
-
154
- Given the URL (non URL escaped for better readability):
155
-
156
- ```
157
- /users?filter[param][name][like][no_brand_name]=doe&filter[param][first_name]=doe%&filter[binding]=(!no_brand_name&first_name)&filter[order]=name&filter[order]=desc(first_name)
158
- ```
159
-
160
- It can be parsed with the following code:
161
-
162
- ```ruby
163
- require 'uri'
164
- require 'cgi'
165
- require 'filterparams'
166
-
167
- url = 'http://www.example.com/users?' +
168
- 'filter[param][name][like][no_brand_name]=doe' +
169
- '&filter[param][first_name]=doe%' +
170
- '&filter[binding]=%28%21no_brand_name%26first_name%29' +
171
- '&filter[order]=name&filter[order]=desc(first_name)'
172
-
173
- data = CGI.parse(URI.parse(url).query)
174
-
175
- Filterparams::extract_query(data)
176
- ```
177
-
178
- This would result into a query instance being produced with the
179
- following data:
180
-
181
- ```
182
- #<Filterparams::Query:0x007ff78b1a51c8
183
- @filters=
184
- #<Filterparams::And:0x007ff78b1a57e0
185
- @left=
186
- #<Filterparams::Not:0x007ff78b1a6ed8
187
- @inner=
188
- #<Filterparams::Parameter:0x007ff78b1ee940
189
- @alias="no_brand_name",
190
- @filter="like",
191
- @name="name",
192
- @value="doe">>,
193
- @right=
194
- #<Filterparams::Parameter:0x007ff78b1ee918
195
- @alias=nil,
196
- @filter=nil,
197
- @name="first_name",
198
- @value="doe%">>,
199
- @orders=
200
- [#<Filterparams::Order:0x007ff78b1ee5f8 @direction="asc", @name="name">,
201
- #<Filterparams::Order:0x007ff78b1ee3a0
202
- @direction="desc",
203
- @name="first_name">]>
204
- ```
205
-
206
- The orders can be accessed through the `.orders` method and the filter
207
- binding through `.filters`.
208
-
209
- ## Syntax ##
210
-
211
- All arguments must be prefixed by "filter". It is possible to
212
- query for specific data with filters, apply orders to the result
213
- and to combine filters through AND, NOT and OR bindings.
214
-
215
- The syntax builds under the filter parameter a virtual object.
216
- The keys of the object are simulated through specifying `[{key}]`
217
- in the passed query parameter. Thus `filter[param]` would point
218
- to the param key in the filter object.
219
-
220
- ### Filter specification ###
221
-
222
- The solution supports to query data through the `param` subkey.
223
-
224
- ```
225
- filter[param][{parameter_name}][{operation}][{alias}] = {to_query_value}
226
- ```
227
-
228
- The `operation` and `alias` parameters may be omitted. If no
229
- `alias` is provided the given parameter name is used for it.
230
- If no `operation` is given, the default one is used (in the
231
- example this would be equal).
232
-
233
- Example:
234
- ```
235
- filter[param][phone_number][like]=001%
236
- ```
237
-
238
- This would add a filter to all phone numbers which start with "001".
239
-
240
- ### Filter binding ###
241
-
242
- Per default all filters are combined through AND clauses.
243
- You can change that by specifying the `filter[binding]` argument.
244
-
245
- This is where the aliases which you can define come into place.
246
- The binding provides means to combine filters with AND and OR.
247
- Also you are able to negate filters here.
248
-
249
- The filters are addressed by their alias or name, if no alias is
250
- provided.
251
-
252
- If you have a filter `search_for_name`, `search_for_phone_number`
253
- and `search_for_account_number` defined you can say
254
- `search_for_name OR NOT search_for_number AND search_for_account_number`
255
- by specifying the following filter:
256
-
257
- ```
258
- filter[binding]=search_for_name|(!search_for_phone_number&search_for_account_number)
259
- ```
260
-
261
- Even though the brackets are useless here, you can use them in
262
- more complex filters.
263
-
264
- The following table summarizes the possible configuration options:
265
- <table>
266
- <thead>
267
- <tr>
268
- <th>Type</th>
269
- <th>Symbol</th>
270
- <th>Example</th>
271
- </tr>
272
- </thead>
273
- <tbody>
274
- <tr>
275
- <td>AND</td>
276
- <td>&</td>
277
- <td>a&b</td>
278
- </tr>
279
- <tr>
280
- <td>OR</td>
281
- <td>|</td>
282
- <td>a|b</td>
283
- </tr>
284
- <tr>
285
- <td>NOT</td>
286
- <td>!</td>
287
- <td>!a</td>
288
- </tr>
289
- <tr>
290
- <td>Bracket</td>
291
- <td>()</td>
292
- <td>(a|b)&c</td>
293
- </tr>
294
- </tbody>
295
- </table>
296
-
297
- ### Ordering ###
298
-
299
- To specify a sort order of the results the `filter[order]` parameter
300
- may be used. The value can be specified multiple times. To add
301
- ordering you have to provide the name of the parameter which should
302
- be ordered, not its alias!
303
-
304
- If you want to order by `name`, `first_name` and in reverse order
305
- `balance` you can do so by specifying the following query url
306
- parameters:
307
-
308
- ```
309
- filter[order]=name&filter[order]=first_name&filter[order]=desc(balance)
310
- ```
311
-
312
- As you can see the `desc()` definition can be used to indicate
313
- reverse ordering.
314
-
315
- ## License ##
316
-
317
- The project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
318
-
319
- ## Used libraries ##
320
-
321
- For parsing the query parameters the [`parslet`](https://kschiess.github.io/parslet/)
322
- library is used. It is released under the [MIT License](https://github.com/kschiess/parslet/blob/master/LICENSE).
323
-
324
- ## Other Languages ##
325
-
326
- This is a list of projects implementing the same API for other languages.
327
- Currently this list only has one entry.
328
-
329
- - Go - [go-filterparams](https://github.com/cbrand/go-filterparams)
330
- - Python - [python-filterparams](https://github.com/cbrand/python-filterparams)
331
- - JavaScript (Client) - [filterparams](https://github.com/cbrand/js-filterparams-client)
131
+ description: Parses filter parameters compatible query parameters and returns an object
132
+ which can be used to be mapped on top of a backend system. More information is available
133
+ on Github ( https://github.com/cbrand/ruby-filterparams ).
332
134
  email: christoph@brand.rest
333
135
  executables: []
334
136
  extensions: []