pyfcstm 0.0.1__py3-none-any.whl

pyfcstm/dsl/parse.py

@@ -0,0 +1,155 @@
+"""
+Grammar parsing module for processing and interpreting grammar-based input text.
+
+This module provides functions to parse input text according to grammar rules defined
+in the GrammarParser. It uses ANTLR4 for lexical analysis and parsing, and provides
+specialized functions for parsing different grammar elements like conditions, preambles,
+and operations.
+"""
+
+from antlr4 import CommonTokenStream, InputStream, ParseTreeWalker
+
+from .error import CollectingErrorListener
+from .grammar import GrammarParser, GrammarLexer
+from .listener import GrammarParseListener
+
+
+def _parse_as_element(input_text, fn_element, force_finished: bool = True):
+    """
+    Parse input text using the specified grammar element function.
+
+    This internal function handles the common parsing logic for all grammar elements,
+    including error handling and parse tree walking.
+
+    :param input_text: The text to parse
+    :type input_text: str
+
+    :param fn_element: The parser function to use for parsing
+    :type fn_element: callable
+
+    :param force_finished: Whether to check if parsing consumed all input
+    :type force_finished: bool
+
+    :return: The parsed node representation of the input
+    :rtype: object
+
+    :raises: Various parsing errors if the input doesn't match the grammar
+    """
+    error_listener = CollectingErrorListener()
+
+    input_stream = InputStream(input_text)
+    lexer = GrammarLexer(input_stream)
+    lexer.removeErrorListeners()
+    lexer.addErrorListener(error_listener)
+
+    stream = CommonTokenStream(lexer)
+    parser = GrammarParser(stream)
+    parser.removeErrorListeners()
+    parser.addErrorListener(error_listener)
+
+    parse_tree = fn_element(parser)
+    if force_finished:
+        error_listener.check_unfinished_parsing_error(stream)
+    error_listener.check_errors()
+
+    listener = GrammarParseListener()
+    walker = ParseTreeWalker()
+    walker.walk(listener, parse_tree)
+    return listener.nodes[parse_tree]
+
+
+def parse_with_grammar_entry(input_text: str, entry_name: str, force_finished: bool = True):
+    """
+    Parse input text using a specified grammar entry point.
+
+    This function allows parsing with any entry point in the grammar by name.
+
+    :param input_text: The text to parse
+    :type input_text: str
+
+    :param entry_name: The name of the grammar rule to use as entry point
+    :type entry_name: str
+
+    :param force_finished: Whether to check if parsing consumed all input
+    :type force_finished: bool
+
+    :return: The parsed node representation of the input
+    :rtype: object
+
+    :raises: Various parsing errors if the input doesn't match the grammar
+
+    Example::
+
+        >>> result = parse_with_grammar_entry("x > 5", "condition")
+    """
+    return _parse_as_element(
+        input_text=input_text,
+        fn_element=getattr(GrammarParser, entry_name),
+        force_finished=force_finished
+    )
+
+
+def parse_condition(input_text: str):
+    """
+    Parse input text as a condition expression.
+
+    This function specifically parses conditional expressions according to
+    the grammar's condition rule.
+
+    :param input_text: The condition text to parse
+    :type input_text: str
+
+    :return: The parsed condition node
+    :rtype: object
+
+    :raises: Various parsing errors if the input doesn't match the condition grammar
+
+    Example::
+
+        >>> condition_node = parse_condition("x > 5 && y < 10")
+    """
+    return parse_with_grammar_entry(input_text, 'condition')
+
+
+def parse_preamble(input_text: str):
+    """
+    Parse input text as a preamble program.
+
+    This function specifically parses preamble programs according to
+    the grammar's preamble_program rule.
+
+    :param input_text: The preamble program text to parse
+    :type input_text: str
+
+    :return: The parsed preamble program node
+    :rtype: object
+
+    :raises: Various parsing errors if the input doesn't match the preamble grammar
+
+    Example::
+
+        >>> preamble_node = parse_preamble("x = 10;")
+    """
+    return parse_with_grammar_entry(input_text, 'preamble_program')
+
+
+def parse_operation(input_text: str):
+    """
+    Parse input text as an operation program.
+
+    This function specifically parses operation programs according to
+    the grammar's operation_program rule.
+
+    :param input_text: The operation program text to parse
+    :type input_text: str
+
+    :return: The parsed operation program node
+    :rtype: object
+
+    :raises: Various parsing errors if the input doesn't match the operation grammar
+
+    Example::
+
+        >>> operation_node = parse_operation("x := 10;")
+    """
+    return parse_with_grammar_entry(input_text, 'operation_program')

