### Start PC-BASIC with a Package

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/examples.html

Loads and executes a program contained within a PC-BASIC package (e.g., Foobar.baz). PC-BASIC will load settings and typically run the main program from the package.

```shell
pcbasic Foobar.baz
```

--------------------------------

### PC-BASIC Command-Line Interface Examples

Source: https://context7.com/robhagemans/pcbasic/llms.txt

Illustrates various ways to invoke PC-BASIC from the command line, including starting interactive sessions, running programs, setting video modes, mounting directories, converting file formats, and configuring interpreter behavior.

```bash
# Start interactive session with default settings
pcbasic

# Run a BASIC program file
pcbasic program.bas

# Run with specific video mode and monitor
pcbasic --video=tandy --monitor=composite program.bas

# Mount directories as drives
pcbasic --mount=A:/path/to/diskA --mount=B:/path/to/diskB

# Execute commands and exit
pcbasic --exec="LOAD \"PROG.BAS\"" --exec="RUN" --quit

# Convert file formats
pcbasic --convert=A program.bas output.txt  # To ASCII
pcbasic --convert=P program.txt output.bas  # To protected
pcbasic program.bas --save-as=output.txt    # Load and save

# Use preset configurations
pcbasic --preset=tandy program.bas
pcbasic --preset=pcjr program.bas

# Set BASIC syntax mode
pcbasic --syntax=advanced program.bas
pcbasic --syntax=gwbasic program.bas

# Specify codepage and font
pcbasic --codepage=437 --font=default
pcbasic --codepage=932 --font=unifont  # Japanese

# Control memory configuration
pcbasic --max-memory=32768 --reserved-memory=1024

# Start with text-only interface (no graphics)
pcbasic --interface=cli program.bas
pcbasic --interface=ansi program.bas
```

--------------------------------

### Start PC-BASIC in Direct Mode (GW-BASIC/BASICA Emulation)

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/examples.html

Launches PC-BASIC in direct mode, emulating GW-BASIC or BASICA with VGA graphics. This is the default behavior when no specific package or file is provided.

```shell
pcbasic
```

--------------------------------

### Example: Integrating PC-BASIC with Python using Session API

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/devguide.html

Demonstrates a complete example of using the PC-BASIC Session API in Python, including session management, code execution, expression evaluation, variable setting, and calling extensions.

```Python
import pcbasic
import random

with pcbasic.Session(extension=random) as s:
    s.execute('a=1')
    print(s.evaluate('string$(a+2, "@")'))
    s.set_variable('B$', 'abcd')
    s.execute('''
        10 a=5
        20 print a
        run
        _seed(42)
        b = _uniform(a, 25.6)
        print a, b
    ''')
```

--------------------------------

### Start PC-BASIC with a Specific Codepage

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/examples.html

Initiates PC-BASIC using a specified codepage, such as Big-5 for traditional Chinese characters. This ensures correct text rendering for non-ASCII character sets.

```shell
pcbasic --codepage=950
```

--------------------------------

### Emulate PCjr and Simulate Keystrokes

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/examples.html

Executes a BASIC program ('PCJRGAME.BAS') on an emulated PCjr machine. The `-k` option simulates keystrokes, in this case, entering 'start' followed by Enter ('\r').

```shell
pcbasic PCJRGAME.BAS --preset=pcjr -k='start\r'
```

--------------------------------

### Python: Manage BASIC Interpreter Sessions with PC-BASIC

Source: https://context7.com/robhagemans/pcbasic/llms.txt

Demonstrates how to create, start, and manage a PC-BASIC interpreter session using Python. It covers executing BASIC statements, setting and getting variables, evaluating expressions, loading program files, and capturing screen output. Uses context manager for automatic cleanup.

```python
from pcbasic import Session

# Create and run a BASIC session with context manager
with Session(syntax='advanced', video='cga') as session:
    # Start the session
    session.start()

    # Execute BASIC statements
    output = session.execute('PRINT "Hello from BASIC"')
    print(output.decode('ascii'))  # b'Hello from BASIC\r\n'

    # Set variables (sigil must be explicit)
    session.set_variable('MYNUM%', 42)
    session.set_variable('MYSTR$', 'test')

    # Get variables
    value = session.get_variable('MYNUM%')
    print(value)  # 42

    # Evaluate expressions
    result = session.evaluate('2 + 2 * 3')
    print(result)  # 8

    # Load and run a program file
    with session.bind_file('/path/to/program.bas') as progfile:
        session.execute(b'LOAD "%s"' % (progfile,)) # Use bytes for file path in BASIC command
    session.execute('RUN')

    # Get screen contents
    chars = session.get_chars(as_type=str)
    pixels = session.get_pixels()

    # Session automatically closes on exit
```

