Metadata-Version: 2.4
Name: ttygrid
Version: 0.1.2
Summary: Simple terminal grid rendering library
Author: JustMedansh
License: MIT
Project-URL: Homepage, https://github.com/JustAMed/ttygrid
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: termcolor
Dynamic: license-file

# ttygrid
ttygrid is a grid-based framework for building terminal simulations, games, and visualizations.
- [ttygrid on PyPi](https://pypi.org/project/ttygrid/)
![TTYGrid Demo](assets/showcase.gif)

## Features
- Grid class and cell class
- Functions to get and set cells
- Inbuilt coloring for different symbols using `termcolor`
- Auto adjust to terminal size using `shutil`
##  v0.1 is out! 

## Quick Start Guide
You can install `ttygrid` using pip using:

```
pip install ttygrid
```

Alternatively, you could use:

```
pip3 install ttygrid
```

Once installed, import with

```
from ttygrid import Grid, Cell
```

## Example
```
import random
import time
from ttygrid import Grid

def main():
    grid = Grid()
    while True:
        cells = grid.get_all_cells(empty=True)
        for cell in cells:
            cell.symb = random.choice(['0', '1'])
            grid.draw_cells(cell)
        grid.clear_term()
        print(grid)
        time.sleep(0.1)

if __name__ == "__main__":
    main()
```

## Documentation
### Grid()

 ```
 Grid(rows=80, cols=40, mode="fit", grid=None, color_map=COLORS)
 ```

Creates a new ttygrid grid instance that can be manipulated using the library.

#### Args
- `rows` (int) - If mode is "custom", the number of rows in the grid. If mode is "fit", the default number of rows in the grid if `shutil.get_terminal_size()` fails to determine terminal size. Default value 80.

- `cols` (int) - If mode is "custom", the number of cols in the grid. If mode is "fit", the default number of cols in the grid if `shutil.get_terminal_size()` fails to determine terminal size. Default value 40.

- `mode` (str) - Can be either "fit" or "custom" (case-sensitive). If mode is "custom", the dimensions of the grid are given through `rows` and `cols`. If mode is "fit", the dimensions are given through `shutil.get_terminal_size()`, with `rows` and `cols` as fallback. Default value "fit"

- `color_map` (dict[str, str]) - A dict with keys as cell symbols and values as colors recognized by `termcolor.colored()`. The default value is:
```
COLORS = {
        '0': "green",
        '1': "black",
        '2': "yellow",
        '3': "blue",
        '4': "light_yellow",
    }
```
---
### __str__() (Grid)
```
print(grid)
```

Prints the formatted grid to the terminal.

---
### show_size()
```
show_size(grid)
```

Prints the number of Lines (rows) and Columns (cols) in the grid. To get them programmatically, use grid.rows and grid.cols instead.

---
### clear_term()
```
clear_term()
```

Clears the terminal. Typically used before printing new frames.

---
### get_cell()
```
get_cell(col, row)
```

Returns the Cell object located at the coordinates (col, row)
Raises ValueError if cell does not exist.

---
### validate_cell()
```
validate_cell(cell)
```

Raises ValueError if cell coordinates not found in grid

---
### get_all_cells()
```
get_all_cells(empty=True)
```

Get a list of all cells in the grid. 
If `empty` is True, empty cells are also included.
If `empty` is False, empty cells are not included.
The default value is True

---
### draw_cells()
```
draw_cells(*cells)
```

Draws all valid cells passed as arguments onto the grid.

---
### clear()
```
clear()
```

Clears the grid (resets it to all cells being None)

---
### redraw_frame()
```
redraw_frame(cell_map)
```

The grid is redrawn using `cell_map`.
Effectively, the value of the grid is now `cell_map`.
A `cell_map` value not made of cells or having irregular sides compared to original grid.rows and grid.cols, results in undefined behaviour.
It is best to first call `get_all_cells()` and pass in modified values of the call to `redraw_frame()`

---

## Cell Class

### Cell()
```
Cell(x, y, symb=None)
```
Args:

- x - the x (col) position of the Cell
- y - the y (row) position of the Cell
- symb - the symbol represented by the cell. A value of None indicates an empty cell.
---
### __str__()
```
print(cell)
```

Prints the cell position and symbol

---

## Known Issues

- Extra newline after print (Scheduled to be fixed in v0.2)

---

## Roadmap

- Drawing primitives
- Demos
- Customizable status bar for simulation


