# jtf.py

Python utilities for interacting with .jtf files.

[View main repository.](https://github.com/NotTimTam/jtf)

[Read the syntax standard.](https://github.com/NotTimTam/jtf/blob/main/SYNTAX.md)

[View an example JTF file.](https://github.com/NotTimTam/jtf/blob/main/example.jtf)

This package is a direct conversion of the main JTF utilities. While the functions within this package use Python wording (like `list` instead of `array`), the casing required by the [JTF standard](https://github.com/NotTimTam/jtf/blob/main/SYNTAX.md) still applies when creating/parsing documents.

Requires Python 3.12 or newer.

# Installation

```terminal
pip install jtf
```

# Usage

```python
from jtf import JTF

document = JTF.parse("<document data>")
```

# Reference

## JTF Class

### Import

```python
from jtf import JTF
```

### `JTF.target_list_includes_cell(target, x, y)`

Checks if a target list targets a specific coordinate.

Parameters:

-   target (List<number|string>): The target list to check.
-   x (number|string): The x-coordinate to check.
-   y (number|string): The y-coordinate to check.

Returns `True` if the target list includes the specified coordinate, otherwise `False`.

### `JTF.parse(data)`

Parses JTF data into a readable object.

Parameters:

-   data (string|obj): The data to parse.

Returns an instance of the `Document` class based on the parsed data.

### `JTF.stringify(document)`

Convert a [`Document`](#document-class) object into a string.

-   document ([`Document`](#document-class)): The document to stringify.

Returns a string of the document's source data.

## Document Class

Generated by JTF class' [`parse`](#jtfparsedata) method.

### `Document.get_cell(table, x, y)`

Retrieves the content of a cell in a specified table.

Parameters:

-   table: The index of the table.
-   x: The x-coordinate of the cell.
-   y: The y-coordinate of the cell.

Returns the content of the cell, or `None` if the cell does not exist.

### `Document.to_csv()`

Converts each table in the document into CSV format.

Returns an object containing CSV strings for each table in the document.

### `Document.to_list()`

Converts each table in the document into lists.

Returns an object containing lists for each table in the document.

### `Document.stringify()`

Returns the data object represented by a JTF string.

### `Document.update_updated_at()`

Updates the document's `updatedAt` value to be the current timestamp.

### `Document.set_table(index, value)`

Set a table to a value. **Will overwrite existing tables.**

Parameters:

-   index (string|number): The index of the table.
-   data: The data to set.

### `Document.get_extra_processor_data(processor)`

Parameters:

-   processor (string): The unique identifier the data is stored under.

Returns a data object if found, or `None` if no object was found.

### `Document.set_extra_processor_data(processor, data, extend)`

Overwrites or updates data objects defined in a document's `metadata.extra` object.

Parameters:

-   processor (string): The unique identifier the data is stored under.
-   data (obj): An object of extra data to set.
-   extend (boolean): If `True`, destructures the new data object into existing data instead of overwriting it. (default `False`)

### `Document.tables`

An integer-string index of [`Table`](#table-class) objects.

### `Document.source`

The document's source object. This is the raw data that is parsed in `JTF.parse()`.

## Table Class

Generated by Document class and stored under `Document.tables` object.

### `Table.get_cell_styles(x, y)`

Retrieves the styles that must be applied to a cell.

Parameters:

-   x (string|number): The x-coordinate of the cell.
-   y (string|number): The y-coordinate of the cell.

Returns an object containing the classes and styles to apply to this cell.

### `Table.get_cell(x, y)`

Retrieves the content of a cell.

Parameters:

-   x (string|number): The x-coordinate of the cell.
-   y (string|number): The y-coordinate of the cell.

Returns the content of the cell, or `None` if the cell does not exist.

### `Table.set_cell(x, y, value)`

Set the content of a cell.

Parameters:

-   x (string|number): The x-coordinate of the cell.
-   y (string|number): The y-coordinate of the cell.
-   value (string|number|null|boolean): The value to set.

### `Table.to_csv()`

Converts the data object into CSV format.

Returns the table data in CSV format.

### `Table.to_list()`

Converts the table into a 2D list.

Returns the table as a 2D list.

### `Table.source`

The table's source object. This is the raw data that is stored under the table's document parent's `source.data`.

### `Table.label`

The table's label value. Can be used to set a `Table` instance's label. (`myTable.label = "myNewLabel"`)
