mirror of https://github.com/kgabis/parson.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
216 lines
16 KiB
216 lines
16 KiB
<!doctype html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="chrome=1">
|
|
<title>parson by kgabis</title>
|
|
|
|
<link rel="stylesheet" href="stylesheets/styles.css">
|
|
<link rel="stylesheet" href="stylesheets/pygment_trac.css">
|
|
<script src="javascripts/scale.fix.js"></script>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
|
|
<!--[if lt IE 9]>
|
|
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
|
|
<![endif]-->
|
|
</head>
|
|
<body>
|
|
<div class="wrapper">
|
|
<header>
|
|
<h1 class="header">parson</h1>
|
|
<p class="header">Lightweight json library written in C.</p>
|
|
|
|
<ul>
|
|
<li class="download"><a class="buttons" href="https://github.com/kgabis/parson/zipball/master">Download ZIP</a></li>
|
|
<li class="download"><a class="buttons" href="https://github.com/kgabis/parson/tarball/master">Download TAR</a></li>
|
|
<li><a class="buttons github" href="https://github.com/kgabis/parson">View On GitHub</a></li>
|
|
</ul>
|
|
|
|
<p class="header">This project is maintained by <a class="header name" href="https://github.com/kgabis">kgabis</a></p>
|
|
|
|
|
|
</header>
|
|
<section>
|
|
<h2>
|
|
<a name="about" class="anchor" href="#about"><span class="octicon octicon-link"></span></a>About</h2>
|
|
|
|
<p>Parson is a lighweight <a href="http://json.org">json</a> library written in C.</p>
|
|
|
|
<h2>
|
|
<a name="features" class="anchor" href="#features"><span class="octicon octicon-link"></span></a>Features</h2>
|
|
|
|
<ul>
|
|
<li>Full JSON support</li>
|
|
<li>Lightweight (only 2 files)</li>
|
|
<li>Simple API</li>
|
|
<li>Addressing json values with dot notation (similiar to C structs or objects in most OO languages, e.g. "objectA.objectB.value")</li>
|
|
<li>C89 compatible</li>
|
|
<li>Test suites</li>
|
|
</ul><h2>
|
|
<a name="installation" class="anchor" href="#installation"><span class="octicon octicon-link"></span></a>Installation</h2>
|
|
|
|
<p>Run:</p>
|
|
|
|
<pre><code>git clone https://github.com/kgabis/parson.git
|
|
</code></pre>
|
|
|
|
<p>and copy parson.h and parson.c to you source code tree.</p>
|
|
|
|
<p>Run <code>make test</code> to compile and run tests.</p>
|
|
|
|
<h2>
|
|
<a name="examples" class="anchor" href="#examples"><span class="octicon octicon-link"></span></a>Examples</h2>
|
|
|
|
<h3>
|
|
<a name="parsing-json" class="anchor" href="#parsing-json"><span class="octicon octicon-link"></span></a>Parsing JSON</h3>
|
|
|
|
<p>Here is a function, which prints basic commit info (date, sha and author) from a github repository. </p>
|
|
|
|
<div class="highlight highlight-c"><pre><span class="kt">void</span> <span class="nf">print_commits_info</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">username</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">repo</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">JSON_Value</span> <span class="o">*</span><span class="n">root_value</span><span class="p">;</span>
|
|
<span class="n">JSON_Array</span> <span class="o">*</span><span class="n">commits</span><span class="p">;</span>
|
|
<span class="n">JSON_Object</span> <span class="o">*</span><span class="n">commit</span><span class="p">;</span>
|
|
<span class="kt">size_t</span> <span class="n">i</span><span class="p">;</span>
|
|
|
|
<span class="kt">char</span> <span class="n">curl_command</span><span class="p">[</span><span class="mi">512</span><span class="p">];</span>
|
|
<span class="kt">char</span> <span class="n">cleanup_command</span><span class="p">[</span><span class="mi">256</span><span class="p">];</span>
|
|
<span class="kt">char</span> <span class="n">output_filename</span><span class="p">[]</span> <span class="o">=</span> <span class="s">"commits.json"</span><span class="p">;</span>
|
|
|
|
<span class="cm">/* it ain't pretty, but it's not a libcurl tutorial */</span>
|
|
<span class="n">sprintf</span><span class="p">(</span><span class="n">curl_command</span><span class="p">,</span>
|
|
<span class="s">"curl -s </span><span class="se">\"</span><span class="s">https://api.github.com/repos/%s/%s/commits</span><span class="se">\"</span><span class="s"> > %s"</span><span class="p">,</span>
|
|
<span class="n">username</span><span class="p">,</span> <span class="n">repo</span><span class="p">,</span> <span class="n">output_filename</span><span class="p">);</span>
|
|
<span class="n">sprintf</span><span class="p">(</span><span class="n">cleanup_command</span><span class="p">,</span> <span class="s">"rm -f %s"</span><span class="p">,</span> <span class="n">output_filename</span><span class="p">);</span>
|
|
<span class="n">system</span><span class="p">(</span><span class="n">curl_command</span><span class="p">);</span>
|
|
|
|
<span class="cm">/* parsing json and validating output */</span>
|
|
<span class="n">root_value</span> <span class="o">=</span> <span class="n">json_parse_file</span><span class="p">(</span><span class="n">output_filename</span><span class="p">);</span>
|
|
<span class="k">if</span> <span class="p">(</span><span class="n">json_value_get_type</span><span class="p">(</span><span class="n">root_value</span><span class="p">)</span> <span class="o">!=</span> <span class="n">JSONArray</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">system</span><span class="p">(</span><span class="n">cleanup_command</span><span class="p">);</span>
|
|
<span class="k">return</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="cm">/* getting array from root value and printing commit info */</span>
|
|
<span class="n">commits</span> <span class="o">=</span> <span class="n">json_value_get_array</span><span class="p">(</span><span class="n">root_value</span><span class="p">);</span>
|
|
<span class="n">printf</span><span class="p">(</span><span class="s">"%-10.10s %-10.10s %s</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="s">"Date"</span><span class="p">,</span> <span class="s">"SHA"</span><span class="p">,</span> <span class="s">"Author"</span><span class="p">);</span>
|
|
<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">json_array_get_count</span><span class="p">(</span><span class="n">commits</span><span class="p">);</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">commit</span> <span class="o">=</span> <span class="n">json_array_get_object</span><span class="p">(</span><span class="n">commits</span><span class="p">,</span> <span class="n">i</span><span class="p">);</span>
|
|
<span class="n">printf</span><span class="p">(</span><span class="s">"%.10s %.10s %s</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span>
|
|
<span class="n">json_object_dotget_string</span><span class="p">(</span><span class="n">commit</span><span class="p">,</span> <span class="s">"commit.author.date"</span><span class="p">),</span>
|
|
<span class="n">json_object_get_string</span><span class="p">(</span><span class="n">commit</span><span class="p">,</span> <span class="s">"sha"</span><span class="p">),</span>
|
|
<span class="n">json_object_dotget_string</span><span class="p">(</span><span class="n">commit</span><span class="p">,</span> <span class="s">"commit.author.name"</span><span class="p">));</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="cm">/* cleanup code */</span>
|
|
<span class="n">json_value_free</span><span class="p">(</span><span class="n">root_value</span><span class="p">);</span>
|
|
<span class="n">system</span><span class="p">(</span><span class="n">cleanup_command</span><span class="p">);</span>
|
|
<span class="p">}</span>
|
|
|
|
</pre></div>
|
|
|
|
<p>Calling <code>print_commits_info("torvalds", "linux");</code> prints: </p>
|
|
|
|
<pre><code>Date SHA Author
|
|
2012-10-15 dd8e8c4a2c David Rientjes
|
|
2012-10-15 3ce9e53e78 Michal Marek
|
|
2012-10-14 29bb4cc5e0 Randy Dunlap
|
|
2012-10-15 325adeb55e Ralf Baechle
|
|
2012-10-14 68687c842c Russell King
|
|
2012-10-14 ddffeb8c4d Linus Torvalds
|
|
...
|
|
</code></pre>
|
|
|
|
<h3>
|
|
<a name="persistence" class="anchor" href="#persistence"><span class="octicon octicon-link"></span></a>Persistence</h3>
|
|
|
|
<p>In this example I'm using parson to save user information to a file and then load it and validate later.</p>
|
|
|
|
<div class="highlight highlight-c"><pre><span class="kt">void</span> <span class="nf">persistence_example</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">JSON_Value</span> <span class="o">*</span><span class="n">schema</span> <span class="o">=</span> <span class="n">json_parse_string</span><span class="p">(</span><span class="s">"{</span><span class="se">\"</span><span class="s">name</span><span class="se">\"</span><span class="s">:</span><span class="se">\"\"</span><span class="s">}"</span><span class="p">);</span>
|
|
<span class="n">JSON_Value</span> <span class="o">*</span><span class="n">user_data</span> <span class="o">=</span> <span class="n">json_parse_file</span><span class="p">(</span><span class="s">"user_data.json"</span><span class="p">);</span>
|
|
<span class="kt">char</span> <span class="n">buf</span><span class="p">[</span><span class="mi">256</span><span class="p">];</span>
|
|
<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">name</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
|
|
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">user_data</span> <span class="o">||</span> <span class="o">!</span><span class="n">json_validate</span><span class="p">(</span><span class="n">schema</span><span class="p">,</span> <span class="n">user_data</span><span class="p">)</span> <span class="o">==</span> <span class="n">JSONSuccess</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">puts</span><span class="p">(</span><span class="s">"Enter your name:"</span><span class="p">);</span>
|
|
<span class="n">scanf</span><span class="p">(</span><span class="s">"%s"</span><span class="p">,</span> <span class="n">buf</span><span class="p">);</span>
|
|
<span class="n">user_data</span> <span class="o">=</span> <span class="n">json_value_init_object</span><span class="p">();</span>
|
|
<span class="n">json_object_set_string</span><span class="p">(</span><span class="n">json_object</span><span class="p">(</span><span class="n">user_data</span><span class="p">),</span> <span class="s">"name"</span><span class="p">,</span> <span class="n">buf</span><span class="p">);</span>
|
|
<span class="n">json_serialize_to_file</span><span class="p">(</span><span class="n">user_data</span><span class="p">,</span> <span class="s">"user_data.json"</span><span class="p">);</span>
|
|
<span class="p">}</span>
|
|
<span class="n">name</span> <span class="o">=</span> <span class="n">json_object_get_string</span><span class="p">(</span><span class="n">json_object</span><span class="p">(</span><span class="n">user_data</span><span class="p">),</span> <span class="s">"name"</span><span class="p">);</span>
|
|
<span class="n">printf</span><span class="p">(</span><span class="s">"Hello, %s."</span><span class="p">,</span> <span class="n">name</span><span class="p">);</span>
|
|
<span class="n">json_value_free</span><span class="p">(</span><span class="n">schema</span><span class="p">);</span>
|
|
<span class="n">json_value_free</span><span class="p">(</span><span class="n">user_data</span><span class="p">);</span>
|
|
<span class="k">return</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
|
|
<h3>
|
|
<a name="serialization" class="anchor" href="#serialization"><span class="octicon octicon-link"></span></a>Serialization</h3>
|
|
|
|
<p>Creating JSON values is very simple thanks to the dot notation.
|
|
Object hierarchy is automatically created when addressing specific fields.
|
|
In the following example I create a simple JSON value containing basic information about a person.</p>
|
|
|
|
<div class="highlight highlight-c"><pre><span class="kt">void</span> <span class="nf">serialization_example</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">JSON_Value</span> <span class="o">*</span><span class="n">root_value</span> <span class="o">=</span> <span class="n">json_value_init_object</span><span class="p">();</span>
|
|
<span class="n">JSON_Object</span> <span class="o">*</span><span class="n">root_object</span> <span class="o">=</span> <span class="n">json_value_get_object</span><span class="p">(</span><span class="n">root_value</span><span class="p">);</span>
|
|
<span class="kt">char</span> <span class="o">*</span><span class="n">serialized_string</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
|
|
<span class="n">json_object_set_string</span><span class="p">(</span><span class="n">root_object</span><span class="p">,</span> <span class="s">"name"</span><span class="p">,</span> <span class="s">"John Smith"</span><span class="p">);</span>
|
|
<span class="n">json_object_set_number</span><span class="p">(</span><span class="n">root_object</span><span class="p">,</span> <span class="s">"age"</span><span class="p">,</span> <span class="mi">25</span><span class="p">);</span>
|
|
<span class="n">json_object_dotset_string</span><span class="p">(</span><span class="n">root_object</span><span class="p">,</span> <span class="s">"address.city"</span><span class="p">,</span> <span class="s">"Cupertino"</span><span class="p">);</span>
|
|
<span class="n">json_object_dotset_value</span><span class="p">(</span><span class="n">root_object</span><span class="p">,</span> <span class="s">"contact.emails"</span><span class="p">,</span> <span class="n">json_parse_string</span><span class="p">(</span><span class="s">"[</span><span class="se">\"</span><span class="s">email@example.com</span><span class="se">\"</span><span class="s">,</span><span class="se">\"</span><span class="s">email2@example.com</span><span class="se">\"</span><span class="s">]"</span><span class="p">));</span>
|
|
<span class="n">serialized_string</span> <span class="o">=</span> <span class="n">json_serialize_to_string</span><span class="p">(</span><span class="n">root_value</span><span class="p">);</span>
|
|
<span class="n">puts</span><span class="p">(</span><span class="n">serialized_string</span><span class="p">);</span>
|
|
<span class="n">json_free_serialized_string</span><span class="p">(</span><span class="n">serialized_string</span><span class="p">);</span>
|
|
<span class="n">json_value_free</span><span class="p">(</span><span class="n">root_value</span><span class="p">);</span>
|
|
<span class="p">}</span>
|
|
|
|
</pre></div>
|
|
|
|
<p>Created value (after formatting outside parson):</p>
|
|
|
|
<pre><code>{
|
|
"name":"John Smith",
|
|
"age":25,
|
|
"address":{
|
|
"city":"Cupertino"
|
|
},
|
|
"contact":{
|
|
"emails":[
|
|
"email@example.com",
|
|
"email2@example.com"
|
|
]
|
|
}
|
|
}
|
|
</code></pre>
|
|
|
|
<h2>
|
|
<a name="contributing" class="anchor" href="#contributing"><span class="octicon octicon-link"></span></a>Contributing</h2>
|
|
|
|
<p>I will always merge <em>working</em> bug fixes. However, if you want to add something to the API,
|
|
I <em>won't</em> merge it without prior discussion.
|
|
Remember to follow parson's code style and write appropriate tests.</p>
|
|
|
|
<h2>
|
|
<a name="license" class="anchor" href="#license"><span class="octicon octicon-link"></span></a>License</h2>
|
|
|
|
<p><a href="http://opensource.org/licenses/mit-license.php">The MIT License (MIT)</a></p>
|
|
</section>
|
|
<footer>
|
|
<p><small>Hosted on <a href="http://pages.github.com">GitHub Pages</a> using the Dinky theme</small></p>
|
|
</footer>
|
|
</div>
|
|
<!--[if !IE]><script>fixScale(document);</script><![endif]-->
|
|
<script type="text/javascript">
|
|
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
|
|
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
|
|
</script>
|
|
<script type="text/javascript">
|
|
try {
|
|
var pageTracker = _gat._getTracker("UA-35563760-2");
|
|
pageTracker._trackPageview();
|
|
} catch(err) {}
|
|
</script>
|
|
|
|
</body>
|
|
</html>
|
|
|