|
| 1 | +##About |
| 2 | +Parson is a lighweight [json](http://json.org) library written in C. |
| 3 | + |
| 4 | +##Features |
| 5 | +* Full JSON support |
| 6 | +* Lightweight (only 2 files) |
| 7 | +* Simple API |
| 8 | +* Addressing json values with dot notation (similiar to C structs or objects in most OO languages, e.g. "objectA.objectB.value") |
| 9 | +* C89 compatible |
| 10 | +* Test suites |
| 11 | + |
| 12 | +##Installation |
| 13 | +Run: |
| 14 | +``` |
| 15 | +git clone https://github.com/kgabis/parson.git |
| 16 | +``` |
| 17 | +and copy parson.h and parson.c to you source code tree. |
| 18 | + |
| 19 | +Run ```make test``` to compile and run tests. |
| 20 | + |
| 21 | +##Examples |
| 22 | +###Parsing JSON |
| 23 | +Here is a function, which prints basic commit info (date, sha and author) from a github repository. |
| 24 | +```c |
| 25 | +void print_commits_info(const char *username, const char *repo) { |
| 26 | + JSON_Value *root_value; |
| 27 | + JSON_Array *commits; |
| 28 | + JSON_Object *commit; |
| 29 | + size_t i; |
| 30 | + |
| 31 | + char curl_command[512]; |
| 32 | + char cleanup_command[256]; |
| 33 | + char output_filename[] = "commits.json"; |
| 34 | + |
| 35 | + /* it ain't pretty, but it's not a libcurl tutorial */ |
| 36 | + sprintf(curl_command, |
| 37 | + "curl -s \"https://api.github.com/repos/%s/%s/commits\" > %s", |
| 38 | + username, repo, output_filename); |
| 39 | + sprintf(cleanup_command, "rm -f %s", output_filename); |
| 40 | + system(curl_command); |
| 41 | + |
| 42 | + /* parsing json and validating output */ |
| 43 | + root_value = json_parse_file(output_filename); |
| 44 | + if (json_value_get_type(root_value) != JSONArray) { |
| 45 | + system(cleanup_command); |
| 46 | + return; |
| 47 | + } |
| 48 | + |
| 49 | + /* getting array from root value and printing commit info */ |
| 50 | + commits = json_value_get_array(root_value); |
| 51 | + printf("%-10.10s %-10.10s %s\n", "Date", "SHA", "Author"); |
| 52 | + for (i = 0; i < json_array_get_count(commits); i++) { |
| 53 | + commit = json_array_get_object(commits, i); |
| 54 | + printf("%.10s %.10s %s\n", |
| 55 | + json_object_dotget_string(commit, "commit.author.date"), |
| 56 | + json_object_get_string(commit, "sha"), |
| 57 | + json_object_dotget_string(commit, "commit.author.name")); |
| 58 | + } |
| 59 | + |
| 60 | + /* cleanup code */ |
| 61 | + json_value_free(root_value); |
| 62 | + system(cleanup_command); |
| 63 | +} |
| 64 | + |
| 65 | +``` |
| 66 | +Calling ```print_commits_info("torvalds", "linux");``` prints: |
| 67 | +``` |
| 68 | +Date SHA Author |
| 69 | +2012-10-15 dd8e8c4a2c David Rientjes |
| 70 | +2012-10-15 3ce9e53e78 Michal Marek |
| 71 | +2012-10-14 29bb4cc5e0 Randy Dunlap |
| 72 | +2012-10-15 325adeb55e Ralf Baechle |
| 73 | +2012-10-14 68687c842c Russell King |
| 74 | +2012-10-14 ddffeb8c4d Linus Torvalds |
| 75 | +... |
| 76 | +``` |
| 77 | +
|
| 78 | +###Persistence |
| 79 | +In this example I'm using parson to save user information to a file and then load it and validate later. |
| 80 | +```c |
| 81 | +void persistence_example(void) { |
| 82 | + JSON_Value *schema = json_parse_string("{\"name\":\"\"}"); |
| 83 | + JSON_Value *user_data = json_parse_file("user_data.json"); |
| 84 | + char buf[256]; |
| 85 | + const char *name = NULL; |
| 86 | + if (user_data == NULL || json_validate(schema, user_data) != JSONSuccess) { |
| 87 | + puts("Enter your name:"); |
| 88 | + scanf("%s", buf); |
| 89 | + user_data = json_value_init_object(); |
| 90 | + json_object_set_string(json_object(user_data), "name", buf); |
| 91 | + json_serialize_to_file(user_data, "user_data.json"); |
| 92 | + } |
| 93 | + name = json_object_get_string(json_object(user_data), "name"); |
| 94 | + printf("Hello, %s.", name); |
| 95 | + json_value_free(schema); |
| 96 | + json_value_free(user_data); |
| 97 | + return; |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +###Serialization |
| 102 | +Creating JSON values is very simple thanks to the dot notation. |
| 103 | +Object hierarchy is automatically created when addressing specific fields. |
| 104 | +In the following example I create a simple JSON value containing basic information about a person. |
| 105 | +```c |
| 106 | +void serialization_example(void) { |
| 107 | + JSON_Value *root_value = json_value_init_object(); |
| 108 | + JSON_Object *root_object = json_value_get_object(root_value); |
| 109 | + char *serialized_string = NULL; |
| 110 | + json_object_set_string(root_object, "name", "John Smith"); |
| 111 | + json_object_set_number(root_object, "age", 25); |
| 112 | + json_object_dotset_string(root_object, "address.city", "Cupertino"); |
| 113 | + json_object_dotset_value(root_object, "contact.emails", json_parse_string(" [\"[email protected]\", \"[email protected]\"]")); |
| 114 | + serialized_string = json_serialize_to_string_pretty(root_value); |
| 115 | + puts(serialized_string); |
| 116 | + json_free_serialized_string(serialized_string); |
| 117 | + json_value_free(root_value); |
| 118 | +} |
| 119 | + |
| 120 | +``` |
| 121 | +
|
| 122 | +Output: |
| 123 | +``` |
| 124 | +{ |
| 125 | + "name": "John Smith", |
| 126 | + "age": 25, |
| 127 | + "address": { |
| 128 | + "city": "Cupertino" |
| 129 | + }, |
| 130 | + "contact": { |
| 131 | + "emails": [ |
| 132 | + |
| 133 | + |
| 134 | + ] |
| 135 | + } |
| 136 | +} |
| 137 | +``` |
| 138 | +
|
| 139 | +##Contributing |
| 140 | +
|
| 141 | +I will always merge *working* bug fixes. However, if you want to add something to the API, |
| 142 | +I *won't* merge it without prior discussion. |
| 143 | +Remember to follow parson's code style and write appropriate tests. |
| 144 | +
|
| 145 | +##License |
| 146 | +[The MIT License (MIT)](http://opensource.org/licenses/mit-license.php) |
0 commit comments