Anonymous avatar Anonymous committed 8e66c24

changes documentation for jsmn

Comments (0)

Files changed (2)

 <p>You can find more information about JSON format at <a href="http://www.json.org/">json.org</a></p>
 <p>Library sources are available at <a href="https://bitbucket.org/zserge/jsmn/wiki/Home">bitbucket.org/zserge/jsmn</a></p>
 <h2>Philosophy</h2>
-<p>Most JSON parsers offer you a bunch of functions to load JSON data, parse it
-and extract any value by its name. jsmn proves that checking the correctness of
-every JSON packet or allocating temporary objects to store parsed JSON fields
-often is an overkill. </p>
-<p>JSON format itself is extremely simple, so why should we complicate it?</p>
+<p>Most JSON parsers convert JSON string to internal object representation.
+But if you are using C it becomes more tricky. There is no objects or hash 
+tables. That's why most JSON parsers written in C try to reinvent the wheel, 
+and either invent custom JSON-like objects, custom hash maps, or use callbacks
+like SAX parsers do.</p>
+<p>jsmn is parser for those who don't accept it.</p>
 <p>jsmn is designed to be  <strong>robust</strong> (it should work fine even with erroneous
 data), <strong>fast</strong> (it should parse data on the fly), <strong>portable</strong> (no superfluous
 dependencies or non-standard C extensions). An of course, <strong>simplicity</strong> is a
 <li>Strings: <code>"name"</code>, <code>"Jack"</code>, <code>"age"</code> (keys and some values)</li>
 <li>Number: <code>27</code></li>
 </ul>
-<p>In jsmn, tokens do not hold any data, but point to token boundaries in JSON
-string instead. In the example above jsmn will create tokens like: Object
-[0..31], String [3..7], String [12..16], String [20..23], Number [27..29].</p>
-<p>Every jsmn token has a type, which indicates the type of corresponding JSON
-token. jsmn supports the following token types:</p>
+<p>The key moment is that in jsmn, tokens <strong>do not hold any data</strong>, 
+but just point to the token boundaries in JSON string instead. 
+In the example above jsmn will create tokens like: </p>
+<ul>
+<li>Object [0..31]</li>
+<li>String [3..7], String [12..16], String [20..23]</li>
+<li>Number [27..29].</li>
+</ul>
+<p>As you can see, every jsmn token has a type, which indicates the type of 
+corresponding JSON token. </p>
+<p>jsmn supports the following token types:</p>
 <ul>
 <li>Object - a container of key-value pairs, e.g.:
     <code>{ "foo":"bar", "x":0.3 }</code></li>
 </ul>
 <p>Token is an object of <code>jsmntok_t</code> type:</p>
 <pre><code>typedef struct {
-    jsmntype_t type; // Token type
-    int start;       // Token start position
-    int end;         // Token end position
-    int size;        // Number of child (nested) tokens
+    jsmntype_t type; /* Token type */
+    int start;       /* Token start position */
+    int end;         /* Token end position */
+    int size;        /* Number of child (nested) tokens */
 } jsmntok_t;
 </code></pre>
 <p><strong>Note:</strong> string tokens point to the first character after
 to simplify string extraction from JSON data.</p>
 <p>All job is done by <code>jsmn_parser</code> object. You can initialize a new parser using:</p>
 <pre><code>struct jsmn_parser parser;
-jsmntok_t tokens[10];
 
-// js - pointer to JSON string
-// tokens - an array of tokens available
-// 10 - number of tokens available
-jsmn_init_parser(&amp;parser, js, tokens, 10);
+jsmn_init_parser(&amp;parser);
 </code></pre>
-<p>This will create a parser, that can parse up to 10 JSON tokens from <code>js</code> string.</p>
-<p>Later, you can use <code>jsmn_parse(&amp;parser)</code> function to process JSON string with the parser.
-If something goes wrong, you will get an error. Error will be one of these:</p>
+<p>This will initialize (reset) the parser.</p>
+<p>Later, you can use <code>jsmn_parse()</code> function to process JSON string with the 
+parser:</p>
+<pre><code>jsmntok_t tokens[256];
+const char *js;
+js = ...;
+
+r = jsmn_parse(&amp;parser, js, tokens, 256);
+</code></pre>
+<p>If something goes wrong, you will get an error returned by <code>jsmn_parse()</code>. 
+Return value will be one of these:</p>
 <ul>
 <li><code>JSMN_SUCCESS</code> - everything went fine. String was parsed</li>
 <li><code>JSMN_ERROR_INVAL</code> - bad token, JSON string is corrupted</li>
 <li><code>JSMN_ERROR_NOMEM</code> - not enough tokens, JSON string is too large</li>
 <li><code>JSMN_ERROR_PART</code> - JSON string is too short, expecting more JSON data</li>
 </ul>
-<p>If you get <code>JSON_ERROR_NOMEM</code>, you can re-allocate more tokens and call
+<p>If you get <code>JSON_ERROR_NOMEM</code>, you should re-allocate more tokens and call
 <code>jsmn_parse</code> once more.  If you read json data from the stream, you can
 periodically call <code>jsmn_parse</code> and check if return value is <code>JSON_ERROR_PART</code>.
