Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doco changes #24

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

doco changes #24

wants to merge 2 commits into from

Conversation

soniah
Copy link
Contributor

@soniah soniah commented Jun 3, 2020

No description provided.

@ldn-softdev
Copy link
Owner

  1. lib/jtc_guide.hpp:
    Hmmm, do you think debugging (-d) is the option regular users would ever use (and hence worth mentioning in the mini-guide)?
    - If so, then why -ddd and not any other forms? (like -d, or -dd, or -dddd, etc)? - the number of times -d is given increasers the depth of the debugs, maybe somehow reword the debug option usage then? Or you think -ddd is a compromise between the verbosity and a revealed programming logic?

  2. lib/wp_guide.hpp
    - agree, the current description of the lexemes in the mini-guide is somewhat incomplete.
    The semantic of the lexeme's content (<>,<txt>) in fact is overloaded and depends on the suffix (search type). E.g., in searches like <..>r, <..>R, <..>l it signifies the pattern to match (even the empty one), while in other lexemes (like <..>N, '<..>P, <..>a) it defines the namespace where the match goes.
    I tried summarizing that in the user guide, thus this section in the mini-guide needs to be reworked a bit deeper.

what do you think?

@soniah
Copy link
Contributor Author

soniah commented Jun 5, 2020

  1. my intention was to indicate that adding debugging flags makes understanding the query logic easier when working through the examples (it certainly did for me). Maybe "you can use -d debug flags to see the steps the jtq engine is taking" (or similar)

  2. I see, searches vs namespace. When I saw your solution it github with <> which matches the whole thing, it surprised me (but makes sense). I was thinking it's good to point out.

These are all minor, jtc is so powerful it takes a while to get your head around things 😄

@ldn-softdev
Copy link
Owner

ldn-softdev commented Jun 5, 2020

2. I see, searches vs namespace. When I saw your solution it github with <> which matches the whole thing, it surprised me (but makes sense). I was thinking it's good to point out.

yes, I see. it indeed might be confusing at first - it's the suffix of the search which defines the search behavior, e.g.: for all the numerical JSON searches:

  • <..>d - will search (recursively) and match the given number (e.g.: <3.14>d)
  • <..>D - will match a JSON numeric using RE pattern (e.g.: <-?[1-3]\.>D)
  • <>N - will match any JSON numeric and optionally will preserve it into a namespace if given (e.g.: <num>N)

Look, I will not merge this PR, but rather will work on a better wording for the lexemes explanation in the mini-guide (and will mentioned the -d option(s) too). Big thank you for your feedback.

@soniah
Copy link
Contributor Author

soniah commented Jun 23, 2020

I wrote some more doco changes. Unfortunately this current PR hasn't been closed, so I can't open a new PR.

Here are the changes: soniah@661777b

Copy link
Owner

@ldn-softdev ldn-softdev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

elaborated a bit more on the requested changes

User Guide.md Outdated Show resolved Hide resolved
User Guide.md Show resolved Hide resolved
User Guide.md Outdated Show resolved Hide resolved
@soniah
Copy link
Contributor Author

soniah commented Jun 24, 2020

Updates made.

- all _JSON iterables_ made of only _atomic values_ or empty iterables (`[]`,
`{}`) are printed on a single line, the remainder are pretty-printed. The `t`
suffix defaults to 3 spaces, this can be changed with an additional `N` suffix,
for example `-tc5`.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

- it's way around:

The -t flag accepts an optional c suffix, ...

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Everything else looks good. I'll merge after fixing that typo.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants