ZedScripts 0.0.2__py3-none-any.whl

ZedScripts/providers/hover.py

@@ -0,0 +1,37 @@
+from typing import TYPE_CHECKING
+
+from lsprotocol import types
+
+from ..utils import textrange_to_lsp
+
+if TYPE_CHECKING:
+    from ..structure.lexer import TextRange
+
+def make_hover_information(description: str, range: 'TextRange | None' = None) -> types.Hover | None:
+    if description == "":
+        return None
+    return types.Hover(
+        contents=types.MarkupContent(
+            kind=types.MarkupKind.Markdown,
+            value=_format_description(description),
+        ),
+        range=textrange_to_lsp(range) if range is not None else None
+    )
+
+def format_tree(tree: str) -> str:
+    return f"```zedserver\n{tree}\n```"
+
+# TODO: this could possibly not work in other IDEs
+def _format_description(description: str) -> str:
+    """
+    Format the description for hover information.
+    The C++ code blocks which are used in the datasets for script blocks are
+    replaced with proper zedscripts code blocks.
+
+    Args:
+        description (str): 
+
+    Returns:
+        str: 
+    """
+    return description.replace("```cpp", "```zedscripts")

ZedScripts/providers/http.py

@@ -0,0 +1,49 @@
+import datetime
+import logging
+import requests_cache
+
+from .. import ZEDSCRIPT_CACHE_DIR
+
+
+
+
+_default_expire_after = datetime.timedelta(hours=12)
+def get_session(expire_after: datetime.timedelta | float = _default_expire_after) -> requests_cache.CachedSession:
+    """
+    Get a cached HTTP session with the specified expiration time.
+
+    Args:
+        expire_after (datetime.timedelta | float, optional): The duration after which the cache expires. Defaults to datetime.timedelta(days=1).
+
+    Returns:
+        requests_cache.CachedSession: A cached HTTP session with the specified expiration time.
+    """
+    session = requests_cache.CachedSession(
+        cache_name=str(ZEDSCRIPT_CACHE_DIR / "http_cache"), 
+        expire_after=expire_after,
+    )
+    return session
+
+def load_json(url: str, expire_after: datetime.timedelta | float = _default_expire_after) -> dict:
+    """
+    Load JSON data from the specified URL using a cached HTTP session.
+
+    Args:
+        url (str): The URL to load JSON data from.
+        expire_after (datetime.timedelta | float, optional): The duration after which the cache expires. Defaults to _default_expire_after.
+
+    Returns:
+        dict: The JSON data loaded from the specified URL.
+    """
+    session = get_session(expire_after=expire_after)
+    response = session.get(url)
+    is_cached = getattr(response, 'from_cache', False)
+    logging.debug(f"Loading {url} - from_cache: {is_cached}")
+    response.raise_for_status()
+    return response.json()
+
+def clear_cache():
+    """Resets the session cache."""
+    session = get_session()
+    session.cache.clear()
+    logging.debug("HTTP cache cleared.")

ZedScripts/providers/locale.py

@@ -0,0 +1,80 @@
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+from importlib.resources import files
+
+if TYPE_CHECKING:
+    from ..enums.Diagnostic import DiagnosticType
+    from ..providers.diagnostics import DiagnosticDefinition
+
+
+class Locale:
+    def __init__(self, code: str, strings: dict[str, str] | None = None) -> None:
+        if strings is None:
+            strings = {}
+        self.code: str = code
+        self.strings: dict[str, str] = strings
+
+
+class Localizer:
+    def __init__(self) -> None:
+        self.locales: dict[str, Locale] = {}
+        self.default_locale: str = "en"
+        self.current_locale: str = self.default_locale
+
+    def localize_string(self, 
+                        identifier: 'DiagnosticType',
+                        definition: 'DiagnosticDefinition', 
+                        locale: str | None = None, 
+                        args: dict[str, Any] | None = None) -> str:
+        if locale is None:
+            locale = self.current_locale
+        assert locale in self.locales, "Locale not loaded or invalid: {}".format(locale)
+
+        string = self.locales[locale].strings.get(identifier.name)
+        if string is None:
+            logging.warning("Missing string: %s (%s).", identifier.name, locale)
+            return identifier.name
+
+        if args is not None:
+            args_formatted = {}
+            args_def = definition.args
+
+            # ensure that each keys in args_def are present in args
+            for k in args_def.keys():
+                if k not in args:
+                    raise ValueError(f"Missing argument '{k}' for localization.")
+
+            # format args properly based on the definition's argument types
+            for k,v in args.items():
+                assert k in args_def.keys(), f"Unexpected argument '{k}' for localization."
+                assert isinstance(v, args_def[k]), f"Argument '{k}' must be of type {args_def[k].__name__}."
+
+                # format based on the type
+                if isinstance(args_def[k], list):
+                    args_formatted[k] = ", ".join(f"'{item}'" for item in v)
+                else:
+                    args_formatted[k] = str(v)
+            return string.format(**args_formatted)
+
+        return string
+
+    def load_locale_files(self) -> None:
+        for locale in files("ZedScripts.locale").iterdir():
+            # safeguards, probably not needed tbh
+            if not locale.is_file():
+                continue
+            if not locale.name.endswith(".json"):
+                continue
+
+            # access the locale data
+            with locale.open('r') as file:
+                raw: dict[str, Any] = json.load(file)
+
+            assert "code" in raw, "Locale file missing 'code'"
+            assert "strings" in raw, "Locale file missing 'strings'"
+
+            self.locales[raw["code"]] = Locale(raw["code"], raw["strings"])
+
+# initialize the localizer here to prevent circular imports
+zedlocalizer = Localizer()

