jsonsl.h 30 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995
  1. /**
  2. * JSON Simple/Stacked/Stateful Lexer.
  3. * - Does not buffer data
  4. * - Maintains state
  5. * - Callback oriented
  6. * - Lightweight and fast. One source file and one header file
  7. *
  8. * Copyright (C) 2012-2015 Mark Nunberg
  9. * See included LICENSE file for license details.
  10. */
  11. #ifndef JSONSL_H_
  12. #define JSONSL_H_
  13. #include <stdio.h>
  14. #include <stdlib.h>
  15. #include <stddef.h>
  16. #include <string.h>
  17. #include <sys/types.h>
  18. #include <wchar.h>
  19. #ifdef __cplusplus
  20. extern "C" {
  21. #endif /* __cplusplus */
  22. #ifdef JSONSL_USE_WCHAR
  23. typedef jsonsl_char_t wchar_t;
  24. typedef jsonsl_uchar_t unsigned wchar_t;
  25. #else
  26. typedef char jsonsl_char_t;
  27. typedef unsigned char jsonsl_uchar_t;
  28. #endif /* JSONSL_USE_WCHAR */
  29. /* Stolen from http-parser.h, and possibly others */
  30. #if defined(_WIN32) && !defined(__MINGW32__) && (!defined(_MSC_VER) || _MSC_VER<1600)
  31. typedef __int8 int8_t;
  32. typedef unsigned __int8 uint8_t;
  33. typedef __int16 int16_t;
  34. typedef unsigned __int16 uint16_t;
  35. typedef __int32 int32_t;
  36. typedef unsigned __int32 uint32_t;
  37. typedef __int64 int64_t;
  38. typedef unsigned __int64 uint64_t;
  39. #if !defined(_MSC_VER) || _MSC_VER<1400
  40. typedef unsigned int size_t;
  41. typedef int ssize_t;
  42. #endif
  43. #else
  44. #include <stdint.h>
  45. #endif
  46. #if (!defined(JSONSL_STATE_GENERIC)) && (!defined(JSONSL_STATE_USER_FIELDS))
  47. #define JSONSL_STATE_GENERIC
  48. #endif /* !defined JSONSL_STATE_GENERIC */
  49. #ifdef JSONSL_STATE_GENERIC
  50. #define JSONSL_STATE_USER_FIELDS
  51. #endif /* JSONSL_STATE_GENERIC */
  52. /* Additional fields for component object */
  53. #ifndef JSONSL_JPR_COMPONENT_USER_FIELDS
  54. #define JSONSL_JPR_COMPONENT_USER_FIELDS
  55. #endif
  56. #ifndef JSONSL_API
  57. /**
  58. * We require a /DJSONSL_DLL so that users already using this as a static
  59. * or embedded library don't get confused
  60. */
  61. #if defined(_WIN32) && defined(JSONSL_DLL)
  62. #define JSONSL_API __declspec(dllexport)
  63. #else
  64. #define JSONSL_API
  65. #endif /* _WIN32 */
  66. #endif /* !JSONSL_API */
  67. #ifndef JSONSL_INLINE
  68. #if defined(_MSC_VER)
  69. #define JSONSL_INLINE __inline
  70. #elif defined(__GNUC__)
  71. #define JSONSL_INLINE __inline__
  72. #else
  73. #define JSONSL_INLINE inline
  74. #endif /* _MSC_VER or __GNUC__ */
  75. #endif /* JSONSL_INLINE */
  76. #define JSONSL_MAX_LEVELS 512
  77. struct jsonsl_st;
  78. typedef struct jsonsl_st *jsonsl_t;
  79. typedef struct jsonsl_jpr_st* jsonsl_jpr_t;
  80. /**
  81. * This flag is true when AND'd against a type whose value
  82. * must be in "quoutes" i.e. T_HKEY and T_STRING
  83. */
  84. #define JSONSL_Tf_STRINGY 0xffff00
  85. /**
  86. * Constant representing the special JSON types.
  87. * The values are special and aid in speed (the OBJECT and LIST
  88. * values are the char literals of their openings).
  89. *
  90. * Their actual value is a character which attempts to resemble
  91. * some mnemonic reference to the actual type.
  92. *
  93. * If new types are added, they must fit into the ASCII printable
  94. * range (so they should be AND'd with 0x7f and yield something
  95. * meaningful)
  96. */
  97. #define JSONSL_XTYPE \
  98. X(STRING, '"'|JSONSL_Tf_STRINGY) \
  99. X(HKEY, '#'|JSONSL_Tf_STRINGY) \
  100. X(OBJECT, '{') \
  101. X(LIST, '[') \
  102. X(SPECIAL, '^') \
  103. X(UESCAPE, 'u')
  104. typedef enum {
  105. #define X(o, c) \
  106. JSONSL_T_##o = c,
  107. JSONSL_XTYPE
  108. JSONSL_T_UNKNOWN = '?',
  109. /* Abstract 'root' object */
  110. JSONSL_T_ROOT = 0
  111. #undef X
  112. } jsonsl_type_t;
  113. /**
  114. * Subtypes for T_SPECIAL. We define them as flags
  115. * because more than one type can be applied to a
  116. * given object.
  117. */
  118. #define JSONSL_XSPECIAL \
  119. X(NONE, 0) \
  120. X(SIGNED, 1<<0) \
  121. X(UNSIGNED, 1<<1) \
  122. X(TRUE, 1<<2) \
  123. X(FALSE, 1<<3) \
  124. X(NULL, 1<<4) \
  125. X(FLOAT, 1<<5) \
  126. X(EXPONENT, 1<<6) \
  127. X(NONASCII, 1<<7)
  128. typedef enum {
  129. #define X(o,b) \
  130. JSONSL_SPECIALf_##o = b,
  131. JSONSL_XSPECIAL
  132. #undef X
  133. /* Handy flags for checking */
  134. JSONSL_SPECIALf_UNKNOWN = 1 << 8,
  135. /** @private Private */
  136. JSONSL_SPECIALf_ZERO = 1 << 9 | JSONSL_SPECIALf_UNSIGNED,
  137. /** @private */
  138. JSONSL_SPECIALf_DASH = 1 << 10,
  139. /** Type is numeric */
  140. JSONSL_SPECIALf_NUMERIC = (JSONSL_SPECIALf_SIGNED| JSONSL_SPECIALf_UNSIGNED),
  141. /** Type is a boolean */
  142. JSONSL_SPECIALf_BOOLEAN = (JSONSL_SPECIALf_TRUE|JSONSL_SPECIALf_FALSE),
  143. /** Type is an "extended", not integral type (but numeric) */
  144. JSONSL_SPECIALf_NUMNOINT = (JSONSL_SPECIALf_FLOAT|JSONSL_SPECIALf_EXPONENT)
  145. } jsonsl_special_t;
  146. /**
  147. * These are the various types of stack (or other) events
  148. * which will trigger a callback.
  149. * Like the type constants, this are also mnemonic
  150. */
  151. #define JSONSL_XACTION \
  152. X(PUSH, '+') \
  153. X(POP, '-') \
  154. X(UESCAPE, 'U') \
  155. X(ERROR, '!')
  156. typedef enum {
  157. #define X(a,c) \
  158. JSONSL_ACTION_##a = c,
  159. JSONSL_XACTION
  160. JSONSL_ACTION_UNKNOWN = '?'
  161. #undef X
  162. } jsonsl_action_t;
  163. /**
  164. * Various errors which may be thrown while parsing JSON
  165. */
  166. #define JSONSL_XERR \
  167. /* Trailing garbage characters */ \
  168. X(GARBAGE_TRAILING) \
  169. /* We were expecting a 'special' (numeric, true, false, null) */ \
  170. X(SPECIAL_EXPECTED) \
  171. /* The 'special' value was incomplete */ \
  172. X(SPECIAL_INCOMPLETE) \
  173. /* Found a stray token */ \
  174. X(STRAY_TOKEN) \
  175. /* We were expecting a token before this one */ \
  176. X(MISSING_TOKEN) \
  177. /* Cannot insert because the container is not ready */ \
  178. X(CANT_INSERT) \
  179. /* Found a '\' outside a string */ \
  180. X(ESCAPE_OUTSIDE_STRING) \
  181. /* Found a ':' outside of a hash */ \
  182. X(KEY_OUTSIDE_OBJECT) \
  183. /* found a string outside of a container */ \
  184. X(STRING_OUTSIDE_CONTAINER) \
  185. /* Found a null byte in middle of string */ \
  186. X(FOUND_NULL_BYTE) \
  187. /* Current level exceeds limit specified in constructor */ \
  188. X(LEVELS_EXCEEDED) \
  189. /* Got a } as a result of an opening [ or vice versa */ \
  190. X(BRACKET_MISMATCH) \
  191. /* We expected a key, but got something else instead */ \
  192. X(HKEY_EXPECTED) \
  193. /* We got an illegal control character (bad whitespace or something) */ \
  194. X(WEIRD_WHITESPACE) \
  195. /* Found a \u-escape, but there were less than 4 following hex digits */ \
  196. X(UESCAPE_TOOSHORT) \
  197. /* Invalid two-character escape */ \
  198. X(ESCAPE_INVALID) \
  199. /* Trailing comma */ \
  200. X(TRAILING_COMMA) \
  201. /* An invalid number was passed in a numeric field */ \
  202. X(INVALID_NUMBER) \
  203. /* Value is missing for object */ \
  204. X(VALUE_EXPECTED) \
  205. /* The following are for JPR Stuff */ \
  206. \
  207. /* Found a literal '%' but it was only followed by a single valid hex digit */ \
  208. X(PERCENT_BADHEX) \
  209. /* jsonpointer URI is malformed '/' */ \
  210. X(JPR_BADPATH) \
  211. /* Duplicate slash */ \
  212. X(JPR_DUPSLASH) \
  213. /* No leading root */ \
  214. X(JPR_NOROOT) \
  215. /* Allocation failure */ \
  216. X(ENOMEM) \
  217. /* Invalid unicode codepoint detected (in case of escapes) */ \
  218. X(INVALID_CODEPOINT)
  219. typedef enum {
  220. JSONSL_ERROR_SUCCESS = 0,
  221. #define X(e) \
  222. JSONSL_ERROR_##e,
  223. JSONSL_XERR
  224. #undef X
  225. JSONSL_ERROR_GENERIC
  226. } jsonsl_error_t;
  227. /**
  228. * A state is a single level of the stack.
  229. * Non-private data (i.e. the 'data' field, see the STATE_GENERIC section)
  230. * will remain in tact until the item is popped.
  231. *
  232. * As a result, it means a parent state object may be accessed from a child
  233. * object, (the parents fields will all be valid). This allows a user to create
  234. * an ad-hoc hierarchy on top of the JSON one.
  235. *
  236. */
  237. struct jsonsl_state_st {
  238. /**
  239. * The JSON object type
  240. */
  241. unsigned int type;
  242. /**
  243. * The position (in terms of number of bytes since the first call to
  244. * jsonsl_feed()) at which the state was first pushed. This includes
  245. * opening tokens, if applicable.
  246. *
  247. * @note For strings (i.e. type & JSONSL_Tf_STRINGY is nonzero) this will
  248. * be the position of the first quote.
  249. *
  250. * @see jsonsl_st::pos which contains the _current_ position and can be
  251. * used during a POP callback to get the length of the element.
  252. */
  253. size_t pos_begin;
  254. /**FIXME: This is redundant as the same information can be derived from
  255. * jsonsl_st::pos at pop-time */
  256. size_t pos_cur;
  257. /** If this element is special, then its extended type is here */
  258. unsigned short special_flags;
  259. /**
  260. * Level of recursion into nesting. This is mainly a convenience
  261. * variable, as this can technically be deduced from the lexer's
  262. * level parameter (though the logic is not that simple)
  263. */
  264. unsigned short level;
  265. /**
  266. * how many elements in the object/list.
  267. * For objects (hashes), an element is either
  268. * a key or a value. Thus for one complete pair,
  269. * nelem will be 2.
  270. *
  271. * For special types, this will hold the sum of the digits.
  272. * This only holds true for values which are simple signed/unsigned
  273. * numbers. Otherwise a special flag is set, and extra handling is not
  274. * performed.
  275. */
  276. uint32_t nelem;
  277. /*TODO: merge this and special_flags into a union */
  278. /**
  279. * Useful for an opening nest, this will prevent a callback from being
  280. * invoked on this item or any of its children
  281. */
  282. int ignore_callback : 1;
  283. /**
  284. * Counter which is incremented each time an escape ('\') is encountered.
  285. * This is used internally for non-string types and should only be
  286. * inspected by the user if the state actually represents a string
  287. * type.
  288. */
  289. unsigned int nescapes : 31;
  290. /**
  291. * Put anything you want here. if JSONSL_STATE_USER_FIELDS is here, then
  292. * the macro expansion happens here.
  293. *
  294. * You can use these fields to store hierarchical or 'tagging' information
  295. * for specific objects.
  296. *
  297. * See the documentation above for the lifetime of the state object (i.e.
  298. * if the private data points to allocated memory, it should be freed
  299. * when the object is popped, as the state object will be re-used)
  300. */
  301. #ifndef JSONSL_STATE_GENERIC
  302. JSONSL_STATE_USER_FIELDS
  303. #else
  304. /**
  305. * Otherwise, this is a simple void * pointer for anything you want
  306. */
  307. void *data;
  308. #endif /* JSONSL_STATE_USER_FIELDS */
  309. };
  310. /**Gets the number of elements in the list.
  311. * @param st The state. Must be of type JSONSL_T_LIST
  312. * @return number of elements in the list
  313. */
  314. #define JSONSL_LIST_SIZE(st) ((st)->nelem)
  315. /**Gets the number of key-value pairs in an object
  316. * @param st The state. Must be of type JSONSL_T_OBJECT
  317. * @return the number of key-value pairs in the object
  318. */
  319. #define JSONSL_OBJECT_SIZE(st) ((st)->nelem / 2)
  320. /**Gets the numeric value.
  321. * @param st The state. Must be of type JSONSL_T_SPECIAL and
  322. * special_flags must have the JSONSL_SPECIALf_NUMERIC flag
  323. * set.
  324. * @return the numeric value of the state.
  325. */
  326. #define JSONSL_NUMERIC_VALUE(st) ((st)->nelem)
  327. /*
  328. * So now we need some special structure for keeping the
  329. * JPR info in sync. Preferrably all in a single block
  330. * of memory (there's no need for separate allocations.
  331. * So we will define a 'table' with the following layout
  332. *
  333. * Level nPosbl JPR1_last JPR2_last JPR3_last
  334. *
  335. * 0 1 NOMATCH POSSIBLE POSSIBLE
  336. * 1 0 NOMATCH NOMATCH COMPLETE
  337. * [ table ends here because no further path is possible]
  338. *
  339. * Where the JPR..n corresponds to the number of JPRs
  340. * requested, and nPosble is a quick flag to determine
  341. *
  342. * the number of possibilities. In the future this might
  343. * be made into a proper 'jump' table,
  344. *
  345. * Since we always mark JPRs from the higher levels descending
  346. * into the lower ones, a prospective child match would first
  347. * look at the parent table to check the possibilities, and then
  348. * see which ones were possible..
  349. *
  350. * Thus, the size of this blob would be (and these are all ints here)
  351. * nLevels * nJPR * 2.
  352. *
  353. * the 'Width' of the table would be nJPR*2, and the 'height' would be
  354. * nlevels
  355. */
  356. /**
  357. * This is called when a stack change ocurs.
  358. *
  359. * @param jsn The lexer
  360. * @param action The type of action, this can be PUSH or POP
  361. * @param state A pointer to the stack currently affected by the action
  362. * @param at A pointer to the position of the input buffer which triggered
  363. * this action.
  364. */
  365. typedef void (*jsonsl_stack_callback)(
  366. jsonsl_t jsn,
  367. jsonsl_action_t action,
  368. struct jsonsl_state_st* state,
  369. const jsonsl_char_t *at);
  370. /**
  371. * This is called when an error is encountered.
  372. * Sometimes it's possible to 'erase' characters (by replacing them
  373. * with whitespace). If you think you have corrected the error, you
  374. * can return a true value, in which case the parser will backtrack
  375. * and try again.
  376. *
  377. * @param jsn The lexer
  378. * @param error The error which was thrown
  379. * @param state the current state
  380. * @param a pointer to the position of the input buffer which triggered
  381. * the error. Note that this is not const, this is because you have the
  382. * possibility of modifying the character in an attempt to correct the
  383. * error
  384. *
  385. * @return zero to bail, nonzero to try again (this only makes sense if
  386. * the input buffer has been modified by this callback)
  387. */
  388. typedef int (*jsonsl_error_callback)(
  389. jsonsl_t jsn,
  390. jsonsl_error_t error,
  391. struct jsonsl_state_st* state,
  392. jsonsl_char_t *at);
  393. struct jsonsl_st {
  394. /** Public, read-only */
  395. /** This is the current level of the stack */
  396. unsigned int level;
  397. /** Flag set to indicate we should stop processing */
  398. unsigned int stopfl;
  399. /**
  400. * This is the current position, relative to the beginning
  401. * of the stream.
  402. */
  403. size_t pos;
  404. /** This is the 'bytes' variable passed to feed() */
  405. const jsonsl_char_t *base;
  406. /** Callback invoked for PUSH actions */
  407. jsonsl_stack_callback action_callback_PUSH;
  408. /** Callback invoked for POP actions */
  409. jsonsl_stack_callback action_callback_POP;
  410. /** Default callback for any action, if neither PUSH or POP callbacks are defined */
  411. jsonsl_stack_callback action_callback;
  412. /**
  413. * Do not invoke callbacks for objects deeper than this level.
  414. * NOTE: This field establishes the lower bound for ignored callbacks,
  415. * and is thus misnamed. `min_ignore_level` would actually make more
  416. * sense, but we don't want to break API.
  417. */
  418. unsigned int max_callback_level;
  419. /** The error callback. Invoked when an error happens. Should not be NULL */
  420. jsonsl_error_callback error_callback;
  421. /* these are boolean flags you can modify. You will be called
  422. * about notification for each of these types if the corresponding
  423. * variable is true.
  424. */
  425. /**
  426. * @name Callback Booleans.
  427. * These determine whether a callback is to be invoked for certain types of objects
  428. * @{*/
  429. /** Boolean flag to enable or disable the invokcation for events on this type*/
  430. int call_SPECIAL;
  431. int call_OBJECT;
  432. int call_LIST;
  433. int call_STRING;
  434. int call_HKEY;
  435. /*@}*/
  436. /**
  437. * @name u-Escape handling
  438. * Special handling for the \\u-f00d type sequences. These are meant
  439. * to be translated back into the corresponding octet(s).
  440. * A special callback (if set) is invoked with *at=='u'. An application
  441. * may wish to temporarily suspend parsing and handle the 'u-' sequence
  442. * internally (or not).
  443. */
  444. /*@{*/
  445. /** Callback to be invoked for a u-escape */
  446. jsonsl_stack_callback action_callback_UESCAPE;
  447. /** Boolean flag, whether to invoke the callback */
  448. int call_UESCAPE;
  449. /** Boolean flag, whether we should return after encountering a u-escape:
  450. * the callback is invoked and then we return if this is true
  451. */
  452. int return_UESCAPE;
  453. /*@}*/
  454. struct {
  455. int allow_trailing_comma;
  456. } options;
  457. /** Put anything here */
  458. void *data;
  459. /*@{*/
  460. /** Private */
  461. int in_escape;
  462. char expecting;
  463. char tok_last;
  464. int can_insert;
  465. unsigned int levels_max;
  466. #ifndef JSONSL_NO_JPR
  467. size_t jpr_count;
  468. jsonsl_jpr_t *jprs;
  469. /* Root pointer for JPR matching information */
  470. size_t *jpr_root;
  471. #endif /* JSONSL_NO_JPR */
  472. /*@}*/
  473. /**
  474. * This is the stack. Its upper bound is levels_max, or the
  475. * nlevels argument passed to jsonsl_new. If you modify this structure,
  476. * make sure that this member is last.
  477. */
  478. struct jsonsl_state_st stack[1];
  479. };
  480. /**
  481. * Creates a new lexer object, with capacity for recursion up to nlevels
  482. *
  483. * @param nlevels maximum recursion depth
  484. */
  485. JSONSL_API
  486. jsonsl_t jsonsl_new(int nlevels);
  487. JSONSL_API
  488. jsonsl_t jsonsl_init(jsonsl_t jsn, int nlevels);
  489. JSONSL_API
  490. size_t jsonsl_get_size(int nlevels);
  491. /**
  492. * Feeds data into the lexer.
  493. *
  494. * @param jsn the lexer object
  495. * @param bytes new data to be fed
  496. * @param nbytes size of new data
  497. */
  498. JSONSL_API
  499. void jsonsl_feed(jsonsl_t jsn, const jsonsl_char_t *bytes, size_t nbytes);
  500. /**
  501. * Resets the internal parser state. This does not free the parser
  502. * but does clean it internally, so that the next time feed() is called,
  503. * it will be treated as a new stream
  504. *
  505. * @param jsn the lexer
  506. */
  507. JSONSL_API
  508. void jsonsl_reset(jsonsl_t jsn);
  509. /**
  510. * Frees the lexer, cleaning any allocated memory taken
  511. *
  512. * @param jsn the lexer
  513. */
  514. JSONSL_API
  515. void jsonsl_destroy(jsonsl_t jsn);
  516. /**
  517. * Gets the 'parent' element, given the current one
  518. *
  519. * @param jsn the lexer
  520. * @param cur the current nest, which should be a struct jsonsl_nest_st
  521. */
  522. static JSONSL_INLINE
  523. struct jsonsl_state_st *jsonsl_last_state(const jsonsl_t jsn,
  524. const struct jsonsl_state_st *state)
  525. {
  526. /* Don't complain about overriding array bounds */
  527. if (state->level > 1) {
  528. return jsn->stack + state->level - 1;
  529. } else {
  530. return NULL;
  531. }
  532. }
  533. /**
  534. * Gets the state of the last fully consumed child of this parent. This is
  535. * only valid in the parent's POP callback.
  536. *
  537. * @param the lexer
  538. * @return A pointer to the child.
  539. */
  540. static JSONSL_INLINE
  541. struct jsonsl_state_st *jsonsl_last_child(const jsonsl_t jsn,
  542. const struct jsonsl_state_st *parent)
  543. {
  544. return jsn->stack + (parent->level + 1);
  545. }
  546. /**Call to instruct the parser to stop parsing and return. This is valid
  547. * only from within a callback */
  548. static JSONSL_INLINE
  549. void jsonsl_stop(jsonsl_t jsn)
  550. {
  551. jsn->stopfl = 1;
  552. }
  553. /**
  554. * This enables receiving callbacks on all events. Doesn't do
  555. * anything special but helps avoid some boilerplate.
  556. * This does not touch the UESCAPE callbacks or flags.
  557. */
  558. static JSONSL_INLINE
  559. void jsonsl_enable_all_callbacks(jsonsl_t jsn)
  560. {
  561. jsn->call_HKEY = 1;
  562. jsn->call_STRING = 1;
  563. jsn->call_OBJECT = 1;
  564. jsn->call_SPECIAL = 1;
  565. jsn->call_LIST = 1;
  566. }
  567. /**
  568. * A macro which returns true if the current state object can
  569. * have children. This means a list type or an object type.
  570. */
  571. #define JSONSL_STATE_IS_CONTAINER(state) \
  572. (state->type == JSONSL_T_OBJECT || state->type == JSONSL_T_LIST)
  573. /**
  574. * These two functions, dump a string representation
  575. * of the error or type, respectively. They will never
  576. * return NULL
  577. */
  578. JSONSL_API
  579. const char* jsonsl_strerror(jsonsl_error_t err);
  580. JSONSL_API
  581. const char* jsonsl_strtype(jsonsl_type_t jt);
  582. /**
  583. * Dumps global metrics to the screen. This is a noop unless
  584. * jsonsl was compiled with JSONSL_USE_METRICS
  585. */
  586. JSONSL_API
  587. void jsonsl_dump_global_metrics(void);
  588. /* This macro just here for editors to do code folding */
  589. #ifndef JSONSL_NO_JPR
  590. /**
  591. * @name JSON Pointer API
  592. *
  593. * JSONPointer API. This isn't really related to the lexer (at least not yet)
  594. * JSONPointer provides an extremely simple specification for providing
  595. * locations within JSON objects. We will extend it a bit and allow for
  596. * providing 'wildcard' characters by which to be able to 'query' the stream.
  597. *
  598. * See http://tools.ietf.org/html/draft-pbryan-zyp-json-pointer-00
  599. *
  600. * Currently I'm implementing the 'single query' API which can only use a single
  601. * query component. In the future I will integrate my yet-to-be-published
  602. * Boyer-Moore-esque prefix searching implementation, in order to allow
  603. * multiple paths to be merged into one for quick and efficient searching.
  604. *
  605. *
  606. * JPR (as we'll refer to it within the source) can be used by splitting
  607. * the components into mutliple sections, and incrementally 'track' each
  608. * component. When JSONSL delivers a 'pop' callback for a string, or a 'push'
  609. * callback for an object, we will check to see whether the index matching
  610. * the component corresponding to the current level contains a match
  611. * for our path.
  612. *
  613. * In order to do this properly, a structure must be maintained within the
  614. * parent indicating whether its children are possible matches. This flag
  615. * will be 'inherited' by call children which may conform to the match
  616. * specification, and discarded by all which do not (thereby eliminating
  617. * their children from inheriting it).
  618. *
  619. * A successful match is a complete one. One can provide multiple paths with
  620. * multiple levels of matches e.g.
  621. * /foo/bar/baz/^/blah
  622. *
  623. * @{
  624. */
  625. /** The wildcard character */
  626. #ifndef JSONSL_PATH_WILDCARD_CHAR
  627. #define JSONSL_PATH_WILDCARD_CHAR '^'
  628. #endif /* WILDCARD_CHAR */
  629. #define JSONSL_XMATCH \
  630. X(COMPLETE,1) \
  631. X(POSSIBLE,0) \
  632. X(NOMATCH,-1) \
  633. X(TYPE_MISMATCH, -2)
  634. typedef enum {
  635. #define X(T,v) \
  636. JSONSL_MATCH_##T = v,
  637. JSONSL_XMATCH
  638. #undef X
  639. JSONSL_MATCH_UNKNOWN
  640. } jsonsl_jpr_match_t;
  641. typedef enum {
  642. JSONSL_PATH_STRING = 1,
  643. JSONSL_PATH_WILDCARD,
  644. JSONSL_PATH_NUMERIC,
  645. JSONSL_PATH_ROOT,
  646. /* Special */
  647. JSONSL_PATH_INVALID = -1,
  648. JSONSL_PATH_NONE = 0
  649. } jsonsl_jpr_type_t;
  650. struct jsonsl_jpr_component_st {
  651. /** The string the component points to */
  652. char *pstr;
  653. /** if this is a numeric type, the number is 'cached' here */
  654. unsigned long idx;
  655. /** The length of the string */
  656. size_t len;
  657. /** The type of component (NUMERIC or STRING) */
  658. jsonsl_jpr_type_t ptype;
  659. /** Set this to true to enforce type checking between dict keys and array
  660. * indices. jsonsl_jpr_match() will return TYPE_MISMATCH if it detects
  661. * that an array index is actually a child of a dictionary. */
  662. short is_arridx;
  663. /* Extra fields (for more advanced searches. Default is empty) */
  664. JSONSL_JPR_COMPONENT_USER_FIELDS
  665. };
  666. struct jsonsl_jpr_st {
  667. /** Path components */
  668. struct jsonsl_jpr_component_st *components;
  669. size_t ncomponents;
  670. /**Type of the match to be expected. If nonzero, will be compared against
  671. * the actual type */
  672. unsigned match_type;
  673. /** Base of allocated string for components */
  674. char *basestr;
  675. /** The original match string. Useful for returning to the user */
  676. char *orig;
  677. size_t norig;
  678. };
  679. /**
  680. * Create a new JPR object.
  681. *
  682. * @param path the JSONPointer path specification.
  683. * @param errp a pointer to a jsonsl_error_t. If this function returns NULL,
  684. * then more details will be in this variable.
  685. *
  686. * @return a new jsonsl_jpr_t object, or NULL on error.
  687. */
  688. JSONSL_API
  689. jsonsl_jpr_t jsonsl_jpr_new(const char *path, jsonsl_error_t *errp);
  690. /**
  691. * Destroy a JPR object
  692. */
  693. JSONSL_API
  694. void jsonsl_jpr_destroy(jsonsl_jpr_t jpr);
  695. /**
  696. * Match a JSON object against a type and specific level
  697. *
  698. * @param jpr the JPR object
  699. * @param parent_type the type of the parent (should be T_LIST or T_OBJECT)
  700. * @param parent_level the level of the parent
  701. * @param key the 'key' of the child. If the parent is an array, this should be
  702. * empty.
  703. * @param nkey - the length of the key. If the parent is an array (T_LIST), then
  704. * this should be the current index.
  705. *
  706. * NOTE: The key of the child means any kind of associative data related to the
  707. * element. Thus: <<< { "foo" : [ >>,
  708. * the opening array's key is "foo".
  709. *
  710. * @return a status constant. This indicates whether a match was excluded, possible,
  711. * or successful.
  712. */
  713. JSONSL_API
  714. jsonsl_jpr_match_t jsonsl_jpr_match(jsonsl_jpr_t jpr,
  715. unsigned int parent_type,
  716. unsigned int parent_level,
  717. const char *key, size_t nkey);
  718. /**
  719. * Alternate matching algorithm. This matching algorithm does not use
  720. * JSONPointer but relies on a more structured searching mechanism. It
  721. * assumes that there is a clear distinction between array indices and
  722. * object keys. In this case, the jsonsl_path_component_st::ptype should
  723. * be set to @ref JSONSL_PATH_NUMERIC for an array index (the
  724. * jsonsl_path_comonent_st::is_arridx field will be removed in a future
  725. * version).
  726. *
  727. * @param jpr The path
  728. * @param parent The parent structure. Can be NULL if this is the root object
  729. * @param child The child structure. Should not be NULL
  730. * @param key Object key, if an object
  731. * @param nkey Length of object key
  732. * @return Status constant if successful
  733. *
  734. * @note
  735. * For successful matching, both the key and the path itself should be normalized
  736. * to contain 'proper' utf8 sequences rather than utf16 '\uXXXX' escapes. This
  737. * should currently be done in the application. Another version of this function
  738. * may use a temporary buffer in such circumstances (allocated by the application).
  739. *
  740. * Since this function also checks the state of the child, it should only
  741. * be called on PUSH callbacks, and not POP callbacks
  742. */
  743. JSONSL_API
  744. jsonsl_jpr_match_t
  745. jsonsl_path_match(jsonsl_jpr_t jpr,
  746. const struct jsonsl_state_st *parent,
  747. const struct jsonsl_state_st *child,
  748. const char *key, size_t nkey);
  749. /**
  750. * Associate a set of JPR objects with a lexer instance.
  751. * This should be called before the lexer has been fed any data (and
  752. * behavior is undefined if you don't adhere to this).
  753. *
  754. * After using this function, you may subsequently call match_state() on
  755. * given states (presumably from within the callbacks).
  756. *
  757. * Note that currently the first JPR is the quickest and comes
  758. * pre-allocated with the state structure. Further JPR objects
  759. * are chained.
  760. *
  761. * @param jsn The lexer
  762. * @param jprs An array of jsonsl_jpr_t objects
  763. * @param njprs How many elements in the jprs array.
  764. */
  765. JSONSL_API
  766. void jsonsl_jpr_match_state_init(jsonsl_t jsn,
  767. jsonsl_jpr_t *jprs,
  768. size_t njprs);
  769. /**
  770. * This follows the same semantics as the normal match,
  771. * except we infer parent and type information from the relevant state objects.
  772. * The match status (for all possible JPR objects) is set in the *out parameter.
  773. *
  774. * If a match has succeeded, then its JPR object will be returned. In all other
  775. * instances, NULL is returned;
  776. *
  777. * @param jpr The jsonsl_jpr_t handle
  778. * @param state The jsonsl_state_st which is a candidate
  779. * @param key The hash key (if applicable, can be NULL if parent is list)
  780. * @param nkey Length of hash key (if applicable, can be zero if parent is list)
  781. * @param out A pointer to a jsonsl_jpr_match_t. This will be populated with
  782. * the match result
  783. *
  784. * @return If a match was completed in full, then the JPR object containing
  785. * the matching path will be returned. Otherwise, the return is NULL (note, this
  786. * does not mean matching has failed, it can still be part of the match: check
  787. * the out parameter).
  788. */
  789. JSONSL_API
  790. jsonsl_jpr_t jsonsl_jpr_match_state(jsonsl_t jsn,
  791. struct jsonsl_state_st *state,
  792. const char *key,
  793. size_t nkey,
  794. jsonsl_jpr_match_t *out);
  795. /**
  796. * Cleanup any memory allocated and any states set by
  797. * match_state_init() and match_state()
  798. * @param jsn The lexer
  799. */
  800. JSONSL_API
  801. void jsonsl_jpr_match_state_cleanup(jsonsl_t jsn);
  802. /**
  803. * Return a string representation of the match result returned by match()
  804. */
  805. JSONSL_API
  806. const char *jsonsl_strmatchtype(jsonsl_jpr_match_t match);
  807. /* @}*/
  808. /**
  809. * Utility function to convert escape sequences into their original form.
  810. *
  811. * The decoders I've sampled do not seem to specify a standard behavior of what
  812. * to escape/unescape.
  813. *
  814. * RFC 4627 Mandates only that the quoute, backslash, and ASCII control
  815. * characters (0x00-0x1f) be escaped. It is often common for applications
  816. * to escape a '/' - however this may also be desired behavior. the JSON
  817. * spec is not clear on this, and therefore jsonsl leaves it up to you.
  818. *
  819. * Additionally, sometimes you may wish to _normalize_ JSON. This is specifically
  820. * true when dealing with 'u-escapes' which can be expressed perfectly fine
  821. * as utf8. One use case for normalization is JPR string comparison, in which
  822. * case two effectively equivalent strings may not match because one is using
  823. * u-escapes and the other proper utf8. To normalize u-escapes only, pass in
  824. * an empty `toEscape` table, enabling only the `u` index.
  825. *
  826. * @param in The input string.
  827. * @param out An allocated output (should be the same size as in)
  828. * @param len the size of the buffer
  829. * @param toEscape - A sparse array of characters to unescape. Characters
  830. * which are not present in this array, e.g. toEscape['c'] == 0 will be
  831. * ignored and passed to the output in their original form.
  832. * @param oflags If not null, and a \uXXXX escape expands to a non-ascii byte,
  833. * then this variable will have the SPECIALf_NONASCII flag on.
  834. *
  835. * @param err A pointer to an error variable. If an error ocurrs, it will be
  836. * set in this variable
  837. * @param errat If not null and an error occurs, this will be set to point
  838. * to the position within the string at which the offending character was
  839. * encountered.
  840. *
  841. * @return The effective size of the output buffer.
  842. *
  843. * @note
  844. * This function now encodes the UTF8 equivalents of utf16 escapes (i.e.
  845. * 'u-escapes'). Previously this would encode the escapes as utf16 literals,
  846. * which while still correct in some sense was confusing for many (especially
  847. * considering that the inputs were variations of char).
  848. *
  849. * @note
  850. * The output buffer will never be larger than the input buffer, since
  851. * standard escape sequences (i.e. '\t') occupy two bytes in the source
  852. * but only one byte (when unescaped) in the output. Likewise u-escapes
  853. * (i.e. \uXXXX) will occupy six bytes in the source, but at the most
  854. * two bytes when escaped.
  855. */
  856. JSONSL_API
  857. size_t jsonsl_util_unescape_ex(const char *in,
  858. char *out,
  859. size_t len,
  860. const int toEscape[128],
  861. unsigned *oflags,
  862. jsonsl_error_t *err,
  863. const char **errat);
  864. /**
  865. * Convenience macro to avoid passing too many parameters
  866. */
  867. #define jsonsl_util_unescape(in, out, len, toEscape, err) \
  868. jsonsl_util_unescape_ex(in, out, len, toEscape, NULL, err, NULL)
  869. #endif /* JSONSL_NO_JPR */
  870. #ifdef __cplusplus
  871. }
  872. #endif /* __cplusplus */
  873. #endif /* JSONSL_H_ */