AdvancedTagScript 3.2.4__py3-none-any.whl → 3.3.0__py3-none-any.whl

TagScriptEngine/__init__.py

@@ -55,6 +55,11 @@ from .block import (
     CountBlock as CountBlock,
     LengthBlock as LengthBlock,
     CooldownBlock as CooldownBlock,
+    JoinBlock as JoinBlock,
+    ListBlock as ListBlock,
+    CycleBlock as CycleBlock,
+    OrdinalBlock as OrdinalBlock,
+
 )
 from .interface import (
     Adapter as Adapter,
@@ -97,6 +102,7 @@ __all__: Tuple[str, ...] = (
     "helper_parse_if",
     "helper_parse_list_if",
     "helper_split",
+    "AllowedMentionsBlock",
     "AllBlock",
     "AnyBlock",
     "AssignmentBlock",
@@ -127,6 +133,11 @@ __all__: Tuple[str, ...] = (
     "LowerBlock",
     "CountBlock",
     "LengthBlock",
+    "JoinBlock",
+    "ListBlock",
+    "CycleBlock",
+    "OrdinalBlock",
+
     "SafeObjectAdapter",
     "StringAdapter",
     "IntAdapter",
@@ -170,7 +181,7 @@ __all__: Tuple[str, ...] = (
 )
 
 
-__version__: Final[str] = "3.2.4"
+__version__: Final[str] = "3.3.0"
 
 
 class VersionNamedTuple(NamedTuple):

TagScriptEngine/adapter/redbotadapters.py

@@ -103,7 +103,7 @@ class RedBotAdapter(SimpleAdapter["Red"]):
         Percentage of chunked guilds the bot has.
 
     .. warning::
-        Attributes denoting `(*)` can only be used by the bot owner.
+        Attributes denoting ``(*)`` can only be used by the bot owner.
     """
 
     if not _has_redbot:

TagScriptEngine/block/__init__.py

@@ -3,13 +3,12 @@ from __future__ import annotations
 from typing import Tuple
 
 # isort: off
-from .helpers import (
-    implicit_bool as implicit_bool,
-    helper_parse_if as helper_parse_if,
-    helper_parse_list_if as helper_parse_list_if,
-    helper_split as helper_split,
-    easier_helper_split as easier_helper_split,
-)
+from .helpers import (
+    implicit_bool as implicit_bool,
+    helper_parse_if as helper_parse_if,
+    helper_parse_list_if as helper_parse_list_if,
+    helper_split as helper_split,
+)
 
 # isort: on
 from .allowedmentions import (
@@ -89,14 +88,25 @@ from .count import (
     CountBlock as CountBlock,
     LengthBlock as LengthBlock,
 )
+from .joinblock import (
+    JoinBlock as JoinBlock,
+)
+from .listblock import (
+    ListBlock as ListBlock,
+)
+from .cycleblock import (
+    CycleBlock as CycleBlock,
+)
+from .ordblock import (
+    OrdinalBlock as OrdinalBlock,
+)
 
 __all__: Tuple[str, ...] = (
     "implicit_bool",
-    "helper_parse_if",
-    "helper_parse_list_if",
-    "helper_split",
-    "easier_helper_split",
-    "AllowedMentionsBlock",
+    "helper_parse_if",
+    "helper_parse_list_if",
+    "helper_split",
+    "AllowedMentionsBlock",
     "AllBlock",
     "AnyBlock",
     "AssignmentBlock",
@@ -127,4 +137,8 @@ __all__: Tuple[str, ...] = (
     "LowerBlock",
     "CountBlock",
     "LengthBlock",
+    "JoinBlock",
+    "ListBlock",
+    "CycleBlock",
+    "OrdinalBlock",
 )

TagScriptEngine/block/assign.py

@@ -12,9 +12,15 @@ __all__: Tuple[str, ...] = ("AssignmentBlock",)
 
 class AssignmentBlock(verb_required_block(False, parameter=True)):  # type: ignore
     """
-    Variables are useful for choosing a value and referencing it later in a tag.
+    Variables are useful for storing a value and referencing it later in a tag.
     Variables can be referenced using brackets as any other block.
 
+    .. note::
+        - Variables are not parsed by default. You must use the ``parse`` method to parse a variable.
+        - They are one of the most versatile and powerful features of TagScript.
+        - By default, a tag cannot store data between invocations. This is where ``variables`` come in.
+        - They are the only way to **store** data. And later **retrieve** it within the same invocation.
+
     **Usage:** ``{=(<name>):<value>}``
 
     **Aliases:** ``assign, let, var``
@@ -23,8 +29,20 @@ class AssignmentBlock(verb_required_block(False, parameter=True)):  # type: igno
 
     **Parameter:** name
 
-    **Examples:** ::
+    **Examples:**
+    
+    .. code-block:: yaml
+
+        {=(message1):Hi there! How are you?}
+        {=(message2):It's a beautiful day today!}
+        {=(message3):Did you know that TagScript is a powerful tool?}
 
+        Now, call the variables by their names:
+        {message1} # Hi there! How are you?
+        {message2} # It's a beautiful day today!
+        {message3} # Did you know that TagScript is a powerful tool?
+        
+        More example:
         {=(prefix):!}
         The prefix here is `{prefix}`.
         # The prefix here is `!`.
@@ -32,6 +50,162 @@ class AssignmentBlock(verb_required_block(False, parameter=True)):  # type: igno
         {assign(day):Monday}
         {if({day}==Wednesday):It's Wednesday my dudes!|The day is {day}.}
         # The day is Monday.
+
+    .. caution::
+        - You can name variables with **anything** ``except`` existing block names or aliases.
+        - They will ``not`` reference the value in payload, if the name is same as an existing block name or alias.
+    
+    ----
+    
+    .. important:: How Argument Parsing Works - In Detail
+
+    - A variable is essentially a string that can be treated as a sequence of elements (words, numbers, etc.) when accessed.
+      These **elements** are split using ``delimiters`` (spaces by default) and are indexed sequentially starting from ``1``.
+    - A delimiter is a sequence of one or more characters that are used to split a string into a sequence of elements.
+    - Once a variable is assigned, its value can be referenced and ``parsed`` (split and indexed)
+      to extract ``specific`` parts. Let's take a look at **how** it works.
+    - Parsing out of bounds index will return the whole string.
+    
+    ----
+    
+    .. rubric:: **Basic Argument Parsing**
+    
+    Example
+        - "Coolaid is setting up the table. So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves"
+
+    - So, our ``argument`` or ``args`` in short, would be:
+
+    .. code-block:: yaml
+
+        {=(args):Coolaid is setting up the table. So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves}
+
+    .. note:: ``args`` is just a variable name, perhaps the most common name, but you can name it anything.
+
+    - Since, the default delimiter is ``space``, so you can access the ``each element`` as follows:
+
+    .. code-block:: yaml
+
+        {args(1)}  -> Coolaid
+        {args(2)}  -> is
+        {args(3)}  -> setting
+        {args(4)}  -> up
+        {args(5)}  -> the
+        {args(6)}  -> table.
+
+        {args(31)} -> Would return the whole string since it doesn't exist (indexing 31st element is out of bounds).
+
+    - ``0`` is special and returns the ``last`` element:
+
+    .. code-block:: yaml
+
+        {args(0)}  -> gloves
+    
+    - Negative indices allow you to access elements from the end of the sequence:
+
+    .. code-block:: yaml
+
+        {args(-1)}  -> work
+        {args(-2)}  -> of
+        {args(-3)}  -> pair
+        {args(-4)}  -> a
+        {args(-5)}  -> and
+        {args(-6)}  -> level,
+
+    .. rubric:: Prefix Range Access (``+n``)
+    
+    - Prefixing an index with ``+`` returns all elements from the start up to and including that position:
+
+    .. code-block:: yaml
+
+        {args(+3)}   -> Coolaid is setting
+        {args(+7)}   -> Coolaid is setting up the table. So,
+        {args(+13)}  -> Coolaid is setting up the table. So, he grabbed - a cordless drill,
+
+    .. rubric:: Suffix Range Access (``n+``)
+
+    - Suffixing an index with ``+`` returns all elements from that position (counting from the start) to the end:
+
+    .. code-block:: yaml
+
+        {args(3+)}   -> setting up the table. So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves
+        {args(7+)}   -> So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves
+        {args(13+)}  -> drill, some screws, a spirit level, and a pair of work gloves
+
+    .. rubric:: Negative Range Access (``-n+``)
+
+    - Appending ``+`` to an negative-index returns a range — all elements from that position to the end:
+    - Negative indices are **first** resolved from the end of the sequence,
+      then range access continues forward to the end.
+
+    .. code-block:: yaml
+
+        {args(-1+)}   -> work gloves # Since {args(0)} == gloves
+        {args(-11+)}  -> drill, some screws, a spirit level, and a pair of work gloves
+
+    .. tip::
+        - ``+n``   → from start → n
+        - ``n+``   → from n → end (index resolved first)
+        - ``-n``   → nth element from end
+        - ``-n+``  → nth element from end → then forward to end (index resolved first)
+    
+    -----
+    
+    .. rubric:: **Advanced Argument Parsing**
+
+    A **custom delimiter** can be passed as the payload to change how
+    the value is split. The syntax is ``{variable(index):delimiter}``:
+
+    .. code-block:: yaml
+
+        # Using the same argument as before.
+        {=(args):Coolaid is setting up the table. So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves}
+
+        1st Example:
+        {args(1):.}  -> Coolaid is setting up the table
+        {args(2):.}  -> So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves
+        {args(3):.}  -> Would return the entire string since there is no 3rd element.
+
+        2nd Example:
+        {args(1):-}  -> Coolaid is setting up the table. So, he grabbed
+        {args(2):-}  -> a cordless drill, some screws, a spirit level, and a pair of work gloves
+
+    .. note::
+        - In the 1st example, the custom delimiter is ``.``, hence the string is split by ``.`` leaving 2 elements.
+        - In the 2nd example, the custom delimiter is ``-``, hence the string is split by ``-`` leaving 2 elements.
+        - Since in both the examples, there are ``2 elements``, so ``args(3)`` would  return the entire string.
+          Because the index ``3rd`` element is out of bounds.
+
+    .. rubric:: **Nested Variables**
+    
+    - Variables can be **nested** to perform multi-level parsing:
+
+    .. code-block:: yaml
+
+        {=(raw):A - B, C, D}
+        {=(part):{raw(2):-}} 
+        
+        # "{raw(2):-}" splits "raw" by "-" and returns the 2nd element -> "B, C, D" (1st element is "A")
+        # Therefore, "part" == "B, C, D"
+        
+        {part(1):,}  -> B
+        {part(2):,}  -> C
+
+        Another Example:
+        # What if you want to parse through the things that Coolaid grabbed?
+        # If you look closely the "-" delimiter is placed conveniently to separate the items. So, we'll use it:
+    
+        {=(args):Coolaid is setting up the table. So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves}
+        {=(items):{args(2):-}}
+        
+        # "{args(2):-}" splits "args" by "-" and returns the 2nd element -> "a cordless drill, ... and a pair of work gloves"
+        # Therefore, "items" == "a cordless drill, some screws, a spirit level, and a pair of work gloves"
+        
+        Items:
+        {items(1):,}  -> a cordless drill
+        {items(2):,}  -> some screws
+        {items(3):,}  -> a spirit level
+        {items(4):,}  -> and a pair of work gloves
+
     """
 
     ACCEPTED_NAMES: Tuple[str, ...] = ("=", "assign", "let", "var")

TagScriptEngine/block/case.py

@@ -12,7 +12,7 @@ __all__: Tuple[str, ...] = ("UpperBlock", "LowerBlock")
 class UpperBlock(Block):
     """Converts the given text to uppercase.
 
-    **Usage:**  ``{upper([text]))}``
+    **Usage:**  ``{upper([text])}``
 
     **Aliases:**  ``uppercase, upper``
 
@@ -22,10 +22,11 @@ class UpperBlock(Block):
 
     **Examples:**  ::
 
-        The text is {lower(ThIs Is A TeXt)}!
+        The text is {upper(ThIs Is A TeXt)}!
         # The text is THIS IS A TEXT!
 
-        You have entered {lower({args})}!
+        {=(args):Hello World}
+        You have entered {upper({args})}!
         # You have entered HELLO WORLD!
     """
 
@@ -52,6 +53,7 @@ class LowerBlock(Block):
         The text is {lower(ThIs Is A TeXt)}!
         # The text is this is a text!
 
+        {=(args):HELLO WORLD}
         You have entered {lower({args})}!
         # You have entered hello world!
     """

TagScriptEngine/block/command.py

@@ -114,7 +114,7 @@ class SequentialGather(Awaitable[T]):
 
     Returns
     -------
-    `List[T]`
+    ``List[T]``
         the result object.
     """
 

TagScriptEngine/block/cooldown.py

@@ -28,6 +28,9 @@ class CooldownBlock(verb_required_block(True, payload=True, parameter=True)):  #
     cooldown is exceeded. If no message is passed, the default message will be sent instead.
     The cooldown message supports 2 blocks: ``key`` and ``retry_after``.
 
+    .. note::
+        - Delimiter for the parameter (``<rate>`` and ``<per>``): ``|`` or ``~``. Where ``|`` takes priority over ``~``.
+
     **Usage:** ``{cooldown(<rate>|<per>):<key>|[message]}``
 
     **Payload:** key, message

TagScriptEngine/block/count.py

@@ -11,25 +11,35 @@ __all__: Tuple[str, ...] = ("CountBlock", "LengthBlock")
 
 class CountBlock(verb_required_block(True, payload=True)):  # type: ignore
     """
-    The count block will count how much of text is in message.
-    This is case sensitive and will include substrings, if you
-    don't provide a parameter, it will count the spaces in the
-    message.
+    The count block counts occurrences of a substring within a message.
+    The search is case sensitive and includes overlapping substrings.
+
+    A payload (the message to search in) is **required**. Optionally,
+    pass the text to search for as a parameter. If no parameter is
+    provided, the block counts the number of words in the message
+    (spaces + 1).
 
     **Usage:** ``{count([text]):<message>}``
 
     **Aliases:** ``None``
 
-    **Payload:** ``message``
+    **Payload:** ``message`` (required)
+
+    **Parameter:** ``text`` (optional, the substring to count)
 
-    **Parameter:** text
+    **Examples:** ::
 
-    .. tagscript::
         {count(Tag):TagScriptEngine}
         # 1
 
-        {count(Tag): Tag Script Engine TagScriptEngine}
+        {count(Tag):Tag Script Engine TagScriptEngine}
         # 2
+
+        {count:hello world}
+        # 2 (word count: 1 space + 1)
+
+        {count(123)}
+        # Returns {count(123)} — rejected because no payload was provided
     """
 
     ACCEPTED_NAMES: Tuple[str, ...] = ("count",)
@@ -38,28 +48,28 @@ class CountBlock(verb_required_block(True, payload=True)):  # type: ignore
         if ctx.verb.parameter:
             payload: str = cast(str, ctx.verb.payload)
             return str(payload.count(ctx.verb.parameter))
-        return str(len(cast(str, ctx.verb.payload)) + 1)
+        return str(cast(str, ctx.verb.payload).count(" ") + 1)
 
 
-class LengthBlock(verb_required_block(True, payload=True)):  # type: ignore
+class LengthBlock(verb_required_block(True, parameter=True)):  # type: ignore
     """
-    The length block will check the length of the given String.
-    If a parameter is passed in, the block will check the length
-    based on what you passed in, w for word, s for spaces.
-    If you provide an invalid parameter, the block will return -1.
+    The length block returns the character count of the given text.
 
     **Usage:** ``{length(<text>)}``
 
     **Aliases:** ``len``
 
-    **Payload:** None
+    **Payload:** ``None``
+
+    **Parameter:** ``text`` (required)
 
-    **Parameter:** ``text``
+    **Examples:** ::
 
-    .. tagscript::
+        {len(TagScriptEngine)}
+        # 15
 
-        {len("TagScriptEngine")}
-        15
+        {len(hello world)}
+        # 11
     """
 
     ACCEPTED_NAMES: Tuple[str, ...] = ("length", "len")

TagScriptEngine/block/cycleblock.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import Optional, Tuple, cast
+
+from ..interface import verb_required_block
+from ..interpreter import Context
+
+
+__all__: Tuple[str, ...] = ("CycleBlock",)
+
+
+class CycleBlock(verb_required_block(True, payload=True, parameter=True)):  # type: ignore
+    """
+    The cycle block returns the element in the payload that corresponds to the
+    index value in the parameter. If the index is out of bounds, it loops around
+    using modulo (``index % list_length``).
+
+    List and Cycle blocks are another way to parse through a list of values in
+    TagScript. They both strictly use either commas ``,`` or tildes ``~`` as the
+    delimiters for the list placed in the block's payload. Use tildes when elements
+    contain commas. These blocks only function in Tags.
+
+    Cycles use ``0`` as the index for the first element. Negative values allow
+    for backward parsing. The block will return an error message if the value in
+    the parameter is not a number.
+
+    **Usage:** ``{cycle(<index>):<elem>,<elem2>,...}``
+
+    **Aliases:** ``None``
+
+    **Payload:** list of elements (comma or tilde separated)
+
+    **Parameter:** index
+
+    **Examples:**
+    
+    .. code-block:: yaml
+
+        {cycle(1):Cake,Candy,Chips,Cookies,Donut}
+        # Candy
+
+        {cycle(13):Cake,Candy,Chips,Cookies,Donut}
+        # Cookies
+        # (The list has 5 elements. 13 modulo 5 = 3. Index 3 is "Cookies".)
+
+        {cycle(3):0,1,2}
+        # 0
+        # (3 modulo 3 = 0. Index 0 is "0".)
+
+        Negative indices:
+        {cycle(-1):Apple,Banana,Cherry}
+        # Cherry
+
+        {cycle(-69):Charlie,Aid,Bob,Dave,Eve,Phen,Steve,Tom,Wendy,Xavier}
+        # Aid
+        # (-69 modulo 10 = 1. Index 1 is "Aid".)
+
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("cycle",)
+
+    def process(self, ctx: Context) -> Optional[str]:
+        try:
+            index = int(cast(str, ctx.verb.parameter))
+        except (ValueError, TypeError):
+            return "Invalid index: parameter must be a number."
+
+        payload = cast(str, ctx.verb.payload)
+        if "~" in payload:
+            items = payload.split("~")
+        else:
+            items = payload.split(",")
+
+        return items[index % len(items)]