yace 0.5.7__py3-none-any.whl

yace/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.5.7"

yace/__main__.py

@@ -0,0 +1,3 @@
+from yace.cli.yace import main
+
+main()

yace/cli/yace.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""
+The is the command-line interface to **yace**.
+
+TODO
+====
+
+* Discover 'adhoc' targets, e.g. targets available in the
+  current-workding-directory
+* Discover targets via packages under the namespace 'yace.targets.{NAME}`
+
+"""
+import argparse
+import logging as log
+import sys
+from pathlib import Path
+
+from yace import __version__ as version
+from yace.compiler import Compiler
+from yace.ir.cparser import c_to_yace
+
+
+def parse_args():
+    """Parse command-line arguments"""
+
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument(
+        "filepath",
+        nargs="+",
+        type=Path,
+        help="path to one or more Yace-file(s) or C Header(s)",
+    )
+
+    parser.add_argument(
+        "--emit",
+        nargs="+",
+        choices=sorted([target.NAME for target in Compiler.TARGETS]),
+        default="capi",
+        help="treat filepath(s) as Yace-file, and emit code using target(s), then exit",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {version}",
+    )
+
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path.cwd(),
+        help="path to output directory, for emitted code / artifacts",
+    )
+    parser.add_argument(
+        "--log-level",
+        "-l",
+        action="append_const",
+        const=1,
+        default=[],
+        help="increase log-level.",
+    )
+
+    return parser.parse_args()
+
+
+def main():
+    """Emit enums, structs, and pretty-printer functions for them"""
+
+    ok = False
+    try:
+        args = parse_args()
+        args.filepath = [filepath.resolve() for filepath in args.filepath]
+
+        levels = [log.ERROR, log.INFO, log.DEBUG]
+        log.basicConfig(
+            format="%(levelname)s:%(module)s:%(funcName)s(): %(message)s",
+            level=levels[min(sum(args.log_level), len(levels) - 1)],
+        )
+
+        suffixes = list(
+            set(path.suffix for path in args.filepath if path.suffix in [".h", ".yaml"])
+        )
+        if len(suffixes) != 1:
+            log.error(f"Suffixes({suffixes}); provide either .h or .yaml")
+            return sys.exit(1)
+
+        missing = [str(path) for path in args.filepath if not path.exists()]
+        if missing:
+            log.error(f"Does not exist: {missing}")
+            return sys.exit(1)
+
+        if suffixes[0] == ".h":  # C to Yace-file Compiler
+            log.info("Got .h will convert to Yace IR")
+
+            errors = c_to_yace(args.filepath, args.output)
+            for error in errors:
+                log.error(error)
+
+            return sys.exit(1 if errors else 0)
+
+        log.info(f"Got .yaml, will do '{args.emit}'")
+        yace = Compiler(args.emit, args.output)
+        ok = all([yace.process(path, yace.STAGES) for path in args.filepath])
+        return sys.exit(0 if ok else 1)
+
+    except Exception as exc:
+        log.error("Unhandled Exception: message(%s)", exc)
+        log.error("Unhandled Exception: increase log-level (-ll) for trace")
+        log.error("Unhandled Exception(%s)", exc, exc_info=True)
+
+    return sys.exit(1)

yace/compiler.py

@@ -0,0 +1,84 @@
+import copy
+import logging as log
+from pathlib import Path
+from typing import List, Optional
+
+from yace.model import Model
+from yace.targets.capi.target import CAPI
+from yace.targets.collector import collect
+from yace.targets.ctypes.target import Ctypes
+
+
+class Compiler(object):
+    """
+    Encapsulation of **yace** compiler stages
+
+    * Parse
+    * Lint
+    * Transform
+    * Emit
+    * Format
+    * Check
+
+    The first two stages are generic, the third is generic however is usually performed
+    for target-specific-reasons such as re-structuring the IR to make the code-emitter
+    simpler, the last three are target-specific.
+    """
+
+    STAGES = ["parse", "lint", "transform", "emit", "format", "check"]
+    TARGETS = list(set([CAPI, Ctypes] + collect()))
+
+    def __init__(self, targets: List[str], output: Path):
+        self.targets = [target for target in Compiler.TARGETS if target.NAME in targets]
+        self.output = output.resolve()
+
+    def process(self, path: Path, stages: Optional[List[str]] = None) -> bool:
+        """
+        Take 'path' through the given compiler 'stages'
+        """
+
+        if stages is None:
+            stages = Compiler.STAGES
+
+        log.info("Path: '%s', stages: '%s'", path, stages)
+        self.output.mkdir(parents=True, exist_ok=True)
+
+        log.info("Stage: 'parse'")
+        model_orig = Model.from_path(path)
+
+        targets = [cls(self.output) for cls in self.targets]
+        if not all([tgt.is_ready() for tgt in targets]):
+            log.error("One or more targets !ready; see above/log. stopping.")
+            return False
+
+        for target in targets:
+            log.info("Target: %s", target.NAME)
+
+            model = copy.deepcopy(model_orig)
+
+            if "transform" in stages:
+                log.info("Stage: 'transform'")
+                model = target.transform(model)
+
+            if "emit" in stages:
+                log.info("Stage: 'emit'")
+                err = target.emit(model)
+                if err:
+                    log.error("Got error, stopping.")
+                    break
+
+            if "format" in stages:
+                log.info("Stage: 'format'")
+                err = target.format()
+                if err:
+                    log.error("Got error, stopping.")
+                    break
+
+            if "check" in stages:
+                log.info("Stage: 'check'")
+                err = target.check()
+                if err:
+                    log.error("Got error, stopping.")
+                    break
+
+        return True

yace/emitters.py

@@ -0,0 +1,99 @@
+"""
+YAML ==> Interface(List[Entities]) ==> Emitter() ==> CodeTarget
+"""
+
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader
+
+
+def camelcase(symbol, pascalcase=True):
+    """Format the given 'symbol' as (C|c)amelCase"""
+
+    camelized = "".join(
+        [part[0].upper() + part[1:].lower() for part in symbol.split("_")]
+    )
+    if pascalcase:
+        return camelized
+
+    return camelized[0].lower() + camelized[1:]
+
+
+class Emitter(object):
+    """
+    The default approach to transforming :class:`.Entity` in :class:`.Model`:
+    to source-code-text is inheriting **this** class and utilizing the Jinja
+    templates made available in self.templates. It might seem naive to utilize
+    templating-engine like Jinja for a code-emitter, however, so far it seems
+    to be the an incredibly simple approach.
+
+    This class populates ``self.templates`` with templates loaded for a given
+    emitter-implementation. They work as Jinja usually does, a feature-addition
+    allowing you to render a Jinja template **within** a Jinja template, via a
+    custom-filter-function. For example, like so::
+
+        {{ entity | emit_entity }}
+
+    This works by seperating Jinja templates by filename-convention,
+    template-names starting with "entity_{name}.template" are usable by this
+    in-template renderer. Thus, for the example above, the template file is
+    named ``entity_typedecl``.
+
+    It assumes that 'entity' is an instance of :class:`.Entity` and uses a
+    Jinja template to render it. This behavior is added as a means to keep
+    **all** text-formating code inside the Jinja-templates, one does not need
+    to goto the Python to see a different technique. Thus, **all**::
+
+        Entity ==> SourceCodeText
+
+    Is by default handled in one place: the Jinja templates.
+    """
+
+    def __init__(self, searchpath: Path):
+        self.searchpath = searchpath.resolve()
+
+    def render(self, template, args, filters):
+        """Renders the given template, passing args..."""
+
+        # Emitter jinja-environment, setup here such that the filter-function
+        # 'emit_entity' can be utilized in the other jinja-environment
+        entity_jenv = Environment(
+            loader=FileSystemLoader(self.searchpath),
+            extensions=["jinja2.ext.do"],
+        )
+        entity_jenv.globals.update(zip=zip, len=len)
+        entity_jenv.filters["camelcase"] = camelcase
+        for name, filter in filters.items():
+            entity_jenv.filters[name] = filter
+
+        entity_templates = {
+            Path(f).stem: entity_jenv.get_template(f)
+            for f in entity_jenv.list_templates()
+            if f.endswith(".template") and f.startswith("entity_")
+        }
+
+        def emit_entity(entity, depth: int = 0):
+            args["entity"] = entity
+            args["depth"] = depth
+
+            return entity_templates[f"entity_{entity.key}.h"].render(**args)
+
+        # This is the jinja environment for files, e.g. the one that renders
+        # "file_<thing>.jinja"
+        file_jenv = Environment(
+            loader=FileSystemLoader(self.searchpath),
+            extensions=["jinja2.ext.do"],
+        )
+        file_jenv.globals.update(zip=zip, len=len)
+        file_jenv.filters["camelcase"] = camelcase
+        file_jenv.filters["emit_entity"] = emit_entity
+        for name, filter in filters.items():
+            file_jenv.filters[name] = filter
+
+        file_templates = {
+            Path(f).stem: file_jenv.get_template(f)
+            for f in file_jenv.list_templates()
+            if f.endswith(".template") and not f.startswith("entity_")
+        }
+
+        return file_templates[template].render(**args)

yace/errors.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""
+YACE returns errors except for the truly exceptional cases.
+"""
+from pydantic import BaseModel
+
+
+class Error(BaseModel):
+    message: str
+
+    def __str__(self):
+        return f"error.message: {self.message}"
+
+
+class ParseError(Error):
+    filename: str
+    line: int
+    column: int
+
+    @classmethod
+    def from_exception(cls, exception, cursor):
+        errors = "\n".join(
+            [f"{count}: {error}" for count, error in enumerate(exception.errors())]
+        )
+
+        return cls(
+            message=errors,
+            filename=cursor.location.file.name if cursor.location.file else "unknown",
+            line=cursor.location.line if cursor.location.line else -1,
+            column=cursor.location.column if cursor.location.column else -1,
+        )
+
+    @classmethod
+    def from_cursor(cls, message, cursor):
+        return cls(
+            message=message,
+            filename=cursor.location.file.name if cursor.location.file else "unknown",
+            line=cursor.location.line if cursor.location.line else -1,
+            column=cursor.location.column if cursor.location.column else -1,
+        )
+
+    def __str__(self):
+        return (
+            f"{self.filename}; line: {self.line}, "
+            f"column: {self.column}, error: {self.message}"
+        )
+
+
+class UnsupportedDatatype(ParseError):
+    @classmethod
+    def from_cursor(cls, cursor, message=None):
+        if not message:
+            message = f"Unsupported datatype({cursor.type.spelling})"
+
+        return cls(
+            message=message,
+            filename=cursor.location.file.name if cursor.location.file else "unknown",
+            line=cursor.location.line if cursor.location.line else -1,
+            column=cursor.location.column if cursor.location.column else -1,
+        )
+
+
+class TransformationError(Exception):
+    """Something went wrong during a yid-transformation"""
+
+    pass
+
+
+class ToolError(Exception):
+    """Exception raised when a tool exists with non-zero returncode"""
+
+    pass
+
+
+class InvalidModelData(Exception):
+    """The data given to entity instantion is not valid"""
+
+    pass
+
+
+class CSubsetIntegrityError(ParseError):
+    """
+    To provide meaningful error messages when a C file uses unsupported language
+    features or violates Yace conventions, errors are captured by C Subset Integrity
+    Errors, which inherit from this class.
+
+    This error itself is typically not instantiated directly; instead, errors inherit
+    from it. The error message is generated by reusing the description from the
+    docstring.
+
+    Integrity errors inherit from ParseError and use the docstring to provide the error
+    message.
+    """
+
+    @classmethod
+    def from_cursor(cls, message, cursor):
+        return cls.from_cursor(cls.__doc__, cursor)
+
+
+class InvalidFunctionPointerSymbol(CSubsetIntegrityError):
+    """
+    Function pointers must be named with a suffix of: '_cb', '_callback', '_fn', '_fun',
+    '_func', or '_function'. The function-pointer found here breaks this convention.
+    """
+
+    pass
+
+
+class MissingFunctionPointerArgumentSymbol(CSubsetIntegrityError):
+    """
+    Function pointers arguments must have symbol names. The function-pointer found here
+    break this convention.
+    """
+
+    pass
+
+
+class MissingDocstring(CSubsetIntegrityError):
+    """
+    To provide usable APIs and their bindings, proper documentation of data structures,
+    magic values, functions, and their arguments is required. This error occurs when a
+    docstring for the entity in question is missing.
+    """
+
+    pass