ZedScripts/providers/notifications.py

@@ -0,0 +1,45 @@
+import enum
+from typing import TypedDict
+from pathlib import Path
+
+from ..utils import path_to_uri
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from ..environment import WorkspaceType
+
+
+class ZedNotification(enum.StrEnum):
+    SET_ZEDSCRIPTS = "zedscripts/setZedScripts"
+
+    LOADING_DOCUMENTS = "zedscripts/loadingDocuments"
+    LOADING_DOCUMENTS_DONE = "zedscripts/loadingDocumentsDone"
+
+
+
+class NotificationParams(TypedDict): ...
+
+class SetZedScriptsNotificationParams(NotificationParams):
+    uri: str
+
+class LoadingDocumentsNotificationParams(NotificationParams):
+    uri: str
+    progress: float
+    workspace_type: 'WorkspaceType'
+
+
+
+
+def send_progress_notification(type: ZedNotification, folder: Path, progress: float, workspace_type: 'WorkspaceType'):
+    from ..server import ZedServer
+    server = ZedServer.instance
+    if server is None:
+        return
+    server.send_notification(
+        type,
+        LoadingDocumentsNotificationParams(
+            uri=path_to_uri(folder),
+            progress=progress,
+            workspace_type=workspace_type
+        )
+    )

ZedScripts/providers/semantic_tokens.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import enum
+import re
+import logging
+from typing import TYPE_CHECKING, cast
+from operator import attrgetter
+
+from lsprotocol.types import SemanticTokens
+
+from .. import IS_DEBUG
+from ..structure.lexer import TokenType, chars_in_range, Token, TokenCollection, TextPosition, TextRange
+
+if TYPE_CHECKING:
+    from ..environment.document import Document
+
+PATTERN_FLOAT = re.compile("-?\\d+(?:\\.\\d+)?")
+
+
+class SemanticTokenType(enum.IntEnum):
+    NAMESPACE = 0
+    TYPE = 1
+    CLASS = 2
+    ENUM = 3
+    INTERFACE = 4
+    STRUCT = 5
+    TYPE_PARAMETER = 6
+    PARAMETER = 7
+    VARIABLE = 8
+    PROPERTY = 9
+    ENUM_MEMBER = 10
+    EVENT = 11
+    FUNCTION = 12
+    METHOD = 13
+    MACRO = 14
+    KEYWORD = 15
+    MODIFIER = 16
+    COMMENT = 17
+    STRING = 18
+    NUMBER = 19
+    REGEXP = 20
+    OPERATOR = 21
+    DECORATOR = 22
+    LABEL = 23
+
+
+class SemanticTokenModifier(enum.IntFlag):
+    DECLARATION = enum.auto()
+    """declaration site of a symbol"""
+    DEFINITION = enum.auto()
+    """definition (vs. just a declaration)"""
+    READONLY = enum.auto()
+    """symbol can't be reassigned (e.g. a constant)"""
+    STATIC = enum.auto()
+    """static member/variable"""
+    DEPRECATED = enum.auto()
+    """symbol is deprecated, editors often show strikethrough"""
+    ABSTRACT = enum.auto()
+    """abstract method/class"""
+    ASYNC = enum.auto()
+    """async function/method"""
+    MODIFICATION = enum.auto()
+    """token is a write/assignment to the symbol, not just a read"""
+    DOCUMENTATION = enum.auto()
+    """token appears inside documentation"""
+    DEFAULT_LIBRARY = enum.auto()
+    """symbol comes from a built-in/default library"""
+
+def get_tokens() -> tuple[list[str], list[str]]:
+    """
+    Returns the list of semantic token types and modifiers as strings.
+    """
+    return [t.name.lower() for t in SemanticTokenType], [cast(str, m.name).lower() for m in SemanticTokenModifier]
+
+
+
+
+
+
+class SemanticToken:
+    def __init__(
+            self, range: TextRange, type: SemanticTokenType, modifiers: SemanticTokenModifier | None = None
+    ) -> None:
+        if modifiers is None:
+            modifiers = SemanticTokenModifier(0)
+        self.range: TextRange = range
+        self.type: SemanticTokenType = type
+        self.modifiers: SemanticTokenModifier = modifiers
+
+    def __repr__(self) -> str:
+        return f"SemanticToken(range={self.range}, type={self.type.name}[{self.type}], modifiers={self.modifiers})"
+
+
+class SemanticTokenCollection(list[SemanticToken]):
+    def __init__(self, document: Document, *args: SemanticToken) -> None:
+        super().__init__(args)
+        self.document = document
+
+    def sort_tokens(self) -> "SemanticTokenCollection":
+        self.sort(key=attrgetter("range.start.line", "range.start.offset"))
+        return self
+
+    def to_lsp(self) -> list[int]:
+        lsp_tokens: list[int] = []
+        last_pos: TextPosition = TextPosition(0, 0)
+
+        # make sure to sort the semantic tokens by their position
+        semantic_tokens = self.sort_tokens()
+        for i in range(len(semantic_tokens)):
+            token = semantic_tokens[i]
+
+            line_delta = token.range.start.line - last_pos.line
+            if line_delta == 0:
+                offset_delta = token.range.start.offset - last_pos.offset
+            else:
+                offset_delta = token.range.start.offset
+
+            characters = chars_in_range(self.document.get_text(), token.range)
+            if characters == "":
+                continue
+
+            lines = characters.split("\n")
+            lsp_tokens.append(line_delta)
+            lsp_tokens.append(offset_delta)
+            lsp_tokens.append(len(lines[0]))
+            lsp_tokens.append(token.type.value)
+            # false positive U_U
+            lsp_tokens.append(int(token.modifiers))
+            for line in lines[1:]:
+                lsp_tokens.append(1)
+                lsp_tokens.append(0)
+                lsp_tokens.append(len(line))
+                lsp_tokens.append(token.type.value)
+                # false positive U_U
+                lsp_tokens.append(int(token.modifiers))
+
+            last_pos = token.range.start if len(lines) == 1 else TextPosition(token.range.start.line + len(lines) - 1, 0)
+
+        # just so we don't have a for loop when not in debug mode
+        # if IS_DEBUG:
+        #     logging.debug("Semantic tokens for document")
+        #     max_token_length = 70
+        #     for line, token in enumerate(semantic_tokens):
+        #         logging.debug(f"{str(token).ljust(max_token_length+2)} {lsp_tokens[line * 5: (line + 1) * 5]}")
+
+        return lsp_tokens
+
+    def add(self, type: SemanticTokenType, location: TextRange, modifiers: list[SemanticTokenModifier] = []):
+        """
+        Add a new semantic token to the collection.
+
+        Args:
+            type (SemanticTokenType): The type of the semantic token.
+            location (TextRange): The range in the document that the token covers.
+        """
+        combined_modifiers = SemanticTokenModifier(0)
+        for modifier in modifiers:
+            combined_modifiers |= modifier
+        self.append(SemanticToken(location, type, combined_modifiers))
+
+
+def build_syntactic_tokens(document: Document):
+    """
+    Builds tokens that can be inferred directly from the lexical tokens without further context.
+    :param document:
+    :return:
+    """
+    semantic_tokens = document.syntactic_semantic_tokens
+    semantic_tokens.clear() # reset syntactic semantic tokens
+
+    # mark every typical lexical token with a corresponding semantic token
+    for token in document.lexical_tokens:
+        match token.type:
+            case TokenType.ELEMENT_DELIMITER:
+                semantic_tokens.add(
+                    SemanticTokenType.KEYWORD,
+                    TextRange(token.pos, token.end),
+                )
+            case TokenType.COMMENT:
+                semantic_tokens.add(
+                    SemanticTokenType.COMMENT,
+                    TextRange(token.pos, token.end),
+                )
+            case TokenType.PUNCTUATOR:
+                semantic_tokens.add(
+                    SemanticTokenType.KEYWORD,
+                    TextRange(token.pos, token.end),
+                )
+

