Jasima/godot-xterm
1
0
Fork 0
mirror of https://github.com/lihop/godot-xterm.git synced 2025-05-23 03:05:32 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs(rtd): move documentation to read the docs

Browse source
This commit is contained in:
Leroy Hopson 2024-03-29 19:07:43 +13:00
parent 4fec353509
commit 5ae8d6a982
No known key found for this signature in database
GPG key ID: D2747312A6DB51AA
45 changed files with 609 additions and 772 deletions
Download patch file Download diff file Expand all files Collapse all files

214
docs/api/pty.md
View file

@ -1,64 +1,64 @@
---
layout: default
title: PTY
parent: API
nav_order: 1
permalink: /api/pty
---
# PTY
**Inherits:** [Node] < [Object]
**Inherits:** {{Node}} < {{Object}}
_Linux and macOS only._
Node for forking processes (e.g. bash, nodejs, python) with pseudoterminal file descriptors.
Can be used with the [Terminal] node to get an actual shell.
Can be used with the {{Terminal}} node to get an actual shell.
:::{note}
Not currently supported on Windows, but it could be in the future using [ConPTY](https://docs.microsoft.com/en-us/windows/console) or [WinPTY](https://github.com/rprichard/winpty).
See issue [\#25](https://github.com/lihop/godot-xterm/issues/25).
:::
## Overview
![PTY Diagram](../media/pty_diagram.png)
![PTY Diagram](../_static/images/diagram_pty.png)
<sub>"PTY Diagram" is a derivative of [Termios-script-diagram.svg](https://commons.wikimedia.org/wiki/File:Termios-script-diagram.svg) by [Krishnavedala](https://en.wikipedia.org/wiki/User:Krishnavedala?rdfrom=commons:User:Krishnavedala), used under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/).
## Properties
| Type | Name | Default |
| ------------ | ------------------------------------ | ------------------------------------------------------ |
| [NodePath] | [terminal_path](#prop-terminal_path) | None |
| [int] | [cols](#prop-cols) | `80` |
| [int] | [rows](#prop-rows) | `24` |
| [Dictionary] | [env](#prop-env) | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` |
| [bool] | [use_os_env](#prop-use_os_env) | `true` |
| Type | Name | Default |
| -------------- | ------------------------------------ | ------------------------------------------------------ |
| {{NodePath}} | [terminal_path](#prop-terminal_path) | None |
| {{int}} | [cols](#prop-cols) | 80 |
| {{int}} | [rows](#prop-rows) | 24 |
| {{Dictionary}} | [env](#prop-env) | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` |
| {{bool}} | [use_os_env](#prop-use_os_env) | true |
## Methods
| Returns | Signature |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| [Error] | [fork](#mthd-fork) **(** [String] file=`$SHELL`, [PoolStringArray] args=[], [String] cwd=`$PWD`, [int] cols=80, [int] rows=24 **)** |
| void | [kill](#mthd-kill) **(** [int] signum **)** |
| [Error] | [open](#mthd-open) **(** [int] cols=80, [int] rows=24 **)** |
| void | [resize](#mthd-resize) **(** [int] cols, [int] rows **)** |
| void | [resizev](#mthd-resizev) **(** [Vector2] size **)** |
| void | [write](#mthd-write) **(** [String]\|[PoolByteArray] data **)** |
| Returns | Signature |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| {{Error}} | [fork](#mthd-fork) **(** {{String}} file=$SHELL, {{PoolStringArray}} args=[ ], {{String}} cwd=$PWD, {{int}} cols=80, {{int}} rows=24 **)** |
| void | [kill](#mthd-kill) **(** {{int}} signum=1 **)** |
| {{Error}} | [open](#mthd-open) **(** {{int}} cols=80, {{int}} rows=24 **)** |
| void | [resize](#mthd-resize) **(** {{int}} cols, {{int}} rows **)** |
| void | [resizev](#mthd-resizev) **(** {{Vector2}} size **)** |
| void | [write](#mthd-write) **(** {{String}}\|{{PoolByteArray}} data **)** |
## Signals
- <a name="sgnl-data_received" /> **data_received** **(** [PoolByteArray] data **)**
<hr id="sgnl-data_received" />
Emitted when data is read from the pseudoterminal master device.
**data_received** **(** {{PoolByteArray}} data **)**
---
Emitted when data is read from the pseudoterminal master device.
- <a name="sgnl-exited" /> **exited** **(** [int] exit_code, [int] signum **)**
<hr id="sgnl-exited" />
Emitted when the child program exits. `exit_code` is the exit status of the child program and `signum` is the number of the signal that terminated the child program.
**exited** **(** {{int}} exit_code, {{int}} signum **)**
Emitted when the child program exits. `exit_code` is the exit status of the child program and `signum` is the number of the signal that terminated the child program.
<hr/>
## Enumerations
### <a name="enum-signal" /> enum **Signal**:
<hr id="enum-signal" />
enum **Signal**:
- **SIGHUP** = 1 --- Hangup.
- **SIGINT** = 2 --- Terminal interrupt signal.
@ -73,121 +73,119 @@ See issue [\#25](https://github.com/lihop/godot-xterm/issues/25).
- **SIGALRM** = 14 --- Alarm clock.
- **SIGTERM** = 15 --- Termination signal.
</hr>
## Property Descriptions
### <a name="prop-terminal_path" /> [NodePath] **terminal_path**
<hr id="prop-terminal_path" />
| | |
| --------- | ------------------------ |
| _Default_ | None |
| _Setter_ | set_terminal_path(value) |
| _Getter_ | None |
{{NodePath}} **terminal_path**
[NodePath] to a [Terminal]. Setting this path will automatically connect the appropriate signals of both nodes for standard operation. It will also disconnected the signals of the previously set terminal, if any.
| | |
| --------- | --------------------------------------------- |
| _Default_ | None |
| _Setter_ | void set_terminal_path ( {{NodePath}} value ) |
| _Getter_ | None |
---
{{NodePath}} to a {{Terminal}}. Setting this path will automatically connect the appropriate signals of both nodes for standard operation. It will also disconnected the signals of the previously set terminal, if any.
- <a name="prop-cols" /> [int] **cols**
<hr id="prop-cols" />
| | |
| --------- | --------------- |
| _Default_ | `80` |
| _Setter_ | set_cols(value) |
| _Getter_ | None |
{{int}} **cols**
The column size in characters.
| | |
| --------- | ------------------------------- |
| _Default_ | 80 |
| _Setter_ | void set_cols ( {{int}} value ) |
| _Getter_ | None |
---
The column size in characters.
- <a name="prop-rows" /> [int] **rows**
<hr id="prop-rows" />
| | |
| --------- | --------------- |
| _Default_ | `24` |
| _Setter_ | set_rows(value) |
| _Getter_ | None |
{{int}} **rows**
The row size in characters.
| | |
| --------- | ------------------------------- |
| _Default_ | 24 |
| _Setter_ | void set_rows ( {{int}} value ) |
| _Getter_ | None |
---
The row size in characters.
- <a name="prop-env" /> [Dictionary] **env**
<hr id="prop-env" />
| | |
| --------- | ------------------------------------------------------ |
| _Default_ | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` |
| _Setter_ | None |
| _Getter_ | None |
{{Dictionary}} **env**
Environment variables to be set for the child program.
| | |
| --------- | ------------------------------------------------------ |
| _Default_ | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` |
| _Setter_ | None |
| _Getter_ | None |
---
Environment variables to be set for the child program.
- <a name="prop-use_os_env" /> [bool] **use_os_env**
<hr id="prop-use_os_env" />
| | |
| --------- | ------ |
| _Default_ | `true` |
| _Setter_ | None |
| _Getter_ | None |
{{bool}} **use_os_env**
If `true` the environment variables from `env` will be merged with the environment variables of the current program (i.e. Godot), with the variables from `env` taking precedence over the environment variables of the current program.
| | |
| --------- | ---- |
| _Default_ | true |
| _Setter_ | None |
| _Getter_ | None |
If `true` the environment variables from `env` will be merged with the environment variables of the current program (i.e. Godot), with the variables from `env` taking precedence over the environment variables of the current program.
</hr>
## Method Descriptions
- <a name="mthd-fork" /> [Error] **fork** **(** [String] file=`$SHELL`, [PoolStringArray] args=[], [String] cwd=`$PWD`, [int] cols=80, [int] rows=24 **)**
<hr id="mthd-fork" />
Opens a pseudoterminal and starts a new process using the program specified by `file`.
`file` defaults to the value of the `SHELL` environment variable, falling back to `sh`.
The arguments specified in `args` are passed to the program.
`cwd` is the directory in which the program will be executed. Defaults to the working directory of the current program (typically the project directory, when running from editor).
`cols` is the initial number of columns and `rows` is the initial number of rows.
Returns [OK] if successful.
{{Error}} **fork** **(** {{String}} file=$SHELL, {{PoolStringArray}} args=[ ], {{String}} cwd=$PWD, {{int}} cols=80, {{int}} rows=24 **)**
See also Godot's [OS.execute()](https://docs.godotengine.org/en/stable/classes/class_os.html#class-os-method-execute) method.
Opens a pseudoterminal and starts a new process using the program specified by `file`.
`file` defaults to the value of the `SHELL` environment variable, falling back to `sh`.
The arguments specified in `args` are passed to the program.
`cwd` is the directory in which the program will be executed. Defaults to the working directory of the current program (typically the project directory, when running from editor).
`cols` is the initial number of columns and `rows` is the initial number of rows.
Returns {{OK}} if successful.
---
:::{seealso}
Godot's {{ '[OS.execute()]({}/classes/class_os.html#class-os-method-execute)'.format(godot_docs) }} method.
:::
- <a name="mthd-kill" /> void **kill** **(** [int] signum=1 **)**
<hr id="mthd-kill" />
Sends the specified signal (`signum`) to the PTY's child process, if any. Defaults to 1 (SIGHUP).
void **kill** **(** {{int}} signum=1 **)**
See also Godot's [OS.kill()](https://docs.godotengine.org/en/stable/classes/class_os.html#class-os-method-kill) method.
Sends the specified signal (`signum`) to the PTY's child process, if any. Defaults to `1` (`SIGHUP`).
---
:::{seealso}
Godot's {{ '[OS.kill()]({}/classes/class_os.html#class-os-method-kill)'.format(godot_docs) }} method.
:::
- <a name="mthd-open" /> [Error] **open** **(** [int] cols=80, [int] rows=24 **)**
<hr id="mthd-open" />
Opens a pseudoterminal but does not start any process. Returns [OK] if successful.
{{Error}} **open** **(** {{int}} cols=80, {{int}} rows=24 **)**
---
Opens a pseudoterminal but does not start any process. Returns {{OK}} if successful.
- <a name="mthd-resize" /> void **resize** **(** [int] cols, [int] rows **)**
<hr id="mthd-resize" />
Resizes the dimensions of the pseudoterminal.
void **resize** **(** {{int}} cols, {{int}} rows **)**
---
Resizes the dimensions of the pseudoterminal.
- <a name="mthd-resizev" /> void **resizev** **(** [Vector2] size **)**
<hr id="mthd-resizev" />
Same as resize, but accepts a [Vector2] where `x` is cols and `y` is rows.
void **resizev** **(** {{Vector2}} size **)**
---
Same as resize, but accepts a {{Vector2}} where `x` is cols and `y` is rows.
- <a name="mthd-write" /> void **write** **(** [String] \| [PoolByteArray] data **)**
<hr id="mthd-write" />
Writes data to the pseudoterminal master device.
void **write** **(** {{String}}\|{{PoolByteArray}} data **)**
[Dictionary]: https://docs.godotengine.org/en/stable/classes/class_dictionary.html
[Error]: https://docs.godotengine.org/en/stable/classes/class_%40globalscope.html#enum-globalscope-error
[Node]: https://docs.godotengine.org/en/stable/classes/class_node.html
[NodePath]: https://docs.godotengine.org/en/stable/classes/class_nodepath.html
[Object]: https://docs.godotengine.org/en/stable/classes/class_object.html
[OK]: https://docs.godotengine.org/en/stable/classes/class_%40globalscope.html#class-globalscope-constant-ok
[PoolByteArray]: https://docs.godotengine.org/en/stable/classes/class_poolbytearray.html
[PoolStringArray]: https://docs.godotengine.org/en/stable/classes/class_poolstringarray.html
[String]: https://docs.godotengine.org/en/stable/classes/class_string.html
[Terminal]: /api/terminal
[Vector2]: https://docs.godotengine.org/en/stable/classes/class_vector2.html
[bool]: https://docs.godotengine.org/en/stable/classes/class_bool.html
[int]: https://docs.godotengine.org/en/stable/classes/class_int.html
Writes data to the pseudoterminal master device.