bTagScript 5.0.0__py3-none-any.whl

bTagScript/block/util_blocks/debug_block.py

@@ -0,0 +1,107 @@
+from typing import Optional
+
+from ...interface import Block
+from ...interpreter import Context
+
+
+class DebugBlock(Block):
+    """
+    The debug block allows you to debug your tagscript quickly and easily,
+    it will save the output to the debug_var key in the response dict.
+    Separate the variables you want to include or exclude with a comma or
+    a tilde.
+
+    If no parameters are provided in addition to no payload, all variables
+    will be included. If no parameters are provided and a payload is
+    provided, it will assume you want to include those variables.
+
+    **Usage:** ``{debug(["i", "include", "e", "exclude"]):<variables>}``
+
+    **Aliases:** ``None``
+
+    **Payload:** ``variables``
+
+    **Parameter:** ``"i", "include", "e", "exclude"``
+
+    .. note::
+
+        {debug} is the same as {debug(exclude):}
+
+        {debug:somevar~anothervar} is the same as {debug(include):somevar~anothervar}
+
+    **Examples:**
+
+    .. note::
+
+            THIS SHOULD ALWAYS BE PLACED AT THE VERY BOTTOM, IT WILL NOT RETURN ANYTHING UNDER IT.
+
+    .. tagscript::
+
+        Assuming we have the following tagscript, we first set the var something, then set
+        parsed (using the dollar sign method), to Hello|World, (assume we actually wanted just the Hello
+        but we forgot)
+
+        {=(something):Hello/World}
+        {$parsed:{something(1)}}
+        {if({parsed}==Hello):Hello|Bye}
+
+        Running this would provided the output Bye, using the debug block below:
+        {debug}
+        We'll get all the variables at their, "final state"
+        This will be provided in a dict, which you can further parse and output to your liking.
+
+        EG, in YAML format:
+        something: Hello/World
+        parsed: Hello/World
+
+        This allow's you to see that you forgot to parse with a delimiter which will lead to easy fixing.
+    """
+
+    ACCEPTED_NAMES = ("debug",)
+
+    def process(self, ctx: Context) -> Optional[str]:  # pylint: disable=too-many-branches
+        """
+        Debug the tagscript!
+        """
+        debug = {}
+
+        if ctx.verb.parameter:
+            if ctx.verb.parameter in ("e", "exc", "exclude"):
+                if ctx.verb.payload:
+                    if "~" in ctx.verb.payload:
+                        exclude = ctx.verb.payload.split("~")
+                    else:
+                        exclude = ctx.verb.payload.split(",")
+                    for k, v in ctx.response.variables.items():
+                        if k not in exclude:
+                            debug[k] = v.get_value(ctx.verb)
+                else:
+                    return None
+
+            elif ctx.verb.parameter in ("i", "inc", "include"):
+                if ctx.verb.payload:
+                    if "~" in ctx.verb.payload:
+                        include = ctx.verb.payload.split("~")
+                    else:
+                        include = ctx.verb.payload.split(",")
+
+                    for k, v in ctx.response.variables.items():
+                        if k in include:
+                            debug[k] = v.get_value(ctx.verb)
+                else:
+                    return None
+
+        elif ctx.verb.payload:
+            if "~" in ctx.verb.payload:
+                include = ctx.verb.payload.split("~")
+            else:
+                include = ctx.verb.payload.split(",")
+
+            for k, v in ctx.response.variables.items():
+                if k in include:
+                    debug[k] = v.get_value(ctx.verb)
+        else:
+            for k, v in ctx.response.variables.items():
+                debug[k] = v.get_value(ctx.verb)
+        ctx.response.extras["debug"] = debug
+        return ""

bTagScript/block/var_block.py

