Starting from 2021-07-01, all LRZ GitLab users will be required to explicitly accept the GitLab Terms of Service. Please see the detailed information at https://doku.lrz.de/display/PUBLIC/GitLab and make sure that your projects conform to the requirements.

Commit a0f52006 authored by eckhart's avatar eckhart
Browse files

- added module docstrings for error.py, log.py, stringview.py and toolkit.py

parent e05065a8
......@@ -15,6 +15,26 @@
# implied. See the License for the specific language governing
# permissions and limitations under the License.
"""
Module ``error`` defines class Error and a few helpful functions that are
needed for error reporting of DHParser. Usually, what is of interest are
the string representations of the error objects. For example::
from DHParser import compile_source, has_errors
result, errors, ast = compile_source(source, preprocessor, grammar,
transformer, compiler)
if errors:
for error in errors:
print(error)
if has_errors(errors):
print("There have been fatal errors!")
sys.exit(1)
else:
print("There have been warnings, but no errors.")
"""
import bisect
from typing import Iterable, Iterator, Union, Tuple, List
......
......@@ -14,21 +14,39 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied. See the License for the specific language governing
# permissions and limitations under the License.
#
#
# Module ``toolkit`` contains utility functions and cross-sectional
# functionality like logging support that is needed across several
# of the the other DHParser-Modules.
#
# For logging functionality, the global variable LOGGING is defined which
# contains the name of a directory where log files shall be placed. By
# setting its value to the empty string "" logging can be turned off.
#
# To read the directory name function ``LOGS_DIR()`` should be called
# rather than reading the variable LOGGING. ``LOGS_DIR()`` makes sure
# the directory exists and raises an error if a file with the same name
# already exists.
"""
Module ``log`` contains logging and debugging support for the
parsing process.
For logging functionality, the global variable LOGGING is defined which
contains the name of a directory where log files shall be placed. By
setting its value to the empty string "" logging can be turned off.
To read the directory name function ``LOGS_DIR()`` should be called
rather than reading the variable LOGGING. ``LOGS_DIR()`` makes sure
the directory exists and raises an error if a file with the same name
already exists.
For debugging of the parsing process, the parsing history can be
logged and written to an html-File.
For ease of use module ``log`` defines a context-manager ``logging``
to which either ``False`` (turn off logging), a log directory name or
``True`` for the default logging directory is passed as argument.
The other components of DHParser check whether logging is on and
write log files in the the logging directory accordingly. Usually,
this will be concrete and abstract syntax trees as well as the full
and abreviated parsing history.
Example::
from DHParser import compile_source, logging
with logging("LOGS"):
result, errors, ast = compile_source(source, preprocessor, grammar,
transformer, compiler)
"""
import collections
import contextlib
......
......@@ -18,14 +18,19 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied. See the License for the specific language governing
# permissions and limitations under the License.
#
# StringView provides string-slicing without copying.
# Slicing Python-strings always yields copies of a segment of the original
# string. See: https://mail.python.org/pipermail/python-dev/2008-May/079699.html
# However, this becomes costly (in terms of space and as a consequence also
# time) when parsing longer documents. Unfortunately, Python's `memoryview`
# does not work for unicode strings. Hence, the StringView class.
"""
StringView provides string-slicing without copying.
Slicing Python-strings always yields copies of a segment of the original
string. See: https://mail.python.org/pipermail/python-dev/2008-May/079699.html
However, this becomes costly (in terms of space and as a consequence also
time) when parsing longer documents. Unfortunately, Python's `memoryview`
does not work for unicode strings. Hence, the StringView class.
It is recommended to compile this modules with the Cython-compiler for
speedup. The modules comes with a ``stringview.pxd`` that contains some type
declarations to fully exploit the potential of the Cython-compiler.
"""
import collections
......
......@@ -14,22 +14,14 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied. See the License for the specific language governing
# permissions and limitations under the License.
#
#
# Module ``toolkit`` contains utility functions and cross-sectional
# functionality like logging support that is needed across several
# of the the other DHParser-Modules.
#
# For logging functionality, the global variable LOGGING is defined which
# contains the name of a directory where log files shall be placed. By
# setting its value to the empty string "" logging can be turned off.
#
# To read the directory name function ``LOGS_DIR()`` should be called
# rather than reading the variable LOGGING. ``LOGS_DIR()`` makes sure
# the directory exists and raises an error if a file with the same name
# already exists.
"""
Module ``toolkit`` contains utility functions that are needed across
several of the the other DHParser-Modules or that are just very generic
so that they are best defined in a toolkit-module.
"""
import codecs
import hashlib
import io
......
......@@ -82,7 +82,7 @@ class LyrikGrammar(Grammar):
JAHRESZAHL = /\d\d\d\d/~
ENDE = !/./
"""
source_hash__ = "5ceb5f91412cbe1bcd4dd8b7005598fb"
source_hash__ = "e4060274178d9c633c6dbfafb34471bd"
parser_initialization__ = "upon instantiation"
COMMENT__ = r''
WHITESPACE__ = r'[\t ]*'
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment