plsqlwks 0.2.2__tar.gz → 0.2.4__tar.gz

{plsqlwks-0.2.2 → plsqlwks-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plsqlwks
-Version: 0.2.2
+Version: 0.2.4
 Summary: An ncurses SQL and PL/SQL workspace for Oracle databases.
 Author: unu2000
 License-Expression: LicenseRef-plsqlwks-Donationware
@@ -19,6 +19,8 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: license.txt
 Requires-Dist: oracledb>=2.0
+Provides-Extra: er-diagram
+Requires-Dist: CairoSVG>=2.9.1; extra == "er-diagram"
 Provides-Extra: csv2oratab
 Requires-Dist: cryptography>=42; extra == "csv2oratab"
 Provides-Extra: xlsx
@@ -533,7 +535,11 @@ After a successful quit, plsqlwks records the open file-backed tabs, active tab,
 Worksheet and configuration saves replace their destination atomically while
 preserving an existing file's POSIX permission bits. A
 file-backed worksheet also detects when its file was changed or deleted outside
-plsqlwks and asks whether to overwrite it, save under another name, or cancel.
+plsqlwks and asks whether to overwrite it, reload the disk version, save under
+another name, or cancel. Reload is available while the file exists, including
+when a change is detected just before saving. It replaces the editor text
+without writing to disk; Undo can restore local edits. If reading fails, the
+local buffer stays intact.
 Undo and redo update the unsaved-change marker by comparing the current content
 with the last successful save.
 
@@ -613,9 +619,11 @@ Use left Alt for application shortcuts; AltGr remains available for characters
 on international keyboards. Shortcut digits and symbols refer to the character
 on the active Windows layout: for example, Czech top-row digits need Shift,
 so Alt-1 is typed with Alt-Shift-1. Use the layout's `+` or `=` character for
-autocomplete refresh. `Ctrl-C`, `Ctrl-X`, and `Ctrl-V` operate on the
-application/host clipboard with the existing internal fallback. SSH does not
-make that the Windows clipboard. Use PuTTY's native paste (`Shift-Insert` or
+autocomplete refresh. Ctrl-C/Ctrl-P copy/paste internally, Ctrl-Shift-C/Ctrl-Shift-P
+use the Windows system clipboard, and Alt-Shift-C/Alt-Shift-P use the Linux
+clipboard. Ctrl-V and Ctrl-Shift-V retain their configured paste sources;
+Ctrl-Shift-V defaults to internal paste. SSH does not expose the Windows clipboard to the host. Use
+PuTTY's native paste (`Shift-Insert` or
 right-click) to insert Windows clipboard text as bracketed paste, and PuTTY
 mouse selection to copy to Windows. Leave plsqlwks' Ctrl-letter shortcuts
 available to the server when customizing PuTTY clipboard settings.
@@ -680,6 +688,104 @@ Run `tools\windows_keys.cmd -SelfTest` to check the helper without enabling it.
 The original `powershell.exe -NoProfile -File .\tools\putty_keys.ps1` command
 also works from Command Prompt and continues to support PuTTY.
 
