Fossil SCM
A number of small doc improvements.
Commit
fa17e0980cd098a964a27033deb18a1a83f275ba
Parent
2f48be58a72d55f…
2 files changed
+22
-11
+13
-4
+22
-11
| --- src/json.c | ||
| +++ src/json.c | ||
| @@ -279,12 +279,13 @@ | ||
| 279 | 279 | blob_append( b, (char const *)src, (int)n ) /* will die on OOM */; |
| 280 | 280 | return 0; |
| 281 | 281 | } |
| 282 | 282 | |
| 283 | 283 | /* |
| 284 | -** Implements the cson_data_source_f() interface and reads | |
| 285 | -** input from a fossil Blob object. pState must be-a (Blob*). | |
| 284 | +** Implements the cson_data_source_f() interface and reads input from | |
| 285 | +** a fossil Blob object. pState must be-a (Blob*) populated with JSON | |
| 286 | +** data. | |
| 286 | 287 | */ |
| 287 | 288 | int cson_data_src_Blob(void * pState, void * dest, unsigned int * n){ |
| 288 | 289 | Blob * b = (Blob*)pState; |
| 289 | 290 | *n = blob_read( b, dest, *n ); |
| 290 | 291 | return 0; |
| @@ -304,12 +305,12 @@ | ||
| 304 | 305 | ** from pSrc. pSrc is rewound before parsing. |
| 305 | 306 | ** |
| 306 | 307 | ** pInfo may be NULL. If it is not NULL then it will contain details |
| 307 | 308 | ** about the parse state when this function returns. |
| 308 | 309 | ** |
| 309 | -** On success a new JSON Object or Array is returned. On error NULL is | |
| 310 | -** returned. | |
| 310 | +** On success a new JSON Object or Array is returned (owned by the | |
| 311 | +** caller). On error NULL is returned. | |
| 311 | 312 | */ |
| 312 | 313 | cson_value * cson_parse_Blob( Blob * pSrc, cson_parse_info * pInfo ){ |
| 313 | 314 | cson_value * root = NULL; |
| 314 | 315 | blob_rewind( pSrc ); |
| 315 | 316 | cson_parse( &root, cson_data_src_Blob, pSrc, NULL, pInfo ); |
| @@ -369,11 +370,15 @@ | ||
| 369 | 370 | if( 0 != rc ){ |
| 370 | 371 | cson_value_free( v ); |
| 371 | 372 | } |
| 372 | 373 | assert( (0==rc) && "Adding item to GC failed." ); |
| 373 | 374 | if(0!=rc){ |
| 374 | - fprintf(stderr,"%s: FATAL: alloc error.\n", fossil_nameofexe()); | |
| 375 | + fprintf(stderr,"%s: FATAL: alloc error.\n", fossil_nameofexe()) | |
| 376 | + /* reminder: allocation error is the only reasonable cause of | |
| 377 | + error here, provided g.json.gc.a and v are not NULL. | |
| 378 | + */ | |
| 379 | + ; | |
| 375 | 380 | fossil_exit(1)/*not fossil_panic() b/c it might land us somewhere |
| 376 | 381 | where this function is called again. |
| 377 | 382 | */; |
| 378 | 383 | } |
| 379 | 384 | } |
| @@ -437,10 +442,13 @@ | ||
| 437 | 442 | cv = getenv(zKey); |
| 438 | 443 | } |
| 439 | 444 | if(cv){/*transform it to JSON for later use.*/ |
| 440 | 445 | /* use sscanf() to figure out if it's an int, |
| 441 | 446 | and transform it to JSON int if it is. |
| 447 | + | |
| 448 | + FIXME: use strtol(), since it has more accurate | |
| 449 | + error handling. | |
| 442 | 450 | */ |
| 443 | 451 | int intVal = -1; |
| 444 | 452 | char endOfIntCheck; |
| 445 | 453 | int const scanRc = sscanf(cv,"%d%c",&intVal, &endOfIntCheck) |
| 446 | 454 | /* The %c bit there is to make sure that we don't accept 123x |
| @@ -545,12 +553,12 @@ | ||
| 545 | 553 | /* |
| 546 | 554 | ** An extended form of find_option() which tries to look up a combo |
| 547 | 555 | ** GET/POST/CLI argument. |
| 548 | 556 | ** |
| 549 | 557 | ** zKey must be the GET/POST parameter key. zCLILong must be the "long |
| 550 | -** form" CLI flag (NULL means to use zKey). zCLIShort may be NUL or | |
| 551 | -** the "short form" CLI flag. | |
| 558 | +** form" CLI flag (NULL means to use zKey). zCLIShort may be NULL or | |
| 559 | +** the "short form" CLI flag (if NULL, no short form is used). | |
| 552 | 560 | ** |
| 553 | 561 | ** If argPos is >=0 and no other match is found, |
| 554 | 562 | ** json_command_arg(argPos) is also checked. |
| 555 | 563 | ** |
| 556 | 564 | ** On error (no match found) NULL is returned. |
| @@ -613,10 +621,11 @@ | ||
| 613 | 621 | char const * zCLIShort, |
| 614 | 622 | int dflt ){ |
| 615 | 623 | enum { Magic = -947 }; |
| 616 | 624 | int rc = Magic; |
| 617 | 625 | if(!g.isHTTP){ |
| 626 | + /* FIXME: use strtol() for better error/dflt handling. */ | |
| 618 | 627 | char const * opt = find_option(zCLILong ? zCLILong : zKey, |
| 619 | 628 | zCLIShort, 1); |
| 620 | 629 | if(NULL!=opt){ |
| 621 | 630 | rc = atoi(opt); |
| 622 | 631 | } |
| @@ -645,11 +654,13 @@ | ||
| 645 | 654 | ** |
| 646 | 655 | ** It will try to figure out if the client can support |
| 647 | 656 | ** application/json or application/javascript, and will fall back to |
| 648 | 657 | ** text/plain if it cannot figure out anything more specific. |
| 649 | 658 | ** |
| 650 | -** Returned memory is static and immutable. | |
| 659 | +** Returned memory is static and immutable, but if the environment | |
| 660 | +** changes after calling this then subsequent calls to this function | |
| 661 | +** might return different (also static/immutable) values. | |
| 651 | 662 | */ |
| 652 | 663 | char const * json_guess_content_type(){ |
| 653 | 664 | char const * cset; |
| 654 | 665 | char doUtf8; |
| 655 | 666 | cset = PD("HTTP_ACCEPT_CHARSET",NULL); |
| @@ -1725,13 +1736,13 @@ | ||
| 1725 | 1736 | } |
| 1726 | 1737 | return v; |
| 1727 | 1738 | } |
| 1728 | 1739 | |
| 1729 | 1740 | /* |
| 1730 | -** Works just like json_stmt_to_array_of_obj(), but | |
| 1731 | -** each row in the result set is represented as an | |
| 1732 | -** Array instead of an Object. | |
| 1741 | +** Works just like json_stmt_to_array_of_obj(), but each row in the | |
| 1742 | +** result set is represented as an Array of values instead of an | |
| 1743 | +** Object (key/value pairs). | |
| 1733 | 1744 | */ |
| 1734 | 1745 | cson_value * json_stmt_to_array_of_array(Stmt *pStmt, |
| 1735 | 1746 | cson_value * pTgt){ |
| 1736 | 1747 | cson_value * v = pTgt; |
| 1737 | 1748 | cson_array * a = NULL; |
| 1738 | 1749 |
| --- src/json.c | |
| +++ src/json.c | |
| @@ -279,12 +279,13 @@ | |
| 279 | blob_append( b, (char const *)src, (int)n ) /* will die on OOM */; |
| 280 | return 0; |
| 281 | } |
| 282 | |
| 283 | /* |
| 284 | ** Implements the cson_data_source_f() interface and reads |
| 285 | ** input from a fossil Blob object. pState must be-a (Blob*). |
| 286 | */ |
| 287 | int cson_data_src_Blob(void * pState, void * dest, unsigned int * n){ |
| 288 | Blob * b = (Blob*)pState; |
| 289 | *n = blob_read( b, dest, *n ); |
| 290 | return 0; |
| @@ -304,12 +305,12 @@ | |
| 304 | ** from pSrc. pSrc is rewound before parsing. |
| 305 | ** |
| 306 | ** pInfo may be NULL. If it is not NULL then it will contain details |
| 307 | ** about the parse state when this function returns. |
| 308 | ** |
| 309 | ** On success a new JSON Object or Array is returned. On error NULL is |
| 310 | ** returned. |
| 311 | */ |
| 312 | cson_value * cson_parse_Blob( Blob * pSrc, cson_parse_info * pInfo ){ |
| 313 | cson_value * root = NULL; |
| 314 | blob_rewind( pSrc ); |
| 315 | cson_parse( &root, cson_data_src_Blob, pSrc, NULL, pInfo ); |
| @@ -369,11 +370,15 @@ | |
| 369 | if( 0 != rc ){ |
| 370 | cson_value_free( v ); |
| 371 | } |
| 372 | assert( (0==rc) && "Adding item to GC failed." ); |
| 373 | if(0!=rc){ |
| 374 | fprintf(stderr,"%s: FATAL: alloc error.\n", fossil_nameofexe()); |
| 375 | fossil_exit(1)/*not fossil_panic() b/c it might land us somewhere |
| 376 | where this function is called again. |
| 377 | */; |
| 378 | } |
| 379 | } |
| @@ -437,10 +442,13 @@ | |
| 437 | cv = getenv(zKey); |
| 438 | } |
| 439 | if(cv){/*transform it to JSON for later use.*/ |
| 440 | /* use sscanf() to figure out if it's an int, |
| 441 | and transform it to JSON int if it is. |
| 442 | */ |
| 443 | int intVal = -1; |
| 444 | char endOfIntCheck; |
| 445 | int const scanRc = sscanf(cv,"%d%c",&intVal, &endOfIntCheck) |
| 446 | /* The %c bit there is to make sure that we don't accept 123x |
| @@ -545,12 +553,12 @@ | |
| 545 | /* |
| 546 | ** An extended form of find_option() which tries to look up a combo |
| 547 | ** GET/POST/CLI argument. |
| 548 | ** |
| 549 | ** zKey must be the GET/POST parameter key. zCLILong must be the "long |
| 550 | ** form" CLI flag (NULL means to use zKey). zCLIShort may be NUL or |
| 551 | ** the "short form" CLI flag. |
| 552 | ** |
| 553 | ** If argPos is >=0 and no other match is found, |
| 554 | ** json_command_arg(argPos) is also checked. |
| 555 | ** |
| 556 | ** On error (no match found) NULL is returned. |
| @@ -613,10 +621,11 @@ | |
| 613 | char const * zCLIShort, |
| 614 | int dflt ){ |
| 615 | enum { Magic = -947 }; |
| 616 | int rc = Magic; |
| 617 | if(!g.isHTTP){ |
| 618 | char const * opt = find_option(zCLILong ? zCLILong : zKey, |
| 619 | zCLIShort, 1); |
| 620 | if(NULL!=opt){ |
| 621 | rc = atoi(opt); |
| 622 | } |
| @@ -645,11 +654,13 @@ | |
| 645 | ** |
| 646 | ** It will try to figure out if the client can support |
| 647 | ** application/json or application/javascript, and will fall back to |
| 648 | ** text/plain if it cannot figure out anything more specific. |
| 649 | ** |
| 650 | ** Returned memory is static and immutable. |
| 651 | */ |
| 652 | char const * json_guess_content_type(){ |
| 653 | char const * cset; |
| 654 | char doUtf8; |
| 655 | cset = PD("HTTP_ACCEPT_CHARSET",NULL); |
| @@ -1725,13 +1736,13 @@ | |
| 1725 | } |
| 1726 | return v; |
| 1727 | } |
| 1728 | |
| 1729 | /* |
| 1730 | ** Works just like json_stmt_to_array_of_obj(), but |
| 1731 | ** each row in the result set is represented as an |
| 1732 | ** Array instead of an Object. |
| 1733 | */ |
| 1734 | cson_value * json_stmt_to_array_of_array(Stmt *pStmt, |
| 1735 | cson_value * pTgt){ |
| 1736 | cson_value * v = pTgt; |
| 1737 | cson_array * a = NULL; |
| 1738 |
| --- src/json.c | |
| +++ src/json.c | |
| @@ -279,12 +279,13 @@ | |
| 279 | blob_append( b, (char const *)src, (int)n ) /* will die on OOM */; |
| 280 | return 0; |
| 281 | } |
| 282 | |
| 283 | /* |
| 284 | ** Implements the cson_data_source_f() interface and reads input from |
| 285 | ** a fossil Blob object. pState must be-a (Blob*) populated with JSON |
| 286 | ** data. |
| 287 | */ |
| 288 | int cson_data_src_Blob(void * pState, void * dest, unsigned int * n){ |
| 289 | Blob * b = (Blob*)pState; |
| 290 | *n = blob_read( b, dest, *n ); |
| 291 | return 0; |
| @@ -304,12 +305,12 @@ | |
| 305 | ** from pSrc. pSrc is rewound before parsing. |
| 306 | ** |
| 307 | ** pInfo may be NULL. If it is not NULL then it will contain details |
| 308 | ** about the parse state when this function returns. |
| 309 | ** |
| 310 | ** On success a new JSON Object or Array is returned (owned by the |
| 311 | ** caller). On error NULL is returned. |
| 312 | */ |
| 313 | cson_value * cson_parse_Blob( Blob * pSrc, cson_parse_info * pInfo ){ |
| 314 | cson_value * root = NULL; |
| 315 | blob_rewind( pSrc ); |
| 316 | cson_parse( &root, cson_data_src_Blob, pSrc, NULL, pInfo ); |
| @@ -369,11 +370,15 @@ | |
| 370 | if( 0 != rc ){ |
| 371 | cson_value_free( v ); |
| 372 | } |
| 373 | assert( (0==rc) && "Adding item to GC failed." ); |
| 374 | if(0!=rc){ |
| 375 | fprintf(stderr,"%s: FATAL: alloc error.\n", fossil_nameofexe()) |
| 376 | /* reminder: allocation error is the only reasonable cause of |
| 377 | error here, provided g.json.gc.a and v are not NULL. |
| 378 | */ |
| 379 | ; |
| 380 | fossil_exit(1)/*not fossil_panic() b/c it might land us somewhere |
| 381 | where this function is called again. |
| 382 | */; |
| 383 | } |
| 384 | } |
| @@ -437,10 +442,13 @@ | |
| 442 | cv = getenv(zKey); |
| 443 | } |
| 444 | if(cv){/*transform it to JSON for later use.*/ |
| 445 | /* use sscanf() to figure out if it's an int, |
| 446 | and transform it to JSON int if it is. |
| 447 | |
| 448 | FIXME: use strtol(), since it has more accurate |
| 449 | error handling. |
| 450 | */ |
| 451 | int intVal = -1; |
| 452 | char endOfIntCheck; |
| 453 | int const scanRc = sscanf(cv,"%d%c",&intVal, &endOfIntCheck) |
| 454 | /* The %c bit there is to make sure that we don't accept 123x |
| @@ -545,12 +553,12 @@ | |
| 553 | /* |
| 554 | ** An extended form of find_option() which tries to look up a combo |
| 555 | ** GET/POST/CLI argument. |
| 556 | ** |
| 557 | ** zKey must be the GET/POST parameter key. zCLILong must be the "long |
| 558 | ** form" CLI flag (NULL means to use zKey). zCLIShort may be NULL or |
| 559 | ** the "short form" CLI flag (if NULL, no short form is used). |
| 560 | ** |
| 561 | ** If argPos is >=0 and no other match is found, |
| 562 | ** json_command_arg(argPos) is also checked. |
| 563 | ** |
| 564 | ** On error (no match found) NULL is returned. |
| @@ -613,10 +621,11 @@ | |
| 621 | char const * zCLIShort, |
| 622 | int dflt ){ |
| 623 | enum { Magic = -947 }; |
| 624 | int rc = Magic; |
| 625 | if(!g.isHTTP){ |
| 626 | /* FIXME: use strtol() for better error/dflt handling. */ |
| 627 | char const * opt = find_option(zCLILong ? zCLILong : zKey, |
| 628 | zCLIShort, 1); |
| 629 | if(NULL!=opt){ |
| 630 | rc = atoi(opt); |
| 631 | } |
| @@ -645,11 +654,13 @@ | |
| 654 | ** |
| 655 | ** It will try to figure out if the client can support |
| 656 | ** application/json or application/javascript, and will fall back to |
| 657 | ** text/plain if it cannot figure out anything more specific. |
| 658 | ** |
| 659 | ** Returned memory is static and immutable, but if the environment |
| 660 | ** changes after calling this then subsequent calls to this function |
| 661 | ** might return different (also static/immutable) values. |
| 662 | */ |
| 663 | char const * json_guess_content_type(){ |
| 664 | char const * cset; |
| 665 | char doUtf8; |
| 666 | cset = PD("HTTP_ACCEPT_CHARSET",NULL); |
| @@ -1725,13 +1736,13 @@ | |
| 1736 | } |
| 1737 | return v; |
| 1738 | } |
| 1739 | |
| 1740 | /* |
| 1741 | ** Works just like json_stmt_to_array_of_obj(), but each row in the |
| 1742 | ** result set is represented as an Array of values instead of an |
| 1743 | ** Object (key/value pairs). |
| 1744 | */ |
| 1745 | cson_value * json_stmt_to_array_of_array(Stmt *pStmt, |
| 1746 | cson_value * pTgt){ |
| 1747 | cson_value * v = pTgt; |
| 1748 | cson_array * a = NULL; |
| 1749 |
+13
-4
| --- src/json_detail.h | ||
| +++ src/json_detail.h | ||
| @@ -108,24 +108,31 @@ | ||
| 108 | 108 | ** returns then the top-level dispatcher will destroy any payload |
| 109 | 109 | ** returned by this function and will output a JSON error response |
| 110 | 110 | ** instead. |
| 111 | 111 | ** |
| 112 | 112 | ** All of the setup/response code is handled by the top dispatcher |
| 113 | -** functions and the callbacks concern themselves only with generating | |
| 114 | -** the payload. | |
| 113 | +** functions and the callbacks concern themselves only with: | |
| 114 | +** | |
| 115 | +** a) Permissions checking (inspecting g.perm). | |
| 116 | +** b) generating a response payload (if applicable) | |
| 117 | +** c) Setting g.json's error state (if applicable). See json_set_err(). | |
| 115 | 118 | ** |
| 116 | 119 | ** It is imperitive that NO callback functions EVER output ANYTHING to |
| 117 | 120 | ** stdout, as that will effectively corrupt any JSON output, and |
| 118 | 121 | ** almost certainly will corrupt any HTTP response headers. Output |
| 119 | 122 | ** sent to stderr ends up in my apache log, so that might be useful |
| 120 | -** for debuggering in some cases, but so such code should be left | |
| 123 | +** for debuggering in some cases, but no such code should be left | |
| 121 | 124 | ** enabled for non-debuggering builds. |
| 122 | 125 | */ |
| 123 | 126 | typedef cson_value * (*fossil_json_f)(); |
| 124 | 127 | |
| 125 | 128 | /* |
| 126 | 129 | ** Holds name-to-function mappings for JSON page/command dispatching. |
| 130 | +** | |
| 131 | +** Internally we model page dispatching lists as arrays of these | |
| 132 | +** objects, where the final entry in the array has a NULL name value | |
| 133 | +** to act as the end-of-list sentinel. | |
| 127 | 134 | ** |
| 128 | 135 | */ |
| 129 | 136 | typedef struct JsonPageDef{ |
| 130 | 137 | /* |
| 131 | 138 | ** The commmand/page's name (path, not including leading /json/). |
| @@ -181,11 +188,13 @@ | ||
| 181 | 188 | ** matching name. If found then that page's func() is called to fetch |
| 182 | 189 | ** the payload, which is returned to the caller. |
| 183 | 190 | ** |
| 184 | 191 | ** On error, g.json.resultCode is set to one of the FossilJsonCodes |
| 185 | 192 | ** values and NULL is returned. If non-NULL is returned, ownership is |
| 186 | -** transfered to the caller. | |
| 193 | +** transfered to the caller (but the g.json error state might still be | |
| 194 | +** set in that case, so the caller must check that or pass it on up | |
| 195 | +** the dispatch chain). | |
| 187 | 196 | */ |
| 188 | 197 | cson_value * json_page_dispatch_helper(JsonPageDef const * pages); |
| 189 | 198 | |
| 190 | 199 | /* |
| 191 | 200 | ** Implements the /json/wiki family of pages/commands. |
| 192 | 201 |
| --- src/json_detail.h | |
| +++ src/json_detail.h | |
| @@ -108,24 +108,31 @@ | |
| 108 | ** returns then the top-level dispatcher will destroy any payload |
| 109 | ** returned by this function and will output a JSON error response |
| 110 | ** instead. |
| 111 | ** |
| 112 | ** All of the setup/response code is handled by the top dispatcher |
| 113 | ** functions and the callbacks concern themselves only with generating |
| 114 | ** the payload. |
| 115 | ** |
| 116 | ** It is imperitive that NO callback functions EVER output ANYTHING to |
| 117 | ** stdout, as that will effectively corrupt any JSON output, and |
| 118 | ** almost certainly will corrupt any HTTP response headers. Output |
| 119 | ** sent to stderr ends up in my apache log, so that might be useful |
| 120 | ** for debuggering in some cases, but so such code should be left |
| 121 | ** enabled for non-debuggering builds. |
| 122 | */ |
| 123 | typedef cson_value * (*fossil_json_f)(); |
| 124 | |
| 125 | /* |
| 126 | ** Holds name-to-function mappings for JSON page/command dispatching. |
| 127 | ** |
| 128 | */ |
| 129 | typedef struct JsonPageDef{ |
| 130 | /* |
| 131 | ** The commmand/page's name (path, not including leading /json/). |
| @@ -181,11 +188,13 @@ | |
| 181 | ** matching name. If found then that page's func() is called to fetch |
| 182 | ** the payload, which is returned to the caller. |
| 183 | ** |
| 184 | ** On error, g.json.resultCode is set to one of the FossilJsonCodes |
| 185 | ** values and NULL is returned. If non-NULL is returned, ownership is |
| 186 | ** transfered to the caller. |
| 187 | */ |
| 188 | cson_value * json_page_dispatch_helper(JsonPageDef const * pages); |
| 189 | |
| 190 | /* |
| 191 | ** Implements the /json/wiki family of pages/commands. |
| 192 |
| --- src/json_detail.h | |
| +++ src/json_detail.h | |
| @@ -108,24 +108,31 @@ | |
| 108 | ** returns then the top-level dispatcher will destroy any payload |
| 109 | ** returned by this function and will output a JSON error response |
| 110 | ** instead. |
| 111 | ** |
| 112 | ** All of the setup/response code is handled by the top dispatcher |
| 113 | ** functions and the callbacks concern themselves only with: |
| 114 | ** |
| 115 | ** a) Permissions checking (inspecting g.perm). |
| 116 | ** b) generating a response payload (if applicable) |
| 117 | ** c) Setting g.json's error state (if applicable). See json_set_err(). |
| 118 | ** |
| 119 | ** It is imperitive that NO callback functions EVER output ANYTHING to |
| 120 | ** stdout, as that will effectively corrupt any JSON output, and |
| 121 | ** almost certainly will corrupt any HTTP response headers. Output |
| 122 | ** sent to stderr ends up in my apache log, so that might be useful |
| 123 | ** for debuggering in some cases, but no such code should be left |
| 124 | ** enabled for non-debuggering builds. |
| 125 | */ |
| 126 | typedef cson_value * (*fossil_json_f)(); |
| 127 | |
| 128 | /* |
| 129 | ** Holds name-to-function mappings for JSON page/command dispatching. |
| 130 | ** |
| 131 | ** Internally we model page dispatching lists as arrays of these |
| 132 | ** objects, where the final entry in the array has a NULL name value |
| 133 | ** to act as the end-of-list sentinel. |
| 134 | ** |
| 135 | */ |
| 136 | typedef struct JsonPageDef{ |
| 137 | /* |
| 138 | ** The commmand/page's name (path, not including leading /json/). |
| @@ -181,11 +188,13 @@ | |
| 188 | ** matching name. If found then that page's func() is called to fetch |
| 189 | ** the payload, which is returned to the caller. |
| 190 | ** |
| 191 | ** On error, g.json.resultCode is set to one of the FossilJsonCodes |
| 192 | ** values and NULL is returned. If non-NULL is returned, ownership is |
| 193 | ** transfered to the caller (but the g.json error state might still be |
| 194 | ** set in that case, so the caller must check that or pass it on up |
| 195 | ** the dispatch chain). |
| 196 | */ |
| 197 | cson_value * json_page_dispatch_helper(JsonPageDef const * pages); |
| 198 | |
| 199 | /* |
| 200 | ** Implements the /json/wiki family of pages/commands. |
| 201 |