Fossil SCM
(Typos) www/json-api/hacking.md changes.
Commit
203578f7102f0f3a7395279c33df3c9e33cf028d5ed758f45df563f648cc1727
Parent
9d9193fd4db6cdb…
1 file changed
+7
-7
+7
-7
| --- www/json-api/hacking.md | ||
| +++ www/json-api/hacking.md | ||
| @@ -79,11 +79,11 @@ | ||
| 79 | 79 | core. The disadvantages of this are that we lose fossil's conventional |
| 80 | 80 | help text mechanism (which is based on code comments in the |
| 81 | 81 | command/path's dispatcher impl) and the ability to write abbreviated |
| 82 | 82 | command names in CLI mode ("json" itself may be abbreviated, but not the |
| 83 | 83 | subcommands). The advantages are that we can handle CLI/HTTP modes |
| 84 | -almost identically (there are a couple minor differences) by unifying | |
| 84 | +almost identically (there are a couple of minor differences) by unifying | |
| 85 | 85 | them under the same callback functions much more easily. |
| 86 | 86 | |
| 87 | 87 | The top-level "json" command/path uses its own dispatching mechanism |
| 88 | 88 | which uses either the path (in HTTP mode) or CLI positional arguments to |
| 89 | 89 | dispatch commands (stopping at the first "flag option" (e.g. -foo) in |
| @@ -125,11 +125,11 @@ | ||
| 125 | 125 | (e.g. `db_prepare()` can be fatal, and callbacks may call `fossil_panic()` |
| 126 | 126 | if they really want to). One exception is `fossil_exit()`, which does |
| 127 | 127 | _not_ generate any extra output and will `exit()` the app. In the JSON |
| 128 | 128 | API, as a rule of thumb, `fossil_exit()` is only used when we *want* a |
| 129 | 129 | failed request to cause an HTTP 500 error, and it is reserved for |
| 130 | -allocation errors and similar truly catostrophic failures. That said... | |
| 130 | +allocation errors and similar truly catastrophic failures. That said... | |
| 131 | 131 | libcson has been hacked to use `fossil_alloc()` and friends for memory |
| 132 | 132 | management, and those routines exit on error, so alloc error handling in |
| 133 | 133 | the JSON command handler code can afford to be a little lax (the |
| 134 | 134 | majority of *potential* errors clients get from the cson API have |
| 135 | 135 | allocation failure as their root cause). |
| @@ -259,11 +259,11 @@ | ||
| 259 | 259 | - `json_getenv()` and `json_getenv_TYPE()` search the so-called "JSON |
| 260 | 260 | environment," which is a superset of the GET/POST/`POST.payload` (if |
| 261 | 261 | `POST.payload` is-a Object). |
| 262 | 262 | - `json_find_option_TYPE()`: searches the CLI args (only when in CLI |
| 263 | 263 | mode) and the JSON environment. |
| 264 | -- The use of fossil's `P()` and `PD()` macros is discourages in JSON | |
| 264 | +- The use of fossil's `P()` and `PD()` macros is discouraged in JSON | |
| 265 | 265 | callbacks because they can only handle String data from the CLI or |
| 266 | 266 | GET parameters (not POST/`POST.payload`). (Note that `P()` and `PD()` |
| 267 | 267 | *normally* also handle POSTed keys, but they only "see" values |
| 268 | 268 | posted as form-urlencoded fields, and not JSON format.) |
| 269 | 269 | - `find_option()` (from `src/main.c`) "should" also be avoided in |
| @@ -280,11 +280,11 @@ | ||
| 280 | 280 | |
| 281 | 281 | <a href="creating-json-values"></a> |
| 282 | 282 | ## Creating JSON Values |
| 283 | 283 | |
| 284 | 284 | cson has a fairly rich API for creating and manipulating the various |
| 285 | -JSON-defined value types. For a detailed overview and demonstration i | |
| 285 | +JSON-defined value types. For a detailed overview and demonstration I | |
| 286 | 286 | recommend reading: |
| 287 | 287 | |
| 288 | 288 | [](https://fossil.wanderinghorse.net/wikis/cson/?page=HowTo) |
| 289 | 289 | |
| 290 | 290 | That said, the Fossil/JSON API has several convenience wrappers to save |
| @@ -310,15 +310,15 @@ | ||
| 310 | 310 | to Arrays or Objects, or convert single columns to a JSON-compatible |
| 311 | 311 | form. See `json_stmt_to_array_of_obj()`, |
| 312 | 312 | `json_stmt_to_array_of_array()` (both in `src/json.c`), and |
| 313 | 313 | `cson_sqlite3_column_to_value()` and friends (in |
| 314 | 314 | `extsrc/cson_amalgamation.h`). They work in an intuitive way for numeric |
| 315 | -types, but they optimistically/natively *assume* that any fields of type | |
| 315 | +types, but they optimistically/naively *assume* that any fields of type | |
| 316 | 316 | TEXT or BLOB are actually UTF8 data, and treat them as such. cson's |
| 317 | 317 | string class only handles UTF8 data and it is semantically illegal to |
| 318 | 318 | feed them anything but UTF8. Violating this will likely result in |
| 319 | -down-stream errors (e.g. when emiting the JSON string output). **The | |
| 319 | +down-stream errors (e.g. when emitting the JSON string output). **The | |
| 320 | 320 | moral of this story is:** *do not use these APIs to fetch binary data*. |
| 321 | 321 | JSON doesn't do binary and the `cson_string` class does not |
| 322 | 322 | protect itself against clients feeding it non-UTF8 data. |
| 323 | 323 | |
| 324 | 324 | Here's a basic example of using these features: |
| @@ -347,7 +347,7 @@ | ||
| 347 | 347 | AS clauses to be guaranteed that the db driver will return the column |
| 348 | 348 | names we want. Note that the AS clause is often used to translate column |
| 349 | 349 | names into something more JSON-conventional or user-friendly, e.g. |
| 350 | 350 | "SELECT cap AS capabilities...". Alternately, we can convert the |
| 351 | 351 | individual `sqlite3_stmt` column values to JSON using |
| 352 | -`cson_sqlite3_column_to_value()`, without refering directly to the | |
| 352 | +`cson_sqlite3_column_to_value()`, without referring directly to the | |
| 353 | 353 | db-reported column name. |
| 354 | 354 |
| --- www/json-api/hacking.md | |
| +++ www/json-api/hacking.md | |
| @@ -79,11 +79,11 @@ | |
| 79 | core. The disadvantages of this are that we lose fossil's conventional |
| 80 | help text mechanism (which is based on code comments in the |
| 81 | command/path's dispatcher impl) and the ability to write abbreviated |
| 82 | command names in CLI mode ("json" itself may be abbreviated, but not the |
| 83 | subcommands). The advantages are that we can handle CLI/HTTP modes |
| 84 | almost identically (there are a couple minor differences) by unifying |
| 85 | them under the same callback functions much more easily. |
| 86 | |
| 87 | The top-level "json" command/path uses its own dispatching mechanism |
| 88 | which uses either the path (in HTTP mode) or CLI positional arguments to |
| 89 | dispatch commands (stopping at the first "flag option" (e.g. -foo) in |
| @@ -125,11 +125,11 @@ | |
| 125 | (e.g. `db_prepare()` can be fatal, and callbacks may call `fossil_panic()` |
| 126 | if they really want to). One exception is `fossil_exit()`, which does |
| 127 | _not_ generate any extra output and will `exit()` the app. In the JSON |
| 128 | API, as a rule of thumb, `fossil_exit()` is only used when we *want* a |
| 129 | failed request to cause an HTTP 500 error, and it is reserved for |
| 130 | allocation errors and similar truly catostrophic failures. That said... |
| 131 | libcson has been hacked to use `fossil_alloc()` and friends for memory |
| 132 | management, and those routines exit on error, so alloc error handling in |
| 133 | the JSON command handler code can afford to be a little lax (the |
| 134 | majority of *potential* errors clients get from the cson API have |
| 135 | allocation failure as their root cause). |
| @@ -259,11 +259,11 @@ | |
| 259 | - `json_getenv()` and `json_getenv_TYPE()` search the so-called "JSON |
| 260 | environment," which is a superset of the GET/POST/`POST.payload` (if |
| 261 | `POST.payload` is-a Object). |
| 262 | - `json_find_option_TYPE()`: searches the CLI args (only when in CLI |
| 263 | mode) and the JSON environment. |
| 264 | - The use of fossil's `P()` and `PD()` macros is discourages in JSON |
| 265 | callbacks because they can only handle String data from the CLI or |
| 266 | GET parameters (not POST/`POST.payload`). (Note that `P()` and `PD()` |
| 267 | *normally* also handle POSTed keys, but they only "see" values |
| 268 | posted as form-urlencoded fields, and not JSON format.) |
| 269 | - `find_option()` (from `src/main.c`) "should" also be avoided in |
| @@ -280,11 +280,11 @@ | |
| 280 | |
| 281 | <a href="creating-json-values"></a> |
| 282 | ## Creating JSON Values |
| 283 | |
| 284 | cson has a fairly rich API for creating and manipulating the various |
| 285 | JSON-defined value types. For a detailed overview and demonstration i |
| 286 | recommend reading: |
| 287 | |
| 288 | [](https://fossil.wanderinghorse.net/wikis/cson/?page=HowTo) |
| 289 | |
| 290 | That said, the Fossil/JSON API has several convenience wrappers to save |
| @@ -310,15 +310,15 @@ | |
| 310 | to Arrays or Objects, or convert single columns to a JSON-compatible |
| 311 | form. See `json_stmt_to_array_of_obj()`, |
| 312 | `json_stmt_to_array_of_array()` (both in `src/json.c`), and |
| 313 | `cson_sqlite3_column_to_value()` and friends (in |
| 314 | `extsrc/cson_amalgamation.h`). They work in an intuitive way for numeric |
| 315 | types, but they optimistically/natively *assume* that any fields of type |
| 316 | TEXT or BLOB are actually UTF8 data, and treat them as such. cson's |
| 317 | string class only handles UTF8 data and it is semantically illegal to |
| 318 | feed them anything but UTF8. Violating this will likely result in |
| 319 | down-stream errors (e.g. when emiting the JSON string output). **The |
| 320 | moral of this story is:** *do not use these APIs to fetch binary data*. |
| 321 | JSON doesn't do binary and the `cson_string` class does not |
| 322 | protect itself against clients feeding it non-UTF8 data. |
| 323 | |
| 324 | Here's a basic example of using these features: |
| @@ -347,7 +347,7 @@ | |
| 347 | AS clauses to be guaranteed that the db driver will return the column |
| 348 | names we want. Note that the AS clause is often used to translate column |
| 349 | names into something more JSON-conventional or user-friendly, e.g. |
| 350 | "SELECT cap AS capabilities...". Alternately, we can convert the |
| 351 | individual `sqlite3_stmt` column values to JSON using |
| 352 | `cson_sqlite3_column_to_value()`, without refering directly to the |
| 353 | db-reported column name. |
| 354 |
| --- www/json-api/hacking.md | |
| +++ www/json-api/hacking.md | |
| @@ -79,11 +79,11 @@ | |
| 79 | core. The disadvantages of this are that we lose fossil's conventional |
| 80 | help text mechanism (which is based on code comments in the |
| 81 | command/path's dispatcher impl) and the ability to write abbreviated |
| 82 | command names in CLI mode ("json" itself may be abbreviated, but not the |
| 83 | subcommands). The advantages are that we can handle CLI/HTTP modes |
| 84 | almost identically (there are a couple of minor differences) by unifying |
| 85 | them under the same callback functions much more easily. |
| 86 | |
| 87 | The top-level "json" command/path uses its own dispatching mechanism |
| 88 | which uses either the path (in HTTP mode) or CLI positional arguments to |
| 89 | dispatch commands (stopping at the first "flag option" (e.g. -foo) in |
| @@ -125,11 +125,11 @@ | |
| 125 | (e.g. `db_prepare()` can be fatal, and callbacks may call `fossil_panic()` |
| 126 | if they really want to). One exception is `fossil_exit()`, which does |
| 127 | _not_ generate any extra output and will `exit()` the app. In the JSON |
| 128 | API, as a rule of thumb, `fossil_exit()` is only used when we *want* a |
| 129 | failed request to cause an HTTP 500 error, and it is reserved for |
| 130 | allocation errors and similar truly catastrophic failures. That said... |
| 131 | libcson has been hacked to use `fossil_alloc()` and friends for memory |
| 132 | management, and those routines exit on error, so alloc error handling in |
| 133 | the JSON command handler code can afford to be a little lax (the |
| 134 | majority of *potential* errors clients get from the cson API have |
| 135 | allocation failure as their root cause). |
| @@ -259,11 +259,11 @@ | |
| 259 | - `json_getenv()` and `json_getenv_TYPE()` search the so-called "JSON |
| 260 | environment," which is a superset of the GET/POST/`POST.payload` (if |
| 261 | `POST.payload` is-a Object). |
| 262 | - `json_find_option_TYPE()`: searches the CLI args (only when in CLI |
| 263 | mode) and the JSON environment. |
| 264 | - The use of fossil's `P()` and `PD()` macros is discouraged in JSON |
| 265 | callbacks because they can only handle String data from the CLI or |
| 266 | GET parameters (not POST/`POST.payload`). (Note that `P()` and `PD()` |
| 267 | *normally* also handle POSTed keys, but they only "see" values |
| 268 | posted as form-urlencoded fields, and not JSON format.) |
| 269 | - `find_option()` (from `src/main.c`) "should" also be avoided in |
| @@ -280,11 +280,11 @@ | |
| 280 | |
| 281 | <a href="creating-json-values"></a> |
| 282 | ## Creating JSON Values |
| 283 | |
| 284 | cson has a fairly rich API for creating and manipulating the various |
| 285 | JSON-defined value types. For a detailed overview and demonstration I |
| 286 | recommend reading: |
| 287 | |
| 288 | [](https://fossil.wanderinghorse.net/wikis/cson/?page=HowTo) |
| 289 | |
| 290 | That said, the Fossil/JSON API has several convenience wrappers to save |
| @@ -310,15 +310,15 @@ | |
| 310 | to Arrays or Objects, or convert single columns to a JSON-compatible |
| 311 | form. See `json_stmt_to_array_of_obj()`, |
| 312 | `json_stmt_to_array_of_array()` (both in `src/json.c`), and |
| 313 | `cson_sqlite3_column_to_value()` and friends (in |
| 314 | `extsrc/cson_amalgamation.h`). They work in an intuitive way for numeric |
| 315 | types, but they optimistically/naively *assume* that any fields of type |
| 316 | TEXT or BLOB are actually UTF8 data, and treat them as such. cson's |
| 317 | string class only handles UTF8 data and it is semantically illegal to |
| 318 | feed them anything but UTF8. Violating this will likely result in |
| 319 | down-stream errors (e.g. when emitting the JSON string output). **The |
| 320 | moral of this story is:** *do not use these APIs to fetch binary data*. |
| 321 | JSON doesn't do binary and the `cson_string` class does not |
| 322 | protect itself against clients feeding it non-UTF8 data. |
| 323 | |
| 324 | Here's a basic example of using these features: |
| @@ -347,7 +347,7 @@ | |
| 347 | AS clauses to be guaranteed that the db driver will return the column |
| 348 | names we want. Note that the AS clause is often used to translate column |
| 349 | names into something more JSON-conventional or user-friendly, e.g. |
| 350 | "SELECT cap AS capabilities...". Alternately, we can convert the |
| 351 | individual `sqlite3_stmt` column values to JSON using |
| 352 | `cson_sqlite3_column_to_value()`, without referring directly to the |
| 353 | db-reported column name. |
| 354 |