@@ -0,0 +1,49 @@
+from typing import Optional
+
+from ..adapter import StringAdapter
+from ..interface import Block
+from ..interpreter import Context
+
+
+class VarBlock(Block):
+    """
+    Variables are useful for choosing a value and referencing it later in a tag.
+    Variables can be referenced using brackets as any other block.
+    Note that if the variable's name is being "used" by any other block the variable
+    will be ignored.
+
+    **Usage:** ``{=(<name>):<value>}``
+
+    **Aliases:** ``assign, let, var, =``
+
+    **Payload:** ``value``
+
+    **Parameter:** ``name``
+
+    **Examples:**
+
+    .. tagscript::
+
+        {=(prefix):!}
+        The prefix here is `{prefix}`.
+        The prefix here is `!`.
+
+        {let(day):Monday}
+        {if({day}==Wednesday):It's Wednesday my dudes!|The day is {day}.}
+        The day is Monday.
+
+        Variables can also be created like so if the interpreter uses loose variables
+        {$<name>:<value>}
+        {$day:Monday} == {=(day):Monday}
+    """
+
+    ACCEPTED_NAMES = ("=", "assign", "let", "var")
+
+    def process(self, ctx: Context) -> Optional[str]:
+        """
+        Process the block and assign the variable.
+        """
+        if ctx.verb.parameter in ctx.interpreter._blocknames:  # pylint: disable=protected-access
+            return None
+        ctx.response.variables[ctx.verb.parameter] = StringAdapter(str(ctx.verb.payload))
+        return ""

bTagScript/block/vargetter_blocks.py

@@ -0,0 +1,91 @@
+from typing import Optional
+
+from ..adapter import StringAdapter
+from ..interface import Block
+from ..interpreter import Context
+
+
+class LooseVariableGetterBlock(Block):
+    """
+    The loose variable block represents the adapters for any seeded or defined variables.
+    This variable implementation is considered "loose" since it checks whether the variable is
+    valid during :meth:`process`, rather than :meth:`will_accept`.
+    You may also define variables here with {$<variable name>:<value>}, note that this is not
+    available using the StrictVariableGetterBlock class.
+
+    **Usage:** ``{<variable_name>([parameter]):[payload]}``
+
+    **Aliases:** This block is valid for any inputted declaration.
+
+    **Payload:** Depends on the variable's underlying adapter.
+
+    **Parameter:** Depends on the variable's underlying adapter.
+
+    **Examples:**
+
+    .. tagscript::
+
+        {=(example):This is my variable.}
+        {example}
+        This is my variable.
+
+        {$variablename:This is another variable.}
+        {variablename}
+        This is another variable.
+    """
+
+    def will_accept(self, ctx: Context) -> bool:  # pylint: disable=arguments-differ
+        """
+        This block will accept any declaration.
+        """
+        return True
+
+    def process(self, ctx: Context) -> Optional[str]:
+        """
+        This block will check whether the variable is valid.
+        """
+        if ctx.verb.declaration.startswith("$"):
+            varname = ctx.verb.declaration.split("$", 1)[1]
+            ctx.response.variables[varname] = StringAdapter(str(ctx.verb.payload))
+            return ""
+        if ctx.verb.declaration in ctx.response.variables:
+            return ctx.response.variables[ctx.verb.declaration].get_value(ctx.verb)
+        return None
+
+
+class StrictVariableGetterBlock(Block):
+    """
+    The strict variable block represents the adapters for any seeded or defined variables.
+    This variable implementation is considered "strict" since it checks whether the variable is
+    valid during :meth:`will_accept` and is only processed if the declaration refers to a valid
+    variable. The main difference between this and the LooseVariableGetterBlock is that this
+    block will only attempt to process if the variable's already been defined.
+
+    **Usage:** ``{<variable_name>([parameter]):[payload]}``
+
+    **Aliases:** This block is valid for any variable name in `Response.variables`.
+
+    **Payload:** Depends on the variable's underlying adapter.
+
+    **Parameter:** Depends on the variable's underlying adapter.
+
+    **Examples:**
+
+    .. tagscript::
+
+        {=(example):This is my variable.}
+        {example}
+        This is my variable.
+    """
+
+    def will_accept(self, ctx: Context) -> bool:  # pylint: disable=arguments-differ
+        """
+        Check if the declaration is in the response variables
+        """
+        return ctx.verb.declaration in ctx.response.variables
+
+    def process(self, ctx: Context) -> Optional[str]:
+        """
+        Process the strict variable block
+        """
+        return ctx.response.variables[ctx.verb.declaration].get_value(ctx.verb)