--------------------------------

### Mount Directories as Drives and Run BASIC Program

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/examples.html

Mounts local subdirectories as emulated floppy drives (e.g., './files' as 'A:' and './morefiles' as 'B:') and then executes a specified BASIC program (MYPROG.BAS).

```shell
pcbasic MYPROG.BAS --mount=A:./files,B:./morefiles
```

--------------------------------

### Emulate MDA Monitor and Run BASIC Program

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/examples.html

Executes a BASIC program ('INFO.BAS') with an emulated MDA (Monochrome Display Adapter) preset and an amber-tinted monitor. The program runs in the current directory.

```shell
pcbasic Z:\INFO.BAS --preset=mda --monitor=amber
```

--------------------------------

### Mount a Directory as a Drive

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/examples.html

Runs PC-BASIC with a specified directory (e.g., 'C:\fakeflop' on Windows) mounted as an emulated drive (e.g., 'A:'). This allows the BASIC program to access files within that directory.

```shell
pcbasic --mount=A:C:\fakeflop
```

--------------------------------

### Emulate CGA Monitor and Run BASIC Program

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/examples.html

Runs a BASIC program ('COMP.BAS') located in a specific directory ('/home/me/retro') using an emulated CGA (Color Graphics Adapter) preset and a composite monitor.

```shell
pcbasic /home/me/retro/COMP.BAS --preset=cga --monitor=composite
```

--------------------------------

### RUN Command

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/reference.html

Executes a program, optionally starting from a specific line number or loading from a file. Clears existing variables and can optionally keep files open.

