Add short example of using jc with NGS?

[ilyash-b]

Open an issue to discuss the new feature, bug fix, or parser before opening a pull request.

I would like to add a short example of using jc with NGS (to the main readme). That would be related and just after the Python example. Something like this (plus some explanation):

echo(``jc dig example.com``[0].answer)

Would this be OK?

[kellyjonbrazil]

Hi Ilya - yes, I think this would be fine. I would, however, like to link it to a discussion (maybe on the jc discussion area or somewhere else) where there are multiple examples of using jc with next-gen shells. That way we could feature the NGS example in the readme and provide more detail somewhere else.

[ilyash-b]

Sounds good. As to implementation, I think GitHub Wiki page would be great. Let's say "Using jc from Different Shells" or alike. Hmm... "Wiki" tab is redirecting back to main page. Is it enabled?

[kellyjonbrazil]

I haven't enabled the Wiki. Any benefit to using that over Discussions?

[ilyash-b]

I think it's better semantic fit. Wiki page is for information that people can edit in random places vs discussion, where typically messages appended at the bottom, like in a forum.

Side note: not sure about discussions but Wiki is a git repo so one can clone it and use favorite IDE.

[ilyash-b]

GitHub Wiki examples:

• https://github.com/ngs-lang/ngs/wiki
• https://github.com/Netflix/Hystrix/wiki
• https://github.com/guard/guard/wiki

Every repository on GitHub.com comes equipped with a section for hosting documentation, called a wiki.

Sounds like a fit. Source: https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis

[kellyjonbrazil]

I think that makes sense - it just seems like it will be odd to have a Wiki with a single article. I guess I could populate with some other content from discussions/blogs as well.

[ilyash-b]

I think that makes sense - it just seems like it will be odd to have a Wiki with a single article. I guess I could populate with some other content from discussions/blogs as well.

Yep, it will also grow organically with time.

[kellyjonbrazil]

I've got a little skeleton going. Feel free to add examples here: https://github.com/kellyjonbrazil/jc/wiki/Using-jc-With-Different-Shells

[ilyash-b]

• Here is my proposed section for NGS. I don't have permissions to the Wiki, please copy it over there, modify as you see fit on the way. I had the wrong impression that the wiki can be edited by anyone by default. It's not the default - https://docs.github.com/en/communities/documenting-your-project-with-wikis/changing-access-permissions-for-wikis
• Feel free to remove the "Notes:" section if it doesn't fit the format you were thinking.
• I was thinking about sorting the shells on the page alphabetically. Makes sense?
• With regard to linking from readme, you think single link or for each shell small snippet + link?

In Next Generation Shell, you will typically use the double-backtick "run and parse" syntax with `jc` and built-in features for data filtering and other manipulation. Examples:

    ``jc dig example.com``[0].answer
    ``jc ifconfig``.the_one({"name": "en0"}).ipv4_addr
    ``jc ifconfig``.name.filter(/tun/)
    ``jc ifconfig``.filter({"name": /tun/}).mtu

Notes:

* Non-zero exit code from `jc` will cause an exception to be thrown.
* The double-backtick will parse any JSON, not just output of `jc`.
* `the_one()` will throw an exception if there is not exactly one matching item.
* `.name` and `.mtu` result an array as `.FIELD_NAME` on an array is defined as mapping each element to the given field.

Next Generation Shell documentation: https://ngs-lang.org/doc/latest/index.html

[kellyjonbrazil]

Looking good! I haven't tested the other shell examples yet - might have some time to do that tomorrow. Yeah, I think I might do a short example from all or maybe a sample of the shells with link backs and one final link for "more shells" or something.

[kellyjonbrazil]

I just disabled Restrict editing to collaborators only. I wonder if you can edit now or if it sends me a PR or something?

[ilyash-b]

I edited. No PR.

https://github.com/kellyjonbrazil/jc/wiki/Using-jc-With-Different-Shells/_compare/3c31cdfa0d84677b99c0432e7f14f30c1a3ca3b2...f42c1c5f5206e09ac8266627771149d5141750b1

[ilyash-b]