yace/ir/base.py

@@ -0,0 +1,121 @@
+"""
+The entities in the **yace** Interface Definition are enherit the
+:class:`.Entity` and mix-in common attributes.
+
+* Base-classes: :class:`.Entity` / :class:`.Typespec`
+
+* Mixin-attributes: :class:`.Named` / :class:`.Documented` / :class:`.Typed`
+
+The above are defined below.
+"""
+
+import re
+from typing import Dict, Optional
+
+from pydantic import BaseModel, Field
+
+
+class Docstring(BaseModel):
+    """
+    An enrichment of a raw-comment-text
+
+    The raw comment-text is parsed into the components of brief, description, and tags.
+    """
+
+    brief: str
+    description: str
+    tags: Dict[str, Dict[str, str]]
+
+    @classmethod
+    def from_cursor(cls, cursor):
+        data = {"brief": "", "description": "", "tags": {}}
+
+        raw_comment = ""
+        if cursor.raw_comment:
+            raw_comment = ("".join(list(cursor.raw_comment))).strip()
+
+        if raw_comment.startswith("///<"):
+            data["brief"] = raw_comment[4:].strip()
+            return cls(**data)
+
+        # Remove comment markers (/**, */, and leading *)
+        cleaned_docstring = re.sub(r"\/\*\*|\*\/", "", raw_comment)
+        cleaned_docstring = re.sub(
+            r"^\s*\*\s?", "", cleaned_docstring, flags=re.MULTILINE
+        ).strip()
+
+        # Split into lines
+        lines = cleaned_docstring.split("\n")
+
+        # Extract brief description (first non-empty line)
+        brief_description = lines[0].strip()
+        data["brief"] = brief_description
+
+        # Extract full description (everything after the first line,
+        # before any tag like @param/@return
+        description_lines = []
+        for line in lines[1:]:
+            if line.strip().startswith("@"):
+                break
+            if line.strip():
+                description_lines.append(line.strip())
+
+        data["description"] = " ".join(description_lines)
+
+        # Generic tag pattern to match any tag starting with @
+        tag_pattern = re.compile(r"@(\w+)\s+(\w+)?\s*(.*?)\n\s*\*", re.DOTALL)
+        matches = re.findall(tag_pattern, raw_comment)
+
+        tags = {}
+        for tag, param, desc in matches:
+            if tag not in tags:
+                tags[tag] = {}
+            if param:
+                tags[tag][param] = desc.strip()
+            else:
+                tags[tag] = desc.strip()
+
+        data["tags"] = tags
+
+        return data
+
+
+class Entity(BaseModel):
+    """
+    A baseclass for all entities in the Yace Interface Definition Language.
+
+    * label; list of labels
+    * annotations; User-defined annotations of any kind
+
+    """
+
+    key: str  # The Yace-IR constructor keyword
+    ant: Optional[dict] = Field(default_factory=dict)  # User annotations
+
+
+class Documented(BaseModel):
+    """
+    Attribute-mixin; adding a required 'doc' describing the :class:`.Entity`
+    """
+
+    doc: Docstring
+
+
+class Named(BaseModel):
+    """
+    Attribute-mixin; adding a required 'sym' to be used as identifier
+    """
+
+    sym: str
+
+    def is_valid_sym(self):
+        """Check whether the symbol is a valid C identifier"""
+
+        if self.sym is None:
+            return False, f"Invalid attr: sym == None; for {self.as_dict()}"
+
+        match = re.match(r"[_a-z][_a-z0-9]{0,30}", str(self.sym))
+        if match:
+            return True, "OK"
+
+        return False, f"Invalid attr: '{self.sym}'; for {self.as_dict()}"

