Style-specific API extensions

CHANGELOG.md

@@ -25,10 +25,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [lib] Image category subclasses (of `BaseImage`), `TextImage` and `GraphicsImage` ([#44]).
 - [lib] Automatic font ratio computation ([#45]).
 - [lib] `term_image.FontRatio` enumeration class ([#45]).
+- [lib] Support for style-specific parameters and format specification ([#47]).
+- [lib] Style-specific exception classes ([#47]).
 - [cli] `--style` command-line option for render style selection ([#37]).
 - [cli] `kitty` render style choice for the `--style` CL option ([#39]).
 - [cli] `--force-style` to bypass render style support checks ([#44]).
 - [cli] `--auto-font-ratio` for automatic font ratio determination ([#45]).
+- [cli] Support for style-specific options ([#47]).
 - [tui] Concurrent/Parallel frame rendering for TUI animations ([#42]).
 - [lib,cli,tui] Support for the Kitty terminal graphics protocol ([#39]).
 - [lib,cli,tui] Automatic render style selection based on the detected terminal support ([#37]).
@@ -62,6 +65,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#44]: https://github.com/AnonymouX47/term-image/pull/44
 [#45]: https://github.com/AnonymouX47/term-image/pull/45
 [#46]: https://github.com/AnonymouX47/term-image/pull/46
+[#47]: https://github.com/AnonymouX47/term-image/pull/47
 
 
 ## [0.3.1] - 2022-05-04

docs/source/library/reference/index.rst

@@ -103,7 +103,7 @@ Image Format Specification
 
 .. code-block:: none
 
-   [h_align] [width] [ . [v_align] [height] ] [ # [threshold | bgcolor] ]
+   [h_align] [width] [ . [v_align] [height] ] [ # [threshold | bgcolor] ] [ + style ]
 
 .. note::
 
@@ -150,4 +150,12 @@ Image Format Specification
   * ``bgcolor``: Hex color with which transparent background should be replaced e.g ``ffffff``, ``7faa52``.
   * If neither ``threshold`` nor ``bgcolor`` is present, but ``#`` is present, transparency is disabled (uses the image's default background color, or black if none).
 
+* ``style``: Style-specific format specification.
+
+  See each render style class for its own specification, if it defines.
+
+  ``style`` can be broken down into ``[parent] [current]``, where ``current`` is the
+  spec defined by a class and ``parent`` is the spec defined by a parent of that class.
+  ``parent`` can in turn be **recursively** broken down as such.
+
 See :ref:`Formatted rendering <formatted-render>` for examples.

term_image/cli.py

@@ -1035,6 +1035,8 @@ def check_arg(
         ),
     )
 
+    style_parsers = {}
+
     args = parser.parse_args()
     MAX_DEPTH = args.max_depth
     RECURSIVE = args.recursive
@@ -1130,6 +1132,9 @@ def check_arg(
                 )
     log(f"Using {style!r} render style", logger, direct=False)
 
+    style_parser = style_parsers.get(style)
+    style_args = vars(style_parser.parse_known_args()[0]) if style_parser else {}
+
     # Some APCs used for render style support detection get emitted on some
     # non-supporting terminal emulators
     write_tty(b"\033[1K\r")
@@ -1293,6 +1298,7 @@ def check_arg(
                         and (args.cache_all_anim or args.anim_cache)
                     ),
                     check_size=not args.oversize,
+                    **style_args,
                 )
 
             # Handles `ValueError` and `.exceptions.InvalidSizeError`

term_image/exceptions.py

@@ -29,13 +29,41 @@ class InvalidSize(InvalidSizeError):
 # Style-specific exceptions
 
 
+class BaseImageError(TermImageError):
+    """Raised for style-specific errors for subclasses of
+    :py:class:`BaseImage <term_image.image.BaseImage>` defined outside this package.
+    """
+
+
+class GraphicsImageError(TermImageError):
+    """Raised for errors specific to
+    :py:class:`GraphicsImage <term_image.image.GraphicsImage>` and style-specific
+    errors for subclasses defined outside this package.
+    """
+
+
+class TextImageError(TermImageError):
+    """Raised for errors specific to
+    :py:class:`TextImage <term_image.image.TextImage>` and style-specific
+    errors for subclasses defined outside this package.
+    """
+
+
 class BlockImageError(TermImageError):
     """Raised for errors specific to
-    :py:class:`BlockImage <term_image.image.BlockImage>`
+    :py:class:`BlockImage <term_image.image.BlockImage>` and style-specific
+    errors for subclasses defined outside this package.
     """
 
 
 class KittyImageError(TermImageError):
     """Raised for errors specific to
-    :py:class:`KittyImage <term_image.image.KittyImage>`
+    :py:class:`KittyImage <term_image.image.KittyImage>` and style-specific
+    errors for subclasses defined outside this package.
     """
+
+
+def _style_error(cls: type):
+    for cls in cls.__mro__:
+        if cls.__module__.startswith("term_image.image"):
+            return globals()[f"{cls.__name__}Error"]