```APIDOC
## RUN

### Description
Executes a program. Existing variables will be cleared. `RUN` implies `[CLEAR](#CLEAR)`. If `file_spec` is given, any program in memory will be erased. If `,R` is specified after `file_spec`, files are kept open; if not, all files are closed.

### Method
RUN

### Endpoint

### Parameters
#### Path Parameters
* `line_number` (integer) - Optional - A valid line number in the current program. If specified, execution starts from this line number. The rest of the `RUN` statement is ignored in this case.
* `file_spec` (string) - Optional - A valid [file specification](#filespec) indicating the file to read the program from.

#### Query Parameters

#### Request Body

### Request Example
```
RUN 100
RUN "myprogram.bas", R
```

### Response
#### Success Response (200)
No specific response body, program execution begins.

#### Response Example

### Errors
* `line_number` is not a line number in the current program: Undefined line number.
* `file_spec` cannot be found: File not found.
* `file_spec` is an empty string: Bad file number.
* A loaded text file contains lines without line numbers: Direct statement in file.
```

--------------------------------

### Running a PC-BASIC Program from Command Line

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/documentation.html

Illustrates how to execute a BASIC program immediately upon starting PC-BASIC using the --run option. The program path can be a PC-BASIC path or a standard OS path.

```shell
pcbasic --run=MYPROG.BAS
```

--------------------------------

### Redirect Output to LPT2 Printer

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/examples.html

Runs a BASIC program ('BANNER.BAS') and directs its output intended for the second printer port (LPT2) to a specified printer device (e.g., 'PRINTER:').

```shell
pcbasic BANNER.BAS --lpt2=PRINTER:
```

--------------------------------

### PALETTE USING Command Syntax

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/reference.html

Assigns multiple colors to attributes simultaneously using an integer array. The mapping starts from a specified index within the array.

```pcbasic
PALETTE USING int_array_name { ( | [ } start_index { ) | ] }
```

--------------------------------

### Resume Last PC-BASIC Session

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/examples.html

Restarts PC-BASIC and restores the state of the most recently closed session. This is useful for continuing work without restarting from scratch.

```shell
pcbasic --resume
```

--------------------------------

### OPTION BASE Statement

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/reference.html

Sets the starting index for array allocations. The index can only be 0 or 1.

```APIDOC
## OPTION BASE Statement

### Description
Sets the starting index of all arrays to `n`. `n` must be a literal digit `0` or `1`.

### Method
Not applicable (keyword statement)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```basic
OPTION BASE 1
```

### Response
#### Success Response (200)
Not applicable

#### Response Example
Not applicable

##### Notes
* If `OPTION BASE` has not been called, the first array allocation defaults to starting index 0.

##### Errors
* `n` is not a digit `0` or `1`: Syntax error.
* `OPTION BASE 1` is called but an array has already been allocated before: Duplicate definition.
* `OPTION BASE` is called more than once with different starting index: Duplicate definition.
```

--------------------------------

### Use PC-BASIC Session as a Context Manager (Python)

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/devguide.html

Manages the lifecycle of a PC-BASIC session using Python's `with` statement. Ensures the session is properly opened and closed automatically. Requires the 'pcbasic' library.

```Python
import pcbasic

with pcbasic.Session() as s:
    # Use the session object 's' here
    s.execute('PRINT "Inside context manager"')
# Session is automatically closed here
```

--------------------------------

### Attach and Launch PC-BASIC Session with Interfaces

Source: https://context7.com/robhagemans/pcbasic/llms.txt

Details how to configure and attach various interfaces (video, audio, input) to a PC-BASIC session. This example specifically shows setting up a session with video, monitor, and syntax options, then attaching an interface to launch an interactive session.

```python
from pcbasic import Session
from pcbasic.interface import Interface

# Create session with specific interface configuration
session = Session(
    video='cga',
    monitor='rgb',
    syntax='advanced'
)

# Create interface (video plugin)
interface = Interface(
    try_interfaces=('sdl2', 'cli', 'ansi'),
    audio_override=None,
    wait=False
)

# Attach interface and run
session.attach(interface)
session.greet()

# Launch interactive session with interface
def run_basic():
    with session:
        session.interact()

interface.launch(run_basic)
```

--------------------------------

### Get BASIC Variables with PC-BASIC Session API (Python)

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/devguide.html

Retrieves the value of a scalar or array variable from the PC-BASIC session. Returns values as Python types (int, float, bytes, list). Variable names are case-insensitive. Requires the 'pcbasic' library.

```Python
import pcbasic

with pcbasic.Session() as s:
    s.set_variable('myVar', 100)
    value = s.get_variable('myVar')
    print(value)
    s.set_variable('myString$', 'Hello PC-BASIC')
    string_value = s.get_variable('myString$')
    print(string_value)
    s.set_variable('myArray()', [1, 2, 3])
    array_value = s.get_variable('myArray()')
    print(array_value)
```

--------------------------------

### Convert and List Package Main Program (UTF-8)

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/examples.html

Extracts and lists the main program from a specified package (Foobar.baz) to standard output. The `--convert=A` flag indicates listing the main program, and `--text-encoding=utf-8` specifies UTF-8 output encoding.

```shell
pcbasic Foobar.baz --convert=A --text-encoding=utf-8
```

--------------------------------

### INSTR Function

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/reference.html

Finds the starting position of a substring within a parent string. Supports specifying a starting search position.

```APIDOC
## INSTR Function

### Description
Returns the location of the first occurrence of the substring `child` in `parent`. The search can optionally start from a specified position.

### Method
```
position = INSTR([start,] parent, child)
```

### Parameters
*   `parent` (string) - The string to search within.
*   `child` (string) - The substring to search for.
*   `start` (numeric) - Optional. The starting position for the search (1-255). Defaults to 1 if not specified.

### Notes
*   If `child` is not found in `parent` at or after `start`, `INSTR` returns 0.

### Errors
*   Type mismatch: `start` is a string, or `parent`/`child` are numeric.
*   Overflow: `start` is outside the range [-32768—32767].
*   Illegal function call: `start` is outside the range [1—255].
```

--------------------------------

### RENUM

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/reference.html

Renumber program lines. Allows specifying new starting line number, old starting line number to affect, and the increment between lines.

```APIDOC
## RENUM

### Description
Replaces the line numbers in the program by a systematic enumeration starting from `new` and increasing by `increment`. If `old` is specified, line numbers less than `old` remain unchanged. `new`, `old` are line numbers; the dot `.` signifies the last line edited. `increment` is a line number but must not be a dot or zero. Also stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.

### Method
RENUM

### Endpoint
Not applicable (this is a language command, not a REST endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **new** - Optional - The new starting line number. Defaults to 10 if not specified.
- **old** - Optional - The old starting line number. Lines before this remain unchanged. Defaults to the first line of the program if not specified.
- **increment** - Optional - The increment between new line numbers. Defaults to 10 if not specified.

### Request Example
```basic
RENUM 100, 50, 5
' Renumber starting from line 100, affecting lines from 50 onwards, with an increment of 5.

RENUM . , , 20
' Renumber from the current line, with an increment of 20.
```

### Response
#### Success Response (200)
This command modifies the program's line numbers and returns control to the user. It does not return a specific data structure.

#### Response Example
No direct response body. The program's line numbers are updated.
```

--------------------------------

### GET (communications)

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/reference.html

Reads bytes from a communications buffer.

```APIDOC
## GET # com_file_number [, number_bytes]

### Description
Reads `number_bytes` bytes from the communications buffer opened under file number `com_file_number`. The data can be accessed through the `FIELD` variables or through `INPUT$`, `INPUT` or `LINE INPUT`.

### Method
N/A (This is a BASIC language keyword, not an HTTP method)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (N/A)
Data is read into variables specified by subsequent I/O statements.

#### Response Example
None

### Parameters
*   `file_number`: A numeric expression that yields the number of a file open to a `COM` device. The `#` is optional and has no effect.
*   `number_bytes`: A numeric expression between `1` and the `COM` buffer length, inclusive.

### Notes
*   If `bytes` is `32768` or greater, GW-BASIC hangs. This functionality is not implemented in PC-BASIC.
*   In GW-BASIC, Device I/O error is raised for overrun error, framing error, and break interrupt. Device fault is raised if DSR is lost during I/O. Parity error is raised if parity is enabled and incorrect parity is encountered. This is according to the manual; it is untested.

### Errors
*   **Bad record number**: `bytes` is less than 1.
*   **Illegal function call**: `bytes` is less than `32768` and greater than the `COM` buffer length; or `com_file_number` is not in `[0—255]`.
*   **Missing operand**: `com_file_number` is not specified.
*   **Bad file number**: `com_file_number` is not the number of an open file.
*   **Communication buffer overflow**: If the serial input buffer is full, i.e. `LOF(com_file_number) = 0`, and `LOC(com_file_number) = 255`.
*   **Hangs**: If the carrier drops during `GET`, hangs until the Ctrl+Break key is pressed.
```

--------------------------------

### GET (files)

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/reference.html

Reads a record from a random-access file.

```APIDOC
## GET # file_number [, record_number]

### Description
Reads a record from the random-access file `file_number` at position `record_number`. The record can be accessed through the `FIELD` variables or through `INPUT$`, `INPUT` or `LINE INPUT`.

### Method
N/A (This is a BASIC language keyword, not an HTTP method)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (N/A)
Data is read into variables specified by subsequent I/O statements.

#### Response Example
None

### Parameters
*   `file_number`: A numeric expression that yields the number of an open random-access file. The `#` is optional and has no effect.
*   `record_number`: A numeric expression in `[1—33554432]` (`2^25`), and is interpreted as the record number.

### Notes
*   If the record number is beyond the end of the file, the file buffer is filled with null bytes.
*   The record number is stored as single-precision; this precision is not high enough to distinguish single records near the maximum value of `2^25`.

### Errors
*   **Bad record number**: `record_number` is not in `[1—33554432]`.
*   **Illegal function call**: `file_number` is not in `[0—255]`.
*   **Bad file mode**: `file_number` is not the number of an open file, or `file_number` is open under a mode other than `RANDOM`.
*   **Missing operand**: `file_number` is not specified.
```

--------------------------------

### PC-BASIC RENUM Statement

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/reference.html

The RENUM statement renumbers program lines systematically. It allows specifying a new starting line number, an old starting line number (lines before this remain unchanged), and an increment. The dot (.) represents the last edited line. RENUM stops execution and returns control to the user. Any statements following RENUM on the same line are ignored.

```BASIC
RENUM [new|.] [, [old|.] [, increment]]
```

--------------------------------

### PAINT Statement

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/reference.html

Flood-fills a region of the screen with a specified color or pattern, starting from a seed point.

```APIDOC
## PAINT Statement

### Description
Flood-fills the screen with a colour or pattern, starting from the given seed point (`x`, `y`).

### Method
Not applicable (keyword statement)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```basic
PAINT (10, 20), 15  ' Fill with color 15 starting at (10, 20)
PAINT STEP (5, 5), "#", 1, " " ' Fill with pattern, boundary color 1, ignore background " "
```

### Response
#### Success Response (200)
Not applicable

#### Response Example
Not applicable

##### Parameters
* `x`, `y` are numeric expressions in the range `[-32768—32767]`. If `STEP` is specified, `x`, `y` are offsets from the current position. If the seed point is outside the visible screen area, no flood fill is performed.
* `attrib` is an expression that specifies the fill attribute or pattern. If not specified, the current foreground attribute is used.
    * If `attrib` has a number value, it must be in `[0—255]`; it specifies the colour attribute used to fill.
    * If `attrib` has a string value, it specifies a tile pattern.
* `border` is a numeric expression in `[0—255]`. It specifies the attribute of the fill boundary.
* `background` is a string expression that represents a background tile pattern to ignore when determining boundaries.
```

--------------------------------

### Resume and Interact with a PC-BASIC Session

Source: https://context7.com/robhagemans/pcbasic/llms.txt

Demonstrates how to resume a saved PC-BASIC session, execute commands within it, and enter interactive mode. Requires a pre-existing session state file.

```python
from pcbasic import Session

resumed_session = Session.resume('/tmp/mysession.state')
with resumed_session:
    # Continue execution
    resumed_session.execute('PRINT "Resumed!"')
    resumed_session.interact()
```

--------------------------------

### File Compatibility and Naming Conventions

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/reference.html

Explains how PC-BASIC matches provided file names to host file systems, including handling of long file names, 8.3 format, and case sensitivity. It also describes the process for creating new files.

```APIDOC
## File Compatibility and Naming Conventions

### Description
PC-BASIC employs a multi-step process to match provided file names to host file system names, ensuring compatibility with both long file names and traditional DOS 8.3 formats. This includes handling case sensitivity and non-permissible characters.

### File Matching Process:

1.  **Direct Match**: Attempts to find a file with the name exactly as provided. This is case-sensitive if the host file system is.
2.  **Truncated 8.3 Match**: If no direct match is found, it truncates the name to an all-uppercase 8.3 format (first 8 characters before the dot, first 3 after) and looks for an exact match. Errors occur if this truncated name contains non-permissible characters.
3.  **Case-Insensitive 8.3 Match**: Searches for 8.3 names in mixed case that match the provided name case-insensitively. Longer file names are only matched if entered exactly. On Windows, this can match short or long 8.3 names.

### Special Case: Trailing Dot
If a file name ends in a single dot and has no other dots, PC-BASIC first matches the name as provided. If not found, it matches the name without the trailing dot. 8.3 format matches will consider both with and without the dot, in lexicographic order.

### New File Creation
If no matching file is found for an output file name, a new file is created using an all-uppercase 8.3 file name.
```

--------------------------------

### Codepage and Font Loading with PC-BASIC Session

Source: https://context7.com/robhagemans/pcbasic/llms.txt

Shows how to load and utilize different codepages and font data within a PC-BASIC session for internationalization and character set support. Demonstrates setting codepage and font during session initialization.

```python
from pcbasic import Session, codepage, font

# Load a codepage
cp437 = codepage('437')
cp850 = codepage('850')
cp932 = codepage('932')  # Japanese Shift-JIS

# Use codepage in session
with Session(codepage='437') as session:
    session.start()
    session.execute('PRINT "Using CP437"')

# Load font data
cga_font = font('cga')
vga_font = font('vga')
unifont = font('unifont')

# Use custom font in session
with Session(font='vga') as session:
    session.start()
    session.execute('PRINT "Using VGA font"')

# Combine codepage and font for Japanese
with Session(codepage='932', font='unifont') as session:
    session.start()
    session.execute('PRINT "日本語"')
```

--------------------------------

### Python: Execute BASIC Commands and Manage I/O with PC-BASIC

Source: https://context7.com/robhagemans/pcbasic/llms.txt

Shows how to execute multiple BASIC statements programmatically, including loops and PRINT statements. It also demonstrates capturing output to a string buffer and executing BASIC commands like LIST and RUN. Custom input/output pipes can be added and removed.

```python
from pcbasic import Session
import io

session = Session()
session.start()

# Execute multiple statements
code = """
FOR I = 1 TO 5
    PRINT I * I
NEXT I
"""
output = session.execute(code, as_type=str)
print(output)
# Output: 1 4 9 16 25

# Execute with custom input/output pipes
output_buffer = io.StringIO()
session.add_pipes(output_streams=output_buffer)
session.execute('PRINT "Captured output"')
session.remove_pipes(output_streams=output_buffer)
print(output_buffer.getvalue())

# Execute BASIC commands
session.execute('10 PRINT "Line 10"')
session.execute('20 PRINT "Line 20"')
session.execute('LIST')  # Lists program lines
session.execute('RUN')    # Runs the program

session.close()
```

--------------------------------

### PUT (graphics)

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/reference.html

Displays an array to a rectangular area of the graphics screen, often used with data stored by GET. Allows for various display modes like PSET, PRESET, AND, OR, and XOR.

```APIDOC
## PUT (graphics)

### Description
Displays an array to a rectangular area of the graphics screen. Usually, `PUT` is used with arrays that have been stored using `GET`. See `[GET](#GET-graphics)` for the format of the array.

The keywords have the following effect:
`PSET`: Overwrite the screen location with the new image
`PRESET`: Overwrite the screen location with the inverse image
`AND`: Combines the old and new attributes with bitwise AND
`OR`: Combines the old and new attributes with bitwise OR
`XOR`: Combines the old and new attributes with bitwise XOR

### Method
PUT

### Endpoint
Not applicable (this is a language command, not a REST endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **array_name** (numeric array) - Required - The name of the array containing the graphics data.
- **x0** (numeric expression) - Required - The x-coordinate of the top-left corner of the rectangular area.
- **y0** (numeric expression) - Required - The y-coordinate of the top-left corner of the rectangular area.
- **mode** (keyword) - Optional - The combination mode (PSET, PRESET, AND, OR, XOR). Defaults to PSET if not specified.

### Request Example
```basic
PUT (10, 20), my_array, XOR
```

### Response
#### Success Response (200)
This command modifies the graphics screen directly and does not return a specific data structure in the typical API sense.

#### Response Example
No direct response body. Visual changes on the graphics screen.
```

--------------------------------

### LOCATE Command

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/reference.html

Positions the cursor on the screen, changes its shape, and controls its visibility during program execution. It also allows for defining the cursor's starting and ending lines within a character cell.

```APIDOC
## LOCATE Command

### Description
Positions the cursor at a specified row and column on the screen, changes the cursor shape, and controls its visibility. It also allows for defining the cursor's starting and ending lines within a character cell, impacting its shape and appearance.

### Method
Not Applicable (BASIC Keyword)

### Endpoint
Not Applicable (BASIC Keyword)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

**Syntax:**
`LOCATE [row] [**,** [col] [**,** [cursor_visible] [**,** [start_line] [**,** [stop_line] [**,**]]]]]`

**Parameter Details:**
- **row** (numeric) - The row position for the cursor.
- **col** (numeric) - The column position for the cursor.
- **cursor_visible** (0 or 1) - Controls cursor visibility. 0 for invisible, 1 for visible.
- **start_line** (numeric) - The starting line within a character cell for cursor shape (0-31).
- **stop_line** (numeric) - The ending line within a character cell for cursor shape (0-31).

### Request Example
```basic
10 LOCATE 10, 20, 1, 5, 10
```

### Response
#### Success Response (200)
No direct response, modifies cursor position and appearance.

#### Response Example
None
```

--------------------------------

### Saving a PC-BASIC Program

Source: https://github.com/robhagemans/pcbasic/blob/master/docs/source/documentation.html

Demonstrates how to save the current BASIC program to a file in three different formats: plain text (A), tokenized (default), and protected (P). The file will be saved with a .BAS extension in the current working directory.

```basic
SAVE "MYPROG",A
SAVE "MYPROG"
SAVE "MYPROG",P
```