plotcli-py 0.1.0__py3-none-any.whl

plotcli.py

@@ -0,0 +1,978 @@
+#!/usr/bin/env python3
+"""
+plotcli - Terminal plotting for CLI interfaces like Claude Code.
+
+Renders plots using Unicode Braille characters, block elements, or ASCII.
+Supports: scatter, line, bar, histogram, boxplot, density, heatmap.
+
+Usage:
+    # Pipe data
+    echo "1 2 3 4 5" | plotcli line
+    echo -e "1,2\\n3,4\\n5,6" | plotcli scatter -d ","
+
+    # Expressions
+    plotcli line -e "import math; [(x/10, math.sin(x/10)) for x in range(100)]"
+
+    # CSV files
+    plotcli scatter -f data.csv -x col1 -y col2
+
+    # Quick functions
+    plotcli fn "math.sin(x)" 0 6.28
+    plotcli hist -e "[random.gauss(0,1) for _ in range(1000)]"
+"""
+
+import sys
+import math
+import argparse
+import os
+import json
+import re
+from typing import Optional
+
+# ─── ANSI Colors ─────────────────────────────────────────────────────────────
+
+COLORS = {
+    "red": "\033[31m",
+    "green": "\033[32m",
+    "yellow": "\033[33m",
+    "blue": "\033[34m",
+    "magenta": "\033[35m",
+    "cyan": "\033[36m",
+    "white": "\033[37m",
+    "bright_red": "\033[91m",
+    "bright_green": "\033[92m",
+    "bright_yellow": "\033[93m",
+    "bright_blue": "\033[94m",
+    "bright_magenta": "\033[95m",
+    "bright_cyan": "\033[96m",
+}
+RESET = "\033[0m"
+
+COLOR_CYCLE = ["blue", "red", "green", "yellow", "magenta", "cyan",
+               "bright_red", "bright_green", "bright_blue", "bright_magenta"]
+
+
+def colorize(text: str, color: Optional[str]) -> str:
+    if color and color in COLORS:
+        return f"{COLORS[color]}{text}{RESET}"
+    return text
+
+
+# ─── Bresenham's Line Algorithm ──────────────────────────────────────────────
+
+def bresenham(x0, y0, x1, y1):
+    points = []
+    dx = abs(x1 - x0)
+    dy = abs(y1 - y0)
+    sx = 1 if x0 < x1 else -1
+    sy = 1 if y0 < y1 else -1
+    err = dx - dy
+    while True:
+        points.append((x0, y0))
+        if x0 == x1 and y0 == y1:
+            break
+        e2 = 2 * err
+        if e2 > -dy:
+            err -= dy
+            x0 += sx
+        if e2 < dx:
+            err += dx
+            y0 += sy
+    return points
+
+
+# ─── Canvas Classes ──────────────────────────────────────────────────────────
+
+class BrailleCanvas:
+    """High-resolution canvas using Unicode Braille patterns (2x4 dots per cell)."""
+
+    BRAILLE_BASE = 0x2800
+    # Bit positions for each dot in a braille cell
+    # Layout:  col0 col1
+    # row0:    0x01 0x08
+    # row1:    0x02 0x10
+    # row2:    0x04 0x20
+    # row3:    0x40 0x80
+    DOT_BITS = [
+        [0x01, 0x08],
+        [0x02, 0x10],
+        [0x04, 0x20],
+        [0x40, 0x80],
+    ]
+
+    def __init__(self, width, height):
+        self.width = width
+        self.height = height
+        self.pixel_width = width * 2
+        self.pixel_height = height * 4
+        self.codes = [[0] * width for _ in range(height)]
+        self.color_matrix = [[None] * width for _ in range(height)]
+
+    def set_pixel(self, px, py, color=None):
+        px = max(0, min(px, self.pixel_width - 1))
+        py = max(0, min(py, self.pixel_height - 1))
+        cell_col = px // 2
+        cell_row = py // 4
+        dot_col = px % 2
+        dot_row = py % 4
+        self.codes[cell_row][cell_col] |= self.DOT_BITS[dot_row][dot_col]
+        if color:
+            self.color_matrix[cell_row][cell_col] = color
+
+    def draw_line(self, x0, y0, x1, y1, color=None):
+        for px, py in bresenham(round(x0), round(y0), round(x1), round(y1)):
+            self.set_pixel(px, py, color)
+
+    def render(self):
+        lines = []
+        for r in range(self.height):
+            row = ""
+            for c in range(self.width):
+                ch = chr(self.BRAILLE_BASE + self.codes[r][c]) if self.codes[r][c] else " "
+                row += colorize(ch, self.color_matrix[r][c])
+            lines.append(row)
+        return lines
+
+
+class BlockCanvas:
+    """Medium-resolution canvas using half-block characters (1x2 per cell)."""
+
+    UPPER = "\u2580"
+    LOWER = "\u2584"
+    FULL = "\u2588"
+
+    def __init__(self, width, height):
+        self.width = width
+        self.height = height
+        self.pixel_width = width
+        self.pixel_height = height * 2
+        self.state = [[0] * width for _ in range(height)]  # 0=none 1=upper 2=lower 3=both
+        self.color_matrix = [[None] * width for _ in range(height)]
+
+    def set_pixel(self, px, py, color=None):
+        px = max(0, min(px, self.pixel_width - 1))
+        py = max(0, min(py, self.pixel_height - 1))
+        cell_col = px
+        cell_row = py // 2
+        is_lower = (py % 2) == 1
+        if is_lower:
+            self.state[cell_row][cell_col] |= 2
+        else:
+            self.state[cell_row][cell_col] |= 1
+        if color:
+            self.color_matrix[cell_row][cell_col] = color
+
+    def draw_line(self, x0, y0, x1, y1, color=None):
+        for px, py in bresenham(round(x0), round(y0), round(x1), round(y1)):
+            self.set_pixel(px, py, color)
+
+    def render(self):
+        chars = {0: " ", 1: self.UPPER, 2: self.LOWER, 3: self.FULL}
+        lines = []
+        for r in range(self.height):
+            row = ""
+            for c in range(self.width):
+                ch = chars.get(self.state[r][c], " ")
+                row += colorize(ch, self.color_matrix[r][c])
+            lines.append(row)
+        return lines
+
+
+class AsciiCanvas:
+    """Basic ASCII canvas (1x1 per cell)."""
+
+    def __init__(self, width, height, char="*"):
+        self.width = width
+        self.height = height
+        self.pixel_width = width
+        self.pixel_height = height
+        self.char = char
+        self.matrix = [[" "] * width for _ in range(height)]
+        self.color_matrix = [[None] * width for _ in range(height)]
+
+    def set_pixel(self, px, py, color=None):
+        px = max(0, min(px, self.pixel_width - 1))
+        py = max(0, min(py, self.pixel_height - 1))
+        self.matrix[py][px] = self.char
+        if color:
+            self.color_matrix[py][px] = color
+
+    def draw_line(self, x0, y0, x1, y1, color=None):
+        for px, py in bresenham(round(x0), round(y0), round(x1), round(y1)):
+            self.set_pixel(px, py, color)
+
+    def render(self):
+        lines = []
+        for r in range(self.height):
+            row = ""
+            for c in range(self.width):
+                row += colorize(self.matrix[r][c], self.color_matrix[r][c])
+            lines.append(row)
+        return lines
+
+
+def create_canvas(width, height, canvas_type="braille"):
+    if canvas_type == "braille":
+        return BrailleCanvas(width, height)
+    elif canvas_type == "block":
+        return BlockCanvas(width, height)
+    elif canvas_type == "ascii":
+        return AsciiCanvas(width, height)
+    raise ValueError(f"Unknown canvas type: {canvas_type}")
+
+
+# ─── Normalization & Helpers ─────────────────────────────────────────────────
+
+def normalize(data, data_min, data_max, plot_range):
+    if data_max == data_min:
+        return [plot_range // 2] * len(data)
+    return [
+        max(0, min(plot_range - 1, round((v - data_min) / (data_max - data_min) * (plot_range - 1))))
+        for v in data
+    ]
+
+
+def format_tick(num, width=6):
+    if abs(num) < 0.001 and num != 0:
+        s = f"{num:.1e}"
+    elif abs(num) >= 10000:
+        s = f"{num:.1e}"
+    elif num == int(num):
+        s = str(int(num))
+    else:
+        s = f"{num:.2f}".rstrip("0").rstrip(".")
+    return s.rjust(width)
+
+
+def auto_size():
+    """Detect terminal size, return (width, height) for the plot canvas."""
+    try:
+        cols, rows = os.get_terminal_size()
+    except (AttributeError, ValueError, OSError):
+        cols, rows = 80, 24
+    # Leave room for borders, labels, title
+    w = max(20, cols - 18)
+    h = max(8, rows - 8)
+    return w, h
+
+
+def compute_boxplot_stats(data):
+    data = sorted(data)
+    n = len(data)
+    def percentile(d, p):
+        k = (len(d) - 1) * p / 100
+        f = math.floor(k)
+        c = math.ceil(k)
+        if f == c:
+            return d[int(k)]
+        return d[f] * (c - k) + d[c] * (k - f)
+    q1 = percentile(data, 25)
+    median = percentile(data, 50)
+    q3 = percentile(data, 75)
+    iqr = q3 - q1
+    lower_fence = q1 - 1.5 * iqr
+    upper_fence = q3 + 1.5 * iqr
+    whisker_low = min(v for v in data if v >= lower_fence)
+    whisker_high = max(v for v in data if v <= upper_fence)
+    outliers = [v for v in data if v < lower_fence or v > upper_fence]
+    return whisker_low, q1, median, q3, whisker_high, outliers
+
+
+# ─── Plot Class ──────────────────────────────────────────────────────────────
+
+class Plot:
+    """Terminal plot with support for multiple series and plot types."""
+
+    # Box-drawing characters
+    H_BORDER = "\u2500"
+    V_BORDER = "\u2502"
+    TL = "\u250c"
+    TR = "\u2510"
+    BL = "\u2514"
+    BR = "\u2518"
+
+    def __init__(self, width=None, height=None, title=None,
+                 x_label="x", y_label="y", canvas_type="braille",
+                 xlim=None, ylim=None, legend=True):
+        if width is None or height is None:
+            aw, ah = auto_size()
+            width = width or aw
+            height = height or ah
+        self.width = width
+        self.height = height
+        self.title = title
+        self.x_label = x_label
+        self.y_label = y_label
+        self.canvas_type = canvas_type
+        self.xlim = xlim
+        self.ylim = ylim
+        self.show_legend = legend
+        self.series = []  # list of dicts: {x, y, type, color, name}
+
+    def add(self, x, y, plot_type="line", color=None, name=None):
+        if color is None:
+            color = COLOR_CYCLE[len(self.series) % len(COLOR_CYCLE)]
+        if name is None:
+            name = f"data_{len(self.series) + 1}"
+        self.series.append({"x": x, "y": y, "type": plot_type, "color": color, "name": name})
+        return self
+
+    def _get_bounds(self):
+        all_x, all_y = [], []
+        for s in self.series:
+            all_x.extend(s["x"])
+            all_y.extend(s["y"])
+        x_min = self.xlim[0] if self.xlim else min(all_x)
+        x_max = self.xlim[1] if self.xlim else max(all_x)
+        y_min = self.ylim[0] if self.ylim else min(all_y)
+        y_max = self.ylim[1] if self.ylim else max(all_y)
+        # Expand if range is zero
+        if x_max == x_min:
+            expand = abs(x_min) * 0.05 if x_min != 0 else 1
+            x_min -= expand
+            x_max += expand
+        if y_max == y_min:
+            expand = abs(y_min) * 0.05 if y_min != 0 else 1
+            y_min -= expand
+            y_max += expand
+        return x_min, x_max, y_min, y_max
+
+    def _draw_scatter(self, canvas, s, x_min, x_max, y_min, y_max):
+        xs_norm = normalize(s["x"], x_min, x_max, canvas.pixel_width)
+        ys_norm = normalize(s["y"], y_min, y_max, canvas.pixel_height)
+        for px, py in zip(xs_norm, ys_norm):
+            canvas.set_pixel(px, canvas.pixel_height - 1 - py, s["color"])
+
+    def _draw_line(self, canvas, s, x_min, x_max, y_min, y_max):
+        xs_norm = normalize(s["x"], x_min, x_max, canvas.pixel_width)
+        ys_norm = normalize(s["y"], y_min, y_max, canvas.pixel_height)
+        # Invert y axis (top=0 in canvas)
+        ys_norm = [canvas.pixel_height - 1 - y for y in ys_norm]
+        for i in range(len(xs_norm) - 1):
+            canvas.draw_line(xs_norm[i], ys_norm[i], xs_norm[i + 1], ys_norm[i + 1], s["color"])
+
+    def _draw_bar(self, canvas, s, x_min, x_max, y_min, y_max):
+        xs_norm = normalize(s["x"], x_min, x_max, canvas.pixel_width)
+        ys_norm = normalize(s["y"], y_min, y_max, canvas.pixel_height)
+        y_zero = normalize([max(y_min, 0)], y_min, y_max, canvas.pixel_height)[0]
+        for px, py in zip(xs_norm, ys_norm):
+            top = canvas.pixel_height - 1 - py
+            bottom = canvas.pixel_height - 1 - y_zero
+            if top > bottom:
+                top, bottom = bottom, top
+            for row in range(top, bottom + 1):
+                # Fill a few columns for width
+                for dx in range(-1, 2):
+                    canvas.set_pixel(max(0, px + dx), row, s["color"])
+
+    def _draw_boxplot(self, canvas, s, x_min, x_max, y_min, y_max, box_center_px):
+        stats = compute_boxplot_stats(s["y"])
+        whisker_low, q1, median, q3, whisker_high, outliers = stats
+        vals = [whisker_low, q1, median, q3, whisker_high]
+        norms = normalize(vals, y_min, y_max, canvas.pixel_height)
+        norms = [canvas.pixel_height - 1 - v for v in norms]
+        # whisker_low_py, q1_py, median_py, q3_py, whisker_high_py
+        wl, q1p, mp, q3p, wh = norms
+        color = s["color"]
+        # Whisker lines (vertical)
+        canvas.draw_line(box_center_px, wh, box_center_px, q3p, color)
+        canvas.draw_line(box_center_px, q1p, box_center_px, wl, color)
+        # Box
+        box_half = max(2, canvas.pixel_width // 12)
+        left = box_center_px - box_half
+        right = box_center_px + box_half
+        canvas.draw_line(left, q1p, right, q1p, color)
+        canvas.draw_line(left, q3p, right, q3p, color)
+        canvas.draw_line(left, q1p, left, q3p, color)
+        canvas.draw_line(right, q1p, right, q3p, color)
+        # Median line
+        canvas.draw_line(left, mp, right, mp, color)
+        # Whisker caps
+        cap = max(1, box_half // 2)
+        canvas.draw_line(box_center_px - cap, wl, box_center_px + cap, wl, color)
+        canvas.draw_line(box_center_px - cap, wh, box_center_px + cap, wh, color)
+        # Outliers
+        for o in outliers:
+            oy = normalize([o], y_min, y_max, canvas.pixel_height)[0]
+            oy = canvas.pixel_height - 1 - oy
+            canvas.set_pixel(box_center_px, oy, color)
+
+    def render(self):
+        """Render the plot and return as a string."""
+        x_min, x_max, y_min, y_max = self._get_bounds()
+        canvas = create_canvas(self.width, self.height, self.canvas_type)
+
+        is_boxplot = any(s["type"] == "boxplot" for s in self.series)
+        boxplot_series = [s for s in self.series if s["type"] == "boxplot"]
+
+        for i, s in enumerate(self.series):
+            t = s["type"]
+            if t == "scatter":
+                self._draw_scatter(canvas, s, x_min, x_max, y_min, y_max)
+            elif t == "line":
+                self._draw_line(canvas, s, x_min, x_max, y_min, y_max)
+            elif t in ("bar", "barplot"):
+                self._draw_bar(canvas, s, x_min, x_max, y_min, y_max)
+            elif t == "boxplot":
+                idx = boxplot_series.index(s)
+                n = len(boxplot_series)
+                center = canvas.pixel_width * (idx * 2 + 1) // (n * 2)
+                self._draw_boxplot(canvas, s, x_min, x_max, y_min, y_max, center)
+
+        canvas_lines = canvas.render()
+        return self._assemble(canvas_lines, x_min, x_max, y_min, y_max, is_boxplot)
+
+    def _assemble(self, canvas_lines, x_min, x_max, y_min, y_max, is_boxplot=False):
+        """Add borders, axes, title, legend around the canvas."""
+        lines = []
+        tick_width = 8
+
+        # Y-axis tick values (top to bottom)
+        n_y_ticks = min(self.height, 6)
+        y_tick_vals = [y_max - i * (y_max - y_min) / (n_y_ticks - 1) for i in range(n_y_ticks)]
+        y_tick_positions = [round(i * (self.height - 1) / (n_y_ticks - 1)) for i in range(n_y_ticks)]
+
+        # Build y tick labels
+        y_labels = {}
+        for pos, val in zip(y_tick_positions, y_tick_vals):
+            y_labels[pos] = format_tick(val, tick_width)
+
+        # Title
+        if self.title:
+            title_line = self.title.center(self.width + tick_width + 3)
+            lines.append(title_line)
+
+        # Top border
+        top = " " * tick_width + " " + self.TL + self.H_BORDER * self.width + self.TR
+        lines.append(top)
+
+        # Canvas rows with y-axis ticks
+        for i, row in enumerate(canvas_lines):
+            label = y_labels.get(i, " " * tick_width)
+            tick_mark = "\u2524" if i in y_labels else self.V_BORDER
+            lines.append(f"{label} {tick_mark}{row}{self.V_BORDER}")
+
+        # Bottom border
+        bot = " " * tick_width + " " + self.BL + self.H_BORDER * self.width + self.BR
+        lines.append(bot)
+
+        # X-axis ticks
+        if not is_boxplot:
+            n_x_ticks = min(self.width // 10, 6)
+            n_x_ticks = max(2, n_x_ticks)
+            x_tick_vals = [x_min + i * (x_max - x_min) / (n_x_ticks - 1) for i in range(n_x_ticks)]
+            x_tick_positions = [round(i * (self.width - 1) / (n_x_ticks - 1)) for i in range(n_x_ticks)]
+
+            tick_line = [" "] * (self.width + tick_width + 3)
+            for pos, val in zip(x_tick_positions, x_tick_vals):
+                s = format_tick(val, 6).strip()
+                start = tick_width + 2 + pos - len(s) // 2
+                for j, ch in enumerate(s):
+                    if 0 <= start + j < len(tick_line):
+                        tick_line[start + j] = ch
+            lines.append("".join(tick_line))
+        else:
+            # Label boxplots by name
+            boxplot_series = [s for s in self.series if s["type"] == "boxplot"]
+            tick_line = [" "] * (self.width + tick_width + 3)
+            for idx, s in enumerate(boxplot_series):
+                n = len(boxplot_series)
+                center = self.width * (idx * 2 + 1) // (n * 2)
+                name = s["name"]
+                start = tick_width + 2 + center - len(name) // 2
+                for j, ch in enumerate(name):
+                    if 0 <= start + j < len(tick_line):
+                        tick_line[start + j] = ch
+            lines.append("".join(tick_line))
+
+        # X-axis label
+        if self.x_label:
+            x_label_line = " " * tick_width + " " + self.x_label.center(self.width + 2)
+            lines.append(x_label_line)
+
+        # Y-axis label (vertically centered, prepend to existing lines)
+        if self.y_label and len(self.y_label) <= self.height:
+            y_start = (len(lines) - len(self.y_label)) // 2
+            new_lines = []
+            for i, line in enumerate(lines):
+                if y_start <= i < y_start + len(self.y_label):
+                    ch = self.y_label[i - y_start]
+                else:
+                    ch = " "
+                new_lines.append(ch + " " + line)
+            lines = new_lines
+        else:
+            lines = ["  " + line for line in lines]
+
+        # Legend
+        if self.show_legend and len(self.series) > 1:
+            legend_start = 2 if self.title else 1
+            for i, s in enumerate(self.series):
+                row_idx = legend_start + 1 + i
+                if row_idx < len(lines):
+                    legend_entry = "  " + colorize("\u2588\u2588", s["color"]) + " " + s["name"]
+                    lines[row_idx] = lines[row_idx] + legend_entry
+
+        return "\n".join(lines)
+
+    def show(self):
+        print(self.render())
+        return self
+
+
+# ─── Convenience Functions ───────────────────────────────────────────────────
+
+def scatter(x, y, **kwargs):
+    return Plot(**kwargs).add(x, y, "scatter")
+
+def line(x, y, **kwargs):
+    return Plot(**kwargs).add(x, y, "line")
+
+def bar(x, y, **kwargs):
+    return Plot(**kwargs).add(x, y, "bar")
+
+def histogram(data, bins=None, **kwargs):
+    if bins is None:
+        bins = max(5, min(int(math.sqrt(len(data))), 50))
+    d_min, d_max = min(data), max(data)
+    if d_max == d_min:
+        d_max = d_min + 1
+    bin_width = (d_max - d_min) / bins
+    counts = [0] * bins
+    for v in data:
+        idx = min(int((v - d_min) / bin_width), bins - 1)
+        counts[idx] += 1
+    mids = [d_min + (i + 0.5) * bin_width for i in range(bins)]
+    kwargs.setdefault("ylim", (0, max(counts) * 1.05))
+    kwargs.setdefault("y_label", "count")
+    return Plot(**kwargs).add(mids, counts, "bar")
+
+def density(data, n_points=100, **kwargs):
+    """Simple KDE using Gaussian kernel."""
+    d = sorted(data)
+    n = len(d)
+    # Silverman's rule of thumb for bandwidth
+    std = (sum((x - sum(d) / n) ** 2 for x in d) / n) ** 0.5
+    bw = 1.06 * std * n ** (-1 / 5) if std > 0 else 1
+    x_min, x_max = min(d) - 3 * bw, max(d) + 3 * bw
+    xs = [x_min + i * (x_max - x_min) / (n_points - 1) for i in range(n_points)]
+    ys = []
+    for x in xs:
+        s = sum(math.exp(-0.5 * ((x - xi) / bw) ** 2) for xi in d)
+        ys.append(s / (n * bw * math.sqrt(2 * math.pi)))
+    kwargs.setdefault("y_label", "density")
+    return Plot(**kwargs).add(xs, ys, "line")
+
+def boxplot(datasets, names=None, **kwargs):
+    """Create boxplots from a list of datasets."""
+    if not isinstance(datasets[0], (list, tuple)):
+        datasets = [datasets]
+    if names is None:
+        names = [f"box_{i+1}" for i in range(len(datasets))]
+    all_vals = [v for d in datasets for v in d]
+    kwargs.setdefault("ylim", (min(all_vals) - 0.05 * (max(all_vals) - min(all_vals)),
+                                max(all_vals) + 0.05 * (max(all_vals) - min(all_vals))))
+    p = Plot(**kwargs)
+    for i, (d, name) in enumerate(zip(datasets, names)):
+        p.add([0] * len(d), d, "boxplot", name=name)
+    return p
+
+def function_plot(expr_str, x_min=0, x_max=10, n_points=200, **kwargs):
+    """Plot a math function like 'math.sin(x)' or 'x**2'."""
+    xs = [x_min + i * (x_max - x_min) / (n_points - 1) for i in range(n_points)]
+    ys = []
+    for x in xs:
+        try:
+            y = eval(expr_str, {"x": x, "math": math, "pi": math.pi, "e": math.e,
+                                "sin": math.sin, "cos": math.cos, "tan": math.tan,
+                                "sqrt": math.sqrt, "log": math.log, "exp": math.exp,
+                                "abs": abs})
+            ys.append(float(y))
+        except Exception:
+            ys.append(float("nan"))
+    # Filter NaN
+    valid = [(x, y) for x, y in zip(xs, ys) if not math.isnan(y) and not math.isinf(y)]
+    if not valid:
+        raise ValueError("No valid points to plot")
+    xs, ys = zip(*valid)
+    kwargs.setdefault("title", f"f(x) = {expr_str}")
+    return Plot(**kwargs).add(list(xs), list(ys), "line")
+
+
+# ─── Heatmap ─────────────────────────────────────────────────────────────────
+
+def heatmap(matrix, row_labels=None, col_labels=None, title=None, width=None, height=None):
+    """Render a simple heatmap using block shading."""
+    rows = len(matrix)
+    cols = len(matrix[0]) if rows > 0 else 0
+    all_vals = [v for row in matrix for v in row]
+    vmin, vmax = min(all_vals), max(all_vals)
+    if vmax == vmin:
+        vmax = vmin + 1
+
+    # Shade characters from light to dark
+    shades = " ░▒▓█"
+    # Color gradient: blue -> cyan -> green -> yellow -> red
+    heat_colors = ["blue", "cyan", "green", "yellow", "red"]
+
+    lines = []
+    if title:
+        lines.append(title.center(cols * 2 + 10))
+
+    label_w = 0
+    if row_labels:
+        label_w = max(len(str(l)) for l in row_labels) + 1
+
+    for r in range(rows):
+        row_str = ""
+        if row_labels:
+            row_str += str(row_labels[r]).rjust(label_w) + " "
+        for c in range(cols):
+            frac = (matrix[r][c] - vmin) / (vmax - vmin)
+            shade_idx = min(int(frac * len(shades)), len(shades) - 1)
+            color_idx = min(int(frac * len(heat_colors)), len(heat_colors) - 1)
+            ch = shades[shade_idx]
+            row_str += colorize(ch * 2, heat_colors[color_idx])
+        lines.append(row_str)
+
+    if col_labels:
+        label_line = " " * (label_w + 1) if row_labels else ""
+        for l in col_labels:
+            label_line += str(l)[:2].center(2)
+        lines.append(label_line)
+
+    return "\n".join(lines)
+
+
+# ─── Data Parsing ────────────────────────────────────────────────────────────
+
+def parse_input(text, delimiter=None):
+    """Parse text input into x, y arrays. Handles various formats:
+    - Single line of values: treated as y values
+    - One value per line: treated as y values
+    - Two columns per line: treated as x,y pairs
+    """
+    lines = [l.strip() for l in text.strip().split("\n") if l.strip() and not l.startswith("#")]
+    if not lines:
+        return [], []
+
+    # Try to detect delimiter
+    if delimiter is None:
+        first = lines[0]
+        if "," in first:
+            delimiter = ","
+        elif "\t" in first:
+            delimiter = "\t"
+        else:
+            delimiter = None  # whitespace
+
+    # If only one line, split it into individual values (y values)
+    if len(lines) == 1:
+        parts = lines[0].split(delimiter) if delimiter else lines[0].split()
+        ys = []
+        for p in parts:
+            try:
+                ys.append(float(p.strip()))
+            except ValueError:
+                continue
+        if len(ys) > 2 or (len(ys) <= 2 and len(parts) <= 2):
+            # Treat as y-values when there are many values on one line
+            # or when there are exactly 1-2 values (ambiguous, default to y)
+            if len(ys) > 2:
+                return list(range(len(ys))), ys
+            # For exactly 2 values on one line, could be x,y pair or two y-values
+            # Default to y-values for consistency with piping
+            return list(range(len(ys))), ys
+
+    # Multi-line: try to detect if it's one column or two columns
+    xs, ys = [], []
+    two_column = False
+    for line in lines:
+        parts = line.split(delimiter) if delimiter else line.split()
+        parts = [p.strip() for p in parts if p.strip()]
+        if len(parts) >= 2:
+            try:
+                xs.append(float(parts[0]))
+                ys.append(float(parts[1]))
+                two_column = True
+            except ValueError:
+                continue
+        elif len(parts) == 1:
+            try:
+                ys.append(float(parts[0]))
+            except ValueError:
+                continue
+
+    if not two_column or not xs:
+        xs = list(range(len(ys)))
+
+    return xs, ys
+
+
+def parse_csv(filepath, x_col=None, y_col=None, delimiter=","):
+    """Parse a CSV file into x, y arrays."""
+    with open(filepath) as f:
+        lines = [l.strip() for l in f if l.strip()]
+
+    if not lines:
+        return [], []
+
+    # Check if first line is a header
+    header = lines[0].split(delimiter)
+    has_header = False
+    try:
+        [float(h) for h in header]
+    except ValueError:
+        has_header = True
+
+    if has_header:
+        header = [h.strip().strip('"').strip("'") for h in header]
+        data_lines = lines[1:]
+    else:
+        header = [str(i) for i in range(len(header))]
+        data_lines = lines
+
+    # Determine columns
+    if x_col is None and y_col is None:
+        x_idx, y_idx = 0, 1 if len(header) > 1 else (None, 0)
+    else:
+        x_idx = header.index(x_col) if x_col and x_col in header else (int(x_col) if x_col and x_col.isdigit() else 0)
+        y_idx = header.index(y_col) if y_col and y_col in header else (int(y_col) if y_col and y_col.isdigit() else 1)
+
+    xs, ys = [], []
+    for line in data_lines:
+        parts = line.split(delimiter)
+        try:
+            y = float(parts[y_idx].strip())
+            ys.append(y)
+            if x_idx is not None:
+                xs.append(float(parts[x_idx].strip()))
+        except (ValueError, IndexError):
+            continue
+
+    if not xs:
+        xs = list(range(len(ys)))
+
+    return xs, ys
+
+
+# ─── CLI ─────────────────────────────────────────────────────────────────────
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="plotcli",
+        description="Terminal plotting tool. Supports piped data, CSV files, expressions, and math functions.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  echo "1 4 9 16 25" | plotcli line
+  echo -e "1,2\\n2,4\\n3,9" | plotcli scatter -d ","
+  plotcli fn "sin(x)" 0 6.28
+  plotcli hist -e "[random.gauss(0,1) for _ in range(500)]"
+  plotcli line -f data.csv -x time -y value
+  plotcli scatter -e "[(x, x**2 + random.gauss(0,5)) for x in range(50)]" --title "Quadratic"
+  seq 100 | awk '{print sin($1/10)}' | plotcli line
+  plotcli boxplot -e "[random.gauss(0,1) for _ in range(100)]" "[random.gauss(2,1.5) for _ in range(100)]"
+  plotcli heatmap -e "[[math.sin(r/3+c/3) for c in range(15)] for r in range(10)]"
+        """,
+    )
+
+    parser.add_argument("type", nargs="?", default="line",
+                        choices=["line", "scatter", "bar", "hist", "histogram",
+                                 "density", "boxplot", "box", "fn", "function",
+                                 "heatmap"],
+                        help="Plot type (default: line)")
+    parser.add_argument("args", nargs="*", help="Positional args (for fn: expression x_min x_max)")
+
+    # Data sources
+    parser.add_argument("-e", "--eval", dest="expr", help="Python expression that produces data")
+    parser.add_argument("-f", "--file", help="CSV/TSV file path")
+    parser.add_argument("-x", "--x-col", help="X column name or index")
+    parser.add_argument("-y", "--y-col", help="Y column name or index")
+    parser.add_argument("-d", "--delimiter", help="Input delimiter")
+    parser.add_argument("-j", "--json", action="store_true", help="Parse input as JSON array")
+
+    # Appearance
+    parser.add_argument("-W", "--width", type=int, help="Canvas width in characters")
+    parser.add_argument("-H", "--height", type=int, help="Canvas height in characters")
+    parser.add_argument("-t", "--title", help="Plot title")
+    parser.add_argument("--x-label", default=None, help="X-axis label")
+    parser.add_argument("--y-label", default=None, help="Y-axis label")
+    parser.add_argument("-c", "--color", help="Series color")
+    parser.add_argument("--canvas", default="braille", choices=["braille", "block", "ascii"],
+                        help="Canvas type (default: braille)")
+    parser.add_argument("--no-legend", action="store_true", help="Hide legend")
+
+    # Limits
+    parser.add_argument("--xlim", nargs=2, type=float, metavar=("MIN", "MAX"))
+    parser.add_argument("--ylim", nargs=2, type=float, metavar=("MIN", "MAX"))
+
+    # Histogram
+    parser.add_argument("--bins", type=int, help="Number of histogram bins")
+
+    return parser
+
+
+def eval_data(expr_str):
+    """Evaluate a Python expression to get data."""
+    import random
+    result = eval(expr_str, {"__builtins__": __builtins__, "math": math, "random": random,
+                              "pi": math.pi, "e": math.e,
+                              "sin": math.sin, "cos": math.cos, "tan": math.tan,
+                              "sqrt": math.sqrt, "log": math.log, "exp": math.exp})
+    return result
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+
+    plot_kwargs = {
+        "width": args.width,
+        "height": args.height,
+        "title": args.title,
+        "x_label": args.x_label if args.x_label else "x",
+        "y_label": args.y_label,
+        "canvas_type": args.canvas,
+        "xlim": tuple(args.xlim) if args.xlim else None,
+        "ylim": tuple(args.ylim) if args.ylim else None,
+        "legend": not args.no_legend,
+    }
+
+    plot_type = args.type
+    if plot_type in ("hist", "histogram"):
+        plot_type = "histogram"
+    elif plot_type in ("box",):
+        plot_type = "boxplot"
+    elif plot_type in ("fn", "function"):
+        plot_type = "function"
+
+    # ── Function plot ────────────────────────────────────────────────────
+    if plot_type == "function":
+        if args.expr:
+            expr = args.expr
+        elif args.args:
+            expr = args.args[0]
+        else:
+            parser.error("fn requires an expression, e.g.: plotcli fn 'sin(x)' 0 6.28")
+        x_min = float(args.args[1]) if len(args.args) > 1 else 0
+        x_max = float(args.args[2]) if len(args.args) > 2 else 10
+        if plot_kwargs["y_label"] is None:
+            plot_kwargs["y_label"] = "f(x)"
+        function_plot(expr, x_min, x_max, **plot_kwargs).show()
+        return
+
+    # ── Heatmap ──────────────────────────────────────────────────────────
+    if plot_type == "heatmap":
+        if args.expr:
+            matrix = eval_data(args.expr)
+        elif not sys.stdin.isatty():
+            text = sys.stdin.read()
+            if args.json:
+                matrix = json.loads(text)
+            else:
+                matrix = []
+                for line in text.strip().split("\n"):
+                    parts = line.split(args.delimiter) if args.delimiter else line.split()
+                    matrix.append([float(p) for p in parts if p.strip()])
+        else:
+            parser.error("heatmap needs data via -e or stdin")
+        print(heatmap(matrix, title=args.title, width=args.width, height=args.height))
+        return
+
+    # ── Get data ─────────────────────────────────────────────────────────
+    xs, ys = [], []
+
+    # For boxplot, support multiple expressions
+    if plot_type == "boxplot":
+        datasets = []
+        names = []
+        if args.expr:
+            data = eval_data(args.expr)
+            if isinstance(data, (list, tuple)):
+                if data and isinstance(data[0], (list, tuple)):
+                    datasets = [list(d) for d in data]
+                else:
+                    datasets = [list(data)]
+            names = [f"box_{i+1}" for i in range(len(datasets))]
+        elif args.args:
+            for i, a in enumerate(args.args):
+                d = eval_data(a)
+                datasets.append(list(d))
+                names.append(f"box_{i+1}")
+        elif not sys.stdin.isatty():
+            text = sys.stdin.read()
+            if args.json:
+                data = json.loads(text)
+                if isinstance(data[0], (list, tuple)):
+                    datasets = data
+                else:
+                    datasets = [data]
+            else:
+                _, ys = parse_input(text, args.delimiter)
+                datasets = [ys]
+            names = [f"box_{i+1}" for i in range(len(datasets))]
+        else:
+            parser.error("No data provided")
+
+        if plot_kwargs["y_label"] is None:
+            plot_kwargs["y_label"] = "value"
+        boxplot(datasets, names, **plot_kwargs).show()
+        return
+
+    if args.expr:
+        data = eval_data(args.expr)
+        if isinstance(data, (list, tuple)):
+            if data and isinstance(data[0], (list, tuple)):
+                xs = [p[0] for p in data]
+                ys = [p[1] for p in data]
+            else:
+                ys = list(data)
+                xs = list(range(len(ys)))
+    elif args.file:
+        xs, ys = parse_csv(args.file, args.x_col, args.y_col,
+                          args.delimiter or ",")
+    elif not sys.stdin.isatty():
+        text = sys.stdin.read()
+        if args.json:
+            data = json.loads(text)
+            if isinstance(data, dict):
+                xs = data.get("x", list(range(len(data.get("y", [])))))
+                ys = data.get("y", [])
+            elif isinstance(data, list):
+                if data and isinstance(data[0], (list, tuple)):
+                    xs = [p[0] for p in data]
+                    ys = [p[1] for p in data]
+                else:
+                    ys = data
+                    xs = list(range(len(ys)))
+        else:
+            xs, ys = parse_input(text, args.delimiter)
+    else:
+        parser.error("No data provided. Pipe data, use -e, or -f. See --help.")
+
+    if not ys:
+        print("Error: No valid data points found.", file=sys.stderr)
+        sys.exit(1)
+
+    if plot_kwargs["y_label"] is None:
+        plot_kwargs["y_label"] = "y"
+
+    # ── Create plot ──────────────────────────────────────────────────────
+    if plot_type == "histogram" or plot_type == "density":
+        if plot_type == "histogram":
+            if args.y_label is None:
+                plot_kwargs["y_label"] = "count"
+            histogram(ys, bins=args.bins, **plot_kwargs).show()
+        else:
+            if args.y_label is None:
+                plot_kwargs["y_label"] = "density"
+            density(ys, **plot_kwargs).show()
+    elif plot_type in ("scatter", "line", "bar"):
+        p = Plot(**plot_kwargs)
+        p.add(xs, ys, plot_type, color=args.color)
+        p.show()
+
+
+if __name__ == "__main__":
+    main()