dktcli 1.0.0__py3-none-any.whl

devkittools/tools/jsontool.py

@@ -0,0 +1,200 @@
+"""dkt json (js) - format, minify, query, validate, flatten and convert JSON."""
+from __future__ import annotations
+
+import argparse
+import csv
+import io
+import json
+import re
+import sys
+
+from ..utils import DktError, c, color_enabled, info, ok, output_result, read_input, sym
+
+META = ("Data & Text", "json", "js", "pretty-print, minify, query, flatten, JSON -> CSV")
+
+EPILOG = """\
+examples:
+  dkt js fmt data.json                 pretty-print (colored in a terminal)
+  cat resp.json | dkt js fmt --sort
+  dkt js min -f data.json --copy
+  dkt js get users[0].name -f data.json
+  dkt js keys -f data.json             show the shape of the document
+  dkt js flat -f data.json             a.b[0].c = value
+  dkt js csv -f users.json             array of objects -> CSV
+  dkt js fmt --paste --copy            fix whatever is on your clipboard
+Trailing commas and // comments are tolerated and cleaned up.
+"""
+
+_TOKEN = re.compile(r'("(?:\\.|[^"\\])*")(\s*:)?|(\btrue\b|\bfalse\b)|(\bnull\b)|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)')
+
+
+def colorize(text: str) -> str:
+    if not color_enabled():
+        return text
+
+    def sub(m):
+        if m.group(1):
+            return (c(m.group(1), "bcyan") + m.group(2)) if m.group(2) else c(m.group(1), "bgreen")
+        if m.group(3):
+            return c(m.group(3), "byellow")
+        if m.group(4):
+            return c(m.group(4), "gray")
+        return c(m.group(5), "bmagenta")
+    return _TOKEN.sub(sub, text)
+
+
+def _strip_lenient(text: str) -> str:
+    """Remove // and /* */ comments (outside strings) and trailing commas."""
+    out, i, n, in_str = [], 0, len(text), False
+    while i < n:
+        ch = text[i]
+        if in_str:
+            out.append(ch)
+            if ch == "\\" and i + 1 < n:
+                out.append(text[i + 1])
+                i += 1
+            elif ch == '"':
+                in_str = False
+        elif ch == '"':
+            in_str = True
+            out.append(ch)
+        elif text.startswith("//", i):
+            while i < n and text[i] != "\n":
+                i += 1
+            continue
+        elif text.startswith("/*", i):
+            end = text.find("*/", i + 2)
+            i = n if end == -1 else end + 2
+            continue
+        else:
+            out.append(ch)
+        i += 1
+    return re.sub(r",(\s*[}\]])", r"\1", "".join(out))
+
+
+def loads(text: str):
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as first:
+        try:
+            data = json.loads(_strip_lenient(text))
+            info(c("note: fixed comments / trailing commas", "gray"))
+            return data
+        except json.JSONDecodeError:
+            lines = text.splitlines()
+            ctx = lines[first.lineno - 1] if 0 < first.lineno <= len(lines) else ""
+            raise DktError("Invalid JSON at line %d, column %d: %s\n  %s\n  %s^" % (
+                first.lineno, first.colno, first.msg, ctx.strip()[:100], " " * min(first.colno, 100)))
+
+
+def get_path(data, path: str):
+    cur = data
+    for tok in re.findall(r"[^.\[\]]+|\[\d+\]", path):
+        try:
+            if tok.startswith("["):
+                cur = cur[int(tok[1:-1])]
+            elif isinstance(cur, list) and tok.isdigit():
+                cur = cur[int(tok)]
+            else:
+                cur = cur[tok]
+        except (KeyError, IndexError, TypeError):
+            raise DktError("Path not found at '%s'" % tok)
+    return cur
+
+
+def flatten(data, prefix=""):
+    items = []
+    if isinstance(data, dict):
+        for k, v in data.items():
+            items += flatten(v, "%s.%s" % (prefix, k) if prefix else str(k))
+    elif isinstance(data, list):
+        for i, v in enumerate(data):
+            items += flatten(v, "%s[%d]" % (prefix, i))
+    else:
+        items.append((prefix, data))
+    return items
+
+
+def shape(data, indent=0, name="$", out=None):
+    out = [] if out is None else out
+    pad = "  " * indent
+    if isinstance(data, dict):
+        out.append("%s%s: object (%d keys)" % (pad, name, len(data)))
+        for k, v in data.items():
+            shape(v, indent + 1, k, out)
+    elif isinstance(data, list):
+        out.append("%s%s: array (%d items)" % (pad, name, len(data)))
+        if data:
+            shape(data[0], indent + 1, "[0]", out)
+    else:
+        out.append("%s%s: %s" % (pad, name, type(data).__name__ if data is not None else "null"))
+    return out
+
+
+def run(args) -> int:
+    text = read_input(args.file_pos, args.file, args.paste, "JSON")
+    data = loads(text)
+    op = args.op
+    if op == "validate":
+        ok("valid JSON")
+        return 0
+    if op == "fmt":
+        out = json.dumps(data, indent=args.indent, sort_keys=args.sort, ensure_ascii=False)
+        output_result(out, copy=True) if args.copy else print(colorize(out))
+    elif op == "min":
+        output_result(json.dumps(data, separators=(",", ":"), sort_keys=args.sort, ensure_ascii=False), copy=args.copy)
+    elif op == "get":
+        val = get_path(data, args.path)
+        out = json.dumps(val, indent=2, ensure_ascii=False) if isinstance(val, (dict, list)) else (
+            val if isinstance(val, str) else json.dumps(val))
+        print(colorize(out) if isinstance(val, (dict, list)) else out)
+    elif op == "keys":
+        print("\n".join(shape(data)))
+    elif op == "flat":
+        for k, v in flatten(data):
+            print("%s = %s" % (c(k, "bcyan"), json.dumps(v, ensure_ascii=False)))
+    elif op == "csv":
+        if not isinstance(data, list) or not data or not all(isinstance(x, dict) for x in data):
+            raise DktError("CSV conversion needs a JSON array of objects.")
+        cols = []
+        for row in data:
+            for k in row:
+                if k not in cols:
+                    cols.append(k)
+        buf = io.StringIO()
+        w = csv.writer(buf, lineterminator="\n")
+        w.writerow(cols)
+        for row in data:
+            w.writerow([json.dumps(row.get(k), ensure_ascii=False) if isinstance(row.get(k), (dict, list))
+                        else ("" if row.get(k) is None else row.get(k)) for k in cols])
+        output_result(buf.getvalue().rstrip("\n"), copy=args.copy)
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("json", aliases=["js"], parents=[common], help=META[3],
+                       description="Swiss army knife for JSON.", epilog=EPILOG,
+                       formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("op", choices=["fmt", "min", "get", "keys", "flat", "csv", "validate"])
+    p.add_argument("path", nargs="?", help="for 'get': a.b[0].c")
+    p.add_argument("file_pos", nargs="?", metavar="TEXT", help=argparse.SUPPRESS)
+    p.add_argument("-f", "--file", metavar="FILE", help="read JSON from a file")
+    p.add_argument("--paste", action="store_true", help="read JSON from clipboard")
+    p.add_argument("--copy", action="store_true", help="copy result to clipboard")
+    p.add_argument("--indent", type=int, default=2)
+    p.add_argument("--sort", action="store_true", help="sort keys")
+    p.set_defaults(func=_dispatch)
+
+
+def _dispatch(args) -> int:
+    import os
+    if args.file_pos and not args.file and os.path.isfile(args.file_pos):
+        args.file, args.file_pos = args.file_pos, None
+    # 'fmt data.json' style: positional after op is the file for every op except 'get'.
+    if args.op != "get":
+        if args.path and not args.file:
+            args.file = args.path
+        args.path = None
+    elif not args.path:
+        raise DktError("'get' needs a path, e.g. dkt js get users[0].name -f data.json")
+    return run(args)

devkittools/tools/net.py

@@ -0,0 +1,114 @@
+"""dkt net - IP addresses, DNS lookups and TCP reachability checks."""
+from __future__ import annotations
+
+import argparse
+import socket
+import time
+import urllib.request
+
+from ..utils import DktError, c, fail, kv, ok, sym, table
+
+META = ("Servers & Network", "net", "", "ip addresses, DNS lookup, is-this-port-open checks")
+
+EPILOG = """\
+examples:
+  dkt net ip                  local IPs
+  dkt net ip --public         also your public IP (asks api.ipify.org)
+  dkt net dns github.com
+  dkt net check github.com:443 localhost:5432 192.168.1.10:22
+"""
+
+
+def local_ips():
+    ips = set()
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.connect(("10.255.255.255", 1))
+        ips.add(s.getsockname()[0])
+        s.close()
+    except Exception:
+        pass
+    try:
+        for info_ in socket.getaddrinfo(socket.gethostname(), None, socket.AF_INET):
+            ips.add(info_[4][0])
+    except Exception:
+        pass
+    return sorted(i for i in ips if not i.startswith("127."))
+
+
+def cmd_ip(args) -> int:
+    rows = [("hostname", socket.gethostname())]
+    for i, ip in enumerate(local_ips()):
+        rows.append(("local ip" if i == 0 else "", c(ip, "bold")))
+    if args.public:
+        try:
+            req = urllib.request.Request("https://api.ipify.org", headers={"User-Agent": "dkt"})
+            rows.append(("public ip", c(urllib.request.urlopen(req, timeout=6).read().decode().strip(), "bold bcyan")))
+        except Exception:
+            rows.append(("public ip", c("unavailable (offline?)", "red")))
+    kv(rows)
+    return 0
+
+
+def cmd_dns(args) -> int:
+    for host in args.hosts:
+        try:
+            t0 = time.perf_counter()
+            res = socket.getaddrinfo(host, None)
+            dt = (time.perf_counter() - t0) * 1000
+        except socket.gaierror as e:
+            fail("%s  %s" % (host, e))
+            continue
+        addrs = []
+        for r in res:
+            a = r[4][0]
+            if a not in addrs:
+                addrs.append(a)
+        print("%s %s %s" % (c(sym("ok"), "bgreen"), c(host, "bold"), c("(%.0f ms)" % dt, "gray")))
+        for a in addrs:
+            print("    %s %s" % (c("IPv6" if ":" in a else "IPv4", "gray"), a))
+        try:
+            print("    %s %s" % (c("rdns", "gray"), socket.gethostbyaddr(addrs[0])[0]))
+        except Exception:
+            pass
+    return 0
+
+
+def cmd_check(args) -> int:
+    rows = []
+    bad = 0
+    for target in args.targets:
+        host, _, port = target.rpartition(":")
+        if not host or not port.isdigit():
+            raise DktError("Use host:port, e.g. github.com:443 (got '%s')" % target)
+        t0 = time.perf_counter()
+        try:
+            with socket.create_connection((host, int(port)), timeout=args.timeout):
+                dt = (time.perf_counter() - t0) * 1000
+            rows.append((c(sym("ok"), "bgreen"), target, c("open", "green"), "%.0f ms" % dt))
+        except socket.timeout:
+            rows.append((c(sym("fail"), "bred"), target, c("timed out", "red"), ""))
+            bad += 1
+        except OSError as e:
+            rows.append((c(sym("fail"), "bred"), target, c("closed / unreachable", "red"), c(str(e.strerror or e)[:30], "gray")))
+            bad += 1
+    table(["", "TARGET", "STATUS", "LATENCY"], rows)
+    return 1 if bad else 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("net", parents=[common], help=META[3],
+                       description="Network helpers.", epilog=EPILOG,
+                       formatter_class=argparse.RawDescriptionHelpFormatter)
+    g = p.add_subparsers(dest="sub", metavar="<ip|dns|check>")
+    p.set_defaults(func=lambda a: (p.print_help() or 0))
+    ip = g.add_parser("ip", help="show local (and public) IP addresses")
+    ip.add_argument("--public", action="store_true")
+    ip.set_defaults(func=cmd_ip)
+    dns = g.add_parser("dns", help="resolve host names")
+    dns.add_argument("hosts", nargs="+")
+    dns.set_defaults(func=cmd_dns)
+    ck = g.add_parser("check", help="test if host:port accepts TCP connections")
+    ck.add_argument("targets", nargs="+", metavar="HOST:PORT")
+    ck.add_argument("--timeout", type=float, default=3.0)
+    ck.set_defaults(func=cmd_check)

devkittools/tools/portkiller.py

@@ -0,0 +1,246 @@
+"""dkt portkiller (pk) - see what is using a port and optionally kill it."""
+from __future__ import annotations
+
+import argparse
+import csv
+import os
+import re
+import shutil
+import signal
+import time
+from typing import Dict, List, Optional, Tuple
+
+from ..utils import DktError, c, info, print_table, run_capture, str2bool
+
+PROTECTED_PIDS = {0, 4}
+
+EPILOG = """\
+examples:
+  dkt pk                       list everything that is listening
+  dkt pk --show 3000           who is using port 3000?
+  dkt pk --show 3000 --kill true   ...and kill it
+  dkt pk --show 3000 8080 --kill   several ports at once
+"""
+
+
+# ------------------------------------------------------------ listing
+
+def _windows_names() -> Dict[int, str]:
+    names = {}  # type: Dict[int, str]
+    _, out, _ = run_capture(["tasklist", "/FO", "CSV", "/NH"])
+    for row in csv.reader(out.splitlines()):
+        if len(row) >= 2 and row[1].isdigit():
+            names[int(row[1])] = row[0]
+    return names
+
+
+def _listeners_windows() -> List[dict]:
+    code, out, err = run_capture(["netstat", "-ano"])
+    if code != 0:
+        raise DktError("netstat failed: %s" % err.strip())
+    names = _windows_names()
+    entries = []
+    for line in out.splitlines():
+        parts = line.split()
+        if len(parts) < 5 or parts[0].upper() != "TCP" or parts[3].upper() != "LISTENING":
+            continue
+        local, pid_s = parts[1], parts[4]
+        addr, _, port_s = local.rpartition(":")
+        if not port_s.isdigit() or not pid_s.isdigit():
+            continue
+        pid = int(pid_s)
+        entries.append({"port": int(port_s), "address": addr, "pid": pid, "name": names.get(pid, "?")})
+    return entries
+
+
+def _listeners_posix() -> List[dict]:
+    entries = []
+    if shutil.which("ss"):
+        _, out, _ = run_capture(["ss", "-ltnp"])
+        for line in out.splitlines():
+            parts = line.split()
+            if len(parts) < 4 or parts[0] == "State":
+                continue
+            local = parts[3]
+            addr, _, port_s = local.rpartition(":")
+            if not port_s.isdigit():
+                continue
+            m = re.search(r'\("([^"]*)",pid=(\d+)', line)
+            entries.append({"port": int(port_s), "address": addr,
+                            "pid": int(m.group(2)) if m else None,
+                            "name": m.group(1) if m else "? (try sudo)"})
+        return entries
+    if shutil.which("lsof"):
+        _, out, _ = run_capture(["lsof", "-nP", "-iTCP", "-sTCP:LISTEN"])
+        for line in out.splitlines()[1:]:
+            parts = line.split()
+            if len(parts) < 9:
+                continue
+            addr, _, port_s = parts[8].rpartition(":")
+            if not port_s.isdigit() or not parts[1].isdigit():
+                continue
+            entries.append({"port": int(port_s), "address": addr, "pid": int(parts[1]), "name": parts[0]})
+        return entries
+    if os.path.exists("/proc/net/tcp"):
+        return _listeners_proc()
+    raise DktError("Neither 'ss' nor 'lsof' is available on this system.")
+
+
+def _listeners_proc() -> List[dict]:
+    """Fallback for minimal Linux systems: read /proc directly."""
+    sockets = {}  # inode -> (port, address)
+    for fname in ("/proc/net/tcp", "/proc/net/tcp6"):
+        try:
+            with open(fname) as f:
+                next(f, None)
+                for line in f:
+                    parts = line.split()
+                    if len(parts) < 10 or parts[3] != "0A":  # 0A = LISTEN
+                        continue
+                    addr_hex, port_hex = parts[1].rsplit(":", 1)
+                    sockets[parts[9]] = (int(port_hex, 16), addr_hex)
+        except OSError:
+            continue
+    owners = {}  # inode -> pid
+    for pid_s in os.listdir("/proc"):
+        if not pid_s.isdigit():
+            continue
+        fd_dir = "/proc/%s/fd" % pid_s
+        try:
+            for fd in os.listdir(fd_dir):
+                target = os.readlink("%s/%s" % (fd_dir, fd))
+                if target.startswith("socket:["):
+                    inode = target[8:-1]
+                    if inode in sockets:
+                        owners[inode] = int(pid_s)
+        except OSError:
+            continue
+    entries = []
+    for inode, (port, addr_hex) in sockets.items():
+        pid = owners.get(inode)
+        name = "? (try sudo)"
+        if pid is not None:
+            try:
+                with open("/proc/%d/comm" % pid) as f:
+                    name = f.read().strip()
+            except OSError:
+                name = "?"
+        address = "::" if len(addr_hex) > 8 else ("0.0.0.0" if int(addr_hex, 16) == 0 else "127.0.0.1")
+        entries.append({"port": port, "address": address, "pid": pid, "name": name})
+    return entries
+
+
+def get_listeners() -> List[dict]:
+    raw = _listeners_windows() if os.name == "nt" else _listeners_posix()
+    seen = set()
+    unique = []
+    for e in sorted(raw, key=lambda e: (e["port"], e["pid"] or 0, e["address"])):
+        key = (e["port"], e["pid"], e["address"])
+        if key not in seen:
+            seen.add(key)
+            unique.append(e)
+    return unique
+
+
+# ------------------------------------------------------------ killing
+
+def _alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def kill_pid(pid: int) -> Tuple[bool, str]:
+    if pid in PROTECTED_PIDS or pid == os.getpid():
+        return False, "refusing to kill a protected system process"
+    if os.name == "nt":
+        code, out, err = run_capture(["taskkill", "/PID", str(pid), "/F", "/T"])
+        if code == 0:
+            return True, "killed"
+        msg = (err or out).strip().splitlines()
+        text = msg[0] if msg else "taskkill failed"
+        if "denied" in text.lower():
+            text += " (try an Administrator PowerShell)"
+        return False, text
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return True, "already gone"
+    except PermissionError:
+        return False, "permission denied (try sudo)"
+    for _ in range(20):
+        time.sleep(0.1)
+        if not _alive(pid):
+            return True, "killed"
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except (ProcessLookupError, PermissionError) as e:
+        return False, str(e)
+    return True, "killed (SIGKILL)"
+
+
+# ------------------------------------------------------------ command
+
+def run(args: argparse.Namespace) -> int:
+    kill = str2bool(args.kill)
+    listeners = get_listeners()
+
+    if args.show is None:
+        if kill:
+            raise DktError("--kill needs a port: dkt pk --show 3000 --kill true")
+        if not listeners:
+            print("Nothing is listening on any TCP port.")
+            return 0
+        print(c("Listening TCP ports", "bold"))
+        print_table(["PORT", "PID", "PROCESS", "ADDRESS"],
+                    [(e["port"], e["pid"] if e["pid"] is not None else "-", e["name"], e["address"])
+                     for e in listeners])
+        info("\nTip: dkt pk --show <port> --kill true")
+        return 0
+
+    for port in args.show:
+        if not 1 <= port <= 65535:
+            raise DktError("Invalid port: %d (must be 1-65535)" % port)
+
+    for port in args.show:
+        matches = [e for e in listeners if e["port"] == port]
+        if not matches:
+            print("Port %d: %s" % (port, c("free - nothing is listening", "green")))
+            continue
+        print("Port %d: %s" % (port, c("in use", "yellow")))
+        print_table(["PID", "PROCESS", "ADDRESS"],
+                    [(e["pid"] if e["pid"] is not None else "-", e["name"], e["address"]) for e in matches])
+        if not kill:
+            info("  (add --kill true to stop it)")
+            continue
+        pids = sorted({e["pid"] for e in matches if e["pid"] is not None})
+        if not pids:
+            print(c("  Can't see the owning process - try running with sudo/Administrator.", "red"))
+            continue
+        for pid in pids:
+            name = next((e["name"] for e in matches if e["pid"] == pid), "?")
+            ok, msg = kill_pid(pid)
+            mark = c("✔", "green") if ok else c("✘", "red")
+            print("  %s PID %d (%s): %s" % (mark, pid, name, msg))
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser(
+        "portkiller", aliases=["pk"], parents=[common],
+        help="see what is using a port, optionally kill it",
+        description="Show which process is listening on a TCP port and optionally kill it.\n"
+                    "With no options, lists every listening port.",
+        epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("-s", "--show", nargs="+", type=int, metavar="PORT",
+                   help="port(s) to inspect")
+    p.add_argument("-k", "--kill", nargs="?", const="true", default="false", metavar="true|false",
+                   help="kill the process(es) using the port (use with --show)")
+    p.set_defaults(func=run)
+
+
+META = ("Servers & Network", "portkiller", "pk", "see what's using a port, kill it")

devkittools/tools/regextool.py

@@ -0,0 +1,84 @@
+"""dkt regex (rx) - test a regular expression against text or a file with highlighted matches."""
+from __future__ import annotations
+
+import argparse
+import re
+
+from ..utils import DktError, c, color_enabled, kv, read_input, warn
+
+META = ("Data & Text", "regex", "rx", "test regexes with highlighted matches, groups, replace")
+
+EPILOG = """\
+examples:
+  dkt rx "\\d{3}-\\d{4}" "call 555-1234 now"
+  dkt rx "(?P<user>\\w+)@(?P<host>[\\w.]+)" -f contacts.txt
+  dkt rx "foo" "foo Foo FOO" -i
+  dkt rx "(\\w+) (\\w+)" "hello world" --replace "\\2 \\1"
+"""
+
+
+def highlight(text: str, matches) -> str:
+    if not color_enabled():
+        return text
+    out, last = [], 0
+    for m in matches:
+        if m.end() == m.start():
+            continue
+        out.append(text[last:m.start()])
+        out.append(c(text[m.start():m.end()], "reverse bgreen"))
+        last = m.end()
+    out.append(text[last:])
+    return "".join(out)
+
+
+def run(args) -> int:
+    flags = 0
+    if args.i:
+        flags |= re.I
+    if args.m:
+        flags |= re.M
+    if args.s:
+        flags |= re.S
+    try:
+        rx = re.compile(args.pattern, flags)
+    except re.error as e:
+        raise DktError("Invalid regex: %s" % e)
+    text = read_input(args.text, args.file, False, "text")
+    matches = list(rx.finditer(text))
+    if args.replace is not None:
+        try:
+            print(rx.sub(args.replace, text))
+        except (re.error, IndexError) as e:
+            raise DktError("Bad replacement: %s" % e)
+        return 0
+    if not matches:
+        warn("no matches")
+        return 1
+    print(highlight(text.rstrip("\n"), matches))
+    print()
+    print("  %s match%s" % (c(len(matches), "bold bgreen"), "" if len(matches) == 1 else "es"))
+    for n, m in enumerate(matches[:args.limit], 1):
+        loc = c("@%d-%d" % (m.start(), m.end()), "gray")
+        print("  %s %s %s" % (c("#%d" % n, "bcyan"), repr(m.group(0)), loc))
+        if m.groups():
+            names = {v: k for k, v in rx.groupindex.items()}
+            for gi, val in enumerate(m.groups(), 1):
+                print("      %s %s" % (c("$%s" % names.get(gi, gi), "bmagenta"), repr(val)))
+    if len(matches) > args.limit:
+        print(c("  ... %d more (use --limit)" % (len(matches) - args.limit), "gray"))
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("regex", aliases=["rx"], parents=[common], help=META[3],
+                       description="Test a Python regular expression.", epilog=EPILOG,
+                       formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("pattern")
+    p.add_argument("text", nargs="?", help="text to test (or -f FILE / pipe stdin)")
+    p.add_argument("-f", "--file", metavar="FILE")
+    p.add_argument("-i", action="store_true", help="ignore case")
+    p.add_argument("-m", action="store_true", help="multiline (^ $ per line)")
+    p.add_argument("-s", action="store_true", help="dot matches newline")
+    p.add_argument("--replace", metavar="REPL", help="show the result of re.sub instead")
+    p.add_argument("--limit", type=int, default=20, help="max matches to detail (default 20)")
+    p.set_defaults(func=run)