documentation request

[stvnmntjy]

Hi. Thanks for this useful and low buy-in JSON library.

Could you revise the documentation or at least provide examples for each key aspect of the CRUD operations?

Things like: (btw, these may not be mutually exclusive or possible? I'm spitballin'...)

1. Selecting an object based on a property's value.
2. Selecting such an object when it's part of an array.
3. Selecting such an object when it's part of an object.
4. Filtering examples of all the above.
5. Examples of the equality operators both as assertion and as part of a query.
6. Advanced queries.
7. *

Like, take your Twitter JSON and then a quick snippet example highlighting all CRUD ops covering all aspects of JSON (arrays, properties, objects, core atomics, etc) the library supports. One-liners with terse, meaningful accompanying information.

Or am I missing this documentation?

I'd PR but I'm on the newb side, looking to utilize more of this good library.

[julesfern]

Hey there!

So I believe I can check these off in the current documentation:

1. Present
2. Present, could be called out more
3. Present, could be called out more
4. Filtering is just nested queries, so a filtering example for each of the above would be redundant. This itself could be called out more.
5. This sounds like it could be redundant, but the fact that you're asking the question indicates that this isn't explicitly called out in the documentation.
6. Can you give an example?

Overall these missing points sound like a structural problem with the docs, where all the info is buried in paragraphs instead of being called out directly. We could look to add a "SpahQL by Example" section which covers this stuff nice and quickly before linking into the deeper docs?

I'd much rather help you PR so you can get the documentation you want than go through a long revision process - and changing the documentation is easy :)

Everything is in readme.mdown in the root. The documentation at github.io is generated from this file. Feel free to fork, improve, and submit back - and ask any questions you want here, be it related to SpahQL or contributing to projects on GH.

[stvnmntjy]

Here's a fiddle that can be massaged over time to benefit this request. The code begins after a local include of minified SpahQL.

There's a couple example queries of the type I'm thinking of and do not know the answers myself. Feel free to update the fiddle with any answers you can provide (and anything else you feel is helpful).

We can make this a WIP. In the end it may turn out to be the kind of practical documentation serving this issue's purpose.

[julesfern]

Good grief, sorry it took me so long to return here - was off travelling. So the fiddle option is interesting, but it's a shame that the bulk of the JS pane is taken up by the lib and data structure rather than the code acting on it. I wonder if we might be better served to just add some better or more qualified examples to the REPL page if what we're hoping to do is to show off a variety of syntaxes. What do you think?