+### Windows Terminal and WSL clipboard shortcuts
+
+PLSQLWKS provides three clipboard methods: System (Windows), WSL/Linux
+(Wayland/X11), and Internal. WSLg can bridge Windows and Linux contents, so the
+two external methods may access shared contents.
+
+| Clipboard | Copy | Paste |
+| --- | --- | --- |
+| System (Windows) | `Ctrl-Shift-C` | `Ctrl-Shift-P` |
+| WSL/Linux | `Alt-Shift-C` | `Alt-Shift-P` |
+| Internal | `Ctrl-C` | `Ctrl-P` |
+
+Each fixed shortcut uses only its assigned target. Copying externally leaves
+the internal clipboard unchanged. `Ctrl-C` interrupts a running database
+operation first; otherwise it copies internally. `Ctrl-Alt-C` still commits or
+applies the active insert draft, and `Ctrl-Alt-R` rolls back.
+The copy shortcuts work for editor selections, result cells/ranges,
+DBMS_OUTPUT selections and schema-browser object names. Paste works in the
+worksheet, paste-enabled prompts and editable cell text dialogs.
+
+Open **Alt-O → Preferences → Clipboard** to inspect the fixed shortcuts and
+backend capabilities, configure legacy copy/cut destinations and choose the
+sources for `Ctrl-V` and `Ctrl-Shift-V`. Save persists settings in your workspace
+`config.ini`; Cancel discards changes. The new C/P shortcuts ignore these
+settings. `Ctrl-X` and legacy copy commands retain configured destinations and
+an internal copy; cut remains one immediate Undo edit. New workspaces without
+Windows tools default legacy copy/paste to Linux.
+
+```ini
+[clipboard]
+copy_to_windows = yes
+copy_to_linux = no
+ctrl_v_source = windows
+ctrl_shift_v_source = internal
+```
+
+Paste sources are `windows`, `internal`, or `linux`. Windows paste reads Windows
+exclusively: failure or empty contents causes no insertion and explicit
+feedback. Internal paste performs no OS access and cancels a pending paste for
+that target. The fixed copy shortcuts update only their selected clipboard;
+legacy copy/cut updates internal text immediately and then attempts configured
+external destinations in a background worker. Windows copy tries PowerShell,
+then `clip.exe` on failure, and verifies contents by readback when a reader is
+available. Copy-only Windows access is labelled unverified. Each Linux provider
+is attempted when Linux copying is enabled. A Linux success does not conceal a
+Windows failure.
+
+If Windows Terminal consumes a shortcut, forward it to PLSQLWKS.
+To configure explicit forwarding, open **Settings → Open JSON file** and add these
+entries to `actions`, keeping the other actions:
+
+```json
+{ "command": { "action": "sendInput", "input": "\u0003" }, "id": "User.PlsqlwksInternalCopy" },
+{ "command": { "action": "sendInput", "input": "\u0010" }, "id": "User.PlsqlwksInternalPaste" },
+{ "command": { "action": "sendInput", "input": "\u001b[99;6u" }, "id": "User.PlsqlwksSystemCopy" },
+{ "command": { "action": "sendInput", "input": "\u001b[112;6u" }, "id": "User.PlsqlwksSystemPaste" },
+{ "command": { "action": "sendInput", "input": "\u001b[99;4u" }, "id": "User.PlsqlwksWslCopy" },
+{ "command": { "action": "sendInput", "input": "\u001b[112;4u" }, "id": "User.PlsqlwksWslPaste" },
+{ "command": { "action": "sendInput", "input": "\u0016" }, "id": "User.PlsqlwksPaste" },
+{ "command": { "action": "sendInput", "input": "\u001b[118;6u" }, "id": "User.PlsqlwksAlternatePaste" }
+```
+
+Replace the existing copy/paste entries in `keybindings` with
+the entries below, keeping the other keybindings:
+
+```json
+{ "id": "User.PlsqlwksInternalCopy", "keys": "ctrl+c" },
+{ "id": "User.PlsqlwksInternalPaste", "keys": "ctrl+p" },
+{ "id": "User.PlsqlwksSystemCopy", "keys": "ctrl+shift+c" },
+{ "id": "User.PlsqlwksSystemPaste", "keys": "ctrl+shift+p" },
+{ "id": "User.PlsqlwksWslCopy", "keys": "alt+shift+c" },
+{ "id": "User.PlsqlwksWslPaste", "keys": "alt+shift+p" },
+{ "id": "User.PlsqlwksPaste", "keys": "ctrl+v" },
+{ "id": "User.PlsqlwksAlternatePaste", "keys": "ctrl+shift+v" }
+```
+
+This setting applies to every Windows Terminal profile and tab. Restart
+plsqlwks after upgrading and reopen Windows Terminal if it retains old bindings.
+The command menu offers equivalents when a terminal intercepts the shortcuts.
+The optional `tools/putty_keys.ps1` helper also forwards these shortcuts when
+enabled for the active Windows terminal window.
+
+Keyboard navigation, resizing and dialogs remain available while clipboard
+commands run. Windows paste waits behind pending external copies. If you change
+the paste target's text, cursor, selection or active tab before it finishes, the
+pending paste is cancelled; repeated external paste requests for that target
+are ignored. Requests retain the settings in effect when submitted.
+
+For native Windows Terminal paste, wait until application copy reports that the
+Windows clipboard has been updated. Native paste reads the Windows clipboard
+independently and receives no internal fallback. Its bracketed paste payload is
+inserted directly without a second clipboard lookup.
+
+Windows Terminal's **Copy on select** setting can overwrite the clipboard when
+you select terminal text with the mouse. Turn it off if you want only explicit
+copy commands to change the Windows clipboard.
+See Microsoft's [send input action](https://learn.microsoft.com/en-us/windows/terminal/customize-settings/actions#send-input).
+
 ## Keys
 
 ### Global