bTagScript/exceptions.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from discord.ext.commands import Cooldown
+
+if TYPE_CHECKING:
+    from .interpreter import Interpreter, Response
+
+
+__all__ = (
+    "TagScriptError",
+    "WorkloadExceededError",
+    "ProcessError",
+    "EmbedParseError",
+    "BadColourArgument",
+    "StopError",
+    "CooldownExceeded",
+    "BlocknameDuplicateError",
+)
+
+
+class TagScriptError(Exception):
+    """
+    Base class for all module errors.
+    """
+
+
+class WorkloadExceededError(TagScriptError):
+    """
+    Raised when the interpreter goes over its passed character limit.
+    """
+
+
+class ProcessError(TagScriptError):
+    """
+    Raised when an exception occurs during interpreter processing.
+
+    Attributes
+    ----------
+    original: Exception
+        The original exception that occurred during processing.
+    response: Response
+        The incomplete response that was being processed when the exception occurred.
+    interpreter: Interpreter
+        The interpreter used for processing.
+    """
+
+    def __init__(self, error: Exception, response: Response, interpreter: Interpreter) -> None:
+        """
+        Construct the error
+        """
+        self.original: Exception = error
+        self.response: Response = response
+        self.interpreter: Interpreter = interpreter
+        super().__init__(error)
+
+
+class EmbedParseError(TagScriptError):
+    """
+    Raised if an exception occurs while attempting to parse an embed.
+    """
+
+
+class BadColourArgument(EmbedParseError):
+    """
+    Raised when the passed input fails to convert to `discord.Colour`.
+
+    Attributes
+    ----------
+    argument: str
+        The invalid input.
+    """
+
+    def __init__(self, argument: str) -> None:
+        """
+        Init the error
+        """
+        self.argument = argument
+        super().__init__(f'Colour "{argument}" is invalid.')
+
+
+class StopError(TagScriptError):
+    """
+    Raised by the StopBlock to stop processing.
+
+    Attributes
+    ----------
+    message: str
+        The stop error message.
+    """
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(message)
+
+
+class CooldownExceeded(StopError):
+    """
+    Raised by the cooldown block when a cooldown is exceeded.
+
+    Attributes
+    ----------
+    message: str
+        The cooldown error message.
+    cooldown: discord.ext.commands.Cooldown
+        The cooldown bucket with information on the cooldown.
+    key: str
+        The cooldown key that reached its cooldown.
+    retry_after: float
+        The seconds left til the cooldown ends.
+    """
+
+    def __init__(self, message: str, cooldown: Cooldown, key: str, retry_after: float) -> None:
+        """
+        Construct the error
+        """
+        self.cooldown = cooldown
+        self.key = key
+        self.retry_after = retry_after
+        super().__init__(message)
+
+
+class BlocknameDuplicateError(TagScriptError):
+    """
+    Raised when a a duplicate block name is passed to the interpreter
+
+    Attributes
+    ----------
+    blockname: str
+        The blockname that was duplicated
+    """
+
+    def __init__(self, blockname: str) -> None:
+        """
+        Init
+        """
+        self.blockname: str = blockname
+        super().__init__()

bTagScript/interface/__init__.py

@@ -0,0 +1,4 @@
+from .adapter import Adapter
+from .block import Block, verb_required_block
+
+__all__ = ("Adapter", "Block", "verb_required_block")

bTagScript/interface/adapter.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ..interpreter import Context
+
+
+class Adapter:
+    """
+    The base class for TagScript adapters.
+
+    Implementations must subclass this to create adapters.
+    """
+
+    def __repr__(self) -> str:
+        """
+        String repr
+        """
+        return f"<{type(self).__qualname__} at {hex(id(self))}>"
+
+    def get_value(self, ctx: Context) -> Optional[str]:
+        """
+        Processes the adapter's actions for a given :class:`~bTagScript.interpreter.Context`.
+
+        Subclasses must implement this.
+
+        Parameters
+        ----------
+        ctx: Context
+            The context object containing the TagScript :class:`~bTagScript.verb.Verb`.
+
+        Returns
+        -------
+        Optional[str]
+            The adapters's processed value.
+
+        Raises
+        ------
+        NotImplementedError
+            The subclass did not implement this required method.
+        """
+        raise NotImplementedError

