https://github.com/polm/philtre
Search objects with a familiar syntax.
https://github.com/polm/philtre
search
Last synced: 6 months ago
JSON representation
Search objects with a familiar syntax.
- Host: GitHub
- URL: https://github.com/polm/philtre
- Owner: polm
- Created: 2016-03-16T14:48:02.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2017-04-11T13:27:19.000Z (over 9 years ago)
- Last Synced: 2025-11-27T09:32:21.058Z (8 months ago)
- Topics: search
- Language: LiveScript
- Size: 119 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Philtre
A library for searching objects, with syntax inspired by Gmail and Github searches.
At the core of Philtre is a function (`philtre`) that takes two arguments: a query (as a string) and a list of Javascript objects. It then returns the objects that match the query.
You can try this out using the included command line script and sample data file. The command line script reads one JSON object per line from stdin (like [jq](https://stedolan.github.io/jq/)), filters them using the supplied query, and prints the specified field:
philtre [query] [field-to-print] < [input.json]
To try it out yourself:
mkdir fiddle && cd fiddle && git clone https://github.com/polm/philtre.git
./bin/philtre "#restaurants" title < data/dampfkraft.json
./bin/philtre "is:location #restaurants" title < data/dampfkraft.json
./bin/philtre "not is:location #restaurants" title < data/dampfkraft.json
./bin/philtre "is:location not #restaurants" title < data/dampfkraft.json
### Supported Keywords
Note that except for values before a colon in keywords using them (which must match the regex `[A-z]*`), anything may be quoted to preserve whitespace or otherwise special characters.
| keyword | effect |
| --- | --- |
| (default) | non-special words check for a string match on every field of the object. |
| `:has:[something]` | true if the object has a field named `something` |
| `:is:[something]` | same as `:has:` |
| `[key]:[value]` | true if `value` equals the `key` property |
| `AND` | does nothing (it's the default) |
| `OR` | logical OR of the conditions on either side |
| `NOT` | negates the next keyword |
| `-[something]` | negates the next keyword; unlike `not` doesn't need a space |
| `(` and `)` | allows grouping of terms |
| `#[xxx]` | true if the `.tags` property contains `xxx` |
| `:before:[xxx]` | true if the `.date` property is less than `xxx` |
| `:after:[xxx]` | true if the `.date` property is greater than `xxx` |
| `:sort:[field]` | sorts on `field` |
| `:sortr:[field]` | sorts on `field` in the order opposite `:sort:` |
| `:limit:[count]` | only shows up to `count` results |
For keyword queries like `[key]:[value]`, by quoting the value you can also use comparisons such as `[key]:"<[value]"`, `[key]:">=[value]"`; you can also use ranges with the syntax `[key]:"low .. high"` (including spaces around the dots). This syntax is borrowed from [Github's search syntax](https://help.github.com/articles/search-syntax/).
Not `:sort:` and `:limit:` only work in the top-level of queries; they will do nothing if contained in parentheses.
You may have some questions:
**Why are `is` and `has` the same?**
In looking at sample data it seemed that either relationship could be expressed by having an object property. I might revisit this.
**How does the tag feature work?**
If it's used, it assumes that each object has a property called `tags` that's a list of strings. It checks if the string after the `#` is in that list. This seems to be a pretty common convention for tagged data.
### TODO
See [issues](https://github.com/polm/philtre/issues).
### Similar Work
[Ghost Query Language](https://github.com/TryGhost/GQL) has basically the same goal but is intended for use via an HTTP API.
### License
WTFPL, do as you please.
-POLM