@@ -738,12 +844,16 @@ also works from Command Prompt and continues to support PuTTY.
 | `Ctrl-F` | Open literal Find/Replace with the `Find next` action |
 | `Alt-O` -> **Editor** -> **Replace text** | Open Find/Replace at the replacement field |
 | `Ctrl-G` | Go to line |
-| `Ctrl-N` / `Ctrl-P` | Move to the next / previous search occurrence |
+| `Ctrl-N` | Move to the next search occurrence |
+| `Alt-O → Editor → Previous search match` | Move to the previous search occurrence |
 | `Ctrl-U` | Uppercase selected SQL code |
 | `Ctrl-L` | Lowercase selected SQL code |
-| `Ctrl-C` | Copy selected text |
+| `Ctrl-C` / `Ctrl-P` | Copy/paste internally |
+| `Ctrl-Shift-C` / `Ctrl-Shift-P` | Copy/paste the System (Windows) clipboard |
+| `Alt-Shift-C` / `Alt-Shift-P` | Copy/paste the WSL/Linux clipboard |
 | `Ctrl-X` | Cut selected text |
 | `Ctrl-V` | Paste clipboard text, expanding each tab to two spaces |
+| `Ctrl-Shift-V` | Paste the alternate source (internal by default) |
 | Terminal paste | Paste text as one edit, expanding each tab to two spaces |
 | `Ctrl-Z` / `Ctrl-Y` | Undo / redo |
 | `Ctrl+=` | Reconnect |
@@ -779,12 +889,13 @@ The dialog provides `Find next`, `Replace`, `Replace all`, and `Cancel` actions.
 and lowercase letters. `Replace` changes the selected matching occurrence, or
 the next match from the cursor, and then selects the following match. `Replace
 all` changes every match in the current buffer. Either replacement operation is
-recorded as one undoable edit. `Ctrl-N` and `Ctrl-P` repeat the last search with
-its case setting, forward or backward with wraparound.
+recorded as one undoable edit. `Ctrl-N` repeats the last search forward;
+**Alt-O → Editor → Previous search match** repeats it backward. Both retain the
+case setting and wrap around.
 
 Editor paste expands every tab character to two spaces and keeps multiline
-text in one undoable edit. This applies to `Ctrl-V` from either the system or
-internal clipboard and to native terminal paste while the editor is focused;
+text in one undoable edit. This applies to all fixed and configured paste shortcuts and
+to native terminal paste while the editor is focused;
 clipboard contents themselves are not changed. Native paste requires a
 terminal that supports the standard bracketed-paste protocol, with `Ctrl-V`
 remaining available as the fallback.
@@ -830,7 +941,9 @@ Read-only mode is a client-side guardrail that rejects statements which the SQL
 | `Home` / `End` | Move to the first/last result-grid column |
 | `Ctrl-Home` / `Ctrl-End` | Move to the first/last result-grid row |
 | `F8` | Toggle result grid / row-detail output |
-| `Ctrl-C` | Copy one result cell immediately, or choose header handling for a rectangular selection |
+| `Ctrl-C` | Copy a cell/range internally; ranges offer header handling |
+| `Ctrl-Shift-C` | Copy the same cell/range to System (Windows) |
+| `Alt-Shift-C` | Copy the same cell/range to WSL/Linux |
 | `F10` | View or edit a mapped text cell in a ROWID-backed result |
 | `Enter` | Edit the selected ROWID-backed result cell when available |
 | `INS` | Prepare a draft insert row for ROWID-backed results |
@@ -919,8 +1032,9 @@ move within a displayed line; Ctrl+Home/End move to the output boundaries.
 
 Copying preserves the stored text, whitespace, blank lines, and statement
 headings, without screen wrapping or padding. The existing system clipboard
-providers are used when available, with the internal clipboard as a fallback
-(including remote PuTTY sessions). Ctrl+C still cancels a running operation
+backends are reused: Ctrl+C copies internally, Ctrl+Shift+C copies to Windows,
+and Alt+Shift+C copies to WSL/Linux. Fixed external shortcuts do not fall back
+to another clipboard. Ctrl+C still cancels a running operation
 before performing a copy. Selection belongs to its file tab, survives appended
 output and resizing, and resets when execution replaces the output.
 