bTagScript/interface/block.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ..interpreter import Context
+
+
+__all__ = ("Block", "verb_required_block")
+
+
+class Block:
+    """
+    The base class for TagScript blocks.
+
+    Implementations must subclass this to create new blocks.
+
+    Attributes
+    ----------
+    ACCEPTED_NAMES: Tuple[str, ...]
+        The accepted names for this block. This ideally should be set as a class attribute.
+    """
+
+    ACCEPTED_NAMES = ()
+
+    def __repr__(self) -> str:
+        """
+        String repr
+        """
+        return f"<{type(self).__qualname__} at {hex(id(self))}>"
+
+    @classmethod
+    def will_accept(cls, ctx: Context) -> bool:
+        """
+        Describes whether the block is valid for the given :class:`~bTagScript.interpreter.Context`.
+
+        Parameters
+        ----------
+        ctx: Context
+            The context object containing the TagScript :class:`~bTagScript.verb.Verb`.
+
+        Returns
+        -------
+        bool
+            Whether the block should be processed for this :class:`~bTagScript.interpreter.Context`.
+        """
+        dec = ctx.verb.declaration.lower()
+        return dec in cls.ACCEPTED_NAMES
+
+    def pre_process(self, ctx: Context) -> Optional[str]:  # pylint: disable=unused-argument
+        """
+        Any pre processing that needs to be done before the block is processed.
+        """
+        return None
+
+    def process(self, ctx: Context) -> Optional[str]:
+        """
+        Processes the block's actions for a given :class:`~bTagScript.interpreter.Context`.
+
+        Subclasses must implement this.
+
+        Parameters
+        ----------
+        ctx: Context
+            The context object containing the TagScript :class:`~bTagScript.verb.Verb`.
+
+        Returns
+        -------
+        Optional[str]
+            The block's processed value.
+
+        Raises
+        ------
+        NotImplementedError
+            The subclass did not implement this required method.
+        """
+        raise NotImplementedError
+
+    def post_process(self, ctx: Context) -> Optional[str]:  # pylint: disable=unused-argument
+        """
+        Any post processing that needs to be done after the block is processed.
+        """
+        return None
+
+
+@lru_cache(maxsize=None)
+def verb_required_block(
+    implicit: bool,
+    *,
+    parameter: bool = False,
+    payload: bool = False,
+) -> Block:
+    """
+    Get a Block subclass that requires a verb to implicitly or explicitly have a parameter or payload passed.
+
+    Parameters
+    ----------
+    implicit: bool
+        Specifies whether the value is required to be passed implicitly or explicitly.
+        ``{block()}`` would be allowed if implicit is False.
+    parameter: bool
+        Passing True will cause the block to require a parameter to be passed.
+    payload: bool
+        Passing True will cause the block to require the payload to be passed.
+    """
+    check = (lambda x: x) if implicit else (lambda x: x is not None)
+
+    class RequireMeta(type):
+        """
+        Require a verb to have a parameter or payload if added.
+        """
+
+        def __repr__(cls) -> str:
+            """
+            String repr
+            """
+            return f"VerbRequiredBlock(implicit={implicit!r}, payload={payload!r}, parameter={parameter!r})"
+
+    class VerbRequiredBlock(Block, metaclass=RequireMeta):  # pylint: disable=abstract-method
+        """
+        The required block.
+        """
+
+        def will_accept(self, ctx: Context) -> bool:  # pylint: disable=arguments-differ
+            """
+            Describes whether the block is valid for the given :class:`~bTagScript.interpreter.Context`.
+            """
+            verb = ctx.verb
+            if payload and not check(verb.payload):
+                return False
+            if parameter and not check(verb.parameter):
+                return False
+            return super().will_accept(ctx)
+
+    return VerbRequiredBlock