From: larrybr Date: Thu, 10 Mar 2022 11:10:03 +0000 (+0000) Subject: Improve formatting of changes doc for this branch X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=29bc92bee224693db8182b09e2c7bd8f380aa50c;p=thirdparty%2Fsqlite.git Improve formatting of changes doc for this branch FossilOrigin-Name: 2129cfb8c5ff2bec9a9f61fd7bf3d63a7385a14ea0161798d1869fe2b87567e6 --- diff --git a/doc/sh_tweak_changes.md b/doc/sh_tweak_changes.md index 4b5c8b1f6a..5a53f4dbcb 100644 --- a/doc/sh_tweak_changes.md +++ b/doc/sh_tweak_changes.md @@ -11,33 +11,55 @@ This section summarizes the changes; motivation is addressed further below. ## Extension features made optional at build-time or runtime, for backwards compatibility. (Described further per-feature.) -## (internal) Query output display mode stack implemented and used. (Associated ShellState reorg supports this, and groups members more by purpose.) +## (internal) Query output display mode stack implemented and used. -## (internal) Expand temp.sqlite_parameters usage to include "scripts", with an extra column, "uses", limiting role of variables to either binding or execution. +(Associated ShellState reorg supports this, and groups members more by purpose.) -## (internal) Refactoring and interface adjustments to allow resuse by new code of previously buried operations or utility routines. +## (internal) Expand temp.sqlite_parameters usage to include "scripts". + +An extra column, "uses", limits role of variables to either binding or execution. This is set when variables are created, keyed off their names. + +## (internal) Refactoring and interface adjustments. ## Add --schema SCHEMA option to .dump ## Many changes and additions to .parameter subcommands: -### clear ?NAME? to allow selective zapping. (Was everything before.) +### clear ?NAME? + +Allowing selective zapping. (Was everything before.) + +### edit ?OPT? NAME + +Allow editing an existing or new entry. The OPT, if provided, may be -t or -e to select whether the resulting value is stored as text or evaluated as a SQL expression. A hidden option, --editor=\, may be used in place of having set environment variable DISPLAY before starting shell. This option is mentioned just when needed in an interactive session. + +### list/ls output options + +These are prettified with optional glob patterns. + +### load ?FILE? ?NAMES? -### edit ?OPT? NAME to allow editing an existing or new entry. The OPT, if provided, may be -t or -e to select whether the resulting value is stored as text or evaluated as a SQL expression. A hidden option, --editor=\, may be used in place of having set environment variable DISPLAY before starting shell. This option is mentioned just when needed in an interactive session. +Allow saved parameters to be loaded. With no arguments, a defaulted file in user's HOME directory is the source, and all of its parameters are loaded. With a FILE argument, named file is the source. With more arguments, selective loading from the file is done. -### list/ls output options, prettified with optional glob patterns. +### save ?FILE? ?NAMES? -### load ?FILE? ?NAMES? to allow saved parameters to be loaded. With no arguments, a defaulted file in user's HOME directory is the source, and all of its parameters are loaded. With a FILE argument, named file is the source. With more arguments, selective loading from the file is done. +This is parallel to load except for direction of data flow and intolerance of FILE being read-only. -### save ?FILE? ?NAMES? is parallel to load except for direction of data flow and intolerance of FILE being read-only. +### set ?TOPT? NAME VALUE -### set ?TOPT? NAME VALUE accepts an optional type option to specify storage of the given value as a particular type, bypassing the old, "evaluate as SQL expression" behavior (which can be problematic without two levels of quoting.) Without the type option, the old behavior occurs. Also, if multiple arguments are found where VALUE would be, they are space-joined to form the stored value. (This is convenient for script use.) +Accept an optional type option to specify storage of the given value as a particular type, bypassing the old, "evaluate as SQL expression" behavior (which can be problematic without two levels of quoting.) Without the type option, the old behavior occurs. Also, if multiple arguments are found where VALUE would be, they are space-joined to form the stored value. (This is convenient for script use.) -### unset ?NAMES? is much like "clear ?NAMES?", except that with no names it is a no-op rather than an error as with prior shell versions. +### unset ?NAMES? -## .shxopts command added to display or modify extension options. +This is much like "clear ?NAMES?", except that with no names it is a no-op rather than an error as with prior shell versions. -## .x NAMES command added to execute named parameters as if their content was fed to the input stream. +## .shxopts command + +This addition is to display or modify extension options. + +## .x NAMES command + +This will execute named parameters as if their content was fed to the input stream. ## Certain dot-commands become "undocumented". @@ -45,23 +67,37 @@ This means that, in addition to not appearing in the website docs, they do not a Undocumented dot commands are: .check, .selftest-*, .seeargs, .testcase, and .testctrl . -## .seeargs command added to show its arguments bounded by '|', for those who are unsure of the shell's quoting and expansion rules. +## .seeargs command + +An "undocumented" dot command to show arguments bounded by '|', for those who are unsure of the shell's quoting and expansion rules. + +## For .open command + +The --hexdb option without a FILE given can read in a hex DB from the current input stream, including from string sources. + +## (internal) Compile option, BOOLNAMES_ARE_BOOLEAN + +This adds "false" and "true" to the recognized binary switch values. -## For .open command, --hexdb option without a FILE given can read in a hex DB from the current input stream, including from string sources. +## (internal) Utility function, db_text() -## (internal) Compile option, BOOLNAMES_ARE_BOOLEAN, adds "false" and "true" to the recognized binary switch values. +This is added for reasons similar those for db_int(). -## (internal) Utility function, db_text(), added. It resembles db_int(). +## (internal) Preparation for variable expansion -## (internal) Preparation made for variable expansion within double-quoted command arguments. (This is not a visible or completed feature, so now "internal".) +This is for later addition of expansion within double-quoted command arguments. -## Dot-command parsing is optionally extended to permit arguments to span more than one line, or more arguments to be added in subsequent lines. This is not the default behavior because it breaks backward compatibility (for ill-formed input with mis-balanced quotes.) It is enabled with either an invocation command-line option or the dot-commad, ".shxopts +parsing". With extended parsing, unclosed arguments may contain literal newlines, and lines may be be spliced if backslash is the final character (other than newline) at the end of an input line. +## Dot-command parsing extension -## (internal) Input line processing (process_input()) rewritten to support collection and dispatch of multi-line input in a more regular manner. +This optional extension permits arguments to span more than one line, or more arguments to be added in subsequent lines. This is not the default behavior because it breaks backward compatibility (for ill-formed input with mis-balanced quotes.) It is enabled with either an invocation command-line option or the dot-commad, ".shxopts +parsing". With extended parsing, unclosed arguments may contain literal newlines, and lines may be be spliced if backslash is the final character (other than newline) at the end of an input line. -## (internal) process_input() is over-commented to aid initial write and review if desired. Its comment volume is slated for post-merge reduction. +## (internal) Rewrite of process_input() -## (semi-internal) An undocumented command-line option, -quiet, added to suppress start-up banner (which contains a version string) and prompts when input is "interactive". +It was rewritten to support collection and dispatch of multi-line input in a more regular manner. It is now over-commented to aid initial write and review if desired. Its comment volume is slated for post-merge reduction. + +## (semi-internal) An undocumented command-line option, -quiet + +This was added to suppress the start-up banner (which contains a version string) and prompts when input is "interactive". ## (internal) Tests added for above new/changed features. @@ -101,28 +137,54 @@ Simplifies scenarios where a user attaches a DB, or creates an attached DB, for The .parameter command becomes the focal point for managing all kinds of user-alterable parameters and variables. It is easy to remember: If some parameter(s) will be created, modified, reviewed, saved, loaded, or removed, .parameter is how it is done. -### clear or unset ?NAMES? are enhanced to conveniently remove just selected parameters, (rather than all of them as before), for pre-save cleanup, list de-clutter, or testing effect of unbound query parameters. +### clear or unset ?NAMES? + +Make it convenient to remove just selected parameters, (rather than all of them as before), for pre-save cleanup, list de-clutter, or testing effect of unbound query parameters. + +### edit ?OPT? NAME + +Allow convenient interactive creation or modification of parameter values, particularly ones that may have multiple lines or tax a user's perception when only a line-editor is available. The feature is only enabled for interactive sessions, as it makes little sense to begin an edit session in batch mode. Its hidden option, --editor=\, is for cases where a user has not set DISPLAY before starting the CLI, or needs to change it. It does not appear in help, but is mentioned when edit is invoked without DISPLAY being set. + +### load/save ?FILE? ?NAMES? + +This persistence facility is mainly for edited queries, DDL or DML that a user may wish to reuse across sessions. Or it may prove useful for commonly repeated sequences of dot commands. Or both. + +### list/ls output options + +These make it easier to see what is in the parameters table by using the short, "ls" form, which lists only names, or by specifying glob patterns to restrict output. With the added utility of parameters, there may be a lot more to see or avoid seeing. + +### set ?TOPT? NAME VALUE + +The new option, TOPT, can force the value's type or to bypass the effective eval trial for text. This makes it more deterministic for those who may not understand the detailed processing or quoting rules. Taking the VALUE to be the space-joined remaining arguments simplifies quoting in many cases. + +## Added .shxopts command + +By allow certain optional features, which potentially impair backward compatibility, to be enabled or disabled at runtime, users are given control over the trade between compatibility and the convenience of the new features. + +## The new dot command, .x NAMES + +This is a convenience for those who are often repeating some command, query, or set of commands and/or queries. Many people do not get their queries right on the first write. -### edit ?OPT? NAME is added to aid convenient interactive creation or modification of parameter values, particularly ones that may have multiple lines or tax a user's perception when only a line-editor is available. The feature is only enabled for interactive sessions, as it makes little sense to begin an edit session in batch mode. Its hidden option, --editor=\, is for cases where a user has not set DISPLAY before starting the CLI, or needs to change it. It does not appear in help, but is mentioned when edit is invoked without DISPLAY being set. +## Certain dot-commands become "undocumented" -### load/save ?FILE? ?NAMES? is a persistence facility mainly for edited queries, DDL or DML that a user may wish to reuse across sessions. Or it may prove useful for commonly repeated sequences of dot commands. Or both. +This is to reduce clutter seen by those who use the CLI to use SQLite rather than to test it. It may also reduce needless doc searches by the curious. -### list/ls output options make it easier to see what is in the parameters table by using the short, "ls" form, which lists only names, or by specifying glob patterns to restrict output. +## Compile option, BOOLNAMES_ARE_BOOLEAN -### set ?TOPT? NAME VALUE gained the option, TOPT, to force the value's type or to bypass the effective eval trial for text. Taking the VALUE to be the space-joined remaining arguments simplifies quoting in many cases. +This is a place-holder for until addition of "false" and "true" to the binary switch name set is rejected or accepted. The case for adding them is that they are a natural choice as boolean values and having "true" taken as "false" (as happens today) can be surprising. -## Added .shxopts command to allow certain optional features, which potentially impair backward compatibility, to be enabled or disabled at runtime. +## Extended dot-command parsing -## The new dot command, .x NAMES, is added to allow convenient execution of pre-written or edited SQL and command sequences. +This feature, (where arguments and/or dot commands may span line-ends), has several uses. One is for allowing ".param set \ \" to specify a multi-line value, useful mainly for script creation. (Otherwise, multi-line script, which may contain complex SQL in need of line-structure, can only be created by using ".parameter edit \".) Another is for .print commands, so that literal multi-line output may be more naturally specified. -## Certain dot-commands become "undocumented" to reduce clutter seen by those who use the CLI to use SQLite rather than to test it. +## process_input() rewrite -## Compile option, BOOLNAMES_ARE_BOOLEAN is a place-holder for until addition of "false" and "true" to the binary switch name set is rejected or accepted. The case for adding them is that they are a natural choice as boolean values and having "true" taken as "false" (as happens today) can be surprising. +This was needed to support extended dot-command parsing. The difficulty of gaining that support without a rewrite, together with anticipation of later adding a TCL input feature, (which would present similar issues), easily made the rewrite appear advantageous. The code was hard to follow before, but can now be easily adapted to incorporate TCL scripting when (or if) that is added. -## Extended dot-command parsing, (where arguments and/or dot commands may span line-ends), has several uses. One is for allowing ".param set \ \" to specify a multi-line value, useful mainly for script creation. (Otherwise, multi-line script, which may contain complex SQL in need of line-structure, can only be created by using ".parameter edit \".) Another is for .print commands, so that literal multi-line output may be more naturally specified. +## added command-line option, -quiet -## The process_input() rewrite was needed to support extended dot-command parsing. The difficulty of gaining that support without a rewrite, together with anticipation of later adding a TCL input feature, (which would present similar issues), easily made the rewrite appear advantageous. The code was hard to follow before, but can now be easily adapted to incorporate TCL scripting when (or if) that is added. +This facilitates testing of the ".parameter edit" feature. -## The added command-line option, -quiet, facilitates testing of the ".parameter edit" feature. +## mkshellc.tcl change to handle more typedef repetition than before -## The mkshellc.tcl change to handle more typedef repetition than before merely reduces the fragility of the feature. It was motivated by added use of a sometimes-redundant typedef which exposed the older fragility. +This merely reduces the fragility of the feature. It was motivated by added use of a sometimes-redundant typedef which exposed the older fragility. diff --git a/manifest b/manifest index f28e6680f1..8a0c661190 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Sync\sw/Trunk,\sfinish\sdoc/sh_tweak_changes.md -D 2022-03-09T22:16:38.326 +C Improve\sformatting\sof\schanges\sdoc\sfor\sthis\sbranch +D 2022-03-10T11:10:03.722 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724 @@ -41,7 +41,7 @@ F doc/F2FS.txt c1d4a0ae9711cfe0e1d8b019d154f1c29e0d3abfe820787ba1e9ed7691160fcd F doc/json-enhancements.md e356fc834781f1f1aa22ee300027a270b2c960122468499bf347bb123ce1ea4f F doc/lemon.html efc0cd2345d66905505d98f862e1c571512def0ceb5b016cb658fd4918eb76a3 F doc/pager-invariants.txt 27fed9a70ddad2088750c4a2b493b63853da2710 -F doc/sh_tweak_changes.md 5a9fbf65817433ddc4493cd328266a8918b70cd90bde7162c92eea59c61093d8 +F doc/sh_tweak_changes.md d7cc2d4f528696722bda07f15e82e68d4fcc4f4dff07cdd5274ee36abdf38aa1 F doc/trusted-schema.md 33625008620e879c7bcfbbfa079587612c434fa094d338b08242288d358c3e8a F doc/vdbesort-memory.md 4da2639c14cd24a31e0af694b1a8dd37eaf277aff3867e9a8cc14046bc49df56 F doc/vfs-shm.txt e101f27ea02a8387ce46a05be2b1a902a021d37a @@ -1946,8 +1946,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0 -P 5ddccc2f2885ae4068e492053dbb4e7215ce7dd052f782bffa0076b4585d175f 6f838305e2c848a43b210bd1b7b962fb9e3c41de34de778675e6578fcd99f397 -R d80dca76fe43cf772691a942a2518ea1 +P 5a1797c2250665d013e0a1818f90c52db1b6f67b2daff82c46c06c9d058080e7 +R 5c01fa176890fe506ddfbaf5b91b0bb9 U larrybr -Z 6f5df54da847b7514dd0b48c6ee05b25 +Z b98fb326f8f5ba3355de2a5d288c631c # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index 3a220123ce..064bf19bec 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -5a1797c2250665d013e0a1818f90c52db1b6f67b2daff82c46c06c9d058080e7 \ No newline at end of file +2129cfb8c5ff2bec9a9f61fd7bf3d63a7385a14ea0161798d1869fe2b87567e6 \ No newline at end of file