@@ -1098,9 +1212,39 @@ validate this opt-in mode with the applications in use.
 
 ### Schema Browser
 
-The `F9` schema browser groups tables, views, procedures, functions, packages, triggers, sequences, indexes, and private synonyms from the current schema. Type while the browser is focused to filter object names with a case-insensitive substring match; groups without matches are hidden and matching groups expand automatically without changing their saved expansion state. Exact quoted and mixed-case names are preserved when columns or definitions are loaded, with Oracle-safe quoting applied to metadata requests.
-
-Press `Enter` on a table or view to choose `Insert SELECT` (the default), `Load DDL`, or `Copy object name`. `Insert SELECT` adds a `select *` statement for the SQL-safe, unqualified object name to the current buffer and focuses the editor; it does not execute the query. `Copy object name` places that SQL-ready, unqualified identifier on the clipboard. For other object types, `Enter` offers `Load DDL` (the default) and `Copy object name`.
+The `F9` schema browser groups tables, views, procedures, functions, package specifications, package bodies, triggers, sequences, indexes, and private synonyms from the current schema. Type while the browser is focused to filter object names with a case-insensitive substring match; groups without matches are hidden and matching groups expand automatically without changing their saved expansion state. Exact quoted and mixed-case names are preserved when columns, routines or definitions are loaded, with Oracle-safe quoting applied to metadata requests.
+
+Press `Enter` on a table or view to choose `Insert SELECT` (the default), `Load DDL`, or `Copy object name`. `Insert SELECT` adds a `select *` statement for the SQL-safe, unqualified object name to the current buffer and focuses the editor; it does not execute the query. `Copy object name` places that SQL-ready, unqualified identifier on the clipboard. For standalone procedures, functions and other object types, `Enter` offers `Load DDL` (the default) and `Copy object name`.
+
+Package specifications and bodies show their own compilation status immediately
+before the package name: `C` means compiled, `I` means invalid compilation and
+`?` means status unavailable. A compiled specification can have an invalid body.
+Press `Enter` on either part to load the specification, body or both, or copy
+the package name. The selected part is the default; unavailable parts are
+omitted. Each loading mode has its own tab, and loading both puts the
+specification before the body in one SQL buffer.
+
+Press `Space` on either package part to expand its public procedures and
+functions, including while filtering. The browser loads signatures in the
+background and shares the cache between the two package sections. `P` marks a
+procedure and `F` a function; overloads have separate signature rows. Private
+body routines are excluded because a worksheet cannot call them.
+Press `Enter` on a routine to insert a default PL/SQL call block at the current
+cursor, replacing selected text as one undoable edit, and focus the editor.
+The block declares typed variables for every parameter, including parameters
+with defaults and OUT/IN OUT parameters, and a result variable for functions.
+Edit the input values before running it. Insertion does not execute or compile
+the call. Unsupported or incomplete signatures report a reason and leave the
+buffer unchanged.
+
+Press `Space` on a table or view to expand or collapse its column subtree,
+including while filtering. Column names appear in database order and are loaded
+in the background on first expansion, then cached. Columns are informational
+leaf rows; object actions apply to their parent table or view. `Ctrl-F` opens an
+object-name filter prompt that accepts spaces. Filtering matches object names
+and shows all children beneath expanded matching objects. `Ctrl-R` refreshes
+objects and package statuses, clears cached columns and routines, and collapses
+object branches, retaining the filter and group expansion state.
 
 | Key | Action |
 | --- | --- |
@@ -1109,9 +1253,10 @@ Press `Enter` on a table or view to choose `Insert SELECT` (the default), `Load
 | `Esc` | Clear a nonempty filter, or return to the editor when the filter is empty |
 | `Up` / `Down` | Move through browser entries |
 | `PageUp` / `PageDown` | Move through browser entries by page |
-| `Enter` | Expand a group or choose an action for an object |
-| `Space` | Expand/collapse a group when the filter is empty, or add a space to the active filter |
-| `Ctrl-R` | Refresh database objects |
+| `Enter` | Expand a group, choose an object action, or insert a package routine call |
+| `Space` | Expand/collapse table/view columns or package routines; on groups, expand/collapse with an empty filter or add a space to an active filter |
+| `Ctrl-F` | Edit the object-name filter, including spaces |
+| `Ctrl-R` | Refresh database objects/statuses and clear column/routine subtrees and caches |
 
 ### Cell Viewer
 
@@ -1123,7 +1268,7 @@ Press `Enter` on a table or view to choose `Insert SELECT` (the default), `Load
 | `PageUp` / `PageDown` | Scroll cell text by page |
 | `Home` / `End` | Move to the first/last cell-viewer line |
 | `Ctrl-S` (editor) | Save the multiline edit |
