### Contributing and Code Documentation

Home

If you want to contribute to the development of the software, every help is much appreciated.

## Bugs And Wishes

If you found any bugs in the software or would like a feature implemented, please open a new issue on the bug tracker or send an email to purest-json-bugs@ix.residuum.org.

## Development

Feel free to fork the project and submit pull requests, if you want to implement some features or fix some bugs. If possible, please open a new issue on the bug tracker, so that noone else tries to fix or implement the same issue.

If you need some help with writing externals for Pd, read the excellent how-to on that subject.

### Code structure

The whole project in written in C99. C code is in subfolder `src/`. Every object and the library itself has a .c and a corresponding .h file. `purest_json.c` is only used to setup the library. `#define`s are done only in the .h files. `purest_json.h` is `#include`d in all objects.

Every object contains functions with a structure of `<OBJECT>_<FUNCTION>`with the exception of setup functions. Only functions that Pd needs to call are exported, and only exported functions are declared in the .h file, all other functions are static.

Shared functions used by more than one object are in directory `src/inc`. The functions are prefixed with the name of the file, e.g. `ctw.c` includes functions named `ctw_<FUNCTION>`.

### Order of Functions And Declarations in .c Files

1. `#include`s
2. `t_class` declaration
3. `struct` declarations
4. prototypes for static functions
5. implementation of static functions
6. setup functions
7. functions reacting to messages
8. constructor function
9. destructor function

### Names of Setup Functions

When Pd tries to load an object, it is looking for the file with the correct platform specific suffix (.pd_linux, .pd_darwin, .dll, .pd_freebsd) and the same name, e.g. to create `[json-encode]`, Pd on Windows looks for a file `json-encode.dll`.

In this library file, Pd looks for a setup function according, depending on the name of the object:

- If the name contains a special character, that cannot be used in a C symbol (`-`, `~`, `.`, etc.), then this special character is converted to a hex representation using `sprintf(symname+i, "0x%02x", c);` where `c` is the special character. This resulting name is prefixed by `setup_`. So the function for creating `[json-encode]` must be called `setup_json0x2dencode`.
- If the name can be converted to a C symbol, then the setup function must be the object name suffixed with `_setup`. So the function for creating `[urlparams]` must be called `urlparams_setup`.

### Names of Other Exported Functions

If an object has a hyphen (`-`) in its name, then this is replaced by an underscore (`_`)

- Creation functions: `<OBJECT>_new`, e.g. `rest_new`.
- Destruction functions: `<OBJECT>_free`, e.g. `rest_free`. Not every object needs to clean up on destruction, do not create this function then.
- Generic message functions: If the function should be called based on the type of content, then the corresponding function is `<OBJECT>_<TYPE>`, e.g. `json_decode_symbol`, `json_encode_bang`.
- HTTP request messages `[GET(`, `[POST(`, `[PUT(`, `[DELETE(`, `[HEAD(`, `[PATCH(`, `[TRACE(`, and `[OPTIONS(`: `<OBJECT>_command`, e.g. `[GET(` on `[rest]` calls `rest_command`.
- Message functions: Every `[MESSAGE(` for the object has a corresponding function `<OBJECT>_<MESSAGE>`, e.g. `[cancel(` on `[oauth]` calls the function `oauth_cancel`.

### Names of Static Functions

Static functions are prefixed with the name of the corresponding file without the .c extension, and an underscore. Function prototypes are declared in .c files before implementations. Sometimes, the object names are abbreviated:

- `json-decode.c` => `jdec_`
- `json-encode.c` => `jenc_`
- `oauth.c` => `oauth_`
- `rest.c` => `rest_`
- `urlparams.c` => `urlp_`

### Content of Included Files

All .c files that do not have a matching .h file contain only static functions and are `#include`d in files defining the objects. These source files are in subfolder `src/inc/`. They have the following properties:

#### ctw.c

ctw is short for curl thread wrapper. As the name suggests, it contain functions for using threading for making requests with libcurl.

This file is used in `[oauth]` and `[rest]`. In both objects, a `struct _ctw` is the first member, so that casting is possible.

All functions are prefixed with `ctw_`.

#### kvp.c

kvp is short for key value pair. Three structs are defined in this file,`struct _v`, `struct _kvp`, and `struct _kvp_store`. `struct _kvp` is a key value pair, while `struct _kvp_store` includes a hash table of key value pair. `struct _v` is a value, containing a union of `t_float`, `char *` and `int` to distinguish between floats, strings and integers for JSON.

This file is used in `[json-encode]` and `[urlparams]`. In both objects, a `struct _kvp_store` is the first member, so that casting is possible.

All functions are prefixed with `kvp_`.

#### string.c

Utility functions for creating and freeing memory for `char *` and the corresponding `size_t`.

This file is used in `[json-decode]`, `[json-encode]`, `[oauth]`, `[rest]`, and `[urlparams]`.

All functions are prefixed with `string_`.

#### strlist.c

Utility functions for creating and freeing memory for a linked list of `char *` and the corresponding `size_t`.

This file is used in `[oauth]` and `[rest]`.

All functions are prefixed with `strlist_`.

### Reasons for using C99

- Variadic macros
- In older implementations `json_object_object_foreach` requires C99: https://github.com/json-c/json-c/pull/73
- C99 forces the memory layout for using casting to structs: § 6.2.5, 20 of the standard:

> A structure type describes a sequentially allocated nonempty set of member objects (and, in certain circumstances, an incomplete array), each of which has an optionally speciﬁed name and possibly distinct type.

### Special Cases

- `static char *string_remove_backslashes(char *source_string, size_t *memsize)` in `string.c` is surrounded by a `#ifndef NO_BACKSLASHES`. This function is not needed for `[urlparams]`, and therefore this is used to not get warnings on compilation.
- There are only a few platform specific `#define`s, those are all declared in `purest_json.h`.
- `[json-encode]` can contain arrays, while `[urlparams]` cannot, so a `#define` is used in `kvp.c` to remove array functions and struct members for `[urlparams]`.