yace/ir/constants.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""
+The **yace** constants consists of:
+
+* Constant Values:
+
+  * :class:`yace.ir.constants.String`
+  * :class:`yace.ir.constants.Dec`
+  * :class:`yace.ir.constants.Hex`
+
+* Symbolic Constants:
+
+  * :class:`yace.ir.constants.Define`
+
+* Enum Types:
+
+  * :class:`yace.ir.constants.Enum`
+  * :class:`yace.ir.constants.EnumValue`
+
+Their ir representation follows below.
+"""
+from typing import List, Union
+
+from .base import Documented, Entity, Named
+
+
+class String(Entity):
+    """
+    Representation of a literal string e.g. in C::
+
+        "this is a string-literal"
+
+    """
+
+    key: str = "str"
+    lit: str
+
+
+class Hex(Entity):
+    """
+    Representation of a hexadecimal constant
+
+    The emitted C code should be hexadecimal notation of literal integer
+    values, such as those used by :class:`yace.ir.constants.Define` and
+    :class:`yace.ir.enumtypes.Enum`::
+
+        #define FOO 0xACDC
+
+    """
+
+    key: str = "hex"
+    lit: int
+
+
+class Dec(Entity):
+    """Representation of a an integer literal in decimal"""
+
+    key: str = "dec"
+    lit: int
+
+
+class Define(Entity, Named):
+    """
+    C MACROS, one of biggest headaches when it comes to FFI interfaces,
+    especially for interpreted languages such as Python, since
+    MACRO-expressions have no symbols to "call" as these are all
+    pre-preprocossed and gone thus, no longer available.
+
+    Thus, **yace** only support the definition of MACRO values, such as::
+
+        #define SOME_GLOBALLY_CONSTANT 0xACDC
+
+    Definitions such as these to translate fairly when into equivalent globally
+    available and constant constructs in other languages
+    """
+
+    key: str = "define"
+    val: Union[String, Hex, Dec]
+
+
+class EnumValue(Entity, Named, Documented):
+    """
+    Representation of values in :class:`yace.ir.constants.Enum`.
+
+    By default, the C emitter produces::
+
+        SYMBOL = lit.val
+
+    for the :class:`yace.ir.constants.EnumValue`.
+    """
+
+    key: str = "enum_value"
+    val: Union[Hex, Dec]
+
+
+class Enum(Entity, Named, Documented):
+    """
+    Representation of enumeration values, note that literals on the
+    :class:`yace.ir.constants.EnumValue` are optional, an
+    :class:`yace.ir.constants.Enum` with **non** literal
+    :class:`yace.ir.constants.EnumValue` looks like::
+
+        enum example {
+            FOO,
+            BAR,
+            BAZ,
+        };
+
+    Whereas, an :class:`yace.ir.constants.Enum` with **literal**
+    :class:`yace.ir.constants.EnumValue` looks like::
+
+        enum example {
+            FOO = 0xACDC,
+            BAR = 0x1337,
+            BAZ = 0xBEEF,
+        };
+
+    for the :class:`yace.ir.constants.EnumValue``.
+    """
+
+    key: str = "enum"
+    members: List[EnumValue]
+
+    def is_valid_members(self):
+        """Checks whether the :class:`yace.ir.constants.Enum` is valid"""
+
+        invalid_types = [type(m) for m in self.members if not isinstance(m, EnumValue)]
+        if len(invalid_types):
+            return (
+                False,
+                f"Invalid types in {self.sym}.members; "
+                "expecting: EnumValue, got: [{invalid_types}]",
+            )
+
+        if String in [type(m) for m in self.members]:
+            return (False, "Enum-values must be numeral-types")
+
+        return (True, None)