Just letting you know, it's possible to have a link to a specific heading on a wiki page.

[kellyjonbrazil]

I got this when testing NGS (via brew install ngs on macOS)

% ngs --version
0.2.14
% ./ngs-test.ngs 
[ERROR 2022-05-18 09:47:00 PDT] +--------------------------------------------------------+
[ERROR 2022-05-18 09:47:00 PDT] | Syntax error in file ./ngs-test.ngs, line 3, column 26 |
[ERROR 2022-05-18 09:47:00 PDT] | 1: #!/usr/bin/env ngs                                  |
[ERROR 2022-05-18 09:47:00 PDT] | 2:                                                     |
[ERROR 2022-05-18 09:47:00 PDT] | 3: ``jc dig www.google.com``[0].answer                 |
[ERROR 2022-05-18 09:47:00 PDT] |                             ^                          |
[ERROR 2022-05-18 09:47:00 PDT] +--------------------------------------------------------+
[ERROR 2022-05-18 09:47:00 PDT] Exception of type CompileFail occurred
[ERROR 2022-05-18 09:47:00 PDT] Info: given = String of length 56: #!/usr/bin/env ngs\x0A\x0A``jc dig www.google.com``[0].answer\x0A
[ERROR 2022-05-18 09:47:00 PDT] Info: position:
[ERROR 2022-05-18 09:47:00 PDT]   Hash of size 4
[ERROR 2022-05-18 09:47:00 PDT]     [file] = ./ngs-test.ngs
[ERROR 2022-05-18 09:47:00 PDT]     [absolute] = 45
[ERROR 2022-05-18 09:47:00 PDT]     [line] = 3
[ERROR 2022-05-18 09:47:00 PDT]     [column] = 26
[ERROR 2022-05-18 09:47:00 PDT] Info: rule = String of length 9: (a class)
[ERROR 2022-05-18 09:47:00 PDT] Frame 0: <builtin-stdlib>:8102:2 - 8102:35
[ERROR 2022-05-18 09:47:00 PDT] Frame 1: <builtin-stdlib>:8076:21 - 8076:30 [in bootstrap_exception_catch_wrapper]
[ERROR 2022-05-18 09:47:00 PDT] Frame 2: <builtin-stdlib>:8003:22 - 8003:29 [in bootstrap]
+--------------------------------------------------------+
| Syntax error in file ./ngs-test.ngs, line 3, column 26 |
| 1: #!/usr/bin/env ngs                                  |
| 2:                                                     |
| 3: ``jc dig www.google.com``[0].answer                 |
|                             ^                          |
+--------------------------------------------------------+

Might be cool to show a variable assignment example like the others. I've tested all of the other examples except for the cmd.exe. I'll spin up a Windows VM for that and test next.

[kellyjonbrazil]

This seems to work fine, though:

% cat ngs-test.ngs 
#!/usr/bin/env ngs

myvar = ``jc dig www.google.com``[0].answer[0].data
echo(myvar)

[ilyash-b]

I've seen the Wiki. You did all the work :) Looks good!

The double-backtick syntax is not accepted at top-level and the example was showing just that.

[kellyjonbrazil]

I have added a section to the README.md in the dev branch. Let me know if you would like any changes:

https://github.com/kellyjonbrazil/jc/tree/dev

[kellyjonbrazil]

I went ahead and turned this into a blog post, too: https://blog.kellybrazil.com/2022/05/19/working-with-json-in-various-shells/

[ilyash-b]

Let me know if you would like any changes:

"WIKI article" should be "wiki page", I think "page" is much more commonly used in the context of "wiki". https://en.wikipedia.org/wiki/Wiki

This allows direct assignment of a JSON value to a variable in a single line of code.

Maybe something like: This allows running jc, parsing the output JSON and assigning the resulting data structure to a variable in a single line of code.

blog post

Nice!

Watch out though because it might go out of sync with the wiki page (after it's edited).

[ilyash-b]

I guess it's done and we can close the issue?

[kellyjonbrazil]

Sounds good - I'll pull this into master with the next release. Probably one or two weeks.