-| `Ctrl-V` / terminal paste (editor) | Paste exact clipboard text as one undoable edit |
+| `Ctrl-P` / `Ctrl-Shift-P` / `Alt-Shift-P` / configured V keys / terminal paste (editor) | Paste exact clipboard text as one undoable edit |
 | `Enter` (editor) | Insert a newline |
 | `F10` / `Esc` / `Ctrl-Q` (editor) | Cancel the multiline edit |
 
@@ -1132,7 +1277,7 @@ Press `Enter` on a table or view to choose `Insert SELECT` (the default), `Load
 | Key | Action |
 | --- | --- |
 | Printable text | Type into prompts or filter picker options |
-| `Ctrl-V` / terminal paste | Paste single-line text; tabs are preserved and multiline text is rejected |
+| `Ctrl-V` / `Ctrl-Shift-V` / terminal paste | Paste single-line text; tabs are preserved and multiline text is rejected |
 | `Backspace` | Delete before the prompt cursor or picker filter |
 | `Enter` | Accept the prompt or selected picker item |
 | `Esc` / `Ctrl-Q` | Cancel the prompt or picker |
@@ -1190,12 +1335,44 @@ for the exact manifest, source layout, validation, replacement, and trust rules.
 
 ### Table DDL Export
 
+### Schema Compare
+
+Install `plugins/packages/schema-compare-0.1.0.plwgn` and restart the updated
+host. **Alt-O -> Database -> Compare schema objects** chooses two schemas on
+the current connection and compares visible object names/types and logical
+definitions. Browse changed, one-sided, equal and unavailable objects; filter
+by name/type/status, open unified differences with Enter, and cycle original
+definitions with Tab. **Ctrl-E** exports all or filtered differences to CSV,
+HTML or XLSX, including summaries, line numbers and visibility notes. CSV/HTML
+need no extra; XLSX uses `plsqlwks[xlsx]`. The comparison preserves transactions,
+sequence state and the original editor/results. See the
+[catalog guide](doc/PLUGIN_CATALOG.md#schema-compare) for rules and limits.
+
+### E-R Diagram
+
+Install `plugins/packages/er-diagram-0.1.3.plwgn` with `plsqlwks plugin install`
+and restart the updated host. **Alt-O -> Database -> Export E-R Diagram (SVG/PNG/PDF)**
+opens a **Bright / Dark** theme picker followed by an **SVG / PNG / PDF** format
+picker. Use arrow keys and Enter; defaults are Bright and SVG. Then filter and
+check current-schema tables and views and export their columns, keys and
+foreign-key relationships. Connectors show numbered foreign-key names matching
+the detailed relationship notes. Relative destinations use the results directory.
+SVG uses the standard library; PNG/PDF require the optional `er-diagram` extra
+and the Cairo library. See the catalog for installation instructions.
+See the [catalog guide](doc/PLUGIN_CATALOG.md#e-r-diagram) for controls and limits.
+
+### Table DDL Export
+
 Install `plugins/packages/table-ddl-export-0.1.1.plwgn` with
 `plsqlwks plugin install` and restart. **Alt-O -> Database -> Export table DDL**
 lets you choose a schema, filter table names as you type, select tables, and
-optionally remap them to another schema. It automatically includes related
+optionally remap them to another schema and prefix tables, indexes, constraints
+and triggers while updating static table references. It automatically includes related
 sequences and directly referencing packages, functions, procedures, and views, and follows
-required source-schema tables and views recursively. Definitions, constraints, indexes,
+required source-schema tables, views, SQL types and program units recursively.
+Unreadable type or program definitions become named destination prerequisites.
+Types retain their names; prefixed copies in the source schema reuse existing types.
+Definitions, constraints, indexes,
 foreign keys and triggers are ordered by creation dependencies in a new
 unsaved SQL tab for review. Generation activates that tab and focuses its editor.
 See the [selection keys and remapping details](doc/PLUGIN_CATALOG.md#table-ddl-export).