-You will get this error until you reach the end of JSON data.</p>
+You will be receiving this error until you reach the end of JSON data.</p>
+<p>jsmn stored only offsets inside parser structure, not pointers.
+It means you can use realloc() to get more tokens, or reallocated your
+<code>js</code> string when more data arrives.</p>
+<h2>Non-strict mode</h2>
+<p>By default jsmn is build in a non-strict mode. It allows you to use it for 
+other useful formats that JSON. In non-struct mode jsmn accepts:</p>
+<ul>
+<li>non-quoted primitive values other than true/false/null/numbers</li>
+<li>only primitive values without a root object</li>
+</ul>
+<p>It means the following strings will be parsed, too:</p>
+<pre><code>server: example.com
+post: 80
+message: "hello world"
+</code></pre>
+<p>Looks like a config file, right? </p>
+<pre><code>{
+    server: "example.com",
+    post: 80,
+    message: "hello world"
+}
+</code></pre>
+<p>And this is how you can use jsmn to parse JavaScript code.</p>
+<p>To switch to strict mode you should define <code>JSMN_STRICT</code> preprocessor variable.</p>
 <h2>Other info</h2>
 <p>This software is distributed under <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>,
  so feel free to integrate it in your commercial products.</p></div>

site/input/jsmn.mkd

 Philosophy
 ----------
 
-Most JSON parsers offer you a bunch of functions to load JSON data, parse it
-and extract any value by its name. jsmn proves that checking the correctness of
-every JSON packet or allocating temporary objects to store parsed JSON fields
-often is an overkill. 
+Most JSON parsers convert JSON string to internal object representation.
+But if you are using C it becomes more tricky. There is no objects or hash 
+tables. That's why most JSON parsers written in C try to reinvent the wheel, 
+and either invent custom JSON-like objects, custom hash maps, or use callbacks
+like SAX parsers do.
 
-JSON format itself is extremely simple, so why should we complicate it?
+jsmn is parser for those who don't accept it.
 
 jsmn is designed to be	**robust** (it should work fine even with erroneous
 data), **fast** (it should parse data on the fly), **portable** (no superfluous
 * Strings: `"name"`, `"Jack"`, `"age"` (keys and some values)
 * Number: `27`
 
-In jsmn, tokens do not hold any data, but point to token boundaries in JSON
-string instead. In the example above jsmn will create tokens like: Object
-[0..31], String [3..7], String [12..16], String [20..23], Number [27..29].
+The key moment is that in jsmn, tokens **do not hold any data**, 
+but just point to the token boundaries in JSON string instead. 
+In the example above jsmn will create tokens like: 
 
-Every jsmn token has a type, which indicates the type of corresponding JSON
-token. jsmn supports the following token types:
+* Object [0..31]
+* String [3..7], String [12..16], String [20..23]
+* Number [27..29].
+
+As you can see, every jsmn token has a type, which indicates the type of 
+corresponding JSON token. 
+
+jsmn supports the following token types:
 
 * Object - a container of key-value pairs, e.g.:
 	`{ "foo":"bar", "x":0.3 }`
 Token is an object of `jsmntok_t` type:
 
 	typedef struct {
-		jsmntype_t type; // Token type
-		int start;       // Token start position
-		int end;         // Token end position
-		int size;        // Number of child (nested) tokens
+		jsmntype_t type; /* Token type */
+		int start;       /* Token start position */
+		int end;         /* Token end position */
+		int size;        /* Number of child (nested) tokens */
 	} jsmntok_t;
 
 **Note:** string tokens point to the first character after
 All job is done by `jsmn_parser` object. You can initialize a new parser using:
 
 	struct jsmn_parser parser;
-	jsmntok_t tokens[10];
+	
+	jsmn_init_parser(&parser);
 
-	// js - pointer to JSON string
-	// tokens - an array of tokens available
-	// 10 - number of tokens available
-	jsmn_init_parser(&parser, js, tokens, 10);
+This will initialize (reset) the parser.
 
-This will create a parser, that can parse up to 10 JSON tokens from `js` string.
+Later, you can use `jsmn_parse()` function to process JSON string with the 
+parser:
 
-Later, you can use `jsmn_parse(&parser)` function to process JSON string with the parser.
-If something goes wrong, you will get an error. Error will be one of these:
+	jsmntok_t tokens[256];
+	const char *js;
+	js = ...;
+
+	r = jsmn_parse(&parser, js, tokens, 256);
+
+
+If something goes wrong, you will get an error returned by `jsmn_parse()`. 
+Return value will be one of these:
 
 * `JSMN_SUCCESS` - everything went fine. String was parsed
 * `JSMN_ERROR_INVAL` - bad token, JSON string is corrupted
 * `JSMN_ERROR_NOMEM` - not enough tokens, JSON string is too large
 * `JSMN_ERROR_PART` - JSON string is too short, expecting more JSON data
 
-If you get `JSON_ERROR_NOMEM`, you can re-allocate more tokens and call
+If you get `JSON_ERROR_NOMEM`, you should re-allocate more tokens and call
 `jsmn_parse` once more.  If you read json data from the stream, you can
 periodically call `jsmn_parse` and check if return value is `JSON_ERROR_PART`.
-You will get this error until you reach the end of JSON data.
+You will be receiving this error until you reach the end of JSON data.
+
+jsmn stored only offsets inside parser structure, not pointers.
+It means you can use realloc() to get more tokens, or reallocated your
+`js` string when more data arrives.
+
+Non-strict mode
+---------------
+
+By default jsmn is build in a non-strict mode. It allows you to use it for 
+other useful formats that JSON. In non-struct mode jsmn accepts:
+
+* non-quoted primitive values other than true/false/null/numbers
+* only primitive values without a root object
+
+It means the following strings will be parsed, too:
+
+	server: example.com
+	post: 80
+	message: "hello world"
+
+Looks like a config file, right? 
+
+	{
+		server: "example.com",
+		post: 80,
+		message: "hello world"
+	}
+
+And this is how you can use jsmn to parse JavaScript code.
+
+To switch to strict mode you should define `JSMN_STRICT` preprocessor variable.
 
 Other info
 ----------
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.