jshn.sh: add convenience functions, cleanup

[pprindeville]

You might not always want to populate JSON serially, so a way to save/restore the cursor through a convenience function is handy.

Also, adding anonymous (unnamed) strings to an array isn't obvious, so added a convenience function for that.

Lastly, some minor cleanup to show what the parameters are to functions, etc.

[pprindeville]

@nbd168 Can I get a review please? I need some of these changes to help with a migration from ISC-DHCP to Kea.

[pprindeville]

cc: @Ansuel @dangowrt @neheb @stintel @jow-

[pprindeville]

@jow- Can you please look this over?

[jow-]

Most (all?) existing functions use reference style returns (caller passes a destination variable name, function populates it and uses it's numeric return value to signify success/error) while your new functions introduce echo style returns requiring calling code to use ugly subshell invocations.

Personally I would also change the naming like that:

• json_get_pos -> json_get_position
• json_set_pos -> json_move_to
• json_get_parent -> json_move_up
• json_add_anon_string -> json_push_string

[pprindeville]

Most (all?) existing functions use reference style returns (caller passes a destination variable name, function populates it and uses it's numeric return value to signify success/error) while your new functions introduce echo style returns requiring calling code to use ugly subshell invocations.

Personally I would also change the naming like that:

• json_get_pos -> json_get_position
• json_set_pos -> json_move_to
• json_get_parent -> json_move_up
• json_add_anon_string -> json_push_string

Thanks, making those changes now.

By json_get_pos you meant json_get_cur, and that should become json_get_position?

And json_set_cur should become json_move_to? Or json_set_position (for symmetry)?

Where do the functions _get_var and _set_var get used? I can only find references to _json_get_var and _json_set_var...

json_get_parent isn't meant to move the cursor explicitly. It's a way to get the parent of a node if you need to do something like query the parent's type (array, table, etc).

For instance, you could implement json_select ".." as:

    local parent
    json_get_parent parent
    json_set_position "$parent"

if json_select ".." didn't exist.

[pprindeville]

Casting a wider net

cc: @blogic

[pprindeville]

Creating 2nd PR (#12) without the positioning getter/setting commit which seems to be stalled.

[pprindeville]

Most (all?) existing functions use reference style returns (caller passes a destination variable name, function populates it and uses it's numeric return value to signify success/error) while your new functions introduce echo style returns requiring calling code to use ugly subshell invocations.

Personally I would also change the naming like that:

• json_get_pos -> json_get_position
• json_set_pos -> json_move_to
• json_get_parent -> json_move_up
• json_add_anon_string -> json_push_string

@jow- I believe I've made these changes as requested. Can you please re-review?