ZedScripts/scripts/__init__.py

@@ -0,0 +1,160 @@
+import enum
+from typing import (TYPE_CHECKING, 
+                    TypedDict, Literal, NotRequired, 
+                    TypeVar, Generic)
+
+if TYPE_CHECKING:
+    from ..structure.ast import ValueNode, BlockNode, Chunk
+
+
+
+class ScriptBlockData(TypedDict):
+    """
+    The data structure representing a script block.
+    """
+    name: str
+    description: str
+    shortDescription: NotRequired[str]
+    needsChildren: NotRequired[list[str]]
+    parents: list[str]
+    ID: NotRequired['ScriptBlockID']
+    parameters: dict[str, 'ScriptBlockParameter']
+    # properties: #TODO
+    variantOf: NotRequired[str]
+    """if this block is a variant of another block, the name of the base block"""
+
+    # those should basically be unused here now
+    isRoot: NotRequired[bool]
+    pattern: NotRequired[list[str]]
+    """to be used as regex patterns for identification"""
+    noComma: NotRequired[bool]
+    """default is false"""
+
+class ScriptBlockID(TypedDict):
+    """
+    Provides information about the ID of the block.
+    """
+    parentsWithout: NotRequired[list[str]]
+    values: NotRequired[list[str]]
+    asType: NotRequired[bool]
+    canHaveSpace: NotRequired[bool]
+    translation: NotRequired['TranslationProperties']
+
+
+## key-value types
+
+type ScriptBlockValue = str | int | float | bool
+class ScriptBlockParameter(TypedDict):
+    """
+    Represents a parameter of a script block.
+    """
+    name: str
+    description: NotRequired[str]
+    allowedDuplicate: NotRequired[bool]
+    canBeEmpty: NotRequired[bool]
+    default: NotRequired[ScriptBlockValue | list]
+    type: NotRequired['ParameterType']
+    deprecated: NotRequired['DeprecatedInfo']
+    values: NotRequired[list[ScriptBlockValue]]
+    needs: NotRequired['ScriptBlockNeeds']
+
+
+class ValueType(enum.StrEnum):
+    STRING = "string"
+    INTEGER = "integer"
+    FLOAT = "float"
+    BOOLEAN = "boolean"
+    ARRAY = "array"
+    OBJECT = "object"
+    BLOCK = "block"
+    CALLBACK = "callback"
+    TRANSLATION = "translation"
+
+_early_return: set[ValueType] = {
+    ValueType.STRING,
+    ValueType.ARRAY,
+    ValueType.OBJECT,
+    ValueType.BLOCK,
+    ValueType.CALLBACK,
+    ValueType.TRANSLATION,
+}
+
+def cant_self_validate(value_type: ValueType) -> bool:
+    """Verifies whenever the provided value_type cannot be validated by the value itself."""
+    return value_type in _early_return
+
+
+class ParameterType(TypedDict):
+    main: ValueType
+    array: NotRequired['ArrayType']
+    object: NotRequired['ObjectType']
+    block: NotRequired['BlockType']
+    translation: NotRequired['TranslationProperties']
+    callback: NotRequired['CallbackType']
+
+class ArrayType(TypedDict):
+    separator: str
+    type: Literal[ValueType.STRING, ValueType.INTEGER, ValueType.FLOAT, ValueType.BOOLEAN]
+
+class ObjectType(TypedDict):
+    keyValueSeparator: str
+    """the separator used to split the key and value"""
+    keyType: Literal[ValueType.STRING, ValueType.INTEGER, ValueType.FLOAT, ValueType.BOOLEAN]
+    valueType: Literal[ValueType.STRING, ValueType.INTEGER, ValueType.FLOAT, ValueType.BOOLEAN]
+    pairsSeparator: str
+    """the separator used to split different key-value pairs"""
+
+class BlockType(TypedDict):
+    name: str
+    """the block type (e.g. "sound", "item", "model"...)"""
+    fullType: NotRequired[bool]
+    """if true, this should use the module to reference the block"""
+    noAutoImport: NotRequired[bool]
+    """if true, the will not automatically check its own parent block module when fullType is set to true"""
+
+class CallbackType(TypedDict):
+    parameters: list['CallbackParameter']
+    returns: NotRequired[str]
+
+class CallbackParameter(TypedDict):
+    name: str
+    type: str
+    isJava: bool
+
+
+class ScriptBlockNeeds(TypedDict):
+    name: str
+    """the dependent parameter"""
+    values: NotRequired[list[ScriptBlockValue]]
+    """list of possible values for the dependent parameter"""
+    valueToType: NotRequired[dict[str, str]]
+    """mapping from dependent parameter values to their types
+    (for dynamic typing based on other parameter's value)"""
+
+## extra metadata
+
+class DeprecatedInfo(TypedDict):
+    replacedBy: NotRequired[str]
+    description: NotRequired[str]
+    version: NotRequired[str]
+
+class TranslationProperties(TypedDict):
+    """
+    Used to indicate translation properties to an element.
+    For example a key=value pair where the value needs a specific translation key.
+    """
+    keyPattern: str
+    sourceFile: str
+
+
+## block and values base classes
+
+
+NodeT = TypeVar("NodeT")
+
+
+class Element(Generic[NodeT]):
+    def __init__(self) -> None:
+        super().__init__()
+        self.node: NodeT
+        """AST node of the element."""