Metadata-Version: 2.1
Name: xontrib-term-integrations
Version: 0.2.3
Summary: Support shell integration of terminal programs iTerm2, Kitty...
Keywords: xontrib,xonsh
Author-Email: Noortheen Raja NJ <jnoortheen@gmail.com>
License: MIT
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Shells
Classifier: Topic :: System :: System Shells
Classifier: Topic :: Terminals
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Project-URL: Documentation, https://github.com/jnoortheen/xontrib-term-integrations/blob/master/README.md
Project-URL: Code, https://github.com/jnoortheen/xontrib-term-integrations
Project-URL: Issue tracker, https://github.com/jnoortheen/xontrib-term-integrations/issues
Project-URL: repository, https://github.com/jnoortheen/xontrib-term-integrations
Requires-Python: >=3.8
Requires-Dist: xonsh>=0.14.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Description-Content-Type: text/markdown

# Terminal Emulators integration

[Shell integration](https://iterm2.com/documentation-escape-codes.html) for Xonsh.

The following terminal emulators are supported

- [iTerm2](https://iterm2.com/documentation-shell-integration.html)
- [kitty](https://sw.kovidgoyal.net/kitty/shell-integration/)
- [WezTerm](https://wezfurlong.org/wezterm/shell-integration.html) with CWD; Input, Output, and Prompt zones; and User Vars for tracking additional shell state
- [Ghostty](https://ghostty.org/docs/features/shell-integration)

**Note**: If identifying current terminal fails, `iTerm2` hooks are loaded.

PRs welcome on improving the support to more terminal programs :)

## Installation

To install use pip:

```bash
xpip install xontrib-term-integrations
# or: xpip install -U git+https://github.com/jnoortheen/xontrib-term-integrations
```

## Usage

```bash
# this modifies the $PROMPT function. So load it after setting $PROMPT if you have a custom value
xontrib load term_integration
```

(WezTerm) Set user vars[^1] via the helper `set_user_var` function:

```xsh
# via a xonsh alias
set_wezterm_user_var 'my_term_user_var' 'value_of_my_term_user_var'

# or an explicit Python import
from xontrib_term_integrations.utils import set_user_var
set_user_var('my_term_user_var','value_of_my_term_user_var')
```

You can disable registering the alias with a `$XONTRIB_TERM_INTEGRATIONS_SKIP_ALIAS = True`

## Contributing

Please make sure that you

- Document the purpose of functions and classes.
- When adding a new feature, please mention it in the `README.md`. Use screenshots when applicable.
- [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) style should be used
  for commit messages as it is used to generate changelog.
- Please use [pre-commit](https://pre-commit.com/) to run qa checks. Configure it with

```sh
pre-commit install-hooks
```

- For new releases, create a GitHub release with new tag (e.g. `v0.x.x`) and it will automatically push the package to PyPI.

## Known issues

<details>
<summary><strong>WezTerm</strong></summary>

- (WezTerm) Multiline prompt is partially supported:
  - every continuation line is semantically marked by default:
    ```xsh
    if True:
    #↓ continuation prompt
    .....     echo 1
    #     ↑ input
    ```
    so you can select `    echo 1` as a `SemanticZone` with a mouse multiclick, but you can't select both lines as one zone (and would need to map some combo of commands to hack around it)
  - if you set `$MULTILINE_PROMPT_PRE=''`, `$MULTILINE_PROMPT_POS=''`, then continuation lines won't be marked, you'd be able to select all the lines as one `SemanticZone` (unles the _right_ prompt interferes), but that will also include `..` continuation markers (so you'd either need to disable them in Xonsh or add some extra WezTerm lua parsing hack to trim them)
    </br> (follow this [WezTerm discussion](https://github.com/wez/wezterm/discussions/3130) for updates)
- (WezTerm) Semantic _right_ prompt not separated from the next-line _left_ prompt ([issue](https://github.com/wez/wezterm/issues/3115))
- WezTerm is _not_ recognized in root shells due to [this issue](https://github.com/wez/wezterm/issues/3114)

</details>

<details>
<summary><strong>Ghostty</strong></summary>

- Implemented features:
  - [x] Do not confirm close for terminals where the cursor is at a prompt.
  - [x] New terminals start in the working directory of the previously focused terminal.
  - [ ] Complex prompts resize correctly by allowing the shell to redraw -- rather than reflow -- the prompt line.
  - [x] Triple-click while holding control (Linux) or command (macOS) to select the output of a command.
  - [ ] The cursor at the prompt is turned into a bar to represent more typical text editing.
  - [x] The jump_to_prompt keybinding can be used to scroll the terminal window forward and back through prompts.
    > :warning: Because of the implementation, jumping includes secondary newlines in multiline prompts.
  - [ ] Alt+click (option+click on macOS) moves the cursor to the click location while at a prompt.
  - [ ] sudo can be automatically wrapped to preserve Ghostty terminfo (disabled by default)
  - [ ] ssh can be automatically wrapped to either transmit the Ghostty terminfo or set the TERM environment variable to xterm-256color to maximize compatibility (disabled by default)

</details>

[^1]: Variables associated with a given pane rather than a process. [WezTerm](https://wezfurlong.org/wezterm/shell-integration.html#user-vars), [iTerm2](https://iterm2.com/documentation-escape-codes.html)
