libcm is a C development framework with an emphasis on audio signal processing applications.
Du kan inte välja fler än 25 ämnen Ämnen måste starta med en bokstav eller siffra, kan innehålla bindestreck ('-') och vara max 35 tecken långa.

cmJson.h 27KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519
  1. #ifndef cmJson_h
  2. #define cmJson_h
  3. #ifdef __cplusplus
  4. extern "C" {
  5. #endif
  6. //( { file_desc: "JSON reader and writer" kw:[file] }
  7. //
  8. // Limitations:
  9. //
  10. // 1. Accpets two digit hex sequences with
  11. // the \\u escape command. JSON specifies 4 digits.
  12. //
  13. // 2. The scientific notation for real numbers is limited to
  14. // exponent prefixes: e,E,e-,E-. The prefixes e+ and E+ are
  15. // not recognized by cmLex.
  16. //
  17. // Extensions:
  18. //
  19. // 1. Will accept C style identifiers where JSON demands
  20. // quoted strings.
  21. //
  22. // 2. Will accept C style hex notation (0xddd) for integer values.
  23. //
  24. //)
  25. //(
  26. // JSON data type flags
  27. enum
  28. {
  29. kInvalidTId = 0x0000,
  30. kObjectTId = 0x0001, // children are pairs
  31. kPairTId = 0x0002, // children are string : value pairs
  32. kArrayTId = 0x0004, // children may be of any type
  33. kStringTId = 0x0008, // terminal
  34. kNullTId = 0x0040, // terminal
  35. kIntTId = 0x0010, // terminal
  36. kRealTId = 0x0020, // terminal
  37. kTrueTId = 0x0080, // terminal
  38. kFalseTId = 0x0100, // terminal
  39. kMaskTId = 0x01ff,
  40. kOptArgJsFl = 0x0800, // only used by cmJsonVMemberValues()
  41. kTempJsFl = 0x1000, // used internally
  42. kNumericTId = kIntTId | kRealTId | kTrueTId | kFalseTId,
  43. kBoolTId = kTrueTId | kFalseTId
  44. };
  45. enum
  46. {
  47. kOkJsRC,
  48. kMemAllocErrJsRC,
  49. kLexErrJsRC,
  50. kSyntaxErrJsRC,
  51. kFileOpenErrJsRC,
  52. kFileCreateErrJsRC,
  53. kFileReadErrJsRC,
  54. kFileSeekErrJsRC,
  55. kFileCloseErrJsRC,
  56. kInvalidHexEscapeJsRC,
  57. kSerialErrJsRC,
  58. kNodeNotFoundJsRC,
  59. kNodeCannotCvtJsRC,
  60. kCannotRemoveLabelJsRC,
  61. kInvalidNodeTypeJsRC,
  62. kValidateFailJsRC,
  63. kCsvErrJsRC,
  64. kBufTooSmallJsRC
  65. };
  66. typedef unsigned cmJsRC_t;
  67. typedef cmHandle_t cmJsonH_t;
  68. // JSON tree node
  69. typedef struct cmJsonNode_str
  70. {
  71. unsigned typeId; // id of this node
  72. struct cmJsonNode_str* siblingPtr; // next ele in array or member list
  73. struct cmJsonNode_str* ownerPtr; // parent node ptr
  74. union
  75. {
  76. // childPtr usage:
  77. // object: first pair
  78. // array: first element
  79. // pair: string
  80. struct cmJsonNode_str* childPtr;
  81. int intVal; // valid if typeId == kIntTId
  82. double realVal; // valid if typeId == kRealTId
  83. char* stringVal; // valid if typeId == kStringTId
  84. bool boolVal; // valid if typeId == kTrueTId || kFalseTId
  85. } u;
  86. } cmJsonNode_t;
  87. extern cmJsonH_t cmJsonNullHandle;
  88. // Initialize a json parser/tree object
  89. cmJsRC_t cmJsonInitialize( cmJsonH_t* hp, cmCtx_t* ctx );
  90. // Equivalent to cmJsonInitialize() followed by cmJsonParseFile()
  91. cmJsRC_t cmJsonInitializeFromFile( cmJsonH_t* hp, const char* fn, cmCtx_t* ctx );
  92. // Equivalent to cmJsonInitialize() followed by cmJsonParse(h,buf,cnt,NULL).
  93. cmJsRC_t cmJsonInitializeFromBuf( cmJsonH_t* hp, cmCtx_t* ctx, const char* buf, unsigned bufByteCnt );
  94. // Release all the resources held by the tree.
  95. cmJsRC_t cmJsonFinalize( cmJsonH_t* hp );
  96. // Returns true if 'h' is a valid cmJsonH_t handle.
  97. bool cmJsonIsValid( cmJsonH_t h );
  98. // Returns true if the tree has been modified since it was initialized.
  99. // If changes to the tree are done directly on the nodes, rather than using
  100. // the API functions, then this function may not indicate the actual
  101. // modification state of the tree.
  102. bool cmJsonIsModified( cmJsonH_t h );
  103. // Build the internal tree by parsing a text buffer.
  104. // altRootPtr is an optional alternate root ptr which can be used
  105. // append to an existing tree. Set to altRootPtr to
  106. // NULL to append the tree to the internal root.
  107. // If altRootPtr is given it must point ot either an array or
  108. // object node.
  109. cmJsRC_t cmJsonParse( cmJsonH_t h, const char* buf, unsigned bufCharCnt, cmJsonNode_t* altRootPtr );
  110. // Fills a text buffer from a file and calls cmJsonParse().
  111. cmJsRC_t cmJsonParseFile( cmJsonH_t h, const char* fn, cmJsonNode_t* altRootPtr );
  112. // Return the root node of the internal tree.
  113. cmJsonNode_t* cmJsonRoot( cmJsonH_t h );
  114. // Return the tree to the post initialize state by clearing the internal tree.
  115. cmJsRC_t cmJsonClearTree( cmJsonH_t h );
  116. // Node type predicates.
  117. bool cmJsonIsObject( const cmJsonNode_t* np );
  118. bool cmJsonIsArray( const cmJsonNode_t* np );
  119. bool cmJsonIsPair( const cmJsonNode_t* np );
  120. bool cmJsonIsString( const cmJsonNode_t* np );
  121. bool cmJsonIsInt( const cmJsonNode_t* np );
  122. bool cmJsonIsReal( const cmJsonNode_t* np );
  123. bool cmJsonIsBool( const cmJsonNode_t* np );
  124. // Return the count of child nodes of 'np'.
  125. // Note that only object,array, and pair nodes have children.
  126. unsigned cmJsonChildCount( const cmJsonNode_t* np );
  127. // Return the node at 'index' from an element array.
  128. // 'np must point to an array element.
  129. cmJsonNode_t* cmJsonArrayElement( cmJsonNode_t* np, unsigned index );
  130. const cmJsonNode_t* cmJsonArrayElementC( const cmJsonNode_t* np, unsigned index );
  131. // Return the child value node of a pair with a label node equal to 'label'.
  132. // Set 'root' to NULL to begin the search at the internal tree root node.
  133. // Set 'typeIdMask' with all type flags to match.
  134. // If 'typeIdMask' is equal to kInvalidTId then all types will match.
  135. cmJsonNode_t* cmJsonFindValue( cmJsonH_t h, const char* label, const cmJsonNode_t* root, unsigned typeIdMask );
  136. // Return the value node of a pair at the end of an object path.
  137. // 'path' is a '/' seperated list of object names where the final
  138. // object specifies the pair label for the value to return.
  139. const cmJsonNode_t* cmJsonFindPathValueC( cmJsonH_t h, const char* path, const cmJsonNode_t* root, unsigned typeIdMask );
  140. cmJsonNode_t* cmJsonFindPathValue( cmJsonH_t h, const char* path, const cmJsonNode_t* root, unsigned typeIdMask );
  141. // Return the node value. If 'np' does not point to the same type as
  142. // specified in '*retPtr' then the value is converted if possible.
  143. // If the value cannot be converted function returns a 'kNodeCannotCvtJsRC'
  144. // error
  145. cmJsRC_t cmJsonUIntValue( const cmJsonNode_t* np, unsigned* retPtr );
  146. cmJsRC_t cmJsonIntValue( const cmJsonNode_t* np, int* retPtr );
  147. cmJsRC_t cmJsonRealValue( const cmJsonNode_t* np, double* retPtr );
  148. cmJsRC_t cmJsonBoolValue( const cmJsonNode_t* np, bool* retPtr );
  149. cmJsRC_t cmJsonStringValue( const cmJsonNode_t* np, const char ** retPtrPtr );
  150. cmJsRC_t cmJsonPairNode( const cmJsonNode_t* vp, cmJsonNode_t ** retPtrPtr );
  151. cmJsRC_t cmJsonArrayNode( const cmJsonNode_t* vp, cmJsonNode_t ** retPtrPtr );
  152. cmJsRC_t cmJsonObjectNode( const cmJsonNode_t* vp, cmJsonNode_t ** retPtrPtr );
  153. // Return the label from a pair object.
  154. const char* cmJsonPairLabel( const cmJsonNode_t* pairPtr );
  155. unsigned cmJsonPairTypeId( const cmJsonNode_t* pairPtr );
  156. cmJsonNode_t* cmJsonPairValue( cmJsonNode_t* pairPtr );
  157. // Return a labelled pair node from an object.
  158. cmJsonNode_t* cmJsonFindPair( const cmJsonNode_t* objectNodePtr, const char* label );
  159. // Return the type of a member value.
  160. cmJsRC_t cmJsonMemberType( const cmJsonNode_t* objectNodePtr, const char* label, unsigned* typeIdRef );
  161. // Return the pair at the specified index. Use cmJsonChildCount() to get the count of pairs in the object.
  162. cmJsonNode_t* cmJsonMemberAtIndex( cmJsonNode_t* objNodePtr, unsigned idx );
  163. // Return values associated with the member values in the object
  164. // pointed to by object objectNodePtr.
  165. cmJsRC_t cmJsonUIntMember( const cmJsonNode_t* objectNodePtr, const char* label, unsigned* retPtr );
  166. cmJsRC_t cmJsonIntMember( const cmJsonNode_t* objectNodePtr, const char* label, int* retPtr );
  167. cmJsRC_t cmJsonRealMember( const cmJsonNode_t* objectNodePtr, const char* label, double* retPtr );
  168. cmJsRC_t cmJsonBoolMember( const cmJsonNode_t* objectNodePtr, const char* label, bool* retPtr );
  169. cmJsRC_t cmJsonStringMember( const cmJsonNode_t* objectNodePtr, const char* label, const char** retPtrPtr );
  170. // Returns array or object nodes.
  171. cmJsRC_t cmJsonNodeMember( const cmJsonNode_t* objectNodePtr, const char* label, cmJsonNode_t** nodePtrPtr );
  172. // Returns the value of the member pair named by 'label' or NULL if the
  173. // named pair does not exist.
  174. cmJsonNode_t* cmJsonNodeMemberValue( const cmJsonNode_t* np, const char* label );
  175. // Return values for specified pairs from an object node.
  176. //
  177. // The var args syntax is: <label>,<typeId>,<valuePtr>.
  178. // This functionis implemented in terms of cmJsonXXXMember().
  179. //
  180. // Add kOptArgJsFl to <typeId> if the member may not exist in
  181. // the object - otherwise the function will fail with a
  182. // kNodeNotFoundJsRC error and errLabelPtr will have the name of the missing pair.
  183. //
  184. // Terminate the var args list with NULL.
  185. //
  186. // Object,Array, and Pair members are returned as node pointers.
  187. //
  188. // Since kBoolTId does not exist use kTrueTId or kFalseTId to
  189. // return bool values.
  190. cmJsRC_t cmJsonVMemberValues(const cmJsonNode_t* objectNodePtr, const char** errLabelPtrPtr, va_list vl );
  191. cmJsRC_t cmJsonMemberValues( const cmJsonNode_t* objectNodePtr, const char** errLabelPtrPtr, ... );
  192. // If objectNodePtr is set to NULL then the tree root is used as the base for the search.
  193. // pathPrefix may be set to NULL.
  194. cmJsRC_t cmJsonPathToValueNode( cmJsonH_t h, const cmJsonNode_t* objectNodePtr, const char* pathPrefix, const char* path, const cmJsonNode_t** nodePtrPtr );
  195. cmJsRC_t cmJsonPathToBool( cmJsonH_t h, const cmJsonNode_t* objectNodePtr, const char* pathPrefix, const char* path, bool* retValPtr );
  196. cmJsRC_t cmJsonPathToInt( cmJsonH_t h, const cmJsonNode_t* objectNodePtr, const char* pathPrefix, const char* path, int* retValPtr );
  197. cmJsRC_t cmJsonPathToUInt( cmJsonH_t h, const cmJsonNode_t* objectNodePtr, const char* pathPrefix, const char* path, unsigned* retValPtr );
  198. cmJsRC_t cmJsonPathToReal( cmJsonH_t h, const cmJsonNode_t* objectNodePtr, const char* pathPrefix, const char* path, double* retValPtr );
  199. cmJsRC_t cmJsonPathToString( cmJsonH_t h, const cmJsonNode_t* objectNodePtr, const char* pathPrefix, const char* path, const char** retValPtr );
  200. cmJsRC_t cmJsonPathToPair( cmJsonH_t h, const cmJsonNode_t* objectNodePtr, const char* pathPrefix, const char* path, cmJsonNode_t** retValPtr );
  201. cmJsRC_t cmJsonPathToArray( cmJsonH_t h, const cmJsonNode_t* objectNodePtr, const char* pathPrefix, const char* path, cmJsonNode_t** retValPtr );
  202. cmJsRC_t cmJsonPathToObject( cmJsonH_t h, const cmJsonNode_t* objectNodePtr, const char* pathPrefix, const char* path, cmJsonNode_t** retValPtr );
  203. // Same as cmJsonMemberValues() except labels may be paths to a given variable.
  204. // These paths are equivalent to those used in cmJsonFindPathValue()
  205. // If objectNodePtr is NULL then the JSON tree root is used as the
  206. // base reference object.
  207. // If pathPrefix is non-NULL then it is appended to each of the
  208. // individual paths.
  209. cmJsRC_t cmJsonVPathValues(cmJsonH_t h, const char* pathPrefix, const cmJsonNode_t* objectNodePtr, const char** errLabelPtrPtr, va_list vl );
  210. cmJsRC_t cmJsonPathValues( cmJsonH_t h, const char* pathPrefix, const cmJsonNode_t* objectNodePtr, const char** errLabelPtrPtr, ... );
  211. // Set 'typeId' to the type of the new node.
  212. // Use 'intVal' for the value of int nodes.
  213. // Use 'realVal' for the value of real nodes.
  214. // Use 'stringVal' for the label of pairs and the value of string nodes.
  215. // 'retNodePtrPtr' is optional
  216. cmJsRC_t cmJsonCreate( cmJsonH_t h, cmJsonNode_t* parentPtr, unsigned typeId, const char* stringVal, int intVal, double realVal, cmJsonNode_t** newNodePtrPtr );
  217. // Insert new nodes in the tree. If the tree is empty then the first
  218. // inserted node will become the root (this must be an object or array node.).
  219. cmJsonNode_t* cmJsonCreateObject( cmJsonH_t h, cmJsonNode_t* parentPtr );
  220. cmJsonNode_t* cmJsonCreateArray( cmJsonH_t h, cmJsonNode_t* parentPtr );
  221. cmJsonNode_t* cmJsonCreatePair( cmJsonH_t h, cmJsonNode_t* parentPtr, const char* label );
  222. cmJsRC_t cmJsonCreateString( cmJsonH_t h, cmJsonNode_t* parentPtr, const char* stringValue );
  223. cmJsRC_t cmJsonCreateStringN(cmJsonH_t h, cmJsonNode_t* parentPtr, const char* stringValue, unsigned stringCharCnt );
  224. cmJsRC_t cmJsonCreateInt( cmJsonH_t h, cmJsonNode_t* parentPtr, int value );
  225. cmJsRC_t cmJsonCreateReal( cmJsonH_t h, cmJsonNode_t* parentPtr, double value );
  226. cmJsRC_t cmJsonCreateBool( cmJsonH_t h, cmJsonNode_t* parentPtr, bool value );
  227. cmJsRC_t cmJsonCreateNull( cmJsonH_t h, cmJsonNode_t* parentPtr );
  228. cmJsRC_t cmJsonCreateStringArray( cmJsonH_t h, cmJsonNode_t* parentPtr, unsigned n, const char** values );
  229. cmJsRC_t cmJsonCreateIntArray( cmJsonH_t h, cmJsonNode_t* parentPtr, unsigned n, const int* values );
  230. cmJsRC_t cmJsonCreateRealArray( cmJsonH_t h, cmJsonNode_t* parentPtr, unsigned n, const double* values );
  231. cmJsRC_t cmJsonCreateBoolArray( cmJsonH_t h, cmJsonNode_t* parentPtr, unsigned n, const bool* values );
  232. //--------------------------------------------------------------------------------------------------------------
  233. //
  234. // Tree creation helper functiosn
  235. //
  236. cmJsRC_t cmJsonSetInt( cmJsonH_t h, cmJsonNode_t* np, int ival );
  237. cmJsRC_t cmJsonSetReal( cmJsonH_t h, cmJsonNode_t * np, double rval );
  238. cmJsRC_t cmJsonSetBool( cmJsonH_t h, cmJsonNode_t * np, bool bval );
  239. cmJsRC_t cmJsonSetString( cmJsonH_t h, cmJsonNode_t* np, const char* sval );
  240. // Insert a pair with a value indicated by 'typeId'.
  241. // 'stringVal','intVal' and 'realVal' are used as in cmJsonCreate().
  242. // Return a pointer to the new pair.
  243. cmJsonNode_t* cmJsonInsertPair( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned typeId, const char* stringVal, int intVal, double realVal );
  244. // Create a pair node and the associated label and value nodes and insert the pair in a parent object.
  245. // The object,array and pair creation functions return pointers to the pair value node.
  246. // These are helper functions that are implemented in terms of cmJsonCreateXXX() function.
  247. cmJsonNode_t* cmJsonInsertPairObject( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label );
  248. cmJsonNode_t* cmJsonInsertPairArray( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label );
  249. cmJsonNode_t* cmJsonInsertPairPair( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, const char* pairLabel );
  250. cmJsRC_t cmJsonInsertPairInt( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, int intVal );
  251. cmJsRC_t cmJsonInsertPairReal( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, double realVal );
  252. cmJsRC_t cmJsonInsertPairString( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, const char* string );
  253. cmJsRC_t cmJsonInsertPairStringN(cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, const char* string, unsigned stringCharCnt );
  254. cmJsRC_t cmJsonInsertPairBool( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, bool boolVal );
  255. cmJsRC_t cmJsonInsertPairNull( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label );
  256. cmJsRC_t cmJsonInsertPairIntArray( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned n, const int* values );
  257. cmJsRC_t cmJsonInsertPairRealArray( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned n, const double* values );
  258. cmJsRC_t cmJsonInsertPairStringArray( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned n, const char** values );
  259. cmJsRC_t cmJsonInsertPairBoolArray( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned n, const bool* values );
  260. // Returns pair pointer
  261. cmJsonNode_t* cmJsonInsertPairIntArray2( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned n, const int* values );
  262. cmJsonNode_t* cmJsonInsertPairRealArray2( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned n, const double* values );
  263. cmJsonNode_t* cmJsonInsertPairStringArray2( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned n, const char** values );
  264. cmJsonNode_t* cmJsonInsertPairBoolArray2( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned n, const bool* values );
  265. // Insert a pair (same as cmJsonInsertPair()) or if a pair
  266. // with a matching label/type already exists then replace the
  267. // existing value with a the new value.
  268. //
  269. // Set matchTypeMask with the type id's of all pair value types
  270. // which sould be considered a match. If matchTypeMask is set to
  271. // kInvalidTId then all value types will match.
  272. //
  273. // Return a pointer to the new or existing pair.
  274. //
  275. // When newTypeId == kObjectTId or kArrayTId then 'nv' may optionally be set to an object or array
  276. // to be set as the new value node for the selected pair. If 'nv' is NULL then an empty array or
  277. // object is created as the pair value node.
  278. //
  279. // When newTypeId == kPairTId then we are inserting/replacing a pair as the value of the selected pair.
  280. // In this case sv must be set to the new pair label. 'nv' may be optionally
  281. // set to a new pair value node. If 'nv' is NULL then the the new pair will have a value of type kNullTId
  282. cmJsonNode_t* cmJsonInsertOrReplacePair( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, unsigned newTypeId, const char* sv, int iv, double dv, cmJsonNode_t* nv );
  283. // Returns pointer to object node.
  284. cmJsonNode_t* cmJsonInsertOrReplacePairObject( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, cmJsonNode_t* newObjNodePtr );
  285. // Returns pointer to array node.
  286. cmJsonNode_t* cmJsonInsertOrReplacePairArray( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, cmJsonNode_t* newArrayNodePtr );
  287. // Returns pointer to child pair node
  288. cmJsonNode_t* cmJsonInsertOrReplacePairPair( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, const char* newPairLabel, cmJsonNode_t* newPairValNodePtr );
  289. cmJsRC_t cmJsonInsertOrReplacePairInt( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, int intVal );
  290. cmJsRC_t cmJsonInsertOrReplacePairReal( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, double realVal );
  291. cmJsRC_t cmJsonInsertOrReplacePairString( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, const char* string );
  292. cmJsRC_t cmJsonInsertOrReplacePairBool( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, bool boolVal );
  293. cmJsRC_t cmJsonInsertOrReplacePairNull( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask );
  294. // Same as the above cmJsonInsertOrReplaceXXX() functions except
  295. // the function fails if a matching pair is not found.
  296. //
  297. // Replace a pair with the same name/type and return a pointer to the
  298. // effected pair. If a pair with the same name and type are not
  299. // found then no change is made and the function returns NULL.
  300. // For newTypeId=kObjectTId,kArrayTId,kPairTId the replaced pair node is blank,
  301. // in other words it will have no child nodes.
  302. cmJsonNode_t* cmJsonReplacePair( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, unsigned newTypeId, const char* sv, int iv, double dv, cmJsonNode_t* nv );
  303. // Returns pointer to object node.
  304. cmJsonNode_t* cmJsonReplacePairObject( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, cmJsonNode_t* newObjNodePtr );
  305. // Return pointer to array node.
  306. cmJsonNode_t* cmJsonReplacePairArray( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, cmJsonNode_t* newArrayNodePtr );
  307. // Returns pointer to child pair node.
  308. cmJsonNode_t* cmJsonReplacePairPair( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, const char* newPairLabel, cmJsonNode_t* newPairValueNodePtr );
  309. cmJsRC_t cmJsonReplacePairInt( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, int intVal );
  310. cmJsRC_t cmJsonReplacePairReal( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, double realVal );
  311. cmJsRC_t cmJsonReplacePairString( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, const char* string );
  312. cmJsRC_t cmJsonReplacePairBool( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask, bool boolVal );
  313. cmJsRC_t cmJsonReplacePairNull( cmJsonH_t h, cmJsonNode_t* objectNodePtr, const char* label, unsigned matchTypeMask );
  314. // Insert multiple pairs in a parent object. Terminate the pair sets with NULL.
  315. // Note that pair,int,real,bool, and string pairs are specified with 3 args: <label>,<typeId>,<value>
  316. // all others are specified with 2 args: <label>,<typeId>.
  317. // The last argument in this function must always be NULL.
  318. cmJsRC_t cmJsonVInsertPairs( cmJsonH_t h, cmJsonNode_t* objectNodePtr, va_list vl );
  319. cmJsRC_t cmJsonInsertPairs( cmJsonH_t h, cmJsonNode_t* objectNodePtr, ... );
  320. // Create an object node, fill it with the specified pairs, and return a pointer to
  321. // the new object node.
  322. // This function uses same var args syntax as cmJsonInsertPairs()
  323. cmJsonNode_t* cmJsonVCreateFilledObject( cmJsonH_t h, cmJsonNode_t* parentPtr, va_list vl );
  324. cmJsonNode_t* cmJsonCreateFilledObject( cmJsonH_t h, cmJsonNode_t* parentPtr, ... );
  325. //--------------------------------------------------------------------------------------------------------------
  326. // Remove a node from the tree by unlinking it from its
  327. // parent and siblings.
  328. // Set the freeFl to true if the node memory should also
  329. // be released.
  330. //
  331. // If 'freeFl' is false then np->ownerPtr and
  332. // np->siblingPtr remain valid when the function returns.
  333. // Even with the valid pointer however be careful
  334. // not to use the node in a way that it depends
  335. // on existing in the tree since the parent and
  336. // siblings will no longer know about it.
  337. //
  338. // If np is the root then the internal tree will be
  339. // cleared (i.e. cmJsonRoot(h) == NULL).
  340. //
  341. // This function will fail if 'np' points to the label value
  342. // of a pair node. Pair labels cannot be removed because this
  343. // would result in an invalid tree (all pairs must have two
  344. // child nodes where the first node is a string value). If 'np'
  345. // points to a pair value node then the value node is replaced
  346. // with a null node to maintain a valid pair structure.
  347. cmJsRC_t cmJsonRemoveNode( cmJsonH_t h, cmJsonNode_t* np, bool freeFl );
  348. //--------------------------------------------------------------------------------------------------------------
  349. // Duplicate the subtree pointed to by 'np' and attach it as a child
  350. // of the node pointed to by 'parentPtr'. This function performs a
  351. // deep copy of the subtree pointed to by np and returns the pointer
  352. // to the duplicated subtree.
  353. //
  354. // 'parentPtr' must be a legal parent for the sub-tree or NULL to not
  355. // attach the duplicate tree to any parent.
  356. //
  357. // The returned value is a pointer to the new subtree.
  358. //
  359. // If an error occurs the return value is NULL and cmJsonErrorCode()
  360. // can be used to obtain the code associated with the error.
  361. cmJsonNode_t* cmJsonDuplicateNode( cmJsonH_t h, const cmJsonNode_t* np, cmJsonNode_t* parentPtr );
  362. //--------------------------------------------------------------------------------------------------------------
  363. // Copy any pairs not found in the destintaion object from the
  364. // source object.
  365. // If an error occurs during merging the destination object is
  366. // returned unmodified. The most likely cause of an error is a
  367. // destination pair with the same name but different type
  368. // than a source pair.
  369. cmJsRC_t cmJsonMergeObjectNodes( cmJsonH_t h, cmJsonNode_t* destObjNodePtr, const cmJsonNode_t* srcObjNodePtr );
  370. //--------------------------------------------------------------------------------------------------------------
  371. // Validate the tree.
  372. cmJsRC_t cmJsonValidateTree( cmJsonH_t h );
  373. // Validate the tree beginning with np. Note that this function does
  374. // not print an error on failure but simply returns kValidateFailJsRC.
  375. cmJsRC_t cmJsonValidate( const cmJsonNode_t* np );
  376. // Get the count of bytes required to serialize the tree rooted at 'np'.
  377. unsigned cmJsonSerialByteCount( const cmJsonNode_t* np );
  378. // Serialize the tree rooted at 'np' into the buffer buf[bufByteCnt].
  379. cmJsRC_t cmJsonSerialize( const cmJsonNode_t* np, void* buf, unsigned bufByteCnt );
  380. // Serialize the subtree indicated by 'np' or the entire tree
  381. // if 'np' is NULL. The buffer created by this call will exist
  382. // for the life of 'h' or until the next call to cmJsonSerialize().
  383. // This function is implemented in terms of cmJsonSerialByteCount()
  384. // and cmJsonSerializeTree().
  385. cmJsRC_t cmJsonSerializeTree( cmJsonH_t h, const cmJsonNode_t* np, void** bufPtrPtr, unsigned* bufByteCntPtr);
  386. // Recreate the objects previously serialzed via cmJsonSerialize().
  387. // The tree held in the buffer will be reconstructed as a child of
  388. // altRootPtr (if it is non-NULL) or the internal root.
  389. // If altRootPtr is given then it must point to an array
  390. // or object node.
  391. cmJsRC_t cmJsonDeserialize( cmJsonH_t h, const void* bufPtr, cmJsonNode_t* altRootPtr );
  392. // Return a string/int/real/null/bool node as a string value.
  393. cmJsRC_t cmJsonLeafToString( const cmJsonNode_t* np, cmChar_t* buf, unsigned bufCharCnt );
  394. // Given a CSV file convert it to an array of JSON objects.
  395. // The first line of the CSV file must contain a comma seperated lists of types.
  396. // The type labels must be from the set: 'int','real','string','true','false'.
  397. // Note that either 'true' or 'false' can be use for boolean columns.
  398. // The seocnd line contains the field names as comma separated quoted strings.
  399. // For example "column1","column2","column3"
  400. // The data is presented as comma separated fields.
  401. // If parentNodePtr is NULL then the array will be created unattached to
  402. // the tree.
  403. // if arrayNodePtrPtr is non-NULL then the array node ptr will be returned.
  404. cmJsRC_t cmJsonFromCSV( cmJsonH_t h, const char* iFn, cmJsonNode_t* parentPtr, cmJsonNode_t** arrayNodePtrPtr );
  405. // Write a CSV file from an array of objects.
  406. // arrayNodePtr must point to an array of objects.
  407. cmJsRC_t cmJsonToCSV( cmJsonH_t h, const char* oFn, const cmJsonNode_t* arrayNodePtr );
  408. // Print the subtree using 'np as the root.
  409. void cmJsonPrintTree( const cmJsonNode_t* np, cmRpt_t* rpt );
  410. // Print the subtree using 'np' as the root to a file.
  411. // 'np' is optional and defaults to cmJsonRoot().
  412. cmJsRC_t cmJsonWrite( cmJsonH_t h, const cmJsonNode_t* np, const cmChar_t* fn );
  413. // Return the code of the last error generated. This is useful for the
  414. // the cmJsonCreateXXX() functions which do not return error codes but
  415. // may still fail.
  416. cmJsRC_t cmJsonErrorCode( cmJsonH_t h );
  417. void cmJsonClearErrorCode( cmJsonH_t h );
  418. // Validate the tree and print all the nodes.
  419. cmJsRC_t cmJsonReport( cmJsonH_t h );
  420. // Testing stub.
  421. cmJsRC_t cmJsonTest( const char* fn, cmCtx_t* ctx );
  422. //)
  423. #ifdef __cplusplus
  424. }
  425. #endif
  426. #endif