libcm is a C development framework with an emphasis on audio signal processing applications.
Du kannst nicht mehr als 25 Themen auswählen Themen müssen mit entweder einem Buchstaben oder einer Ziffer beginnen. Sie können Bindestriche („-“) enthalten und bis zu 35 Zeichen lang sein.

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