Add "should_emit_codes" check (#46)

.circleci/config.yml

@@ -27,6 +27,9 @@ jobs:
       - codecov/upload:
           file: coverage.xml
       - run: pipenv run ./build.sh
+      - run: pip install naughtty
+      - run: pip install dist/*
+      - run: ./test-cli.sh
       - run: if [[ -z "${CIRCLE_TAG}" ]]; then circleci-agent step halt; fi
       - run: pipenv run twine upload dist/*
 

.vscode/settings.json

@@ -5,6 +5,7 @@
     "CMYB",
     "dinject",
     "epilog",
+    "fstat",
     "naughtty",
     "RGBA",
     "Strikethrough"

README.md

@@ -32,7 +32,7 @@ ls --color | ansiscape
 <!--dinject as=markdown host=shell range=start-->
 
 ```text
-[{"background": -1, "foreground": 4, "weight": 1},"ansiscape",{"background": -1},"\n",{"foreground": 4, "weight": 1},"ansiscape.egg-info",{"background": -1},"\n",{"foreground": 2, "weight": 1},"build.sh",{"background": -1},"\ncoverage.xml\n",{"foreground": 4, "weight": 1},"dist",{"background": -1},"\n",{"foreground": 4, "weight": 1},"docs",{"background": -1},"\n",{"foreground": 4, "weight": 1},"htmlcov",{"background": -1},"\nLICENSE\n",{"foreground": 2, "weight": 1},"lint.sh",{"background": -1},"\nMANIFEST.in\nmkdocs.yml\nmypy.ini\nPipfile\nPipfile.lock\npyproject.toml\nREADME.md\nsetup.py\n",{"foreground": 4, "weight": 1},"tests",{"background": -1},"\n",{"foreground": 2, "weight": 1},"test.sh",{"background": -1}]
+[{"background": -1, "foreground": 4, "weight": 1},"ansiscape",{"background": -1},"\n",{"foreground": 4, "weight": 1},"ansiscape.egg-info",{"background": -1},"\n",{"foreground": 2, "weight": 1},"build.sh",{"background": -1},"\ncoverage.xml\n",{"foreground": 4, "weight": 1},"dist",{"background": -1},"\n",{"foreground": 4, "weight": 1},"docs",{"background": -1},"\n",{"foreground": 4, "weight": 1},"htmlcov",{"background": -1},"\nLICENSE\n",{"foreground": 2, "weight": 1},"lint.sh",{"background": -1},"\nMANIFEST.in\nmkdocs.yml\nmypy.ini\nPipfile\nPipfile.lock\npyproject.toml\nREADME.md\nsetup.py\n",{"foreground": 2, "weight": 1},"test-cli.sh",{"background": -1},"\n",{"foreground": 4, "weight": 1},"tests",{"background": -1},"\n",{"foreground": 2, "weight": 1},"test.sh",{"background": -1}]
 ```
 
 <!--dinject range=end-->

ansiscape/__main__.py

@@ -3,6 +3,7 @@
 from typing import List, TextIO
 
 from ansiscape import Sequence, get_version
+from ansiscape.checks import should_emit_codes
 from ansiscape.example import make_example
 
 
@@ -25,11 +26,24 @@ def cli_entry(
         epilog="Made with love by Cariad Eccleston: https://github.com/cariad/ansiscape",
     )
 
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="checks if codes should be emitted",
+    )
+
     parser.add_argument("--example", action="store_true", help="print an example")
     parser.add_argument("--version", action="store_true", help="print the version")
 
     args = parser.parse_args(cli_args[1:])
 
+    if args.check:
+        if should_emit_codes():
+            out_pipe.write("yes\n")
+        else:
+            out_pipe.write("no\n")
+        return
+
     if args.example:
         out_pipe.write(str(make_example()))
         return

ansiscape/checks.py

@@ -0,0 +1,7 @@
+from os import fstat
+
+
+def should_emit_codes() -> bool:
+    """Returns `True` if ANSI escape codes should be emitted."""
+
+    return fstat(0) == fstat(1)

docs/checks.md

@@ -0,0 +1,5 @@
+# Checks
+
+`ansiscape.checks` contains functions to check the state of your application.
+
+`should_emit_codes()` returns `True` if ANSI escape codes should be emitted. It'll return `False`, for example, if the script appears to be running non-interactively.

docs/cli.md

@@ -44,7 +44,7 @@ ls --color | ansiscape
 <!--dinject as=markdown host=shell range=start-->
 
 ```text
-[{"background": -1, "foreground": 4, "weight": 1},"ansiscape",{"background": -1},"\n",{"foreground": 4, "weight": 1},"ansiscape.egg-info",{"background": -1},"\n",{"foreground": 2, "weight": 1},"build.sh",{"background": -1},"\ncoverage.xml\n",{"foreground": 4, "weight": 1},"dist",{"background": -1},"\n",{"foreground": 4, "weight": 1},"docs",{"background": -1},"\n",{"foreground": 4, "weight": 1},"htmlcov",{"background": -1},"\nLICENSE\n",{"foreground": 2, "weight": 1},"lint.sh",{"background": -1},"\nMANIFEST.in\nmkdocs.yml\nmypy.ini\nPipfile\nPipfile.lock\npyproject.toml\nREADME.md\nsetup.py\n",{"foreground": 4, "weight": 1},"tests",{"background": -1},"\n",{"foreground": 2, "weight": 1},"test.sh",{"background": -1}]
+[{"background": -1, "foreground": 4, "weight": 1},"ansiscape",{"background": -1},"\n",{"foreground": 4, "weight": 1},"ansiscape.egg-info",{"background": -1},"\n",{"foreground": 2, "weight": 1},"build.sh",{"background": -1},"\ncoverage.xml\n",{"foreground": 4, "weight": 1},"dist",{"background": -1},"\n",{"foreground": 4, "weight": 1},"docs",{"background": -1},"\n",{"foreground": 4, "weight": 1},"htmlcov",{"background": -1},"\nLICENSE\n",{"foreground": 2, "weight": 1},"lint.sh",{"background": -1},"\nMANIFEST.in\nmkdocs.yml\nmypy.ini\nPipfile\nPipfile.lock\npyproject.toml\nREADME.md\nsetup.py\n",{"foreground": 2, "weight": 1},"test-cli.sh",{"background": -1},"\n",{"foreground": 4, "weight": 1},"tests",{"background": -1},"\n",{"foreground": 2, "weight": 1},"test.sh",{"background": -1}]
 ```
 
 <!--dinject range=end-->

mkdocs.yml

@@ -3,6 +3,7 @@ markdown_extensions:
 nav:
   - index.md
   - cli.md
+  - checks.md
   - make.md
   - read.md
   - interpretation.md

test-cli.sh

@@ -0,0 +1,16 @@
+#!/bin/env bash
+
+set -euo pipefail
+
+assert() {
+  if [[ "${1}" == "${2}" ]]; then
+    return
+  fi
+
+  echo "Expected \"${2}\" but got \"${1}\" 🔥"
+  exit 1
+}
+
+assert "$(ansiscape --version)"        "${CIRCLE_TAG:-"-1.-1.-1"}"
+assert "$(ansiscape --check)"          "no"
+assert "$(naughtty ansiscape --check)" $'yes\r'

tests/test_checks.py

@@ -0,0 +1,5 @@
+from ansiscape.checks import should_emit_codes
+
+
+def test_should_emit_codes() -> None:
+    assert not should_emit_codes()

tests/test_main.py

@@ -3,6 +3,12 @@
 from ansiscape.__main__ import cli_entry
 
 
+def test_cli_entry__check() -> None:
+    stdout = StringIO()
+    cli_entry(cli_args=["ansiscape", "--check"], out_pipe=stdout)
+    assert stdout.getvalue() == "no\n"
+
+
 def test_cli_entry__example() -> None:
     stdout = StringIO()
     cli_entry(cli_args=["ansiscape", "--example"], out_pipe=stdout)