diff --git a/customization/editor-settings.mdx b/customization/editor-settings.mdx index 2b902f2..7417bec 100644 --- a/customization/editor-settings.mdx +++ b/customization/editor-settings.mdx @@ -52,14 +52,22 @@ Autocomplete is always on; see [Autocomplete](/features/autocomplete). Editor sh **Query > Format Query** (`Cmd+Shift+L`) follows these rules. The preview at the end of the section formats a sample statement with them, in the editor theme. The defaults produce the layout shown under [Formatting](/features/sql-editor#formatting). + + Formatter section of Settings Editor with its pickers above a preview of a formatted SELECT statement + Formatter section of Settings Editor with its pickers above a preview of a formatted SELECT statement + + | Setting | Default | Notes | |---------|---------|-------| | Indent with | Spaces | Tabs indent each level with one tab, then line items up with spaces | | Indent width | 2 spaces | 2, 4, 8, or the editor's **Tab width** | | Keyword case | Same as editor | `UPPERCASE`, `lowercase`, or **As written**. **Same as editor** writes `lowercase` when **Keyword case** under Editing prefers lowercase, otherwise `UPPERCASE` | | Function case | As written | Applies to a call, `count(*)`, never to a column that shares a function's name. ClickHouse keeps the case you typed, since it matches function names by exact case | +| Data type case | As written | Applies to type names such as `date` in `CAST(x AS date)` and in column definitions. ClickHouse keeps the case you typed, since it matches type names by exact case | | Commas | At the end of the line | **At the start of the line** puts `, ` before each item of a SELECT list, SET list and CREATE TABLE column list | +| AND and OR | At the start of the line | **At the end of the line** ends each broken line of a WHERE or HAVING condition with its `AND` or `OR` | | Line width | One item per line | At 80, 100 or 120 characters, a SELECT list, SET list or WHERE condition that fits stays on one line | +| Clause items | Beside the keyword | **Below the keyword** starts a broken SELECT list, SET list, WITH list, or WHERE or HAVING condition on the line under its keyword, one level in. A single item stays beside its keyword | | Join condition | On its own line | **On the JOIN line** writes `LEFT JOIN orders o ON u.id = o.user_id` | | Align column aliases | Off | Lines up the `AS` of each SELECT item that sits on one line | @@ -71,27 +79,46 @@ Click **Export…** to save the rules as `sql-formatter.json`. The file holds th To apply the rules to a [linked SQL folder](/features/favorites#linked-sql-folders) instead, save the file in that folder as `.sql-formatter.json`. A file opened from the folder then formats with it rather than with Settings. The nearest `.sql-formatter.json` wins, from the file's own folder up to the linked folder; nothing above the linked folder is read. A rules file that cannot be read stops Format Query with an error naming it. +The npm `sql-formatter` package reads the same file, so one `.sql-formatter.json` drives both tools. + ```json { "alignAliases" : false, - "commaPosition" : "trailing", + "clauseItems" : "sameLine", + "commaPlacement" : "trailing", + "dataTypeCase" : "preserve", "functionCase" : "preserve", - "indentStyle" : "spaces", - "indentWidth" : 2, "joinCondition" : "newLine", "keywordCase" : "upper", - "lineWidth" : 0 + "lineWidth" : 0, + "logicalOperatorNewline" : "before", + "tabWidth" : 2, + "useTabs" : false } ``` -| Key | Values | -|-----|--------| -| `indentStyle` | `spaces`, `tabs` | -| `indentWidth` | 1 to 16 | -| `keywordCase`, `functionCase` | `upper`, `lower`, `preserve` | -| `commaPosition` | `trailing`, `leading` | -| `lineWidth` | 0 to 1000. 0 puts each item on its own line | -| `joinCondition` | `newLine`, `sameLine` | -| `alignAliases` | `true`, `false` | - -A key the file leaves out takes the default shown in the example, not your Settings value. A key TablePro does not know is ignored, and a value it cannot read is an error. +| Key | Values | `sql-formatter` reads it | +|-----|--------|--------------------------| +| `useTabs` | `true`, `false` | Yes | +| `tabWidth` | 1 to 16 | Yes | +| `keywordCase`, `functionCase`, `dataTypeCase` | `upper`, `lower`, `preserve` | Yes | +| `logicalOperatorNewline` | `before`, `after` | Yes | +| `commaPlacement` | `trailing`, `leading` | No | +| `lineWidth` | 0 to 1000. 0 puts each item on its own line | No | +| `joinCondition` | `newLine`, `sameLine` | No | +| `clauseItems` | `sameLine`, `newLine` | No | +| `alignAliases` | `true`, `false` | No | + +A key the file leaves out takes the default shown in the example, not your Settings value. For `keywordCase` that is `upper`, where `sql-formatter` keeps the case as written. A key only `sql-formatter` has, such as `language` or `expressionWidth`, is ignored. `indentStyle` takes `sql-formatter`'s values, `standard`, `tabularLeft` and `tabularRight`, and changes nothing here. Any value TablePro cannot read is an error that names its key. + +### A rules file from TablePro 0.83 + +A file exported by 0.83 uses older key names. Format Query and **Import…** refuse it with "The value of “indentStyle” is not valid." Export it again from Settings, or rename the keys: + +| 0.83 key | Key now | +|----------|---------| +| `indentStyle: "spaces"`, `indentStyle: "tabs"` | `useTabs: false`, `useTabs: true` | +| `indentWidth` | `tabWidth` | +| `commaPosition` | `commaPlacement` | + +The other keys keep their names. diff --git a/development/plugin-development.mdx b/development/plugin-development.mdx index 2ddb5b4..d55b978 100644 --- a/development/plugin-development.mdx +++ b/development/plugin-development.mdx @@ -13,7 +13,7 @@ A plugin is a macOS loadable bundle target with `WRAPPER_EXTENSION = tableplugin | Key | Type | Required | Purpose | |-----|------|----------|---------| -| `TableProPluginKitVersion` | integer | Yes | The PluginKit ABI the plugin was built against. Current value: 40 | +| `TableProPluginKitVersion` | integer | Yes | The PluginKit ABI the plugin was built against. Current value: 41 | | `TableProProvidesDatabaseTypeIds` | array of strings | Recommended | Database type IDs the plugin serves, which is what makes lazy loading possible | | `CFBundleShortVersionString` | string | Yes | Plugin version shown in **Settings > Plugins** | | `CFBundleVersion` | string | Yes | Build number. Of two copies of a plugin the higher build loads, and a registry update needs a higher build | diff --git a/features/sql-editor.mdx b/features/sql-editor.mdx index 6c1a8c4..7517ff3 100644 --- a/features/sql-editor.mdx +++ b/features/sql-editor.mdx @@ -190,7 +190,9 @@ The editor also carries multiple cursors, for editing several places at once. Press `Cmd+Shift+L` to format the statement at the cursor. The toolbar's format button and **Query > Format Query** do the same, and the shortcut is rebindable in **Settings > Keyboard**. -The formatter breaks a line per clause and keeps your comments, string literals, cursor position and dialect identifier quoting (MySQL backticks, PostgreSQL double quotes). Indentation, keyword and function case, comma position, line width, the join condition and alias alignment are set in **Settings > Editor > Formatter**; see [Formatter](/customization/editor-settings#formatter). A `.sql-formatter.json` in a [linked SQL folder](/features/favorites#linked-sql-folders) sets them for the files in that folder. JOINs, subqueries, CASE expressions, recursive CTEs, window functions and set operations are all handled. Procedural blocks pass through with minimal changes: PL/pgSQL `DO`, stored procedures, T-SQL `BEGIN`/`END`. +The formatter breaks a line per clause and keeps your comments, string literals, cursor position and each engine's quoted names: MySQL backticks, PostgreSQL double quotes, SQL Server brackets. A dollar-quoted body, such as a PL/pgSQL function or `DO` block, stays exactly as written. So does a line the client reads rather than the server: `GO` in a SQL Server script, `DELIMITER` in a MySQL one, a lone `/` in an Oracle one. A keyword or type name used as a column name, such as `date` in `SELECT date FROM events`, keeps the case you typed. + +Indentation, case, and where lines break are set in **Settings > Editor > Formatter**; see [Formatter](/customization/editor-settings#formatter). A `.sql-formatter.json` in a [linked SQL folder](/features/favorites#linked-sql-folders) sets them for the files in that folder. JOINs, subqueries, CASE expressions, recursive CTEs, window functions and set operations are all handled. Stored procedures and T-SQL `BEGIN`/`END` blocks pass through with minimal changes. A query larger than 10.5 MB is not formatted: an error says so, and the text stays as it was. **Before**: ```sql diff --git a/features/vim-mode.mdx b/features/vim-mode.mdx index d39ad0a..bf7213e 100644 --- a/features/vim-mode.mdx +++ b/features/vim-mode.mdx @@ -105,7 +105,7 @@ Counts work: `3w` moves three words, `5j` moves five lines down. `2d3w` deletes six words. `3yy` yanks three lines. `5>>` indents five lines. -Yank, delete, and change all write to the system clipboard. +Yank, delete, and change all write to the system clipboard, except through the black-hole register `"_`. ## Text objects @@ -137,7 +137,7 @@ In visual mode, `p` and `P` replace the selection with the register. ## Registers -Prefix with `"{a-z}` to pick a register. +Prefix a command with `"` and the register's name to pick one. | Register | Holds | |----------|-------| @@ -146,8 +146,9 @@ Prefix with `"{a-z}` to pick a register. | `"A` … `"Z` | Same, append | | `"0` | Last yank only | | `"1` … `"9` | Delete ring, rotates on each delete | +| `"_` | Nothing. A yank or delete through it leaves every other register and the clipboard as they were | -`"ayy` stores a line in `a`. `"ap` pastes it back later. +`"ayy` stores a line in `a`. `"ap` pastes it back later. `"_dd` deletes a line and keeps what you yanked last ready for `p`. ## Marks @@ -248,6 +249,21 @@ Indent and outdent work in normal mode only (`>>`, `<<`, `>{m}`, `<{m}`). `Esc` or `Ctrl+[` goes back to normal mode. Apart from the insert-mode [control keys](#control-keys), what you type goes to the editor as usual. +## Switch tabs + +| Keys | Goes to | +|------|---------| +| `gt` | Next tab, wrapping from the last to the first | +| `gT` | Previous tab, wrapping from the first to the last | +| `{N}gt` | Tab N | +| `{N}gT` | N tabs back | +| `:tabn[ext]` | Next tab | +| `:tabn[ext] {N}` | Tab N | +| `:tabn[ext] +{N}` `:tabn[ext] -{N}` | N tabs forward, N tabs back | +| `:tabp[revious] [N]` `:tabN[ext] [N]` | Previous tab, or N tabs back | + +The part in brackets is optional, so `:tabn`, `:tabne` and `:tabnext` are one command. Tabs are counted along the strip, the same tabs `Cmd+1` through `Cmd+9` count, and a number past the last one selects the last tab. `gt` and `gT` work in normal mode only. + ## Command line | Command | Action | @@ -255,6 +271,6 @@ Indent and outdent work in normal mode only (`>>`, `<<`, `>{m}`, `<{m}`). | `:w` | Run the current query | | `:q` | Close the tab | -`/` and `?` are search. Every other `:` command is parsed and ignored, `:wq`, `:x` and `:set` among them. `:10` does not jump to line 10 either; use `10G` or `10gg`. +`/` and `?` are search, and `:tabnext`, `:tabprevious` and `:tabNext` [switch tabs](#switch-tabs). Every other `:` command is parsed and ignored, `:wq`, `:x` and `:set` among them. `:10` does not jump to line 10 either; use `10G` or `10gg`. `Delete` and `Ctrl+H` erase the last character of the command. The arrow keys and the other `Ctrl` letters do nothing while you type one. diff --git a/images/settings-editor-formatter-dark.png b/images/settings-editor-formatter-dark.png new file mode 100644 index 0000000..8a36d5e Binary files /dev/null and b/images/settings-editor-formatter-dark.png differ diff --git a/images/settings-editor-formatter.png b/images/settings-editor-formatter.png new file mode 100644 index 0000000..5d4bdb5 Binary files /dev/null and b/images/settings-editor-formatter.png differ