- compile.py: added CompilerError

DHParser/compile.py

@@ -47,6 +47,17 @@ from DHParser.toolkit import typing, sane_parser_name, load_if_file
 from typing import Any, Optional, Tuple, List
 
 
+__all__ = ('CompilerError', 'Compiler', 'compile_source')
+
+
+class CompilerError(Exception):
+    """Exception raised when an error of the compiler itself is detected.
+    Compiler errors are not to be confused with errors in the source
+    code to be compiled, which do not raise Exceptions but are merely
+    reported as an error."""
+    pass
+
+
 class Compiler:
     """
     Class Compiler is the abstract base class for compilers. Compiler
@@ -119,6 +130,9 @@ class Compiler:
     @staticmethod
     def propagate_error_flags(node: Node, lazy: bool = True) -> None:
         # See test_parser.TestCompilerClass.test_propagate_error()..
+        """Propagates error flags from children to parent nodes to make sure
+        that the parent's error flag is always greater or equal the maximum
+        of the children's error flags."""
         if not lazy or node.error_flag < Error.HIGHEST:
             for child in node.children:
                 Compiler.propagate_error_flags(child)
@@ -172,7 +186,9 @@ class Compiler:
             result = compiler(node)
             self.context.pop()
             if result is None:
-                raise ValueError('%s failed to return a valid compilation result!' % str(compiler))
+                raise CompilerError(('Method %s returned `None` instead of a '
+                                     'valid compilation result!')
+                                    % str(compiler))
             # # the following statement makes sure that the error_flag
             # # is propagated early on. Otherwise it is redundant, because
             # # the __call__ method globally propagates the node's error_flag
@@ -189,7 +205,7 @@ def compile_source(source: str,
                    compiler: Compiler) -> Tuple[Any, List[Error], Node]:  # Node (AST) -> Any
     """
     Compiles a source in four stages:
-    1. Preprocessing (if needed)
+    1. Pre-Processing (if needed)
     2. Parsing
     3. AST-transformation
     4. Compiling.

DHParser/dsl.py

@@ -23,19 +23,21 @@ compilation of domain specific languages based on an EBNF-grammar.
 
 
 import os
-from typing import Any, cast, List, Tuple, Union, Iterator, Iterable
 
+from DHParser.compile import Compiler, compile_source
 from DHParser.ebnf import EBNFCompiler, grammar_changed, \
     get_ebnf_preprocessor, get_ebnf_grammar, get_ebnf_transformer, get_ebnf_compiler, \
     PreprocessorFactoryFunc, ParserFactoryFunc, TransformerFactoryFunc, CompilerFactoryFunc
 from DHParser.error import Error, is_error, has_errors, only_errors
 from DHParser.log import logging
 from DHParser.parse import Grammar
-from DHParser import Compiler, compile_source, TransformationFunc
 from DHParser.preprocess import nil_preprocessor, PreprocessorFunc
 from DHParser.syntaxtree import Node
+from DHParser.transform import TransformationFunc
 from DHParser.toolkit import load_if_file, is_python_code, compile_python_object, \
-    re
+    re, typing
+from typing import Any, cast, List, Tuple, Union, Iterator, Iterable
+
 
 __all__ = ('DHPARSER_IMPORTS',
            'GrammarError',

DHParser/ebnf.py

@@ -27,19 +27,21 @@ conforming to this grammar into contrete syntax trees.
 import keyword
 from collections import OrderedDict
 from functools import partial
-from typing import Callable, Dict, List, Set, Tuple
 
+from DHParser.compile import CompilerError, Compiler
 from DHParser.error import Error
 from DHParser.parse import Grammar, mixin_comment, Forward, RegExp, RE, \
     NegativeLookahead, Alternative, Series, Option, OneOrMore, ZeroOrMore, Token
-from DHParser import Compiler, TransformationFunc
 from DHParser.preprocess import nil_preprocessor, PreprocessorFunc
 from DHParser.syntaxtree import Node, WHITESPACE_PTYPE, TOKEN_PTYPE
-from DHParser.toolkit import load_if_file, escape_re, md5, sane_parser_name, re, expand_table
-from DHParser.transform import traverse, remove_brackets, \
+from DHParser.toolkit import load_if_file, escape_re, md5, sane_parser_name, re, expand_table, \
+    typing
+from DHParser.transform import TransformationFunc, traverse, remove_brackets, \
     reduce_single_child, replace_by_single_child, remove_expendables, \
     remove_tokens, flatten, forbid, assert_content, remove_infix_operator
 from DHParser.versionnumber import __version__
+from typing import Callable, Dict, List, Set, Tuple
+
 
 __all__ = ('get_ebnf_preprocessor',
            'get_ebnf_grammar',
@@ -314,7 +316,7 @@ def get_compiler(grammar_name="{NAME}", grammar_source="") -> {NAME}Compiler:
 '''
 
 
-class EBNFCompilerError(Exception):
+class EBNFCompilerError(CompilerError):
     """Error raised by `EBNFCompiler` class. (Not compilation errors
     in the strict sense, see `CompilationError` in module ``dsl.py``)"""
     pass

DHParser/error.py

@@ -37,10 +37,11 @@ the string representations of the error objects. For example::
 
 
 import bisect
-from typing import Iterable, Iterator, Union, Tuple, List
 
 from DHParser.preprocess import SourceMapFunc
 from DHParser.stringview import StringView
+from DHParser.toolkit import typing
+from typing import Iterable, Iterator, Union, Tuple, List
 
 __all__ = ('Error',
            'is_error',

DHParser/log.py

@@ -52,12 +52,12 @@ import collections
 import contextlib
 import html
 import os
-from typing import List, Union
 
 from DHParser.error import line_col
 from DHParser.stringview import StringView
 from DHParser.syntaxtree import Node, WHITESPACE_PTYPE
-from DHParser.toolkit import is_filename, escape_control_characters
+from DHParser.toolkit import is_filename, escape_control_characters, typing
+from typing import List, Union
 
 __all__ = ('log_dir',
            'logging',

DHParser/preprocess.py

@@ -31,9 +31,10 @@ cannot completely be described with context-free grammars.
 import bisect
 import collections
 import functools
+
+from DHParser.toolkit import re, typing
 from typing import Union, Callable, Tuple, List
 
-from DHParser.toolkit import re
 
 __all__ = ('RX_TOKEN_NAME',
            'BEGIN_TOKEN',

DHParser/syntaxtree.py

@@ -29,7 +29,7 @@ import copy
 
 from DHParser.error import Error, linebreaks, line_col
 from DHParser.stringview import StringView
-from DHParser.toolkit import re
+from DHParser.toolkit import re, typing
 from typing import Callable, cast, Iterator, List, Union, Tuple, Optional
 
 

DHParser/transform.py

@@ -32,9 +32,8 @@ from functools import partial, reduce, singledispatch
 
 from DHParser.syntaxtree import Node, WHITESPACE_PTYPE, TOKEN_PTYPE, MockParser
 from DHParser.toolkit import expand_table, smart_list, re, typing
-
 from typing import AbstractSet, Any, ByteString, Callable, cast, Container, Dict, \
-    Iterator, List, NamedTuple, Sequence, Union, Text, Tuple
+    List, Sequence, Union, Text
 
 __all__ = ('TransformationDict',
            'TransformationProc',