freyacli 0.1.0__tar.gz

freyacli-0.1.0/LICENSE.md

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2026 Diego Barquero Morera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

freyacli-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: freyacli
+Version: 0.1.0
+Summary: A CLI framework for Python
+Home-page: https://github.com/diegobarmor/freya-cli
+Author: DiegoBarMor
+Author-email: diegobarmor42@gmail.com
+License: MIT
+Keywords: cli terminal user interface
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+# FREYA CLI
+**Freya CLI** (FRamEwork for pYthon Applications) is, as the name suggests, a Python framework for building Command Line Interface (CLI) applications. It allows developers to use a set of well defined rules and specifications for the intended usage of the CLI (via the `FYR` format), while giving an intuitive idea to the users on how the app's CLI expects to receive.
+
+As a bonus, **Freya CLI** provides a simple utility for coloring any printed text, via the `freyacli.Color` class. The colors provided are black, white, red, green, blue, yellow, magenta, cyan; with their respective *bright* variations, for a total of 16 colors.
+
+## FYR / FYH format
+- `FYR` (FreYa Rules) specifies a list of **rules** that must be followed when using an application's CLI. These rules are organized inside a hierarchy structure composed of **subcommand** nodes.
+- `FYH` (FreYa Helps) should follow the same structure as its respective `FYR`. Instead of specifying the CLI rules, it stores the help strings that will be displayed whenever an incorrect use of the CLI is detected.
+
+Below is an explanation of the argument **rules** and the **subcommand** nodes.
+
+### Argument Rules
+Argument rules specify how the arguments should be passed to the CLI, and are specified in the `FYR` format. The simplest rule has the form:
+```
+name[]1.STR
+```
+where `name` is both the name that will be used to fetch the user values, and the name displayed in the automatic help string. The empty brackets represent that this argument is **positional** (e.g. like how the argument is passed to the command `cat README.md`). The expected type is passed after a `.`, in this case `STR` (`1` indicates that one value is expected, more on that [later](#argument-count)). Supported types are:
+- `STR`: string
+- `PATH`: Python `Path` instance
+- `INT`: integer
+- `FLOAT`: float
+
+
+If the argument is intended to be a simple on/off flag instead (e.g. `-a` in `ls -a`), it would instead look like
+```
+name[a,all]
+```
+
+This means that the flag `name` can be toggled on by passing either the flag `-a` (short name) or `--all` (long name). Short names can only be 1-character long; numbers are currently not allowed. If only a short name is to be defined, you can write it as `[a,]`; if only a long name is needed instead, it can be written as `[,all]`.
+
+Naturally, toggle flags should be optional by nature. To indicate that an argument is **optional**, a `~``char should be placed in front of the name. This applies to any kind of argument, be it positional or flags. So the previous example would be:
+
+```
+~name[a,all]
+```
+
+Flags can also have a value attached to them. It will look similar to the positional argument syntax, with the added short/long flag names inside the brackets, e.g.:
+```
+~path_file[i,input]1.PATH
+```
+
+Finally, default values can be specified inside the `FYR` too. These will be assigned to optional arguments that the user didn't specify. It uses a `=` at the end of the rule (limitation: spaces are not allowed inside default values), e.g.:
+```
+~path_file[i,input]1.PATH=README.md
+```
+
+#### Argument Count
+...
+
+### Subcommands
+...
+
+### Macros
+...
+
+### Help String
+...
+
+## Current limitations (TODO)
+- Default values shouldn't have spaces or newlines inside
+- Flag --help/-h is currently reserved.
+- Positional arguments / options (flags) aren't currently supported for non-leaf **subcommand** nodes.
+- Execution of the app must currently happen at a leaf **subcommand** node.
+- Short flag names should not be a digit. Otherwise the parser will confuse it as a float value (e.g. `-3`).

freyacli-0.1.0/README.md

@@ -0,0 +1,64 @@
+# FREYA CLI
+**Freya CLI** (FRamEwork for pYthon Applications) is, as the name suggests, a Python framework for building Command Line Interface (CLI) applications. It allows developers to use a set of well defined rules and specifications for the intended usage of the CLI (via the `FYR` format), while giving an intuitive idea to the users on how the app's CLI expects to receive.
+
+As a bonus, **Freya CLI** provides a simple utility for coloring any printed text, via the `freyacli.Color` class. The colors provided are black, white, red, green, blue, yellow, magenta, cyan; with their respective *bright* variations, for a total of 16 colors.
+
+## FYR / FYH format
+- `FYR` (FreYa Rules) specifies a list of **rules** that must be followed when using an application's CLI. These rules are organized inside a hierarchy structure composed of **subcommand** nodes.
+- `FYH` (FreYa Helps) should follow the same structure as its respective `FYR`. Instead of specifying the CLI rules, it stores the help strings that will be displayed whenever an incorrect use of the CLI is detected.
+
+Below is an explanation of the argument **rules** and the **subcommand** nodes.
+
+### Argument Rules
+Argument rules specify how the arguments should be passed to the CLI, and are specified in the `FYR` format. The simplest rule has the form:
+```
+name[]1.STR
+```
+where `name` is both the name that will be used to fetch the user values, and the name displayed in the automatic help string. The empty brackets represent that this argument is **positional** (e.g. like how the argument is passed to the command `cat README.md`). The expected type is passed after a `.`, in this case `STR` (`1` indicates that one value is expected, more on that [later](#argument-count)). Supported types are:
+- `STR`: string
+- `PATH`: Python `Path` instance
+- `INT`: integer
+- `FLOAT`: float
+
+
+If the argument is intended to be a simple on/off flag instead (e.g. `-a` in `ls -a`), it would instead look like
+```
+name[a,all]
+```
+
+This means that the flag `name` can be toggled on by passing either the flag `-a` (short name) or `--all` (long name). Short names can only be 1-character long; numbers are currently not allowed. If only a short name is to be defined, you can write it as `[a,]`; if only a long name is needed instead, it can be written as `[,all]`.
+
+Naturally, toggle flags should be optional by nature. To indicate that an argument is **optional**, a `~``char should be placed in front of the name. This applies to any kind of argument, be it positional or flags. So the previous example would be:
+
+```
+~name[a,all]
+```
+
+Flags can also have a value attached to them. It will look similar to the positional argument syntax, with the added short/long flag names inside the brackets, e.g.:
+```
+~path_file[i,input]1.PATH
+```
+
+Finally, default values can be specified inside the `FYR` too. These will be assigned to optional arguments that the user didn't specify. It uses a `=` at the end of the rule (limitation: spaces are not allowed inside default values), e.g.:
+```
+~path_file[i,input]1.PATH=README.md
+```
+
+#### Argument Count
+...
+
+### Subcommands
+...
+
+### Macros
+...
+
+### Help String
+...
+
+## Current limitations (TODO)
+- Default values shouldn't have spaces or newlines inside
+- Flag --help/-h is currently reserved.
+- Positional arguments / options (flags) aren't currently supported for non-leaf **subcommand** nodes.
+- Execution of the app must currently happen at a leaf **subcommand** node.
+- Short flag names should not be a digit. Otherwise the parser will confuse it as a float value (e.g. `-3`).

freyacli-0.1.0/freyacli/__init__.py

@@ -0,0 +1,18 @@
+from ._misc.freya_syntax_error import FreyaSyntaxError
+from ._misc.arg_dtype_error import ArgDTypeError
+from ._misc.help_str import HelpStr
+
+from ._utils.color import Color
+from ._utils.path_assertion import PathAssertion
+
+from ._arguments.arg_count import ArgCount
+from ._arguments.arg_dtype import ArgDType
+from ._arguments.argument_rule import ArgumentRule
+from ._arguments.subcommand import Subcommand
+
+from ._parsers.freya_parser import FreyaParser
+from ._parsers.args_parser import ArgsParser
+
+from ._core.app import App
+
+WIDTH_TERMINAL: int = 1 # automatically set to the current terminal width when App is initialized

freyacli-0.1.0/freyacli/_arguments/arg_count.py

@@ -0,0 +1,118 @@
+import freyacli as fy
+
+# //////////////////////////////////////////////////////////////////////////////
+class ArgCount:
+    """
+    `FYR` syntax follows a similarity to regex conventions for specifying amount of expected arguments.
+
+    - `n` -> exactly n
+        - `min_nvalues = n`, `val_optional = False`, `unlimited = False`
+        - `FYR` example: `~sphere[s,sphere]4.FLOAT`
+            - this means that `-s` must be passed with exactly `4` float values.
+        - Automatic help string:
+            - n = 1: `<value>`
+            - n > 1: `<value(n)>`
+
+    - `n?` -> 0 or n
+        - `min_nvalues = n`, `val_optional = True`, `unlimited = False`
+        - `FYR` example: `~out_mrc[m,mrc]1?.PATH`
+            - this means `-m` can be passed with exactly `1` value or without a value.
+        - Automatic help string:
+            - n = 1: `[<value>]`
+            - n > 1: `[<value(n)>]`
+
+    - `*` -> 0 or more
+        - `min_nvalues = 0`, `val_optional = True`, `unlimited = True`
+        - `FYR` example: `~configs[c,config]*.STR`
+            - this means that `-c` can be passed with or without values. Amount of values is arbitrary.
+        - Automatic help string: `[<value...>]`
+
+    - `n+` -> n or more
+        - `min_nvalues = n`, `val_optional = False`, `unlimited = True`
+        - `FYR` example: `~resids[i,resids]1+.STR`
+            - this means that `-i` must be passed with *at least* `1` value.
+        - Automatic help string:
+            - n = 1: `<value...>`
+            - n > 1: `<value(n)[...]>`
+    """
+
+    # --------------------------------------------------------------------------
+    def __init__(self, min_nvalues: int = 0, val_optional: bool = False, unlimited: bool = False):
+        self.min_nvalues  = min_nvalues  # 0 for *, n otherwise
+        self.val_optional = val_optional # True for n? and *, False for n and n+
+        self.unlimited    = unlimited    # True for * and n+, False for n and n?
+
+
+    # --------------------------------------------------------------------------
+    @classmethod
+    def from_str(cls, string: str) -> "ArgCount":
+        def _safe_substr(s: str) -> str:
+            substr = s[:-1]
+            if not substr: raise fy.FreyaSyntaxError(
+                f"Invalid argument count specification: '{s}'."+\
+                "Expected format examples: '3', '3?', '*', '3+'."+\
+                "Number is mandatory for all formats except '*', which always means '0 or more'."
+            )
+            return substr
+
+        def _safe_int(s: str) -> int:
+            try: return int(s)
+            except ValueError: raise fy.FreyaSyntaxError(
+                f"Invalid number in argument count specification: '{s}'."+\
+                "Expected format examples: '3', '3?', '*', '3+'."+\
+                "Number is mandatory for all formats except '*', which always means '0 or more'."
+            )
+
+        if string.endswith("?"): return cls(
+            min_nvalues = _safe_int(_safe_substr(string)),
+            unlimited = False,
+            val_optional = True
+        )
+        if string.endswith("*"): return cls(
+            min_nvalues = 0,
+            unlimited = True,
+            val_optional = True
+        )
+        if string.endswith("+"): return cls(
+            min_nvalues = _safe_int(_safe_substr(string)),
+            unlimited = True,
+            val_optional = False
+        )
+        return cls(
+            min_nvalues = _safe_int(string),
+            unlimited = False,
+            val_optional = False
+        )
+
+
+    # --------------------------------------------------------------------------
+    def get_help_str(self, buffer: str) -> str:
+        if self.val_optional:
+            if self.unlimited: return f"[<{buffer}...>]"     # * case
+            if self.min_nvalues == 1: return f"[<{buffer}>]" # n? case with n=1
+            return f"[<{buffer}({self.min_nvalues})>]"       # n? case with n>1
+
+        if self.unlimited:
+            if self.min_nvalues == 1: return f"<{buffer}...>" # n+ case with n=1
+            return f"<{buffer}({self.min_nvalues})[...]>"     # n+ case with n>1
+
+        if self.min_nvalues == 1: return f"<{buffer}>" # n case with n=1
+        return f"<{buffer}({self.min_nvalues})>"       # n case with n>1
+
+
+    # --------------------------------------------------------------------------
+    def is_full(self, nvalues: int) -> bool:
+        """Returns `True` for an argument that shouldn't take more values."""
+        if self.unlimited: return False
+        return nvalues >= self.min_nvalues
+
+
+    # --------------------------------------------------------------------------
+    def has_enough_values(self, nvalues: int) -> bool:
+        """Returns `True` for an argument that has already received enough values."""
+        if self.val_optional: return True
+        if self.unlimited: return nvalues >= self.min_nvalues
+        return nvalues == self.min_nvalues
+
+
+# //////////////////////////////////////////////////////////////////////////////

freyacli-0.1.0/freyacli/_arguments/arg_dtype.py

@@ -0,0 +1,61 @@
+from enum import Enum, auto
+from pathlib import Path
+
+import freyacli as fy
+
+# //////////////////////////////////////////////////////////////////////////////
+class ArgDType(Enum):
+    NONE   = auto()
+    TOGGLE = auto()
+    STR    = auto()
+    PATH   = auto()
+    INT    = auto()
+    FLOAT  = auto()
+
+    # --------------------------------------------------------------------------
+    @classmethod
+    def from_str(cls, s: str | None) -> "ArgDType":
+        if s is None: return cls.NONE
+        s = s.lower()
+        if not s:        return cls.TOGGLE
+        if s == "str":   return cls.STR
+        if s == "path":  return cls.PATH
+        if s == "float": return cls.FLOAT
+        if s == "int":   return cls.INT
+        raise fy.FreyaSyntaxError(f"Invalid flag type specified: '{s}'")
+
+
+    # --------------------------------------------------------------------------
+    def stores_data(self) -> bool:
+        return self != ArgDType.NONE and self != ArgDType.TOGGLE
+
+    # --------------------------------------------------------------------------
+    def parse_value(self, arg_name: str, raw_value: str) -> fy.ArgDTypeError |\
+        bool|str|Path|int|float:
+
+        if self == ArgDType.NONE:
+            raise fy.FreyaSyntaxError(f"Argument doesn't accept any values, but somehow got '{raw_value}'.")
+
+        if self == ArgDType.TOGGLE:
+            raise fy.FreyaSyntaxError(f"Argument is a flag of type TOGGLE and doesn't accept any values, but somehow got '{raw_value}'.")
+
+        if self == ArgDType.STR:
+            return raw_value.strip('"').strip("'")
+
+        if self == ArgDType.PATH:
+            return Path(raw_value)
+
+        if self == ArgDType.INT:
+            try: return int(raw_value)
+            except ValueError: return fy.ArgDTypeError(
+                f"Argument '{arg_name}' expected an integer value, but got '{raw_value}'."
+            )
+
+        if self == ArgDType.FLOAT:
+            try: return float(raw_value)
+            except ValueError: return fy.ArgDTypeError(
+                f"Argument '{arg_name}' expected a float value, but got '{raw_value}'."
+            )
+
+
+# //////////////////////////////////////////////////////////////////////////////

freyacli-0.1.0/freyacli/_arguments/argument_rule.py

@@ -0,0 +1,217 @@
+from pathlib import Path
+
+import freyacli as fy
+
+# //////////////////////////////////////////////////////////////////////////////
+class ArgumentRule:
+    _INDENT_LONG_DESC = 8
+
+    # --------------------------------------------------------------------------
+    def __init__(self, raw_rule: str | None):
+        self._raw_rule = raw_rule
+        self.help_str: fy.HelpStr = fy.HelpStr()
+
+        self._raw_user_values: list[str] = [] # raw string values provided by the user
+        self._n_user_values: int = 0 # amount of values provided by the user so far
+        self._was_used: bool = False # True when the flag of this argument was used at least once.
+
+        self.name: str = ""               # name that will be displayed between <> (e.g. "<value>") in the help string, and used to fetch any given values
+        self.is_positional: bool = False  # True when the argument doesn't need a preceding "flag" (e.g. just "<value>" instead of "--flag <value>")
+        self.is_optional: bool = False    # display with surrounding [] in the help string (e.g. "[<value>]")
+        self.flag_short: str = ""         # must be 1 character long. It's always used with a single preceding dash (e.g. "-f")
+        self.flag_long: str = ""          # used with a double preceding dash (e.g. "--flag")
+        self.default_value: str = ""      # when a default value is present, it's placed at the beginning of the respective help string, right after the flag type (e.g. "INT (default: 0)").
+        self.arg_dtype = fy.ArgDType.NONE # placed at the beginning of the help string. TOGGLE type is used for flags with no arguments, and the respective type (e.g. STR, INT) is used for flags with arguments.
+        self.arg_count = fy.ArgCount()    # contains information about the expected number of passed values and whether they are optional.
+
+        if raw_rule is None: return
+
+        self.is_optional = raw_rule.startswith('~')
+
+        (buffer,
+            self.default_value
+        ) = self._parse_default_value(raw_rule)
+
+        (buffer,
+            self.name
+        ) = self._parse_name(buffer)
+
+        (buffer,
+            self.is_positional,
+            self.flag_short,
+            self.flag_long
+        ) = self._parse_flags(buffer)
+
+        (buffer,
+            self.arg_count
+        ) = self._parse_arg_count(buffer)
+
+        self.arg_dtype = fy.ArgDType.from_str(buffer)
+
+
+    # --------------------------------------------------------------------------
+    def register_user_value(self, value: str) -> bool:
+        """Returns `True` when the argument is "full" (i.e. won't accept any more user values)"""
+        self._raw_user_values.append(value)
+        self._n_user_values += 1
+        self.touch()
+        return self.arg_count.is_full(self._n_user_values)
+
+
+    # --------------------------------------------------------------------------
+    def touch(self):
+        """
+        Marks the argument as used even if it doesn't receive any user values.
+        Useful when dealing with flags with optional keyword arguments
+        """
+        self._was_used = True
+
+
+    # --------------------------------------------------------------------------
+    def parse_user_values(self) -> None | fy.ArgDTypeError |\
+        bool|str|Path|int|float |\
+        list[bool]|list[str]|list[Path]|list[int]|list[float]:
+        """
+        Parses the raw user values according to the argument type (e.g. `INT`, `STR`, etc.) and returns the parsed values in the respective types.
+        When the argument accepts only 1 value, the value is returned directly instead of a `list`.
+        A boolean is returned for flags of `TOGGLE` type. Alternatively, `True` can be returned when a flag is passed but its optional keyword argument isn't.
+        An `ArgDTypeError` instance is returned when parsing fails due to invalid user input.
+        `None` is returned for non-used optional arguments, be it positional or non-toggle flags (i.e. those that should receive values).
+        """
+        if self._was_used and not self.arg_count.has_enough_values(self._n_user_values):
+            s = 's' if self.arg_count.min_nvalues > 1 else ''
+            return fy.ArgDTypeError(f"Expected {self.arg_count.min_nvalues} value{s} for argument '{self.name}', but got {len(self._raw_user_values)}.")
+
+        if self.arg_dtype in (fy.ArgDType.INT, fy.ArgDType.FLOAT):
+            ### for numeric types, split the raw user values, just in case they are received as a single space-separated string
+            self._raw_user_values = [
+                v for lst in self._raw_user_values for v in lst.split()
+            ]
+
+        parsed_values = [
+            self.arg_dtype.parse_value(self.name, raw_value)
+            for raw_value in self._raw_user_values
+        ]
+
+        if not parsed_values:
+            if self._was_used: return True # used flag has value of "True"
+            if self.is_positional: return None # unused optional positional argument has value of "None"
+            if self.arg_dtype is fy.ArgDType.TOGGLE: return False # unused toggle flag has value of "False"
+            return None # unused optional flag with arguments has value of "None"
+
+        if self.arg_count.min_nvalues == 1: return parsed_values[0]
+        return parsed_values
+
+
+    # --------------------------------------------------------------------------
+    def get_usage_str_positional(self) -> str:
+        """
+        Usage string is only relevant for positionals.
+        Flag arguments are summarized as [options...] in the usage string.
+        A more detailed description of them is provided in the longer help string.
+        """
+        if not self.is_positional:
+            raise fy.FreyaSyntaxError(f"Usage string can only be generated for positional arguments, but got a flag argument ('{self._raw_rule}').")
+
+        buffer = self.arg_count.get_help_str(self.name)
+        return fy.Color.blue(buffer)
+
+
+    # --------------------------------------------------------------------------
+    def get_help_string_description(self) -> str:
+        preffix = ""
+        if self.is_optional: preffix += "[optional] "
+        if self.arg_dtype.stores_data():
+            preffix += self.arg_dtype.name
+            if self.default_value: preffix += f" (default: {self.default_value})"
+            preffix += ". "
+
+        arg_desc = self._get_arg_description()
+        long_desc = self.help_str.wrapped_text(
+            indent = self._INDENT_LONG_DESC,
+            width = fy.WIDTH_TERMINAL - self._INDENT_LONG_DESC,
+            preffix = fy.Color.yellow(preffix)
+        )
+        return f"{arg_desc}\n{self._INDENT_LONG_DESC*' '}{long_desc}"
+
+
+    # --------------------------------------------------------------------------
+    def _parse_default_value(self, buffer: str) -> tuple[str, str]:
+        idx = buffer.find('=')
+        if idx == -1: return buffer, ''
+        return buffer[:idx], buffer[idx+1:]
+
+
+    # --------------------------------------------------------------------------
+    def _parse_name(self, buffer: str) -> tuple[str, str]:
+        name, buffer = self._safe_split_into_2(buffer, '[')
+        return buffer, name[int(self.is_optional):]
+
+
+    # --------------------------------------------------------------------------
+    def _parse_flags(self, buffer: str) -> tuple[str, bool, str, str]:
+        flags, buffer = self._safe_split_into_2(buffer, ']')
+        if not flags: return buffer, True, '', ''
+
+        flag_short, flag_long = self._safe_split_into_2(flags, ',')
+        if len(flag_short) > 1:
+            raise fy.FreyaSyntaxError(f"Short flags should be 1 character long, but got '{self.flag_short}'.")
+
+        return buffer, False, flag_short, flag_long
+
+
+    # --------------------------------------------------------------------------
+    def _parse_arg_count(self, buffer: str) -> fy.ArgCount:
+        if not buffer:
+            if self.default_value:
+                raise fy.FreyaSyntaxError(f"Flags with no arguments can't have a default value ('{self._raw_rule}')")
+            if self.is_positional:
+                raise fy.FreyaSyntaxError(f"Positional arguments must specify type and number of arguments ('{self._raw_rule}')")
+
+            return "", fy.ArgCount()
+
+        min_nvalues, buffer = self._safe_split_into_2(buffer, '.')
+        arg_count = fy.ArgCount.from_str(min_nvalues)
+        if self.is_positional:
+            ### having a distinction between self.is_optional (e.g. "passing -x" is optional)
+            ### vs arg_count.val_optional (e.g. "passing a value for -x" is optional)
+            ### is only relevant for flags, not for positionals
+            arg_count.val_optional = self.is_optional
+
+        return buffer, arg_count
+
+
+    # --------------------------------------------------------------------------
+    def _safe_split_into_2(self, buffer: str, char_split: str) -> tuple[str, str]:
+        splitted = buffer.split(char_split)
+        if len(splitted) == 2: return splitted
+        raise fy.FreyaSyntaxError(f"Invalid substring found inside argument rule: '{self._raw_rule}'")
+
+
+    # --------------------------------------------------------------------------
+    def _get_arg_description(self) -> str:
+        buffer = self.arg_count.get_help_str(self.name)
+        if self.is_positional: return fy.Color.blue("    " + buffer)
+
+        buffer = f" {buffer}" if self.arg_dtype.stores_data() else ""
+
+        if self.is_optional:
+            str_flags_0 = "["
+            str_flags_1 = "]"
+        else:
+            str_flags_0 = ""
+            str_flags_1 = ""
+
+        flag_short = f"-{self.flag_short}" if self.flag_short else ""
+        flag_long  = f"--{self.flag_long}" if self.flag_long  else ""
+
+        str_flags_0 += (
+            f"{flag_short}, {flag_long}" if self.flag_long else flag_short
+        ) if self.flag_short else flag_long
+
+        buffer = f"    {fy.Color.green(str_flags_0)}{fy.Color.blue(buffer)}"
+        if str_flags_1: buffer += fy.Color.green(str_flags_1)
+        return buffer
+
+
+# //////////////////////////////////////////////////////////////////////////////