Built in functions

Builtin functions like map, sort and so on are defined in builtin.c. Many are written in jq itself, while others have to be implemented in C.

If at all possible, new builtins should be written in jq code. If this is impossible, it's better to write a minimal C builtin for the currently-impossible part and then write the real function in jq.

Builtins written in jq

Do something like this commit

Towards the end of builtin.c, there's an array of strings called jq_builtins, containing entries like:

"def map(f): [.[] | f];"

Add a new one of those. That's it. If you've never seen the def syntax before, you can check it out in the jq manual.

Of course, after you do this you need to write docs and tests, which in practice means adding a paragraph to a YAML file.

Builtins written in C

Do something like this commit

A builtin can be written in C by defining it as a static function in builtin.c, and adding an entry to the array function_list like:

{(cfunction_ptr)f_keys, "keys", 1}

f_keys is the name of the function, by convention they start with f_. The number at the end is the number of arguments including the implicit input argument: keys is called from jq passing no explicit arguments and operates on the program's input.

The function must be declared to take the appropriate number of arguments of type jv and return a jv. It should consume all arguments (to know what "consume" means, and to figure out what you can do with a jv, read jv).

Builtin functions written in C can't call back to jq like map does. If this is what you want to do, you should split your builtin into a small C builtin and a wrapper jq builtin which calls it. For an example of this, look at the implementation of sort_by, which is written in jq but calls _sort_by_impl.

Again, write docs and tests when you're done.