pyfcstm/entry/__init__.py

@@ -0,0 +1 @@
+from .cli import cli as pyfcstmcli

pyfcstm/entry/base.py

@@ -0,0 +1,126 @@
+import builtins
+import itertools
+import os
+import sys
+import traceback
+from functools import wraps, partial
+from typing import Optional, IO, Callable
+
+import click
+from click.exceptions import ClickException
+
+CONTEXT_SETTINGS = dict(
+    help_option_names=['-h', '--help']
+)
+
+
+class ClickWarningException(ClickException):
+    """
+    Custom exception class for displaying warnings in yellow color.
+
+    :param message: The error message.
+    :type message: str
+    """
+
+    def show(self, file: Optional[IO] = None) -> None:
+        """
+        Display the warning message in yellow.
+
+        :param file: File to write the output to.
+        :type file: Optional[IO]
+        """
+        click.secho(self.format_message(), fg='yellow', file=sys.stderr)
+
+
+class ClickErrorException(ClickException):
+    """
+    Custom exception class for displaying errors in red color.
+
+    :param message: The error message.
+    :type message: str
+    """
+
+    def show(self, file: Optional[IO] = None) -> None:
+        """
+        Display the error message in red.
+
+        :param file: File to write the output to.
+        :type file: Optional[IO]
+        """
+        click.secho(self.format_message(), fg='red', file=sys.stderr)
+
+
+def print_exception(err: BaseException, print: Optional[Callable] = None):
+    """
+    Print exception information, including traceback.
+
+    :param err: The exception object.
+    :type err: BaseException
+    :param print: Custom print function. If not provided, uses built-in print.
+    :type print: Optional[Callable]
+    """
+    print = print or builtins.print
+
+    lines = list(itertools.chain(*map(
+        lambda x: x.splitlines(keepends=False),
+        traceback.format_tb(err.__traceback__)
+    )))
+
+    if lines:
+        print('Traceback (most recent call last):')
+        print(os.linesep.join(lines))
+
+    if len(err.args) == 0:
+        print(f'{type(err).__name__}')
+    elif len(err.args) == 1:
+        print(f'{type(err).__name__}: {err.args[0]}')
+    else:
+        print(f'{type(err).__name__}: {err.args}')
+
+
+class KeyboardInterrupted(ClickWarningException):
+    """
+    Exception class for handling keyboard interruptions.
+
+    :param msg: Custom message to display.
+    :type msg: Optional[str]
+    """
+    exit_code = 0x7
+
+    def __init__(self, msg=None):
+        """
+        Initialize the exception.
+
+        :param msg: Custom message to display.
+        :type msg: Optional[str]
+        """
+        ClickWarningException.__init__(self, msg or 'Interrupted.')
+
+
+def command_wrap():
+    """
+    Decorator for wrapping Click commands.
+
+    This decorator catches exceptions and provides consistent error handling.
+
+    :return: Decorator function.
+    :rtype: Callable
+    """
+
+    def _decorator(func):
+        @wraps(func)
+        def _new_func(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except ClickException:
+                raise
+            except KeyboardInterrupt:
+                raise KeyboardInterrupted
+            except BaseException as err:
+                click.secho('Unexpected error found when running pyfcstm!', fg='red', file=sys.stderr)
+                print_exception(err, partial(click.secho, fg='red', file=sys.stderr))
+                click.get_current_context().exit(1)
+
+        return _new_func
+
+    return _decorator

pyfcstm/entry/cli.py

@@ -0,0 +1,12 @@
+from .dispatch import pyfcstmcli
+from .generate import _add_generate_subcommand
+from .plantuml import _add_plantuml_subcommand
+
+_DECORATORS = [
+    _add_generate_subcommand,
+    _add_plantuml_subcommand,
+]
+
+cli = pyfcstmcli
+for deco in _DECORATORS:
+    cli = deco(cli)

pyfcstm/entry/dispatch.py

@@ -0,0 +1,46 @@
+import click
+from click.core import Context, Option
+
+from .base import CONTEXT_SETTINGS
+from ..config.meta import __TITLE__, __VERSION__, __AUTHOR__, __AUTHOR_EMAIL__, __DESCRIPTION__
+
+_raw_authors = [item.strip() for item in __AUTHOR__.split(',') if item.strip()]
+_raw_emails = [item.strip() for item in __AUTHOR_EMAIL__.split(',')]
+if len(_raw_emails) < len(_raw_authors):  # pragma: no cover
+    _raw_emails += [None] * (len(_raw_authors) - len(_raw_emails))
+elif len(_raw_emails) > len(_raw_authors):  # pragma: no cover
+    _raw_emails[len(_raw_authors) - 1] = tuple(_raw_emails[len(_raw_authors) - 1:])
+    del _raw_emails[len(_raw_authors):]
+
+_author_tuples = [
+    (author, tuple([item for item in (email if isinstance(email, tuple) else ((email,) if email else ())) if item]))
+    for author, email in zip(_raw_authors, _raw_emails)
+]
+_authors = [
+    author if not emails else '{author} ({emails})'.format(author=author, emails=', '.join(emails))
+    for author, emails in _author_tuples
+]
+
+
+# noinspection PyUnusedLocal
+def print_version(ctx: Context, param: Option, value: bool) -> None:
+    """
+    Print version information of cli
+    :param ctx: click context
+    :param param: current parameter's metadata
+    :param value: value of current parameter
+    """
+    if not value or ctx.resilient_parsing:
+        return  # pragma: no cover
+    click.echo('{title}, version {version}.'.format(title=__TITLE__.capitalize(), version=__VERSION__))
+    if _authors:
+        click.echo('Developed by {authors}.'.format(authors=', '.join(_authors)))
+    ctx.exit()
+
+
+@click.group(context_settings=CONTEXT_SETTINGS, help=__DESCRIPTION__)
+@click.option('-v', '--version', is_flag=True,
+              callback=print_version, expose_value=False, is_eager=True,
+              help="Show pyfcstm's version information.")
+def pyfcstmcli():
+    pass  # pragma: no cover

pyfcstm/entry/generate.py

@@ -0,0 +1,83 @@
+"""
+State Machine Code Generation Module
+
+This module provides command line interface functionality for generating code from a state machine DSL.
+It includes functionality to parse DSL code, convert it to a state machine model, and render the model
+using templates to generate output code.
+"""
+
+import pathlib
+
+import click
+
+from .base import CONTEXT_SETTINGS
+from ..dsl import parse_with_grammar_entry
+from ..model import parse_dsl_node_to_state_machine
+from ..render import StateMachineCodeRenderer
+
+
+def _add_generate_subcommand(cli: click.Group) -> click.Group:
+    """
+    Add the 'generate' subcommand to the CLI group.
+
+    This function adds a 'generate' subcommand to the provided CLI group that allows users to
+    generate code from a state machine DSL file using specified templates.
+
+    :param cli: The click Group object to which the subcommand will be added
+    :type cli: click.Group
+
+    :return: The modified CLI group with the 'generate' subcommand added
+    :rtype: click.Group
+
+    Example::
+
+        >>> app = click.Group()
+        >>> app = _add_generate_subcommand(app)
+    """
+
+    @cli.command('generate', help='Generate code with template of a given state machine DSL code.',
+                 context_settings=CONTEXT_SETTINGS)
+    @click.option('-i', '--input-code', 'input_code_file', type=str, required=True,
+                  help='Input code file of state machine DSL.')
+    @click.option('-t', '--template-dir', 'template_dir', type=str, required=True,
+                  help='Template directory of the code generation.')
+    @click.option('-o', '--output-dir', 'output_dir', type=str, required=True,
+                  help='Output directory of the code generation.')
+    @click.option('--clear', '--clear-directory', 'clear_directory', type=bool, is_flag=True,
+                  help='Clear the destination directory of the output directory.')
+    def generate(input_code_file, template_dir, output_dir, clear_directory):
+        """
+        Generate code from a state machine DSL file using templates.
+
+        This function reads a state machine DSL file, parses it into an AST node,
+        converts the AST node to a state machine model, and renders the model using
+        templates to generate output code.
+
+        :param input_code_file: Path to the input DSL code file
+        :type input_code_file: str
+
+        :param template_dir: Path to the directory containing templates
+        :type template_dir: str
+
+        :param output_dir: Path to the directory where generated code will be written
+        :type output_dir: str
+
+        :param clear_directory: Whether to clear the output directory before generating code
+        :type clear_directory: bool
+
+        :return: None
+        """
+        code = pathlib.Path(input_code_file).read_text()
+        ast_node = parse_with_grammar_entry(code, entry_name='state_machine_dsl')
+        model = parse_dsl_node_to_state_machine(ast_node)
+
+        renderer = StateMachineCodeRenderer(
+            template_dir=template_dir,
+        )
+        renderer.render(
+            model,
+            output_dir=output_dir,
+            clear_previous_directory=clear_directory
+        )
+
+    return cli

pyfcstm/entry/plantuml.py

@@ -0,0 +1,67 @@
+"""
+State Machine DSL to PlantUML Converter Module
+
+This module provides functionality to convert state machine DSL code into PlantUML format.
+It includes a command-line interface for easy conversion of state machine DSL files
+to PlantUML code, which can be used to generate visual state machine diagrams.
+"""
+
+import pathlib
+
+import click
+
+from .base import CONTEXT_SETTINGS
+from ..dsl import parse_with_grammar_entry
+from ..model import parse_dsl_node_to_state_machine
+
+
+def _add_plantuml_subcommand(cli: click.Group) -> click.Group:
+    """
+    Add the 'plantuml' subcommand to the provided CLI group.
+
+    This function adds a subcommand that converts state machine DSL code to PlantUML format.
+    The subcommand reads DSL code from a file, parses it into a state machine model,
+    and outputs the corresponding PlantUML code.
+
+    :param cli: The click Group to which the subcommand should be added
+    :type cli: click.Group
+
+    :return: The modified CLI group with the plantuml subcommand added
+    :rtype: click.Group
+
+    Example::
+
+        >>> from click import Group
+        >>> cli = Group()
+        >>> cli = _add_plantuml_subcommand(cli)
+    """
+
+    @cli.command('plantuml', help='Create Plantuml code of a given state machine DSL code.',
+                 context_settings=CONTEXT_SETTINGS)
+    @click.option('-i', '--input-code', 'input_code_file', type=str, required=True,
+                  help='Input code file of state machine DSL.')
+    @click.option('-o', '--output', 'output_file', type=str, default=None,
+                  help='Output directory of the code generation, output to stdout when not assigned.')
+    def plantuml(input_code_file, output_file):
+        """
+        Convert state machine DSL code to PlantUML format.
+
+        This command reads state machine DSL code from the specified input file,
+        parses it into a state machine model, and outputs the corresponding PlantUML code
+        either to a file or to stdout.
+
+        :param input_code_file: Path to the file containing state machine DSL code
+        :type input_code_file: str
+        :param output_file: Path to the output file for PlantUML code (stdout if None)
+        :type output_file: str or None
+        """
+        code = pathlib.Path(input_code_file).read_text()
+        ast_node = parse_with_grammar_entry(code, entry_name='state_machine_dsl')
+        model = parse_dsl_node_to_state_machine(ast_node)
+        if output_file is not None:
+            with open(output_file, 'w') as f:
+                f.write(model.to_plantuml())
+        else:
+            click.echo(model.to_plantuml())
+
+    return cli

pyfcstm/model/__init__.py

@@ -0,0 +1,3 @@
+from .base import AstExportable, PlantUMLExportable
+from .expr import *
+from .model import *

pyfcstm/model/base.py

@@ -0,0 +1,51 @@
+"""
+Module for defining exportable interfaces for AST and PlantUML formats.
+
+This module provides abstract base classes that define interfaces for objects
+that can be exported to Abstract Syntax Tree (AST) nodes or PlantUML diagram
+representations.
+"""
+
+from ..dsl import node as dsl_nodes
+
+
+class AstExportable:
+    """
+    Abstract base class for objects that can be exported to AST nodes.
+
+    Classes that inherit from this interface should implement the to_ast_node
+    method to convert themselves into appropriate AST node representations.
+
+    :raises NotImplementedError: If the subclass does not implement the to_ast_node method.
+    """
+
+    def to_ast_node(self) -> dsl_nodes.ASTNode:
+        """
+        Convert the object to an AST node representation.
+
+        :return: An AST node representing this object
+        :rtype: dsl_nodes.ASTNode
+        :raises NotImplementedError: This is an abstract method that must be implemented by subclasses
+        """
+        raise NotImplementedError  # pragma: no cover
+
+
+class PlantUMLExportable:
+    """
+    Abstract base class for objects that can be exported to PlantUML format.
+
+    Classes that inherit from this interface should implement the to_plantuml
+    method to convert themselves into PlantUML diagram syntax.
+
+    :raises NotImplementedError: If the subclass does not implement the to_plantuml method.
+    """
+
+    def to_plantuml(self) -> str:
+        """
+        Convert the object to a PlantUML diagram representation.
+
+        :return: A string containing PlantUML syntax representing this object
+        :rtype: str
+        :raises NotImplementedError: This is an abstract method that must be implemented by subclasses
+        """
+        raise NotImplementedError  # pragma: no cover