Adds "toboolean" builtin function for converting strings to booleans

[brahmlower]

This PR adds a builtin tobool function which converts string values to booleans, similar to tonumber.

This was motivated by the need to create a boolean value based on a value provided through an environment variable. All environment variables are strings, so I needed some mechanism to convert from a string to a boolean. A contrived example of what I wanted (and what this PR implements) is:

$ TEST=true jq --null-input '{"mytest": env.TEST | tobool}'
{
  "mytest": true
}

This boolean conversion is already achievable using a function defined in the filter:

$ TEST=true jq --null-input 'def tobool: {"true":true, "false":false}[ . | tostring ]; {"mytest": env.TEST | tobool}'

The inline function definition is rather unwieldily for my use case, making the availability of the builtin function more appealing.

[coveralls]

Coverage increased (+0.02%) to 84.149% when pulling 5074537 on bplower:tobool-builtin into ccc79e5 on stedolan:master.

[itchyny]

I like this proposal, so I rebased your PR onto the master branch and added a performance improvement commit. We have tonumber and why not tobool.

[pkoppstein]

@itchyny asked:

We have tonumber and why not tobool.

The question should be: We have tonumber and why not toboolean?

That is, jq has tonumber and tostring, not tonum and tostr.

[itchyny]

Makes sense. I renamed to toboolean.

[pkoppstein]

@brahmlower @itchyny - I think it would be worthwhile discussing whether toboolean should also map TRUE and FALSE to JSON boolean values. That would honor the generosity that with_entries shows by allowing both 'value' and 'VALUE'; indeed it allows any typographical-case variant of 'value'.

It certainly wouldn't be bizarre. E.g. consider DuckDB:

D select 'TRUE'::boolean;
┌─────────────────────────┐
│ CAST('TRUE' AS BOOLEAN) │
│         boolean         │
├─────────────────────────┤
│ true                    │
└─────────────────────────┘
D select 'FALSE'::boolean;
┌──────────────────────────┐
│ CAST('FALSE' AS BOOLEAN) │
│         boolean          │
├──────────────────────────┤
│ false                    │
└──────────────────────────┘

Of course I recognize that there is potentially a principle at stake here: should toTYPE filters ever generalize fromjson?

[itchyny]

I tend to follow the existing principles or consistency, so I'm in favor of accepting only JSON format, I would suggest using ascii_downcase if asked for supporting TRUE or True.

[brahmlower]

Hey @itchyny and @pkoppstein, glad to see yall are reviving this PR! 😁 Looks like you two are taking point on getting this aligned with the project's current goals and standards, but if you need anything from me just let me know 👍

I think it would be worthwhile discussing whether toboolean should also map TRUE and FALSE to JSON boolean values.

I really can't give any useful input here. I've completely forgotten the context for opening this PR in the first place 🤷

[itchyny]

I think this is good.