Contributing and Code Documentation

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 implemtations. 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 c url t hread w rapper. 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 k ey v alue p air. 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

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 specified 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] .