empy-4.2.1/0000755000175000017500000000000015142227214012412 5ustar jriverojriveroempy-4.2.1/LICENSE.md.pre0000644000175000017500000000272314747330470014620 0ustar jriverojrivero# The 3-clause BSD license %COPYRIGHT% All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. empy-4.2.1/setup.py0000644000175000017500000000476715142227044014143 0ustar jriverojrivero#!/usr/bin/env python3 import sys if sys.version_info >= (3, 10): from setuptools import setup else: from distutils.core import setup PROGRAM = "empy" VERSION = "4.2.1" AUTHOR = "Erik Max Francis ".split(' <')[0] CONTACT = "software@alcyone.com" URL = "http://www.alcyone.com/software/empy/" LICENSE = "BSD" DESCRIPTION = "A templating system for Python." LONG_DESCRIPTION = """\ EmPy is a powerful, robust and mature templating system for inserting Python code in template text. EmPy takes a source document, processes it, and produces output. This is accomplished via expansions, which are signals to the EmPy system where to act and are indicated with markup. Markup is set off by a customizable prefix (by default the at sign, `@`). EmPy can expand arbitrary Python expressions, statements and control structures in this way, as well as a variety of additional special forms. The remaining textual data is sent to the output, allowing Python to be used in effect as a markup language. """ setup( name=PROGRAM, version=VERSION, author=AUTHOR, author_email=CONTACT, url=URL, license=LICENSE, python_requires=">=2.4", py_modules=[ "em", "emlib", "emhelp", "emdoc", ], scripts=[ "em.py", ], platforms="any", description=DESCRIPTION, long_description=LONG_DESCRIPTION, classifiers=[ "Development Status :: 6 - Mature", "Environment :: Console", "Intended Audience :: Developers", "Intended Audience :: Other Audience", "License :: OSI Approved :: BSD License", "Operating System :: OS Independent", "Programming Language :: Python :: 2", "Programming Language :: Python :: 3", "Programming Language :: Python :: Implementation :: CPython", "Programming Language :: Python :: Implementation :: IronPython", "Programming Language :: Python :: Implementation :: Jython", "Programming Language :: Python :: Implementation :: PyPy", "Programming Language :: Python :: Implementation :: Stackless", "Topic :: Software Development :: Interpreters", "Topic :: Software Development :: Libraries :: Python Modules", "Topic :: Software Development :: Pre-processors", "Topic :: Text Editors :: Text Processing", "Topic :: Text Processing :: Filters", "Topic :: Text Processing :: General", "Topic :: Text Processing :: Markup", "Topic :: Utilities", ], ) empy-4.2.1/emhelp.py0000644000175000017500000013534315072304205014245 0ustar jriverojrivero#!/usr/bin/env python3 """ Help subsystem for EmPy. """ # # imports # import sys import em # # Entry ... # class Entry(em.Root): """An entry in one of the usage tables. This exists to allow optional annotations or processing for each entry.""" def __init__(self, raw, right, var=None, val=None, env=None, arg=None, ord=None, ex=None, fun=None): """Create an entry for a help topic. Arguments are: - raw: The left side raw value: str | list[str] - right: The right side base value: str - var: The configuration variable, if any: Optional[str] - val: The boolean value of the variable, if any: Optional[bool] - env: The environment variable name, if any: Optional[str] - arg: The command line option arguments, if any: Optional[str] - ord: The Unicode code point value(s), if any: Optional[int | list[int]] - ex: A practical example, if any: Optional[str] - fun: An optional function to format the resulting string: Optional[Callable] - sim: Whether or not the option entry is simple (-x): bool """ self.raw = raw self.left = self.format(raw) self.right = right self.var = var self.val = val self.env = env self.arg = arg if isinstance(ord, int): ord = [ord] self.ords = ord self.ex = ex self.fun = fun if isinstance(self.raw, list): self.sim = self.raw[0] != ' ' else: self.sim = False def __str__(self): if self.ords is None: ords = '--' else: ords = ' '.join([hex(x) for x in self.ords]) return '%s [%s]' % (self.left, ords) def key(self): return (self.ords, self.left) def format(self, raw): """Format the raw list. Override in subclasses.""" if isinstance(raw, list): return ' '.join(raw) else: return raw class NameEntry(Entry): """An entry tailored to a name.""" def key(self): return self.left class OptionEntry(Entry): """An entry tailored to an option.""" def format(self, raw): if isinstance(raw, list): assert len(raw) > 0 if raw[0].startswith('--'): raw.insert(0, ' ') return ' '.join(raw) else: return raw class ControlEntry(Entry): """An entry tailored to a control (named escape).""" def key(self): name = self.left if name.isdigit(): name = '_' + name return (self.ords, name) # # Section ... # class Section(em.Root): """A section in one of the usage tables.""" def __init__(self, topic, description, header): self.topic = topic self.description = description self.header = header def __str__(self): return self.topic def ok(self): return True def show(self, usage, useSeparator=True): if not self.ok(): return if useSeparator: usage.separator() usage.write("%s:\n" % self.topic.upper()) usage.write(self.header) self.block(usage) def block(self, usage): pass class TableSection(Section): """A section with a block that consists of a flat table of entries.""" def __init__(self, topic, description, header, entries): super(TableSection, self).__init__(topic, description, header) self.entries = entries def ok(self): return bool(self.entries) def block(self, usage): usage.table(self.entries) class ConfigSection(TableSection): """A section with a block that consists of each configuration variable.""" def __init__(self, topic, description, header, config): super(ConfigSection, self).__init__(topic, description, header, []) for left in config._names: right = config._descriptions[left] fun = config._functions[left] entry = Entry(left, right, var=left, fun=fun) self.entries.append(entry) class MappingSection(TableSection): """A section with a block that consists of a mapping type which is transformed into a table of entries.""" def __init__(self, topic, description, header, mapping, factory=Entry): super(MappingSection, self).__init__(topic, description, header, []) for key, value in mapping.items(): if value is None: continue # Value can be an ordinal, a string, or a 2-tuple of (ordinal, # name). if isinstance(value, tuple): ordinal, right = value else: ordinal = None right = value if isinstance(ordinal, (em.bytes, em.str)): ordinal = ord(ordinal) if isinstance(right, int): right = em.chr(right) elif isinstance(right, list): right = ''.join([em.chr(x) for x in right]) entry = factory(key, right, ord=ordinal) self.entries.append(entry) self.entries.sort(key=lambda x: x.key()) class HelpSection(TableSection): """A section with a block that consists of the help topics.""" def __init__(self, topic, description, header, usage): super(HelpSection, self).__init__(topic, description, header, []) self.usage = usage def refresh(self): """Refresh the list of topics. At creation time it won't contain itself.""" payload = self.usage.payload all = Usage.aliases['all'] for topic in all: if topic in payload: section = payload[topic] if section.ok(): self.entries.append( Entry(section.topic, section.description)) # # Usage # class Usage(em.Root): """A utility class to print usage and extended help.""" aliases = { # Groups 'default': ['usage', 'options', 'markup', 'hints', 'topics'], 'more': ['usage', 'options', 'markup', 'escapes', 'environ', 'hints', 'topics'], 'all': ['usage', 'options', 'simple', 'markup', 'escapes', 'environ', 'pseudo', 'constructor', 'variables', 'methods', 'hooks', 'named', 'diacritics', 'icons', 'emojis', 'hints', 'topics'], # Aliases 'accents': ['diacritics'], 'config': ['variables', 'methods'], 'control': ['named'], 'controls': ['named'], 'ctor': ['constructor'], 'diacritic': ['diacritics'], 'emoji': ['emojis'], 'escape': ['escapes'], 'flags': ['options'], 'hint': ['hints'], 'hook': ['hooks'], 'icon': ['icons'], 'markups': ['markup'], 'method': ['methods'], 'option': ['options'], 'optional': ['emojis'], 'switches': ['options'], 'topic': ['topics'], 'variable': ['variables'], } defaultWidth = 6 columns = None # 81 dottedCircle = '\N{DOTTED CIRCLE}' def __init__(self, config=None, file=None): if config is None: config = em.Configuration() self.config = config if file is None: file = sys.stdout self.file = file self.payload = {} prepare(self) self.fix() def format(self, width): return ' %%-%ds %%s\n' % max(width, Usage.defaultWidth) def transform(self, topics): """Transform a list of possible topics into a list of valid topics.""" if topics is None: topics = 'default' results = [] if not isinstance(topics, list): topics = [topics] for topic in topics: topic = topic.lower() if topic in Usage.aliases: results.extend(Usage.aliases[topic]) else: results.append(topic) return results def add(self, section): """Add a section to the payload.""" assert section.topic not in self.payload self.payload[section.topic] = section def fix(self): """Fix the payload.""" self.payload['topics'].refresh() def separator(self): """Write a separator.""" self.write("\n") def write(self, string): """Write a string (with the correct prefix substitution).""" if not self.config.hasDefaultPrefix(): string = string.replace(self.config.defaultPrefix, self.config.prefix) self.file.write(string) def flush(self): """Flush the underlying stream.""" self.file.flush() def scan(self, table): """Scan a table to find the minimum column width.""" result = 0 for entry in table: left = entry.left if len(left) > result: result = len(left) return result def preview(self, ords): """Return a preview of the (non-text) character ordinals, or None.""" if ords is None: return if em.major < 3 or not sys.stdout.encoding.lower().startswith('utf'): # Don't bother if this isn't Python 3.x or the encoding isn't # UTF-8. return firstOrd = ords[0] chars = ''.join([chr(x) for x in ords]) while not chars.isprintable(): # Some emoji blocks report as unprintable in various versions of # Python. (This is implemented as a while loop with breaks ending # in a return to make it easier to edit.) if firstOrd >= 0x2300 and firstOrd < 0x2400: break if firstOrd >= 0x2600 and firstOrd < 0x2c00: break if firstOrd >= 0x1f000 and firstOrd < 0x1fb00: break return if chars.isspace(): return if firstOrd == 0x034f: # Combining grapheme joiner. return if firstOrd >= 0xfe00 and firstOrd < 0xfe10: # Variation selectors 1-16. return if firstOrd == 0xfffc: # Object replacement character. return if firstOrd >= 0xe0100 and firstOrd < 0xe01f0: # Variation selectors 17-256. return if firstOrd >= 0x0300 and firstOrd < 0x0370: # Combining diacritical marks. chars = self.dottedCircle + chars if firstOrd >= 0x1ab0 and firstOrd < 0x1b00: # Combining diacritical marks extended. chars = self.dottedCircle + chars if firstOrd >= 0x1dc0 and firstOrd < 0x1e00: # Combining diacritical marks supplemental. chars = self.dottedCircle + chars if firstOrd >= 0x20d0 and firstOrd < 0x2100: # Combining diacritical marks for symbols. chars = self.dottedCircle + chars return chars def entry(self, entry, format): """Print a table entry.""" def _identity(x): return x left = entry.left lines = entry.right.split('\n') fun = entry.fun or _identity i = 0 for line in lines: last = i == len(lines) - 1 fragments = [] if entry.ords is not None: first = True for x in entry.ords: if first: first = False else: fragments.append(' ') fragments.append("U+%04X" % x) fragments.append("; ") fragments.append(line) if last: if entry.arg is not None: fragments.append(": %s" % fun(entry.arg)) if entry.var is not None and entry.val is None: value = fun(getattr(self.config, entry.var)) if isinstance(value, dict): value = "{%d}" % len(value) fragments.append(" [%s]" % str(value)) if entry.ex is not None: fragments.append(" (e.g., %s)" % fun(entry.ex)) preview = self.preview(entry.ords) if preview: fragments.append(': ') fragments.append(preview) right = ''.join(fragments).strip() line = format % (left, right) assert self.columns is None or len(line) < self.columns, line self.write(line) left = '' i += 1 def table(self, table): """Print a table at the current level with an optional header.""" width = self.scan(table) format = self.format(width) for entry in table: self.entry(entry, format) def hello(self): self.write("Welcome to %s version %s.\n" % ( em.__project__, em.__version__)) def show(self, topics=None, useSeparator=True): """Show usage.""" if topics is None: topics = 'default' topics = self.transform(topics) flag = False for topic in topics: topic = topic.lower() if topic in self.payload: section = self.payload[topic] if section.ok(): section.show(self, useSeparator) flag = True else: self.write("*** Unknown usage topic: %s\n" % topic) if not flag: self.write("*** No active topics found\n") # # functions # def prepare(usage, executable=None): """Lazily initialize the usage data and tables only if they're actually needed. This is a standalone function so there's less misleading indentation. Idempotent.""" if executable is None: executable = sys.argv[0] payload = usage.payload if payload: return payload E = Entry OE = OptionEntry usage.add(Section( 'usage', "Basic command line usage", """\ %s [] [ [...]] - Options begin with `-` or `--` - Specify a filename (and arguments) to process that document as input - Specify `-` (and arguments) to process stdin with standard buffering - Specify no filename to enter interactive mode with line buffering - Specify `--` to stop processing options """ % executable)) usage.add(Section( 'hints', "Usage hints", """\ Whitespace immediately inside parentheses of `@(...)` are ignored. Whitespace immediately inside braces of `@{...}` are ignored, unless ... spans multiple lines. Use `@{ ... }@` to suppress newline following second `@`. Simple expressions ignore trailing punctuation; `@x.` means `@(x).`, not a parse error. A `#!` at the start of a file is treated as a comment. The full documentation is available at <%s>. """ % em.__url__)) usage.add(TableSection( 'options', "Command line options", """\ Valid command line options (defaults in brackets): """, [ OE(["-V", "--version"], "Print version"), OE(["-W", "--info"], "Print version and system information"), OE(["-Z", "--details"], "Print extensive system and platform details"), OE(["-h", "--help"], "Print help; more -h options for more help"), OE(["-H", "--topics=TOPICS"], "Print usage for comma-separated topics"), OE(["-v", "--verbose"], "Show verbose debugging while processing"), OE(["-p", "--prefix=CHAR"], "Choose desired prefix", var='prefix', env=em.PREFIX_ENV), OE(["--no-prefix"], "Do not do any markup processing at all"), OE(["-q", "--no-output"], "Suppress all output"), OE(["-m", "--pseudomodule=NAME"], "Change internal pseudomodule name", var='pseudomoduleName', env=em.PSEUDO_ENV), OE(["-f", "--flatten"], "Flatten pseudomodule members at start", var='doFlatten', env=em.FLATTEN_ENV, val=True), OE(["-k", "--keep-going"], "Don't exit on errors; continue", var='exitOnError', val=False), OE(["-e", "--ignore-errors"], "Ignore errors completely", var='ignoreErrors', val=True), OE(["-r", "--raw-errors"], "Show full tracebacks of Python errors", var='rawErrors', env=em.RAW_ERRORS_ENV, val=True), OE(["-s", "--brief-errors"], "Don't show attributes when formatting errors", var='verboseErrors', val=False), OE(["--verbose-errors"], "Show attributes when formatting errors (default)", var='verboseErrors', val=True), OE(["-i", "--interactive"], "Enter interactive mode after processing", var='goInteractive', env=em.INTERACTIVE_ENV, val=True), OE(["-d", "--delete-on-error"], "Delete output file on error\n" "(-o or -a needed)", var='deleteOnError', env=em.DELETE_ON_ERROR_ENV), OE(["-n", "--no-proxy"], "Do not override sys.stdout with proxy", var='useProxy', env=em.NO_PROXY_ENV), OE(["--config=STATEMENTS"], "Do configuration variable assignments"), OE(["-c", "--config-file=FILENAME"], "Load configuration resource path(s)", env=em.CONFIG_ENV), OE(["--config-variable=NAME"], "Configuration variable name while loading", var='configVariableName'), OE(["-C", "--ignore-missing-config"], "Don't raise for missing configuration files", var='missingConfigIsError', val=False), OE(["-o", "--output=FILENAME"], "Specify file for output as write"), OE(["-a", "--append=FILENAME"], "Specify file for output as append"), OE(["-O", "--output-binary=FILENAME"], "Specify file for binary output as write"), OE(["-A", "--append-binary=FILENAME"], "Specify file for binary output as append"), OE(["--output-mode=MODE"], "Explicitly specify the mode for output"), OE(["--input-mode=MODE"], "Explicitly specify the mode for input"), OE(["-b", "--buffering"], "Specify buffering strategy for files:\n" "none (= 0), line (= 1), full (= -1), default,\n" "or another value for fixed", var='buffering', env=em.BUFFERING_ENV), OE(["--default-buffering"], "Specify default buffering for files (default)"), OE(["-N", "--no-buffering"], "Specify no buffering for reads on files"), OE(["-L", "--line-buffering"], "Specify line buffering for files"), OE(["-B", "--full-buffering"], "Specify full buffering for files"), OE(["-I", "--import=MODULES"], "Import Python modules before processing"), OE(["-D", "--define=DEFN"], "Execute Python assignment statement"), OE(["-S", "--string=STR"], "Execute string literal assignment"), OE(["-P", "--preprocess=FILENAME"], "Interpret EmPy file before main document"), OE(["-Q", "--postprocess=FILENAME"], "Interpret EmPy file after main document"), OE(["-E", "--execute=STATEMENT"], "Execute Python statement before main document"), OE(["-K", "--postexecute=STATEMENT"], "Execute Python statement after main document"), OE(["-F", "--file=FILENAME"], "Execute Python file before main document"), OE(["-G", "--postfile=FILENAME"], "Execute Python file after main document"), OE(["-X", "--expand=MARKUP"], "Expand EmPy markup before main document"), OE(["-Y", "--postexpand=MARKUP"], "Expand EmPy markup after main document"), OE(["--preinitializer=FILENAME"], "Execute Python file before interpreter"), OE(["--postinitializer=FILENAME"], "Execute Python file after interpreter"), OE(["-w", "--pause-at-end"], "Prompt at the end of processing", var='pauseAtEnd'), OE(["-l", "--relative-path"], "Add path of EmPy script to sys.path", var='relativePath'), OE(["--replace-newlines"], "Replace expression newlines with spaces (default)", var='replaceNewlines', val=True), OE(["--no-replace-newlines"], "Don't replace expression newlines with spaces", var='replaceNewlines', val=False), OE(["--ignore-bangpaths"], "Treat bangpaths as comments (default)", var='ignoreBangpaths', val=True), OE(["--no-ignore-bangpaths"], "Don't treat bangpaths as comments", var='ignoreBangpaths', val=False), OE(["--expand-user"], "Expand user constructions (~user) in paths (default)", var='expandUserConstructions', val=True), OE(["--no-expand-user"], "Don't expand user constructions in paths", var='expandUserConstructions', val=False), OE(["--auto-validate-icons"], "Auto-validate icons on first use (default)", var='autoValidateIcons', val=True), OE(["--no-auto-validate-icons"], "Don't auto-validate icons on first use", var='autoValidateIcons', val=False), OE(["--none-symbol"], "String to write when expanding None", var='noneSymbol'), OE(["--no-none-symbol"], "Write nothing when expanding None (default)"), OE(["--starting-line"], "Line number to start with", var='startingLine'), OE(["--starting-column"], "Column number to start with", var='startingColumn'), OE(["--emoji-modules"], "Comma-separated list of emoji modules to try\n", var='emojiModuleNames', fun=lambda x: ','.join(x)), OE(["--no-emoji-modules"], "Only use unicodedata for emoji markup"), OE(["--disable-emoji-modules"], "Disable emoji modules; use emojis dictionary"), OE(["--ignore-emoji-not-found"], "Emoji not found is not an error", var='emojiNotFoundIsError', val=False), OE(["-u", "--binary", "--unicode"], "Read input file as binary?\n" "(enables Unicode support in Python 2.x)", var='useBinary', env=em.BINARY_ENV), OE(["-x", "--encoding=E"], "Set both input and output Unicode encodings"), OE(["--input-encoding=E"], "Set input Unicode encoding", var='inputEncoding', env=em.INPUT_ENCODING_ENV, fun=lambda x: x == 'utf_8' and 'utf-8' or x), OE(["--output-encoding=E"], "Set output Unicode encoding", var='outputEncoding', env=em.OUTPUT_ENCODING_ENV, fun=lambda x: x == 'utf_8' and 'utf-8' or x), OE(["-y", "--errors=E"], "Set both input and output Unicode error handler"), OE(["--input-errors=E"], "Set input Unicode error handler", var='inputErrors', env=em.INPUT_ERRORS_ENV), OE(["--output-errors=E"], "Set output Unicode error handler", var='outputErrors', env=em.OUTPUT_ERRORS_ENV), OE(["-z", "--normalization-form=F"], "Specify Unicode normalization form", var='normalizationForm'), OE(["--auto-play-diversions"], "Autoplay diversions on exit (default)", var='autoPlayDiversions', val=True), OE(["--no-auto-play-diversions"], "Don't autoplay diversions on exit", var='autoPlayDiversions', val=False), OE(["--check-variables"], "Validate configuration variables (default)", var='checkVariables', val=True), OE(["--no-check-variables"], "Don't validate configuration variables", var='checkVariables', val=False), OE(["--path-separator"], "Path separator for configuration paths", var='pathSeparator'), OE(["--enable-modules"], "Enable EmPy module support (default)", var='supportModules', val=True), OE(["-g", "--disable-modules"], "Disable EmPy module support", var='supportModules', val=False), OE(["--module-extension"], "Filename extension for EmPy modules", var='moduleExtension'), OE(["--module-finder-index"], "Index of module finder in meta path", var='moduleFinderIndex'), OE(["--enable-import-output"], "Enable output during import (default)", var='enableImportOutput', val=True), OE(["-j", "--disable-import-output"], "Disable output during import", var='enableImportOutput', val=False), OE(["--context-format"], "Context format", var='contextFormat'), OE(["--success-code=N"], "Exit code to return on script success", var='successCode'), OE(["--failure-code=N"], "Exit code to return on script failure", var='failureCode'), OE(["--unknown-code=N"], "Exit code to return on bad configuration", var='unknownCode'), ])) usage.add(TableSection( 'simple', "Simple (one-letter) command line options", """\ Short (single letter) command line options: """, sorted([x for x in usage.payload['options'].entries if x.sim], key=lambda x: x.raw[0].swapcase()))) usage.add(TableSection( 'markup', "Markup syntax", """\ The following markups are supported (NL means newline; WS means whitespace): """, [ E("@# ... NL", "Line comment; consume everything including newline"), E("@* ... *", "Inline comment; consume everything inside"), E("@ WS", "Ignore whitespace; line continuation"), E("@- ... NL", "Disable output; consume up to trailing newline"), E("@+ ... NL", "Enable output; consume up to trailing newline"), E("@@", "Literal @; @ is escaped (duplicated prefix)"), E("@' STRING '", "Replace with string literal contents"), E("@\" STRING \"", "Replace with string literal contents"), E("@''' STRING ... '''", "Replace with multiline string literal contents"), E("@\"\"\" STRING ... \"\"\"", "Replace with multiline string literal contents"), E("@` LITERAL `", "Write everything inside literally (no expansion)"), E("@( EXPRESSION )", "Evaluate expression and substitute with str"), E("@( TEST ? THEN )", "If test, evaluate then, otherwise do nothing"), E("@( TEST ? THEN ! ELSE )", "If test, evaluate then, otherwise evaluate else;\n" "can be chained with repeated test/then/[else]"), E("@( TRY $ EXCEPT )", "Evaluate try expression, or except if it raises"), E("@ SIMPLE_EXPRESSION", "Evaluate simple expression and substitute\n", ex="@x, @x.y, @f(a, b), @l[i], @f{...}, etc."), E("@$ EXPRESSION $ [DUMMY] $", "Evaluates to @$ EXPRESSION $ EXPANSION $"), E("@{ STATEMENTS }", "Statements are executed for side effects"), E("@[ CONTROL ]", "Control markups: if E; elif E; for N in E;\n" "while E; dowhile E; try; except E as N; finally;\n" "continue; break; else; with E as N; match E;\n" "case E; defined N; def F(...); end X"), E("@\\ ESCAPE_CODE", "A C-style escape sequence"), E("@\\^{ NAMED_ESCAPE }", "A named escape sequence", ex="ESC for escape"), E("@^ CHAR DIACRITIC(S)", "A two-part diacritic sequence\n", ex="e' for an e with acute accent"), E("@| ICON", "A custom icon sequence\n", ex=":) for a smiley face emoji"), E("@: EMOJI :", "Lookup emoji by name"), E("@% KEY NL", "Significator form of __KEY__ = None"), E("@% KEY WS VALUE NL", "Significator form of __KEY__ = VALUE"), E("@%! KEY NL", "Significator form of __KEY__ = \"\""), E("@%! KEY WS STRING NL", "Stringized significator form: __KEY__ = \"STRING\""), E("@%% KEY WS VALUE %% NL", "Multiline significator form"), E("@%%! KEY WS STRING %% NL", "Multiline stringized significator form"), E("@? NAME NL", "Set the current context name"), E("@! INTEGER NL", "Set the current context line number"), E("@(( ... )), @[[ ... ]],", "Extension markup; implementation provided by user"), E("@{{ ... }}, @< ... >", ""), ])) usage.add(TableSection( 'escapes', "Escape sequences", """\ Valid escape sequences are: """, [ E("@\\0", "NUL, null", ord=0x0), E("@\\a", "BEL, bell", ord=0x7), E("@\\b", "BS, backspace", ord=0x8), E("@\\B{BIN}", "freeform binary code BIN", ex="{1000001} for A"), E("@\\dDDD", "three-digit decimal code DDD", ex="065 for A"), E("@\\D{DEC}", "freeform decimal code DEC", ex="{65} for A"), E("@\\e", "ESC, escape", ord=0x1b), E("@\\f", "FF, form feed", ord=0xc), E("@\\h", "DEL, delete", ord=0x7f), E("@\\k", "ACK, acknowledge", ord=0x6), E("@\\K", "NAK, negative acknowledge", ord=0x15), E("@\\n", "LF, linefeed; newline", ord=0xa), E("@\\N{NAME}", "Unicode character named NAME", ex="LATIN CAPITAL LETTER A"), E("@\\oOOO", "three-digit octal code OOO", ex="101 for A"), E("@\\O{OCT}", "freeform octal code OCT", ex="{101} for A"), E("@\\qQQQQ", "four-digit quaternary code QQQQ", ex="1001 for A"), E("@\\Q{QUA}", "freeform quaternary code QUA", ex="{1001} for A"), E("@\\r", "CR, carriage return", ord=0xd), E("@\\s", "SP, space", ord=0x20), E("@\\S", "NBSP, no-break space", ord=0xa0), E("@\\t", "HT, horizontal tab", ord=0x9), E("@\\uHHHH", "16-bit hexadecimal Unicode HHHH", ex="0041 for A"), E("@\\UHHHHHHHH", "32-bit hexadecimal Unicode HHHHHHHH", ex="00000041 for A"), E("@\\v", "VT, vertical tab", ord=0xb), E("@\\V{VS}", "VS, variation selector (1 .. 256)", ex="16 for emoji display"), E("@\\w", "VS15, variation selector 15; text display", ord=0xfe0e), E("@\\W", "VS16, variation selector 16; emoji display", ord=0xfe0f), E("@\\xHH", "8-bit hexadecimal code HH", ex="41 for A"), E("@\\X{HEX}", "freeform hexadecimal code HEX", ex="{41} for A"), E("@\\y", "SUB, substitution", ord=0x1a), E("@\\Y", "RC, replacement character", ord=0xfffd), E("@\\z", "EOT, end of transmission", ord=0x4), E("@\\Z", "ZWNBSP/BOM, zero-width no-break space/byte order mark", ord=0xfeff), E("@\\,", "THSP, thin space", ord=0x2009), E("@\\^C", "Control character C", ex="[ for ESC"), E("@\\^{NAME}", "Escape named NAME (control character)", ex="ESC"), E("@\\(", "Literal (", ord=0x28), E("@\\)", "Literal )", ord=0x29), E("@\\[", "Literal [", ord=0x5b), E("@\\]", "Literal ]", ord=0x5d), E("@\\{", "Literal {", ord=0x7b), E("@\\}", "Literal }", ord=0x7d), E("@\\<", "Literal <", ord=0x3c), E("@\\>", "Literal >", ord=0x3e), E("@\\\\", "Literal \\", ord=0x5c), E("@\\'", "Literal '", ord=0x27), E("@\\\"", "Literal \"", ord=0x22), E("@\\?", "Literal ?", ord=0x3f), ])) usage.add(TableSection( 'environ', "Environment variables", """\ The following environment variables are recognized (with corresponding command line arguments): """, [ E(em.OPTIONS_ENV, "Specify additional options to be included"), E(em.CONFIG_ENV, "Specify configuration file(s) to load", arg='-c PATHS'), E(em.PREFIX_ENV, "Specify the default prefix", arg='-p PREFIX'), E(em.PSEUDO_ENV, "Specify name of pseudomodule", arg='-m NAME'), E(em.FLATTEN_ENV, "Flatten empy pseudomodule if defined", arg='-f'), E(em.RAW_ERRORS_ENV, "Show raw errors if defined", arg='-r'), E(em.INTERACTIVE_ENV, "Enter interactive mode if defined", arg='-i'), E(em.DELETE_ON_ERROR_ENV, "Delete output file on error", arg='-d'), E(em.NO_PROXY_ENV, "Do not install sys.stdout proxy if defined", arg='-n'), E(em.BUFFERING_ENV, "Buffer size (-1, 0, 1, or n)", arg='-b VALUE'), E(em.BINARY_ENV, "Open input file as binary (for Python 2.x Unicode)", arg='-u'), E(em.ENCODING_ENV, "Unicode both input and output encodings"), E(em.INPUT_ENCODING_ENV, "Unicode input encoding"), E(em.OUTPUT_ENCODING_ENV, "Unicode output encoding"), E(em.ERRORS_ENV, "Unicode both input and output error handlers"), E(em.INPUT_ERRORS_ENV, "Unicode input error handler"), E(em.OUTPUT_ERRORS_ENV, "Unicode output error handler"), ])) usage.add(TableSection( 'pseudo', "Pseudomodule attributes and functions", """\ The %s pseudomodule contains the following attributes and methods: """ % usage.config.pseudomoduleName, [ E("version", "String representing EmPy version"), E("compat", "List of applied Python compatibility features"), E("executable", "The EmPy executable"), E("argv", "EmPy script name and command line arguments"), E("config", "The configuration for this interpreter"), E("ok", "Is the interpreter still active?"), E("error", "The last error to occur, or None"), E("__init__(**kwargs)", "The interpreter constructor"), E("__enter__/__exit__(...)", "Context manager support"), E("reset()", "Reset the interpreter state"), E("ready()", "Declare the interpreter ready"), E("shutdown()", "Shutdown the interpreter"), E("write(data)", "Write data to stream"), E("writelines(lines)", "Write a sequence of lines to stream"), E("flush()", "Flush the stream"), E("serialize(object)", "Write a string version of the object"), E("top() -> Stream", "Get the top-level stream"), E("push()", "Push this interpreter on the stream stack"), E("pop()", "Pop this interpreter off the stream stack"), E("clear()", "Clear the interpreter stacks"), E("go(fname, mode, [pre, [post]])", "Process a file by filename"), E("interact()", "Enter interactive mode"), E("file(file, [loc])", "Process a file object"), E("fileLine(file, [loc])", "Process a file object in lines"), E("fileChunk(file, buf, [loc]])", "Process a file in chunks"), E("fileFull(file, [loc]])", "Process a file as a single chunk"), E("process(command)", "Process a command"), E("processAll(commands)", "Process a sequence of commands"), E("identify()", "Identify top context as name, line"), E("getContext()", "Return the current context"), E("newContext(...)", "Return a new context with name and counts"), E("pushContext(context)", "Push a context"), E("popContext()", "Pop the current context"), E("setContext(context)", "Replace the current context"), E("setContextName(name)", "Set the name of the current context"), E("setContextLine(line)", "Set the line number of the current context"), E("setContextColumn(column)", "Set the column number of the current context"), E("setContextData(...)", "Set any of the name, line, column number"), E("restoreContext(context)", "Replace the top context with an existing one"), E("clearFinalizers()", "Clear all finalizers"), E("appendFinalizer(finalizer)", "Append function to be called at shutdown"), E("prependFinalizer(finalizer)", "Prepend function to be called at shutdown"), E("setFinalizers(finalizers)", "Set functions to be called at shutdown"), E("getGlobals()", "Retrieve this interpreter's globals"), E("setGlobals(dict)", "Set this interpreter's globals"), E("updateGlobals(dict)", "Merge dictionary into interpreter's globals"), E("clearGlobals()", "Start globals over anew"), E("saveGlobals([deep])", "Save a copy of the globals"), E("restoreGlobals([pop])", "Restore the most recently saved globals"), E("include(file, [loc])", "Include filename or file-like object"), E("expand(string, [loc])", "Explicitly expand string and return"), E("defined(name, [loc])", "Find if the name is defined"), E("lookup(name, [loc])", "Lookup the variable name"), E("evaluate(expression, [loc])", "Evaluate the expression (and write?)"), E("execute(statements, [loc])", "Execute the statements"), E("single(source, [loc])", "Execute the expression or statement"), E("atomic(name, value, [loc])", "Perform an atomic assignment"), E("assign(name, value, [loc])", "Perform an arbitrary assignment"), E("significate(key, [value])", "Significate the given key, value pair"), E("quote(string)", "Quote prefixes in provided string and return"), E("escape(data)", "Escape EmPy markup in data and return"), E("flatten([keys])", "Flatten module contents to globals namespace"), E("getPrefix()", "Get current prefix"), E("setPrefix(char)", "Set new prefix"), E("stopDiverting()", "Stop diverting; data sent directly to output"), E("createDiversion(name)", "Create a diversion but do not divert to it"), E("retrieveDiversion(name, [def])", "Retrieve the actual named diversion object"), E("startDiversion(name)", "Start diverting to given diversion"), E("playDiversion(name)", "Recall diversion and then eliminate it"), E("replayDiversion(name)", "Recall diversion but retain it"), E("dropDiversion(name)", "Drop diversion"), E("playAllDiversions()", "Stop diverting and play all diversions"), E("replayAllDiversions()", "Stop diverting and replay all diversions"), E("dropAllDiversions()", "Stop diverting and drop all diversions"), E("getCurrentDiversionName()", "Get the name of the current diversion"), E("getAllDiversionNames()", "Get a sorted sequence of diversion names"), E("isExistingDiversionName(name)", "Is this the name of a diversion?"), E("getFilter()", "Get the first filter in the current chain"), E("getLastFilter()", "Get the last filter in the current chain"), E("getFilterCount()", "Get the number of filters in current chain"), E("resetFilter()", "Reset filter; no filtering"), E("setFilter(filter...)", "Install new filter(s), replacing any chain"), E("prependFilter(filter)", "Prepend filter to beginning of current chain"), E("appendFilter(filter)", "Append a filter to end of current chain"), E("setFilterChain(filters)", "Install a new filter chain"), E("areHooksEnabled()", "Return whether or not hooks are enabled"), E("enableHooks()", "Enable hooks (default)"), E("disableHooks()", "Disable hook invocation"), E("getHooks()", "Get all the hooks"), E("appendHook(hook)", "Append the given hook"), E("prependHook(hook)", "Prepend the given hook"), E("removeHook(hook)", "Remove an already-registered hook"), E("clearHooks()", "Clear all hooks"), E("invokeHook(_name, ...)", "Manually invoke hook"), E("hasCallback()", "Is there a custom callback?"), E("getCallback()", "Get custom callback"), E("registerCallback(callback)", "Register custom callback"), E("deregisterCallback()", "Deregister custom callback"), E("invokeCallback(contents)", "Invoke the custom callback directly"), E("defaultHandler(t, e, tb)", "The default error handler"), E("getHandler()", "Get the current error handler (or None)"), E("setHandler(handler, [eoe])", "Set the error handler"), E("resetHandler([eoe])", "Reset the error handler"), E("invokeHandler(t, e, tb)", "Manually invoke the error handler"), E("initializeEmojiModules(names)", "Initialize the emoji modules"), E("getEmojiModule(name)", "Get an abstracted emoji module"), E("getEmojiModuleNames()", "Return the list of emoji module names"), E("substituteEmoji(text)", "Do an emoji substitution"), ])) usage.add(TableSection( 'constructor', "Keyword arguments for the Interpreter constructor", """\ The following keyword arguments for the Interpreter constructor are supported (defaults in brackets). All arguments have meaningful defaults: """, [ E("argv", "The system arguments to use ['<->']"), E("callback", "A custom callback to register [None]"), E("config", "The configuration object [default]"), E("core", "The core to use for this interpreter [Core()]"), E("dispatcher", "Dispatch errors or raise to caller? [True]"), E("executable", "The path to the EmPy executable [\".../em.py\"]"), E("extension", "The extension to automatically install [None]"), E("filespec", "A 3-tuple of the input filename, mode, and buffering [None]"), E("filters", "The list of filters to install [[]]"), E("finalizers", "The list of finalizers to installed [[]]"), E("globals", "The globals dictionary to use [{}]"), E("handler", "The error handler to use [default]"), E("hooks", "The list of hooks to install [[]]"), E("ident", "The identifier for the interpreter [None]"), E("immediately", "Declare the interpreter ready after initialization? [True]"), E("input", "The input file to use for interactivity [sys.stdin]"), E("output", "The output file to use [sys.stdout]"), E("root", "The root interpreter context filename ['']"), ])) usage.add(ConfigSection( 'variables', "Configuration variable attributes", """\ The following configuration variable attributes are supported (defaults in brackets, with dictionaries being summarized with their length): """, usage.config)) usage.add(TableSection( 'methods', "Configuration methods", """\ The configuration instance contains the following methods: """, [ E("initialize()", "Initialize the instance"), E("shutdown()", "Shutdown the instance"), E("isInitialize()", "Is this configuration initialized?"), E("pauseIfRequired()", "Pause if required"), E("check(in, out)", "Check file settings"), E("has(name)", "Is this variable defined?"), E("get(name[, default])", "Get this variable value"), E("set(name, value)", "Set this variable"), E("update(**kwargs)", "Update with dictionary"), E("clone([deep])", "Clone (optionally deep) this configuration"), E("run(statements)", "Run configuration commands"), E("load(filename, [required])", "Load configuration file"), E("path(filename, [required])", "Load configuration file(s) path"), E("hasEnvironment(name)", "Is this environment variable defined?"), E("environment(name, ...)", "Get the enviroment variable value"), E("hasDefaultPrefix()", "Is the prefix the default?"), E("hasFullBuffering()", "Is the buffering set to full?"), E("hasNoBuffering()", "Is the buffering set to none?"), E("hasLineBuffering()", "Is the buffering set to line?"), E("hasFixedBuffering()", "Is the buffering set to fixed?"), E("createFactory([tokens])", "Create token factory"), E("adjustFactory()", "Adjust token factory for non-default prefix"), E("getFactory([tokens], [force])", "Get a token factory"), E("resetFactory()", "Clear the current token factory"), E("hasBinary()", "Is binary (Unicode) support enabled?"), E("enableBinary(...)", "Enable binary (Unicode) support"), E("disableBinary()", "Disable binary (Unicode) support"), E("isDefaultEncodingErrors()", "Is encoding/errors the default?"), E("getDefaultEncoding()", "Get the default file encoding"), E("open(filename, [mode], ...)", "Open a file"), E("significatorReString()", "Regular expression string for significators"), E("significatorRe()", "Regular expression pattern for significators"), E("significatorFor(key)", "Significator variable name for key"), E("setContextFormat(format)", "Set the context format"), E("renderContext(context)", "Render context using format"), E("calculateIconsSignature()", "Calculate icons signature"), E("signIcons()", "Sign the icons dictionary"), E("transmogrifyIcons()", "Process the icons dictionary"), E("validateIcons()", "Process the icons dictionaray if necessary"), E("intializeEmojiModules([names])", "Initialize emoji module support"), E("substituteEmoji(text)", "Substitute emoji"), E("isSuccessCode(code)", "Does this exit code indicate success?"), E("isExitError(error)", "Is this exception instance an exit?"), E("errorToExitCode(error)", "Return exit code for exception instance"), E("isNotAnError(error)", "Is this exception instance not an error?"), E("formatError(error[, p, s])", "Render an error string from instance"), ])) usage.add(TableSection( 'hooks', "Hook methods", """\ The following hook methods are supported. The return values are ignored except for the `pre...` methods which, when they return a true value, signal that the following token handling should be skipped: """, [ E("atInstallProxy(proxy, new)", "Proxy being installed"), E("atUninstallProxy(proxy, new)", "Proxy being uninstalled"), E("atStartup()", "Interpreter started up"), E("atReady()", "Interpreter ready"), E("atFinalize()", "Interpreter finalizing"), E("atShutdown()", "Interpreter shutting down"), E("atParse(scanner, loc)", "Interpreter parsing"), E("atToken(token)", "Interpreter expanding token"), E("atHandle(info, fatal, contexts)", "Interpreter encountered error"), E("atInteract()", "Interpreter going interactive"), E("pushContext(context)", "Context being pushed"), E("popContext(context)", "Context was popped"), E("setContext(context)", "Context was set or modified"), E("restoreContext(context)", "Context was restored"), E("prePrefix()", "Pre prefix token"), E("preWhitespace()", "Pre whitespace token"), E("preString(string)", "Pre string literal token"), E("preLineComment(comment)", "Pre line comment"), E("postLineComment()", "Post line comment"), E("preInlineComment(comment)", "Pre inline comment"), E("postInlineComment()", "Post inline comment"), E("preBackquote(literal)", "Pre backquote literal"), E("postBackquote()", "Post backquote literal"), E("preSignificator(key, value, s)", "Pre significator"), E("postSignificator()", "post significator"), E("preContextName(name)", "Pre context name"), E("postContextName()", "Post context name"), E("preContextLine(line)", "Pre context line"), E("postContextLine()", "Post context line"), E("preExpression(pairs, except, loc)", "Pre expression"), E("postExpression(result)", "Post expression"), E("preSimple(code, sub, loc)", "Pre simple expression"), E("postSimple(result)", "Post simple expression"), E("preInPlace(code, loc)", "Pre in-place expression"), E("postInPlace(result)", "Post in-place expression"), E("preStatement(code, loc)", "Pre statement"), E("postStatement()", "Post statement"), E("preControl(type, rest, loc)", "Pre control"), E("postControl()", "Post control"), E("preEscape(code)", "Pre escape"), E("postEscape()", "Post escape"), E("preDiacritic(code)", "Pre diacritic"), E("postDiacritic()", "Post diacritic"), E("preIcon(code)", "Pre icon"), E("postIcon()", "Post icon"), E("preEmoji(name)", "Pre emoji"), E("postEmoji()", "Post emoji"), E("preCustom(contents)", "Pre custom"), E("postCustom()", "Post custom"), E("beforeProcess(command, n)", "Before command processing"), E("afterProcess()", "After command processing"), E("beforeInclude(file, loc, name)", "Before file inclusion"), E("afterInclude()", "After file inclusion"), E("beforeExpand(string, loc, name)", "Before expand call"), E("afterExpand(result)", "After expand call"), E("beforeTokens(tokens, loc)", "Before processing tokens"), E("afterTokens(result)", "After processing tokens"), E("beforeFileLines(file, loc)", "Before reading file by lines"), E("afterFileLines()", "After reading file by lines"), E("beforeFileChunks(file, loc)", "Before reading file by chunks"), E("afterFileChunks()", "After reading file by chunks"), E("beforeFileFull(file, loc)", "Before reading file in full"), E("afterFilFull()", "After reading file in full"), E("beforeString(string, loc)", "Before processing string"), E("afterString()", "After processing string"), E("beforeQuote(string)", "Before quoting string"), E("afterQuote()", "After quoting string"), E("beforeEscape(string)", "Before escaping string"), E("afterEscape()", "After escaping string"), E("beforeSignificate(key, value, loc)", "Before significator"), E("afterSignificate()", "After significator"), E("beforeCallback(contents)", "Before custom callback"), E("afterCallback()", "Before custom callback"), E("beforeAtomic(name, value, loc)", "Before atomic assignment"), E("afterAtomic()", "After atomic assignment"), E("beforeMulti(names, values, loc)", "Before complex assignment"), E("afterMulti()", "After complex assignment"), E("beforeImport(name, loc)", "Before module import"), E("afterImport()", "After module import"), E("beforeFunctional(code, lists, loc)", "Before functional expression"), E("afterFunctional(result)", "After functional expression"), E("beforeEvaluate(code, loc, write)", "Before expression evaluation"), E("afterEvaluate(result)", "After expression evaluation"), E("beforeExecute(statements, loc)", "Before statement execution"), E("afterExecute()", "After statement execution"), E("beforeSingle(source, loc)", "Before single execution"), E("afterSingle(result)", "After single execution"), E("beforeFinalizer(final)", "Before finalizer processing"), E("afterFinalizer()", "After finalizer processing"), ])) usage.add(MappingSection( 'named', "Named escapes", "The following named escapes (control codes and control-like characters)\n(`@\\^{...}`) are supported:\n", usage.config.controls, ControlEntry)) usage.add(MappingSection( 'diacritics', "Diacritic combiners", "The following diacritic combining characters (`@^C...`) are supported:\n", usage.config.diacritics)) usage.add(MappingSection( 'icons', "Icons", "The following icon sequences (`@|...`) are supported:\n", usage.config.icons, NameEntry)) usage.add(MappingSection( 'emojis', "Custom emojis", "The following custom emojis have been made available:\n", usage.config.emojis, NameEntry)) usage.add(HelpSection( 'topics', "This list of topics", """\ Need more help? Add more -h options (-hh, -hhh) for more help. Use -H for help on a specific topic, or specify a comma-separated list of topics. Try `default` (-h) for default help, `more` (-hh) for more common topics, `all` (-hhh) for all help topics, or `topics` for this list. Use -V for version information, -W for version and system information, or -Z for all debug details. Available topics: """, usage)) return payload # # main # def main(): topics = sys.argv[1:] if not topics: topics = ['default'] usage = Usage() usage.show(topics) if __name__ == '__main__': main() empy-4.2.1/setup.cfg0000644000175000017500000000004615142227214014233 0ustar jriverojrivero[egg_info] tag_build = tag_date = 0 empy-4.2.1/LICENSE.md0000644000175000017500000000276015142227044014024 0ustar jriverojrivero# The 3-clause BSD license Copyright (C) 2002-2026 Erik Max Francis All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. empy-4.2.1/PKG-INFO0000644000175000017500000000402015142227214013503 0ustar jriverojriveroMetadata-Version: 2.1 Name: empy Version: 4.2.1 Summary: A templating system for Python. Home-page: http://www.alcyone.com/software/empy/ Author: Erik Max Francis Author-email: software@alcyone.com License: BSD Platform: any Classifier: Development Status :: 6 - Mature Classifier: Environment :: Console Classifier: Intended Audience :: Developers Classifier: Intended Audience :: Other Audience Classifier: License :: OSI Approved :: BSD License Classifier: Operating System :: OS Independent Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Programming Language :: Python :: Implementation :: IronPython Classifier: Programming Language :: Python :: Implementation :: Jython Classifier: Programming Language :: Python :: Implementation :: PyPy Classifier: Programming Language :: Python :: Implementation :: Stackless Classifier: Topic :: Software Development :: Interpreters Classifier: Topic :: Software Development :: Libraries :: Python Modules Classifier: Topic :: Software Development :: Pre-processors Classifier: Topic :: Text Editors :: Text Processing Classifier: Topic :: Text Processing :: Filters Classifier: Topic :: Text Processing :: General Classifier: Topic :: Text Processing :: Markup Classifier: Topic :: Utilities Requires-Python: >=2.4 License-File: LICENSE.md License-File: LICENSE.md.pre EmPy is a powerful, robust and mature templating system for inserting Python code in template text. EmPy takes a source document, processes it, and produces output. This is accomplished via expansions, which are signals to the EmPy system where to act and are indicated with markup. Markup is set off by a customizable prefix (by default the at sign, `@`). EmPy can expand arbitrary Python expressions, statements and control structures in this way, as well as a variety of additional special forms. The remaining textual data is sent to the output, allowing Python to be used in effect as a markup language. empy-4.2.1/emdoc.py0000644000175000017500000004406715002511736014066 0ustar jriverojrivero#!/usr/bin/env python3 """ EmPy documentation generating system. This module requires a modern Python 3.x interpreter. """ # # imports # import hashlib import io import os import subprocess import sys import time import em import emhelp import emlib # # constants # SOURCE = '\N{KEYBOARD}\ufe0f' OUTPUT = '\N{DESKTOP COMPUTER}\ufe0f' PATHS = ['../..', '.'] EMOJIS = { '...': ('\N{HORIZONTAL ELLIPSIS}', "horizontal ellipsis"), '<--': ('\N{LONG LEFTWARDS ARROW}', "long leftwards arrow"), '-->': ('\N{LONG RIGHTWARDS ARROW}', "long rightwards arrow"), } def admonish(text, emoji=None, admonition="important"): """Create an admonition.""" if emoji is None: return ":::{{{admonition}}}\n{text}\n:::\n".format( admonition=admonition, text=text) else: return ":::{{{admonition}}}\n{emoji} {text}\n:::\n".format( admonition=admonition, emoji=emoji, text=text) if not os.environ.get('EMPY_STRICT', None): # Only make the alerting admonitions available available if this is not # strict; if strict, this will result in an emoji error. EMOJIS.update({ '!!!': (admonish("!!!", "\u2757\ufe0f"), "exclamation mark"), '???': (admonish("???", "\u2753\ufe0f"), "question mark"), '^^^': (admonish("^^^", "\u26a0\ufe0f"), "warning sign"), '///': (admonish("///", "\u2714\ufe0f"), "check mark"), '\\\\\\': (admonish("\\\\\\", "\u274c\ufe0f"), "cross mark"), '+++': (admonish("+++", "\U0001f53a"), "red triangle pointed up"), '---': (admonish("---", "\U0001f53b"), "red triangle pointed down"), }) # # Error ... # class DocumentationError(em.Error): pass # # Identity # class Identity: """Dynamically access magic attributes on both the interpreter and underlying module.""" def __init__(self, interp, module): self.interp = interp self.module = module def __str__(self): try: return self.__getattr__('project') except AttributeError: return self.__getattr__('program') def __getattr__(self, attr): attribute = '__{}__'.format(attr) if attribute in self.interp.globals: return self.interp.globals[attribute] elif attribute in self.module.__dict__: return self.module.__dict__[attribute] else: raise AttributeError("unknown attribute: {}".format(__attribute__)) def tarball(self, version='latest'): if version is None: version = self.version return '{}{}-{}.tar.gz'.format(self.url, self.program, version) def path(self, suffix=None): if suffix is not None: return self.url + suffix else: return self.url # # Tee # class Tee: """A file-like object which can split output into multiple files.""" temporary = '/tmp' def __init__(self, files): self.files = files def __call__(self, string): self.write(string) def write(self, string): for file in self.files: file.write(string) def writelines(self, lines): for line in lines: self.write(line) # # Information # class Information: """A helper information class to generate documentation.""" timeFormat = '%Y-%m-%d %H:%M:%S' extensions = ['.md.em', '.md.pre', '.md', ''] hashFactory = hashlib.sha1 hashName = 'SHA1' encoding = 'utf-8' class Flag: """Encapsulate a flag: a command line option, a configuration variable, and/or an environment variable.""" def __init__(self, config, options, var=None, env=None, val=None): self.config = config self.options = options self.var = var self.val = val self.env = env def __str__(self): return str((self.options, self.var, self.val, self.env)) def render(self, file, key, showDefault=True, default=None, verbose=False): isOption = key.startswith('-') options = '/'.join("{}".format(x) for x in self.options) environ = '{}'.format(self.env) if self.env else None if self.var is not None: if (verbose and not showDefault and self.val is not None): variable = '{}\N{NO-BREAK SPACE}=\N{NO-BREAK SPACE}{}'.format( self.var, repr(self.val)) else: variable = '{}'.format(self.var) else: variable = None declarations = [] fragments = [] if isOption: assert options, (key, str(self)) # It's an option, so list those first. declarations.append(options) if environ: fragments.extend(["_environment variable:_ `{}`".format( environ)]) if variable: fragments.extend(["_configuration variable:_ `{}`".format( variable)]) elif key.startswith('EMPY_'): assert environ, (key, str(self)) # If it starts with EMPY_, it's an environment variable. declarations.append(environ) if options: fragments.extend(["_command line option:_ `{}`".format( options)]) if variable: fragments.extend(["_configuration variable:_ `{}`".format( variable)]) else: assert variable, (key, str(self)) # Otherwise, it's a configuration variable. declarations.append(variable) types = self.config._specs[key] if types is not None and verbose: if types == em.strType: types = str if types is list: types = 'list[str]' if not isinstance(types, tuple): types = (types,) optional = False if types[-1] is None: # If the last one is None, then the type is # Optional. optional = True types = types[:-1] types = ' | '.join( x if isinstance(x, str) else x.__name__ for x in types) if optional: types = 'Optional[%s]' % types declarations.append(": {}".format(types)) if options: fragments.extend(["_command line option:_ `{}`".format(options)]) if environ: fragments.extend(["_environment variable:_ `{}`".format(environ)]) if showDefault: declarations.append("\N{NO-BREAK SPACE}=\N{NO-BREAK SPACE}{}".format(default)) if fragments and verbose: file.write('`{}` ({})'.format(''.join(declarations), ', '.join(fragments))) else: file.write('`{}`'.format(''.join(declarations))) noLanguage = 'text' def __init__(self, interp, moduleName, file=sys.stdout): self.interp = interp self.moduleName = moduleName self.file = file self.module = __import__(moduleName) self.ident = Identity(interp, self.module) self.details = emlib.Details() self.config = em.Configuration() self.usage = emhelp.Usage(config=self.config) self.options = self.process() def process(self): options = {} section = self.usage.payload['options'] for entry in section.entries: fullOptions = [x for x in entry.raw if not x.isspace()] theseOptions = [x.split('=', 1)[0] for x in fullOptions] flag = self.Flag(self.config, fullOptions, var=entry.var, val=entry.val, env=entry.env) for key in theseOptions: assert key not in options, key options[key] = flag if entry.var: options[entry.var] = flag if entry.env: options[entry.env.split(' ', 1)[0]] = flag for key, value in self.config.__dict__.items(): if key in options: options[key].default = value else: flag = self.Flag(self.config, [], var=key) options[key] = flag return options def topic(self, topic, separator=False): self.file.write("```{}\n".format(self.noLanguage)) self.usage.show([topic], separator) self.file.write("```\n") def option(self, key, verbose=False, showDefault=False): if verbose is None: self.file.write('`{}`'.format(key)) return if showDefault and key in self.config: if key == 'pathSeparator': default = "';'` (Windows) or `':'` (others) ` " else: default = getattr(self.config, key) if isinstance(default, dict): default = "{...}" else: default = repr(default) else: default = None self.options[key].render(self.file, key, showDefault, default, verbose) def variable(self, variable): self.file.write("`{}`".format(variable)) def source(self, filename): for extension in self.extensions: if os.path.exists(filename + extension): return filename + extension else: raise FileNotFoundError("source file not found: {}".format(filename)) def filter(self, text, lines=None, blanks=None): if isinstance(text, bytes) and self.encoding: text = text.decode(self.encoding) text = (text .replace('&', '&') .replace('<', '<') .replace('>', '>')) stopped = False chunks = [] for line in text.splitlines(): if line.startswith('...'): chunks.append("{}".format(line)) else: chunks.append(line) if not line and blanks is not None: blanks -= 1 if blanks == 0: stopped = True if lines is not None and len(chunks) >= lines: stopped = True if stopped: break if stopped: chunks.append('...') return '\n'.join(chunks) def shell(self, command, output, prefix='% ', lines=None, blanks=None, class_='shell', exitCode=0): display = command if isinstance(display, list): words = ['"{}"'.format(x) if ' ' in x and not x.startswith('#') else x for x in command] display = ' '.join(words) self.file.write("
\n".format(class_))
        if display:
            self.file.write("{}{}\n".format(
                prefix, self.filter(display)))
        self.file.write(self.filter(output, lines, blanks))
        if exitCode != 0:
            self.file.write("Exit code: {}\n".format(exitCode))
        self.file.write("
\n") def execute(self, command, prefix='% ', lines=None, blanks=None, check=True): oldPath = os.environ['PATH'] try: # Make sure that if it's em.py, it's the local one. path = '.:' + oldPath os.environ['PATH'] = path result = subprocess.run(command, capture_output=True) output = result.stdout self.shell(command, output, prefix, lines, blanks, exitCode=result.returncode if check else 0) finally: os.environ['PATH'] = oldPath def splice(self, file, name=''): context = self.interp.newContext(name) self.interp.pushContext(context) try: self.interp.fileFull(file) finally: self.interp.popContext() def load(self, filename, mode='r'): with open(filename, mode) as file: self.splice(file, filename) def clip(self, filename, heading, rename=None, stoplines=None, mode='r'): buffer = [] on = False start = 0 number = 1 if stoplines is None: stoplines = [] stoplines = [x if x.endswith('\n') else x + '\n' for x in stoplines] with open(filename, mode) as file: for line in file.readlines(): if line.startswith('#'): try: prelim, title = line.split(' ', 1) except ValueError: raise DocumentationError("malformed header line: {}".format(line), line=line) if ':' in title: title, subtitle = title.split(':', 1) subtitle = subtitle.strip() title = title.strip() level = prelim.count('#') if title == heading: if rename is not None: line = ('#' * level) + ' ' + rename + '\n' if not on: start = number on = True else: if on: break if line in stoplines: on = False if on: buffer.append(line) number += 1 if start: self.splice(io.StringIO(''.join(buffer)), (filename, start)) else: raise DocumentationError("could not find heading '{}'".format(heading), heading=heading) def tee(self, filename): return Tee(filename) def summarize(self, filename='README'): filename = self.source(filename) hasher = self.hashFactory() with open(filename, 'rb') as f: data = f.read() length = len(data) hasher.update(data) hash = hasher.hexdigest() record = os.stat(filename) when = time.localtime(record.st_mtime) timeStamp = time.strftime(self.timeFormat, when) out = em.StringIO('w') self.details.show(file=out) self.file.write("""\ _This documentation for {} version {} was generated from {} ({} `{}`, {} bytes) at {} using {}._ """.format( self.ident, self.ident.version, filename, self.hashName, hash, length, timeStamp, out.getvalue())) self.done() def done(self): if self.config: self.interp.dropAllDiversions() self.config = None # # Extension # class Extension(em.Extension): """The EmPy documentation extension.""" languages = { 'empy': '' # to eliminate Pygments warning } sub = True def __init__(self): super(Extension, self).__init__() self.current = 0 def next(self, amount=1): self.current += amount return self.current def expand(self, source, root=''): with em.StringIO() as file: with em.Interpreter(output=file, root=root) as interp: interp.string(source) output = file.getvalue() return output def angle_brackets(self, source, depth, locals): caption = None if source.startswith('['): language = 'empy' caption, source = source[1:].split(']', 1) example = True else: if not source.startswith('\n'): language, source = source.split('\n', 1) language = language.strip() else: language = '' example = False if caption: suffix = ': ' + caption else: suffix = '' source = source.strip() + '\n' if example: number = self.next() self.interp.startDiversion(caption) self.interp.write('\n'.format(number)) self.interp.write('\n') self.interp.write(':::{{admonition}} Example {}{}\n'.format( number, suffix)) output = self.expand(source, ''.format( number, ' "' + caption + '"' if caption else '')) self.interp.write('_Source_: {}\n'.format(SOURCE)) self.interp.write('
\n\n') self.interp.write('``````{}\n'.format(self.languages.get(language, language))) self.interp.write(source) self.interp.write('``````\n') self.interp.write('\n
\n\n') self.interp.write('_Output_: {}\n'.format(OUTPUT)) self.interp.write('
\n\n') self.interp.write('``````\n') self.interp.write(output) self.interp.write('``````\n') self.interp.write('\n
\n\n') self.interp.write(':::\n') self.interp.stopDiverting() self.interp.replayDiversion(caption) else: self.interp.write('``````{}\n'.format(self.languages.get(language, language))) self.interp.write(source) self.interp.write('``````\n') # # Hook # class Hook(emlib.Hook): """The EmPy documentation hook.""" delimiter = '`' def __init__(self, interp): self.interp = interp def preBackquote(self, literal): if self.delimiter in literal: for count in range(1, 10): if '`' * count not in literal: count -= 1 break else: count = 0 affix = self.delimiter * (count + 1) self.interp.write("{}{}{}".format(affix, literal, affix)) return True # # init # def init(interp, moduleName, paths=None): """Initialize the information object.""" if paths is None: paths = PATHS for path in paths: sys.path.insert(0, os.path.abspath(path)) interp.config.emojis = EMOJIS interp.addHook(Hook(interp)) interp.installExtension(Extension()) return Information(interp, moduleName) empy-4.2.1/emlib.py0000644000175000017500000012433015074055765014075 0ustar jriverojrivero#!/usr/bin/env python3 """ Optional support classes for EmPy. """ # # imports # import operator import os import platform import sys import em # # Filter ... # class Filter(em.Root): """An abstract filter.""" # Meta methods. def follow(self): """Return the next filter/file-like object in the sequence, or None.""" raise NotImplementedError def isAttached(self): """Is a filter/file already attached to this one?""" raise NotImplementedError def attach(self, filter): """Attach a filter to this one.""" raise NotImplementedError def detach(self): """Detach a filter from its sink.""" raise NotImplementedError def last(self): """Find the last filter in this chain.""" this, last = self, None while this is not None: last = this this = this.follow() return last def _flush(self): """The _flush method should always flush the underlying sinks.""" raise NotImplementedError # File-like methods. def write(self, data): """The write method must be implemented.""" raise NotImplementedError def writelines(self, lines): """Write lines. This should not need to be overriden for most filters.""" for line in lines: self.write(line) def flush(self): """The flush method can be overridden.""" self._flush() def close(self): """The close method must be implemented.""" raise NotImplementedError class NullFilter(Filter): """A filter that never sends any output to its sink.""" def follow(self): return None def isAttached(self): return False def attach(self, filter): pass def detach(self): pass def write(self, data): pass def close(self): pass class ConcreteFilter(Filter): """A concrete filter has a single sink.""" def __init__(self): if self.__class__ is ConcreteFilter: raise NotImplementedError self.sink = None def follow(self): """Return the next filter/file-like object in the sequence, or None.""" return self.sink def isAttached(self): """Is a filter/file already attached to this one?""" return self.sink is not None def attach(self, filter): """Attach a filter to this one.""" if self.sink is not None: # If one's already attached, detach it first. self.detach() self.sink = filter def detach(self): """Detach a filter from its sink.""" self.flush() self._flush() # do a guaranteed flush to just to be safe self.sink = None def last(self): """Find the last filter in this chain.""" this, last = self, None while this is not None: last = this this = this.follow() return last def _flush(self): """This method should flush the concrete sink and should not be overridden.""" self.sink.flush() def flush(self): self._flush() def close(self): """Close the filter. Do an explicit flush first, then close the sink.""" self.flush() self.sink.close() class IdentityFilter(ConcreteFilter): """A filter which just sends any output straight through to its sink.""" def write(self, data): self.sink.write(data) class FunctionFilter(ConcreteFilter): """A filter that works simply by pumping its input through a function which maps strings into strings.""" def __init__(self, function): super(FunctionFilter, self).__init__() self.function = function def write(self, data): self.sink.write(self.function(data)) class IndentFilter(ConcreteFilter): """Automatically indent a fixed number of spaces after every newline.""" default = ' ' def __init__(self, indent): super(IndentFilter, self).__init__() if indent is None: self.indent = self.default elif isinstance(indent, int): self.indent = self.default * indent else: self.indent = indent def write(self, data): self.sink.write(data.replace('\n', '\n' + self.indent)) class StringFilter(ConcreteFilter): """A filter that takes a lookup table (e.g., string, list, or dictionary) and filters any incoming data through it via `str.translate`.""" def __init__(self, table): super(StringFilter, self).__init__() self.table = table def write(self, data): self.sink.write(data.translate(self.table)) class BufferedFilter(ConcreteFilter): """A buffered filter is one that doesn't modify the source data sent to the sink, but instead holds it for a time. The standard variety only sends the data along when it receives a flush command.""" def __init__(self): super(BufferedFilter, self).__init__() self.buffer = '' def write(self, data): self.buffer += data def flush(self): if self.buffer: self.sink.write(self.buffer) self._flush() class SizeBufferedFilter(BufferedFilter): """A size-buffered filter only in fixed size chunks (excepting the final chunk).""" def __init__(self, bufferSize=em.Configuration.defaultBuffering): super(SizeBufferedFilter, self).__init__() assert bufferSize > 0 self.bufferSize = bufferSize def write(self, data): BufferedFilter.write(self, data) while len(self.buffer) > self.bufferSize: chunk, self.buffer = self.buffer[:self.bufferSize], self.buffer[self.bufferSize:] self.sink.write(chunk) class FullyBufferedFilter(BufferedFilter): """A maximally-buffered filter only lets its data through on the final close. It ignores flushes.""" def flush(self): pass def close(self): if self.buffer: BufferedFilter.flush(self) self.sink.close() class DelimitedFilter(BufferedFilter): """A delimited filter only lets data through when it sees whole lines.""" def __init__(self, delimiter): super(DelimitedFilter, self).__init__() self.delimiter = delimiter def write(self, data): BufferedFilter.write(self, data) chunks = self.buffer.split(self.delimiter) for chunk in chunks[:-1]: self.sink.write(chunk + self.delimiter) self.buffer = chunks[-1] class LineDelimitedFilter(DelimitedFilter): """A line-delimited filter only lets data through when it sees whole lines.""" def __init__(self, delimiter=em.NEWLINE_CHAR): super(LineDelimitedFilter, self).__init__(delimiter) def write(self, data): DelimitedFilter.write(self, data) chunks = self.buffer.split(self.delimiter) for chunk in chunks[:-1]: self.sink.write(chunk + self.delimiter) self.buffer = chunks[-1] class DroppingFilter(ConcreteFilter): """A filter which drops any chunks that match the provided list of chunks to ignore.""" def __init__(self, droppings): super(DroppingFilter, self).__init__() self.droppings = droppings def write(self, data): if data not in self.droppings: self.sink.write(data) class SplittingFilter(Filter): """A filter that splits the output stream n ways.""" def __init__(self, sinks): super(SplittingFilter, self).__init__() self.sinks = sinks[:] def _flush(self): for sink in self.sinks: sink._flush() def write(self, data): for sink in self.sinks: sink.write(data) def flush(self): for sink in self.sinks: sink.flush() def close(self): for sink in self.sinks: sink.close() # # Container # Container = em.Plugin # DEPRECATED # # AbstractHook, Hook ... # class AbstractHook(em.Plugin): """An abstract base class for implementing hooks. All hook invocations are not present. (Use this if you plan to systematically handle all calls with something like __getattr__.)""" pass class Hook(AbstractHook): """The base class for implementing hooks. All hook invocations are present and no-ops.""" # Override these in a subclass. def test(self): pass # used in tests # Events def atInstallProxy(self, proxy, new): pass def atUninstallProxy(self, proxy, done): pass def atInstallFinder(self, finder): pass def atUninstallFinder(self, finder): pass def atStartup(self): pass def atReady(self): pass def atFinalize(self): pass def atShutdown(self): pass def atParse(self, scanner, locals): pass def atToken(self, token): pass def atHandle(self, info, fatal, contexts): pass def atInteract(self): pass # Contexts def pushContext(self, context): pass def popContext(self, context): pass def setContext(self, context): pass def restoreContext(self, context): pass # Tokens def preLineComment(self, comment): pass def preInlineComment(self, comment): pass def preWhitespace(self, whitespace): pass def preEnable(self, comment): pass def preDisable(self, comment): pass def prePrefix(self): pass def preString(self, string): pass def postString(self): pass def preBackquote(self, literal): pass def postBackquote(self, result): pass def preSignificator(self, key, value, stringized): pass def postSignificator(self): pass def preContextName(self, name): pass def postContextName(self, context): pass def preContextLine(self, line): pass def postContextLine(self, context): pass def preExpression(self, pairs, except_, locals): pass def postExpression(self, result): pass def preSimple(self, code, subtokens, locals): pass def postSimple(self, result): pass def preInPlace(self, code, locals): pass def postInPlace(self, result): pass def preStatement(self, code, locals): pass def postStatement(self): pass def preControl(self, type, rest, locals): pass def postControl(self): pass def preEscape(self, code): pass def postEscape(self): pass def preDiacritic(self, code): pass def postDiacritic(self): pass def preIcon(self, code): pass def postIcon(self): pass def preEmoji(self, name): pass def postEmoji(self): pass def preExtension(self, name, contents, depth, locals): pass def postExtension(self, result): pass def preCustom(self, contents): pass # DEPRECATED def postCustom(self, result): pass # DEPRECATED # Interpreter actions def beforeProcess(self, command, n): pass def afterProcess(self): pass def beforeInclude(self, file, locals, name): pass def afterInclude(self): pass def beforeExpand(self, string, locals, name, dispatcher): pass def afterExpand(self, result): pass def beforeFileLines(self, file, locals, dispatcher): pass def afterFileLines(self): pass def beforeFileChunks(self, file, bufferSize, locals, dispatcher): pass def afterFileChunks(self): pass def beforeFileFull(self, file, locals, dispatcher): pass def afterFileFull(self): pass def beforeImport(self, filename, module, locals, dispatcher): pass def afterImport(self): pass def beforeString(self, string, locals, dispatcher): pass def afterString(self): pass def beforeTokens(self, tokens, locals): pass def afterTokens(self, result): pass def beforeQuote(self, string): pass def afterQuote(self, result): pass def beforeEscape(self, string, more): pass def afterEscape(self, result): pass def beforeSignificate(self, key, value, locals): pass def afterSignificate(self): pass def beforeCallback(self, contents): pass # DEPRECATED def afterCallback(self, result): pass # DEPRECATED def beforeAtomic(self, name, value, locals): pass def afterAtomic(self): pass def beforeMulti(self, names, values, locals): pass def afterMulti(self): pass def beforeClause(self, catch, locals): pass def afterClause(self, exception, variable): pass def beforeDictionary(self, code, locals): pass def afterDictionary(self, result): pass def beforeSerialize(self, expression, locals): pass def afterSerialize(self): pass def beforeDefined(self, name, locals): pass def afterDefined(self, result): pass def beforeLiteral(self, text, locals): pass def afterLiteral(self, result): pass def beforeFunctional(self, code, lists, locals): pass def afterFunctional(self, result): pass def beforeEvaluate(self, expression, locals, replace): pass def afterEvaluate(self, result): pass def beforeExecute(self, statements, locals): pass def afterExecute(self): pass def beforeSingle(self, source, locals): pass def afterSingle(self, result): pass def beforeFinalizer(self, finalizer): pass def afterFinalizer(self): pass # # Callback # class Callback(em.Plugin): """A root class for any callback utilities.""" pass # # Finalizer # class Finalizer(em.Plugin): """A root class for a finalizer.""" pass # # Handler # class Handler(em.Plugin): """A root class for any error handler.""" pass # # Document # class Document(em.Root): """A representation of an individual EmPy document, as used by a processor.""" def __init__(self, ident, filename): self.ident = ident self.filename = filename self.significators = {} # # Processor # class Processor(em.Root): """An entity which is capable of processing a hierarchy of EmPy files and building a dictionary of document objects associated with them describing their significator contents.""" defaultExtensions = ['.em'] def __init__(self, config, factory=Document): self.config = config self.factory = factory self.documents = {} def identifier(self, pathname, filename): return filename def clear(self): self.documents = {} def scan(self, basename, extensions=None): if extensions is None: extensions = self.defaultExtensions if isinstance(extensions, em.strType): extensions = [extensions] def _noCriteria(x): return True def _extensionsCriteria(pathname, extensions=extensions): if extensions: for extension in extensions: if pathname[-len(extension):] == extension: return True return False else: return True self.directory(basename, _noCriteria, _extensionsCriteria, None) self.postprocess() def postprocess(self): pass def directory(self, basename, dirCriteria, fileCriteria, depth=None): if depth is not None: if depth <= 0: return else: depth -= 1 filenames = os.listdir(basename) for filename in filenames: pathname = os.path.join(basename, filename) if os.path.isdir(pathname): if dirCriteria(pathname): self.directory(pathname, dirCriteria, fileCriteria, depth) elif os.path.isfile(pathname): if fileCriteria(pathname): documentID = self.identifier(pathname, filename) document = self.factory(documentID, pathname) self.file(document, open(pathname)) self.documents[documentID] = document def file(self, document, file): while True: line = file.readline() if not line: break self.line(document, line) def line(self, document, line): significatorRe = re.compile(self.config.significatorReString()) match = significatorRe.search(line) if match: key, valueS = match.groups() valueS = valueS.strip() if valueS: value = eval(valueS) else: value = None document.significators[key] = value # # Requirement ... # class Requirement(em.Root): def check(self, details): raise NotImplementedError class ConjunctiveRequirement(Requirement): def __init__(self, requirements): self.requirements = requirements def check(self, details): for requirement in self.requirements: if not requirement.check(details): return False return True class DisjunctiveRequirement(Requirement): def __init__(self, requirements): self.requirements = requirements def check(self, details): for requirement in self.requirements: if requirement.check(details): return True return False class VersionRequirement(Requirement): operators = { '=~': lambda x, y: y == x[:min(len(x), len(y))], '==': operator.eq, '!=': operator.ne, '>=': operator.ge, '>': operator.gt, '<=': operator.le, '<': operator.lt, } def __init__(self, operator, version): if isinstance(operator, em.strType): operator = self.operators[operator] self.operator = operator if isinstance(version, em.strType): version = Details.unpack(version) self.version = version def check(self, details): thisVersion = Details.unpack(details.getPythonVersion()) return self.operator(thisVersion, self.version) class ImplementationRequirement(Requirement): identity = lambda x: x operators = { '': identity, '+': identity, '-': operator.not_, } def __init__(self, operator, implementation): if isinstance(operator, em.strType): operator = self.operators[operator] self.operator = operator self.implementation = implementation def check(self, details): thisImplementation = details.getPythonImplementation() return self.operator(self.implementation == thisImplementation) # # Details # class Details(em.Root): """Gather details on a running Python system for debugging purposes.""" releaseFilenames = ['/etc/os-release', '/usr/lib/os-release'] delimiter = '/' unsanitizableNames = set(['URL', 'ID']) @staticmethod def pack(tuple, delimiter='.'): """Pack a sequence of ints into a string.""" return delimiter.join([str(x) for x in tuple]) @staticmethod def unpack(string, delimiter='.'): """Unpack a string into a sequence of ints.""" def convert(x): if x.isdigit(): return int(x) else: return x return tuple([convert(x) for x in string.split(delimiter)]) def __init__(self, useSanitization=False): self.useSanitization = useSanitization self.data = {} self._system = None self._os = None self._machine = None self._implementation = None self._version = None self._framework = None self._context = None def __contains__(self, key): return key in self.data def __getitem__(self, key): return self.data[key] def __iter__(self): items = list(self.items()) items.sort() return iter(items) def empty(self): return len(self.data) == 0 # System/OS information. def transformName(self, value, pairs, defaultFormat='[%s]', blank='?'): """Find the prefix of the value in the pairs and return the resulting name.""" if not value: return blank for prefix, name in pairs: if value.startswith(prefix): return name return defaultFormat % value def getSystemName(self): """Get a nice name for the system this interpreter is running on. Cached.""" if self._system is None: self._system = platform.system() assert self._system is not None return self._system def getOSName(self): """Get a nice name for the OS this interpreter is running on. Cached.""" if self._os is None: PAIRS = [ ('posix', 'POSIX'), ('nt', 'NT'), ('java', 'Java'), ] self._os = self.transformName(os.name, PAIRS) assert self._os is not None return self._os # Python information. def getPythonImplementation(self): """Get the name of this implementation. Cached.""" if self._implementation is None: DEFAULT = 'CPython' try: self._implementation = platform.python_implementation() except AttributeError: # If the module does not contain the function, then it's old # enough that we're surely the default. Fall through. pass if not self._implementation: self._implementation = DEFAULT assert self._implementation is not None return self._implementation def checkPythonImplementation(self, choices): """Check the Python implementation against the sequence of choices.""" return self.getPythonImplementation() in choices def getPythonVersion(self): """Get the version of Python. Cached.""" if self._version is None: try: self._version = platform.python_version() except AttributeError: # Stackless Python 2.4 raises an internal error when this is # called since sys.version is in an unexpected format. self._version = self.pack(sys.version_info[:3]) assert self._version is not None return self._version def parsePythonVersion(self, version): """Parse a Python version into a tuple of ints.""" if isinstance(version, em.strType): version = Details.unpack(version) return version def checkPythonVersion(self, minimum, maximum=None, closed=True): """Check whether or not this Python version is greater than or equal to the minimum, and if present, less than or equal to (or less than) the maximum.""" version = sys.version_info[:3] minimum = self.parsePythonVersion(minimum) if version < minimum: return False if maximum is not None: maximum = self.parsePythonVersion(maximum) if len(version) > len(maximum): # Trim the version down so it's no more detailed than the # maximum. version = version[:len(maximum)] if closed: test = version > maximum else: test = version >= maximum if test: return False return True def getMachineType(self): """Get the machine name. Cached.""" if self._machine is None: self._machine = platform.machine() if not self._machine: self._machine = '?' assert self._machine is not None return self._machine def getFramework(self): """Get the framework and version this interpreter is running under as a 2-tuple, or None. Cached.""" if self._framework is None: implementation = self.getPythonImplementation() if implementation == 'PyPy': # The PyPy version is in the second line of the version string. lines = sys.version.split('\n') second = lines[1] if second.startswith('['): second = second[1:] fields = second.split() self._framework = 'PyPy', fields[1] elif implementation == 'Jython': from java.lang import System self._framework = 'JDK', System.getProperty('java.version') elif implementation == 'IronPython': from System import Environment self._framework = '.NET', Environment.Version else: # CPython try: fields = platform.python_compiler().split() pair = fields[:2] rest = fields[3:] self._framework = tuple(pair) except AttributeError: # Stackless Python 2.4 raises an internal error when this # is called since sys.version is in an unexpected format. lines = sys.version.splitlines() compiler = lines[-1] if compiler.startswith('[') and compiler.endswith(']'): compiler = compiler[1:-1] self._framework = tuple(compiler.split(' ', 1)) assert self._framework is not None return self._framework def getContext(self): """Get the context that this interpreter is running in as a string. Note: This is not always possible. Cached.""" release = platform.release().lower() if self._context is None: if 'pyrun_config' in sys.modules: self._context = 'PyRun' elif 'Stackless' in sys.version: fields = sys.version.split(None, 3) self._context = fields[1] + '/' + fields[2] elif 'ActiveState' in sys.copyright: self._context = 'ActiveState' elif ('microsoft' in release or 'wsl' in release or 'WSL_DISTRO_NAME' in os.environ): version = '?' # It's WSL. if 'wsl2' in release: version = 2 else: version = 1 self._context = 'WSL/' + str(version) else: self._context = '' assert self._context is not None return self._context # Details. def sanitize(self, suffix): """Normalize this key suffix if necessary.""" if self.useSanitization: if '_' in suffix: words = suffix.split('_') for i, word in enumerate(words): if i == 0: words[i] = word.lower() elif word in self.unsanitizableNames: words[i] = word else: words[i] = word.capitalize() suffix = ''.join(words) if suffix.isupper(): suffix = suffix.lower() if suffix[0].isupper(): suffix = suffix[0].lower() + suffix[1:] return suffix def key(self, prefix, suffix): """Make a key out of this prefix and suffix.""" if prefix and suffix: return prefix + self.delimiter + self.sanitize(suffix) elif prefix: return prefix else: # if suffix: return self.normalize(suffix) def has(self, prefix, suffix): """Is this key present?""" return self.key(prefix, suffix) in self.data def get(self, prefix, suffix, default=None): """Get the value for this key.""" key = self.key(prefix, suffix) if key in self: return self.data[key] else: return default def set(self, prefix, suffix, value): """Set a key/value pair.""" self.data[self.key(prefix, suffix)] = value def wrap(self, prefix, suffixes, func): """Replace an existing entry by passing it through a function.""" if not isinstance(suffixes, tuple): suffixes = (suffixes,) for suffix in suffixes: key = self.key(prefix, suffix) if key in self.data: self.data[key] = func(self.data[key]) def accumulate(self, prefix, suffixes, object, name, args=None, attr=None, func=None, kwargs=None, delim='/'): """Accumulate the results of a method or attribute in a dictionary. If the argument is None, just return the attribute; if not, treat it as a function and call it with the args and kwargs. If attr is not None, access that named attribute on the result before returning. If func is not None, pass the result through the function before storing.""" assert name is not None if prefix is None: prefix = '' result = getattr(object, name, None) if result is None: return error = None if not isinstance(suffixes, tuple): suffixes = (suffixes,) try: if args is not None: # It's a function call. if kwargs is None: kwargs = {} result = result(*args, **kwargs) if result is None: return if not isinstance(result, tuple): # If it's not a tuple, make it one for uniformity. result = (result,) if len(suffixes) == 1 and len(result) > 1: # If we have only one key but multiple values, then it's a # single key with a value that's a tuple. Join up the tuple # with the delimiter. result = (delim.join(result),) for suffix, value in zip(suffixes, result): # Now iterate over the suffixes/values: if suffix is None: # Skip suffixes that are None. continue if attr is not None: # We want an attribute of it. value = getattr(value, attr) if func is not None: # If there's a function wrapper, call it. value = func(value) assert suffix not in self.data self.set(prefix, suffix, value) except: # Some weird things can happen when calling/accessing the result: # # - Jython 2.5 raises an internal AttributeError when accessing # platform.architecture. # - IronPython 2.7 has not implemented platform.architecture. # - Some older versions of IronPython 2.7 raise an ImportError when # calling platform.platform which is then bizarrely reported as a # TypeError with no traceback by the executive. # # Set the appropriate values with a question mark and the name of # the exception which occurred to make it clear what happened. type, error, traceback = sys.exc_info() value = '?' + error.__class__.__name__ for suffix in suffixes: self.set(prefix, suffix, value) # Requirements. def parseRequirement(self, string): DISJUNCTION = ';' VERSION_OPERATORS = '><=!~' IMPLEMENTATION_OPERATORS = '-' strings = string.split(';') results = [] for string in strings: assert string if string[0] in VERSION_OPERATORS: # It's a version requirement. i = 0 while i < len(string) and string[i] in VERSION_OPERATORS: i += 1 op, ver = string[:i], string[i:].strip() results.append(VersionRequirement(op, ver)) else: # It's an implementation requirement. i = 0 while i < len(string) and string[i] in IMPLEMENTATION_OPERATORS: i += 1 op, impl = string[:i], string[i:].strip() results.append(ImplementationRequirement(op, impl)) if len(results) == 1: return results[0] else: return DisjunctiveRequirement(results) def parseRequirements(self, filename): requirements = [] file = open(filename) try: for line in file.readlines(): line = line.strip() if not line: continue elif line.startswith('#'): continue requirement = self.parseRequirement(line) requirements.append(requirement) finally: file.close() return requirements def checkRequirements(self, requirements): if isinstance(requirements, em.strType): requirements = self.parseRequirements(requirements) for requirement in requirements: if not requirement.check(self): return False return True # Details. def getBasicDetails(self): """Collect basic details.""" self.accumulate('basic', 'system', self, 'getSystemName', ()) self.accumulate('basic', 'os', self, 'getOSName', ()) self.accumulate('basic', 'machine', self, 'getMachineType', ()) self.accumulate('basic', 'implementation', self, 'getPythonImplementation', ()) self.accumulate('basic', 'version', self, 'getPythonVersion', ()) self.accumulate('basic/framework', ('name', 'version'), self, 'getFramework', ()) self.accumulate('basic', 'context', self, 'getContext', ()) def getPythonDetails(self): """Collect details about this interpreter. Use the platform module if available when the flag is set to true.""" self.accumulate('python', 'implementation', self, 'getPythonImplementation', ()) self.accumulate('python', 'version', self, 'getPythonVersion', ()) self.accumulate('python', 'branch', platform, 'python_branch', ()) self.accumulate('python/build', ('name', 'date'), platform, 'python_build', ()) self.accumulate('python', 'compiler', platform, 'python_compiler', ()) self.accumulate('python', 'revision', platform, 'python_revision', ()) def getSystemDetails(self): """Collect details about the system settings on this interpreter.""" self.accumulate('system/api', 'flags', sys, 'abiflags') self.accumulate('system/api', 'version', sys, 'api_version') self.accumulate('system', 'byteorder', sys, 'byteorder') self.accumulate('system', 'copyright', sys, 'copyright', func=repr) self.accumulate('system/filesystem', 'encoding', sys, 'getfilesystemencoding', ()) self.accumulate('system/filesystem', 'errors', sys, 'getfilesystemencodeerrors', ()) self.accumulate('system/float', ('max', 'max_exp', None, 'min', 'min_exp', None, 'dig', 'mant_dig', 'epsilon', 'radix', 'rounds'), sys, 'float_info') self.accumulate('system/hash', ('width', 'modulus', 'inf', 'nan', 'imag', 'algorithm', 'bits', 'seed_bits'), sys, 'hash_info') self.wrap('system/hash', 'modulus', hex) self.accumulate('system/int', ('bits', 'sizeof', 'default_max', 'check_threshold'), sys, 'int_info') self.accumulate('system/path', 'executable', sys, 'executable') self.accumulate('system/path', 'library', sys, 'platlibdir') self.accumulate('system/path', 'prefix', sys, 'prefix') self.accumulate('system', 'platform', sys, 'platform') self.accumulate('system', 'size/max', sys, 'maxsize', func=hex) self.set('system', 'unicode/build', ['wide', 'narrow'][em.narrow]) self.accumulate('system', 'unicode/max', sys, 'maxunicode', func=hex) self.accumulate('system/version', 'hex', sys, 'hexversion', func=hex) self.accumulate('system/version', 'str', sys, 'version', func=repr) def getPlatformDetails(self): """Collect details about this platform. Use the platform module if available when the flag is set to true.""" self.accumulate('platform/architecture', ('bits', 'linkage'), platform, 'architecture', ()) self.accumulate('platform', 'machine', platform, 'machine', ()) self.accumulate('platform', 'name', platform, 'platform', ()) self.accumulate('platform', 'node', platform, 'node', ()) self.accumulate('platform', 'processor', platform, 'processor', ()) self.accumulate('platform', 'release', platform, 'release', ()) self.accumulate('platform', 'system', platform, 'system', ()) self.accumulate('platform/thread', ('implementation', 'lock', 'version'), sys, 'thread_info') self.accumulate('platform', 'version', platform, 'version', ()) def getReleaseDetails(self, system=None): """Collect details about the given system release, or the running one if None.""" if system is None: system = self.getSystemName() methodName = 'getReleaseDetails_' + system method = getattr(self, methodName, None) if method is not None: method() # Release details specializations. def getReleaseDetails_Linux(self): """Collect details about the Linux release.""" PREFIX = 'release/linux' file = None for filename in self.releaseFilenames: try: file = open(filename, 'r') break except IOError: pass if file is None: return self.data try: while True: line = file.readline() if not line: break if line.endswith('\n'): line = line[:-1] key, value = line.split('=', 1) if value.startswith('"') and value.endswith('"'): value = value[1:-1] self.set(PREFIX, key, value) finally: file.close() def getReleaseDetails_Darwin(self): """Collect details about the Darwin release.""" PREFIX = 'release/darwin' PROGRAM = 'sw_vers' FILENAME = '/tmp/sw_vers_%d.out' % os.getpid() waitStatus = os.system('%s > %s 2> /dev/null' % (PROGRAM, FILENAME)) exitCode = waitStatus >> 8 if exitCode != 0: return file = None try: try: file = open(FILENAME, 'r') for line in file: if line.endswith('\n'): line = line[:-1] key, value = line.split(':', 1) key = key.strip() value = value.strip() self.set(PREFIX, key, value) except OSError: pass finally: if file is not None: file.close() try: os.remove(FILENAME) except OSError: pass def getReleaseDetails_Windows(self): """Collect details about the Windows release.""" PREFIX = 'release/windows' PRODUCT_TYPES = { 1: 'VER_NT_WORKSTATION', 2: 'VER_NT_DOMAIN_CONTROLLER', 3: 'VER_NT_SERVER', } self.accumulate(PREFIX, 'dllhandle', sys, 'dllhandle', func=hex) self.accumulate(PREFIX, 'registry', sys, 'winver') self.accumulate(PREFIX, ('major', 'minor', 'build', 'platform', 'service_pack'), sys, 'getwindowsversion', ()) self.accumulate(PREFIX, 'suite_mask', sys, 'getwindowsversion', (), attr='suite_mask', func=hex) self.accumulate(PREFIX, 'product_type', sys, 'getwindowsversion', (), attr='product_type', func=lambda x: PRODUCT_TYPES.get(x, x)) self.accumulate(PREFIX, 'platform_version', sys, 'getwindowsversion', (), attr='platform_version', func=lambda x: '.'.join([em.nativeStr(e) for e in x])) # Summary. def classify(self, version): """Classify a release by version string.""" PAIRS = [ ('a', 'alpha'), ('b', 'beta'), ('d', 'development'), ('g', 'gamma'), ('h', 'adhoc'), ('r', 'revision'), ('RC', 'release candidate'), ('v', 'version'), ('x', 'development'), ] # First, normalize it. if '-' in version and '.' not in version: version = version.replace('-', '.') major = version.split('.')[0] if len(major) == 4 and major.isdigit(): # If the major version looks like a year, it's a preview version. return 'preview' for key, name in PAIRS: if key in version: return name return None def collect(self, level): """Collect details.""" if level >= em.Version.BASIC: self.getBasicDetails() if level >= em.Version.PYTHON: self.getPythonDetails() if level >= em.Version.SYSTEM: self.getSystemDetails() if level >= em.Version.PLATFORM: self.getPlatformDetails() if level >= em.Version.RELEASE: self.getReleaseDetails() def show(self, level=em.Version.INFO, prelim="", postlim="", file=None): """Show details.""" if file is None: file = sys.stdout write = file.write if prelim: write(prelim) write("%s version %s" % (em.__project__, em.__version__)) classification = self.classify(em.__version__) if classification: write(" [%s]" % classification) if level >= em.Version.INFO: write(", in %s/%s" % ( self.getPythonImplementation(), self.getPythonVersion())) context = self.getContext() if context: write(", as %s" % context) write(", on %s (%s)" % ( self.getSystemName(), self.getOSName())) write(", with %s" % self.getMachineType()) framework = self.getFramework() if framework: write(", under %s/%s" % framework) if em.compat: write(" (%s)" % ', '.join(em.compat)) if postlim: write(postlim) if self.empty(): self.collect(level) if level >= em.Version.DATA: if self.data: write("Details:\n") items = list(self.data.items()) items.sort() for key, value in items: if value is None or value == '': value = '--' write("- %s: %s\n" % (key, value)) else: write("(No details available.)\n") # # main # def main(): if len(sys.argv) > 1: arg = sys.argv[1] try: level = int(arg) except ValueError: level = getattr(em.Version, arg) else: level = em.Version.ALL details = Details() details.show(level, prelim="Welcome to ", postlim=".\n") if __name__ == '__main__': main() empy-4.2.1/README.md0000644000175000017500000106764215142227046013714 0ustar jriverojrivero# User's guide ## Introduction: Welcome to EmPy! [EmPy](http://www.alcyone.com/software/empy/) is a powerful, robust and mature templating system for inserting Python code in template text. EmPy takes a source document, processes it, and produces output. This is accomplished via expansions, which are signals to the EmPy system where to act and are indicated with markup. Markup is set off by a customizable prefix (by default the at sign, `@`). EmPy can expand arbitrary Python expressions, statements and control structures in this way, as well as a variety of additional special forms. The remaining textual data is sent to the output, allowing Python to be used in effect as a markup language. EmPy also supports hooks, which can intercept and modify the behavior of a running interpreter; diversions, which allow recording and playback; filters, which can alter output and can be chained together. The system is highly configurable via command line options, configuration files, and environment variables. EmPy documents can also be imported as modules, and an extensive API is also available for embedding EmPy functionality in your own Python programs. EmPy also has a supplemental library for additional non-essential features (`emlib`), a documentation building library used to create this documentation (`emdoc`), and an extensive help system (`emhelp`) which can be queried from the command line with the main executable `em.py` (`-h/--help`, `-H/--topics=TOPICS`). The base EmPy interpreter can function with only the `em.py`/`em` file/module available. EmPy can be used in a variety of roles, including as a templating system, a text processing system (preprocessing and/or postprocessing), a simple macro processor, a frontend for a content management system, annotating documents, for literate programming, as a souped-up text encoding converter, a text beautifier (with macros and filters), and many other purposes. ### Markup overview Expressions are embedded in text with the `@(...)` notation; variations include conditional expressions with `@(...?...!...)` and the ability to handle thrown exceptions with `@(...$...)`. As a shortcut, simple variables and expressions can be abbreviated as `@variable`, `@object.attribute`, `@sequence[index]`, `@function(arguments...)`, and combinations. Functions can be called with expanded markup as arguments using `@function{markup}{...}`. Full-fledged statements are embedded with `@{...}`. Control flow in terms of conditional or repeated expansion is available with `@[...]`. A `@` followed by any whitespace character (including a newline) expands to nothing, allowing string concatenations and line continuations. Line comments are indicated with `@#...` including the trailing newline. `@*...*` allows inline comments. Output can be disabled and re-enabled with `@-...` and `@+...`, including the trailing newlines. Escapes are indicated with `@\...`; diacritics with `@^...`; icons with `@|...`; and emoji with `@:...:`. `@%...`, `@%!...`, `@%%...%%` and `@%%!...%%` indicate "significators," which are distinctive forms of variable assignment intended to specify document metadata in a format easy to parse externally. In-place expressions are specified with `@$...$...$`. Context name and line number changes can be made with `@?...` and `@!...`, respectively. A set of markups (`@((...))`, `@[[...]]`, `@{{...}}`, `@<...>`) are customizable by the user and can be used for any desired purpose. `` @`...` `` allows literal escaping of any EmPy markup. Output can be toggled on and off with `@+` and `@-`, respectively. And finally, a `@@` sequence (the prefix repeated once) expands to a single literal at sign. The prefix defaults to `@` but can be changed with the command line option `-p/--prefix=CHAR` (_environment variable:_ `EMPY_PREFIX`, _configuration variable:_ `prefix`). ### Getting the software The current version of EmPy is 4.2.1. The official URL for this Web site is . The latest version of the software is available in a tarball here: . The software can be installed through PIP via this shell command: 
% python3 -m pip install empy
For information about upgrading from 3._x_ to 4._x_, see . ### Requirements EmPy works with any modern version of Python. Python version 3._x_ is expected to be the default and all source file references to the Python interpreter (_e.g._, the bangpath of the .py scripts) use `python3`. EmPy also has legacy support for versions of Python going back all the way to 2.4, with special emphasis on 2.7 regardless of its end-of-life status. It has no dependency requirements on any third-party modules and can run directly off of a stock Python interpreter. EmPy will run on any operating system with a full-featured Python interpreter; this includes, but is probably not limited to, the operating systems Linux, Windows, Windows Subsystem for Linux 2 (WSL2) and macOS (Darwin). Using EmPy requires knowledge of the [Python language](https://www.python.org/). EmPy is compatible with many different Python implementations, interpreter variants, packaging systems, and enhanced shells: {#supported-versions-table} | Variant | Supported versions | Description | | --- | --- | --- | | [CPython](https://www.python.org/) | 2.4 and up | Standard implementation in C | | [PyPy](https://www.pypy.org/) | 2.7 and up | Implementation with just-in-time compiler | | [Stackless Python](https://github.com/stackless-dev/stackless/wiki/) | 2.4 and up | Implementation supporting microthreading | | [IronPython](https://ironpython.net/) | 2.7 and up | Implementation for .NET CLR and Mono | | [Jython](https://www.jython.org/) | 2.5 to 2.7 (and up?) | Implementation for JVM | | [ActiveState Python](https://www.activestate.com/products/python/) | 2.7 and up | Secure supply chain open source solution | | [eGenix PyRun](https://www.egenix.com/products/python/PyRun/) | 2.5 and up | One-file, no-installation CPython environment | | [WinPython](https://winpython.github.io/) | 3.0 and up | Portable Scientific Python for Windows | | [PortablePython](https://portablepython.com/) | 2.7 and up | Minimalistic Python distribution for Windows | | [IDLE](https://docs.python.org/3/library/idle.html) | all | Python's Integrated Development and Learning Environment | | [IPython](https://ipython.org/) | all | Powerful interactive shell; kernel for [Jupyter](https://jupyter.org/) | EmPy is also compatible with scaled-down implementations of Python, provided they support the set of standard modules that EmPy requires, namely: - `codecs ` - `copy ` - `getopt ` - `os ` - `platform ` - `re ` - `sys ` - `unicodedata ` Only a few .py module file(s) are needed to use EmPy; they can be installed system-wide through a distribution package, via PIP, or just dropped into any desired directory in the `PYTHONPATH` (as a module) and/or `PATH` (as an executable). A minimal installation need only install the em.py file, either as an importable module or an executable, or both, depending on the user's needs. EmPy also has optional support for several [third-party emoji modules](#third-party-emoji-modules); see [](#emoji-markup) for details. The testing system included (the test.sh script and the tests and suites directories) is intended to run on Unix-like systems with a Bourne-like shell (_e.g._, sh, bash, zsh, etc.). EmPy is routinely tested with all supported versions of all available interpreters. If you find an incompatibility with your Python interpreter or operating system, [let me know](#reporting-bugs). ### License This software is licensed under [BSD (3-Clause)](https://opensource.org/licenses/bsd-3-clause/). ## Getting started This section serves as a quick introduction to the EmPy system. For more details, see the sections below. :::{hint} As an introduction to the terminology, the following names are used throughout: {#terminology-table} | Name | Description | | --- | --- | | `EmPy` | The name of the software | | `em.py` | The name of the executable and main source file | | `em` | The name of the main module | | `empy` | The name of the [pseudomodule](#pseudomodule-and-interpreter), as well as the PyPI package | | `.em` | The conventional filename extension for EmPy documents | ::: ### Starting EmPy After installing EmPy (see [](#getting-the-software)), EmPy is invoked by running the EmPy **executable**, `em.py`, on the command line (standalone mode). If it is invoked without arguments, it will accept input from `sys.stdin`. Unless otherwise specified, the output is sent to `sys.stdout`. You can use this as an interactive session to familiarize yourself with EmPy when starting out: 
% em.py
... accepts input from stdin with results written to stdout ...
If an EmPy document is specified (which by convention has the extension .em, though this is not enforced), then that document is used as input: 
% em.py document.em
... document.em is processed with results written to stdout ...
:::{note} In some distribution packages, the EmPy interpreter may be named `empy` rather than `em.py`. In the [official release tarballs](#getting-the-software), and throughout this documentation, it is `em.py`. This is to distinguish it from the pseudomodule `empy`. ::: :::{warning} If your document filename begins with a `-`, it will be interpreted as a command line argument and cause command line option processing errors. Either precede it with a relative path (_e.g._, `em.py ./-weirdname.em`) or the GNU-style `--` option which indicates there are no further options (_e.g._, `em.py -- -weirdname.em`). ::: Any number of command line arguments (beginning with `-` or `--`) can precede the document name. The command line argument `--` indicates that there are no more options. For instance, this command writes its output to document.out: 
% em.py -o document.out document.em
... document.em is processed with results written to document.out ...
Many options are available to change the behavior of the EmPy system. This command will open the input file as UTF-8, write the output file as Latin-1, show raw errors if they occur, and delete the output file if an error occurs: 
% em.py --input-encoding=utf-8 --output-encoding=latin-1 -r -d -o document.out document.em
... you get the idea ...
EmPy documents can also take arguments, which are an arbitrary sequence of strings that follow after the document, and are analogous to the Python interpreter arguments `sys.argv`: 
% em.py document.em run test
... empy.argv is ['document.em', 'run', 'test'] ...
:::{tip} When installed as a module, EmPy can also be invoked as 
% python3 -m em
...
::: :::{tip} You can create executable EmPy scripts by making their file executable and starting them with a bangpath: ```shell #!/usr/bin/env em.py ... EmPy code here ... ``` By default, bangpaths are treated as EmPy comments unless `--no-ignore-bangpaths` (_configuration variable:_ `ignoreBangpaths = False`) is specified. ::: :::{tip} If you wish to run EmPy under Python 2._x_ for some reason on a system that also has Python 3 installed, explicitly invoke the Python 2 interpreter when running it (`python2 em.py ...`). If you wish to make this more streamlined, edit the first line ("bangpath") of the em.py executable and change it to read `#!/usr/bin/env python2` (or whatever your Python 2._x_ interpreter is named). ::: :::{seealso} See the [](#command-line-options) section for a list of command line options that EmPy supports. ::: ### The prefix and markup expansion EmPy **markup** is indicated with a configurable **prefix**, which is by default the at sign (`@`). The character (Unicode code point) following the prefix indicates what type of markup it is. There are a wide variety of markups available, from comments to expression evaluation to statement execution, and from prefixes, literals and escapes to diacritics, icons and emojis. Converting markup into text to be rendered as output is referred to as **expansion**. Here is a long EmPy code sample illustrating some of the more essential markups in EmPy, though there are several not shown here: :::{admonition} Example 1: Markup sample _Source_: ⌨️
`````` Comments: The line below will not render. @# This is a line comment, up to and including the newline. If a line comment appears in the middle of a line, @# this is a comment! the line will be continued. Inline comments can be @*placed inline* (this phrase did not render, but note the double space due to the spaces before and after it). @** * Or it can span multiple lines. **@ Whitespace markup consumes the following space. So two@ words become one word. And this @ is a line continuation. @* Inline comments can be used as a line comment. *@ Note the use of the trailing prefix to consume the final newline; this is a common idiom. Literals: Double the prefix to render it: @@. String literals can be used to render escaped Python strings: @ @"A is also \N{LATIN CAPITAL LETTER A}". Escape markup can render arbitrary characters: These are all Latin capital letter A: @ A, @\B{1000001}, @\q1001, @\o101, @\x41, @\u0041, @\U00000041, @\N{LATIN CAPITAL LETTER A}. Backquotes can be used to escape EmPy markup. This is not evaluated: @`@(!@#$%^&*()`. Expressions: Python expressions can be evaluated like this: 1 + 2 = @(1 + 2). Expressions can be arbitrary complex: @ This is running in Python @('.'.join(str(x) for x in __import__('sys').version_info[:3])). Expressions can contain builtin ternary operators: Seven is an @(7 % 2 == 0 ? 'even' ! 'odd') number. They can even handle exceptions: @ Division by zero is @(1/0 $ 'illegal'). Statements: @{ print("Hello, world!") x = 123 }@ x is now @(x), which can be simplified to @x. Statements can execute arbitrarily complex Python code, including defining functions and classes. Back to expressions, they can be simplified: @{ # Define some variables. class Person: def __init__(self, name): self.name = name a = [4, 5, 6] p = Person('Fred') }@ x is @x. a[1] is @a[1]. The name of p is @p.name. You can even call functions this way: p's name when shouted is @p.name.upper(). Note that the parser does not try to evaluate end-of-sentence punctuation. Control structures: Iterate over some numbers and classify them, but stop after 5: @[for n in range(-1, 10)]@ @[ if n > 5]@ And done. @[ break]@ @[ end if]@ @n is @ @[ if n < 0]@ negative@ @[ elif n == 0]@ zero@ @[ elif n % 2 == 0]@ even@ @[ else # odd]@ odd@ @[ end if]@ . @[end for]@ Note the use of indentation inside control markup and end-of-line whitespace markup (a prefix with trailing whitespace is consumed) to make things more clear (though this is optional). You can even define your own EmPy functions: @[def officer(name, species, rank, role)]@ @# The definition is EmPy, not Python! @name (@species, @rank, @role)@ @[end def]@ Some of the bridge crew of the USS Enterprise (NCC-1701): - @officer("James T. Kirk", "Human", "captain", "commanding officer") - @officer("Spock", "Vulcan-Human hybrid", "commander", "science officer") - @officer("Montgomery Scott", "Human", "commander", "chief engineer") - @officer("Nyota Uhura", "Human", "lieutenant commander", "communications officer") - @officer("Hikaru Sulu", "Human", "commander", "astrosciences/helmsman") Diacritics: Libert@^e', @^e'galit@^e', fraternit@^e'! Icons for curly quotes: @|"(these are curly quotes.@|") This is an emoji: @:pile of poo:. (Of course I would choose that one.) ``````
_Output_: 🖥️
`````` Comments: The line below will not render. If a line comment appears in the middle of a line, the line will be continued. Inline comments can be (this phrase did not render, but note the double space due to the spaces before and after it). Whitespace markup consumes the following space. So twowords become one word. And this is a line continuation. Note the use of the trailing prefix to consume the final newline; this is a common idiom. Literals: Double the prefix to render it: @. String literals can be used to render escaped Python strings: A is also A. Escape markup can render arbitrary characters: These are all Latin capital letter A: A, A, A, A, A, A, A, A. Backquotes can be used to escape EmPy markup. This is not evaluated: @(!@#$%^&*(). Expressions: Python expressions can be evaluated like this: 1 + 2 = 3. Expressions can be arbitrary complex: This is running in Python 3.10.12. Expressions can contain builtin ternary operators: Seven is an odd number. They can even handle exceptions: Division by zero is illegal. Statements: Hello, world! x is now 123, which can be simplified to 123. Statements can execute arbitrarily complex Python code, including defining functions and classes. Back to expressions, they can be simplified: x is 123. a[1] is 5. The name of p is Fred. You can even call functions this way: p's name when shouted is FRED. Note that the parser does not try to evaluate end-of-sentence punctuation. Control structures: Iterate over some numbers and classify them, but stop after 5: -1 is negative. 0 is zero. 1 is odd. 2 is even. 3 is odd. 4 is even. 5 is odd. And done. Note the use of indentation inside control markup and end-of-line whitespace markup (a prefix with trailing whitespace is consumed) to make things more clear (though this is optional). You can even define your own EmPy functions: Some of the bridge crew of the USS Enterprise (NCC-1701): - James T. Kirk (Human, captain, commanding officer) - Spock (Vulcan-Human hybrid, commander, science officer) - Montgomery Scott (Human, commander, chief engineer) - Nyota Uhura (Human, lieutenant commander, communications officer) - Hikaru Sulu (Human, commander, astrosciences/helmsman) Diacritics: Liberté, égalité, fraternité! Icons for curly quotes: “these are curly quotes.” This is an emoji: 💩. (Of course I would choose that one.) ``````
::: :::{tip} If you wish to change the prefix, use `-p/--prefix=CHAR` (_environment variable:_ `EMPY_PREFIX`, _configuration variable:_ `prefix`). ::: :::{seealso} See the [](#markup) section for detailed specifications on all support EmPy markup. ::: ### Pseudomodule and interpreter The **interpreter** instance is available to a running EmPy system through the globals; by default, it is named `empy`. When it is referenced this way, it is called a **pseudomodule** (since it acts like a module although it is not actually a module you can import): :::{admonition} Example 2: Pseudomodule sample _Source_: ⌨️
`````` This version of EmPy is @empy.version. The prefix in this interpreter is @empy.getPrefix() @ and the pseudomodule name is @empy.config.pseudomoduleName. Do an explicit write: @empy.write("Hello, world!"). The context is currently @empy.getContext(). Adding a new global in a weird way: @ @empy.updateGlobals({'q': 789})@ Now q is @q! You can do explicit expansions: @empy.expand("1 + 1 = @(1 + 1)"). q is @(empy.defined('q') ? 'defined' ! 'undefined'). ``````
_Output_: 🖥️
`````` This version of EmPy is 4.2.1. The prefix in this interpreter is @ and the pseudomodule name is empy. Do an explicit write: Hello, world!. The context is currently :5:26. Adding a new global in a weird way: Now q is 789! You can do explicit expansions: 1 + 1 = 2. q is defined. ``````
::: :::{seealso} See the [Pseudomodule/interpreter](#pseudomodule-interpreter) section for details on the pseudomodule/interpreter. ::: ### Diversions, filters & hooks **Diversions** can defer and replay output at a desired time: :::{admonition} Example 3: Diversions sample _Source_: ⌨️
`````` This text is output normally. @empy.startDiversion('A')@ (This text was diverted!) @empy.stopDiverting()@ This text is back to being output normally. Now playing the diversion: @empy.playDiversion('A')@ And now back to normal output. ``````
_Output_: 🖥️
`````` This text is output normally. This text is back to being output normally. Now playing the diversion: (This text was diverted!) And now back to normal output. ``````
::: **Filters** can modify output before sending it to the final stream: :::{admonition} Example 4: Filters sample _Source_: ⌨️
`````` @{ # For access to the filter classes. import emlib }@ This text is normal. @empy.appendFilter(emlib.FunctionFilter(lambda x: x.upper()))@ This text is in all uppercase! @empy.appendFilter(emlib.FunctionFilter(lambda x: '[' + x + ']'))@ Now it's also surrounded by brackets! (Note the brackets are around output as it is sent, not at the beginning and end of each line.) @empy.resetFilter()@ Now it's back to normal. ``````
_Output_: 🖥️
`````` This text is normal. THIS TEXT IS IN ALL UPPERCASE! [NOW IT'S ALSO SURROUNDED BY BRACKETS! (NOTE THE BRACKETS ARE AROUND OUTPUT AS IT IS SENT, NOT AT THE BEGINNING AND END OF EACH LINE.) ]Now it's back to normal. ``````
::: **Hooks** can intercept and even alter the behavior of a running system: :::{admonition} Example 5: Hooks sample _Source_: ⌨️
`````` @# Modify the backquote markup to prepend and append backquotes @# (say, for a document rendering system, cough cough). @{ import emlib class BackquoteHook(emlib.Hook): def __init__(self, interp): self.interp = interp def preBackquote(self, literal): self.interp.write('`' + literal + '`') return True # return true to skip the standard behavior empy.addHook(BackquoteHook(empy)) }@ Now backquote markup will render with backquotes: @ @`this is now in backquotes`! ``````
_Output_: 🖥️
`````` Now backquote markup will render with backquotes: `this is now in backquotes`! ``````
::: :::{seealso} See the [](#diversions), [](#filters), or the [](#hooks) sections for more information. ::: ### Embedding EmPy is modular and can be **embedded** in your Python programmers, rather than running it standalone. In Python, simply import the `em` module and create an `Interpreter`: ```python import sys import em config = em.Configuration(...) output = sys.stdout with em.Interpreter(config=config, output=output) as interp: ... do things with interp ... ``` An exception which occurs during processing will be handled by the interpreter's error handler. For one-off uses, you can use the global, standalone `expand` function: ```python import em result = em.expand(source) ``` When calling this function, an ephemeral interpreter is dynamically created, used, and shutdown to perform the expansion. If an exception occurs during this processing, it will be raised to the caller, rather than handled by the ephemeral interpreter. ::: :::{important} When you create an interpreter, you must call its `shutdown` method when you are done. This is required to remove the proxy on `sys.stdout` that EmPy requires for proper operation and restore your Python environment to the state it was before creating the interpreter. This can be accomplished by creating the interpreter in a `with` statement -- interpreters are also context managers -- or by creating it and shutting it down in a `try`/`finally` statement. This is not needed when calling the `expand` global function; it creates and shuts down an ephemeral interpreter automatically. ::: :::{seealso} See the [](#embedding-empy) section for more details on embedding EmPy in your Python programs. ::: ### Getting help For basic help, use the `-h/--help` option: 
% em.py -h # or: --help
Welcome to EmPy version 4.2.1.

USAGE:
./em.py [<options>] [<filename, or `-` for stdin> [<argument>...]]
  - Options begin with `-` or `--`
  - Specify a filename (and arguments) to process that document as input
  - Specify `-` (and arguments) to process stdin with standard buffering
  - Specify no filename to enter interactive mode with line buffering
  - Specify `--` to stop processing options

...
For more help, repeat the `-h/--help` option (up to three times for the full help). For help on a particular topic, use the `-H/--topics=TOPICS` option, where `TOPICS` is a comma-separated list of topics. The list of available topics can be shown by using the topic `topics`: 
% em.py -H topics # or: --topics=topics
Welcome to EmPy version 4.2.1.

TOPICS:
Need more help?  Add more -h options (-hh, -hhh) for more help.  Use -H <topic>
for help on a specific topic, or specify a comma-separated list of topics.  Try
`default` (-h) for default help, `more` (-hh) for more common topics, `all`
(-hhh) for all help topics, or `topics` for this list.  Use -V for version
information, -W for version and system information, or -Z for all debug
details.  Available topics:
  usage        Basic command line usage
  options      Command line options
  simple       Simple (one-letter) command line options
  markup       Markup syntax
  escapes      Escape sequences
  environ      Environment variables
  pseudo       Pseudomodule attributes and functions
  constructor  Keyword arguments for the Interpreter constructor
  variables    Configuration variable attributes
  methods      Configuration methods
  hooks        Hook methods
  named        Named escapes
  diacritics   Diacritic combiners
  icons        Icons
  hints        Usage hints
  topics       This list of topics
:::{tip} Repeating the help option once (`-hh`) is the same as requesting the `more` topic (`-H more`). Repeating it three times (`-hhh`) is the same as requesting the `all` topic (`-H all`). ::: :::{warning} The builtin help system requires the presence of the `emhelp` module. If you have a minimal EmPy installation, this module may not be available. You can get it from the [release tarball](#getting-the-software). ::: :::{seealso} See the rest of this document for details and specifications on all the markup and features, and see the [Help topics section](HELP.md) for the output of all the builtin help topics. ::: ## Markup EmPy markup always begins with the EmPy prefix, which defaults to `@`. The character (Unicode code point) following the prefix indicates what type of markup it is, and the different types of markup are parsed differently. It is legal to set the EmPy prefix to `None`; then, no markup will be parsed or expanded and EmPy will merely process filters and encoding conversions. This can be done from the command line with the `--no-prefix` option, or by indicating a prefix that is an empty string (`''`) or the word `none`. Using a non-default prefix that is also the first character of an existing markup will swap that markup character with the default. For example, setting the prefix to `$` would otherwise collide with the in-place token (`@$...$...$` with a default prefix). On startup it will be adjusted so that with a `$` prefix the in-place markup can be accessed as `$@...@...@`. The following subsections list the types of markup supported by EmPy and in which version they were introduced, organized by category. `NL` represents a newline and `WS` represents any whitespace. :::{important} All of the following code snippets and examples below assume that the prefix is the default, `@`. It can be changed with `-p/--prefix=CHAR` (_environment variable:_ `EMPY_PREFIX`, _configuration variable:_ `prefix`). ::: {#markup-table} | Markup | Syntax | Description | Ver. | | --- | --- | --- | --- | | [Line comment](#line-comment-markup) | `@#... NL` | Consumes text up to and including newline | 1.0 | | [Inline comment](#inline-comment-markup) | `@*...*` | Consumes text up to and including the final asterisk(s) | 4.0 | | [Whitespace](#whitespace-markup) | `@ WS` | Consumes the following whitespace character | 1.0 | | [Switch disable](#output-disable-markup) | `@-... NL` | Disables output | 4.2 | | [Switch enable](#output-enable-markup) | `@+... NL` | (Re-)enables output | 4.2 | | [Prefix](#prefix-markup) | `@@` | Produces the prefix character | 1.0 | | [String](#string-markup) | `@'...'`, `@"..."`, `@'''...'''`, `@"""..."""` | Produces a string from a literal | 3.1.1 | | [Backquote](#backquote-markup) | `` @`...` `` | Quotes contained markup up to final backquote(s) | 4.0 | | [Escape](#escape-markup) | `@\...` | Render an escape character | 1.5 | | [Named escape](#named-escape-markup) | `@\^{...}` | Render an escape control character by name | 4.0 | | [Expression](#expression-markup) | `@(...)` | Evaluates an expression | 1.0 | | [Simple expression](#simple-expression-markup) | `@variable`, `@object.attribute`, `@array[index]`, `@function(args...)`, etc. | Evaluates a simple expression | 1.0 | | [Functional expression](#functional-expression-markup) | `@function{markup}{...}` | Evaluates a functional expression | 4.0 | | [Extended expression](#extended-expression-markup) | `@(...?...!...$...)` | Expression evaluation with if-else-except | 1.3 | | [In-place expression](#in-place-expression-markup) | `@$...$...$` | Copies and evaluates an expression | 1.4 | | [Statement](#statement-markup) | `@{...}` | Executes a statement or statements | 1.0 | | [Control](#control-markups) | `@[...]` | Control structures | 3.0 | | [If control](#if-control-markup) | `@[if C1]`…`@[elif C2]`…`@[else]`…`@[end if]` | Branching control structure | 3.0 | | [Break control](#break-and-continue-control-markup) | `@[break]` | Break out of repeating control structure | 3.0 | | [Continue control](#break-and-continue-control-markup) | `@[continue]` | Continue with next iteration of repeating control structure | 3.0 | | [For control](#for-control-markup) | `@[for N in E]`…`@[else]`…`@[end for]` | Iterating control structure | 3.0 | | [While control](#while-control-markup) | `@[while E]`…`@[else]`…`@[end while]` | Looping control structure | 3.0 | | [Dowhile control](#dowhile-control-markup) | `@[dowhile E]`…`@[else]`…`@[end dowhile]` | Looping control structure always entered once (`do`/`while` structure analogous to C, C++) | 4.0 | | [Try control](#try-control-markup) | `@[try]`…`@[except E1 as N1]`…`@[else]`…`@[finally]`…`@[end try]` | Exception handling, guarding | 3.0 | | [With control](#with-control-markup) | `@[with E as N]`…`@[end with]` | Handle a context manager | 4.0 | | [Match control](#match-control-markup) | `@[match E]@[case C1]`…`@[else]`…`@[end match]` | Structural pattern matching | 4.1 | [Defined control](#defined-control-markup) | `@[defined N]`…`@[else]`…`@[end defined]` | Branch on whether a variable is defined | 4.0 | | [Def control](#def-control-markup) | `@[def F(...)]`…`@[end def]` | Define an EmPy function | 3.0 | | [Diacritic](#diacritic-markup) | `@^...` | Render and normalize diacritic combiner(s) | 4.0 | | [Icon](#icon-markup) | `@\|...` | Render a customizable icon | 4.0 | | [Emoji](#emoji-markup) | `@:...:` | Render a customizable emoji | 4.0 | | [Significator](#significator-markup) | `@%... NL`, `@%!... NL`, `@%%...%% NL`, `@%%!...%% NL` | Declare a significator (metadata assignment) | 1.2 | | [Context name](#context-name-markup) | `@?... NL` | Set the context filename | 3.0.2 | | [Context line](#context-line-markup) | `@!... NL` | Set the context line | 3.0.2 | | [Extension](#extension-markup) | `@((...))`, `@[[...]]`, `@{{...}}`, `@<...>`, … | Fully-customizable markups with no set definition | 4.1 | :::{seealso} The list of supported markup is available in the `markup` help topic and is summarized [here](HELP.md#markup-summary). ::: ### Comment markup Comment markup consumes its contents and performs no output. A few variants of comment markup are available. #### Line comment markup: `@#... NL` **Line comment markup** consists of a starting `@#` and consumes up until (and including) the following newline. Note that if the markup appears in the middle of a line, that line will be continued since it consumes the ending newline. :::{admonition} Example 6: Line comments _Source_: ⌨️
`````` @# This is a comment. It will not render in the output. @# Even would-be EmPy markup is consumed by a comment: @(!@#$%^&*() Welcome to EmPy! Here's some text @# This will consume the rest of the line on the same line. ``````
_Output_: 🖥️
`````` Welcome to EmPy! Here's some text on the same line. ``````
::: :::{versionadded} 1.0 Line comment markup was introduced in EmPy version 1.0. ::: #### Inline comment markup: `@*...*` **Inline comment markup** (`@*...*`) is a form of comment markup that can appear anywhere in text and can even span multiple lines. It consumes everything up to and including the final asterisk(s). :::{admonition} Example 7: Inline comments, basic _Source_: ⌨️
`````` This is text. @* This is a comment in the text. * This is continuing text. (Note the extra spaces around where the comment was.) @* A trailing whitespace markup consumes the whole line. *@ There is no extraneous blank line here. ``````
_Output_: 🖥️
`````` This is text. This is continuing text. (Note the extra spaces around where the comment was.) There is no extraneous blank line here. ``````
::: Multiple asterisks can be used as long as they are matched with the end of the markup. This allows asterisks to appear in the comment, provided there are fewer asterisks than the delimiters: :::{admonition} Example 8: Inline comments, advanced _Source_: ⌨️
`````` @** Here's an asterisk inside the comment: * **@ @*** There can * be any number of asterisks ** as long as it's * less than ** the delimiters. ***@ @** * This is a multiline inline comment. **@ @************************************* * This comment thinks it's so cool. * *************************************@ So many comments! ``````
_Output_: 🖥️
`````` So many comments! ``````
::: :::{attention} Note that when markup which has starting and ending delimiters appears alone on a line, the trailing newline will be rendered in the output. To avoid these extra newlines, use a trailing `@` to turn it into whitespace markup which consumes that trailing newline, so _e.g._ `` @*...* `` followed by a newline becomes `` @*...*@`` followed by a newline. This is idiomatic for suppressing unwanted newlines. See [here](#idiom) for more details. ::: :::{versionadded} 4.0 Inline comment markup was introduced in EmPy version 4.0. ::: #### Whitespace markup: `@ WS` While not quite a comment, **whitespace markup** is sufficiently common and useful that it warrants introduction early on. The interpreter prefix followed by any whitespace character, including a newline, is consumed. This allows a way to concatenate two strings, create a line continuation, or create a line separator: :::{admonition} Example 9: Whitespace, basic _Source_: ⌨️
`````` This was two@ words. Now it is one. Note that this consumes the newline @ so that this is on the same line. @ Note there is no blank line above. ``````
_Output_: 🖥️
`````` This was twowords. Now it is one. Note that this consumes the newline so that this is on the same line. Note there is no blank line above. ``````
::: ::::{tip} {#idiom} A trailing prefix after markup which has beginning and ending delimiters -- for instance, inline comment (`@*...*`), expression (`@(...)`), statement (`@{...}`) and control (`@[...]`) -- is idiomatic for suppressing the newline when there is nothing at the end of the line after the markup. The trailing prefix will consume the final newline, eliminating unwanted newlines. For example, using a statement markup (see below) on a whole line will result in a seemingly spurious newline: :::{admonition} Example 10: Whitespace, idiom _Source_: ⌨️
`````` Statement markup: @{x = 123} Note there's an extra newline above from the EmPy code after the statement markup. The markup itself doesn't print anything; it's from the trailing newline after the markup. To suppress the extra newline: @{x = 456}@ The trailing prefix above consumes the trailing newline, eliminating it. ``````
_Output_: 🖥️
`````` Statement markup: Note there's an extra newline above from the EmPy code after the statement markup. The markup itself doesn't print anything; it's from the trailing newline after the markup. To suppress the extra newline: The trailing prefix above consumes the trailing newline, eliminating it. ``````
::: :::: :::{versionadded} 1.0 Whitespace markup was introduced in EmPy version 1.0. ::: #### Switch markup Output to the underlying file can be switched on and off with output **switch markup**. This can be useful, for instance, when sourcing a file that is a "header" or "module" which defines various objects but its output is irrelevant; you can disable output at the beginning of the file and enable it at the end to ensure that any output is ignored. By default, output is enabled. Both markups consume everything up to and including the next newline, effectively acting as a comment analogous to `@#`. The markup is very simple. :::{versionadded} 4.2 Switch markups were introduced in EmPy version 4.2. ::: ##### Switch disable markup: `@-... NL` A line starting with `@-` is **switch disable markup** and will disable output. The entire line is consumed. :::{admonition} Example 11: Output disable _Source_: ⌨️
`````` This will be rendered to the output. @- This will not. @- The rest of this line is consumed as a comment. The output for this line is also disabled. ``````
_Output_: 🖥️
`````` This will be rendered to the output. ``````
::: ##### Switch enable markup: `@+... NL` A line starting with `@+` is **switch enable markup** and will (re-)enable output. The entire line is consumed. For example: :::{admonition} Example 12: Output disable and enable _Source_: ⌨️
`````` This will be rendered to the output. @- This will not. @+ But this will. @- Note that you can use the rest of the line as a comment. This will not be rendered. @+ This, too, will act as a comment. This will also be rendered. ``````
_Output_: 🖥️
`````` This will be rendered to the output. But this will. This will also be rendered. ``````
::: :::{note} [](#diversions) attempt to write their contents to the output stream only when they are played (or replayed), not when they are created. Thus, you can create diversions when output is disabled just fine: :::{admonition} Example 13: Output switches: diversions _Source_: ⌨️
`````` @- @# Output is disabled; now create a diversion. @empy.startDiversion('test')@ This text is diverted. @empy.stopDiverting()@ @# Replaying the diversion when output is disabled will print nothing. @empy.replayDiversion('test')@ @+ @# But now that it is enabled, it will print normally. @empy.playDiversion('test')@ ``````
_Output_: 🖥️
`````` This text is diverted. ``````
::: ::: ### Literal markups **Literal markups** are a category of markup that evaluate to some form of themselves. #### Prefix markup: `@@` To render the prefix character literally in the output, duplicate it as **prefix markup**. For the default, `@`, it will be `@@`: :::{admonition} Example 14: Prefix literals _Source_: ⌨️
`````` This becomes a single at sign: @@. ``````
_Output_: 🖥️
`````` This becomes a single at sign: @. ``````
::: :::{tip} The prefix markup is not indicated by the prefix followed by an at sign, but rather the prefix repeated once. So if the prefix has been changed to `$`, the prefix markup is `$$`, not `$@`. ::: :::{versionadded} 1.0 Prefix markup was introduced in EmPy version 1.0. ::: #### String markup: `@'...'`, `@"..."`, `@'''...'''`, `@"""..."""` The interpreter prefix followed by a Python string literal (_e.g._, `@'...'`) is **string markup**. It evaluates the Python string literal and expands it. All variants of string literals with single and double quotes, as well as triple quoted string literals (with both variants) are supported. This can be useful when you want to use Python string escapes (not EmPy escapes) in a compact form: :::{admonition} Example 15: String _Source_: ⌨️
`````` This is a string: @'A single-quoted string'. This is also a string: @"A double-quoted string". This is another string: @'''A triple single-quoted string'''. This is yet another string: @"""A triple double-quoted string""". This is a multiline string: @"""Triple quotes containing newlines will be preserved.""" This is a string using escapes: @ @'Welcome to \U0001d53c\U0001d55e\u2119\U0001d56a!'. ``````
_Output_: 🖥️
`````` This is a string: A single-quoted string. This is also a string: A double-quoted string. This is another string: A triple single-quoted string. This is yet another string: A triple double-quoted string. This is a multiline string: Triple quotes containing newlines will be preserved. This is a string using escapes: Welcome to 𝔼𝕞ℙ𝕪!. ``````
::: :::{versionadded} 3.1.1 String markup was introduced in EmPy version 3.1.1. ::: #### Backquote markup: `` @`...` `` **Backquote markup** (`` @`...` ``) can be used to escape any text, including EmPy markup. Multiple opening backquotes can be used as long as they are matched by an equal number in order to allow quoting text which itself has backquotes in it: :::{admonition} Example 16: Backquote _Source_: ⌨️
`````` This is literal text: @`some text`. This is a prefix: @`@`. This would be expanded if it were not backquoted: @`@(1 + 1)`. This would be an error if expanded: @`@(!@#$%^&*())`. This contains backquotes: @```here's one: ` and here's two: `` ```. ``````
_Output_: 🖥️
`````` This is literal text: some text. This is a prefix: @. This would be expanded if it were not backquoted: @(1 + 1). This would be an error if expanded: @(!@#$%^&*()). This contains backquotes: here's one: ` and here's two: `` . ``````
::: :::{warning} To use the backquote markup with content containing backquotes which are adjacent to the start or end markup, you need to pad it with spaces. So when quoting a single backquote, it needs to be written as ```@`` ` `` ```. This also means you cannot use backquote markup to specify a completely empty string. It must always contain at least one non-backquote character, e.g., `` @` ` ``. If you really need backquotes without whitespace padding, you can use a [hook](#hooks) to intercept the backquote markup and strip it out. ::: :::{attention} Note that when markup which has starting and ending delimiters appears alone on a line, the trailing newline will be rendered in the output. To avoid these extra newlines, use a trailing `@` to turn it into whitespace markup which consumes that trailing newline, so _e.g._ `` @`...` `` followed by a newline becomes `` @`...`@`` followed by a newline. This is idiomatic for suppressing unwanted newlines. See [here](#idiom) for more details. ::: :::{versionadded} 4.0 Backquote markup was introduced in EmPy version 4.0. ::: ### Escape markup: `@\...` **Escape markup** allows specifying individual non-printable characters with a special readable syntax: `@\...`. It is inspired by and extends the string literal escape codes from languages such as C/C++ and Python. :::{admonition} Example 17: Escapes _Source_: ⌨️
`````` @# These are all a Latin uppercase A: Binary: @\B{1000001} Quaternary: @\q1001, @\Q{1001} Octal: @\o101, @\O{101} Hexadecimal (variable bytes): @\X{41} Hexadecimal (one-byte): @\x41 Hexadecimal (two-byte): @\u0041 Hexadecimal (eight-byte): @\U00000041 By Unicode name: @\N{LATIN CAPITAL LETTER A} ``````
_Output_: 🖥️
`````` Binary: A Quaternary: A, A Octal: A, A Hexadecimal (variable bytes): A Hexadecimal (one-byte): A Hexadecimal (two-byte): A Hexadecimal (eight-byte): A By Unicode name: A ``````
::: The escape sequence type is indicated by the first character and then consumes zero or more characters afterward, depending on the escape sequence. Some sequence sequences support a variable number of characters, delimited by curly braces (`{...}`). :::{seealso} The list of all valid escape sequences is available in the `escapes` help topic and is summarized [here](HELP.md#escape-sequences-summary). ::: :::{versionadded} 1.5 Escape markup was introduced in EmPy version 1.5, and then reworked in EmPy version 4.0. ::: #### Named escape markup: `@\^{...}` The escape markup for controls `@\^...` has an extended usage where the character can be specified by a control code name. The resulting **named escape markup** takes the form of `@\^{...}` with the escape code name between the curly braces. The name of the escape code used in the markup is case insensitive. The mapping of escape names to characters is specified in the configuration variable `controls`. The keys of this dictionary must be in uppercase and the values can be integers (Unicode code point values), lists of integers, or strings. They can also take the form of a 2-tuple, where the first element is one of the above values and the second element is a description string used for displaying in help topics. :::{admonition} Example 18: Named escapes _Source_: ⌨️
`````` Normal space: [ ] Normal space by name: [@\^{SP}] No-break space: [@\^{NBSP}] Thin space: [@\^{THSP}] En space: [@\^{ENSP}] Em space: [@\^{EMSP}] (Well, these would look right if it this were in a proportional font.) ``````
_Output_: 🖥️
`````` Normal space: [ ] Normal space by name: [ ] No-break space: [ ] Thin space: [ ] En space: [ ] Em space: [ ] (Well, these would look right if it this were in a proportional font.) ``````
::: :::{note} The dictionary mapping all named escape codes to characters is stored in the `controls` configuration variable. This can be modified or completely replaced as desired. The values will be recoded to a native string and can be any of the following, in order: - a `str`, representing the string; - a `bytes`, which will be decoded into a string according to the output encoding; - an `int`, representing the Unicode code point value, which will be converted to a string via `chr`; - a callable object, which will be called and then converted; - any object with a `__str__` method, whose `str` value will be used; or a `list` of the above values, which will be converted as above and concatenated together. Additionally, they can take the form of a 2-tuple, where the first element is one of the above types and the second element is a description string, used for rendering the value in help topics. ::: :::{seealso} The list of all valid control code names is available in the `named` help topic and is summarized [here](HELP.md#named-escapes-control-codes-summary). ::: :::{versionadded} 4.0 Named escape markup was introduced in EmPy version 4.0. ::: ### Expression markup: `@(...)` EmPy mainly processes markups by evaluating expressions and executing statements. Expressions are bits of Python code that return a value; that value is then rendered into the output stream. Simple examples of Python expressions are `1 + 2`, `abs(-2)`, or `"test"*3`. In EmPy, expressions are evaluated and expanded with the **expression markup** `@(...)`. By default, an expression that evaluates to `None` does not print anything to the underlying output stream; this is equivalent to it having returned `''`. :::{tip} If you want to change this behavior, specify your preferred value with `--none-symbol` (_configuration variable:_ `noneSymbol`). ::: :::{admonition} Example 19: Expressions _Source_: ⌨️
`````` The sum of 1 and 2 is @(1 + 2). The square of 3 is @(3**2). The absolute value of -12 is @(abs(-12)). This prints "test" but does not print None: @(print("test", end='')). This, however, does: @(repr(None)). ``````
_Output_: 🖥️
`````` The sum of 1 and 2 is 3. The square of 3 is 9. The absolute value of -12 is 12. This prints "test" but does not print None: test. This, however, does: None. ``````
::: :::{attention} Note that when markup which has starting and ending delimiters appears alone on a line, the trailing newline will be rendered in the output. To avoid these extra newlines, use a trailing `@` to turn it into whitespace markup which consumes that trailing newline, so _e.g._ `` @(...) `` followed by a newline becomes `` @(...)@`` followed by a newline. This is idiomatic for suppressing unwanted newlines. See [here](#idiom) for more details. ::: :::{versionadded} 1.0 Expression markup was introduced in EmPy version 1.0. ::: ### Additional expression markup Several expression markup variants are available. #### Simple expression markup: `@x`, `@x.a`, `@x[i]`, `@x(args...)`, _etc._ Often expressions are "simple" and unambiguous enough that needing to use the full `@(...)` syntax is unnecessary. In cases where a single variable is being referenced unambiguously, the parentheses can be left off to create **simple expression markup**: :::{admonition} Example 20: Simple expressions, basic _Source_: ⌨️
`````` @# Set a variable to use. @{x = 16309}@ The value of x is @x. ``````
_Output_: 🖥️
`````` The value of x is 16309. ``````
::: `@x` is precisely the same thing as `@(x)`. This markup can be extended further. Attribute references (`@x.a`), indexing (`@x[i]`), and function calls (`@x(args...)`) can also be simplified in this way. They can also be chained together arbitrarily, so `@object.attribute.subattribute`, `@object.method(arguments...)`, `@object[index1][index2]`, `@object[index].attribute`, `@object[index].method(arguments...)`, etc. are all valid examples of simple expression markup. Function calls can even be chained in simple expression markup: `@factory(identifier)(arguments...)`. These simple expressions can be extended arbitrarily. :::{admonition} Example 21: Simple expressions, chaining _Source_: ⌨️
`````` @# Define some variables to use. @{ import time def mean(seq): # a function return sum(seq)/len(seq) class Person: # a class def __init__(self, name, birth, scores): self.name = name self.birth = birth self.scores = scores def age(self): current = time.localtime(time.time()).tm_year return current - self.birth person = Person("Fred", 1984, [80, 100, 70, 90]) # an instance of that class }@ The name of person is @(person.name), or more simply @person.name. The first letter is @(person.name[0]), or more simply @person.name[0]. He has @(len(person.scores)) scores, or more simply @len(person.scores). His first score is @(person.scores[0]), or more simply @person.scores[0]. His average score is @(mean(person.scores)), or more simply @mean(person.scores). His age is @(person.age()), or more simply @person.age(). ``````
_Output_: 🖥️
`````` The name of person is Fred, or more simply Fred. The first letter is F, or more simply F. He has 4 scores, or more simply 4. His first score is 80, or more simply 80. His average score is 85.0, or more simply 85.0. His age is 42, or more simply 42. ``````
::: :::{note} Final punctuation, including a period (`.`), is not interpreted as an attribute reference and thus does not result in a parse error. Thus you can use end-of-sentence punctuation naturally after a simple expression markup. ::: If you wish to concatenate an expression with immediately following text so that it will not be parsed incorrectly, either use whitespace markup or just fall back to a full expression markup: :::{admonition} Example 22: Simple expressions, concatenation _Source_: ⌨️
`````` @# Define a variable for use. @{thing = 'cat'}@ @# Referencing `@things` to pluralize `@thing` will not work. But: The plural of @thing is @thing@ s. Or: The plural of @thing is @(thing)s. ``````
_Output_: 🖥️
`````` The plural of cat is cats. Or: The plural of cat is cats. ``````
::: :::{versionadded} 1.0 Simple expression markup was introduced in EmPy version 1.0. ::: #### Functional expression markup: `@function{markup}{...}` Arguments to function calls in EmPy expression markups use Python expressions, not EmPy markup (_e.g._, `@f(x)` calls the function `f` with the variable `x`). To specify EmPy markup which is expanded and then passed in to the function, there is **functional expression markup** as an extension of simple expression markup. Since each argument to the function is expanded, the arguments are always strings: :::{admonition} Example 23: Functional expressions, one argument _Source_: ⌨️
`````` @{ def f(x): return '[' + x + ']' }@ @# Note that the argument is expanded before being passed to the function: This will be in brackets: @f{1 + 1 is @(1 + 1)}. ``````
_Output_: 🖥️
`````` This will be in brackets: [1 + 1 is 2]. ``````
::: Functional expressions support the application of multiple arguments by repeating the `{...}` suffix for as many arguments as is desired. Each argument is expanded one at a time in order, from left to right: :::{admonition} Example 24: Functional expressions, multiple arguments _Source_: ⌨️
`````` @{ def f(x, y, z): return x.lower() + ', ' + y.upper() + ', ' + z.capitalize() }@ @# Multiple arguments are possible by repeating the pattern: These expansions are separated by commas: @ @f{lowercase: @(1)}{uppercase: @(1 + 1)}{capitalized: @(1 + 1 + 1)}. ``````
_Output_: 🖥️
`````` These expansions are separated by commas: lowercase: 1, UPPERCASE: 2, Capitalized: 3. ``````
::: The opening and closing curly braces can be repeated an equal number of times to allow curly braces to be used within the markup: :::{admonition} Example 25: Functional expressions, repeated braces _Source_: ⌨️
`````` @{ def f(*args): return ''.join('[' + x + ']' for x in args) }@ @# Repeated matching curly braces allow internal curly braces to be used: This contains internal curly braces: @f{{There are {curly braces} inside}}. This contains more: @f{{{Even more {curly} {{braces}} here}}}. @# To have internal curly braces at the start or end, @# use escape markup or whitespace markup to separate them: Internal curly braces with whitespace: @f{{@ {braces}@ }}. Internal curly braces with escapes: @f{@\{braces@\}}. Internal curly braces with hexdecimal escapes: @f{@\x7bbraces@\x7d}. ``````
_Output_: 🖥️
`````` This contains internal curly braces: [There are {curly braces} inside]. This contains more: [Even more {curly} {{braces}} here]. Internal curly braces with whitespace: [{braces}]. Internal curly braces with escapes: [{braces}]. Internal curly braces with hexdecimal escapes: [{braces}]. ``````
::: :::{warning} Functional expression markup is an extension of simple expression markup so cannot be used in standard expression markup. Further, it cannot be seemlessly combined ("curried") with a normal function call. Thus, `@f(1){a}{b}` is equivalent to `@(f(1)('a', 'b'))`, not `@(f(1, 'a', 'b'))`. A functional argument calls will terminate simple expression parsing, so `@f{a}{b}(3)` is the same as `@(f('a', 'b'))(3)`, not `@f('a', 'b', 3)`; that is, trailing function calls are not applied. ::: :::{versionadded} 4.0 Functional expression markup was introduced in EmPy version 4.0. ::: #### Extended expression markup: `@(...?...!...$...)` Expression markup has an **extended expression markup** form which allows more powerful manipulation of expressions. ##### Conditional expression markup: `@(...?...!...)` The first form is **conditional expression markup** which allows for a compact form of an `@[if]` statement with a ternary operator, similar to C/C++'s `?` and `:` operators. In EmPy, however, these are represented with `?` and `!`, respectively. :::{note} C/C++'s use of `:` was changed to `!` for EmPy since `:` already has special meaning in Python. This syntax was originally added before Python supported the `if/else` ternary expression, although EmPy's syntax is more general and powerful. ::: If a `?` is present in the expression, then the Python (not EmPy) expression before the `?` is tested; if it is true, then the Python expression following it is evaluated. If a `!` is present afterward and the originally expression was false, then the Python expression following it is expanded (otherwise, nothing is). It thus acts as an if-then-else construct: :::{admonition} Example 26: Extended expressions, conditional _Source_: ⌨️
`````` Four is an @(4 % 2 == 0 ? 'even' ! 'odd') number. Five is @(5 % 2 == 0 ? 'also even' ! 'not'). Seven is an @(7 % 2 == 0 ? 'even' ! 'odd') number. And this is blank: @(False ? 'this will expand to nothing') @# Whitespace is not required: Eleven is an @(11 % 2 == 0?'even'!'odd') number. ``````
_Output_: 🖥️
`````` Four is an even number. Five is not. Seven is an odd number. And this is blank: Eleven is an odd number. ``````
::: ##### Chained conditional expression markup: `@(...?...!... ...)` These `?` and `!` sequences can be repeated indefinitely, forming an if-else-if-else chain called **chained conditional expression markup**, with a `!` expression serving as the conditional test for the next `?`: :::{admonition} Example 27: Extended expressions, chained conditional _Source_: ⌨️
`````` @# Define a variable for use. @{x = 3}@ x is @(x == 1 ? 'one' ! x == 2 ? 'two' ! x == 3 ? 'three' ! 'unknown'). ``````
_Output_: 🖥️
`````` x is three. ``````
::: ##### Except expression markup: `@(...$...)` Finally, a `$` present toward the end of expression markup, whether or not it includes an if-else chain, represents **except expression markup**: If the main expression throws an exception, suppress it and evaluate the Python (not EmPy) except expression instead. This can be combined with conditional or chained conditional expresion markup: :::{admonition} Example 28: Extended expressions, except _Source_: ⌨️
`````` No exception: 2 + 2 = @(2 + 2 $ 'oops'). Division by zero is @(1/0 $ 'illegal'). Two divided by zero is @(2/0 % 2 == 0 ? 'even' ! 'odd' $ 'also illegal'). ``````
_Output_: 🖥️
`````` No exception: 2 + 2 = 4. Division by zero is illegal. Two divided by zero is also illegal. ``````
::: :::{tip} Except expression markup will not capture `SyntaxError`s, since it is much more likely that this is a static error (_e.g._, a typographical error) rather than a dynamic error. This behavior can be modified by changing `fallThroughErrors` in the [configuration](#configuration). ::: :::{attention} Note that when markup which has starting and ending delimiters appears alone on a line, the trailing newline will be rendered in the output. To avoid these extra newlines, use a trailing `@` to turn it into whitespace markup which consumes that trailing newline, so _e.g._ `` @(...) `` followed by a newline becomes `` @(...)@`` followed by a newline. This is idiomatic for suppressing unwanted newlines. See [here](#idiom) for more details. ::: :::{versionadded} 1.3 Conditional expression markup was first introduced in EmPy version 1.3, updated to extended expressions (including exception handling) in EmPy version 1.4, and was expanded to support if-else chained conditional expressions in 4.0. ::: ### In-place expression markup: `@$...$...$` Occasionally it's desirable to designate an expression that will be evaluated alongside its evaluation which may change, but which will be re-evaluated with subsequent updates, in other words, explicitly identifying exactly what is being evaluated at the same time. This is similar to the notion of CVS or SVN keywords such as `$Date ...$`. For this, there is **in-place expression markup** (`@$...$...$`). They consist of two segments: first, the Python (not EmPy) expression to evaluate, and the second, the result of that evaluation. When evaluating the markup, the second (result) section is ignored and replaced with the evaluation of the first and a new in-place markup is rendered. For example: :::{admonition} Example 29: In-place expressions _Source_: ⌨️
`````` This could be a code comment indicating the version of EmPy: # @$empy.version$this text is replaced with the result$ Arbitrary Python expressions can be evaluated: # @$__import__('time').asctime()$$ ``````
_Output_: 🖥️
`````` This could be a code comment indicating the version of EmPy: # @$empy.version$4.2.1$ Arbitrary Python expressions can be evaluated: # @$__import__('time').asctime()$Sun Feb 8 16:45:25 2026$ ``````
::: :::{note} The `$` character is a common choice for an alternate prefix. If it is chosen instead of the default `@`, the in-place expression markup will be remapped to have the form `$@...@...@`; that is, the `@` and `$` are swapped. (This is done automatically for any prefix collision with a markup indicator.) ::: :::{attention} Note that when markup which has starting and ending delimiters appears alone on a line, the trailing newline will be rendered in the output. To avoid these extra newlines, use a trailing `@` to turn it into whitespace markup which consumes that trailing newline, so _e.g._ `` @$...$...$ `` followed by a newline becomes `` @$...$...$@`` followed by a newline. This is idiomatic for suppressing unwanted newlines. See [here](#idiom) for more details. ::: :::{versionadded} 1.4 In-place markup was introduced in EmPy version 1.4. ::: ### Statement markup: `@{...}` Again, EmPy mainly processes markups by evaluating expressions and executing statements. Statements include assignments, control structures (`if`, `for`, function and class definitions, etc.) Statements do not yield a value; they are used for side effects, whether that's changing the state of the interpreter (setting or changing variables, defining objects, calling functions, etc.) or printing output. Statements can also consist of expressions, so an expression (such as `print("Hello, world!")`) can be used solely for its side effects with the statement markup. **Statement markup** sets off a series of statements to be executed inside the `@{...}` markup. Since statements do not yield a value, they are executed but the markup itself does not implicitly write anything. Since the executed statements are Python, multiline statements must be formatted and indented according to Python's parsing rules: :::{admonition} Example 30: Statements _Source_: ⌨️
`````` @# Note the use of whitespace markup below to consume trailing newlines. @{x = 16309}@ x is now @x. @{ if x > 0: category = 'positive' else: category = 'non-positive' print("x is {}.".format(category)) }@ @{ # Since statement markup does not write anything itself, this # statement has no effect. x + 123 }@ ``````
_Output_: 🖥️
`````` x is now 16309. x is positive. ``````
::: :::{attention} Note that when markup which has starting and ending delimiters appears alone on a line, the trailing newline will be rendered in the output. To avoid these extra newlines, use a trailing `@` to turn it into whitespace markup which consumes that trailing newline, so _e.g._ `` @{...} `` followed by a newline becomes `` @{...}@`` followed by a newline. This is idiomatic for suppressing unwanted newlines. See [here](#idiom) for more details. ::: :::{versionadded} 1.0 Statement markup was introduced in EmPy version 1.0. ::: ### Control markups: `@[...]` EmPy supports a variety of control structures, analogous to the builtin Python control structures (`if`, `while`, `for`, etc.), with some additional markups for convenience. This is done with **control markup** indicated by `@[...]`. Since EmPy cannot rely on source indentation to delimit control structure syntax, all primary control markups must end with an explicit `end` markup (_e.g._, `@[if ...]...@[end if]`). The clauses surrounded by control markup are EmPy (Python) markup and are expanded according to the logic of each control markup; see below. Unlike the Python control structures, the code that is expanded within each subclause is EmPy code, not Python code. Thus, control markups can be nested arbitrarily (_e.g._, `@[while ...]@[for ...]@[if ...]...@[end if]@[end for]@[end while]`). ::::{attention} To use nested control markup that spans multiple lines and is more readable, you can rely on whitespace markup to consume the newline immediately following the control markup. As an example: :::{admonition} Example 31: Controls, idiom _Source_: ⌨️
`````` @# Note the user of whitespace markup to consume the trailing newlines. Counting: @[for i, x in enumerate(range(0, 5))]@ @x is @ @[ if x % 2 == 0]@ even@ @[ else]@ odd@ @[ end if]@ . @[end for]@ ``````
_Output_: 🖥️
`````` Counting: 0 is even. 1 is odd. 2 is even. 3 is odd. 4 is even. ``````
::: This method of writing organizing control markup with `@[...]@` all on a single line for clarity is idiomatic EmPy. (This applies to all markup with starting and ending delimiters.) See [here](#idiom) for more details. :::: :::{hint} Whitespace before the control keyword is ignored, so you can add whitespace inside the markup to simulate Python indentation for clarity, as the above example demonstrates. ::: :::{tip} Simple ("clean") control markup which does not contain arbitrary Python expressions -- `@[try]`, `@[else]`, `@[except ...]`, `@[finally]`, `@[continue]`, `@[break]` and `@[end ...]` -- can include a Python-style comment for clarity: :::{admonition} Example 32: Controls, clean _Source_: ⌨️
`````` @{ number = 42 test = 3%2 == 0 }@ @[if test]@ @number is even. @# Say there were many more lines here ... @[else # test]@ @number is not even. @# And also here ... @[end if # test]@ ``````
_Output_: 🖥️
`````` 42 is not even. ``````
::: ::: :::{versionadded} 3.0 Control markups were introduced in EmPy version 3.0 unless otherwise noted below. ::: #### If control markup: `@[if E]...@[end if]` The simplest control markup is the **if control markup**. It precisely mimics the Python `if` branching control structure. The test expressions are Python expressions. Like the native Python control structure, it takes on the following forms: - `@[if E]...@[end if]` - `@[if E]...@[else]...@[end if]` - `@[if E1]...@[elif E2]...@[end if]` - `@[if E1]...@[elif E2]...@[else]...@[end if]` - `@[if E1]...@[elif E2]...@[elif E3]...@[else]...@[end if]` - `@[if E1]...@[elif E2]...@[elif E3]... ... @[else]...@[end if]` where the _`E`s_ are Python expressions to be tested for truth. Thus, as with the builtin Python `if` control structure, zero or more `@[elif]` clauses can be used and the `@[else]` clause (only valid at the end of the chain) is optional. If there is no `@[else]` clause and all the test expressions are false, nothing will be expanded. :::{admonition} Example 33: If controls _Source_: ⌨️
`````` @{ def even(x): return x % 2 == 0 }@ 0 is @[if even(0)]even@[end if]. 1 is @[if even(1)]even@[else]odd@[end if]. 2 is @[if even(2)]even@[else]odd@[end if]. 3 is @[if even(3)]even@[elif not even(3)]not even@[end if]. 4 is @[if 0 == 1]wrong@[elif 1 == 2]wrong@[else]fine@[end if]. ``````
_Output_: 🖥️
`````` 0 is even. 1 is odd. 2 is even. 3 is not even. 4 is fine. ``````
::: #### Break and continue control markup: `@[break]`, `@[continue]` The looping control markup structures below (`@[for]`, `@[while]`, and `@[dowhile]`) all support **break** and **continue control markup**. These markups follow the native Python forms; `@[break]` will exit out of the innermost looping control structure, and `@[continue]` will restart the innermost looping control structure. They take the following forms: - `@[break]` - `@[continue]` What follows is a few examples using a `@[for]` loop: :::{admonition} Example 34: Continue controls _Source_: ⌨️
`````` @# Print even numbers. @[for n in range(10)]@ @[ if n % 2 != 0]@ @[ continue]@ @[ end if]@ @n is even. @[end for]@ ``````
_Output_: 🖥️
`````` 0 is even. 2 is even. 4 is even. 6 is even. 8 is even. ``````
::: :::{admonition} Example 35: Break controls _Source_: ⌨️
`````` @# Print numbers up to (but not including) 5. @[for n in range(10)]@ @[ if n >= 5]@ @[ break]@ @[ end if]@ @n is less than 5. @[end for]@ ``````
_Output_: 🖥️
`````` 0 is less than 5. 1 is less than 5. 2 is less than 5. 3 is less than 5. 4 is less than 5. ``````
::: #### For control markup: `@[for N in E]...@[end for]` A basic iteration markup is the **for control markup**. It precisely mimics the Python `for` looping control structure. The iterator expression is a Python expression. Like the native Python control structure, it takes on the following forms: - `@[for N in E]...@[end for]` - `@[for N in E]...@[else]...@[end for]` where _`N`_ is a Python identifier and _`E`_ is a Python expression which is iterable. As with the native Python control structure, an `@[else]` clause is supported; this is expanded if the loop exits without an intervening break. :::{admonition} Example 36: For controls _Source_: ⌨️
`````` @[for x in range(1, 6)]@ @x squared is @(x*x). @[else]@ ... and done. @[end for]@ ``````
_Output_: 🖥️
`````` 1 squared is 1. 2 squared is 4. 3 squared is 9. 4 squared is 16. 5 squared is 25. ... and done. ``````
::: #### While control markup: `@[while E]...@[end while]` The most general looping markup is the **while control markup**. It precisely mimics the Python `while` looping control structure. The test expression is a python expression. Like the native Python control structure, it takes on the following forms: - `@[while E]...@[end while]` - `@[while E]...@[else]...@[end while]` where _`E`_ is a Python expression to be tested for truth. As with the native Python control structure, an `@[else]` clause is supported; this is invoked if the loop exits without an intervening break. :::{admonition} Example 37: While controls _Source_: ⌨️
`````` @{a = 1}@ @[while a <= 5]@ @a pound signs: @('#'*a). @{a += 1}@ @[else]@ ... and done. @[end while]@ ``````
_Output_: 🖥️
`````` 1 pound signs: #. 2 pound signs: ##. 3 pound signs: ###. 4 pound signs: ####. 5 pound signs: #####. ... and done. ``````
::: #### Dowhile control markup: `@[dowhile E]...@[end dowhile]` An alternate `while` control structure is provided by EmPy: **dowhile control markup**. This differs from the standard `while` markup only in that the loop is always entered at least once; that is, the test expression is not checked before the first iteration. In this way, it is similar to the `do ... while` control structure from C/C++. It takes the following forms: - `@[dowhile E]...@[end dowhile]` - `@[dowhile E]...@[else]...@[end dowhile]` where _`E`_ is a Python expression to be tested for truth. Like the native Python `while` control structure, an `@[else]` clause is supported; this is invoked if the loop exits without an intervening break. :::{admonition} Example 38: Dowhile controls _Source_: ⌨️
`````` @# Stop when divisible by 5, but include 0 since it's the first iteration: @{n = 0}@ @[dowhile n % 5 != 0]@ @n works@[if n % 5 == 0] (even though it's divisible by 5)@[end if]. @{n += 1}@ @[else]@ ... and done. @[end dowhile]@ ``````
_Output_: 🖥️
`````` 0 works (even though it's divisible by 5). 1 works. 2 works. 3 works. 4 works. ... and done. ``````
::: :::{versionadded} 4.0 Dowhile control markup was introduced in EmPy version 4.0. ::: #### Try control markup: `@[try]...@[end try]` **Try control markup** is the EmPy equivalent of a `try` statement. As with the native Python statement, this markup can take on the widest variety of forms. They are: - `@[try]...@[except]...@[end try]` - `@[try]...@[except C]...@[end try]` - `@[try]...@[except C as N]...@[end try]` - `@[try]...@[except C, N]...@[end try]` - `@[try]...@[except (C1, C2, ...) as N]...@[end try]` - `@[try]...@[except C1]...@[except C2]...@[end try]` - `@[try]...@[except C1]...@[except C2]... ... @[end try]` - `@[try]...@[finally]...@[end try]` - `@[try]...@[except ...]...@[finally]...@[end try]` - `@[try]...@[except ...]...@[else]...@[end try]` - `@[try]...@[except ...]...@[else]...@[finally]...@[end try]` where the _`C`s_ are Python expressions to be treated as an exception class or tuple of classes and _`N`_ is a Python identifier. Its behavior mirrors in every way the native Python `try` statement. The try clause will be expanded, and if an exception is thrown, the first `@[except]` clause that matches the thrown exception (if there are any) will be expanded. If a `@[finally]` clause is present, that will be expanded after any possible exception handling, regardless of whether an exception was in fact thrown. Finally, if there is at least one `@[except]` clause, an `@[else]` may be present which will be expanded in the event that no exception is thrown (but before any `@[finally]` clause). The argument to the `@[except]` markup indicates which type(s) of exception should be handled and with what name, if any. No argument indicates that it will handle any exception. A simple expression will indicate an exception class, or a tuple of exception classes, that will be handled. The variable name of the thrown exception can be captured and passed to the expansion with the `as` keyword, or a comma (this latter notation is invalid in modern Python versions but is still supported in EmPy regardless of the underlying Python version). For example: :::{admonition} Example 39: Try controls _Source_: ⌨️
`````` Garbage is @[try]@hugalugah@[except NameError]not defined@[end try]. Division by zero is @[try]@(1/0)@[except ZeroDivisionError]illegal@[end try]. An index error is @[try]@([][3])@[except IndexError as e]@e.__class__.__name__@[end try]. And finally: @[try]@(nonexistent)@[except]oops, @[finally]something happened@[end try]. ``````
_Output_: 🖥️
`````` Garbage is not defined. Division by zero is illegal. An index error is IndexError. And finally: oops, something happened. ``````
::: :::{versionadded} 3.0 Try control markup was introduced in EmPy version 3.0, and was expanded in 4.0 to include all modern valid uses of `@[else]` and `@[finally]`. ::: #### With control markup: `@[with E as N]...@[end with]` EmPy supports a version of the `with` statement, which was introduced in Python 2.5. In EmPy, the **with control markup** is written as `@[with]` and mirrors the behavior of the native `with` statement. It takes the following forms: - `@[with E as N]...@[end with]` - `@[with N]...@[end with]` - `@[with E]...@[end with]` where _`E`_ is a Python expression which is iterable and _`N`_ is a Python identifier. All forms use context managers, just as with the native statement. Context managers are objects which have `__enter__` and `__exit__` methods, and the `@[with]` markup ensures that the former is called before the markup's contents are expanded and that the latter is always called afterward, whether or not an exception has been thrown. The three forms of the `@[with]` markup mirror the uses of the `with` keyword: The user can specify an expression and a variable name with the `as` keyword, or just a variable name, or just an expression (it will be entered and exited, but the name of the resulting object will not be available). For example: :::{admonition} Example 40: With controls _Source_: ⌨️
`````` @{ import os, sys # Create a test file to use with the @[with ...] markup. with open('/tmp/with.txt', 'w') as f: print("Hello, world!", file=f) }@ @[with open('/tmp/with.txt') as f]@f.read()@[end with]@ ``````
_Output_: 🖥️
`````` Hello, world! ``````
::: :::{note} Although the `with` keyword was only introduced in Python 2.5, the `@[with]` markup will work in any supported version of Python. ::: :::{versionadded} 4.0 With control markup was introduced in EmPy version 4.0. ::: #### Match control markup: `@[match E]@[case C]...@[end match]` Python 3.10 introduces structural pattern matching with the `match`/`case` control structure. The analog to this in EmPy is the **match control markup**. It takes the following forms: - `@[match E]@[case C1]...@[end match]` - `@[match E]@[case C1]...@[case C2]...@[end match]` - `@[match E]@[case C1]...@[case C2]...@[else]...@[end match]` where _`E`_ is a Python expression to be matched and the _`C`s_ are Python expressions to be tested as match cases. The control markup behaves the same as the native Python control structure: The first `@[case]` clause which matches is expanded and the control finishes. An optional `@[else]` clause can appear at the end of the chain of cases and will be expanded if no previous `@[case]` clause matches; `@[else]` is identical to `@[case _]`. Markup that is present between the `@[match]` markup and the first `@[case]` is unconditionally expanded. Typically this will be markup that expands to nothing, but it can involve a preamble if desired. :::{admonition} Example 41: Match controls _Source_: ⌨️
`````` @[for p in [(0, 0), (10, 0), (0, 10), (10, 10), (10, 20), (20, 10), 'oops']]@ @[ match p]@ @# Markup here is expanded unconditionally. @p is @ @[ case (0, 0)]@ the origin. @[ case (0, y)]@ y = @y. @[ case (x, 0)]@ x = @x. @[ case (x, y) if x == y]@ x = y = @x. @[ case (x, y)]@ x = @x, y = @y. @[ else]@ not a point. @[ end match]@ @[end for]@ ``````
_Output_: 🖥️
`````` (0, 0) is the origin. (10, 0) is x = 10. (0, 10) is y = 10. (10, 10) is x = y = 10. (10, 20) is x = 10, y = 20. (20, 10) is x = 20, y = 10. oops is not a point. ``````
::: :::{warning} Since the `@[match]` markup relies on the underlying Python functionality, using this markup with a version of Python before 3.10 will result in a `CompatibilityError` being raised. ::: :::{versionadded} 4.1 Match control markup was introduced in EmPy version 4.1. ::: #### Defined control markup: `@[defined N]...@[end defined]` Sometimes it's useful to know whether a name is defined in either the locals or globals dictionaries. EmPy provides a dedicated markup for this purpose: **defined control markup**. It takes the following forms: - `@[defined N]...@[end defined]` - `@[defined N]...@[else]...@[end defined]` where _`N`_ is a Python identifier. When provided a name, it will expand the contained markup if that name is defined in either the locals or globals. `@[defined NAME]...@[end defined]` is equivalent to `@[if 'NAME' in globals() or 'NAME' in locals()]...@[end if]`. An `@[else]` clause is also supported; if present, this will be expanded if the name does _not_ appear in the locals or globals. If no `@[else]` clause is present and the name is not defined, nothing will be expanded. :::{admonition} Example 42: Defined controls _Source_: ⌨️
`````` @{cat = 'Boots'}@ Cat is @[defined cat]@cat@[else]not defined@[end defined]. Dog is @[defined dog]@dog@[else]not defined@[end defined]. ``````
_Output_: 🖥️
`````` Cat is Boots. Dog is not defined. ``````
::: :::{versionadded} 4.0 Defined control markup was introduced in EmPy version 4.0. ::: #### Def control markup: `@[def F(...)]...@[end def]` EmPy supports defining functions which expand EmPy code, not Python code as with the standard `def` Python statement. This is called **def control markup**. It takes on the following form: - `@[def F(...)]...@[end def]` where _`F(...)`_ is a Python function signature. Def control markup involves specifying the signature of the resulting function (such as with the standard Python `def` statement) and encloses the EmPy code that the function should expand. It is then defined in the interpreter's globals/locals and can be called like any other Python function. It is best demonstrated with a simple example: :::{admonition} Example 43: Def controls _Source_: ⌨️
`````` @# Define an EmPy-native function. @[def element(name, symbol, atomicNumber, group)]@ Element @name (symbol @symbol, atomic number @atomicNumber) is a @group@ @[end def]@ @# Now use it. @element('hydrogen', 'H', 1, 'reactive nonmetal'). @element('helium', 'He', 2, 'noble gas'). @element('lithium', 'Li', 3, 'alkali metal'). @element('beryllium', 'Be', 4, 'alkaline earth metal'). @element('boron', 'B', 5, 'metalloid'). @element('carbon', 'C', 6, 'reactive nonmetal'). ``````
_Output_: 🖥️
`````` Element hydrogen (symbol H, atomic number 1) is a reactive nonmetal. Element helium (symbol He, atomic number 2) is a noble gas. Element lithium (symbol Li, atomic number 3) is a alkali metal. Element beryllium (symbol Be, atomic number 4) is a alkaline earth metal. Element boron (symbol B, atomic number 5) is a metalloid. Element carbon (symbol C, atomic number 6) is a reactive nonmetal. ``````
::: :::{hint} The markup `@[def FUNC(...)]DEFN@[end def]` is equivalent to the following Python code: ```python def FUNC(...): r"""DEFN""" return empy.expand(r"""DEFN""", locals()) ``` It simply defines a Python function with the provided signature, a docstring indicating its EmPy definition, and the function calls the `expand` method on the pseudomodule/interpreter with the definition and returns the results. ::: Any valid Python function notation is allowed, including type hints; note, though, that the return value of the defined function is an expansion and thus should always be `str`: :::{admonition} Example 44: Def controls: type hints _Source_: ⌨️
`````` @{ DIGITS = [ 'zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'niner', ] }@ @[def words(number: int) -> str]@ @(' '.join(DIGITS[int(x)] for x in str(number)))@ @[end def]@ 16309 in words is @words(16309). ``````
_Output_: 🖥️
`````` 16309 in words is one six three zero niner. ``````
::: :::{tip} Functions defined with def control markup are callable Python objects like any other. They can be called through any mechanism, whether Python (`f(...)`), through EmPy markup (`@f(...)`), or even via [functional expression markup](#functional-expression-markup) (`@f{...}`). ::: ### Diacritic markup: `@^ CHAR DIACRITIC(S)` EmPy provides a quick and convenient way to combine diacritics (accents) to characters with **diacritic markup**. Diacritic markup consists of the prefix `@^`, followed by the base character, and then either a single character representing the accent to apply or a sequence of such characters enclosed in curly braces (`{...}`). The first character is the base character to combine diacritics with, and the remaining characters (possibly more than one if the curly braces form is used) are diacritic codes corresponding to Unicode combining characters that can be combined (or just appended) to the base character. These combining diacritics are simpler, more easily entered characters that (at least in some cases) resemble the actual desired combining character. For instance, `'` (apostrophe) represents the acute accent ◌́; `` ` `` (backquote) represents the grave accent ◌̀; `^` represents the circumflex accent ◌̂, and so on: :::{admonition} Example 45: Diacritics _Source_: ⌨️
`````` French: Voil@^a`, c'est ici que @^c,a s'arr@^e^te. Spanish: Necesito ir al ba@^n~o ahora mismo. Portuguese: Informa@^c,@^a~o @^e' poder. Swedish: Hur m@^aonga kockar kr@^a:vs f@^o:r att koka vatten? Vietnamese: Ph@^o{h?} b@^o` vi@^e^n ngon qu@^a'! Esperanto: E@^h^o@^s^an@^g^e @^c^iu@^j^a@^u(de! Shakespearean: All are punish@^e`d. ``````
_Output_: 🖥️
`````` French: Voilà, c'est ici que ça s'arrête. Spanish: Necesito ir al baño ahora mismo. Portuguese: Informação é poder. Swedish: Hur många kockar krävs för att koka vatten? Vietnamese: Phở bò viên ngon quá! Esperanto: Eĥoŝanĝe ĉiuĵaŭde! Shakespearean: All are punishèd. ``````
::: :::{tip} Curly braces can enclose zero or more characters representing diacritics. If they enclose zero, the diacritic markup has no effect (`@^e{}` is no different from `e`). If they enclose one, the results are no different from not using curly braces (`@^e{'}` and `@^e'` are have identical results). Only when applying more than one diacritic are curly braces required. ::: By default, the base character and diacritics will be combined with NFKC normalization -- this will, when possible, replace the base character and its combiners with a single Unicode character representing the combination, if one exists. Normalization is not required (and may sometimes fail when a suitable combined form does not exist); in these cases, your system's Unicode renderer will cope as best it can. To change the normalization type, use `-z/--normalization-form=F` (_configuration variable:_ `normalizationForm`). To disable normalization, set it to the empty string. :::{note} The dictionary mapping all diacritic codes to combining characters is stored in the `diacritics` configuration variable. This can be modified or completely replaced as desired. The values will be recoded to a native string and can be any of the following, in order: - a `str`, representing the string; - a `bytes`, which will be decoded into a string according to the output encoding; - an `int`, representing the Unicode code point value, which will be converted to a string via `chr`; - a callable object, which will be called and then converted; - any object with a `__str__` method, whose `str` value will be used; or a `list` of the above values, which will be converted as above and concatenated together. Additionally, they can take the form of a 2-tuple, where the first element is one of the above types and the second element is a description string, used for rendering the value in help topics. ::: :::{seealso} The list of all default diacritic codes is available in the `diacritics` help topic and is summarized [here](HELP.md#diacritic-combiners-summary). ::: :::{versionadded} 4.0 Diacritic markup was introduced in EmPy version 4.0. ::: ### Icon markup: `@|...` A customizable brief way to map "icon" keys -- short, user-specified strings -- to arbitrary Unicode strings exists in the form of **icon markup**. Icon markup is set off with `@|...` and then followed by an unambiguous, arbitrary-length sequence of characters (Unicode code points) corresponding to one of its keys. Keys can be arbitrary length and can consist of whatever characters are desired (including letters, numbers, punctuation, or even Unicode characters). They are not delimited by whitespace; however, they must be unambiguous, so if more than one key exists with the same prefixes (say, `@|#+` and `@|#-`), a key cannot be assigned the common prefix (`@|#`) as this would be found first and would hide the longer prefixes. Such a common prefix key should be set to the value `None` (which indicates to the parser that the icon is potentially valid but not yet complete). This validation is done automatically when the icon markup is first used: The dictionary of icons is traversed and any common prefixes not defined in the dictionary are set to `None`. In the event that this auto-validation may be expensive and the user wishes to do it manually to avoid this step, specify the `--no-auto-validate-icons` command line option (`autoValidateIcons` configuration variable) to disable it. :::{admonition} Example 46: Icons _Source_: ⌨️
`````` These are @|"(curly quotes.@|") This is a royal flush: A@|%s K@|%s Q@|%s J@|%s T@|%s. This is a check mark @|/ and this is an X mark @|\. Smile! @|:) Laugh! @|:9 Cry! @|:5 Sleep! @|:Z ``````
_Output_: 🖥️
`````` These are “curly quotes.” This is a royal flush: A♠️ K♠️ Q♠️ J♠️ T♠️. This is a check mark ✔️ and this is an X mark ❌️. Smile! 😀 Laugh! 🤣 Cry! 🥲 Sleep! 😴 ``````
::: To customize icons, modify or replace the `icons` configuration variable: :::{admonition} Example 47: Icons, customization _Source_: ⌨️
`````` @# Replace the icons with just a few very serious ones. @{ empy.config.icons = { 'kitty': '\U0001f431', 'cat': '\U0001f408', } }@ Counting: one two @|kitty @|cat five. ``````
_Output_: 🖥️
`````` Counting: one two 🐱 🐈 five. ``````
::: :::{note} The dictionary mapping all icon keys to their substitutes is stored in the `icons` configuration variable. This can be modified or completely replaced as desired. The values will be recoded to a native string and can be any of the following, in order: - a `str`, representing the string; - a `bytes`, which will be decoded into a string according to the output encoding; - an `int`, representing the Unicode code point value, which will be converted to a string via `chr`; - a callable object, which will be called and then converted; - any object with a `__str__` method, whose `str` value will be used; or a `list` of the above values, which will be converted as above and concatenated together. Additionally, they can take the form of a 2-tuple, where the first element is one of the above types and the second element is a description string, used for rendering the value in help topics. ::: :::{tip} If you're finding problems with icons being ambiguous, you can add delimiters at the end of the icon key to ensure that they are unambiguous. For example, the icons `@|!`, `@|!!` and `@|!?` would normally be ambiguous. However, wrapping them in, say, curly braces, will remove the ambiguity: `@|{!}`, `@|{!!}`, `@|{!?}` are unambiguous and can be used as icon keys. ::: :::{seealso} The list of all valid icon keys is available in the `icons` help topic and is summarized [here](HELP.md#icons-summary). ::: :::{warning} The default set of icons were chosen by the author for his convenience and to demonstrate what icon markup can do. It is expected that users using icon markup will modify (or more likely completely replace) the icons dictionary to their liking. Thus the default icons are subject to change. ::: :::{versionadded} 4.0 Icon markup was introduced in EmPy version 4.0. ::: ### Emoji markup: `@:...:` A dedicated **emoji markup** is available to translate Unicode emoji names, and Unicode names more generally, into Unicode glyphs. Using the markup is simple: Use the `@:...:` syntax and put the name of the emoji character between the colons. Since EmPy is often used in wrapped text, any newlines in the emoji name will be replaced with spaces. By default it uses the builtin `unicodedata.lookup` function call which allow the lookup of any Unicode code point by name, not just emoji. Whether names are case sensitive or not, or whether words are separated by spaces or underscores or either, is module-dependent. The builtin `unicodedata` module (the fallback if no emoji-specific modules are installed) is case insensitive and requires spaces, not underscores: :::{admonition} Example 48: Emojis _Source_: ⌨️
`````` Latin capital letter A: @:LATIN CAPITAL LETTER A: Latin small letter O with diaeresis: @:latin small letter o with diaeresis: White heavy check mark: @:WHITE HEAVY CHECK MARK: Volcano: @:VOLCANO: ``````
_Output_: 🖥️
`````` Latin capital letter A: A Latin small letter O with diaeresis: ö White heavy check mark: ✅ Volcano: 🌋 ``````
::: User-specified emojis can also be assigned to the `emojis` configuration variable; these will be checked before any emoji modules are queried. Emojis in the `emojis` dictionary are case sensitive: :::{admonition} Example 49: Emojis, custom _Source_: ⌨️
`````` @# What's with this guy and cats? @{ empy.config.emojis['kittycat'] = '\U0001f408' }@ This is a kitty cat: @:kittycat: ``````
_Output_: 🖥️
`````` This is a kitty cat: 🐈 ``````
::: :::{note} The dictionary mapping all emoji keys to their substitutes is stored in the `emojis` configuration variable. This can be added to or completely replaced as desired. The values will be recoded to a native string and can be any of the following, in order: - a `str`, representing the string; - a `bytes`, which will be decoded into a string according to the output encoding; - an `int`, representing the Unicode code point value, which will be converted to a string via `chr`; - a callable object, which will be called and then converted; - any object with a `__str__` method, whose `str` value will be used; or a `list` of the above values, which will be converted as above and concatenated together. Additionally, they can take the form of a 2-tuple, where the first element is one of the above types and the second element is a description string, used for rendering the value in help topics. ::: #### Third-party emoji modules The emoji markup can also use third-party emoji modules if they are present. These can be installed in the usual way with PyPI (_e.g._, `python3 -m pip install emoji`) or any other preferred method. The following emoji modules are supported: {#third-party-emoji-modules-table} | Module | Function | Parameter | Capitalization | Word delimiters | | --- | --- | --- | --- | --- | | [`emoji`](https://pypi.org/project/emoji/) | `emojize` | `':%s:'` | lowercase | underscores | [`emojis`](https://pypi.org/project/emojis/) | `encode` | `':%s:'` | lowercase | underscores | [`emoji_data_python`](https://pypi.org/project/emoji_data_python/) | `replace_colons` | `':%s:'` | lowercase | underscores | `unicodedata` (standard) | `lookup` | `'%s'` | both | spaces On first usage, each module is checked to see if it is present and is then registered in the order listed above. When a lookup on a name is performed, each module which is present is queried in order, and if it finds the given name, that is used as output. If no modules find the name, by default an error is generated, but this behavior can be changed with the `--ignore-emoji-not-found` command line option. The order in which modules are queried is also customizable with the `--emoji-modules` command line option; specify the sequence of emoji module names to test separated by commas. Use the `--no-emoji-modules` command line option to only enable the builtin `unicodedata` module lookup, deactivating the use of any custom modules which may be installed. And use `--disable-emoji-modules` to disable all emoji module lookup; only the `emojis` configuration variable will be consulted. In summary, after install the third-party emoji module you prefer -- or rely on the default standard module, `unicodedata` -- and using the emoji markup will "just work." If you're aware of other third-party emoji modules you'd like to see supported, [contact the author](#contact). :::{tip} It's expected that the typical EmPy user will have at most one third-party module installed, so no effort has been put in place to avoid conflicts or redundancies regarding emoji names between them other than specifying the desired lookup order. Choose a third-party module that works for you, or just rely on the builtin `unicodedata` lookup table. If you're relying on a third-party module to be present, you might want to have your EmPy code explicitly import that module so that if it's missing, the dependency will be called out prominently. ::: :::{attention} Note that when markup which has starting and ending delimiters appears alone on a line, the trailing newline will be rendered in the output. To avoid these extra newlines, use a trailing `@` to turn it into whitespace markup which consumes that trailing newline, so _e.g._ `` @:...: `` followed by a newline becomes `` @:...:@`` followed by a newline. This is idiomatic for suppressing unwanted newlines. See [here](#idiom) for more details. ::: :::{versionadded} 4.0 Emoji markup was introduced in EmPy version 4.0. ::: ### Significator markup: `@%[!]... NL`, `@%%[!]...%% NL` **Significator markup** is a way to perform distinctive assignments within an EmPy system which are easily parsed externally; for instance, for specifying metadata for an EmPy source document; these assignments are called **significators**. In its simplest form, it defines in a variable in the globals with the evaluation of a Python value. The significator `@%KEY VALUE` is equivalent to the Python assignment statement `__KEY__ = VALUE`. The name of the assigned variable is preceded and ended with a double underscore (`__`). (This behavior can be changed with configurations.) Note that the value assigned can be any Python expression, not just a string literal: :::{admonition} Example 50: Significators, basics _Source_: ⌨️
`````` @%title "A Tale of Two Cities" @%author 'Charles Dickens' @%year 1859 @%version '.'.join([str(x) for x in __import__('sys').version_info[0:2]]) The book is _@(__title__)_ (@__year__) by @__author__. This version of Python is @__version__. ``````
_Output_: 🖥️
`````` The book is _A Tale of Two Cities_ (1859) by Charles Dickens. This version of Python is 3.10. ``````
::: Whitespace is allowed between the `@%` markup introducer and the key, and any (non-newline) whitespace is allowed between the key and the value. The ending newline is always consumed. A variant of significator markup can span multiple lines. Instead of using `@%` and a newline to delimit the significator, use `@%%` and `%%` followed by a newline: :::{admonition} Example 51: Significators, multiline _Source_: ⌨️
`````` @%%longName "This is a potentially very long \ name which can span multiple lines." %% @%%longerName """This is a triple quoted string which itself contains newlines. Note the newlines are preserved.""" %% @%%longExpression [[1, 2, 3], [4, 5, 6], [7, 8, 9]] %% Long name: @__longName__ Longer name: @__longerName__ Long expression: @__longExpression__ ``````
_Output_: 🖥️
`````` Long name: This is a potentially very long name which can span multiple lines. Longer name: This is a triple quoted string which itself contains newlines. Note the newlines are preserved. Long expression: [[1, 2, 3], [4, 5, 6], [7, 8, 9]] ``````
::: ::::{note} When using multiline significators, the value must still be a valid Python expression. So the significator `````` @%%bad 1 + 2 + 3 + 4 + 5 + 6 %% `````` is a syntax error due to the intervening newline. To correct this, use a backslash character (`\`) to escape the newline or enclose the value expression in parentheses: `````` @%%good1 1 + 2 + 3 + \ 4 + 5 + 6 %% @%%good2 (1 + 2 + 3 + 4 + 5 + 6) %% `````` :::: Two more subvariants of significator markup exists, one for each of these two variants. Frequently significator values will just be string literals and for uniformity users may wish to not deal with full Python expressions. For these purposes, significator values can be **stringized**, or treated merely as strings with no Python evaluation. Simply insert a `!` after the `@%` or `@%%` markup introducer and before the name of the key: :::{admonition} Example 52: Significators, stringized _Source_: ⌨️
`````` @# These values are all implicit strings. @%!single This is on a single line. @%%!multi This is on multiple lines. %% Single line: @__single__ Multiple lines: @__multi__ ``````
_Output_: 🖥️
`````` Single line: This is on a single line. Multiple lines: This is on multiple lines. ``````
::: Finally, the values for both single and multiline significator markups are optional. If the markup is not stringized, the value will be `None`; if stringized, it will be the empty string (`''`): :::{admonition} Example 53: Significators, optional values _Source_: ⌨️
`````` @%none @%!empty This is a None: @repr(__none__). This is an empty string: @repr(__empty__). ``````
_Output_: 🖥️
`````` This is a None: None. This is an empty string: ''. ``````
::: :::{hint} Significators can appear anywhere in an EmPy document, but typically are used at the beginning. ::: :::{tip} A compiled regular expression object is returned by the `significatorRe` configuration method and can be used to systematically find all the significators in a given text. The values of a non-stringinized significators can be any Python expression, so can include side effects from prior EmPy expansions. It's best practice, however, to only have significator values depend on the value of previous significators, so that trimmed down processors can evaluate them without having to expand the entire document. ::: :::{versionadded} 1.2 Significator markup was introduced in EmPy version 1.2. Stringified and multiline variants were introduced in version 4.0. ::: ### Context markups Contexts are objects which track the current progress of an EmPy interpreter through its source document(s) for the purposes of error reporting. This is handled automatically by the EmPy system, but they can be modified through the API or with context markup. :::{versionadded} 3.0.2 Context markups were introduced in EmPy version 3.0.2. ::: #### Context name markup: `@?... NL` The **context name markup** can be used to change the current context name with `@?... NL`; it uses as the new name what follows on the same line and consumes everything up to and including the newline. Whitespace surrounding the context name is ignored. :::{admonition} Example 54: Context names _Source_: ⌨️
`````` @?Test This context is now: @empy.getContext(). ``````
_Output_: 🖥️
`````` This context is now: Test:2:22. ``````
::: #### Context line markup: `@!... NL` The **context line markup** can be used to change the current context line with `@!... NL`; it uses as the new line what follows on the same line and consumes everything up to and including the newline. Whitespace surrounding the context name is ignored. If the remaining text is not parseable as an integer, it is a parse error. :::{admonition} Example 55: Context lines _Source_: ⌨️
`````` @!1000 This context is now: @empy.getContext(). Note that the line is 1001 since it's the next line after the markup. ``````
_Output_: 🖥️
`````` This context is now: :1001:22. Note that the line is 1001 since it's the next line after the markup. ``````
::: ### Extension markup: `@((...))`, `@[[...]]`, `@{{...}}`, `@<...>`, ... Markup can be provided with customizable user-defined meanings with **extension markup**. Use of these markups calls a method on an extension instance installed with the running interpreter, and serializes its return result. Once installed, an extension cannot be uninstalled (but you can dynamically change its behavior). Each of these methods has the following signature: > `method(contents: str, depth: int, locals: Optional[dict]) -> str` It takes the following arguments: {#extension-arguments-table} | Argument | Type | Description | | --- | --- | --- | | `contents` | `str` | The contents inside the markup | | `depth` | `int` | The number of opening and closing markup characters | | `locals` | `Optional[dict]` | The locals dictionary or `None` | The return value is a string to serialize to the output. Of course, these methods can perform any other desired side effects. Encountering extension markup with no installed extension, or with an extension that has no correspondingly defined method is an error. The following extension markups are available out of the box: {#extension-markups-table} | Markup | Start | Extension method name | Minimum depth | | --- | --- | --- | --- | | `@((...))` | `((` | `parentheses` | 2 | | `@[[...]]` | `[[` | `square_brackets` | 2 | | `@{{...}}` | `{{` | `curly_braces` | 2 | | `@<...>` | `<` | `angle_brackets` | 1 | Extension markup is parsed so that the number of starting and ending characters can be of any depth but the number of starting and ending characters must match. For angle brackets extension markup, any depth can be used. For the others, a depth of 2 or more is needed (since only one character, _e.g._, `@(...)`, is a different markup). For additional user-specified markups, it is up to the user. :::{admonition} Example 56: Extensions _Source_: ⌨️
`````` @{ import em class Extension(em.Extension): def parentheses(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('parentheses', contents, depth) def square_brackets(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('square_brackets', contents, depth) def curly_braces(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('curly_braces', contents, depth) def angle_brackets(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('angle_brackets', contents, depth) empy.installExtension(Extension()) }@ Parentheses: @((This is a test.)) Parentheses: @(((This is a test.))) Parentheses: @((((This is a test.)))) Square brackets: @[[This is a test.]] Square brackets: @[[[This is a test.]]] Square brackets: @[[[[This is a test.]]]] Curly braces: @{{This is a test.}} Curly braces: @{{{This is a test.}}} Curly braces: @{{{{This is a test.}}}} Angle brackets: @ Angle brackets: @<> Angle brackets: @<<>> Angle brackets: @<<<>>> ``````
_Output_: 🖥️
`````` Parentheses: [parentheses] "This is a test." (depth 2) Parentheses: [parentheses] "This is a test." (depth 3) Parentheses: [parentheses] "This is a test." (depth 4) Square brackets: [square_brackets] "This is a test." (depth 2) Square brackets: [square_brackets] "This is a test." (depth 3) Square brackets: [square_brackets] "This is a test." (depth 4) Curly braces: [curly_braces] "This is a test." (depth 2) Curly braces: [curly_braces] "This is a test." (depth 3) Curly braces: [curly_braces] "This is a test." (depth 4) Angle brackets: [angle_brackets] "This is a test." (depth 1) Angle brackets: [angle_brackets] "This is a test." (depth 2) Angle brackets: [angle_brackets] "This is a test." (depth 3) Angle brackets: [angle_brackets] "This is a test." (depth 4) ``````
::: Extensions can be used to define entirely new markup in this way. The first optional argument to the `Extension` constructor is a dict or list or 2-tuples mapping first characters to method names. If it is a list, it will be added to the default mapping: :::{admonition} Example 57: Extensions, additions _Source_: ⌨️
`````` @{ import em class Extension(em.Extension): def __init__(self): super().__init__([('/', 'slashes')]) def parentheses(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('parentheses', contents, depth) def square_brackets(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('square_brackets', contents, depth) def curly_braces(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('curly_braces', contents, depth) def angle_brackets(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('angle_brackets', contents, depth) def slashes(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('slashes', contents, depth) empy.installExtension(Extension()) }@ Parentheses: @((This is a test.)) Square brackets: @[[This is a test.]] Curly braces: @{{This is a test.}} Angle brackets: @ Slashes: @/This is a test./ Slashes: @//This is a test.// Slashes: @///This is a test./// Slashes: @////This is a test.//// ``````
_Output_: 🖥️
`````` Parentheses: [parentheses] "This is a test." (depth 2) Square brackets: [square_brackets] "This is a test." (depth 2) Curly braces: [curly_braces] "This is a test." (depth 2) Angle brackets: [angle_brackets] "This is a test." (depth 1) Slashes: [slashes] "This is a test." (depth 1) Slashes: [slashes] "This is a test." (depth 2) Slashes: [slashes] "This is a test." (depth 3) Slashes: [slashes] "This is a test." (depth 4) ``````
::: :::{warning} If the opening and closing characters are the same, the markup must contain at least one other character in order to be recognized. For instance, if an extension is added for `@/.../`, the character sequence `@//` is not an extension markup with a depth of one containing the empty string; it is the unfinished start of an extension markup of at least depth two. `@/ /`, with a space in between, on the other hand, would be valid. ::: The first constructor argument can also be a dict, in which case the mapping is completely replaced: :::{admonition} Example 58: Extensions, replacement _Source_: ⌨️
`````` @{ import em class Extension(em.Extension): def __init__(self): super().__init__({ '((': 'parens', '[[': 'brackets', '{{': 'braces', '<': 'angles', '/': 'slashes', }) def parens(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('parens', contents, depth) def brackets(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('brackets', contents, depth) def braces(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('braces', contents, depth) def angles(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('angles', contents, depth) def slashes(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('slashes', contents, depth) empy.installExtension(Extension()) }@ Parentheses: @((This is a test.)) Square brackets: @[[This is a test.]] Curly braces: @[[This is a test.]] Angle brackets: @ Slashes: @/This is a test./ ``````
_Output_: 🖥️
`````` Parentheses: [parens] "This is a test." (depth 2) Square brackets: [brackets] "This is a test." (depth 2) Curly braces: [brackets] "This is a test." (depth 2) Angle brackets: [angles] "This is a test." (depth 1) Slashes: [slashes] "This is a test." (depth 1) ``````
::: Note that the markup opening can either be one character or two. This is so that some extension markup can exist alongside of existing markup (_e.g._, `@((...))` is extension markup whereas `@(...)` is expression markup). Finally, you can manually install token class factories corresponding to your extension: :::{admonition} Example 59: Extensions, manual _Source_: ⌨️
`````` @{ import em class Extension(em.Extension): def __init__(self): super().__init__({}) def the_colons(self, contents, depth, locals): return '[{}] "{}" (depth {})'.format('the_colons', contents, depth) empy.installExtension(Extension()) factory = empy.config.getFactory() factory.addToken(empy.config.createExtensionToken(';', 'the_colons', ':')) }@ The colons: @;This is a test.: ``````
_Output_: 🖥️
`````` The colons: [the_colons] "This is a test." (depth 1) ``````
::: :::{attention} Note that when markup which has starting and ending delimiters appears alone on a line, the trailing newline will be rendered in the output. To avoid these extra newlines, use a trailing `@` to turn it into whitespace markup which consumes that trailing newline, so _e.g._ `` @<...> `` followed by a newline becomes `` @<...>@`` followed by a newline. This is idiomatic for suppressing unwanted newlines. See [here](#idiom) for more details. ::: :::{versionadded} 4.1 Extension markup was introduced in EmPy version 4.1. ::: ## Features Various additional features are available in a running EmPy system. The following subsections list the various features available in the EmPy system and in which version they were introduced. {#features-table} | Feature | Description | Ver. | | --- | --- | --- | | [Pseudomodule](#pseudomodule-interpreter) | The pseudomodule/interpreter available in an EmPy system | 1.0 | | [Commands](#commands) | Preprocessing and postprocessing commands | 1._x_ | | [Plugins](#plugins) | Plugins for the interpreter | 4.1 | | [Cores](#cores) | Alternatives for the underlying language interpreter | 4.1 | | [Extensions](#extensions) | Specify user-customizable markup | 4.1 | | [Callbacks](#callbacks) | Specify user-customizable markup for `@<...>` [deprecated] | 3.3 | | [Finalizers](#finalizers) | Functions to be called on interpreter shutdown | 2.1 | | [Diversions](#diversions) | Defer and playing back output | 1.0 | | [Filters](#filters) | Filter output | 1.3 | | [Modules](#modules) | Import native EmPy modules | 4.2 | | [Hooks](#hooks) | Inspect and modify interpreter behavior | 2.0---4.0 | ### Pseudomodule/interpreter The pseudomodule/interpreter can be accessed by a running EmPy system by referencing its name (which defaults to `empy`) in the globals: :::{admonition} Example 2: Pseudomodule sample _Source_: ⌨️
`````` This version of EmPy is @empy.version. The prefix in this interpreter is @empy.getPrefix() @ and the pseudomodule name is @empy.config.pseudomoduleName. Do an explicit write: @empy.write("Hello, world!"). The context is currently @empy.getContext(). Adding a new global in a weird way: @ @empy.updateGlobals({'q': 789})@ Now q is @q! You can do explicit expansions: @empy.expand("1 + 1 = @(1 + 1)"). q is @(empy.defined('q') ? 'defined' ! 'undefined'). ``````
_Output_: 🖥️
`````` This version of EmPy is 4.2.1. The prefix in this interpreter is @ and the pseudomodule name is empy. Do an explicit write: Hello, world!. The context is currently :5:26. Adding a new global in a weird way: Now q is 789! You can do explicit expansions: 1 + 1 = 2. q is defined. ``````
::: :::{important} The pseudomodule and interpreter are one and the same object; the terms _pseudomodule_ and _interpreter_ are used interchangeably. The interpreter exposes itself as the pseudomodule `empy` in a running EmPy system; this pseudomodule is never imported explicitly. ::: :::{versionadded} 1.0 The pseudomodule was introduced in EmPy version 1.0. ::: #### Interpreter attributes and methods ##### Interpreter attributes The following attributes are set on the pseudomodule after it is initialized. `version: str` : The version of EmPy. `compat: list[str]` : A list of strings indicating the "compatibility features" that were automatically enabled to support or call out earlier versions of Python. Possible strings are: {#compatibility-features-table} | Feature | Description | Affected versions | | --- | --- | --- | | `BaseException` | `BaseException` class does not exist | before 2.5 | | `FileNotFoundError` | `FileNotFoundError` class does not exist | before 3.3 | | `callable` | `callable` builtin does not exist | from 3.0 up to 3.2 | | `chr/decode` | Substituted an implementation of `chr` for narrow Unicode builds using `decode` | before 3.0 | | `chr/uliteral` | Substituted an implementation of `chr` for narrow Unicode builds using `uliteral` | before 2.6 | | `narrow` | Python was built with narrow Unicode (strings natively stored as UCS-2) | -- | | `!modules` | EmPy module support disabled; `importlib` not available (or IronPython) | before 3.4 | | `!codecs.open` | `codecs.open` is deprecated (use `open` instead) | 3.14 and up | :::{note} Whether Python builds are narrow is a function of how the Python interpreter was built, and not directly correlated with the Python version. ::: `executable: str` : The path to the EmPy interpreter that is being used by the system (analogous to `sys.executable`). `argv: list[str]` : The arguments (analogous to `sys.argv`) used to start the interpreter. The first element is the EmPy document filename and the remaining elements are the arguments, if any. If no EmPy document was specified, `<->` is used. `config: Configuration` : The [configuration](#configuration) instance that the interpreter is using. `core: Core` : The [core](#cores) used by this interpreter. `extension: Optional[Extension]` : The [extension](#extensions), if any, used by this interpreter. `enabled: bool` : A Boolean indicating whether or not output is currently enabled. This can be disabled and re-enabled with [switch markup](#switch-markup). `ok: bool` : A Boolean indicating whether or not the interpreter is still active. `error: Optional[Error]` : If an error occurs, the instance of it will be assigned to this attribute. When using `invoke`, this will determine whether or not a failure exit code is returned. No error is indicated by `None`. ##### Interpreter constructor {#constructor} `__init__(**kwargs)` : The constructor. It takes the following keyword arguments (listed in alphabetical order), all of which have reasonable defaults. {#constructor-arguments-table} | Argument | Type | Meaning | Default | | --- | --- | --- | --- | | `argv` | `Sequence[str]` | The system arguments to use | `['<->']` | | `callback` | `Callable` | A custom callback to register [deprecated] | `None` | | `config` | `Confguration` | The configuration instance to use | default | | `core` | `Core` | The interpreter core to use | `Core()` | | `dispatcher` | `bool \| Callable` | Dispatch errors or raise to caller? | `True` | | `executable` | `str` | The path to the EmPy executable | `".../em.py"` | | `extension` | `Extension` | The extension to install on this interpreter | `None` | | `filespec` | `tuple` | A 3-tuple of the input filename, output mode, and buffering | `None` | | `filters` | `Sequence[Filter]` | The list of filters to install | `[]` | | `finalizers` | `Sequence[Callable]` | The list of finalizers to install | `[]` | | `globals` | `dict` | The globals dictionary to use | `{}` | | `handler` | `Callable` | The error handler to use | default | | `hooks` | `Sequence[Hook]` | The list of hooks to install | `[]` | | `ident` | `str` | The identifier of the interpreter (used for debugging) | `None` | | `immediately` | `bool` | Declare the interpreter ready immediately after initialization? | `True` | | `input` | `file` | The input file to use for interactivity | `sys.stdin` | | `origin` | `bool` | Is this the top-level interpreter? | `False` | | `output` | `file` | The output file to use | `sys.stdout` | | `root` | `str \| tuple \| Context` | The root interpreter context filename | `''` | The ordering of the arguments does not matter. Missing arguments have reasonable defaults and unrecognized arguments are ignored. :::{important} The order of the `Interpreter` constructor arguments has changed over time and is subject to change in the future, so you must use keyword arguments to prevent any ambiguity, _e.g._: ```python import em myConfig = em.Configuration(...) myGlobals = {...} myOutput = open(...) interp = em.Interpreter( config=myConfig, globals=myGlobals, output=myOutput, ...) ``` ::: {#constructor-arguments} The allowed arguments are: `argv: Optional[Sequence[str]]` : The list of EmPy arguments. The first element is always the EmPy executable, with the remaining elements the actual arguments. If not specified, a reasonable default is used with no arguments. `callback: Optional[Callable]` : The custom [callback](#callbacks) to register. Defaults to no callback. :::{warning} Custom callbacks are deprecated in favor of [extensions](#extensions) but registering them is supported for backward compatibility providing that extensions are not also being used. ::: `config: Optional[Configuration]` : The [configuration](#configurations) to use for this interpreter. If not specified, a default configuration will be created and used. :::{note} The current configuration of an interpreter can be modified while the interpreter is running and the changes will be effective as they occur. Configurations can also be shared between multiple interpreters if desired. ::: `core: Core` : The [core](#cores) to use with this interpreter. See [Cores](#cores) for more information. `dispatcher: bool | Callable` : The [dispatcher](#error-dispatchers) to use when an error is encountered. Dispatchers determine whether the error handler will be called (`True`), whether the error will be reraised to the caller (`False`), or something else (a custom callable). See [Error dispatchers](#error-dispatchers) for more information. `executable: str` : A string representing the path to the EmPy executable. `extension: Optional[Extension]` : The [extension](#extensions) to install, if any. `filespec: Optional[tuple[str, str, int | str]]` : An optional 3-tuple of the filename, the file open mode, and the buffering mode of the EmPy script to be loaded. When using the command line arguments, this will be handled automatically. `filters: Sequence[Filter]` : A list of [filters](#filters) to install at startup. Defaults to none. `finalizers: Sequence[Callable]` : A list of [finalizers](#finalizers) to install at startup. Defaults to none. `globals: Optional[dict]` : The globals dictionary to use for this interpreter. If not specified, an empty dictionary will be created and used. `handler: Optional[Callable]` : The [error handler](#error-handlers) to set. If not specified, use the default handler. `hooks: Sequence[Hook]` : A list of [hooks](#hooks) to install at startup. Defaults to none. `ident: Optional[str]` : The name of the interpreter, printed when calling `repr` on the interpreter/pseudomodule object. Used only for debugging; defaults to `None`. `immediately: bool` : A Boolean which indicates whether or not the [`ready`](#ready) method will be called before the constructor exits. This is only relevant for hooks which implement the `atReady` method. Defaults to true. `input: Optional[file]` : The input file to use for interactive mode and pausing at end. Defaults to `sys.stdin`. `origin: bool` : Is this the top-level interpreter? This is used to determine whether to report an error if the proxy is not properly cleaned up on its shutdown, suggesting that the proxy reference count got out of sync due to a subinterpreter not being properly shutdown. Defaults to `False` for a new interpreter, but calling the global `invoke` function (as the main em.py executable does) sets it to `True` for the main interpreter. `output: Optional[file]` : The output file to use. Defaults to `sys.stdout`. `root: str | (tuple[str] | tuple[str, int] | tuple[str, int, int]) | Context` : The root [context](#context-formatting) to use, which appears at the bottom of every Python error traceback (`-r/--raw-errors`). This can be a string, representing the filename; a tuple with between 1 and 3 parameters, with the full 3-tuple consisting of the name, the line number, and the column number; or an instance of the `Context` class, which will be cloned. :::{warning} The five `...Func` arguments (`evalFunc`, `execFunc`, `definerFunc`, `matcherFunc` and `serializerFunc`) collectively define the behavior of the underlying interpreter (which defaults to Python). Alternates can be specified if desired; however, specifying these arguments in the constructor in this way is now deprecated. (These arguments to the constructor are still supported for backward compatibility, however.) Instead, use [cores](#cores). Using cores is as simple as passing the functions (which, if not specified, will default to the standard Python interpreter) to a `Core` constructor and using that: ```python import em core = em.Core( evaluate=evalFunc, execute=execFunc, serialize=serializerFunc, define=definerFunc, match=matcherFunc, ) interp = em.Interpreter(core=core, ...) ``` ::: :::{seealso} The list of `Interpreter` constructor arguments is available in the `constructor` help topic and is summarized [here](HELP.md#interpreter-constructor-arguments-summary). ::: ##### Interpreter methods These methods involve the interpreter directly. :::{note} Most interpreter methods return `None` so they can be called from EmPy expression markup. ::: {#context-management} `__enter__()`/`__exit__(*exc)` : The interpreter presents a context manager interface and so can be used with the `with` Python control structure; this will automatically shut down the interpreter after the control structure ends, _e.g._: ```python import em with em.Interpreter(...) as interp: ... manipulate interp here ... # interp is now shutdown ``` {#reset} `reset([clearStacks: bool])` : Reset the interpreter to a pristine state. If `clearStacks` is true, reset the stacks as well. {#ready} `ready()` : Declare the interpreter ready for processing. This calls the `atReady` hook. By default this is called before the [constructor](#constructor) exits, but the user can do this explicitly by passing `False` to the `immediately` constructor argument and calling it when they wish to declare the interpreter ready. {#shutdown} `shutdown()` : Shutdown the interpreter. No further expansion must be done. This method is idempotent. :::{important} When you create an interpreter, you must call its `shutdown` method when you are done. This is required to remove the proxy on `sys.stdout` that EmPy requires for proper operation and restore your Python environment to the state it was before creating the interpreter. This can be accomplished by creating the interpreter in a `with` statement -- interpreters are also context managers -- or by creating it and shutting it down in a `try`/`finally` statement. This is not needed when calling the `expand` global function; it creates and shuts down an ephemeral interpreter automatically. ::: ##### Interpreter file-like methods These methods mimic a file so the interpreter can be treated as a file-like object (_e.g._, `print("Lorem ipsum", file=empy)`. `write(data: str)` : Write the string data to the output stream. `writelines(lines: list[str])` : Write the sequence of strings to the output stream. `flush()` : Flush the output stream. `close()` : Close the output stream. Note this will never close the fundamental output stream; it will only flush it, and it will only close other streams when they are not at the bottom of the stream stack. `serialize(thing: object)` : Write a string version of the object to the output stream. This will reference `--none-symbol` (_configuration variable:_ `noneSymbol`) if the object is `None`. ##### Interpreter stream methods `top() -> Stream` : Get the top-level stream. `push()` : Push this interpreter onto the proxy's stream stack. `pop()` : Pop this interpreter off the proxy's stream stack. `clear()` : Clear the interpreter's stacks. ##### Interpreter high-level methods `go(inputFilename, inputMode, [preprocessing, [postprocessing]])` : Process the main document with the given mode. Optionally process the specified commands before processing the main document and after, respectively. `interact()` : Go into interactive mode. `file(file, [locals, [dispatcher]])` : Process the given file, expanding its contents. This will defer to one of the below methods based on the buffering setting. `fileLines(file, [locals, [dispatcher]])` : Process the given file line by line. `fileChunks(file, [bufferSize, [locals, [dispatcher]]])` : Process the given file in chunks with the optional buffer size; if not specified, the configuration default will be used. `fileFull(file, [locals, [dispatcher]])` : Process the given file as a single chunk that's read in all at once. `string(string, [locals, [dispatcher]])` : Process the given string, expanding its contents. `import_(filename, module, [locals, [dispatcher]])` : Import an EmPy module contained in `filename` to the module object `module`. `process(command: Command)` : Process a command. `processAll(commands: Sequence[Command])` : Process a sequence of commands. ##### Interpreter context methods These methods manipulate the interpreter's context stack. `identify() -> tuple[char, int, int, int]` : Get a 4-tuple of the current context, consisting of the filename, the line number, the column number, and the number of characters (Unicode code points) processed. `getContext() -> Context` : Get the current context object. `newContext([name: str, [line: int, [column: int, [chars: int]]]]) -> Context` : Create a new context and return it. `pushContext(context: str | tuple | Context)` : Push the given context on top of the context stack. `popContext()` : Pop the top context off the context stack; do not return it. `setContext(context: str | tuple | Context)` : Replace the context on the top of the context stack with the given context. `setContextName(name: str)` : Set the top context's name to the given value. `setContextLine(line: int)` : Set the top context's line to the given value. `setContextColumn(column: int)` : Set the top context's column to the given value. `setContextData([name: str, [line: int, [column: int, [chars: int]]]])` : Set the top context's name, line, and/or column to the given value(s). `restoreContext(oldContext: str | tuple | Context)` : Restore the top context on the stack to the given context. ##### Interpreter finalizer methods These methods manipulate the interpreter's finalizers. `clearFinalizers()` : Clear all finalizers from this interpreter. `appendFinalizer(finalizer: Callable)`/`atExit(finalizer: Callable)` : Append the given finalizer to the finalizers list for this interpreter. `atExit` is an alias for backward compatibility [deprecated]. `prependFinalizer(finalizer: Callable)` : Prepend the given finalizer to the finalizers list for this interpreter. `setFinalizers(finalizers: list[Callable])` : Replace the current list of finalizers wih the given sequence. ##### Interpreter globals methods These methods manipulate the interpreter's globals. `getGlobals() -> dict` : Get the current globals dictionary. `setGlobals(globals: dict)` : Set the current globals dictionary,. `updateGlobals(moreGlobals: dict)` : Update the current globals dictionary, adding this dictionary's entries to it. `clearGlobals()` : Clear the current globals dictionary completely. `saveGlobals([deep: bool])` : Save a copy of the globals off to on the history stack. If deep is true, do a deep copy (defaults to false). `restoreGlobals([destructive: bool])` : Restore the globals dictionary on the top of the globals history stack. If destructive is true (default), pop it off when done. `flattenGlobals([skipKeys: Sequence[str]])` : Flatten the interpreter namespace into the globals. If `skipKeys` is specified, skip over those keys; otherwise, use the defaults from the configuration. ##### Interpreter expansion methods These methods are involved with markup expansion. `include(fileOrFilename, [locals, [name]])` : Include the given EmPy (not Python) document (or filename, which is opened) and process it with the given optional locals dictionary and context name. `expand(data, [locals, [name], [dispatcher]]) -> str` : Create a new context and stream to evaluate the EmPy data, with the given optional locals and context name and return the result. If the expansion raises an exception, by default it will be raised up to the caller; set `dispatcher` to true to have the interpreter handle it with its formal error handler mechanism. Set `dispatcher` to another callable to do custom dispatching. See [Error dispatchers](#error-dispatchers) for more information. `defined(name, [locals]) -> bool` : Return a Boolean indicating whether the given name is present in the interpreter globals (or the optional locals, if provided). `lookup(name, [locals]) -> object` : Lookup the value of a name in the globals (and optionally the locals, if provided) and return the value. `evaluate(expression, [locals, [write]]) -> object` : Evaluate the given Python expression in the interpreter, with the given optional locals dictionary. If write is true, write it to the output stream, otherwise return it (defaults to false). `execute(statements, [locals])` : Execute the given Python statements in the interpreter, with the given optional locals dictionary. `single(source, [locals]) -> Optional[object]` : Execute the given Python expression or statement, with the given optional locals dictionary. This compiles the code with the `single` Python compilation mode which supports either. Return the result or `None`. This method is not used internally by the EmPy system and is not used by interpreter [cores](#cores) but is available for embedding. `atomic(name, value, [locals])` : Do an atomic assignment of the given name and value in the interpreter globals. If the optional locals dictionary is provided, set it in the locals instead. `assign(name, value, [locals])` : Do a potentially complex assignment of the given name "lvalue" and "rvalue." Unlike `atomic`, `assign` can support tuple assignment. `significate(key, [value, [locals]])` : Declare a significator with the given key and optional value (if not specified, defaults to `None`). If the optional locals dictionary is provided, set it in the locals instead. `quote(string) -> str` : Given an EmPy string, return it quoted. `escape(string) -> str` : Given an EmPy string, escape non-ASCII characters in it and return. `getPrefix() -> str` : Get this interpreter's prefix. `setPrefix(char)` : Set this interpreter's prefix. ##### Interpreter diversion methods These methods manipulate the interpreter's diversions. `stopDiverting()` : Stop any current diversion. `createDiversion(name)` : Create a new diversion with the given name but do not start diverting to it. `retrieveDiversion(name, [default]) -> Diversion` : Get the diversion with the given name. If `default` is provided, return that if the diversion does not exist; otherwise, raise an error. `startDiversion(name)` : Start diverting to a diversion with the given name, creating if it necessary. `playDiversion(name, [drop])` : Play the diversion with the given name, optionally dropping it (default is true). `replayDiversion(name, [drop])` : Play the diversion with the given name, optionally dropping it (default is false). `dropDiversion(name)` : Drop the diversion with the given name without playing it. `playAllDiversions()` : Play all diversions in sorted order by name, dropping them. `replayAllDiversions()` : Replay all diversions in sorted order by name, leaving them in place. `dropAllDiversions()` : Drop all diversions without playing them. `getCurrentDiversionName() -> Optional[str]` : Get the name of the current diversion or `None` if there is no current diversion. `getAllDiversionNames() -> list[str]` : Get a list of the names of all diversions in sorted order. `isExistingDiversionName(name) -> bool` : Is the given name the name of an existing diversion? ##### Interpreter filter methods These methods manipulate the interpreter's filters. `resetFilter()` : Reset the filtering system so there are no filters. `getFilter() -> Filter` : Get the top-most filter. `getLastFilter() -> Filter` : Get the bottom-most filter. `setFilter(*filters)` : Set the top-most filter(s) to the given filter chain, replacing any current chain. More than one filter can be specified as separate arguments. `prependFilter(filter)` : Prepend the given filter to the current filter chain. `appendFilter(filter)` : Append the given filter to the current filter chain. `setFilterChain(filters)` : Set the filter chain to the given list of filters, replacing any current chain. ##### Interpreter core methods These methods involve cores, an optional EmPy feature for overriding the core behavior of an EmPy interpreter. See [cores](#cores) for details. `hasCore() -> bool` : Does this interpreter currently have a core installed? (A default core is installed by the time initialization ends, regardless of whether or not a custom core has been specified.) `getCore() -> Core` : Get the core currently inserted into this interpreter. `insertCore(core: Optional[Core])` : Insert a core on this interpreter. If `core` is `None`, a default core will be created and used. This will detach any previous core. `ejectCore()` : Eject this interpreter's core. Since cores may have a reference back to the interpreter, this will cut any cyclical link that may be present. This method is automatically called by the interpreter's `shutdown` method. Note that once this method is called, no further expansion can be performed by this interpreter until a new core is installed. This method is idempotent. `resetCore()` : Reset the core for this interpreter to the default (Python). ##### Interpreter extension methods `hasExtension() -> bool` : Does this interpreter already have an extension installed? `getExtension() -> Optional[Extension]` : Get the extension installed in this interpreter, or `None` if there is no such extension. `installExtension(Extension)` : Install an extension in this interpreter. This can only be done once per interpreter. `callExtension(name: str, contents: str, depth: int)` : Calls the extension as if extension markup had been encountered and serializes the result. ##### Interpreter hook methods These methods manipulate the interpreter's hooks. `invokeHook(_name: str, **kwargs)` : Invoke the hooks associated with the given name and keyword arguments dictionary. This is the primary method called when hook events are invoked. `areHooksEnabled() -> bool` : Are hooks currently enabled? `enableHooks()` : Enable hooks. `disableHooks()` : Disable hooks. Any existing hooks will not be called until `enableHooks` is called. `getHooks() -> list[Hook]` : Get the current list of hooks. `prependHook(hook: Hook)` : Prepend the given hook to the list of hooks. `appendHook(hook: Hook)` : Append the given hook to the list of hooks. `removeHook(hook: Hook)` : Remove the given hook from the list of hooks. `clearHooks()` : Clear the list of hooks. ##### Interpreter callback methods These methods manipulate the interpreter's custom callback. A callback is a callable object which takes one argument: the content to process. `hasCallback() -> bool` : Does this interpreter have a custom callback registered? `getCallback() -> Optional[Callable]` : Return the interpreter's registered custom callback or `None` if none is registered. `registerCallback(callback)` : Register the given callback with the interpreter, replacing any existing callback. `deregisterCallback()` : Remove the current interpreter's registered callback, if any. `invokeCallback(contents)` : Manually invoke the interpreter's custom callback as if the custom markup `@<...>` were expanded. :::{warning} Custom callbacks are deprecated in favor of [extensions](#extensions) but registering them and querying them is supported for backward compatibility, providing that extensions are not also being used. ::: ##### Interpreter error handler methods These methods manipulate the interpreter's error handler. A handler is a callable object which takes three arguments: the type of the error, the error instance itself, and a traceback object. `defaultHandler(type, error, traceback)` : The default EmPy error handler. This can be called manually by custom error handlers if desired. `getHandler() -> Callable` : Get the current error handler, or `None` for the default. `setHandler(handler, [exitOnError])` : Set the error handler. If `exitOnError` is not `None` (defaults to false), also set the interpreter's configuration's `exitOnError` configuration variable. This default is `False` (so that custom error handlers do not automatically exit, which is usually the intent). `resetHandler([exitOnError])` : Reset the error handler to the default. `exitOnError` is as above. `invokeHandler(*exc)` : Manually invoke the error handler. The arguments should be the 3-tuple of the return value of `sys.exc_info` as a single argument or as three positional arguments, _e.g._: ```python interp.invokeHandler(sys.exc_info()) # or: *sys.exc_info() ``` `getExitCode() -> int` : Get the exit code that will be returned by the process given the current state of the `error` attribute. ##### Interpreter emoji methods `initializeEmojiModules([moduleNames: Sequence[str]])` : Initialize the allowed emoji modules to use by name. If the names list is not specified, use the defaults. `getEmojiModule(moduleName: str) -> Module` : Get the initialized module abstraction corresponding to the given module name. `getEmojiModuleNames() -> list[str]` : Return the list of available emoji modules by name in their proper order. `substituteEmoji(text: str) -> str` : Use the emoji facilities to lookup the given emoji name and return the result as if the emoji markup `@:...:` were expanded. :::{seealso} The list of pseudomodule/interpreter attributes in methods is available in the `pseudo` help topic and is summarized [here](HELP.md#pseudomodule-attributes-and-methods-summary). ::: #### Commands **Commands** are self-contained objects which encapsulate some interpreter processing. They are primarily used by the command line options system, but can be used by users. Commands are created from the `Command` class and its subclasses, and are processed by an interpreter with its `process` method. Commands are created with a single argument which represents the action of that particular command. For instance, this EmPy code will use commands to include an EmPy document: :::{admonition} Example 60: Commands _Source_: ⌨️
`````` @{ import em # Create a temporary file for this example. with open('/tmp/include.em', 'w') as file: file.write("Hello, world! 1 + 1 = @(1 + 1).\n") }@ Including a file with a command: @empy.process(em.DocumentCommand('/tmp/include.em'))@ ``````
_Output_: 🖥️
`````` Including a file with a command: Hello, world! 1 + 1 = 2. ``````
::: A sequence of commands can be processed with the `processAll` method. The following `Command` subclasses are available, alongside their corresponding command line options. Preprocessing commands are processed before the main EmPy document is expanded; postprocessing commands after. {#command-classes-table} | Subclass | Behavior | Preprocessing option | Postprocessing option | | --- | --- | --- | --- | | `ImportCommand` | Import a Python module | `-I/--import=MODULES` | | `DefineCommand` | Define a Python variable | `-D/--define=DEFN` | | `StringCommand` | Define a Python string variable | `-S/--string=STR` | | `DocumentCommand` | Expand an EmPy document by filename | `-P/--preprocess=FILENAME` | `-Q/--postprocess=FILENAME` | | `ExecuteCommand` | Execute a Python statement | `-E/--execute=STATEMENT` | `-K/--postexecute=STATEMENT` | | `FileCommand` | Execute a Python file by filename | `-F/--file=FILENAME` | `-G/--postfile=FILENAME` | | `ExpandCommand` | Expand some EmPy markup | `-X/--expand=MARKUP` | `-Y/--postexpand=MARKUP` | Users can define their own subclasses of `Command`. :::{seealso} For more details on the various commands, check the corresponding [](#command-line-options). ::: :::{versionchanged} 4.0 Commands were codified and introduced in EmPy version 4.0, though the equivalent command line options that they correspond to were available going back to 1._x_. ::: #### Plugins **Plugins** are objects which can be installed in an interpreter and contain a reference back to it via an `interp` attribute. They are registered with the interpreter by calling an interpreter method such as `insertCore`, `installExtension`, etc. and are either callable objects (callbacks, finalizers) or are objects defined with attributes approrpiate to their purpose (cores, extensions). User-defined plugins can derive from `em.Plugin` or the relevant subclass (_e.g._, `em.Core` or `em.Extension`). The types of plugins available follow below. {#plugins-table} | Type | Purpose | Subclass | Install, uninstall method | Ver. | | --- | --- | --- | --- | --- | | [](#cores) | Modify core interpreter behavior | `em.Core` | `insertCore`, `ejectCore` | 4.1 | | [](#extensions) | Add additional customized markup | `em.Extension` | `installExtension`, `uninstallExtension` | 4.1 | | [](#callbacks) | Add custom markup callback (deprecated) | `emlib.Callback` | `registerCallback` | 3.3 | | [](#finalizers) | Functions to call before shutdown | `emlib.Finalizer` | `append`/`prependFinalizer`, `clearFinalizers` | 2.1 | | [](#hooks) | Objects to adjust interepter behavior by event | `emlib.Hook` | `addHook`/`appendHook`/`prependHook`, `removeHook` | 2.0 | | [Handlers](#error-handlers) | Error handlers | `emlib.Handler` | `setHandler`, `resetHandler` | 4.0 | :::{versionadded} 4.1 Plugins were codified and introduced in EmPy version 4.1. ::: ##### Cores By default, of course, EmPy expands expressions and statements through the underlying Python interpreter. But even this behavior is configurable with interpreter **cores**. Cores can be used to completely change the underlying language that EmPy expands to (provided, naturally, that it can be implemented with Python). Cores (represented with the base class `Core` in the module `em`) support any language/system that can be encapsulated with a set of globals, optional locals, and with these actions (methods on the core object): evaluating an expression, executing a statement, serializing an object, defining an EmPy function (`@[def]`), and defining the behavior of the `@[match]` markup. As with the Python languge, expressions which are evaluated must return a value (or `None`); statements which are executed do not return a value. Beyond this definition, the meaning and purpose of these operations in a custom core are completely configurable. Cores can be created by either providing a set of callables to the `Core` constructor or by deriving a subclass from `Core` and providing overriding methods. The default implementation (`Core()`) provides the implementation for Python. Not specifying a core defaults to this implementation. {#core-constructor} The default `Core` class has the following constructor: `__init__(**kwargs)` : Create a core with optional keyword arguments. The arguments can be callables representing the different possible operations on a core, or an interpreter to attach to immediately after initialization: {#core-constructor-arguments-table} | Argument | Description | Default | | --- | --- | --- | | `evaluate` | Evaluate an expression; return the result | `eval` | | `execute` | Execute a statement; no return result | `exec` | | `serialize` | Serialize an object; return the result | `str` | | `define` | Functionality of `@[def ...]` markup; no return result | (Python-specific) | | `match` | Functionality of `@[match ...]` markup; no return result | (Python-specific) | An optional `interp` argument is also allowed which will automatically attach this core to the given interpreter after intiialization. {#core-methods} The expected signatures of these methods are as follows: `evaluate(code: str, globals: dict, [locals: dict]) -> object` : Evaluate the string expression given the current globals (and optional locals) and return the result. `execute(code: str, globals: dict, [locals: dict])` : Execute the string statements given the current globals (and optional locals). The return value is ignored. `serialize(thing: object) -> str` : Take a custom object and render it as a string for output. `define(signature: str, definition: str, [globals: dict, [locals: dict]])` : Implement the behavior of the `def` control markup `@[def SIGNATURE]DEFINITION@[end def]`, given the globals dictionary (defaults to the interpreter's globals), and an optional locals dictionary. The meaning of the signature and the definition are arbitrary. The return value is ignored. `match(expression: str, cases: list[Core.Case], [locals: dict])` : Implement the behavior of the `match` control markup `@[match EXPRESSION]...@[end match]`. The first argument is the string expression to test. `cases` is a list of `Core.Case` instances each representing a `case` statements. Cases have the following attributes: {#match-arguments-table} | Attribute | Type | Purpose | | --- | --- | --- | | `expression` | `str` | A string representing the case test expression | | `tokens` | `list[Token]` | The list of tokens to run if there is a match | The `expression` instance is the string representing the case test, and the second element is a list of `Core.Case` instances representing the case expression to test and the markup to expand when the case matches. Also passed are is an optional locals dictionary. The return result is ignored. Cores are installed in an interpreter by either providing one as the `core` [constructor argument](#constructor-arguments) or by calling the `insertCore` interpreter method. An interpreter's core can be reset to the default (Python implementation core) with the `resetCore` method, or can be manually removed by calling the `ejectCore` method (though this will leave the interpeter non-functional until a new core is installed). An interpreter's core can also be modified dynamically while an interpreter is running. Cores must be attached to the interpreter in order to make sure that cores have a reference to the interpreter (needed for the default `define` method). This is done automatically when calling `insertCore`. As mentioned earlier, cores can be created in one of two ways. First, a subclass of `Core` in the `em` module can be instantiated and provided to the interpreter: ```python import em class MyCore(em.Core): def evaluate(self, code, globals, locals=None): ... def execute(self, code, globals, locals=None): ... def serialize(self, thing): ... def define(self, signature, definition, globals, locals=None): ... def match(self, expression, casePairs, globals, locals=None): ... core = MyCore(...) interp = em.Interpreter(core=core) ``` Alternatively, the core methods can be implemented as standalone callables and passed to the `Core` constructor: ```python import em def myEvaluate(code, globals, locals=None): ... def myExecute(code, globals, locals=None): ... def mySerialize(thing): ... def myDefine(signature, definition, globals, locals=None): ... def myMatch(expression, casePairs, globals, locals=None): ... core = em.Core( evaluate=myEvaluate, execute=myExecute, serialize=mySerialize, define=myDefine, match=myMatch, ) interp = em.Interpreter(core=core) ``` For methods which are not defined in a subclass or specified as a callable in the constructor, the default (Python implementation core) will be used. The source code for the default definitions can be used as a guide. :::{tip} The `define` method and `match` method correspond to the `@[def ...]` and `@[match ...]` markup, respectively. If these markups will not be used by the user, these methods can be left unimplemented as they will never be called. It's good form, however, to have them raise `NotImplementedError` in that case just to make the intent clear. ::: :::{versionadded} 4.1 Interpreter cores were introduced in EmPy version 4.1. ::: ##### Extensions Starting with EmPy 4.1, users can now specify their own customizable markup with **extensions**. They define methods which are called when the respective custom markup is expanded and are installed via the `installExtension` method on the interpreter. Extensions are documented in the [Extension markup](#extension-markup) section. :::{versionadded} 4.1 Extensions were introduced in EmPy version 4.1, replacing custom markup which was introduced in EmPy version 3.3. ::: ##### Callbacks :::{warning} Custom callbacks are deprecated in favor of [extensions](#extensions) but registering them and querying them is supported for backward compatibility providing that extensions are not also being used. ::: Before the introduction of [extensions](#extensions), only one markup was available for customization: the **custom markup**, `@<...>`. This meaning of this markup was provided with the use of a Python callable object referred to as a **custom callback**, or just "callback," which can be set or queried using pseudomodule functions. At most one custom callback can be registered, and once registered, it cannot be deregistered or replaced. When the custom markup `@<...>` is encountered, the contents inside the markup are passed to the current custom callback. Its return value, if not `None`, is then written to the output stream. The custom callback may also perform operations with side effects resulting in output, as well. If there are multiple opening angle brackets, an equal number of closing angle brackets will be required to match. This allows the embedding of `<` and `>` in the contents passed to the callback. The custom callback is a callable object which, when invoked, is passed a single argument: a string representing the contents of what was found inside the custom markup `@<...>`. Only one custom callback can be registered at a time. To register a callback, call `empy.registerCallback`. To see if there is a callback registered, use `empy.hasCallback`. To retrieve the callback registered with the interpreter, use `empy.getCallback`; if no callback is registered, `None` will be returned. Finally, to invoke the callback explicitly just as if the custom markup had been encountered, call `empy.invokeCallback`. For instance, `@` would be equivalent to the call `@empy.invokeCallback("This text")`. Invoking a callback (either explicitly with `empy.invokeCallback` or by processing a `@<...>` custom markup) when no callback has been registered is an error. :::{admonition} Example 61: Custom markup _Source_: ⌨️
`````` @{ def callback(contents): return contents.upper() empy.registerCallback(callback) }@ This will be in uppercase: @. This will also contain angle brackets: @< test>>. ``````
_Output_: 🖥️
`````` This will be in uppercase: THIS IS A TEST. This will also contain angle brackets: THIS IS TEST. ``````
::: :::{deprecated} 4.1 Custom markup was introduced in EmPy version 3.3 and transformed into extension markup in EmPy version 4.1. ::: ##### Finalizers Every interpreter must shutdown (by the `shutdown` method being called either implicitly or explicitly). As part of this process, the interpreter runs any **finalizers** that may have been registered with the interpreter. Finalizers are callable objects which take zero arguments. The interpreter contains a list of finalizers which are called sequentially in order. If a finalizer raises an exception, any remaining finalizers will not be called that exception will be propagated up. To add a finalizer, call either the `appendFinalizer` or `preprendFinalizer` interpreter methods. To clear all finalizers, call the `clearFinalizers` method. :::{note} `atExit` is an alias for `appendFinalizer` for backward compatibility and is now deprecated. ::: :::{admonition} Example 62: Finalizers _Source_: ⌨️
`````` @# These are printed in reverse order. @empy.appendFinalizer(lambda: empy.write("This is the last line.\n"))@ @empy.appendFinalizer(lambda empy=empy: empy.write("This is the penultimate line.\n"))@ @{ import em class Finalizer: def __init__(self, interp): self.interp = interp def __call__(self): self.interp.write("This is the third to last line.\n") finalizer = Finalizer(empy) empy.appendFinalizer(finalizer) }@ This is the first line. ``````
_Output_: 🖥️
`````` This is the first line. This is the third to last line. This is the penultimate line. This is the last line. ``````
::: :::{tip} The finalizers are callables which take no arguments when they are called, so if they need a reference to the interpreter to do their work (as the example above), they need to arrange it with a closure, an implicit argument, or by implementing it as an instance which contains a reference to the interpreter. All three of these approaches are illustrated in the example above. ::: :::{warning} When using the `expand` method or standalone function, the `StringIO` object which is used to capture the output of the ephemeral interpreter is processed before finalizers are handled. Thus attempting to use finalizers to generate output will not work as expected. Instead, create a dedicated interpreter (Python code): ```python import em source = ... # the EmPy source to expand with em.StringIO() as file: with em.Interpreter(output=file, ...) as interp: interp.string(source) output = file.getvalue() ``` ::: :::{versionadded} 2.1 Finalizers were introduced in EmPy version 2.1. ::: ##### Handlers Error handlers are also implemented as plugins. See [Error handlers](#error-handlers). ### Diversions EmPy supports an extended form of **diversions**, which are a mechanism for deferring and playing back output on demand, similar to the functionality included in [m4](https://www.gnu.org/software/m4/). Multiple "streams" of output can be diverted (deferred) and played back (undiverted) in this manner. A diversion is identified with a name, which is any immutable object such an integer or string. Diversions can be played back multiple times ("replayed") if desired. When recalled, diverted code is *not* resent through the EmPy interpreter (although a [filter](#filters) could be set up to do this). By default, no diversions take place. When no diversion is in effect, processing output goes directly to the specified output file. This state can be explicitly requested at any time by calling the `empy.stopDiverting` function. It is always legal to call this function, even when there is currently no active diversion. When diverted, however, output goes to a deferred location which can then be recalled later. Output is diverted with the `empy.startDiversion` function, which takes an argument that is the name of the diversion. If there is no diversion by that name, a new diversion is created and output will be sent to that diversion; if the diversion already exists, output will be appended to that preexisting diversion. Output send to diversions can be recalled in two ways. The first is through the `empy.playDiversion` function, which takes the name of the diversion as an argument. This plays back the named diversion, sends it to the output, and then erases that diversion. A variant of this behavior is the `empy.replayDiversion`, which plays back the named diversion but does not eliminate it afterwards; `empy.replayDiversion` can be repeatedly called with the same diversion name, and will replay that diversion repeatedly. `empy.createDiversion` will create a diversion without actually diverting to it, for cases where you want to make sure a diversion exists but do not yet want to send anything to it. The diversion object itself can be retrieved with `empy.retrieveDiversion`. Diversions act as writable file-objects, supporting the usual `write`, `writelines`, `flush`, and `close` methods. The data that has been diverted to them can be manually retrieved in one of two ways; either through the `asString` method, which returns the entire contents of the diversion as a single string, or through the `asFile` method, which returns the contents of the diversion as a readable (not writable) file-like object. Diversions can also be explicitly deleted without playing them back with the `empy.dropDiversion` function, which takes the desired diversion name as an argument. Additionally there are three functions which will apply the above operations to all existing diversions: `empy.playAllDiversions`, `empy.replayAllDiversions`, and `empy.dropAllDiversions`. The diversions are handled in lexicographical order by their name. Also, all three will do the equivalent of a `empy.stopDiverting` call before they do their thing. The name of the current diversion can be requested with the `empy.getCurrentDiversionName` function; also, the names of all existing diversions (in sorted order) can be retrieved with `empy.getAllDiversionNames`. `empy.isExistingDiversionName` will return whether or not a diversion with the given name exists. When all processing is finished, the equivalent of a call to `empy.playAllDiversions` is done. This can be disabled with the `--no-auto-play-diversions` (_configuration variable:_ `autoPlayDiversions = False`) option. :::{admonition} Example 3: Diversions sample _Source_: ⌨️
`````` This text is output normally. @empy.startDiversion('A')@ (This text was diverted!) @empy.stopDiverting()@ This text is back to being output normally. Now playing the diversion: @empy.playDiversion('A')@ And now back to normal output. ``````
_Output_: 🖥️
`````` This text is output normally. This text is back to being output normally. Now playing the diversion: (This text was diverted!) And now back to normal output. ``````
::: :::{versionadded} 1.0 Diversions were introduced in EmPy version 1.0. ::: ### Filters EmPy also supports dynamic **filters**. Filters are put in place immediately before the final output file, and so are only invoked after all other processing has taken place (including interpreting and diverting). Filters take input, remap it, and then send it to the output. They can be chained together where a series of filters point to each other in series and then finally to the output file. The current top-level filter can be retrieved with `empy.getFilter` (or `empy.getFirstFilter`). The last filter in the chain (the one just before the underlying file) can be retrieved with `empy.getLastFilter`. The filter can be set with `empy.setFilter` (which allows multiple arguments to constitute a chain). To append a filter at the end of the chain (inserting it just before the underlying output file), use `empy.appendFilter`. To prepend it to the top of the chain, use `empy.prependFilter`. A filter chain can be set directly with `empy.setFilterChain`. And a filter chain can be reset with `empy.resetFilter`, removing all filters. Filters are, at their core, simply file-like objects (minimally supporting `write`, `flush`, and `close` methods that behave in the usual way) which, after performing whatever processing they need to do, send their work to the next file-like object or filter in line, called that filter's "sink." That is to say, filters can be "chained" together; the action of each filter takes place in sequence, with the output of one filter being the input of the next. The final sink of the filter chain will be the output file. Additionally, filters support a `_flush` method (note the leading underscore) which will always flush the filter's underlying sink; this method should be not overridden. Filters also support two additional methods, not part of the traditional file interface: `attach`, which takes as an argument a file-like object (perhaps another filter) and sets that as the filter's "sink" -- that is, the next filter/file-like object in line. `detach` (which takes no arguments) is another method which flushes the filter and removes its sink, leaving it isolated. Finally, `next`, if present, is an attribute which references the filter's sink -- or `None`, if the filter does not yet have a sink attached. To create your own filter, you can create an object which supports the above described interface, or simply derive from the `Filter` class (or one of its subclasses) in the `emlib` module and override the relevant methods. :::{admonition} Example 4: Filters sample _Source_: ⌨️
`````` @{ # For access to the filter classes. import emlib }@ This text is normal. @empy.appendFilter(emlib.FunctionFilter(lambda x: x.upper()))@ This text is in all uppercase! @empy.appendFilter(emlib.FunctionFilter(lambda x: '[' + x + ']'))@ Now it's also surrounded by brackets! (Note the brackets are around output as it is sent, not at the beginning and end of each line.) @empy.resetFilter()@ Now it's back to normal. ``````
_Output_: 🖥️
`````` This text is normal. THIS TEXT IS IN ALL UPPERCASE! [NOW IT'S ALSO SURROUNDED BY BRACKETS! (NOTE THE BRACKETS ARE AROUND OUTPUT AS IT IS SENT, NOT AT THE BEGINNING AND END OF EACH LINE.) ]Now it's back to normal. ``````
::: :::{versionadded} 1.3 Filters were introduced in EmPy version 1.3. ::: ### Modules EmPy also supports importing EmPy files as modules, the same way that Python can import Python modules. EmPy modules are files with an .em extension (configurable with `--module-extension` (_configuration variable:_ `moduleExtension`)) located somewhere in the path. EmPy modules are imported with the `import` statement just as Python modules are imported. EmPy modules are implemented via the [`importlib` architecture](https://docs.python.org/3/library/importlib.html). EmPy modules are activated by installing a meta path finder instance in `sys.meta_path`. By default, it is installed before all the other meta path finders; this can be modified with `--module-finder-index` (_configuration variable:_ `moduleFinderIndex`) -- it represents the index to insert the module finder in the meta path, with 0 being at the beginning; a negative value indicates that it should be appended. This module path finder is installed when the first interpreter is created. It is designed so that if an `import` statement is executed outside of a running interpreter, the EmPy module path finder will be skipped. When all interpreters are shut down, the meta path finder is _not_ removed from the `sys.meta_path`; it will become inactive since there is no proxy installed and no interpreter is running. EmPy modules are real modules and have the same attributes and behavior as Python modules. When an EmPy module is imported, the module is created, and then the pseudodmodule is placed in that module's globals (or its attributes are if `-f/--flatten` (_environment variable:_ `EMPY_FLATTEN`, _configuration variable:_ `doFlatten = True`) is set). After the module is so prepared, the source file is expanded in a new interpreter context with the globals pointing to that new module's contents. Module support can disabled with `-g/--disable-modules` (_configuration variable:_ `supportModules = False`). An EmPy document can determine whether it is being imported as a module or expanded naturally by checking for the globals `__name__`, `__file__`, and/or `__spec__`. As an example, given this file names.em somewhere in your path: ```empy @[def upper(x)]@x.upper()@[end def]@ @[def capitalize(x)]@x.capitalize()@[end def]@ @[def lower(x)]@x.lower()@[end def]@ ``` Then (with test.em found in /tmp): :::{admonition} Example 63: Modules _Source_: ⌨️
`````` @{ import names }@ Module: @names Uppercase: @names.upper("uppercase"). Lowercase: @names.lower("LOWERCASE"). Capitalize: @names.capitalize("capitalize"). ``````
_Output_: 🖥️
`````` Module: Uppercase: UPPERCASE. Lowercase: lowercase. Capitalize: Capitalize. ``````
::: :::{important} To change the filename extension used to detect EmPy modules (which defaults to `.em`), use `--module-extension` (_configuration variable:_ `moduleExtension`). The meta path finder used to support modules is installed when the first interpreter is created; therefore, changing the configuration variable `moduleExtension` after the interpreter is up and running will have no effect. To use configurations to change the module extension, use the `-c/--config-file=FILENAME` (_environment variable:_ `EMPY_CONFIG`) or `--config=STATEMENTS` command line options, or create a `Configuration` object manually and then pass it into the first `Interpreter` instance created. For instance, to use the extension .empy: 
% em.py --module-extension=.empy ...

...
or 
% em.py --config='moduleExtension = ".empy"' ...

...
or (Python code): ```python import em config = em.Configuration(modulExtension='.empy') interp = em.Interpreter(config=config, ...) ... use interp here ... ``` ::: :::{tip} By default, any output generated by an EmPy module _will_ be sent to the output. Often this is undesirable, as modules are usually intended to define classes, functions and variables, rather than generate output. Using natural spacing between these definitions -- particularly if they are long and take up many lines themselves -- would normally result in blank lines in the output. For instance, when importing this module: ```empy @[def f(...)]@ ... definition of f here ... @[end def]@ @[def g(...)]@ ... definition of g here ... @[end def]@ ``` a blank line will be rendered since there is one between the two function definitions. That is unfortunate since the blank line helps to separate the two definitions. This can be addressed in a few different ways: 1. Wrap the EmPy module in [switch markup](#switch-markup) (`@- ... NL`, `@+ ... NL`). Something like this: ```empy @- @[def f(...)]@ ... definition of f here ... @[end def]@ @[def g(...)]@ ... definition of g here ... @[end def]@ @+ ``` 2. Systematically use whitespace markup `@ NL` or comment markup `@#` to make sure no blank lines are generated: ```empy @[def f(...)]@ ... definition of f here ... @[end def]@ @ @[def g(...)]@ ... definition of g here ... @[end def]@ ``` 3. Disable module output with `-j/--disable-import-output` (_configuration variable:_ `enableImportOutput = False`). ::: :::{warning} EmPy modules rely on the `importlib` architecture in order to function, so they are only supported in Python version 3.4 and up. Also, IronPython's `importlib` implementation is flawed, so modules do not function in IronPython. To see if modules are not supported in your interpreter, verify that the string `!modules` is an element of the `compat` pseudomodule/interpreter attribute. ::: :::{versionadded} 4.2 Modules were introduced in EmPy version 4.2. ::: ### Hooks The EmPy system allows for the registration of **hooks** with a running EmPy interpreter. Hooks are objects, registered with an interpreter, whose methods represent specific hook events. Any number of hook objects can be registered with an interpreter, and when a hook is invoked, the associated method on each one of those hook objects will be called by the interpreter in sequence. The method name indicates the type of hook, and it is called with a keyword list of arguments corresponding the event arguments. To use a hook, derive a class from `emlib.Hook` and override the desired methods (with the same signatures as they appear in the base class). Create an instance of that subclass, and then register it with a running interpreter with the `empy.addHook` function. A hook instance can be removed with the `empy.removeHook` function. More than one hook instance can be registered with an interpreter; in such a case, the appropriate methods are invoked on each instance in the order in which they were appended. To adjust this behavior, an optional `prepend` argument to the `empy.addHook` function can be used dictate that the new hook should placed at the *beginning* of the sequence of hooks, rather than at the end (which is the default). Also there are explicit `empy.appendHook` and `empy.prependHook` functions. All hooks can be enabled and disabled entirely for a given interpreter; this is done with the `empy.enableHooks` and `empy.disableHooks` functions. By default hooks are enabled, but obviously if no hooks have been registered no hooks will be called. Whether hooks are enabled or disabled can be determined by calling `empy.areHooksEnabled`. To get the list of registered hooks, call `empy.getHooks`. All the hooks can be removed with `empy.clearHooks`. Finally, to invoke a hook manually, use `empy.invokeHook`. For a list of supported hooks, see [](#hook-methods) or the `Hook` class definition in the `emlib` module. (There is also an `AbstractHook` class in this module which does not have blank stubs for existing hook methods in case a user wishes to create them dynamically.) For example: :::{admonition} Example 5: Hooks sample _Source_: ⌨️
`````` @# Modify the backquote markup to prepend and append backquotes @# (say, for a document rendering system, cough cough). @{ import emlib class BackquoteHook(emlib.Hook): def __init__(self, interp): self.interp = interp def preBackquote(self, literal): self.interp.write('`' + literal + '`') return True # return true to skip the standard behavior empy.addHook(BackquoteHook(empy)) }@ Now backquote markup will render with backquotes: @ @`this is now in backquotes`! ``````
_Output_: 🖥️
`````` Now backquote markup will render with backquotes: `this is now in backquotes`! ``````
::: :::{versionchanged} 4.0 Hooks were originally introduced in EmPy version 2.0, much improved in version 3.2, and revamped again in version 4.0. ::: #### Hook methods ##### Hook `at...` methods These hooks are called when a self-contained event occurs. `atInstallProxy(proxy, new)` : A `sys.stdout` proxy was installed. The Boolean value `new` indicates whether or not the proxy was preexisting. `atUninstallProxy(proxy, done)` : A `sys.stdout` proxy was uninstalled. The Boolean value `done` indicates whether the reference count went to zero (and so the proxy has been completely removed). `atStartup()` : The interpreter has started up. `atReady()` : The interpreter has declared itself ready for processing. `atFinalize()` : The interpreter is finalizing. `atShutdown()` : The interpreter is shutting down. `atParse(scanner, locals)` : The interpreter is initiating a parse action with the given scanner and locals dictionary (which may be `None`). `atToken(token)` : The interpreter is expanding a token. `atHandle(info, fatal, contexts)` : The interpreter has encountered an error. The `info` parameter is a 3-tuple error (error type, error, traceback) returned from `sys.exc_info`, `fatal` is a Boolean indicating whether the interpreter should exit afterwards, and `contexts` is the context stack. `atInteract()` : The interpreter is going interactive. ##### Hook context methods `pushContext(context)` : This context is being pushed. `popContext(context)` : This context has been popped. `setContext(context)` : This context has been set or modified. `restoreContext(context)` : This context has been restored. ##### Hook `pre...`/`post...` methods The `pre...` hooks are invoked before a token expands. The hook can return a true value to indicate that it has intercepted the expansion and the token should cancel native expansion. Not explicitly returning anything, as in standard Python, is equivalent to returning `None`, which is a false value, which continues expansion: :::{admonition} Example 64: Hook `pre...` methods _Source_: ⌨️
`````` @{ import emlib class Hook(emlib.Hook): def __init__(self, interp): self.interp = interp def preString(self, string): self.interp.write('[' + string + ']') return True empy.addHook(Hook(empy)) }@ @# Now test it: @"Hello, world!" ``````
_Output_: 🖥️
`````` ["Hello, world!"] ``````
::: :::{tip} It's typical to want to have an instance of the interpreter/pseudomodule available to the hook, but it is neither done automatically nor is it required. ::: The `post...` hooks are invoked after a non-intercepted token finishes expanding. Not all `pre...` hooks have a corresponding `post...` hook. The `post...` hooks take at most one argument (the result of the token expansion, if applicable) and their return value is ignored. `preLineComment(comment)`, `postLineComment()` : The line comment `@#... NL` with the given text. `preInlineComment(comment)`, `postInlineComment()` : The inline comment `@*...*` with the given text. `preWhitespace(whitespace)` : The whitespace token `@ WS` with the given whitespace. `prePrefix()` : The prefix token `@@`. `preString(string)`, `postString()` : The string token `@'...'`, etc. with the given string. `preBackquote(literal)`, `postBackquote(result)` : The backquote token `` @`...` `` with the given literal. `preSignificator(key, value, stringized)`, `postSignificator()` : The significator token `@%... NL`, etc. with the given key, value and a Boolean indicating whether the significator is stringized. `preContextName(name)`, `postContentName()` : The context name token `@?...` with the given name. `preContextLine(line)`, `postContextLine()` : The context line token `@!...` with the given line. `preExpression(pairs, except, locals)`, `postExpression(result)` : The expression token `@(...)` with the given if-then run pairs, the except run, and the locals dictionary (which may be `None`). `preSimple(code, subtokens, locals)`, `postSimple(result)` : The simple expression token `@word` (etc.) with the given code, subtokens and locals. `preInPlace(code, locals)`, `postInPlace(result)` : The in-place expression token `@$...$...$` with the given code (first section) and locals (which may be `None`). `preStatement(code, locals)`, `postStatement()` : The statement token `@{...}` with the given code and locals (which may be `None`). `preControl(type, rest, locals)`, `postControl()` : The control token `@[...]` of the given type, with the rest run and locals (which may be None). `preEscape(code)`, `postEscape()` : The control token `@\...` with the resulting code. `preDiacritic(code)`, `postDiacritic()` : The diacritic token `@^...` with the resulting code. `preIcon(code)`, `postIcon()` : The icon token `@|...` with the resulting code. `preEmoji(name)`, `postEmoji()` : The emoji token `@:...:` with the given name. `preExtension(name, contents, depth)`, `postExtension(result)` : An extension with the given name, contents and depth was invoked. `preCustom(contents)`, `postCustom()` : The custom token `@<...>` with the given contents. ##### Hook `before...`/`after...` methods The `before...` and `after...` hooks are invoked before and after (go figure) mid-level expansion activities are performed. Any `locals` argument indicates the locals dictionary, which may be `None`. If the expansion returns something relevant, it is passed as a `result` argument to the corresponding `after...` method. `beforeProcess(command, n)`, `afterProcess()` : The given command (with index number) is being processed. `beforeInclude(file, locals, name)`, `afterInclude()` : The given file is being processed with the given name. `beforeExpand(string, locals, name)`, `afterExpand(result)` : `empy.expand` is being called with the given string and name. `beforeTokens(tokens, locals)`, `afterTokens(result)` : The given list of tokens is being processed. `beforeFileLines(file, locals)`, `afterFileLines()` : The given file is being read by lines. `beforeFileChunks(file, locals)`, `afterFileChunks()` : The given file is being read by buffered chunks. `beforeFileFull(file, locals)`, `afterFileFull()` : The given file is being read fully. `beforeString(string, locals)`, `afterString()` : The given string is being processed. `beforeQuote(string)`, `afterQuote(result)` : The given string is being quoted. `beforeEscape(string)`, `afterEscape(result)` : The given string is being escaped. `beforeSignificate(key, value, locals)`, `afterSignificate()` : The given key/value pair is being processed. `beforeCallback(contents)`, `afterCallback()` : The custom callback is being processed with the given contents. `beforeAtomic(name, value, locals)`, `afterAtomic()` : The given atomic variable setting with the name and value is being processed. `beforeMulti(names, values, locals)`, `afterMulti()` : The given complex variable setting with the names and values is being processed. `beforeImport(name, locals)`, `afterImport()` : A module with the given name is being imported. `beforeFunctional(code, lists, locals)`, `afterFunctional(result)` : A functional markup is with the given code and argument lists (of EmPy code) is being processed. `beforeEvaluate(expression, locals, write)`, `afterEvaluate(result)` : An evaluation markup is being processed with the given code and a Boolean indicating whether or not the results are being written directly to the output stream or returned. `beforeExecute(statements, locals)`, `afterExecute()` : A statement markup is being processed. `beforeSingle(source, locals)`, `afterSingle(result)` : A "single" source (either an expression or a statement) is being compiled and processed. `beforeFinalizer(final)`, `afterFinalizer()` : The given finalizer is being processed. If the `beforeFinalizer` hook returns true for a particular finalizer, then that finalizer will not be called. :::{seealso} The list of hook methods is available in the `hooks` help topic and is summarized [here](HELP.md#hook-methods-summary). ::: ## Customization The behavior of an EmPy system can be customized in various ways. ### Command line options EmPy uses a standard GNU-style command line options processor with both short and long options (_e.g._, `-p` or `--prefix`). Short options can be combined into one word, and options can have values either in the next word or in the same word separated by an `=`. An option consisting of only `--` indicates that no further option processing should be performed. EmPy supports the following options: `-V/--version` : Print version information exit. Repeat the option for more details (see below). `-W/--info` : Print additional information, including the operating system, Python implementation and Python version number. `-Z/--details` : Print all additional details about the running environment, including interpreter, system, platform, and operating system release details. `-h/--help` : Print basic help and exit. Repeat the option for more extensive help. Specifying `-h` once is equivalent to `-H default`; twice to `-H more`, and three or more times to `-H all` (see below). `-H/--topics=TOPICS` : Print extended help by topic(s). Topics are a comma-separated list of the following choices: {#help-topics-table} | Topic | Description | | --- | --- | | `usage` | Basic command line usage | | `options` | Command line options | | `simple` | Simple (one-letter) command line options (why not) | | `markup` | Markup syntax | | `escapes` | Escape sequences | | `environ` | Environment variables | | `pseudo` | Pseudomodule attributes and functions | | `variables` | Configuration variable attributes | | `methods` | Configuration methods | | `hook` | Hook methods | | `named` | Named escapes (control codes) | | `diacritics` | Diacritic combiners | | `icons` | Icons | | `emojis` | User-specified emojis (optional) | | `hints` | Usage hints | | `topics` | This list of topics | | `default` | `usage,options,markup,hints` and `topics` | | `more` | `usage,options,markup,escapes,environ,hints` and `topics` | | `all` | `usage,options,markup,escapes,environ,pseudo,config,controls,diacritics,icons,hints` | As a special case, `-H` with no topic argument is treated as `-H all` rather than error. `-v/--verbose` : The EmPy system will print debugging information to `sys.stderr` as it is doing its processing. {#prefix} `-p/--prefix=CHAR` (_environment variable:_ `EMPY_PREFIX`, _configuration variable:_ `prefix`) : Specify the desired EmPy prefix. It must consist of a single Unicode code point (or character). To specify no prefix (see below), provide an empty string, the string `None` or `none`, or set the `prefix` configuration variable to `None`. Defaults to `@`. `--no-prefix` : Specify that EmPy use no prefix. In this mode, will only process text and perform no markup expansion. This is equivalent to specifying `-p ''`, or setting the `prefix` configuration variable to `None`. `-q/--no-output` : Use a null file for the output file. This will result in no output at all. `-m/--pseudomodule=NAME` (_environment variable:_ `EMPY_PSEUDO`, _configuration variable:_ `pseudomoduleName`) : Specify the name of the EmPy pseudomodule/interpreter. Defaults to `empy`. `-f/--flatten` (_environment variable:_ `EMPY_FLATTEN`, _configuration variable:_ `doFlatten = True`) : Before processing, move the contents of the `empy` pseudomodule into the globals, just as if `empy.flattenGlobals()` were executed immediately after starting the interpreter. This is the equivalent of executing `from empy import *` (though since the pseudomodule is not a real module that statement is invalid). _e.g._, `empy.include` can be referred to simply as `include` when this flag is specified on the command line. `-k/--keep-going` (_configuration variable:_ `exitOnError = False`) : Don't exit immediately when an error occurs. Execute the error handler but continue processing EmPy tokens. `-e/--ignore-errors` (_configuration variable:_ `ignoreErrors = True`) : Ignore errors completely. No error dispatcher or handler is executed and token processing continues indefinitely. Implies `-k/--keep-going`. `-r/--raw-errors` (_environment variable:_ `EMPY_RAW_ERRORS`, _configuration variable:_ `rawErrors = True`) : After logging an EmPy error, show the full Python traceback that caused it. Useful for debugging. `-s/--brief-errors` (_configuration variable:_ `verboseErrors = False`) : When printing an EmPy error, show only its arguments and not its keyword arguments. This is in contrast to the default (verbose) where keyword arguments are shown. `--verbose-errors` (_configuration variable:_ `verboseErrors = True`) : When printing an EmPy error, show both its arguments and its (sorted) keyword arguments. This is the default. `-i/--interactive` (_environment variable:_ `EMPY_INTERACTIVE`, _configuration variable:_ `goInteractive = True`) : Enter interactive mode after processing is complete by continuing to process EmPy markup from the input file, which is by default `sys.stdin`); this can be changed with the `input` interpreter attribute. This is helpful for inspecting the state of the interpreter after processing. `-d/--delete-on-error` (_environment variable:_ `EMPY_DELETE_ON_ERROR`, _configuration variable:_ `deleteOnError`) : If an error occurs, delete the output file; requires the use of the one of the output options such as `-o/--output=FILENAME`. This is useful when running EmPy under a build systemn such as GNU Make. If this option is not selected and an error occurs, the output file will stop when the error is encountered. `-n/--no-proxy` (_environment variable:_ `EMPY_NO_PROXY`, _configuration variable:_ `useProxy`) : Do not install a proxy in `sys.stdout`. This will make EmPy thread safe but writing to `sys.stdout` will not be captured or processed in any way. `--config=STATEMENTS` : Perform the given configuration variable assignments. This option can be specified multiple times. `-c/--config-file=FILENAME` (_environment variable:_ `EMPY_CONFIG`) : Read and process the given configuration file(s), separated by the platform-specific path delimiter (`;` on Windows, `:` on other operating systems). This option can be specified multiple times. `--config-variable=NAME` (_configuration variable:_ `configVariableName`) : Specify the variable name corresponding to the current configuration when configuration files are processed. Defaults to `_`. `-C/--ignore-missing-config` (_configuration variable:_ `missingConfigIsError = False`) : Ignore missing files while reading and processing configurations. By default, a missing file is an error. `-o/--output=FILENAME` : Specify the file to write output to. If this argument is not used, final output is written to the underlying `sys.stdout`. `-a/--append=FILENAME` : Specify the file to append output to. If this argument is not used, final output is appended to the underlying `sys.stdout`. `-O/--output-binary=FILENAME` : Specify the file to write output to and open it as binary. `-A/--append-binary=FILENAME` : Specify the file to append output to and open it as binary. `--output-mode=MODE` : Specify the output mode to use. `--input-mode=MODE` : Specify the input mode to use. Defaults to `'r'`. `-b/--buffering` (_environment variable:_ `EMPY_BUFFERING`, _configuration variable:_ `buffering`) : Specify the buffering to use. Use an integer to specify the maximum number of bytes to read per block or one of the following string values: {#buffering-names-table} | Name | Value | Description | | --- | --- | --- | | `full` | -1 | Use full buffering | | `none` | 0 | Use no buffering | | `line` | 1 | Use line buffering | | `default` | 16384 | Default buffering | If the choice of buffering is incompatible with other settings, a `ConfigurationError` is raised. This option has no effect on interactive mode, as `sys.stdin` is already open. Defaults to 16384. `--default-buffering` : Use default buffering. `-N/--no-buffering` : Use no buffering. `-L/--line-buffering` : Use line buffering. `-B/--full-buffering` : Use full buffering. {#import} `-I/--import=MODULES` : Import the given Python (not EmPy) module(s) into the interpreter globals before main document processing begins. To specify more than one module to import, separate the module names with commas or use multiple `-I/--import=MODULES` options. Variations on the Python `import` statement can be expressed with the following arguments **shortcuts**: {#import-shortcuts-table} | Argument shortcut patterns | Python equivalent | | --- | --- | | `X` | `import X` | | `X as Y` | `import X as Y` | | `X=Y` | `import X as Y` | | `X:Y` | `from X import Y` | | `X:Y as Z` | `from X import Y as Z` | | `X:Y=Z` | `from X import Y as Z` | | `X,Y` | `import X, Y` | For convenience, any `+` character in the argument is replaced with a space. `-D/--define=DEFN` : Define the given variable into the interpreter globals before main document processing begins. This is executed as a Python assignment statement (`variable = ...`); if it does not contain a `=` character, then the variable is defined in the globals with the value `None`. `-S/--string=STR` : Define the given string variable into the interpreter globals before main document processing begins. The value is always treated as a string and never evaluated; if it does not contain a `=` character, then the variable is defined as the empty string (`''`). `-P/--preprocess=FILENAME` : Process the given EmPy (not Python) file before main document processing begins. `-Q/--postprocess=FILENAME` : Process the given EmPy (not Python) file after main document processing begins. `-E/--execute=STATEMENT` : Execute the given arbitrary Python (not EmPy) statement before main document processing begins. `-K/--postexecute=STATEMENT` : Execute the given arbitrary Python (not EmPy) statement after main document processing begins. `-F/--file=FILENAME` : Execute the given Python (not EmPy) file before main document processing begins. `-G/--postfile=FILENAME` : Execute the given Python (not EmPy) file after main document processing begins. `-X/--expand=MARKUP` : Expand the given arbitrary EmPy (not Python) markup before main document processing begins. `-Y/--postexpand=MARKUP` : Expand the given arbitrary EmPy (not Python) markup after main document processing begins. `--preinitializer=FILENAME` : Execute the given Python file locally just before creating the main interpreter. Used for tests. `--postinitializer=FILENAME` : Execute the given Python file locally just after shutting edown the main interpreter. Used for tests. `-w/--pause-at-end` (_configuration variable:_ `pauseAtEnd`) : Prompt for a line of input after all processing is complete. Useful for systems where the window running EmPy would automatically disappear after EmPy exits (_e.g._, Windows). By default, the input file used is `sys.stdin`, so this will not work when redirecting stdin to an EmPy process. This can be changed with the `input` interpreter attribute. `-l/--relative-path` (_configuration variable:_ `relativePath`) : Prepend the location of the EmPy script to Python's `sys.path`. This is useful when the EmPy scripts themselves import Python .py modules in that same directory. `--replace-newlines` (_configuration variable:_ `replaceNewlines = True`) : Replace newlines in (Python) expressions before evaluation. `--no-replace-newlines` (_configuration variable:_ `replaceNewlines = False`) : Don't replace newlines in (Python) expressions before evaluations. This is the default. `--ignore-bangpaths` (_configuration variable:_ `ignoreBangpaths = True`) : Treat bangpaths as comments. By default, bangpaths (starting lines that begin with the characters `#!`) are treated as comments and ignored. `--no-ignore-bangpaths` (_configuration variable:_ `ignoreBangpaths = False`) : Do not treat bangpaths as comments. This is the opposite of the default. `--none-symbol` (_configuration variable:_ `noneSymbol`) : The string to write when expanding the value `None`. Defaults to `None`, which will result in no output. `--no-none-symbol` : Do not write any preset string when expanding `None`; equivalent to setting `noneSymbol` to `None`. `--expand-user` (_configuration variable:_ `expandUserConstructions = True`) : Expand user constructions (`~user`) in configuration file pathnames. This is the default. `--no-expand-user` (_configuration variable:_ `expandUserConstructions = False`) : Do not expand user constructions (`~user`) in configuration file pathnames. By default they are expanded. `--auto-validate-icons` (_configuration variable:_ `autoValidateIcons = True`) : Auto-validate icons when an icon markup is first used. This is the default. See below. `--no-auto-validate-icons` (_configuration variable:_ `autoValidateIcons = False`) : Do not auto-validate icons when an icon markup is first used. See below. `--starting-line` (_configuration variable:_ `startingLine`) : Specify an integer representing the default starting line for contexts. Default is 1. `--starting-column` (_configuration variable:_ `startingColumn`) : Specify an integer representing the default starting column for contexts. Default is 1. `--emoji-modules` (_configuration variable:_ `emojiModuleNames`) : A comma-separated list of emoji modules to try to use for the emoji markup (`@:...:`). See below. Defaults to `emoji,emojis,emoji_data_python,unicodedata`. `--no-emoji-modules` : Only use `unicodedata` as an emoji module; disable all the third-party emoji modules. `--disable-emoji-modules` : Disable all emoji module usage; just rely on the `emojis` attribute of the configuration. See below. `--ignore-emoji-not-found` (_configuration variable:_ `emojiNotFoundIsError = False`) : When using emoji markup (`@:...:`), do not raise an error when an emoji is not found; just pass the `:...:` text through. `-u/--binary/--unicode` (_environment variable:_ `EMPY_BINARY`, _configuration variable:_ `useBinary`) : Operate in binary mode; open files in binary mode and use the `codecs` module for Unicode support. This is necessary in older versions of Python 2._x_. `-x/--encoding=E` : Specify both input and output Unicode encodings. Requires specifying both an input and an output file. `--input-encoding=E` (_environment variable:_ `EMPY_INPUT_ENCODING`, _configuration variable:_ `inputEncoding`) : Specify the input Unicode encoding. Requires specifying an input file rather than `sys.stdout`. :::{note} Specifying a non-default encoding when using interactive mode (`sys.stdin`) raises a `ConfigurationError`. ::: `--output-encoding=E` (_environment variable:_ `EMPY_OUTPUT_ENCODING`, _configuration variable:_ `outputEncoding`) : Specify the output Unicode encoding. Requires specifying an output file rather than `sys.stdout`. :::{note} Specifying a non-default encoding when using `sys.stdout` raises a `ConfigurationError`. ::: `-y/--errors=E` : Specify both [input and output Unicode error handlers](https://docs.python.org/3/library/functions.html#open). `--input-errors=E` (_environment variable:_ `EMPY_INPUT_ERRORS`, _configuration variable:_ `inputErrors`) : Specify the [input Unicode error handler](https://docs.python.org/3/library/functions.html#open). :::{note} Specifying a non-default error handler when using interactive mode (`sys.stdin`) raises a `ConfigurationError`. ::: `--output-errors=E` (_environment variable:_ `EMPY_OUTPUT_ERRORS`, _configuration variable:_ `outputErrors`) : Specify the [output Unicode error handler](https://docs.python.org/3/library/functions.html#open). :::{note} Specifying a non-default error handler when using `sys.stdout` raises a `ConfigurationError`. ::: `-z/--normalization-form=F` (_configuration variable:_ `normalizationForm`) : Specify the Unicode normalization to perform when using the diacritics markup (`@^...`). Specify an empty string (`''`) to skip normalization. Defaults to `NFKC` for modern versions of Python and `''` for very old versions of Python 2._x_. `--auto-play-diversions` (_configuration variable:_ `autoPlayDiversions = True`) : Before exiting, automatically play back any remaining diversions. This is the default. `--no-auto-play-diversions` (_configuration variable:_ `autoPlayDiversions = False`) : Before exiting, do not automatically play back any remaining diversions. By default such diversions are played back. `--check-variables` (_configuration variable:_ `checkVariables = True`) : When modifying configuration variables, by default the existence and proper type of these variables is checked; anomalies will raise a `ConfigurationError`. This is the default. `--no-check-variables` (_configuration variable:_ `checkVariables = False`) : When modifying configuration variables, normally the existence and types of these variables is checked and if it doesn't exist or it is attempting to be assigned to an incompatible type, it will raise a `ConfigurationError`. To override this behavior, use this flag. `--path-separator` (_configuration variable:_ `pathSeparator`) : The path separator delimiter for specifying configuration paths. Defaults to `;` on Windows and `:` on all other platforms. `--enable-modules` (_configuration variable:_ `supportModules = True`) : Enable EmPy module support (Python 3.4 and up). The default. `-g/--disable-modules` (_configuration variable:_ `supportModules = False`) : Disable EmPy module support. `--module-extension` (_configuration variable:_ `moduleExtension`) : The filename extension for EmPy modules. Defaults to `.em`. `--module-finder-index` (_configuration variable:_ `moduleFinderIndex`) : When installing the module finder, which allows EmPy module support, use this index as the position in the meta path to insert it. Zero means that it will be inserted into the front of the list, one means the second, etc. Negative values means that it will appended. Defaults to zero. `--enable-import-output` (_configuration variable:_ `enableImportOutput = True`) : Output from imported EmPy modules is allowed through. The default. `-j/--disable-import-output` (_configuration variable:_ `enableImportOutput = False`) : Output from imported EmPy modules is suppressed. `--context-format` (_configuration variable:_ `contextFormat`) : Specify the format for printing contexts. See below. `--success-code=N` (_configuration variable:_ `successCode`) : Specify the exit code for the Python interpreter on success. Defaults to 0. `--failure-code=N` (_configuration variable:_ `failureCode`) : Specify the exit code for the Python interpreter when a processing error occurs. Defaults to 1. `--unknown-code=N` (_configuration variable:_ `unknownCode`) : Specify the exit code for the Python interpreter when an invalid configuration (such as unknown command line options) is encountered. Defaults to 2. :::{seealso} The list of command line options is available in the `options` help topic and is summarized [here](HELP.md#command-line-options-summary). ::: ### Environment variables The following environment variables are supported: `EMPY_OPTIONS` : Specify additional command line options to be used. These are in effect added to the start of the command line and parsed before any explicit command line options and processing begins. For example, this will run the EmPy interpreter as if the `-r` and `-d` command line options were specified: 
% export EMPY_OPTIONS='-r -d'; em.py ...
`EMPY_CONFIG` (_command line option:_ `-c/--config-file=FILENAME`) : Specify the configuration file(s) to process before main document processing begins. `EMPY_PREFIX` (_command line option:_ `-p/--prefix=CHAR`, _configuration variable:_ `prefix`) : Specify the prefix to use when processing. `EMPY_PSEUDO` (_command line option:_ `-m/--pseudomodule=NAME`, _configuration variable:_ `pseudomoduleName`) : Specify the name of the pseudomodule/interpreter to use when processing. `EMPY_FLATTEN` (_command line option:_ `-f/--flatten`, _configuration variable:_ `doFlatten = True`) : If defined, flatten the globals before processing. `EMPY_RAW_ERRORS` (_command line option:_ `-r/--raw-errors`, _configuration variable:_ `rawErrors = True`) : If defined, after an error occurs, show the full Python tracebacks of the exception. `EMPY_INTERACTIVE` (_command line option:_ `-i/--interactive`, _configuration variable:_ `goInteractive = True`) : If defined, enter interactive mode by processing markup from `sys.stdin` after main document processing is complete. `EMPY_DELETE_ON_ERROR` (_command line option:_ `-d/--delete-on-error`, _configuration variable:_ `deleteOnError`) : If defined, when an error occurs, delete the corresponding output file. `EMPY_NO_PROXY` (_command line option:_ `-n/--no-proxy`, _configuration variable:_ `useProxy`) : If defined, do not install a `sys.stdout` proxy. `EMPY_BUFFERING` (_command line option:_ `-b/--buffering`, _configuration variable:_ `buffering`) : Specify the desired file buffering. `EMPY_BINARY` (_command line option:_ `-u/--binary/--unicode`, _configuration variable:_ `useBinary`) : If defined, use binary mode. `EMPY_ENCODING` : Specify the desired input and output Unicode encodings. `EMPY_INPUT_ENCODING` (_command line option:_ `--input-encoding=E`, _configuration variable:_ `inputEncoding`) : Specify the desired input Unicode encoding only. `EMPY_OUTPUT_ENCODING` (_command line option:_ `--output-encoding=E`, _configuration variable:_ `outputEncoding`) : Specify the desired output Unicode encoding only. `EMPY_ERRORS` : Specify the desired input and output Unicode error handler. `EMPY_INPUT_ERRORS` (_command line option:_ `--input-errors=E`, _configuration variable:_ `inputErrors`) : Specify the desired input Unicode error handler. `EMPY_OUTPUT_ERRORS` (_command line option:_ `--output-errors=E`, _configuration variable:_ `outputErrors`) : Specify the desired output Unicode error handler. :::{seealso} The list of environment variables is available in the `environ` help topic and is summarized [here](HELP.md#environment-variables-summary). ::: :::{versionadded} 2.2 Environment variables were first introduced in EmPy version 2.2, and revamped in version 4.0. ::: ### Configuration **Configurations** are objects which determine the behavior of an EmPy interpreter. They can be created with an instance of the `Configuration` class and have a set of attributes (**configuration variables**) which can be modified. Most configuration variables correspond to a command line option. The configuration instance also contains supporting methods which are used by the interpreter which can be overridden. When configuration variables are modified, they are by default checked to make sure have a known name and that they have the correct type; if not, a `ConfigurationError` will be raised. This behavior can be disabled with `--no-check-variables` (_configuration variable:_ `checkVariables = False`). When a configuration is assigned to an interpreter, it exists as a `config` attribute of the `empy` pseudomodule and can be modified by a running EmPy system. Configurations can be shared between multiple interpreters if desired. :::{admonition} Example 65: Configuration instances _Source_: ⌨️
`````` @{ empy.config.prefix = '$' }$ ${ print("The EmPy prefix is now $, not @!") }$ ``````
_Output_: 🖥️
`````` The EmPy prefix is now $, not @! ``````
::: :::{tip} This example shows a quirk of changing configurations in the middle of processing an EmPy document; the prefix changes from a `@` to a `$` by the end of the first statement markup, so a `$` and a newline is required to suppress the trailing newline; a `@` would have been sent to the output unchanged since it is no longer the prefix. Use [command line options](#command-line-options), [environment variables](#environment-variables) or [configuration files](#configuration-files) to avoid issues like this, as they are processed before any EmPy document. For changing the prefix, use `-p/--prefix=CHAR` (_environment variable:_ `EMPY_PREFIX`, _configuration variable:_ `prefix`). ::: #### Configuration files **Configuration files** are snippets of Python (not EmPy) code which can be executed under an EmPy system to modify the current configuration. By convention they have the extension .conf. though this is not a requirement. Configuration files are processed before any expansion begins and are specified with the `-c/--config-file=FILENAME` (_environment variable:_ `EMPY_CONFIG`) command line option; a list of configuration files can be specified with a `:` delimiter (`;` on Windows); the delimiter can be specified with `--path-separator` (_configuration variable:_ `pathSeparator`). A nonexistent configuration file specified in this way is an error unless `-C/--ignore-missing-config` (_configuration variable:_ `missingConfigIsError = False`) is specified. When a configuration file is processed, its contents are executed in a Python (not EmPy) interpreter and then any resulting variable assignments are assigned to the configuration instance. So: ``````python prefix = '$' `````` is a simple configuration file which will change the EmPy prefix to `$`. Any resulting variable beginning with an underscore will be ignored. Thus these variables can be used as auxiliary variables in the configuration file. For example, this configuration file will define custom emojis for the numbered keycaps: ``````python emojis = {} for _x in range(10): emojis[str(_x)] = '{}\ufe0f\u20e3'.format(_x) `````` Finally, when a configuration file is processed, the current configuration instance is presented as a variable named `_` (this can be changed with `--config-variable=NAME` (_configuration variable:_ `configVariableName`)). The following example does the same as the previous example but uses the dedicated variable: ``````python _.emojis.update(((str(_x), '{}\ufe0f\u20e3'.format(_x)) for _x in range(10))) `````` :::{tip} To make a set of configuration files automatic loaded by EmPy, use the `EMPY_CONFIG` environment variable in your startup shell: 
% export EMPY_CONFIG=~/path/to/default.conf
To make a more general set of _options_ available, set `EMPY_OPTIONS`. ::: #### Configuration variables The following configuration variables (attributes of a `Configuration` object) exist with the given types and their corresponding command line options and environment variables. Default values are shown after a `=` sign. When a corresponding command line option exists, See [](#command-line-options) for more detailed information. `name: str = 'default'` : The name of this configuration. It is for organizational purposes and is not used directly by the EmPy system. `notes = None` : Arbitrary data about this configuration. It can be anything from an integer to a string to a dictionary to a class instance, or its default, `None`. It is for organizational purposes and is not used directly by the EmPy system. `prefix: str = '@'` (_command line option:_ `-p/--prefix=CHAR`, _environment variable:_ `EMPY_PREFIX`) : The prefix the interpreter is using to delimit EmPy markup. Must be a single Unicode code point (character). `pseudomoduleName: str = 'empy'` (_command line option:_ `-m/--pseudomodule=NAME`, _environment variable:_ `EMPY_PSEUDO`) : The name of the pseudomodule for this interpreter. `verbose: bool = False` : If true, print debugging information before processing each EmPy token. `rawErrors: bool = False` (_command line option:_ `-r/--raw-errors`, _environment variable:_ `EMPY_RAW_ERRORS`) : If true, print a Python traceback for every exception that is thrown. `exitOnError: bool = True` (_command line option:_ `-k/--keep-going`) : If true, exit the EmPy interpreter after an error occurs. If false, processing will continue despite the error. `ignoreErrors: bool = False` (_command line option:_ `-e/--ignore-errors`) : If true, all errors are ignored by the EmPy interpreter. Setting this to true also implies `exitOnError` is false. `contextFormat: str = '%(name)s:%(line)d:%(column)d'` (_command line option:_ `--context-format`) : The string format to use to render contexts. EmPy will automatically determine whether or not it should use the `%` operator or the `str.format` method with this format. See [](#context-formatting) for more details. `goInteractive: bool = False` (_command line option:_ `-i/--interactive`, _environment variable:_ `EMPY_INTERACTIVE`) : When done processing the main EmPy document (if any), go into interactive mode by running a REPL loop with `sys.stdin`. If such document is specified (_i.e._, EmPy is invoked with no arguments), go into interactive mode as well. `deleteOnError: bool = False` (_command line option:_ `-d/--delete-on-error`, _environment variable:_ `EMPY_DELETE_ON_ERROR`) : If an output file is chosen (_e.g._, with `-o/--output=FILENAME` or one of the other such options) and an error occurs, delete the output file. If this is set to true with output set to `sys.stdout`, a ConfigurationError will be raised. `doFlatten: bool = False` (_command line option:_ `-f/--flatten`, _environment variable:_ `EMPY_FLATTEN`) : Flatten the contents of the `empy` pseudomodule into the globals rather than having them all under the pseudomodule name. `useProxy: bool = True` (_command line option:_ `-n/--no-proxy`, _environment variable:_ `EMPY_NO_PROXY`) : If true, install a proxy object for `sys.stdout`. This should be true if any output is being done via `print` or `sys.stdout.write`. `relativePath: bool = False` (_command line option:_ `-l/--relative-path`) : If true, the directory of the EmPy script's path will be prepended to Python's `sys.path`. `buffering: int = 16384` (_command line option:_ `-b/--buffering`, _environment variable:_ `EMPY_BUFFERING`) : Specify the buffering for the input and output files. `replaceNewlines: bool = False` (_command line option:_ `--no-replace-newlines`) : If true, newlines in emoji names, Unicode character name escape markup, and code evaluation will be changed to spaces. This can help when writing EmPy with a word-wrapping editor. `ignoreBangpaths: bool = True` (_command line option:_ `--no-ignore-bangpaths`) : If true, a bangpath (the first line of a file which starts with `#!`) will be treated as an EmPy comment, allowing the creation of EmPy executable scripts. If false, it will not be treated specially and will be rendered to the output. `noneSymbol: str = None` (_command line option:_ `--none-symbol`) : When an EmPy expansion evaluates to None (_e.g._, `@(None)`), this is the string that will be rendered to the output stream. If set to `None` (the default), no output will be rendered. `missingConfigIsError: bool = True` (_command line option:_ `-C/--ignore-missing-config`) : If a configuration file is specified with `-c/--config-file=FILENAME` but does not exist, if this variable is true an error will be raised. `pauseAtEnd: bool = False` (_command line option:_ `-w/--pause-at-end`) : When done processing EmPy files, read a line from `sys.stdin` before exiting the interpreter. This can be useful when testing under consoles on Windows. `startingLine: int = 1` (_command line option:_ `--starting-line`) : The line to start with in contexts. `startingColumn: int = 1` (_command line option:_ `--starting-column`) : The column to start with in contexts. `significatorDelimiters: tuple = ('__', '__')` : A 2-tuple of strings representing the prefix and suffix to add to significator names in order to determine what name to give them in the globals. `emptySignificator: object = None` : The default value to use for non-stringized significators. `autoValidateIcons: bool = True` (_command line option:_ `--no-auto-validate-icons`) : When icons are used with a custom dictionary, a preprocessing phase needs to be done to make sure that all icon starting substrings are marked in the `icons` dictionary. If this variable is false, this extra processing step will not be done; this is provided if the user wants to specify their own properly-validated icons dictionary and wishes to avoid a redundant step. `emojiModuleNames: list[str] = ['emoji', 'emojis', 'emoji_data_python', 'unicodedata']` (_command line option:_ `--emoji-modules`) : The list of names of supported emoji modules that the EmPy system will attempt t use at startup. `emojiNotFoundIsError: bool = True` (_command line option:_ `--ignore-emoji-not-found`) : If true, a non-existing emoji is an error. `useBinary: bool = False` (_command line option:_ `-u/--binary/--unicode`, _environment variable:_ `EMPY_BINARY`) : If true, open files in binary mode. `inputEncoding: str = 'utf-8'` (_command line option:_ `--input-encoding=E`, _environment variable:_ `EMPY_INPUT_ENCODING`) : The file input encoding to use. This needs to be set before files are opened to take effect. `outputEncoding: str = 'utf-8'` (_command line option:_ `--output-encoding=E`, _environment variable:_ `EMPY_OUTPUT_ENCODING`) : The file output encoding to use. This needs to be set before files are opened to take effect. `inputErrors: str = 'strict'` (_command line option:_ `--input-errors=E`, _environment variable:_ `EMPY_INPUT_ERRORS`) : the file input error handler to use. This needs to be set before files are opened to take effect. `outputErrors: str = 'strict'` (_command line option:_ `--output-errors=E`, _environment variable:_ `EMPY_OUTPUT_ERRORS`) : The file output error handler to use. This needs to be set before files are opened to take effect. `normalizationForm: str = 'NFKC'` (_command line option:_ `-z/--normalization-form=F`) : The normalization form to use when applying diacritic combiners. Set to `None` or `''` in order to skip normalization. `autoPlayDiversions: bool = True` (_command line option:_ `--no-auto-play-diversions`) : If diversions are extant when an interpreter is ready to exist, if this variable is true then those diversions will be undiverted to the output stream in lexicographical order by name. `expandUserConstructions: bool = True` (_command line option:_ `--no-expand-user`) : If true, when processing configuration files, call `os.path.expanduser` on each filename to expand `~` and `~user` constructions. `configVariableName: str = '_'` (_command line option:_ `--config-variable=NAME`) : When processing configuration files, the existing configuration object can be referenced as a variable. This indicates its name. `successCode: int = 0` (_command line option:_ `--success-code=N`) : The exit code to return when a processing is successful. `failureCode: int = 1` (_command line option:_ `--failure-code=N`) : The exit code to return when an error occurs during processing. `unknownCode: int = 2` (_command line option:_ `--unknown-code=N`) : The exit code to return when a configuration error is found (and processing never starts). `checkVariables: bool = True` (_command line option:_ `--no-check-variables`) : If true, configuration variables will be checked to make sure they are known variables and have the proper type on assignment. `pathSeparator: str = ';'` (Windows) or `':'` (others) ` ` (_command line option:_ `--path-separator`) : The path separator to use when specifying multiple filenames with `-c/--config-file=FILENAME`. Defaults to `;` on Windows and `:` on other platforms. `supportModules: bool = True` (_command line option:_ `-g/--disable-modules`) : Enable EmPy module support? Requires Python 3.4 or greater. `moduleExtension: str = '.em'` (_command line option:_ `--module-extension`) : The filename extension to use for modules. `moduleFinderIndex: int = 0` (_command line option:_ `--module-finder-index`) : The integer index where to insert the module finder (required for module support) into the meta path. 0 would insert the finder into the beginning of the meta path (so it is checked before any other finder, such as the native Python module finder), 1 would place it in the second position, etc. A negative index indicates that the finder should be appended to the meta path, so that it is checked last. `enableImportOutput: bool = True` (_command line option:_ `-j/--disable-import-output`) : By default output is handled normally when a module is imported; any markup expanded that renders output in a module will be sent to the output stream. This is sometimes undesirable, so this can be disabled by setting this configuration variable to false. `duplicativeFirsts: list[str] = ['(', '[', '{']` : The list of first markup characters that may be duplicated to indicate variants. For instance, `@(...)` is expression markup, but `@((...))` is parenthesis extension markup. `openFunc = None` : The file open function to use. If `None`, defaults to either `codecs.open` or `open`, depending on Python version. `controls: dict = {...}` : The controls dictionary used by the [named escape markup](#named-escape-markup). `diacritics: dict = {...}` : The diacritic combiners dictionary used by the [diacritic markup](#diacritic-markup). `icons: dict = {...}` : The icons dictionary used by the [icon markup](#icon-markup). `emojis: dict = {...}` : The custom emojis dictionary which is referenced first by the [emoji markup](#emoji-markup). Defaults to an empty dictionary. :::{seealso} The list of configuration variables is available in the `variables` help topic and is summarized [here](HELP.md#configuration-variables-summary). ::: :::{versionadded} 4.0 Configuration objects were introduced in EmPy version 4.0; previously an underused options dictionary was introduced in version 2.2.2. ::: #### Configuration methods The following methods are supported by configuration instances: `__init__(**kwargs)` : The constructor. Takes a set of keyword arguments that are then set as attributes in the configuration instance. So ```python config = em.Configuration(prefix='$') ``` is a shorter form of ```python config = em.Configuration() config.prefix = '$' ``` `isInitialized() -> bool` : Has this instance been initialized? Before initialization, no typechecking is done even if `checkVariables` is set. `check(inputFilename: str, outputFilename: str)` : Check the file settings against these filenames and raise a `ConfigurationError` is there appears to be an inconsistency. `has(name: str) -> bool` : Is this name an existing configuration variable? `get(name: str, [default: object]) -> bool` : Get the value of this configuration variable or return this default if it does not exist. `set(name: str, value: object)` : Set the configuration variable to the given value. `update(**kwargs)` : Set a series of configuration variables via a set of keyword arguments. `clone(deep: bool = False) -> Configuration` : Clone this configuration and return it. If `deep` is true, make it a deep copy. `run(statements: str)` : Execute a series of configuration commands. `load(filename: str, [required: bool])` : Load and execute a configuration file. If `required` is true, raise an exception; if false, ignore; if `None`, use the default for this configuration. `path(path: str, [required: bool])` : Load and execute one or more configuration files separated by the path separator. `required` argument is the same as for `load` above. `hasEnvironment(name: str) -> bool` : Is the given environment variable defined, regardless of its value? `environment(name: str, [default: str, blank: str])` : Get the value of the environment variable. If it is not defined, return `default`; if it is defined but is empty, return `blank`. `hasDefaultPrefix() -> bool` : Is the `prefix` configuration variable set to the default? `has{Full|No|Line|Fixed}Buffering() -> bool` : Is buffering set to full, none, line, or some fixed value, respectively? `createFactory([tokens: Sequence[Token]]) -> Factory` : Create a token factory from the list of token classes and return it. If `tokens` is not specified, use the default list. `adjustFactory()` : Adjust an existing factory to take into account a non-default prefix. `getFactory([tokens: Sequence[Token], [force: bool]])` : Get a factory, creating one if one has not yet been created, with the given `tokens` list (if not specified, a default list will be used). If `force` is true, then create a new one even if one already exists. `resetFactory()` : Clear the current factory, if any. `createExtensionToken(first: str, name: str, [last: str])` : Create a new extension token class with the first character `first` and with method name `name`. If `last` is specified, use that as the last character; otherwise, guess for a closed form with a default of `first`. `hasBinary() -> bool` : Is binary (formerly called Unicode) support enabled? `enableBinary([major: int, minor: int])` : Enable binary support, conditionally if `major` and `minor` (the major and minor versions of Python) are specified and binary support is needed for this version of Python. `disableBinary()` : Turn off binary/Unicode support. `isDefaultEncodingErrors([encoding: str, errors: str, asInput: bool]) -> bool` : Are both the file encoding and file error handler the default? Check for input if `asInput` is true, otherwise check for output. `getDefaultEncoding([default: str]) -> str` : Get the current default encoding, overriding with `default` if desired. `open(filename: str, mode: Optional[str] = None, buffering: int = -1, [encoding: Optional[str], errors: Optional[str], expand: bool]) -> file` : The main wrapper around the `open`/`codecs.open` call, allowing for seamless file opening in both binary and non-binary mode across all supported Python versions. `significatorReString() -> str` : Return a regular expression string that will match significators in EmPy code with this configuration's prefix. :::{hint} It can be used in Python like this: ```python data = open('script.em', 'r').read() for result in empy.config.significatorRe().findall(data): string2, key2, value2, string1, key1, value1 = result if key1: print("Single line significator: {} = {}{}".format( key1, value1, ' (stringized)' if string1 else '')) else: # key2 print("Multi-line significator: {} = {}{}".format( key2, value2, ' (stringized)' if string2 else '')) ``` ::: `significatorRe([flags: int]) -> re.Pattern` : Return a compiled regular expression pattern object for this configuration's prefix. Override the `re` `flags` if desired. `significatorFor(key: str) -> str` : Return the significator variable name for this significator key. `setContextFormat(rawFormat: str)` : Set the context format for this configuration. See [context formatting](#context-formatting). `renderContext(context) -> str` : Render the given context using the existing context format string. `calculateIconsSignature() -> tuple` : Calculate the icons signature to try to detect any accidental changes. `signIcons()` : Calculate the icons signature and update the configuration with it. `transmogrifyIcons([icons: dict])` : Process the icons dictionary and make sure any keys' prefixes are backfilled with `None` values. This is necessary for the functioning of the [icon markup](#icon-markup). This method will be called automatically unless `autoValidateIcons` is false. `validateIcons([icons: dict])` : Check whether the icons have possibly changed and transmogrify them if necessary. `initializeEmojiModules([moduleNames: Sequence])` : Scan for existing emoji modules and set up the appropriate internal data structures. Use the list of module names in the configuration if `moduleNames` is not specified. `substituteEmoji(text: str) -> str` : Perform emoji substitution with the detected emoji modules. `isSuccessCode(code: int) -> bool` : Is this exit code a success code? `isExitError(error: Optional[Error]) -> bool` : Is this exception instance an exit error rather than a real error? `errorToExitCode(error: Optional[Error]) -> int` : Return an appropriate exit code for this error. `isNotAnError(error: Optional[Error]) -> bool` : Does this exception instance not represent an actual error? `formatError(error: Optional[Error][, prefix: str, suffix: str]) -> str` : Return a string representing the details of the given exception instance, with an optional prefix and suffix. :::{seealso} The list of configuration methods is available in the `methods` help topic and is summarized [here](HELP.md#configuration-methods-summary). ::: ### Error handling #### Error dispatchers When an error occurs in an EmPy system, first an **error dispatcher** is invoked. The purpose of the dispatcher is to determine at a high-level what should be done about the error. A dispatcher is a zero-argument callable which primarily determines whether the error should be handled by the running interpreter, whether it should be raise to the parent caller rather than handled by the interpreter, or some other custom behavior. When specified in the [`Interpreter` constructor](#constructor) or one of the high-level interpreter methods (_e.g._, `file` or `string`), it can take on a few special values: {#error-dispatchers-table} | Value | Meaning | Corresponding method | | --- | --- | --- | | `None` | Use interpreter default | -- | | `True` | Interpreter should handle error | `dispatch` | | `False` | Interpreter should reraise error | `reraise` | :::{note} For standalone interpreters and its high-level methods, the default dispatcher is `True` (`dispatch`); that is, the interpeter will handle the error itself. When calling the `expand` interpreter method or the global `expand` function, the dispatcher is `False` (`reraise`); in other words, calls to `expand` will result in any occurring errors being raised to the caller rather than handled by the interpteter. ::: :::{versionadded} 4.0.1 Error dispatchers were introduced in EmPy version 4.0.1. ::: #### Error handlers Once an error is dispatched to the interpteter, it is handled by an **error handler**. An error handler is a callable object that will respond to the error and take any necessary action. If no user-specified error handler is set, the default error handler is used, which prints a formatted EmPy error message to `sys.stderr`. An error handler is a callable object with the following signature: > `handler(type, error, traceback) -> bool` It takes the error type, the error instance, and the traceback object corresponding to an exception (a tuple of which is the return value of `sys.exc_info()`) and returns an optional Boolean. If the return value is true, the default handler will _also_ be invoked after the error handler is called. (Not explicitly returning anything will implicitly return `None`, which is a false value.) The current error that the interpreter has encountered is set in the interpreter's `error` attribute (with `None` indicating no error). The error handler can manually set this attribute to `None` to clear the error if desired. After the error handler(s) have been called, the interpreter will then decide how to resolve the error. If the `error` attribute of the interpreter is still non-`None` and the configuration variable `exitOnError` is true (option: `-k/--keep-going`), the interpreter will exit. If the `error` attribute is `None`, it will continue running. If the `ignoreErrors` configuration variable (option: `-e/--ignore-errors`) is true, then no error dispatchers or error handlers will be called. :::{versionadded} 4.0 Error handlers were introduced in EmPy version 4.0. ::: #### Error classses The following error classes are used by EmPy: {#error-classes-table} | Class | Base class | Meaning | | --- | --- | --- | | `Error` | `Exception` | Base error class | | `ConsistencyError` | `Error` | An error involving inconsistent settings has occurred | | `ProxyError` | `ConsistencyError` | A consistency error involving misuse of the stdout proxy | | `DiversionError` | `Error` | An error involving diversions has occurred | | `FilterError` | `Error` | An error involving filters has occurred | | `CoreError` | `Error` | An error involving cores has occurred | | `ExtensionError` | `Error` | An error involving extensions has occurred | | `StackUnderflowError` | `Error` | A stack has underflowed (internal error) | | `UnknownEmojiError` | `Error` | An unknown emoji was requested | | `StringError` | `Error` | An old-style string error (used internally) | | `InvocationError` | `Error` | An error invoking the interpreter has occurred | | `ConfigurationError` | `Error` | An error involving a bad configuration has occurred | | `CompatibilityError` | `ConfigurationError` | An error involving backward compatibility has occurred | | `ConfigurationFileNotFoundError` | `ConfigurationError` | A requested configuration file was missing | | `ParseError` | `Error` | Invalid EmPy syntax was encountered | | `TransientParseError` | `ParseError` | Invalid EmPy syntax was encountered (but may be resolved by reading further data) | ## Reference The following reference material is available: ### Getting version and debugging information To print the version of EmPy you have installed, run: 
% em.py -V # or: --version
Welcome to EmPy version 4.2.1.
To print additional information including the Python implementation and version, operating system, and machine type, run: 
% em.py -W # or: --info
Welcome to EmPy version 4.2.1, in CPython/3.10.12, on Linux (POSIX), with x86_64, under GCC/11.4.0.
For diagnostic details (say, to report a potential problem to the developer), run: 
% em.py -Z # or: --details
Welcome to EmPy version 4.2.1, in CPython/3.10.12, on Linux (POSIX), with x86_64, under GCC/11.4.0.
Details:
- basic/context: --
- basic/framework/name: GCC
- basic/framework/version: 11.4.0
- basic/implementation: CPython
- basic/machine: x86_64
...
### Examples and testing For quick examples of EmPy code, check out the examples throughout this document. For a more expansive tour of examples illustrating EmPy features, check out tests/sample/sample.em. For a real-world example, check out README.md.em, which is the EmPy source file from which this documentation is generated. EmPy has an extensive testing system. (If you have EmPy installed via an operating system package that does not include the test system and you wish to use it, [download the tarball](#getting-the-software).) EmPy's testing system consists of the shell script test.sh and two directories: tests and suites. The tests directory contains the unit/system tests, and the suites directory contains files with lists of tests to run. The test.sh shell script will run with any modern Bourne-like shell. Tests can be run changing to the directory where test.sh and both the tests and suites directories are located, and then executing `./test.sh` followed by the tests desired to be run following on the command line. For example, this runs a quick test: 
% ./test.sh tests/sample/sample.em
tests/sample/sample.em (python3) [PASS]

PASSES: 1/1
All tests passed (python3) in 0.217 s = 217 ms/test.
Specifying a directory will run all the tests contained in that directory and all its subdirectories: 
% ./test.sh tests/common/trivial
tests/common/trivial/empty.em (python3) [PASS]
tests/common/trivial/long.em (python3) [PASS]
tests/common/trivial/medium.em (python3) [PASS]
tests/common/trivial/short.em (python3) [PASS]
tests/common/trivial/short_no_newline.em (python3) [PASS]

PASSES: 5/5
All tests passed (python3) in 0.400 s = 80 ms/test.
Suites can be run by using the `@` character before the filename. A suite is a list of tests, one per line, to run. Blank lines and lines starting with `#` are ignored: 
% cat suites/default
# Run tests for Python versions from 3.4 up.
tests/common
tests/python2.7
tests/python3.4
tests/python3
tests/sample
% ./test.sh @suites/default
tests/common/callbacks/deregister.em (python3) [PASS]
tests/common/callbacks/get_none.em (python3) [PASS]
tests/common/callbacks/get_one.em (python3) [PASS]
...
PASSES: 566/566
All tests passed (python3).
To test a version of Python other than the default (that is, other than a Python 3._x_ interpreter named `python3`), specify it with the `-p` option to the test script and use that version's test suite. To test CPython 2.7, for instance: 
% ./test.sh -p python2.7 @suites/python2.7
tests/common/callbacks/deregister.em (python2.7) [PASS]
tests/common/callbacks/get_none.em (python2.7) [PASS]
tests/common/callbacks/get_one.em (python2.7) [PASS]
...
Suites for all supported interpreters and versions are provided. For example, if you have PyPy 3.10 installed: 
% ./test.sh -p pypy3.10 @suites/pypy3.10
tests/common/callbacks/deregister.em (pypy3.10) [PASS]
tests/common/callbacks/get_none.em (pypy3.10) [PASS]
tests/common/callbacks/get_one.em (pypy3.10) [PASS]
...
To only report errors ("quiet mode"), use the `-q` option: 
% ./test.sh -q @suites/default
PASSES: 566/566
All tests passed (python3).
For more information about the testing tool, run: 
% ./test.sh -h # or: --help
Usage: ./test.sh [<option>...] [--] (<file> | <directory> | @<suite>)...
Example: ./test.sh -p python3 @suites/python3

Run one or more EmPy tests, comparing the results to exemplars, and
return an exit code indicating whether all tests succeeded or whether
there were some failures.  If no tests are specified, this help is
displayed.  Test filenames, directory names, and suite names cannot
contain spaces.  All tests are run from the current working directory.

...
:::{note} All tests can be run by specifying tests as the test directory (`./test.sh ... tests`) and will automatically skip in the inappropriate tests; however, specifying the version-specific suite (_e.g._, `@suites/python3`) will be more efficient. ::: :::{versionchanged} 4.0 A simple benchmark test system was introduced in EmPy version 2.1, and was expanded to full unit and system test suites for all supported versions of Python in EmPy version 4.0. ::: ### Embedding EmPy EmPy can be easily embedded into your Python programs. Simply ensure that the em.py file is available in the `PYTHONPATH` and import `em` as a module: ```python import em print(em) ``` To embed an interpreter, create an instance of the `Interpreter` class. The interpreter constructor requires keyword arguments, all with reasonable defaults; [see here for the list](#constructor). One important argument to an interpreter is a [configuration](#configuration), which, if needed, should be constructed first and then passed into the interpreter. If no configuration is specified, a default instance will be created and used: ```python import em config = em.Configuration(...) interp = em.Interpreter(config=config, ...) try: ... do some things with interp ... finally: interp.shutdown() ``` Then call interpreter methods on it such as `write`, `evaluate`, `execute`, `expand`, `string`, `file`, `expand`, and so on. The full list of interpreter methods is [here](#interpreter-methods). Exceptions that occur during processing will be handled by the interpreter's error handler. :::{important} When you create an interpreter, you must call its `shutdown` method when you are done. This is required to remove the proxy on `sys.stdout` that EmPy requires for proper operation and restore your Python environment to the state it was before creating the interpreter. This can be accomplished by creating the interpreter in a `with` statement -- interpreters are also context managers -- or by creating it and shutting it down in a `try`/`finally` statement. This is not needed when calling the `expand` global function; it creates and shuts down an ephemeral interpreter automatically. ::: Calling the interpreter's `shutdown` can be handled with either with a `try`/`finally` statement or a `with` statement: ```python import em interp = em.Interpreter(...) try: ... do some things with the interpreter ... finally: interp.shutdown() # or ... with em.Interpreter(...) as interp: ... do other things with the interpreter ... ``` :::{warning} If you receive a `ProxyError` mentioning when quitting your program, you are likely not calling the `shutdown` method on the interpreter. Make sure to call `shutdown` so the interpreter can clean up after itself. ::: :::{note} The `empy` pseudmodule is itself an instance of the `Intrerpreter` class, and its `config` attribute is an instance of the `Configuration` class, so within an EmPy interpreter you can access the `Interpreter` and `Configuration` classes without needing to import the `em` module: ```empy @{ Configuration = empy.config.__class__ Interpreter = empy.__class__ config = Configuration(...) interp = Interpreter(config=config, ...) ... }@ ``` ::: There is also a global `expand` function which will expand a single string and return the results, creating and destroying an ephemeral interpreter to do so. You can use this function to do a one-off expansion of, say, a large file: ```python import em data = open('tests/sample/sample.em').read() print(em.expand(data)) ``` If an exception occurs during `expand` processing, the exception will be raised to the caller. ### Standard modules A fully-functional EmPy system contains the following standard modules. #### `empy` pseudomodule The pseudomodule is not an actual module, but rather the instance of the running EmPy interpreter exposed to the EmPy system. It is automatically placed into the interpreter's globals and cannot be imported explicitly. See [Pseudomodule/interpreter](#pseudomodule-interpreter) for details. #### `em` module The primary EmPy module. It contains the `Configuration` and `Interpreter` classes as well as all supporting logic. An EmPy system can be functional with only this module present if needed. It also includes the following global functions: {#details} `details(level, [prelim, postlim, file])` : Write details about the running system to the given file, which defaults to `sys.stdout`. The `level` parameter is an attribute of the `em.Version` class (effectively an enum). `prelim` and `postlim` indicate preliminary and postliminary text to output before and after the details (and have reasonable defaults). :::{note} This function requires the `emlib` standard module to be installed to function most effectively. ::: {#expand} `expand(data, **kwargs) -> str` : Create a ephemeral interpreter with the given kwargs, expand data, shut the interpreter down, and then return the expansion. The function takes the same keyword arguments as the [`Interpreter` constructor](#constructor), with the following additions: {#expand-arguments-table} | Argument | Meaning | Default | | --- | --- | --- | | `dispatcher` | Dispatch errors or raise to caller? | `False` | | `locals` | The locals dictionary | `{}` | | `name` | The context filename | `""` | If the markup that is being expanded causes an exception to be raised, by default the exception will be let through to the caller. :::{important} As with the [`Interpreter` constructor](#constructor), the order of the `expand` arguments has changed over time and is subject to change in the future, so you must use keyword arguments to prevent any ambiguity, _e.g._: ```python myConfig = em.Configuration(...) myGlobals = {...} myOutput = open(...) result = em.expand(source, config=myConfig, globals=myGlobals, ...) ``` Attempts have been made to make the `expand` function as backward compatible (to 3._x_) as feasible, but some usages are ambiguous or do not have direct mappings to configurations. A `CompatibilityError` will be raised in these cases; if you encounter this, redesign your use of `expand` to be compatible with [the modern usage](#expand). In particular, in 3._x_, additional keyword arguments were used to indicate the locals dictionary; in 4._x_, keyword arguments are used for all arguments so the locals dictionary must be specified as a distinct `locals` keyword argument: ```python myGlobals = {...} myLocals = {...} result = em.expand(source, globals=myGlobals, locals=myLocals) ``` ::: :::{warning} Not all of the `Interpreter` constructor arguments are compatible with the `expand` function. The `filters`, `handler`, `input` and `output` arguments are immediately overridden by the inherent nature of the ephemeral interpreter and so would not behave as expected. Thus, if they are specified, a `ConfigurationError` will be raised. For more detailed configuration of an interpreter, it's better to create one yourself rather than rely on `expand`. ::: {#invoke} `invoke(args, **kwargs)` : Invoke the EmPy system with the given command line arguments (`sys.argv[1:]`, not `sys.argv`) and optional string settings. This is the entry point used by the main EmPy function. The remaining keyword arguments correspond to the [`Interpreter` constructor](#constructor) arguments. :::{warning} Since the `invoke` function configures and manages the lifetime of an `Interpreter`, not all of the constructor arguments are compatible with it. Specifically, the `filespec` and `immediately` arguments need to be managed by the function and so specifying a starting value is nonsensical. Thus, if they are specified, a `ConfigurationError` will be raised. ::: #### `emlib` module The EmPy supporting library. It contains various support classes, including the base classes `Filter` and `Hook` to assist in creating this supporting functionality. #### `emhelp` module The EmPy help system. It can be accessed from the main executable with the `-h/--help` and `-H/--topics=TOPICS` command line options. If the emlib module is not available to the executable, the help system will return an error. #### `emdoc` module The EmPy documentation system, used to create this document. :::{note} Unlike the other EmPy modules, `emdoc` requires a modern Python 3._x_ interpreter. ::: ### Using EmPy with build tools If you're using EmPy to process documents within a build system such as GNU Make or Ninja, you'll want to use the `-o/--output=FILENAME` (or `-a/--append=FILENAME`) and `-d/--delete-on-error` options together. This will guarantee that a file will be output (or appended) to a file without shell redirection, and that the file will be deleted if an error occurs. This will prevent errors from leaving a partial file around which subsequent invocations of the build system will mistake as being up to date. The invocation of EmPy should look like this (the `--` is not required if the input filename never starts with a dash): ```shell em.py -d -o $output -- $input ``` For GNU Make: ```make EMPY ?= em.py EMPY_OPTIONS ?= -d %: %.em $(EMPY) $(EMPY_OPTIONS) -o $@ -- $< ``` For Ninja: ```ninja empy = em.py empy_options = -d rule empy command = $empy $empy_options -o $out -- $in ``` ### Context formatting **Contexts** are objects which contain the filename, the line number, the column number, and the character (Unicode code point) number to record the location of an EmPy error during processing. These are formatted into human-readable strings with a **context format**, a string specifiable with `--context-format` (_configuration variable:_ `contextFormat`). A few different mechanisms for formatting contexts are available: {#context-formatting-mechanisms-table} | Mechanism | Description | Example | --- | --- | --- | | format | Use the `str.format` method | `{name}:{line}:{column}` | | operator | Use the `%` operator | `%(name)s:%(line)d:%(column)d` | | variable | Use `$` variables | `$NAME:$LINE:$COLUMN` | The default context format is `%(name)s:%(line)d:%(column)d` and uses the operator mechanism for backward compatibility. When a context format is set, EmPy will attempt to detect which of the above mechanisms is needed: {#context-formatting-criteria-table} | Mechanism | Criteria | | --- | --- | | format | string begins with `format:` or does not contain a `%` | | operator | string begins with `operator:` or contains a `%` | | variable | string begins with `variable:` | ### Data flow **input ⟶ interpreter ⟶ diversions ⟶ filters ⟶ output** Here, in summary, is how data flows through a working EmPy system: 1. Input comes from a source, such as an .em file on the command line, `sys.stdin`, a module import, or via an `empy.include` statement. 2. The interpreter processes this material as it comes in, processing EmPy expansions as it goes. 3. After expansion, data is then sent through the diversion layer, which may allow it directly through (if no diversion is in progress) or defer it temporarily. Diversions that are recalled initiate from this point. 4. If output is disabled, the expansion is dropped. 5. Otherwise, any filters in place are then used to filter the data and produce filtered data as output. 6. Finally, any material surviving this far is sent to the output stream. That stream is `sys.stdout` by default, but can be changed with the `-o/--output=FILENAME` or `-a/--append=FILENAME` options. 7. If an error occurs, execute the error handler (which by default prints an EmPy error). If the `-r/--raw-errors` option is specified, then print a full Python traceback. If `-k/--keep-going` is specified, continue processing rather than exit; otherwise halt. 8. On unsuccessful exit, if `-d/--delete-on-error` is specified, delete any specified output file. ### Glossary The following terms with their definitions are used by EmPy: *[callback](#callbacks)* : The user-provided callback which is called when the custom markup `@<...>` is encountered. _Custom markup and callbacks have been supplanted by [extensions](#extensions)._ *[command](#commands)* : A processing step which is performed before or after main document processing. Examples are `-D/--define=DEFN`, `-F/--file=FILENAME` or `-P/--preprocess=FILENAME`. *[configuration](#configuration)* : An object encapsulating all the configurable behavior of an interpreter which passed into interpreter on creation. Configurations can be shared between multiple interpreters. *[context](#context-formatting)* : An object which tracks the location of the parser in an EmPy file for tracking and error reporting purposes. *[control markup](#control-markups)* : A markup used to direct high-level control flow within an EmPy session. Control markups are expressed with the `@[...]` notation. *[core](#cores)* : An interpreter core is a plugin which determines how the underlying language is evaluated, executed, serialized, and how the `@[def ...]` control markup works. By default, the underlying language is Python. *[custom markup](#callback)* : The custom markup invokes a callback which is provided by the user, allowing any desired behavior. Custom markup is `@<...>`. _Custom markup and callbacks have been supplanted by [extensions](#extensions)._ *[diacritic](#diacritic-markup)* : A markup which joins together a letter and one or more combining characters from a dictionary in the configuration and outputs it. Diacritic markup is `@^...`. *[dispatcher](#error-dispatcher)* : An error dispatcher determines whether to dispatch the error to the interpreter's error handler (`True`), to reraise the error to the caller (`False`), or something else. *[diversion](#diversions)* : A process by which output is deferred, and can be recalled later on demand, multiple times if desired. *document* : An EmPy file containing EmPy markup to expand. *[embedding](#embedding-empy)* : Using an EmPy system by importing the `em` module and using the API to create and manipulate interpreters programmatically, as opposed to standalone. *[emoji](#emoji-markup)* : A markup which looks up a Unicode code point by name via a customizable set of installable emoji modules, or via a dictionary in the configuration. Emoji markup is `@:...:`. *[error](#error-handling)* : An exception thrown by a running EmPy system. When these occur, they are dispatched by an error dispatcher and then (possibly) passed to an error handler. *[escape](#escape-markup)* : A markup designed to expand to a single (often non-printable) character, similar to escape sequences in C or other languages. Escape markup is `@\...`. *executable* : The Python executable for an EmPy system, which by default is em.py. *expansion* : The process of processing EmPy markups and producing output. *[expression](#expression-markup)* : An expression markup represents a Python expression to be evaluated, and replaced with the `str` of its value. Expression markup is `@(...)`. *[extension](#extensions)* : An interpreter extension is a plugin which defines user-specifiable custom markups. *file* : An object which exhibits a file-like interface (methods such as `write` and `close`). *[filter](#filters)* : A file-like object which can be chained to other filters or the final stream, and can buffer, alter, or manipulate in any way the data sent. Filters can be chained together in arbitrary order. *[finalizer](#finalizers)* : A function which is called when an interpreter exits. Multiple finalizers can be added to each interpreter. *finder* : The `importlib` architecture for importng custom modules uses the meta path (`sys.meta_path`) which consists of a list of module finders to use. EmPy installs its own finder in this meta path for EmPy module support. *globals* : The dictionary (or dictionary-like object) which resides inside the interpreter and holds the currently-defined variables. *[handler](#error-handlers)* : An error handler which is called whenever an error occurs in the EmPy system. The default error handler prints details about the error to `sys.stderr`. *[hook](#hooks)* : A callable object that can be registered in a dictionary, and which will be invoked before, during, or after certain internal operations, identified by name with a string. Some types of hooks can override the behavior of the EmPy interpreter. *[icon](#icon-markup)* : A markup which looks up a variable-length abbreviation for a string from a lookup table in the configuration. Icon markup is `@|...`. *[interpreter](#pseudomodule-interpreter)* : The application (or class instance) which processes EmPy markup. *locals* : Along with the globals, a locals dictionary can be passed into individual EmPy API calls. *[markup](#markup)* : EmPy substitutions set off with a prefix (by default `@`) and appropriate delimiters. *[module](#modules)* : An EmPy module, imported with the native Python `import` statement. *[named escape](#named-escape-markup)* : A control character referenced by name in an escape markup, `@\^{...}`. *output* : The final destination of the result of processing an EmPy file. *[plugin](#plugins)* : An object which can be attached to an interpreter for custom functionality and implicitly retains a reference to it. Examples are cores and extensions. *[prefix](#prefix)* : The Unicode code point (character) used to set off an expansions. By default, the prefix is `@`. If set to `None`, no markup will be processed. *processor* : An extensible system which processes a group of EmPy files, usually arranged in a filesystem, and scans them for significators. *proxy* : An object which replaces the `sys.stdout` file object and allows the EmPy system to intercept any indirect output to `sys.stdout` (say, by the `print` function). *[pseudomodule](#pseudomodule-interpreter)* : The module-like object named `empy` (by default) which is exposed as a global inside every EmPy system. The pseudomodule and the interpreter are in fact the same object, an instance of the `Interpreter` class. *recode* : Converting reference values representing strings (contained in the dictionaries corresponding to `emojis`, `icons`, `diacritics` or `controls`) into native strings for expansion. *[shortcut](#import-shortcuts-table)* : An abbreviation that can be used in the `-I/--import=MODULES` command line option; _e.g._, `--import sys:version=ver` for `from sys import version as ver`. *[significator](#significator-markup)* : A special form of an assignment markup in EmPy which can be easily parsed externally, primarily designed for representing uniform assignment across a collection of files. Significator markup is `@%[!]... NL` and `@%%[!]...%% NL`. *standalone* : Using the EmPy system by running the `em.py` executable from the command line. *[statement](#statement-markup)* : A line of code that needs to be executed; statements do not have return values. Statement markup is `@{...}`. *stream* : A file-like object which manages diversion and filtering. A stack of these is used by the interpreter with the top one being active. *system* : A running EmPy environment. *token* : An element of EmPy parsing. Tokens are parsed and then processed one at a time. ### Statistics 
% wc setup.py bench.py emdoc.py emhelp.py timeline.py emlib.py em.py test.sh LICENSE.md README.md README.md.em
    75    307   2551 setup.py
   102    330   3084 bench.py
   551   1519  18487 emdoc.py
  1080   4944  47843 emhelp.py
   291    932   8404 timeline.py
  1345   4013  43224 emlib.py
  7032  24918 262309 em.py
   923   3139  23555 test.sh
    14    230   1520 LICENSE.md
  8244  35329 247737 README.md
  7605  35614 250472 README.md.em
 27262 111275 909186 total
% sha1sum setup.py bench.py emdoc.py emhelp.py timeline.py emlib.py em.py test.sh LICENSE.md README.md README.md.em
5e451dd6da2d96bc1cab865d470fb0b2f9ce0ff7  setup.py
1918abd38533653ddde61f93043f2d5a7d0aa277  bench.py
7821817cbb6d55a5e14a5d250913d5a7f813ddf9  emdoc.py
1e18843ff150236f4d0a22d85814440c6257a83d  emhelp.py
eda8b74776467e9e160722c9be198770d13ea8c5  timeline.py
c8cc5e34c26beab4c438d3b9878b9da44d0added  emlib.py
a43d49fd854f68a2047e77013384f1139775d12f  em.py
4a54d29cf0a87d2d350d6c44d05d00c0c2eed3a2  test.sh
b6db0b81a7c250442f29dcf8530c032b33662a95  LICENSE.md
eb4b9c8d8fa1349197a8fbc7825f3e0c5b8966ca  README.md
28f1f1dee6d3f31d9c2a71702be53188b25532c0  README.md.em
## End notes ### Author's notes I originally conceived EmPy as a replacement for my [Web templating system](http://www.alcyone.com/max/info/m4.html) which uses [m4](https://www.gnu.org/software/m4/), a general macroprocessing system for Unix. Most of my Web sites use a variety of m4 files, some of which are dynamically generated from databases, which are then scanned by a cataloging tool to organize them hierarchically (so that, say, a particular m4 file can understand where it is in the hierarchy, or what the titles of files related to it are without duplicating information); the results of the catalog are then written in database form as an m4 file (which every other m4 file implicitly includes), and then GNU Make converts each m4 to an HTML file by processing it. As the Web sites got more complicated, the use of m4 (which I had originally enjoyed for the challenge and abstractness) really started to become an impediment to serious work; while I was very knowledgeable about m4 -- having used it for so many years -- getting even simple things done with it is awkward and often difficult. Worse yet, as I started to use Python more and more over the years, the cataloging programs which scanned the m4 and built m4 databases were migrated to Python and made almost trivial, but writing out huge awkward tables of m4 definitions simply to make them accessible in other m4 scripts started to become almost farcical. It occurred to me what I really wanted was an all-Python solution. But replacing what used to be the m4 files with standalone Python programs would result in somewhat awkward programs normally consisting mostly of unprocessed text punctuated by small portions where variables and small amounts of code need to be substituted. Thus the idea was a sort of inverse of a Python interpreter: a program that normally would just pass text through unmolested, but when it found a special signifier would execute Python code in a normal environment. I looked at existing Python templating systems, and didn't find anything that appealed to me -- I wanted something where the desired markups were simple and unobtrusive. After considering choices of prefixes, I settled on `@` and EmPy was born. As I developed the tool, I realized it could have general appeal, even to those with widely varying problems to solve, provided the core tool they needed was an interpreter that could embed Python code inside templated text. As I continue to use the tool, I have been adding features as unobtrusively as possible as I see areas that can be improved. A design goal of EmPy is that its feature set should work on several levels; at any given level, if the user does not wish or need to use features from another level, they are under no obligation to do so -- in fact, they wouldn't even need to know they exist. If you have no need of diversions, for instance, you are under no obligation to use them or even to know anything about them. If significators will not help you organize a set of EmPy scripts globally, then you can ignore them. New features that are being added are whenever feasible transparently backward compatible (except for major version releases); if you do not need them, their introduction should not affect you in any way. Finally, the use of unknown prefix and escape sequences results in errors, ensuring that they are reserved for future use. ### Acknowledgements Questions, suggestions, bug reports, evangelism, and even complaints from many people over the years have helped make EmPy what it is today. Some, but by no means all, of these people are (in alphabetical order by surname): - Biswapesh Chattopadhyay - Beni Cherniavsky - Dr. S. Candelaria de Ram - Eric Eide - Dinu Gherman - Grzegorz Adam Hankiewicz - Robert Kroeger - Bohdan Kushnir - Kouichi Takahashi - Ville Vainio ### Known issues and caveats {#security} - A running EmPy system is just an alternate form of a Python interpreter; EmPy code is just as powerful as any Python code. Thus it is vitally important that an EmPy system not expand EmPy markup from an untrusted source; this is just as unsafe and potentially dangerous as executing untrusted Python code. {#speed} - As the EmPy parser is written in Python, it is not designed for speed. A compiled version designed for speed may be added in the future. - To function properly, EmPy must override `sys.stdout` with a proxy file object, so that it can capture output of side effects and support diversions for each interpreter instance. It is important that code executed in an environment _not_ rebind `sys.stdout`, although it is perfectly legal to reference it explicitly (_e.g._, `@sys.stdout.write("Hello world\n")`). If one really needs to access the "true" stdout, then use `sys.__stdout__` instead (which should also not be rebound). EmPy uses the standard Python error handlers when exceptions are raised in EmPy code, which print to `sys.stderr`. `sys.stderr`, `sys.__stdout__`, and `sys.__stderr__` are never overridden by the interpreter; only `sys.stdout` is. - If you are using multiple interpreters with distinct output files and are using the low-level interpreter methods (the ones not documented here) to perform expansion and output, the `sys.stdout` proxy will not be reliable. Only the high-level interpreter methods (`evaluate`, `execute`, `string`, `expand`) properly use the protected stream stack on the `sys.stdout` proxy to guarantee valid output. Either only use a single interpreter instance at a time (creating and shutting it down with its `shutdown` method), use the `-n/--no-proxy` option and only perform output with the `write` method on the interpreter (_i.e._, do not use any `print` statements in your code), or only use the high-level interpreter methods documented here. - The `empy` "module" exposed through the EmPy interface (_i.e._, `@empy`) is an artificial module. It is automatically exposed in the globals of a running interpreter and it cannot be manually imported with the `import` statement (nor should it be -- it is an artifact of the EmPy processing system and does not correspond directly to any .py file). - For an EmPy statement expansion all alone on a line, _e.g._, `@{a = 1}`, will include a blank line due to the newline following the closing curly brace. To suppress this blank line, use the symmetric convention `@{a = 1}@`, where the final `@` markup precedes the newline, making it whitespace markup and thus consumed. For instance: ````empy @{a = 1} There will be an extra newline above (following the closing brace). Compare this to: @{a = 1}@ There will be no extra newline above. ```` See [here](#idiom) for more details. - Errors generated from within nested control structures (_e.g._, `@[for ...]@[if ...]...@[end if]@[end for]` will report a context of the start of the top-level control structure markup, not the innermost markup, which would be much more helpful. This issue is not new to 4.0 and will be addressed in a future release. - Errors are very literal and could be made more useful to find the underlying cause. - Contexts (such as `empy.identify`) track the context of executed _EmPy_ code, not Python code. This means, for instance, that blocks of code delimited with `@{` and `}` will identify themselves as appearing on the line at which the `@{` appears. If you're tracking errors and want more information about the location of the errors from the Python code, use the `-r/--raw-errors` option, which will provide you with the full Python traceback. - The `@[for]` variable specification supports tuples for tuple unpacking, even recursive tuples. However, it is limited in that the names included may only be valid Python identifiers, not arbitrary Python "lvalues." Since this is something of an accidental Python feature that is very unlikely to be relied on in practice, this is not thought to be a significant limitation. As a concrete example: ```python a = [None] for a[0] in range(5): print(a) ``` is valid (but strange) Python code, but the EmPy equivalent with `@[for a[0] in range(5)]...` is invalid. - The `:=` assignment expression syntax ("walrus operator") for `while` loops and `if` statements, introduced in Python 3.8, is not supported in the EmPy equivalent control markups `@[while]` and `@[if]`. This may be supported in the future. - As of Python 3.10, the `with` control structure supports specifying multiple context managers separated by commas. This is not yet supported by EmPy, but may be in a future version. For now, just use nested `@[with]` control markups. ### For package maintainers EmPy is available as a system package in most major Linux distributions, though some have not updated to EmPy 4._x_ yet. EmPy can be made available as an operating system distribution package in several different ways. Regardless of the high-level organization, the installed .py Python files must be made available as importable Python modules, with the additional requirement that em.py must be made available as an executable in the default `PATH`. If necessary, this executable may also be named `empy`, but `em.py` is preferred -- and either way it is still important that the em.py file be available for importing as a Python module (`em`). :::{important} Since EmPy 4._x_ is not fully compatible with EmPy 3._x_, I suggest making both EmPy 3._x_ and 4._x_ packages available side by side until 4._x_ becomes more fully adopted by the community. ::: Here is a breakdown of the contents of a release tarball: {#release-tarball-contents-table} | File | Description | | --- | --- | | em.py | Main EmPy module and executable | | emhelp.py | Help subsystem module | | emlib.py | Supplementary EmPy facilities module | | emdoc.py | Documentation subsystem module | | setup.py | `setuptools` installation script | | ANNOUNCE.md | EmPy 4._x_ release announcement | | HELP.md | Help topic summaries | | LEGACY.md | Legacy user's guide (3.3.4) | | LICENSE.md | Software license | | README.md | README (this file) | | README.md.em | README source file | | doc | HTML documentation directory hierarchy | | test.sh | Test shell script | | tests | Tests directory hierarchy | | suites | Test suites directory hierarchy | They can either be bundled up into a single, monolithic package, or divided into a series of subpackages. Here's a suggestion for a fleshed-out series of EmPy subpackages: `empy-minimal` : Just the em.py file, available as a Python module as well as an executable. Note that this will not allow the use of the EmPy help subsystem, unless the module emhelp.py is also included. `empy-basic` : The .md files, all the .py files (em.py, emhelp.py, emlib.py, emdoc.py) available as Python modules, with the em.py file also available as an executable. `empy-doc` : The docs directory hierarchy, the top-level .md files (README.md, LICENSE.md, etc.) and the README EmPy source file README.md.em. `empy-test` : The test script test.sh, the tests directory, and the suites directory. `empy` : All of the above. ### Reporting bugs If you find a bug in EmPy, please follow these steps: 1. Whittle a reproducible test case down to the smallest standalone example which demonstrates the issue, the smaller the better; 2. Collect the output of `em.py -Z` (this will provide detailed diagnostic details about your environment), or at least `em.py -W` (which provides only basic details); 3. [Send me an email](mailto:software@alcyone.com) with _EmPy_ in the Subject line including both files and a description of the problem. Thank you! ### Release history {#latest-release} 4.2.1 (2026 Feb 8) : `codecs.open` is deprecated as of Python 3.14, so use `open` instead in binary mode; better proxy and module finder management using `sys` module; uniform attachment and detachment of plugins; converted and expanded documentation to Furo theme; better Java exception printing under Jython; add preinitializers, postinitialiers, and requirements for testing; additions to named escapes; add `SimpleToken` token factory. 4.2 (2024 Aug 25) : Add module support; add support for disabling output and switch markup; add support for reconfiguring stdin/stdout; support repeated curly braces with functional expression; add backward-compatible `Case` abstraction for match markup; add more preprocessing and postprocessing commands via command line options (`-K/--postexecute=STATEMENT`, `-X/--expand=MARKUP`, `-Y/--postexpand=MARKUP`). {#last-release} 4.1 (2024 Mar 24) : Add support for extension markup `@((...))`, `@[[...]]`, `@{{...}}`, `@<...>`, etc., with custom callbacks retained for backward compatibility; add `@[match]` control support; add interpreter cores for overriding interpreter behavior; add more command line option toggles; add notion of verbose/brief errors; more uniform error message formatting; various documentation updates. {#last-minor-release} 4.0.1 (2023 Dec 24) : Add root context argument, serializers, and idents to interpreter; fix `setContext...` methods so they also modify the currents stack; better backward compatibility for `expand` function and `CompatibilityError`; fix inconsistent stack usage with `expand` method; add error dispatchers, cleaner error handling and `ignoreErrors`; have `expand` method/function raise exceptions to caller; eliminate need for `FullContext` class distinct from `Context`; support comments in "clean" controls; add `--no-none-symbol` option; add clearer errors for removed literal markup; add `Container` support class in `emlib`; hide non-standard proxy attributes and methods; support string errors (why not); update and expand tests; help subsystem and documentation updates. {#last-major-release} 4.0 (2023 Nov 29) : A major revamp, refresh, and modernization. Major new features include inline comments `@*...*`; backquote literals `` @`...` ``; chained if-then-else expressions; functional expressions `@f{...}`; full support for `@[try]`, `@[while ...]` and `@[with ...]` control markup; `@[defined ...]` control markup; stringized and multiline significators; named escapes `@\^{...}`; diacritics `@^...`; icons `@|...`; emojis `@:...:`; configurations; full Unicode and file buffering support; proxy now reference counted; hooks can override behavior; many bug fixes; an extensive builtin help system (`emhelp`); and rewritten and expanded documentation in addition to a dedicated module (`emdoc`). Changes include relicensing to BSD, interpreter constructor now requires keyword arguments, `-d/--delete-on-error` instead of "fully buffered files"; cleaned up environment variables; "repr" markup replaced with emoji markup; remove literal markups `@)`, `@]`, `@}`; context line markup `@!...` no longer pre-adjusts line; custom markup `@<...>` now parsed more sensibly; filter shortcuts removed; context now track column and character count; auxiliary classes moved to `emlib` module; use `argv` instead of `argc` for interpreter arguments. See [Full list of changes between EmPy 3._x_ and 4.0](ANNOUNCE.md#all-changes) for a more comprehensive list. {#prior-major-release} 3.3.4a (2021 Nov 19) : Fix an error in setup.py in the release tarball (did not affect PIP downloads). 3.3.4 (2019 Feb 26) : Minor fix for a Python 3._x_ compatibility issue. 3.3.3 (2017 Feb 12) : Fix for `empy.defined` interpreter method. 3.3.2 (2014 Jan 24) : Additional fix for source compatibility between 2._x_ and 3.0. 3.3.1 (2014 Jan 22) : Source compatibility for 2._x_ and 3.0; 1._x_ compatibility dropped. 3.3 (2003 Oct 27) : Custom markup `@<...>`; remove separate pseudomodule instance for greater transparency; deprecate `Interpreter` attribute of pseudomodule; deprecate auxiliary class name attributes associated with pseudomodule in preparation for separate support library in 4.0; add `--no-callback-error` [defunct] and `--no-bangpath-processing` [now `--no-ignore-bangpaths`] command line options; add `atToken` hook. 3.2 (2003 Oct 7) : Reengineer hooks support to use hook instances; add `-v/--verbose` and `-l/--relative-path` option; reversed PEP 317 style; modify Unicode support to give less confusing errors in the case of unknown encodings and error handlers; relicensed under LGPL. 3.1.1 (2003 Sep 20) : Add string literal `@"..."` markup; add `-w/--pause-at-end` option; fix improper globals collision error via the `sys.stdout` proxy. 3.1 (2003 Aug 8) : Unicode support (Python 2.0 and above); add Document and Processor helper classes for processing significators [later moved to `emlib`]; add `--no-prefix` option for suppressing all markups. 3.0.4 (2003 Aug 7) : Implement somewhat more robust "lvalue" parsing for `@[for]` construct. 3.0.3 (2003 Jul 9) : Fix bug regarding recursive tuple unpacking using `@[for]`; add `empy.saveGlobals`, `empy.restoreGlobals`, and `empy.defined` functions. 3.0.2 (2003 Jun 19) : `@?` and `@!` markups for changing the current context name and line, respectively; add `update` method to interpreter; new and renamed context operations, `empy.setContextName`, `empy.setContextLine`, `empy.pushContext`, `empy.popContext`. 3.0.1 (2003 Jun 9) : Fix simple bug preventing command line preprocessing directives (`-I/--import=MODULES`, `-D/--define=DEFN`, `-E/--execute=STATEMENT`, `-F/--file=FILENAME`, `-P/--preprocess=FILENAME`) from executing properly; defensive PEP 317 compliance [defunct]. 3.0 (2003 Jun 1) : Replace substitution markup with control markup `@[...]`; support `@(...?...!...)` for conditional expressions; add acknowledgements and glossary sections to documentation; rename buffering option back to `-b/--buffering`; add `-m/--pseudomodule=NAME` and `-n/--no-proxy` for suppressing `sys.stdout` proxy; rename main error class to `Error`; add standalone `expand` function; add `--binary` and `--chunk-size` options [defunct]; reengineer parsing system to use tokens for easy extensibility; safeguard curly braces in simple expressions [now used by functional expressions]; fix bug involving custom `Interpreter` instances ignoring globals argument; `distutils` [now `setuptools`] support. 2.3 (2003 Feb 20) : Proper and full support for concurrent and recursive interpreters; protection from closing the true stdout file object; detect edge cases of interpreter globals or `sys.stdout` proxy collisions; add globals manipulation functions `empy.getGlobals`, `empy.setGlobals`, and `empy.updateGlobals` which properly preserve the `empy` pseudomodule; separate usage info out into easily accessible lists for easier presentation; have `-h` option show simple usage and `-H` show extended usage [defunct]; add `NullFile` utility class. 2.2.6 (2003 Jan 30) : Fix a bug in the `Filter.detach` method (which would not normally be called anyway). 2.2.5 (2003 Jan 9) : Strip carriage returns out of executed code blocks for DOS/Windows compatibility. 2.2.4 (2002 Dec 23) : Abstract Filter interface to use methods only; add `@[noop: ...]` substitution for completeness and block commenting [defunct]. 2.2.3 (2002 Dec 16) : Support compatibility with Jython by working around a minor difference between CPython and Jython in string splitting. 2.2.2 (2002 Dec 14) : Include better docstrings for pseudomodule functions; segue to a dictionary-based options system for interpreters; add `empy.clearAllHooks` and `empy.clearGlobals`; include a short documentation section on embedding interpreters; fix a bug in significator regular expression. 2.2.1 (2002 Nov 30) : Tweak test script to avoid writing unnecessary temporary file; add `Interpreter.single` method; expose `evaluate`, `execute`, `substitute` [defunct], and `single` methods to the pseudomodule; add (rather obvious) `EMPY_OPTIONS` environment variable support; add `empy.enableHooks` and `empy.disableHooks`; include optimization to transparently disable hooks until they are actually used. 2.2 (2002 Nov 21) : Switched to `-V/--version` option for version information; `empy.createDiversion` for creating initially empty diversion; direct access to diversion objects with `empy.retrieveDiversion`; environment variable support; removed `--raw` long argument (use `-r/--raw-errors` instead); added quaternary escape code (well, why not). 2.1 (2002 Oct 18) : Finalizers now separate from hooks; include a benchmark sample and test.sh verification script; expose `empy.string` directly; `-D/--define=DEFN` option for explicit defines on command line; remove ill-conceived support for `@else:` separator in `@[if ...]` substitution [defunct]; handle nested substitutions properly [defunct]; `@[macro ...]` substitution for creating recallable expansions [defunct]; add support for finalizers with `empy.atExit` [now `empy.appendFinalizer`]. 2.0.1 (2002 Oct 8) : Fix missing usage information; fix `after_evaluate` hook not getting called [defunct]. 2.0 (2002 Sep 30) : Parsing system completely revamped and simplified, eliminating a whole class of context-related bugs; builtin support for buffered filters; support for registering hooks; support for command line arguments; interactive mode with `-i/--interactive`; significator value extended to be any valid Python expression. 1.5.1 (2002 Sep 24) : Allow `@]` to represent unbalanced close brackets in `@[...]` markups [defunct]. 1.5 (2002 Sep 18) : Escape codes (`@\...`); conditional and repeated expansion substitutions [defunct; replaced with control markups]; fix a few bugs involving files which do not end in newlines. 1.4 (2002 Sep 7) : Add in-place markup `@:...:...:` [now `@$...$...$`]; fix bug with triple quotes; collapse conditional and protected expression syntaxes into the single generalized `@(...)` notation; `empy.setName` and `empy.setLine` functions [now `empy.setContextName` and `empy.setContextLine`]; true support for multiple concurrent interpreters with improved `sys.stdout` proxy; proper support for `empy.expand` to return a string evaluated in a subinterpreter as intended; reorganized parser class hierarchy. 1.3 (2002 Aug 24) : Pseudomodule as true instance; move toward more verbose (and clear) pseudomodule function names; fleshed out diversions model; filters; conditional expressions; except expressions; preprocessing with `-P/--preprocess=FILENAME`. 1.2 (2002 Aug 16) : Treat bangpaths as comments; `empy.quote` for the opposite process of `empy.expand`; significators (`@%...` sequences); add `-I/--import=MODULES` and `-f/--flatten` options; much improved documentation. 1.1.5 (2002 Aug 15) : Add a separate `invoke` function that can be called multiple times with arguments to execute multiple runs. 1.1.4 (2002 Aug 12) : Handle strings thrown as exceptions properly; use `getopt` to process command line arguments; cleanup file buffering with `AbstractFile` [defunct]; very slight documentation and code cleanup. 1.1.3 (2002 Aug 9) : Support for changing the prefix from within the `empy` pseudomodule [defunct; now in configuration]. 1.1.2 (2002 Aug 5) : Renamed buffering option [defunct], added `-F/--file=FILENAME` option for interpreting Python files from the command line, fixed improper handling of exceptions from commands (`-E/--execute=STATEMENT`, `-F/--file=FILENAME`). 1.1.1 (2002 Aug 4) : Typo bugfixes; documentation clarification. 1.1 (2002 Aug 4) : Added option for fully buffering output [defunct; use `-d/--delete-on-error` instead], executing commands through the command line; some documentation errors fixed. {#first-major-release} 1.0 (2002 Jul 23) : Renamed project to EmPy. Documentation and sample tweaks; added `empy.flatten` [now `empy.flattenGlobals`]; added `-a/--append=FILENAME` option. First official release. 0.3 (2002 Apr 14) : Extended "simple expression" syntax, interpreter abstraction, proper context handling, better error handling, explicit file inclusion, extended samples. 0.2 (2002 Apr 13) : Bugfixes, support non-expansion of `None`s, allow choice of alternate prefix. 0.1.1 (2002 Apr 12) : Bugfixes, support for Python 1.5._x_ [defunct], add `-r/--raw-errors` option. {#first-early-release} 0.1 (2002 Apr 12) : Initial early access release. ### Timelines [![Early development](dynamic/early.png)](dynamic/early.png) --- [![Stable maintenance](dynamic/mid.png)](dynamic/mid.png) --- [![Recent development](dynamic/recent.png)](dynamic/recent.png) ### Contact This software was written by [Erik Max Francis](http://www.alcyone.com/max/). If you use this software, have suggestions for future releases, or bug reports or problems with this documentation, [I'd love to hear about it](mailto:software@alcyone.com). Even if you try out EmPy for a project and find it unsuitable, I'd like to know what stumbling blocks you ran into so they can potentially be addressed in a future version. I hope you enjoy using EmPy! ℰ ### About this document This document was generated with EmPy itself using the `emdoc` module. Both the source (README.md.em) and the resulting Markdown text (README.md) are included in the release tarball, as is the HTML directory hierarchy generated with Sphinx (doc). _This documentation for EmPy version 4.2.1 was generated from README.md.em (SHA1 `28f1f1dee6d3f31d9c2a71702be53188b25532c0`, 250472 bytes) at 2026-02-08 16:22:56 using EmPy version 4.2.1, in CPython/3.10.12, on Linux (POSIX), with x86_64, under GCC/11.4.0._ empy-4.2.1/em.py0000755000175000017500000100024515142214615013373 0ustar jriverojrivero#!/usr/bin/env python3 """ A system for processing Python via markup embeded in text. """ __project__ = "EmPy" __program__ = "empy" __module__ = "em" __version__ = "4.2.1" __url__ = "http://www.alcyone.com/software/empy/" __author__ = "Erik Max Francis " __contact__ = "software@alcyone.com" __copyright__ = "Copyright (C) 2002-2026 Erik Max Francis" __license__ = "BSD" # # imports # import codecs import copy import getopt import os import platform import re import sys import unicodedata # # compatibility # # Initializes the following global names based on Python 2.x vs. 3.x: # # - major Detected major Python version # - minor Detected minor Python version # - compat List of Python backward-compatibility features applied # - narrow Was Python built with narrow Unicode (UTF-16 natively)? # - modules Is EmPy module support feasible? # - nativeStr The native str type (str in Python 3.x; str in Python 2.x) # - str (_unicode) The str type (str in Python 3.x; unicode in Python 2.x) # - bytes (_str) The bytes type (bytes in Python 3.x; str in Python 2.x) # - strType The str type (Python 3.x) or the bytes and str types (2.x) # - chr The chr function (unichr in Python 2.x) # - input The input function (raw_input in Python 2.x) # - evalFunc The eval function # - execFunc The exec function # - binaryOpen The codecs.open function, or open (Python 3.14+) # - BaseException The base exception class for all exceptions # - FileNotFoundError FileNotFoundError (= IOError in Python < 3.3) # - StringIO The StringIO class # - isIdentifier Is this string a valid Python identifier? # - uliteral Return a version-specific wide Unicode literal ('\U...') # - toString Convert an arbitrary object to a Unicode-compatible string # The major version of Python (2 or 3). major = sys.version_info[0] # The minor version of Python. minor = sys.version_info[1] # A list of Python backward-compatibility features which were applied. compat = [] # The native str type/function. nativeStr = str # The eval function. evalFunc = eval if major == 2: # We're using Python 2.x! Make sure there are Python 3.x-like names for # the basic types and functions; hereafter, use str for unicode and bytes # for str, respectively. bytes = _str = str str = _unicode = unicode strType = (bytes, str) chr = unichr input = raw_input # In Python 2.x, binaryOpen defers to codecs.open. binaryOpen = codecs.open # In Python 2.x, StringIO is contained in the cStringIO module. try: from cStringIO import StringIO except ImportError: # If cStringIO is not present for some reason, try to use the slower # StringIO module. from StringIO import StringIO if minor < 5: # Starting with Python 2.5, a new BaseException class serves as the # base class of all exceptions; prior to that, it was just Exception. # So create a name for it if necessary. BaseException = Exception compat.append('BaseException') # Python 2.x did not have a FileNotFoundError. FileNotFoundError = IOError compat.append('FileNotFoundError') # In Python 2.x, exec is a statement; in Python 3.x, it's a function. Make # a new function that will simulate the Python 3.x form but work in Python # 2.x. def execFunc(code, globals=None, locals=None): if globals is None: exec("""exec code""") else: if locals is None: exec("""exec code in globals""") else: exec("""exec code in globals, locals""") def toString(value): """Convert value to a (Unicode) string.""" if isinstance(value, _unicode): # Good to go. return value elif isinstance(value, _str): # It's already a str (bytes), convert it to a unicode (str). return _unicode(value) else: # In Python 2.x, __str__ returns a str, not a unicode. Convert the # object to a str (bytes), then convert it to a unicode (str). return _unicode(_str(value)) def isIdentifier(string, first=True): """Is this string a valid identifier? If first is true, make sure the first character is a valid starting identifier character.""" for char in string: if first: if not (char.isalpha() or char == '_'): return False first = False else: if not (char.isalpha() or char.isdigit() or char == '_'): return False return True def uliteral(i): """Return a wide Unicode string literal.""" return r"u'\U%08x'" % i elif major >= 3: # We're using Python 3.x! Add Python 2.x-like names for the basic types # and functions. The name duplication is so that there will always be a # definition of both str and types in the globals (as opposed to the # builtins). bytes = _str = bytes str = _unicode = str strType = str chr = chr input = input # In Python 3.x, the module containing StringIO is io. from io import StringIO # codecs.open is deprecated starting with Python 3.14. Use open instead. if minor >= 14: binaryOpen = open compat.append('!codecs.open') else: binaryOpen = codecs.open # Python 3.x prior to 3.3 did not have a FileNotFoundError. if minor < 3: FileNotFoundError = IOError compat.append('FileNotFoundError') # The callable builtin was removed from Python 3.0 and reinstated in Python # 3.2, but we need it. if minor < 2: def callable(object): return getattr(object, '__call__', None) is not None compat.append('callable') # In Python 3.x, exec is a function, but attempting to reference it as such # in Python 2.x generates an error. Since this needs to also compile in # Python 2.x, defer the evaluation past the parsing phase. try: execFunc = evalFunc('exec') except NameError: execFunc = evalFunc('__builtins__.exec') def toString(value): """Convert value to a (Unicode) string.""" return str(value) def isIdentifier(string, first=True): """Is this string a valid identifier? If first is true, make sure the first character is a valid starting identifier character.""" if first: return string.isidentifier() else: return ('_' + string).isidentifier() def uliteral(i): """Return a wide Unicode string literal.""" return r"'\U%08x'" % i # Was this Python interpreter built with narrow Unicode? That is, does it use # a UTF-16 encoding (with surrgoate pairs) vs. UTF-32 internally? if hasattr(sys, 'maxunicode'): narrow = sys.maxunicode < 0x10000 else: narrow = len(evalFunc(uliteral(0x10000))) > 1 if narrow: # Narrow Python builds will raise a ValueError when calling chr (unichr) on # a code point value outside of the Basic Multilingual Plane (U+0000 # .. U+FFFF). See if it needs to be replaced. _chr = chr if major == 2: if minor >= 6: # Versions 2.6 and up can use this struct/decode trick. compat.append('chr/decode') def chr(i, _chr=_chr): if i < 0x10000: return _chr(i) else: import struct try: return struct.pack('i', i).decode('utf-32') except UnicodeDecodeError: raise ValueError("chr() arg not in range") else: # Earlier versions (2.5 and below) need to evaluate a literal. compat.append('chr/uliteral') def chr(i, _chr=_chr): if i < 0x10000: return _chr(i) else: try: return evalFunc(uliteral(i)) except (SyntaxError, UnicodeDecodeError): raise ValueError("chr() arg not in range") compat.append('narrow') # Is EmPy module support feasible on this interpreter? modules = True if (major, minor) < (3, 4): # importlib architecture didn't exist before Python 3.4. modules = False if ('python_implementation' in platform.__dict__ and platform.python_implementation() == 'IronPython'): # importlib architecture doesn't work right in IronPython. modules = False if not modules: compat.append('!modules') # # constants # # Character information. UNDERSCORE_CHAR = '_' DOT_CHAR = '.' BACKSLASH_CHAR = '\\' CARET_CHAR = '^' STROKE_CHAR = '|' OCTOTHORPE_CHAR = '#' PLUS_CHAR = '+' MINUS_CHAR = '-' ASTERISK_CHAR = '*' QUESTION_CHAR = '?' EXCLAMATION_CHAR = '!' PERCENT_CHAR = '%' OPEN_PARENTHESIS_CHAR = '(' OPEN_BRACE_CHAR = '{' OPEN_BRACKET_CHAR = '[' OPEN_ANGLE_CHAR = '<' BACKQUOTE_CHAR = '`' DOLLAR_CHAR = '$' COLON_CHAR = ':' WHITESPACE_CHARS = ' \t\v\f\r\n' LITERAL_CHARS = '()[]{}<>\\\'\"?' CARRIAGE_RETURN_CHAR = '\r' NEWLINE_CHAR = '\n' OPENING_CHARS = '([{<' DUPLICATIVE_CHARS = '([{' PHRASE_OPENING_CHARS = '([' CLOSING_CHARS = ')]}>' QUOTE_CHARS = '\'\"' ENDING_CHAR_MAP = {'(': ')', '[': ']', '{': '}', '<': '>'} # Environment variable names. OPTIONS_ENV = 'EMPY_OPTIONS' CONFIG_ENV = 'EMPY_CONFIG' PREFIX_ENV = 'EMPY_PREFIX' PSEUDO_ENV = 'EMPY_PSEUDO' FLATTEN_ENV = 'EMPY_FLATTEN' RAW_ERRORS_ENV = 'EMPY_RAW_ERRORS' INTERACTIVE_ENV = 'EMPY_INTERACTIVE' DELETE_ON_ERROR_ENV = 'EMPY_DELETE_ON_ERROR' NO_PROXY_ENV = 'EMPY_NO_PROXY' BUFFERING_ENV = 'EMPY_BUFFERING' BINARY_ENV = 'EMPY_BINARY' ENCODING_ENV = 'EMPY_ENCODING' INPUT_ENCODING_ENV = 'EMPY_INPUT_ENCODING' OUTPUT_ENCODING_ENV = 'EMPY_OUTPUT_ENCODING' ERRORS_ENV = 'EMPY_ERRORS' INPUT_ERRORS_ENV = 'EMPY_INPUT_ERRORS' OUTPUT_ERRORS_ENV = 'EMPY_OUTPUT_ERRORS' # A regular expression string suffix which will match singificators; prepend # the interpreter prefix to make a full regular expression string. A # successful match will yield six groups, arranged in two clusters of three. # Each cluster contains the following three named groups in index order: # # - string: A `!` to represent a stringized significator, or blank # - key: The significator key # - value: The significator value; can be blank # # The value should be stripped before being tested. If it is blank and if the # significator is not stringized, then the resulting significator value will be # None. # # The first cluster (with group names ending in 2: string2, key2, value2) # matches multiline significators; the second (with group names ending in 1: # string1, key1, value1) matches singleline ones. Only one of these clusters # will be set. # # The regular expression should be compiled with the following flags: # re.MULTILINE|re.DOTALL|re.VERBOSE. To get a compiled regular expression # object for a given config, call `config.significatorRe()`. SIGNIFICATOR_RE_STRING_SUFFIX = r""" # Flags: re.MULTILINE|re.DOTALL|re.VERBOSE % # Opening `%` (?: # Start non-grouping choice: Multiline % # A second `%` (?P!?) # An optional `!` [string2] [ \t\v\f\r]* # Zero or more non-newline whitespace (?P\S+) # One or more non-whitespace [key2] \s* # Zero or more whitespace (?P[^%]*) # Zero or more non-`%` characters [value2] \s* # Zero or more whitespace %% # Closing `%%` | # Next non-grouping choice: Singleline (?P!?) # An optional `!` [string1] [ \t\v\f\r]* # Zero or more non-newline whitespace (?P\S+) # One or more non-whitespace [key1] [ \t\v\f\r]* # Zero or more non-newline whitespace (?P[^\n]*) # Zero or more non-newline characters [value1] [ \t\v\f\r]* # Zero or more non-newline whitespace ) # End choice $ # End string """ # # Error ... # class Error(Exception): def __init__(self, *args, **kwargs): # super does not work here in Python 2.4. Exception.__init__(self, *args) self.__dict__.update(kwargs) class ConsistencyError(Error): pass class ProxyError(ConsistencyError): pass class DiversionError(Error): pass class FilterError(Error): pass class CoreError(Error): pass class ExtensionError(Error): pass class StackUnderflowError(Error, IndexError): pass class UnknownEmojiError(Error, KeyError): pass class StringError(Error): pass class InvocationError(Error): pass class ConfigurationError(Error): pass class CompatibilityError(ConfigurationError): pass class ConfigurationFileNotFoundError(ConfigurationError, FileNotFoundError): pass class ParseError(Error): pass class TransientParseError(ParseError): pass # # Flow ... # class Flow(Exception): pass class ContinueFlow(Flow): pass class BreakFlow(Flow): pass # # Root # class Root(object): """The root class of all EmPy class hierarchies. It defines a default __repr__ method which will work appropriately whether or not the subclass defines a __str__ method. Very old versions of Python 2.x won't print the proper __str__ form, but so be it.""" def __repr__(self): if (hasattr(self, '__str__') and hasattr(type(self), '__str__') and getattr(type(self), '__str__') is not getattr(Root, '__str__')): return '%s(%s)' % (self.__class__.__name__, toString(self)) else: return '<%s @ 0x%x>' % (self.__class__.__name__, id(self)) # # EmojiModuleInfo # class EmojiModuleInfo(Root): """The abstraction of an emoji module that may or may not be available for usage.""" def __init__(self, name, attribute, format, capitalization, delimiters, *extra): self.name = name self.attribute = attribute self.format = format self.capitalization = capitalization self.delimiters = delimiters self.extra = extra self.ok = False self.initialize() def __str__(self): return self.name def initialize(self): """Attempt to initialize this emoji module. Set ok to true if successful.""" try: self.module = __import__(self.name) self.function = getattr(self.module, self.attribute, None) except ImportError: self.module = self.function = None if self.function is not None: self.ok = True def substitute(self, text): """Substitute text using this module. Return None if unsuccessful.""" assert self.ok wrapped = self.format % text try: result = self.function(wrapped) except KeyError: return None if wrapped == result: return None else: return result Module = EmojiModuleInfo # DEPRECATED # # Configuration # class Configuration(Root): """The configuration encapsulates all the defaults and parameterized behavior of an interpreter. When created, an interpreter is assigned a configuration; multiple configurations can be shared between different interpreters. To override the defaults of an interpreter, create a Configuration instance and then modify its attributes.""" # Constants. version = __version__ bangpath = '#!' unknownScriptName = '<->' significatorReStringSuffix = SIGNIFICATOR_RE_STRING_SUFFIX fullBuffering = -1 noBuffering = 0 lineBuffering = 1 unwantedGlobalsKeys = [None, '__builtins__'] # None = pseudomodule name unflattenableGlobalsKeys = ['globals'] priorityVariables = ['checkVariables'] ignoredConstructorArguments = [] emojiModuleInfos = [ # module name, attribute name, wrapping format, capitaliztion, delimiters ('emoji', 'emojize', ':%s:', 'lowercase', 'underscores'), ('emojis', 'encode', ':%s:', 'lowercase', 'underscores'), ('emoji_data_python', 'replace_colons', ':%s:', 'lowercase', 'underscores'), ('unicodedata', 'lookup', '%s', 'both', 'spaces'), ] # Defaults. defaultName = 'default' defaultPrefix = '@' defaultPseudomoduleName = 'empy' defaultModuleExtension = '.em' defaultRoot = '' defaultBuffering = 16384 defaultContextFormat = '%(name)s:%(line)d:%(column)d' defaultNormalizationForm = 'NFKC' defaultErrors = 'strict' defaultConfigVariableName = '_' defaultStdout = sys.stdout defaultSuccessCode = 0 defaultFailureCode = 1 defaultUnknownCode = 2 defaultSkipCode = 111 defaultSignificatorDelimiters = ('__', '__') defaultEmptySignificator = None defaultAutoValidateIcons = True defaultEmojiModuleNames = [ 'emoji', 'emojis', 'emoji_data_python', 'unicodedata', ] defaultNoEmojiModuleNames = [ 'unicodedata', ] # Statics. baseException = BaseException topLevelErrors = (ConfigurationError,) fallThroughErrors = (SyntaxError,) proxyWrapper = None useContextFormatMethod = None emojiModules = None iconsSignature = None verboseFile = sys.stderr factory = None ignorableErrorAttributes = [ # Python atttributes 'args', 'message', 'add_note', 'characters_written', 'with_traceback', # Jython attributes 'addSuppressed', 'cause', 'class', 'equals', 'fillInStackTrace', 'getCause', 'getClass', 'getLocalizedMessage', 'getMessage', 'getStackTrace', 'getSuppressed', 'hashCode', 'initCause', 'localizedMessage', 'notify', 'notifyAll', 'printStackTrace', 'setStackTrace', 'stackTrace', 'suppressed', 'toString', 'wait', ] tokens = None # list of token factories; intialized below _initialized = False # overridden in instances tag = None # overridden in instances # Dictionaries. controls = { # C0 (ASCII, ISO 646, ECMA-6) 'NUL': (0x00, "null"), 'SOH': (0x01, "start of heading, transmission control one"), 'TC1': (0x01, "start of heading, transmission control one"), 'STX': (0x02, "start of text, transmission control two"), 'TC2': (0x02, "start of text, transmission control two"), 'ETX': (0x03, "end of text, transmission control three"), 'TC3': (0x03, "end of text, transmission control three"), 'EOT': (0x04, "end of transmission, transmission control four"), 'TC4': (0x04, "end of transmission, transmission control four"), 'ENQ': (0x05, "enquiry, transmission control five"), 'TC5': (0x05, "enquiry, transmission control five"), 'ACK': (0x06, "acknowledge, transmission control six"), 'TC6': (0x06, "acknowledge, transmission control six"), 'BEL': (0x07, "bell; alert"), 'BS': (0x08, "backspace, format effector zero"), 'FE0': (0x08, "backspace, format effector zero"), 'HT': (0x09, "horizontal tabulation, format effector one; tab"), 'FE1': (0x09, "horizontal tabulation, format effector one; tab"), 'LF': (0x0a, "linefeed, format effector two; newline (Unix)"), 'NL': (0x0a, "linefeed, format effector two; newline (Unix)"), 'FE2': (0x0a, "linefeed, format effector two; newline (Unix)"), 'VT': (0x0b, "line tabulation, format effector three; vertical tab"), 'LT': (0x0b, "line tabulation, format effector three; vertical tab"), 'FE3': (0x0b, "line tabulation, format effector three; vertical tab"), 'FF': (0x0c, "form feed, format effector four"), 'FE4': (0x0c, "form feed, format effector four"), 'CR': (0x0d, "carriage return, format effector five; enter"), 'FE5': (0x0d, "carriage return, format effector five; enter"), 'SO': (0x0e, "shift out, locking-shift one"), 'LS1': (0x0e, "shift out, locking-shift one"), 'SI': (0x0f, "shift in, locking-shirt zero"), 'LS0': (0x0f, "shift in, locking-shirt zero"), 'DLE': (0x10, "data link escape; transmission control seven"), 'TC7': (0x10, "data link escape; transmission control seven"), 'XON': (0x11, "device control one; xon"), 'DC1': (0x11, "device control one; xon"), 'DC2': (0x12, "device control two"), 'XOFF': (0x13, "device control three; xoff"), 'DC3': (0x13, "device control three; xoff"), 'STOP': (0x14, "device control four; stop"), 'DC4': (0x14, "device control four; stop"), 'NAK': (0x15, "negative acknowledge, transmission control eight"), 'TC8': (0x15, "negative acknowledge, transmission control eight"), 'SYN': (0x16, "synchronous idle, transmission control nine"), 'TC9': (0x16, "synchronous idle, transmission control nine"), 'ETB': (0x17, "end of transmission block, transmission control ten"), 'TC10': (0x17, "end of transmission block, transmission control ten"), 'CAN': (0x18, "cancel"), 'EM': (0x19, "end of medium"), 'SUB': (0x1a, "substitute; end of file (DOS)"), 'ESC': (0x1b, "escape"), 'FS': (0x1c, "file separator, information separator four"), 'IS4': (0x1c, "file separator, information separator four"), 'GS': (0x1d, "group separator, information separator three"), 'IS3': (0x1d, "group separator, information separator three"), 'RS': (0x1e, "record separator, information separator two"), 'IS2': (0x1e, "record separator, information separator two"), 'US': (0x1f, "unit separator, information separator one"), 'IS1': (0x1f, "unit separator, information separator one"), 'SP': (0x20, "space"), 'DEL': (0x7f, "delete"), # C1 (ANSI X3.64, ISO 6429, ECMA-48) 'PAD': (0x80, "padding character"), 'HOP': (0x81, "high octet preset"), 'BPH': (0x82, "break permitted here"), 'NBH': (0x83, "no break here"), 'IND': (0x84, "index"), 'NEL': (0x85, "next line"), 'SSA': (0x86, "start of selected area"), 'ESA': (0x87, "end of selected area"), 'HTS': (0x88, "horizontal/character tabulation set"), 'HTJ': (0x89, "horizontal/character tabulation with justification"), 'VTS': (0x8a, "vertical/line tabulation set"), 'PLD': (0x8b, "partial line down/forward"), 'PLU': (0x8c, "partial line up/backward"), 'RI': (0x8d, "reverse index, reverse line feed"), 'SS2': (0x8e, "single shift two"), 'SS3': (0x8f, "single shift three"), 'DCS': (0x90, "device control string"), 'PU1': (0x91, "private use one"), 'PU2': (0x92, "private use two"), 'STS': (0x93, "set transmission state"), 'CHC': (0x94, "cancel character"), 'MW': (0x95, "message waiting"), 'SPA': (0x96, "start of protected/guarded area"), 'EPA': (0x97, "end of protected/guarded area"), 'SOS': (0x98, "start of string"), 'SGCI': (0x99, "single graphic character introducer, unassigned"), 'SCI': (0x9a, "single character introducer"), 'CSI': (0x9b, "control sequence introducer"), 'ST': (0x9c, "string terminator"), 'OSC': (0x9d, "operating system command"), 'PM': (0x9e, "privacy message"), 'APC': (0x9f, "application program command"), # ISO 8859 'NBSP': (0xa0, "no-break space"), 'SHY': (0xad, "soft hyphen, discretionary hyphen"), # Unicode, general punctuation 'NQSP': (0x2000, "en quad"), 'MQSP': (0x2001, "em quad; mutton quad"), 'ENSP': (0x2002, "en space; nut"), 'EMSP': (0x2003, "em space; mutton"), '3MSP': (0x2004, "three-per-em space; thick space"), '4MSP': (0x2005, "four-per-em space; mid space"), '6MSP': (0x2006, "six-per-em space"), 'FSP': (0x2007, "figure space"), 'PSP': (0x2008, "punctuation space"), 'THSP': (0x2009, "thin space"), 'HSP': (0x200a, "hair space"), 'ZWSP': (0x200b, "zero width space"), 'ZWNJ': (0x200c, "zero width non-joiner"), 'ZWJ': (0x200d, "zero width joiner"), 'LRM': (0x200e, "left-to-right mark"), 'RLM': (0x200f, "right-to-left mark"), 'NBHY': (0x2011, "non-breaking hyphen"), 'LS': (0x2028, "line separator"), 'LSEP': (0x2028, "line separator"), 'PS': (0x2029, "paragraph separator"), 'PSEP': (0x2029, "paragraph separator"), 'LRE': (0x202a, "left-to-right encoding"), 'RLE': (0x202b, "right-to-left encoding"), 'PDF': (0x202c, "pop directional formatting"), 'LRO': (0x202d, "left-to-right override"), 'RLO': (0x202e, "right-to-left override"), 'NNBSP': (0x202f, "narrow no-break space"), 'MMSP': (0x205f, "medium mathematical space"), 'WJ': (0x2060, "word joiner"), 'FA': (0x2061, "function application (`f()`)"), 'IT': (0x2062, "invisible times (`x`)"), 'IS': (0x2063, "invisible separator (`,`)"), 'IP': (0x2064, "invisible plus (`+`)"), 'LRI': (0x2066, "left-to-right isolate"), 'RLI': (0x2067, "right-to-left isolate"), 'FSI': (0x2068, "first strong isolate"), 'PDI': (0x2069, "pop directional isolate"), 'ISS': (0x206a, "inhibit symmetric swapping"), 'ASS': (0x206b, "activate symmetric swapping"), 'IAFS': (0x206c, "inhibit arabic form shaping"), 'AAFS': (0x206d, "activate arabic form shaping"), 'NADS': (0x206e, "national digit shapes"), 'NODS': (0x206f, "nominal digit shapes"), # Geometric shapes (some circles) 'WC': (0x25cb, "white circle"), 'DC': (0x25cc, "dotted circle"), 'CWVF': (0x25cc, "circle with vertical fill"), 'BE': (0x25cc, "bullseye"), # Unicode, CJK symbols and punctuation 'IDSP': (0x3000, "ideographic space"), 'IIM': (0x3005, "ideographic iteration mark"), 'ICM': (0x3006, "ideographic closing mark"), 'INZ': (0x3007, "ideographic number zero"), 'VIIM': (0x303b, "vertical ideographic iteration mark"), 'MASU': (0x303c, "masu mark"), 'PAM': (0x303d, "part alternation mark"), 'IVI': (0x303e, "ideographic variation indicator"), 'IHFSP': (0x303f, "ideograhic half fill space"), # Combining diacritical marks 'CGJ': (0x034f, "combining grapheme joiner"), # Arabic leter forms 'ANS': (0x0600, "Arabic number sign"), 'ASN': (0x0601, "Arabic sign sanah"), 'AFM': (0x0602, "Arabic footnote marker"), 'ASF': (0x0603, "Arabic sign safha"), 'ASM': (0x0604, "Arabic sign samvat"), 'ANMA': (0x0605, "Arabic number mark above"), 'ALM': (0x061c, "Arabic letter mark"), # Unicode, variation selectors 'VS1': (0xfe00, "variation selector 1"), 'VS2': (0xfe01, "variation selector 2"), 'VS3': (0xfe02, "variation selector 3"), 'VS4': (0xfe03, "variation selector 4"), 'VS5': (0xfe04, "variation selector 5"), 'VS6': (0xfe05, "variation selector 6"), 'VS7': (0xfe06, "variation selector 7"), 'VS8': (0xfe07, "variation selector 8"), 'VS9': (0xfe08, "variation selector 9"), 'VS10': (0xfe09, "variation selector 10"), 'VS11': (0xfe0a, "variation selector 11"), 'VS12': (0xfe0b, "variation selector 12"), 'VS13': (0xfe0c, "variation selector 13"), 'VS14': (0xfe0d, "variation selector 14"), 'VS15': (0xfe0e, "variation selector 15; text display"), 'TEXT': (0xfe0e, "variation selector 15; text display"), 'VS16': (0xfe0f, "variation selector 16; emoji display"), 'EMOJI': (0xfe0f, "variation selector 16; emoji display"), # Unicode, Arabic presentation forms 'ZWNBSP': (0xfeff, "zero width no-break space; byte order mark"), 'BOM': (0xfeff, "zero width no-break space; byte order mark"), # Unicode, specials 'IAA': (0xfff9, "interlinear annotation anchor"), 'IAS': (0xfffa, "interlinear annotation separator"), 'IAT': (0xfffb, "interlinear annotation terminator"), 'ORC': (0xfffc, "object replacement character"), 'RC': (0xfffd, "replacement character"), # Egyptian hieroglyph format controls 'EHVJ': (0x13430, "Egyptian hieroglyph vertical joiner"), 'EHHJ': (0x13431, "Egyptian hieroglyph horizontal joiner"), 'EHITS': (0x13432, "Egyptian hieroglyph insert at top start"), 'EHIBS': (0x13433, "Egyptian hieroglyph insert at bottom start"), 'EHITE': (0x13434, "Egyptian hieroglyph insert at top end"), 'EHIBE': (0x13435, "Egyptian hieroglyph insert at bottom end"), 'EHOM': (0x13436, "Egyptian hieroglyph overlay middle"), 'EHBS': (0x13437, "Egyptian hieroglyph begin segment"), 'EHES': (0x13437, "Egyptian hieroglyph end segment"), # Shorthand format controls 'SFLO': (0x1bca0, "shorthand format letter overlap"), 'SFCO': (0x1bca1, "shorthand format continuing overlap"), 'SFDS': (0x1bca2, "shorthand format down step"), 'SFUS': (0x1bca3, "shorthand format up step"), # step 'TAG': (0xe0001, "language tag"), } diacritics = { '`': (0x0300, "grave"), "'": (0x0301, "acute"), '^': (0x0302, "circumflex accent"), '~': (0x0303, "tilde"), '-': (0x0304, "macron"), '_': (0x0305, "overline"), '(': (0x0306, "breve"), '.': (0x0307, "dot"), ':': (0x0308, "diaeresis"), '?': (0x0309, "hook above"), 'o': (0x030a, "ring above"), '"': (0x030b, "double acute accent"), 'v': (0x030c, "caron"), 's': (0x030d, "vertical line above"), 'S': (0x030e, "double vertical line above"), '{': (0x030f, "double grave accent"), '@': (0x0310, "candrabinu"), ')': (0x0311, "inverted breve"), '1': (0x0312, "turned comma above"), '2': (0x0313, "comma above"), '3': (0x0314, "reversed comma above"), '4': (0x0315, "comma above right"), ']': (0x0316, "grave accent below"), '[': (0x0317, "acute accent below"), '<': (0x0318, "left tack below"), '>': (0x0319, "right tack below"), 'A': (0x031a, "left angle above"), 'h': (0x031b, "horn"), 'r': (0x031c, "left half ring below"), 'u': (0x031d, "up tack below"), 'd': (0x031e, "down tack below"), '+': (0x031f, "plus sign below"), 'm': (0x0320, "minus sign below"), 'P': (0x0321, "palatalized hook below"), 'R': (0x0322, "retroflex hook below"), 'D': (0x0323, "dot below"), 'E': (0x0324, "diaeresis below"), 'O': (0x0325, "ring below"), 'c': (0x0326, "comma below"), ',': (0x0327, "cedilla"), 'K': (0x0328, "ogonek"), 'V': (0x0329, "vertical line below"), '$': (0x032a, "bridge below"), 'W': (0x032b, "inverted double arch below"), 'H': (0x032c, "caron below"), 'C': (0x032d, "circumflex accent below"), 'B': (0x032e, "breve below"), 'N': (0x032f, "inverted breve below"), 'T': (0x0330, "tilde below"), 'M': (0x0331, "macron below"), 'l': (0x0332, "low line"), 'L': (0x0333, "double low line"), '&': (0x0334, "tilde overlay"), '!': (0x0335, "short stroke overlay"), '|': (0x0336, "long stroke overlay"), '%': (0x0337, "short solidays overlay"), '/': (0x0338, "long solidus overlay"), 'g': (0x0339, "right half ring below"), '*': (0x033a, "inverted bridge below"), '#': (0x033b, "square below"), 'G': (0x033c, "seagull below"), 'x': (0x033d, "x above"), ';': (0x033e, "vertical tilde"), '=': (0x033f, "double overline"), } icons = { '!': ([0x2757, 0xfe0f], "exclamation mark"), '#': (0x1f6d1, "octagonal sign"), '$': (0x1f4b2, "heavy dollar sign"), '%%': (0x1f3b4, "flower playing cards"), '%': None, '%c': ([0x2663, 0xfe0f], "club suit"), '%d': ([0x2666, 0xfe0f], "diamond suit"), '%e': (0x1f9e7, "red gift envelope"), '%h': ([0x2665, 0xfe0f], "heart suit"), '%j': (0x1f0cf, "joker"), '%r': (0x1f004, "Mahjong red dragon"), '%s': ([0x2660, 0xfe0f], "spade suit"), '&!': ([0x1f396, 0xfe0f], "military medal"), '&$': (0x1f3c6, "trophy"), '&': None, '&0': (0x1f3c5, "sports medal"), '&1': (0x1f947, "first place medal"), '&2': (0x1f948, "second place medal"), '&3': (0x1f949, "third place medal"), '*': ([0x2a, 0xfe0f], "asterisk"), '+': (0x1f53a, "red triangle pointed up"), ',': None, ',+': (0x1f44d, "thumbs up"), ',-': (0x1f44e, "thumbs down"), ',a': ([0x261d, 0xfe0f], "point above"), ',d': (0x1f447, "point down"), ',f': (0x1f44a, "oncoming fist"), ',l': (0x1f448, "point left"), ',o': (0x1faf5, "point out"), ',r': (0x1f449, "point right"), ',s': (0x1f91d, "handshake"), ',u': (0x1f446, "point up"), '-': (0x1f53b, "red triangle pointed down"), '.': None, '.d': ([0x2b07, 0xfe0f], "down arrow"), '.l': ([0x2b05, 0xfe0f], "left arrow"), '.r': ([0x27a1, 0xfe0f], "right arrow"), '.u': ([0x2b06, 0xfe0f], "up arrow"), '/': ([0x2714, 0xfe0f], "check mark"), ':$': (0x1f911, "money-mouth face"), ':': None, ':(': (0x1f61e, "disappointed face"), ':)': (0x1f600, "grinning face"), ':*': (0x1f618, "face blowing a kiss"), ':/': (0x1f60f, "smirking face"), ':0': (0x1f636, "face without mouth"), ':1': (0x1f914, "thinking face"), ':2': (0x1f92b, "shushing face"), ':3': (0x1f617, "kissing face"), ':4': (0x1f605, "grinning face with sweat"), ':5': (0x1f972, "smiling face with tear"), ':6': (0x1f602, "face with tears of joy"), ':7': (0x1f917, "smiling face with open hands"), ':8': (0x1f910, "zipper-mouth face"), ':9': (0x1f923, "rolling on the floor laughing"), ':<': None, ':<3': ([0x2764, 0xfe0f], "red heart"), ':D': (0x1f601, "beaming face with smiling eyes"), ':O': (0x1f62f, "hushed face"), ':P': (0x1f61b, "face with tongue"), ':S': (0x1fae1, "saluting face"), ':T': (0x1f62b, "tired face"), ':Y': (0x1f971, "yawning face"), ':Z': (0x1f634, "sleeping face"), ':[': (0x1f641, "frowning face"), ':\\': (0x1f615, "confused face"), ':]': ([0x263a, 0xfe0f], "smiling face"), ':|': (0x1f610, "neutral face"), ';': None, ';)': (0x1f609, "winking face"), '<': (0x23ea, "black left-pointing double triangle"), '=': None, '=*': ([0x2716, 0xfe0f], "heavy multiplication sign"), '=+': ([0x2795, 0xfe0f], "heavy plus sign"), '=-': ([0x2796, 0xfe0f], "heavy minus sign"), '=/': ([0x2797, 0xfe0f], "heavy division sign"), '>': (0x23e9, "black right-pointing double triangle"), '?': ([0x2753, 0xfe0f], "question mark"), 'B': None, 'B)': (0x1f60e, "smiling face with sunglasses"), 'E': (0x2130, "script capital E"), 'F': (0x2131, "script capital F"), 'M': (0x2133, "script capital M"), '\"': None, '\"(': (0x201c, "left double quotation mark"), '\")': (0x201d, "right double quotation mark"), '\"\"': (0x22, "quotation mark"), '\'': None, '\'(': (0x2018, "left single quotation mark"), '\')': (0x2019, "right single quotation mark"), '\'/': (0xb4, "acute accent"), '\'\'': (0x27, "apostrophe"), '\'\\': (0x60, "grave accent"), '\\': ([0x274c, 0xfe0f], "cross mark"), '^': ([0x26a0, 0xfe0f], "warning sign"), '{!!': None, '{!!}': ([0x203c, 0xfe0f], "double exclamation mark"), '{!': None, '{!?': None, '{!?}': ([0x2049, 0xfe0f], "exclamation question mark"), '{': None, '{(': None, '{()': None, '{()}': (0x1f534, "red circle"), '{[': None, '{[]': None, '{[]}': (0x1f7e5, "red square"), '{{': None, '{{}': None, '{{}}': ([0x2b55, 0xfe0f], "hollow red circle"), '|': (0x1f346, "aubergine"), '~': ([0x3030, 0xfe0f], "wavy dash"), } emojis = {} def __init__(self, **kwargs): self._initialized = False # Meta variables. self._names = [] self._specs = {} self._initials = {} self._descriptions = {} self._nones = {} self._functions = {} # Initialize. self.initialize() # Mark initialized. self._initialized = True # Update with any keyword arguments, if specified. self.update(**kwargs) def __setattr__(self, name, value): self.set(name, value) def __contains__(self, name): return name in self.__dict__ def __bool__(self): return self._initialized # 3.x def __nonzero__(self): return self._initialized # 2.x def __iter__(self): return iter(self._names) def __str__(self): results = [] for name in self._names: results.append("%s=%r" % (name, self.get(name))) return ', '.join(results) # Initialization. def initialize(self): """Setup the declarations and definitions for the defined attributes.""" self.define('name', strType, self.defaultName, "The name of this configuration (optional)") self.define('notes', None, None, "Notes for this configuration (optional)") self.define('prefix', strType, self.defaultPrefix, "The prefix", none=True, env=PREFIX_ENV) self.define('pseudomoduleName', strType, self.defaultPseudomoduleName, "The pseudomodule name", env=PSEUDO_ENV) self.define('verbose', bool, False, "Verbose processing (for debugging)?") self.define('rawErrors', bool, None, "Print Python stacktraces on error?", env=RAW_ERRORS_ENV) self.define('verboseErrors', bool, True, "Show attributes in error messages?") self.define('exitOnError', bool, True, "Exit after an error?") self.define('ignoreErrors', bool, False, "Ignore errors?") self.define('contextFormat', strType, self.defaultContextFormat, "Context format") self.define('goInteractive', bool, None, "Go interactive after done processing?", env=INTERACTIVE_ENV) self.define('deleteOnError', bool, None, "Delete output file on error?", env=DELETE_ON_ERROR_ENV) self.define('doFlatten', bool, None, "Flatten pseudomodule members at start?", env=FLATTEN_ENV) self.define('useProxy', bool, None, "Install a stdout proxy?", env=NO_PROXY_ENV, invert=True) self.define('relativePath', bool, False, "Add EmPy script path to sys.path?") self.define('buffering', int, self.defaultBuffering, "Specify buffering strategy for files:\n0 (none), 1 (line), -1 (full), or N", env=BUFFERING_ENV, func=self.setBuffering) self.define('replaceNewlines', bool, False, "Replace newlines with spaces in expressions?") self.define('ignoreBangpaths', bool, True, "Treat bangpaths as comments?") self.define('noneSymbol', strType, None, "String to write when expanding None", none=True) self.define('missingConfigIsError', bool, True, "Is a missing configuration file an error?") self.define('pauseAtEnd', bool, False, "Prompt at the end of processing?") self.define('startingLine', int, 1, "Line number to start with") self.define('startingColumn', int, 1, "Column number to start with") self.define('significatorDelimiters', tuple, self.defaultSignificatorDelimiters, "Significator variable delimiters") self.define('emptySignificator', object, self.defaultEmptySignificator, "Value to use for empty significators", none=True) self.define('autoValidateIcons', bool, self.defaultAutoValidateIcons, "Automatically validate icons before each use?") self.define('emojiModuleNames', list, self.defaultEmojiModuleNames, "List of emoji modules to try to use\n", none=True) self.define('emojiNotFoundIsError', bool, True, "Is an unknown emoji an error?") self.define('useBinary', bool, False, "Open files as binary (Python 2.x Unicode)?", env=BINARY_ENV) defaultEncoding = self.environment(ENCODING_ENV, self.getDefaultEncoding()) self.define('inputEncoding', strType, defaultEncoding, "Set input Unicode encoding", none=True, env=INPUT_ENCODING_ENV, helpFunction=lambda x: x == 'utf_8' and 'utf-8' or x) self.define('outputEncoding', strType, defaultEncoding, "Set output Unicode encoding", none=True, env=OUTPUT_ENCODING_ENV, helpFunction=lambda x: x == 'utf_8' and 'utf-8' or x) defaultErrors = self.environment(ERRORS_ENV, self.defaultErrors) self.define('inputErrors', strType, defaultErrors, "Set input Unicode error handler", none=True, env=INPUT_ERRORS_ENV) self.define('outputErrors', strType, defaultErrors, "Set output Unicode error handler", none=True, env=OUTPUT_ERRORS_ENV) self.define('normalizationForm', strType, self.defaultNormalizationForm, "Specify Unicode normalization form", none=True) self.define('autoPlayDiversions', bool, True, "Auto-play diversions on exit?") self.define('expandUserConstructions', bool, True, "Expand ~ and ~user constructions") self.define('configVariableName', strType, self.defaultConfigVariableName, "Configuration variable name while loading") self.define('successCode', int, self.defaultSuccessCode, "Exit code to return on script success") self.define('failureCode', int, self.defaultFailureCode, "Exit code to return on script failure") self.define('unknownCode', int, self.defaultUnknownCode, "Exit code to return on bad configuration") self.define('skipCode', int, self.defaultSkipCode, "Exit code to return on requirements failure (testing") self.define('checkVariables', bool, True, "Check configuration variables on assignment?") self.define('pathSeparator', strType, sys.platform.startswith('win') and ';' or ':', "Path separator for configuration file paths") self.define('supportModules', bool, True, "Support EmPy modules?") self.define('moduleExtension', strType, self.defaultModuleExtension, "Filename extension for EmPy modules") self.define('moduleFinderIndex', int, 0, "Index of module finder in meta path") self.define('enableImportOutput', bool, True, "Disable output during import?") self.define('duplicativeFirsts', list, list(DUPLICATIVE_CHARS), "List of duplicative first characters") self.define('openFunc', None, None, "The open function to use (None for automatic)") # Redefine static configuration variables so they're in the help. self.define('controls', dict, self.controls, "Controls dictionary") self.define('diacritics', dict, self.diacritics, "Diacritics dictionary") self.define('icons', dict, self.icons, "Icons dictionary") self.define('emojis', dict, self.emojis, "Emojis dictionary") # If the encoding or error handling has changed, enable binary # implicitly, just as if it had been specified on the command line. if (self.inputEncoding != defaultEncoding or self.outputEncoding != defaultEncoding or self.inputErrors != defaultErrors or self.outputErrors != defaultErrors): self.enableBinary(major, minor) def isInitialized(self): """Is this configuration initialized and ready for use?""" return self._initialized def check(self, inputFilename, outputFilename): """Do a sanity check on the configuration settings.""" if self.prefix == '' or self.prefix == 'none' or self.prefix == 'None': self.prefix = None if self.buffering is None: self.buffering = self.defaultBuffering if isinstance(self.prefix, strType) and len(self.prefix) != 1: raise ConfigurationError("prefix must be single-character string") if not self.pseudomoduleName: raise ConfigurationError("pseudomodule name must be non-empty string") if self.deleteOnError and outputFilename is None: raise ConfigurationError("-d only makes sense with -o, -a, -O or -A arguments") if self.hasNoBuffering() and not self.hasBinary(): raise ConfigurationError("no buffering requires file open in binary mode; try adding -u option") # Access. def declare(self, name, specs, initial, description, none=False, helpFunction=None): """Declare the configuration attribute.""" self._names.append(name) self._specs[name] = specs self._initials[name] = initial self._descriptions[name] = description self._nones[name] = none self._functions[name] = helpFunction def define(self, name, specs, value, description, none=False, env=None, func=None, blank=None, invert=False, helpFunction=None): """Define a configuration attribute with the given name, type specification, initial value, and description. If none is true, None is a legal value. Also, allow an optional corresponding environment variable, and, if present, an optional blank variable to set the value to if the environment variable is defined but is blank. If both env and func are present, call the function to set the environment variable. Finally, if invert is true, invert the (bool) environment variable. Additionally, if the type specification is or contains toString, convert the value to a proper string.""" if isinstance(specs, tuple): isString = str in specs or bytes in specs else: isString = str is specs or bytes is specs if value is not None and specs is not None: assert isinstance(value, specs), (value, specs) if env is not None: if func is not None: if self.hasEnvironment(env): value = func(self.environment(env, value)) elif isString: value = self.environment(env, value, blank) elif specs is bool: value = self.hasEnvironment(env) if invert: value = not value elif not isinstance(specs, tuple): value = specs(self.environment(env, value, blank)) else: assert False, "environment attribute type must be bool or str: `%s`" % name if isString and value is not None: value = toString(value) self.declare(name, specs, value, description, none, helpFunction) self.set(name, value) def has(self, name): """Is this name a valid configuration attribute?""" return name in self.__dict__ or name in self.__class__.__dict__ def get(self, name, default=None): """Get this (valid, existing) configuration attribute.""" return getattr(self, name, default) def set(self, name, value): """Set the (valid) configuration attribute, checking its type if necessary.""" if self._initialized and self.checkVariables: if not name.startswith('_'): # If this attribute is not already present, it's invalid. if not self.has(name): raise ConfigurationError("unknown configuration attribute: `%s`" % name) # If there's a registered type for this attribute, check it. specs = self._specs.get(name) if specs is not None: if value is None: if not self._nones[name]: raise ConfigurationError("configuration value cannot be None: `%s`: `%s`; `%s`" % (name, value, specs)) elif not isinstance(value, specs): raise ConfigurationError("configuration value has invalid type: `%s`: `%s`; `%s`" % (name, value, specs)) self.__dict__[name] = value def update(self, **kwargs): """Update the configuration by keyword arguments.""" for name, value in kwargs.items(): if not self.has(name): raise ConfigurationError("unknown configuration attribute: `%s`" % name) self.set(name, value) def clone(self, deep=False): """Create a distinct copy of this configuration. Make it deep if desired.""" if deep: copyMethod = copy.deepcopy else: copyMethod = copy.copy return copyMethod(self) # Configuration file loading. def run(self, statements): """Run some configuration variable assignment statements.""" locals = {self.configVariableName: self} execFunc(statements, globals(), locals) keys = list(locals.keys()) # Put the priority variables first. for priority in self.priorityVariables: if priority in locals: keys.remove(priority) keys.insert(0, priority) for key in keys: if not key.startswith('_') and key != self.configVariableName: setattr(self, key, locals[key]) return True def load(self, filename, required=None): """Update the configuration by loading from a resource file. If required is true, raise an exception; if false, ignore; if None, use the default in this configuration. Return whether or not the load succeeded.""" if required is None: required = self.missingConfigIsError try: file = self.open(filename, 'r') except IOError: if required: raise ConfigurationFileNotFoundError("cannot open configuration file: %s" % filename, filename) return False try: contents = file.read() return self.run(contents) finally: file.close() def path(self, path, required=None): """Attempt to load several resource paths, either as a list of paths or a delimited string of paths. If required is true, raise an exception; if false, ignore; if None, use the default in this configuration.""" if isinstance(path, list): filenames = path else: filenames = path.split(self.pathSeparator) for filename in filenames: self.load(filename, required) # Environment. def hasEnvironment(self, name): """Is the current environment variable defined in the environment? The value does not matter.""" return name in os.environ def environment(self, name, default=None, blank=None): """Get the value of the given environment variable, or default if it is not set. If a variable is set to an empty value and blank is non-None, return blank instead.""" if name in os.environ: value = os.environ[name] if not value and blank is not None: return blank else: return value else: return default # Convenience. def recode(self, result, encoding=None): """Convert a lookup table entry into a string. A value can be a string itself, an integer corresponding to a code point, or a 2-tuple, the first value of which is one of the above (the second is a description). If the encoding is provided, use that to convert bytes objects; otherwise, use the output encoding.""" assert result is not None # First, if it's a tuple, then use the first element; the remaining # elements are a description. if isinstance(result, tuple): result = result[0] # Check the type of the value: if isinstance(result, list): # If it's a list, then it's a sequence of some the above. # Turn them all into strings and then concatenate them. fragments = [] for elem in result: fragments.append(self.recode(elem)) result = ''.join(fragments) elif isinstance(result, str): # It's already a string, so do nothing. pass elif isinstance(result, bytes): # If it's a bytes, decode it. if encoding is None: encoding = self.outputEncoding result = result.decode(encoding) elif isinstance(result, int): # If it's an int, then it's a character code. result = chr(result) elif callable(result): # If it's callable, then call it. result = self.recode(result()) else: # Otherwise, it's something convertible to a string. result = str(result) return result def escaped(self, ord, prefix='\\'): """Write a valid Python string escape sequence for the given character ordinal.""" if ord <= 0xff: return '%sx%02x' % (prefix, ord) elif ord <= 0xffff: return '%su%04x' % (prefix, ord) else: return '%sU%08x' % (prefix, ord) def hasDefaultPrefix(self): """Is this configuration's prefix the default or non-existent?""" return self.prefix is None or self.prefix == self.defaultPrefix # Buffering. def hasFullBuffering(self): return self.buffering <= self.fullBuffering def hasNoBuffering(self): return self.buffering == self.noBuffering def hasLineBuffering(self): return self.buffering == self.lineBuffering def hasFixedBuffering(self): return self.buffering is not None and self.buffering > self.lineBuffering def setBuffering(self, name): """Set the buffering by name or value.""" if isinstance(name, int): self.buffering = name elif name == 'none': self.buffering = self.noBuffering elif name == 'line': self.buffering = self.lineBuffering elif name == 'full': self.buffering = self.fullBuffering elif name is None or name == 'default' or name == '': self.buffering = self.defaultBuffering else: try: self.buffering = int(name) except ValueError: raise ConfigurationError("invalid buffering name: `%s`" % name) if self.buffering < self.fullBuffering: self.buffering = self.fullBuffering return self.buffering # Token factories. def createFactory(self, tokens=None): """Create a token factory and return it.""" if tokens is None: tokens = self.tokens return Factory(tokens) def adjustFactory(self): """Adjust the factory to take into account a non-default prefix.""" self.factory.adjust(self) def getFactory(self, tokens=None, force=False): """Get a factory (creating one if one has not yet been created). If force is true, always create a new one.""" if self.factory is None or force: self.factory = self.createFactory(tokens) self.adjustFactory() return self.factory def resetFactory(self): """Clear the current factory.""" self.factory = None def createExtensionToken(self, first, name, last=None): if last is None: last = ENDING_CHAR_MAP.get(first[0], first[0]) newType = type('ExtensionToken:' + first[:1], (ExtensionToken,), {'first': first, 'last': last, 'name': name}) return newType # Binary/Unicode. def hasBinary(self): """Is binary/Unicode file open support enabled?""" return self.useBinary def enableBinary(self, major=None, minor=None): """Enable binary/Unicode file open support. This is needed in Python 2.x for Unicode support. If major/minor is present, only enable it implicitly if this is in fact Python 2.x.""" if major is None or major == 2: self.useBinary = True def disableBinary(self): """Disable binary/Unicode support for this configuration.""" self.useBinary = False # File I/O. def isDefaultEncodingErrors(self, encoding=None, errors=None, asInput=True): """Are both of the encoding/errors combinations the default? If either passed value is None the value in this configuration is what is checked. Check for input if asInput is true; otherwise check output.""" if encoding is None: if asInput: encoding = self.inputEncoding else: encoding = self.outputEncoding if encoding is not None and encoding != self.getDefaultEncoding(): return False if errors is None: if asInput: errors = self.inputErrors else: errors = self.outputErrors if errors is not None and errors != self.defaultErrors: return False return True def getDefaultEncoding(self, default='unknown'): """What is the default encoding?""" try: return sys.getdefaultencoding() except AttributeError: return default def determineOpenFunc(self, filename, mode=None, buffering=-1, encoding=None, errors=None): """Determine which openFunc to use if it has not already been specified and return it.""" if self.openFunc is None: if self.useBinary: # Use binary mode, so call binaryOpen. self.openFunc = binaryOpen else: if major >= 3: # If it's Python 3.x, just use open. self.openFunc = open else: # For Python 2.x, open doesn't take encoding and error # handler arguments. Check to make sure non-default # encodings and error handlers haven't been chosen, because # we can't comply. if not self.isDefaultEncodingErrors(encoding, errors): raise ConfigurationError("cannot comply with non-default Unicode encoding/errors selected in Python 2.x; use -u option: `%s`/`%s`" % (encoding, errors)) self.openFunc = open assert self.openFunc is not None return self.openFunc def isModeBinary(self, mode): """Does this mode represent binary mode?""" return 'b' in mode def open(self, filename, mode=None, buffering=-1, encoding=None, errors=None, expand=None): """Open a new file, handling whether or not binary (Unicode) should be employed. Raise if the selection cannot be complied with. Arguments: - filename: The filename to open (required); - mode: The file open mode, None for read; - buffering: The buffering setting (int); - encoding: The encoding to use, None for default; - errors: The error handler to use, None for default; - expand: Expand user constructions? (~ and ~user)""" if expand is None: expand = self.expandUserConstructions if expand: filename = os.path.expanduser(filename) if mode is None: # Default to read. mode = 'r' if self.useBinary and not self.isModeBinary(mode): # Make it binary if it needs to be. mode += 'b' # Figure out the encoding and error handler. if 'w' in mode or 'a' in mode: if encoding is None: encoding = self.outputEncoding if errors is None: errors = self.outputErrors else: if encoding is None: encoding = self.inputEncoding if errors is None: errors = self.inputErrors func = self.determineOpenFunc( filename, mode, buffering, encoding, errors) try: return func(filename, mode=mode, buffering=buffering, encoding=encoding, errors=errors) except TypeError: # Some older versions of the open functions (e.g., Python 2.x's # open) do not accept the Unicode encoding and errors arguments. # Try again. return func(filename, mode=mode, buffering=buffering) def reconfigure(self, file, buffering=-1, encoding=None, errors=None): """Reconfigure an existing file (e.g., sys.stdout)) with the same arguments as open.""" try: if buffering == 1: file.reconfigure(encoding=encoding, errors=errors, line_buffering=True) else: file.reconfigure(encoding=encoding, errors=errors) except (AssertionError, AttributeError): raise InvocationError("non-default Unicode output encoding/errors selected with %s; use -o/-a option instead: %s/%s" % (file.name, encoding, errors)) # Significators. def significatorReString(self): """Return a string that can be compiled into a regular expression representing a significator. If multi is true, it will match multiline significators.""" return self.prefix + self.significatorReStringSuffix def significatorRe(self, flags=re.MULTILINE|re.DOTALL, baseFlags=re.VERBOSE): """Return a regular expression object with the given flags that is suitable for parsing significators.""" return re.compile(self.significatorReString(), flags|baseFlags) def significatorFor(self, key): """Return the significator name for this key.""" prefix, suffix = self.significatorDelimiters return prefix + toString(key) + suffix # Contexts. def setContextFormat(self, rawFormat): """Set the context format, auto-detecting which mechanism to use.""" useFormatMethod = None format = rawFormat if format.startswith('format:'): useFormatMethod = True format = format.split(':', 1)[1] elif format.startswith('operator:'): useFormatMethod = False format = format.split(':', 1)[1] elif format.startswith('variable:'): useFormatMethod = False format = format.split(':', 1)[1] format = format.replace('$NAME', '%(name)s') format = format.replace('$LINE', '%(line)d') format = format.replace('$COLUMN', '%(column)d') format = format.replace('$CHARS', '%(chars)d') else: useFormatMethod = '%' not in format self.contextFormat = format self.useContextFormatMethod = useFormatMethod def renderContext(self, context): """Render the context as a string according to this configuration.""" if self.useContextFormatMethod is None: self.setContextFormat(self.contextFormat) return context.render(self.contextFormat, self.useContextFormatMethod) # Icons. def calculateIconsSignature(self, icons=None): """Calculate a signature of the icons dict. If the value changes, it's likely (but not certain) that the underlying dict has changed. The signature will always differ from None.""" if icons is None: icons = self.icons length = len(icons) try: # Include the size of the dictionary, if possible. If it's not # available, that's okay. sizeof = sys.getsizeof(icons) except (AttributeError, TypeError): sizeof = -1 return length, sizeof def signIcons(self, icons=None): """Sign the icons dict.""" self.iconsSignature = self.calculateIconsSignature(icons) return self.iconsSignature def transmogrifyIcons(self, icons=None): """Process the icons and make sure any keys' prefixes are backfilled with Nones. Call this method after modifying icons.""" if icons is None: icons = self.icons additions = {} for parent in icons.keys(): key = parent while len(key) > 1: key = key[:-1] if key in icons: value = icons[key] if value is None: continue else: raise ConfigurationError("icon `%s` makes icon `%s` inaccessible" % (key, parent)) else: additions[key] = None icons.update(additions) return icons def validateIcons(self, icons=None): """If the icons have not been transmogrified yet, do so and store their signature for future reference.""" if icons is None: icons = self.icons if icons is None: raise ConfigurationError("icons not configured") if not self.autoValidateIcons: return icons if self.iconsSignature is None: self.transmogrifyIcons(icons) self.signIcons(icons) return icons # Emojis. def initializeEmojiModules(self, moduleNames=None): """Initialize the emoji modules. If moduleNames is not specified, check the defaults. Idempotent.""" if self.emojiModules is None: okNames = [] # Use the config default if not specified. if moduleNames is None: moduleNames = self.emojiModuleNames # If it's still blank, specify no modules. if moduleNames is None: moduleNames = [] # Create a map of module names for fast lookup. (This would be a # set, but sets aren't available in early versions of Python 2.x.) nameMap = {} for moduleName in moduleNames: nameMap[moduleName] = None # Now iterate over each potential module. self.emojiModules = {} for info in self.emojiModuleInfos: moduleName = info[0] if moduleName in nameMap: module = EmojiModuleInfo(*info) if module.ok: okNames.append(moduleName) self.emojiModules[moduleName] = module # Finally, replace the requested module names with the ones # actually present. self.emojiModuleNames = okNames if not self.emojiModules and not self.emojis: raise ConfigurationError("no emoji lookup methods available; install modules and set emoji modules or set emojis dictionary in configuration") def substituteEmoji(self, text): """Substitute emojis from the provided string. Return the resulting substitution or None.""" text = text.replace('\n', ' ') self.initializeEmojiModules() for moduleName in self.emojiModuleNames: module = self.emojiModules[moduleName] result = module.substitute(text) if result is not None: return result # Exit codes and errors. def isSuccessCode(self, code): """Does this exit code indicate success?""" return code == self.successCode def isExitError(self, error): """Is this error a SystemExit?""" return isinstance(error, SystemExit) def errorToExitCode(self, error): """Determine the exit code (can be a string) from the error. If the error is None, then it is success.""" if error is None: return self.successCode isExit = self.isExitError(error) if isExit: if len(error.args) == 0: return self.successCode else: # This can be a string which is okay. return error.args[0] else: return self.failureCode def isNotAnError(self, error): """Is this error None (no error) or does it indicate a successful exit?""" if error is None: return True else: return self.isSuccessCode(self.errorToExitCode(error)) def formatError(self, error, prefix=None, suffix=None): """Format an error into a string for printing.""" parts = [] if prefix is not None: parts.append(prefix) parts.append(error.__class__.__name__) if self.verboseErrors: # Find the error's arguments. This needs special treatment due to # spurious Java exceptions leaking through under Jython. args = getattr(error, 'args', None) if args is None: # It might be an unwrapped Java exception. Check for # getMessage. method = getattr(error, 'getMessage', None) if method is not None: args = (method(),) else: # Otherwise, not sure what this is; treat it as having no # arguments. args = () # Check for arguments. if len(args) > 0: parts.append(": ") parts.append(", ".join([toString(x) for x in args])) # Check for keyword arguments. pairs = [] for attrib in dir(error): if (attrib not in self.ignorableErrorAttributes and not attrib.startswith('_')): value = getattr(error, attrib, None) if value is not None: pairs.append((attrib, value)) if pairs: parts.append("; ") pairs.sort() kwargs = [] for key, value in pairs: kwargs.append("%s=%s" % (key, value)) parts.append(', '.join(kwargs)) # Fold the arguments together. if suffix is not None: parts.append(suffix) return ''.join(parts) # Proxy. @staticmethod def proxy(object=sys): """Find the proxy for this Python interpreter session, or None.""" return getattr(object, '_EmPy_proxy', None) @staticmethod def evocare(increment=0, ignore=True): """Try to call the EmPy special method on the proxy with the given increment argument and return the resulting count value. If the magic method is not present (no proxy installed) and ignore is true (default), return None; otherwise, raise. Exodus is four as one!""" method = getattr(Configuration.proxy(), '_EmPy_evocare', None) if method is not None: try: return method(increment) except: raise ProxyError("proxy evocare method should not raise") else: if ignore: return None else: raise ProxyError("proxy evocare method not found") def installProxy(self, output): """Install a proxy if necessary around the given output, wrapped to be uncloseable. Return the wrapped object (not the proxy).""" assert output is not None # Invoke the special method ... count = self.evocare(+1) proxy = self.proxy() if count is not None: # ... and if it's present, we've already created it. new = False else: if proxy is None: # If not, setup the proxy, and increment the reference count. proxy = sys._EmPy_proxy = ProxyFile(output, self.proxyWrapper) if self.useProxy: # Replace sys.stdout with the proxy. sys.stdout = proxy self.evocare(+1) else: # ... but if the count showed no proxy but there is one, # something went wrong. raise ProxyError("proxy conflict; no proxy registered but one found") new = True if not self.useProxy: output = UncloseableFile(output) return output def uninstallProxy(self): """Uninstall a proxy if necessary.""" # Try decrementing the reference count; if it hits zero, it will # automatically remove itself and restore sys.stdout. try: proxy = self.proxy() done = not self.evocare(-1) if done: del sys._EmPy_proxy except AttributeError: if self.proxy() is not None: raise ProxyError("proxy lost") def checkProxy(self, abandonedIsError=True): """Check whether a proxy is installed. Returns the current reference count (positive means one is installed), None (for no proxy installed), or 0 if the proxy has been abandoned. Thus, true means a proxy is installed, false means one isn't. If abandonIsError is true, raise instead of returning 0 on abandonment.""" if not self.useProxy: return False count = self.evocare(0) if count is not None: if count == 0 and abandonedIsError: raise ProxyError("stdout proxy abandoned; proxy present but with zero reference count: %r" % sys.stdout) return count else: return None # Meta path finder (for module support). @staticmethod def finder(object=sys): """Find the meta path finder for this Python interpreter session, if there is one.""" return getattr(object, '_EmPy_finder', None) def createFinder(self): """Create a new finder object, ready for installation.""" # Use the importlib architecture to set up an EmPy path finder. import importlib import importlib.abc import importlib.util # # Loader # class Loader(importlib.abc.Loader): def __init__(self, filename): self.filename = filename def create_module(self, spec): return None # default def exec_module(self, module): interp = sys.stdout._EmPy_current() assert interp interp.import_(self.filename, module) # # Finder # class Finder(importlib.abc.PathEntryFinder): _EmPy_next = 1 def __init__(self): self._EmPy_tag = self._EmPy_next self.__class__._EmPy_next += 1 def __str__(self): return '%s [tag %d]' % ( self.__class__.__name__, self._EmPy_tag) def find_spec(self, fullname, path, target=None): # If the proxy is not installed, skip. method = getattr(sys.stdout, '_EmPy_current', None) if not method: return None interp = method() # If there's no active interpreter, also skip. if not interp: return None # If this interpreter has modules disable, also skip. if not interp.config.supportModules: return None if not path: path = sys.path import os name = fullname.replace('.', os.sep) for dirname in path: filename = (os.path.join(dirname, name) + interp.config.moduleExtension) if os.path.isfile(filename): return importlib.util.spec_from_file_location( fullname, filename, loader=Loader(filename)) return None return Finder() def installFinder(self, index=None, dryRun=False): """Install EmPy module support, if possible. Mark a flag the first time this is called so it's only installed once, if ever. Idempotent.""" if Configuration.finder(): # A finder had already been installed; abort. return None if not self.supportModules or not self.moduleExtension: # This configuration does not want to support mnodules; abort. return None if not modules: # Modules are not supported by the underlying interpreter; abort. return None if dryRun: # This is a dry run for displaying details; abort. return None # Create the finder. finder = self.createFinder() # Register it with this configuration. self.tag = finder._EmPy_tag # And install it. if index is None: index = self.moduleFinderIndex if index < 0: sys.meta_path.append(finder) else: sys.meta_path.insert(index, finder) # Register it with the sys module. sys._EmPy_finder = finder return finder def uninstallFinder(self, tag=None): """Uninstall any module meta path finder for EmPy support, either by tag (if not None), or all. Idempotent.""" if sys.meta_path is not None: newMetaPath = [] for finder in sys.meta_path: finderTag = getattr(finder, '_EmPy_tag', None) if tag is None: # Delete any custom finder. if finderTag is not None: continue else: # Delete only the matching finder. if finderTag == tag: continue # If we're still here, we're keeping this finder. newMetaPath.append(finder) sys.meta_path = newMetaPath # Debugging. def printTraceback(self, file=sys.stderr): import types, traceback tb = None depth = 0 while True: try: frame = sys._getframe(depth) depth += 1 except ValueError: break tb = types.TracebackType(tb, frame, frame.f_lasti, frame.f_lineno) traceback.print_tb(tb, file=file) # # Version # class Version(Root): """An enumerated type representing version detail levels.""" NONE, VERSION, INFO, BASIC, PYTHON, SYSTEM, PLATFORM, RELEASE, ALL = range(9) DATA = BASIC # # Stack # class Stack(Root): """A simple stack that is implemented as a sequence.""" def __init__(self, seq=None): if seq is None: seq = [] self.data = seq def __bool__(self): return len(self.data) != 0 # 3.x def __nonzero__(self): return len(self.data) != 0 # 2.x def __len__(self): return len(self.data) def __getitem__(self, index): return self.data[-(index + 1)] def __str__(self): return '[%s]' % ', '.join([repr(x) for x in self.data]) def top(self): """Access the top element on the stack.""" if self.data: return self.data[-1] else: raise StackUnderflowError("stack is empty for top") def pop(self): """Pop the top element off the stack and return it.""" if self.data: return self.data.pop() else: raise StackUnderflowError("stack is empty for pop") def push(self, object): """Push an element onto the top of the stack.""" self.data.append(object) def replace(self, object): """Replace the top element of the stack with another one.""" if self.data: self.data[-1] = object else: raise StackUnderflowError("stack is empty for replace") def filter(self, function): """Filter the elements of the stack through the function.""" self.data = list(filter(function, self.data)) def purge(self, function=None): """Purge the stack, calling an optional function on each element first from top to bottom.""" if function is None: self.data = [] else: while self.data: element = self.data.pop() function(element) def clone(self): """Create a duplicate of this stack.""" return self.__class__(self.data[:]) # # File ... # class File(Root): """An abstract filelike object.""" def __enter__(self): pass def __exit__(self, *exc): self.close() def write(self, data): raise NotImplementedError def writelines(self, lines): raise NotImplementedError def flush(self): raise NotImplementedError def close(self): raise NotImplementedError class NullFile(File): """A simple class that supports all the file-like object methods but simply does nothing at all.""" def write(self, data): pass def writelines(self, lines): pass def flush(self): pass def close(self): pass class DelegatingFile(File): """A simple class which wraps around a delegate file-like object and lets everything through.""" def __init__(self, delegate): self.delegate = delegate def __repr__(self): return '<%s : %r @ 0x%x>' % ( self.__class__.__name__, self.delegate, id(self)) def write(self, data): self.delegate.write(data) def writelines(self, lines): self.delegate.writelines(lines) def flush(self): self.delegate.flush() def close(self): self.delegate.close() self.unlink() def unlink(self): """Unlink from the delegate.""" self.delegate = None class UncloseableFile(DelegatingFile): """A delegating file class that lets through everything except close calls, which it turns into a flush.""" def close(self): self.flush() class ProxyFile(File): """The proxy file object that is intended to take the place of sys.stdout. The proxy can manage a stack of interpreters (and their file object streams) it is writing to, and an underlying bottom file object.""" def __init__(self, bottom, wrapper=None): """Create a new proxy file object with bottom as the underlying stream. If wrapper is not None (and is an instance of (a subclass of) a DelegatingFile), we should wrap and unwrap the bottom file with it for protection.""" assert bottom is not None self._EmPy_original = sys.stdout self._EmPy_count = 0 self._EmPy_stack = Stack() self._EmPy_bottom = bottom self._EmPy_wrapper = wrapper self._EmPy_wrap() def __del__(self): self.finalize() def __str__(self): return '%s [count %d, depth %d]'% ( self.__class__.__name__, self._EmPy_count, len(self._EmPy_stack)) def __repr__(self): return '<%s [count %d, depth %d] : %r @ 0x%x>' % ( self.__class__.__name__, self._EmPy_count, len(self._EmPy_stack), self._EmPy_bottom, id(self)) def __getattr__(self, name): return getattr(self._EmPy_top(), name) # Finalizer. def finalize(self): pass # File methods. def write(self, data): self._EmPy_top().write(data) def writelines(self, lines): self._EmPy_top().writelines(lines) def flush(self): top = self._EmPy_top() assert top is not None top.flush() def close(self): """Close the current file. If the current file is the bottom, then flush it (don't close it) and dispose of it.""" top = self.top() assert top is not None if top is self._EmPy_bottom: # If it's the bottom stream, flush it, don't close it, and mark # this proxy done. top.flush() self._EmPy_bottom = None else: top.close() # Stack management. def _EmPy_enabled(self): """Is the top interpreter enabled?""" if self._EmPy_stack: return self._EmPy_stack.top().enabled else: return True def _EmPy_current(self): """Get the current interpreter, or None.""" if self._EmPy_stack: return self._EmPy_stack.top() else: return None def _EmPy_top(self): """Get the current stream (not interpreter) to write to.""" if self._EmPy_stack: return self._EmPy_stack.top().top() else: return self._EmPy_bottom def _EmPy_push(self, interpreter): self._EmPy_stack.push(interpreter) def _EmPy_pop(self, interpreter): top = self._EmPy_stack.pop() if interpreter.error is not None and interpreter is not top: # Only check if an error is not in progress; otherwise, when there # are interpreters and subinterpreters and full dispatchers, # interpreters can get popped out of order. raise ConsistencyError("interpreter popped off of proxy stack out of order") def _EmPy_clear(self, interpreter): self._EmPy_stack.filter(lambda x, i=interpreter: x is not i) # Bottom file protection. def _EmPy_shouldWrap(self): """Should the bottom file be wrapped and unwrapped?""" return self._EmPy_wrapper is not None def _EmPy_wrap(self): """Wrap the bottom file in a delegate.""" if self._EmPy_shouldWrap(): assert issubclass(self._EmPy_wrapper, DelegatingFile), self._EmPy_wrapper self._EmPy_bottom = self._EmPy_wrapper(self._EmPy_bottom) def _EmPy_unwrap(self): """Unwrap the bottom file from the delegate, and unlink the delegate.""" if self._EmPy_shouldWrap(): wrapped = self._EmPy_bottom self._EmPy_bottom = wrapped.delegate wrapped.unlink() # Special. def _EmPy_evocare(self, increment): """Do the EmPy magic: Increment or decrement the reference count. Either way, return the current reference count. Beware of Exodus!""" if increment > 0: self._EmPy_count += increment elif increment < 0: self._EmPy_count += increment # note: adding a negative number if self._EmPy_count <= 0: assert self._EmPy_original is not None self._EmPy_unwrap() sys.stdout = self._EmPy_original return self._EmPy_count # # Diversion # class Diversion(File): """The representation of an active diversion. Diversions act as (writable) file objects, and then can be recalled either as pure strings or (readable) file objects.""" def __init__(self, name): self.name = name self.file = StringIO() def __str__(self): return self.name # These methods define the writable file-like interface for the diversion. def write(self, data): self.file.write(data) def writelines(self, lines): for line in lines: self.write(line) def flush(self): self.file.flush() def close(self): self.file.close() # These methods are specific to diversions. def preferFile(self): """Would this particular diversion prefer to be treated as a file (true) or a string (false)? This allows future optimization of diversions into actual files if they get overly large.""" return False def asString(self): """Return the diversion as a string.""" return self.file.getvalue() def asFile(self): """Return the diversion as a file.""" return StringIO(self.file.getvalue()) def spool(self, sink, chunkSize=Configuration.defaultBuffering): """Spool the diversion to the given sink.""" if self.preferFile(): # Either write it a chunk at a time ... input = self.asFile() while True: chunk = input.read(chunkSize) if not chunk: break sink.write(chunk) else: # ... or write it all at once. sink.write(self.asString()) # # Stream # class Stream(File): """A wrapper around an (output) file object which supports diversions and filtering.""" def __init__(self, interp, file, diversions): assert file is not None self.interp = interp self.file = file self.current = None self.diversions = diversions self.sink = file self.done = False def __repr__(self): return '<%s : %r @ 0x%x>' % ( self.__class__.__name__, self.file, id(self)) def __getattr__(self, name): return getattr(self.sink, name) # File methods. def write(self, data): if self.current is None: if self.interp.enabled: self.sink.write(data) else: self.diversions[self.current].write(data) def writelines(self, lines): if self.interp.enabled: for line in lines: self.write(line) def flush(self): self.sink.flush() def close(self): self.flush() if not self.done: self.sink.close() self.done = True # Filters. def count(self): """Count the number of filters.""" thisFilter = self.sink result = 0 while thisFilter is not None and thisFilter is not self.file: thisFilter = thisFilter.follow() result += 1 return result def last(self): """Find the last filter in the current filter chain, or None if there are no filters installed.""" if self.sink is None: return None thisFilter, lastFilter = self.sink, None while thisFilter is not None and thisFilter is not self.file: lastFilter = thisFilter thisFilter = thisFilter.follow() return lastFilter def install(self, filters=None): """Install a list of filters as a chain, replacing the current chain.""" self.sink.flush() if filters is None: filters = [] if len(filters) == 0: # An empty sequence means no filter. self.sink = self.file else: # If there's more than one filter provided, chain them together. lastFilter = None for filter in filters: if lastFilter is not None: lastFilter.attach(filter) lastFilter = filter lastFilter.attach(self.file) self.sink = filters[0] def prepend(self, filter): """Attach a solitary filter (no sequences allowed here) at the beginning of the current filter chain.""" self.sink.flush() firstFilter = self.sink if firstFilter is None: # Just install it from scratch if there is no active filter. self.install([filter]) else: # Attach this filter to the current one, and set this as the main # filter. filter.attach(firstFilter) self.sink = filter def append(self, filter): """Attach a solitary filter (no sequences allowed here) at the end of the current filter chain.""" self.sink.flush() lastFilter = self.last() if lastFilter is None: # Just install it from scratch if there is no active filter. self.install([filter]) else: # Attach the last filter to this one, and this one to the file. lastFilter.attach(filter) filter.attach(self.file) # Diversions. def names(self): """Return a sorted sequence of diversion names.""" keys = list(self.diversions.keys()) keys.sort() return keys def has(self, name): """Does this stream have a diversion with the given name?""" return name in self.diversions def revert(self): """Reset any current diversions.""" self.current = None def create(self, name): """Create a diversion if one does not already exist, but do not divert to it yet. Return the diversion.""" if name is None: raise DiversionError("diversion name must be non-None") diversion = None if not self.has(name): diversion = Diversion(name) self.diversions[name] = diversion return diversion def retrieve(self, name, *defaults): """Retrieve the given diversion. If an additional argument is provided, return that instead of raising on a nonexistent diversion.""" if name is None: raise DiversionError("diversion name must be non-None") if self.has(name): return self.diversions[name] else: if defaults: return defaults[0] else: raise DiversionError("nonexistent diversion: `%s`" % name) def divert(self, name): """Start diverting.""" if name is None: raise DiversionError("diversion name must be non-None") self.create(name) self.current = name def undivert(self, name, dropAfterwards=False): """Undivert a particular diversion.""" if name is None: raise DiversionError("diversion name must be non-None") if self.has(name): if self.interp.enabled: diversion = self.diversions[name] diversion.spool(self.sink) if dropAfterwards: self.drop(name) else: raise DiversionError("nonexistent diversion: `%s`" % name) def drop(self, name): """Drop the specified diversion.""" if name is None: raise DiversionError("diversion name must be non-None") if self.has(name): del self.diversions[name] if self.current == name: self.current = None def undivertAll(self, dropAfterwards=True): """Undivert all pending diversions.""" if self.diversions: self.revert() # revert before undiverting! for name in self.names(): self.undivert(name, dropAfterwards) def dropAll(self): """Eliminate all existing diversions.""" if self.diversions: self.diversions.clear() self.current = None # # Context # class Context(Root): """A simple interpreter context, storing only the current data. It is not intended to be modified.""" format = Configuration.defaultContextFormat def __init__(self, name, line, column, chars=0, startingLine=None, startingColumn=None): self.name = name self.line = line self.column = column self.chars = chars if startingLine is None: startingLine = line self.startingLine = startingLine if startingColumn is None: startingColumn = column self.startingColumn = startingColumn self.pendingLines = 0 self.pendingColumns = 0 self.pendingChars = 0 def __str__(self): return self.render(self.format) def reset(self): """Reset the context to the start.""" self.line = self.startingLine self.column = self.startingColumn self.chars = 0 def track(self, string, start, end): """Track the information for the substring in [start, end) in the context and mark it pending.""" assert end >= start, (start, end) if end > start: length = end - start self.pendingLines += string.count(NEWLINE_CHAR, start, end) loc = string.rfind(NEWLINE_CHAR, start, end) if loc == -1: self.pendingColumns += length else: self.pendingColumns = self.startingColumn + end - loc - 1 self.pendingChars += length def accumulate(self): """Accumulate the pending information and incorporate it into the total.""" self.line += self.pendingLines if self.pendingLines > 0: self.column = self.pendingColumns # replaced, not added else: self.column += self.pendingColumns self.chars += self.pendingChars self.pendingLines = 0 self.pendingColumns = 0 self.pendingChars = 0 def save(self, strict=False): """Take a snapshot of the current context.""" if strict and self.pendingChars == 0: raise ConsistencyError("context %s has pending chars" % toString(self)) return Context(self.name, self.line, self.column, self.chars) def restore(self, other, strict=False): """Restore from another context.""" if strict and self.pendingChars == 0: raise ConsistencyError("context %s has pending chars" % toString(self)) self.name = other.name self.line = other.line self.column = other.column self.chars = other.chars def render(self, format, useFormatMethod=None): """Render the context with the given format. If useFormatMethod is true, use the format method; if false, use the % operator. If useFormatMethod is None, try to trivially auto-detect given the format.""" record = { 'name': self.name, 'line': self.line, 'column': self.column, 'chars': self.chars, } if useFormatMethod is None: # If it contains a percent sign, it looks like it's not using the # format method. useFormatMethod = '%' not in format if useFormatMethod: return format.format(**record) else: return format % record def identify(self): return self.name, self.line, self.column, self.chars # # Token ... # class Token(Root): """An element resulting from parsing.""" def __init__(self, current): self.current = current def __str__(self): return self.string() def string(self): raise NotImplementedError def run(self, interp, locals): raise NotImplementedError class TextToken(Token): """A chunk of text not containing markups.""" def __init__(self, current, data): super(TextToken, self).__init__(current) self.data = data def string(self): return self.data def run(self, interp, locals): interp.write(self.data) class ExpansionToken(Token): """A token that involves an expansion.""" last = None # subclasses should always define a first class attribute def __init__(self, current, config, first): super(ExpansionToken, self).__init__(current) self.config = config # Only record a local copy of first/last if it's ambiguous. if self.first is None: self.first = first elif len(self.first) != 1: first = first[:1] self.first = first self.last = ENDING_CHAR_MAP.get(first, first) def scan(self, scanner): pass def run(self, interp, locals): pass class CommentToken(ExpansionToken): """The abstract base class for the comment tokens.""" pass class LineCommentToken(CommentToken): """A line comment markup: ``@# ... NL``""" first = OCTOTHORPE_CHAR def scan(self, scanner): loc = scanner.find(NEWLINE_CHAR) if loc >= 0: self.comment = scanner.chop(loc, 1) else: raise TransientParseError("comment expects newline") def string(self): return '%s%s%s\n' % (self.config.prefix, self.first, self.comment) def run(self, interp, locals): interp.invoke('preLineComment', comment=self.comment) class InlineCommentToken(CommentToken): """An inline comment markup: ``@* ... *``""" first = ASTERISK_CHAR last = ASTERISK_CHAR def scan(self, scanner): # Find the run of starting characters to match. self.count = 1 start = scanner.last(self.first) self.count += start scanner.advance(start) # Then match them with the same number of closing characters. loc = scanner.find(self.last * self.count) if loc >= 0: self.comment = scanner.chop(loc, self.count) else: raise TransientParseError("inline comment expects asterisk") def string(self): return '%s%s%s%s' % ( self.config.prefix, self.first * self.count, self.comment, self.last * self.count) def run(self, interp, locals): interp.invoke('preInlineComment', comment=self.comment) class LiteralToken(ExpansionToken): """The abstract base class of the literal tokens. If used as a concrete token class, it will expand to the first character.""" def string(self): return '%s%s' % (self.config.prefix, self.first) def run(self, interp, locals): interp.write(self.first) class WhitespaceToken(LiteralToken): """A whitespace markup: ``@ WS``""" first = '' def string(self): return '%s%s' % (self.config.prefix, self.first) def run(self, interp, locals): interp.invoke('preWhitespace', whitespace=self.first) class SwitchToken(CommentToken): """Base class for the enable/disable tokens.""" def scan(self, scanner): loc = scanner.find(NEWLINE_CHAR) if loc >= 0: self.comment = scanner.chop(loc, 1) else: raise TransientParseError("switch expects newline") def string(self): return '%s%s%s\n' % (self.config.prefix, self.first, self.comment) class EnableToken(SwitchToken): """An enable output markup: ``@+ ... NL``""" first = PLUS_CHAR def run(self, interp, locals): interp.invoke('preEnable', comment=self.comment) interp.enable() class DisableToken(SwitchToken): """An disable output markup: ``@- ... NL``""" first = MINUS_CHAR def run(self, interp, locals): interp.invoke('preDisable', comment=self.comment) interp.disable() class PrefixToken(LiteralToken): """A prefix markup: ``@@``""" first = None # prefix def string(self): return self.config.prefix * 2 def run(self, interp, locals): if interp.invoke('prePrefix'): return interp.write(self.config.prefix) class StringToken(LiteralToken): """A string token markup: ``@'...'``, ``@'''...'''``, ``@"..."``, ``@\"\"\"...\"\"\"``""" first = list(QUOTE_CHARS) def scan(self, scanner): scanner.retreat() assert scanner[0] == self.first, (scanner[0], self.first) i = scanner.quote() self.literal = scanner.chop(i) def string(self): return '%s%s' % (self.config.prefix, self.literal) def run(self, interp, locals): if interp.invoke('preString', string=self.literal): return interp.literal(self.literal, locals) interp.invoke('postString') class BackquoteToken(LiteralToken): """A backquote markup: ``@`...```""" first = BACKQUOTE_CHAR def scan(self, scanner): # Find the run of starting characters to match. self.count = 1 start = scanner.last(self.first) self.count += start scanner.advance(start) # Then match them with the same number of closing characters. loc = scanner.find(self.first * self.count) if loc >= 0: self.literal = scanner.chop(loc, self.count) else: raise TransientParseError("backquote markup expects %d backquotes" % self.count) def string(self): return '%s%s%s%s' % ( self.config.prefix, self.first * self.count, self.literal, self.first * self.count) def run(self, interp, locals): if interp.invoke('preBackquote', literal=self.literal): return interp.write(self.literal) interp.invoke('postBackquote', result=self.literal) class SimpleToken(ExpansionToken): """An abstract base class for simple tokens which consist of nothing but the prefix and expand to either the results a function call in the interpreter globals (if args is not specified or is a tuple) or the value of a variable name named function (if args is None).""" def string(self): return self.config.prefix + self.first def run(self, interp, locals): args = getattr(self, 'args', ()) if args is None: result = interp.lookup(self.function) else: callable = interp.lookup(self.function) result = callable(*args) interp.write(result) class ExecutionToken(ExpansionToken): """The abstract base class for execution tokens (expressions, statements, controls, etc.)""" pass class ExpressionToken(ExecutionToken): """An expression markup: ``@(...)``""" first = OPEN_PARENTHESIS_CHAR last = ENDING_CHAR_MAP[first] def scan(self, scanner): start = 0 end = scanner.complex(self.first, self.last) try: except_ = scanner.next('$', start, end, True) except ParseError: except_ = end # Build up a list of relevant indices (separating start/if/then/else # clauses) indices = [start - 1] # start, if, then, [if, then]..., [else] while True: try: first = scanner.next('?', start, except_, True) indices.append(first) try: last = scanner.next('!', first, except_, True) indices.append(last) except ParseError: last = except_ break except ParseError: first = last = except_ break start = last + 1 indices.append(except_) code = scanner.chop(end, 1) # Now build up the ifThenCodes pair chain. self.ifThenCodes = [] prev = None pair = None for index in indices: if prev is not None: # pair can either be None or a 2-list, possibly with None as # the second element. if pair is None: pair = [code[prev + 1:index], None] else: pair[1] = code[prev + 1:index] self.ifThenCodes.append(pair) pair = None prev = index # If there's a half-constructed pair not yet added to the chain, add it # now. if pair is not None: self.ifThenCodes.append(pair) self.exceptCode = code[except_ + 1:end] def string(self): fragments = [] sep = None for ifCode, thenCode in self.ifThenCodes: if sep: fragments.append(sep) fragments.append(ifCode) if thenCode is not None: fragments.append('?') fragments.append(thenCode) sep = '!' if self.exceptCode: fragments.append('$' + self.exceptCode) return '%s%s%s%s' % ( self.config.prefix, self.first, ''.join(fragments), self.last) def run(self, interp, locals): # ifThenCodes is a list of 2-lists. A list of one sublist whose second # subelement is None is a simple expression to evaluate; no # if-then-else logic. A list of more than one sublist is a chained # if-then-if-then-...-else clause with each sublist containing an if # and a then subelement. If the second subelement is None, then the # first element is not an if but an else. if interp.invoke('preExpression', pairs=self.ifThenCodes, except_=self.exceptCode, locals=locals): return result = None try: for ifCode, thenCode in self.ifThenCodes: # An if or an else clause; evaluate it. result = interp.evaluate(ifCode, locals) if thenCode is None: # If there's no then clause, then this is an isolated if or # a final else, so we're done. break else: if result: # With a then clause with a true if clause, evaluate # it. result = interp.evaluate(thenCode, locals) # If it's true, we're done. if result: break else: # Otherwise, go again. If there no remaining pairs, # return None (no expansion). result = None except self.config.fallThroughErrors: # Don't catch these errors; let them fall through. raise except: if self.exceptCode: result = interp.evaluate(self.exceptCode, locals) else: raise interp.serialize(result) interp.invoke('postExpression', result=result) class SimpleExpressionToken(ExecutionToken): """A simple expression markup: ``@x``, ``@x.y``, ``@x(y)``, ``@x[y]``, ``@f{...}``""" first = '' def top(self): return self.subtokens[-1] def new(self): self.subtokens.append([]) def append(self, token): self.subtokens[-1].append(token) def scan(self, scanner, begin='{', end='}'): i = scanner.simple() self.code = self.first + scanner.chop(i) # Now scan ahead for functional expressions. self.subtokens = [] scanner.acquire() try: while True: if not scanner: raise TransientParseError("need more context for end of simple expression") if scanner.read() != begin: break self.new() count = None while True: peek = scanner.read() if peek == begin: # The start of an argument. if count is None: count = scanner.last(begin) scanner.chop(count) current = self.config.renderContext(scanner.context) scanner.currents.replace(current) elif peek == end and count is not None: # The possible end of an argument. if scanner.read(0, count) == end * count: scanner.chop(count) current = self.config.renderContext(scanner.context) scanner.currents.replace(current) break token = scanner.one([end * count]) self.append(token) finally: scanner.release() def string(self): results = ['%s%s' % (self.config.prefix, self.code)] for tokens in self.subtokens: results.append('{%s}' % ''.join(map(str, tokens))) return ''.join(results) def run(self, interp, locals): if interp.invoke('preSimple', code=self.code, subtokens=self.subtokens, locals=locals): return result = None if self.subtokens: result = interp.functional(self.code, self.subtokens, locals) else: result = interp.evaluate(self.code, locals) interp.serialize(result) interp.invoke('postSimple', result=result) class InPlaceToken(ExecutionToken): """An in-place markup: ``@$...$...$``""" first = DOLLAR_CHAR def scan(self, scanner): i = scanner.next(self.first) j = scanner.next(self.first, i + 1) self.code = scanner.chop(i, j - i + 1) def string(self): return '%s%s%s%s%s' % ( self.config.prefix, self.first, self.code, self.first, self.first) def run(self, interp, locals): if interp.invoke('preInPlace', code=self.code, locals=locals): return result = None interp.write("%s%s%s%s" % ( self.config.prefix, self.first, self.code, self.first)) try: result = interp.evaluate(self.code, locals) interp.serialize(result) finally: interp.write(self.first) interp.invoke('postInPlace', result=result) class StatementToken(ExecutionToken): """A statement markup: ``@{...}``""" first = OPEN_BRACE_CHAR last = ENDING_CHAR_MAP[first] def scan(self, scanner): i = scanner.complex(self.first, self.last) self.code = scanner.chop(i, 1) def string(self): return '%s%s%s%s' % ( self.config.prefix, self.first, self.code, self.last) def run(self, interp, locals): if interp.invoke('preStatement', code=self.code, locals=locals): return interp.execute(self.code, locals) interp.invoke('postStatement') class ControlToken(ExecutionToken): """A control markup: ``@[...]``""" first = OPEN_BRACKET_CHAR last = ENDING_CHAR_MAP[first] class Chain(Root): """A chain of tokens with a starting token and the rest that follow.""" def __init__(self, head, tail): self.head = head self.tail = tail def __str__(self): return '(%s, %s)' % (self.head, self.tail) def getType(self): return self.head.type def hasType(self, name): return self.head.type == name PRIMARY = ['if', 'for', 'while', 'dowhile', 'try', 'with', 'match', 'defined', 'def'] SECONDARY = ['elif', 'else', 'except', 'finally', 'case'] TERTIARY = ['continue', 'break'] GREEDY = [ 'if', 'elif', 'for', 'while', 'dowhile', 'with', 'match', 'defined', 'def', 'end' ] CLEAN = ['try', 'else', 'except', 'finally', 'case', 'continue', 'break', 'end'] END = ['end'] ALLOWED = { 'if': ['elif', 'else'], 'for': ['else'], 'while': ['else'], 'dowhile': ['else'], 'try': ['except', 'else', 'finally'], 'with': [], 'match': ['case', 'else'], 'defined': ['else'], 'def': None, 'continue': None, 'break': None, } IN_RE = re.compile(r"\bin\b") AS_RE = re.compile(r"\bas\b") runPrefix = 'run_' elseCase = '_' def scan(self, scanner): scanner.acquire() try: i = scanner.complex(self.first, self.last) self.contents = scanner.chop(i, 1) fields = self.contents.strip().split(None, 1) if len(fields) > 1: self.type, self.rest = fields # If this is a "clean" control, remove anything that looks like # a comment. if self.type in self.CLEAN and '#' in self.rest: self.rest = self.rest.split('#', 1)[0].strip() else: self.type = fields[0] self.rest = None self.subtokens = [] if self.type in self.GREEDY and self.rest is None: raise ParseError("control `%s` needs arguments" % self.type) if self.type in self.PRIMARY: self.subscan(scanner, self.type) self.kind = 'primary' elif self.type in self.SECONDARY: self.kind = 'secondary' elif self.type in self.TERTIARY: self.kind = 'tertiary' elif self.type in self.END: self.kind = 'end' else: raise ParseError("unknown control markup: `%s`" % self.type) finally: scanner.release() def subscan(self, scanner, primary): """Do a subscan for contained tokens.""" while True: token = scanner.one() if token is None: raise TransientParseError("control `%s` needs more tokens" % primary) if isinstance(token, ControlToken) and token.type in self.END: if token.rest != primary: raise ParseError("control must end with `end %s`" % primary) break self.subtokens.append(token) def build(self, allowed): """Process the list of subtokens and divide it up into a list of chains, returning that list. Allowed specifies a list of the only secondary markup types which are allowed.""" result = [] current = [] result.append(self.Chain(self, current)) for subtoken in self.subtokens: if (isinstance(subtoken, ControlToken) and subtoken.kind == 'secondary'): if subtoken.type not in allowed: raise ParseError("control unexpected secondary: `%s`" % subtoken.type) current = [] result.append(self.Chain(subtoken, current)) else: current.append(subtoken) return result def subrun(self, tokens, interp, locals): """Execute a list of tokens.""" interp.runSeveral(tokens, locals) def substring(self): return ''.join([toString(x) for x in self.subtokens]) def string(self): if self.kind == 'primary': return ('%s[%s]%s%s[end %s]' % (self.config.prefix, self.contents, self.substring(), self.config.prefix, self.type)) else: return '%s[%s]' % (self.config.prefix, self.contents) def run(self, interp, locals): if interp.invoke('preControl', type=self.type, rest=self.rest, locals=locals): return try: allowed = self.ALLOWED[self.type] except KeyError: raise ParseError("control `%s` cannot be at this level" % self.type) if allowed is not None: chains = self.build(allowed) else: chains = None try: method = getattr(self, self.runPrefix + self.type) except AttributeError: raise ConsistencyError("unknown handler for control type `%s`" % self.type) method(chains, interp, locals) interp.invoke('postControl') # Type handlers. def run_if(self, chains, interp, locals): # @[if E]...@[end if] # @[if E]...@[else]...@[end if] # @[if E]...@[elif E2]...@[end if] # @[if E]...@[elif E2]...@[else]...@[end if] # @[if E]...@[elif E2]... ... @[else]...@[end if] if chains[-1].hasType('else'): elseChain = chains.pop() else: elseChain = None first = True for chain in chains: if first: if not chain.hasType('if'): raise ParseError("control `if` expected: `%s`" % chain.head.type) first = False else: if not chain.hasType('elif'): raise ParseError("control `elif` expected: `%s`" % chain.head.type) if interp.evaluate(chain.head.rest, locals): self.subrun(chain.tail, interp, locals) break else: if elseChain: self.subrun(elseChain.tail, interp, locals) def run_for(self, chains, interp, locals): # @[for N in E]...@[end for] # @[for N in E]...@[else]...@[end for] sides = self.IN_RE.split(self.rest, 1) if len(sides) != 2: raise ParseError("control `for` expected `for x in ...`") iterator, iterableCode = sides forChain = chains[0] assert forChain.hasType('for'), forChain.getType() elseChain = None if chains[-1].hasType('else'): elseChain = chains.pop() if len(chains) != 1: raise ParseError("control `for` expects at most one `else`") iterable = interp.evaluate(iterableCode, locals) for element in iterable: try: interp.assign(iterator, element, locals) self.subrun(forChain.tail, interp, locals) except ContinueFlow: continue except BreakFlow: break else: if elseChain: self.subrun(elseChain.tail, interp, locals) def run_while(self, chains, interp, locals): # @[while E]...@[end while] # @[while E]...@[else]...@[end while] testCode = self.rest whileChain = chains[0] assert whileChain.hasType('while'), whileChain.getType() elseChain = None if chains[-1].hasType('else'): elseChain = chains.pop() if len(chains) != 1: raise ParseError("control `while` expects at most one `else`") exitedNormally = False while True: try: if not interp.evaluate(testCode, locals): exitedNormally = True break self.subrun(whileChain.tail, interp, locals) except ContinueFlow: continue except BreakFlow: break if exitedNormally and elseChain: self.subrun(elseChain.tail, interp, locals) def run_dowhile(self, chains, interp, locals): # @[dowhile E]...@[end dowhile] # @[dowhile E]...@[else]...@[end dowhile] testCode = self.rest doWhileChain = chains[0] assert doWhileChain.hasType('dowhile'), doWhileChain.getType() elseChain = None if chains[-1].hasType('else'): elseChain = chains.pop() if len(chains) != 1: raise ParseError("control `dowhile` expects at most one `else`") exitedNormally = False while True: try: self.subrun(doWhileChain.tail, interp, locals) if not interp.evaluate(testCode, locals): exitedNormally = True break except ContinueFlow: continue except BreakFlow: break if exitedNormally and elseChain: self.subrun(elseChain.tail, interp, locals) def run_try(self, chains, interp, locals): # @[try]...@[except]...@[end try] # @[try]...@[except C]...@[end try] # @[try]...@[except C as N]...@[end try] # @[try]...@[except C, N]...@[end try] # @[try]...@[except (C1, C2, ...) as N]...@[end try] # @[try]...@[except C1]...@[except C2]...@[end try] # @[try]...@[except C1]...@[except C2]... ... @[end try] # @[try]...@[finally]...@[end try] # @[try]...@[except ...]...@[finally]...@[end try] # @[try]...@[except ...]...@[else]...@[end try] # @[try]...@[except ...]...@[else]...@[finally]...@[end try] if len(chains) == 1: raise ParseError("control `try` expects at least one `except` or `finally`") tryChain = None exceptChains = [] elseChain = None finallyChain = None # Process the chains and verify them. for chain in chains: if chain.hasType('try'): if exceptChains or elseChain or finallyChain: raise ParseError("control `try` must be first") tryChain = chain elif chain.hasType('except'): if elseChain: raise ParseError("control `try` cannot have `except` following `else`") elif finallyChain: raise ParseError("control `try` cannot have `except` following `finally`") exceptChains.append(chain) elif chain.hasType('else'): if not exceptChains: raise ParseError("control `try` cannot have `else` with no preceding `except`") elif elseChain: raise ParseError("control `try` cannot have more than one `else`") elif finallyChain: raise ParseError("control `try` cannot have `else` following `finally`") elseChain = chain elif chain.hasType('finally'): if finallyChain: raise ParseError("control `try` cannot have more than one `finally`") finallyChain = chain else: assert False, chain try: try: self.subrun(tryChain.tail, interp, locals) if elseChain: self.subrun(elseChain.tail, interp, locals) except Flow: raise except self.config.baseException: type, error, traceback = sys.exc_info() for chain in exceptChains: exception, variable = interp.clause(chain.head.rest) if isinstance(error, exception): if variable is not None: interp.assign(variable, error, locals) self.subrun(chain.tail, interp, locals) break else: raise finally: if finallyChain: self.subrun(finallyChain.tail, interp, locals) def run_with(self, chains, interp, locals): # @[with E as N]...@[end with] # @[with N]...@[end with] # @[with E]...@[end with] fields = self.AS_RE.split(self.rest, 1) if len(fields) == 1: expression = fields[0].strip() variable = None else: # len(fields) == 2 expression, variable = fields variable = variable.strip() manager = interp.evaluate(expression, locals) resource = manager if variable is not None: interp.assign(variable, resource, locals) if len(chains) != 1: raise ParseError("control `with` must be simple") withChain = chains[0] assert withChain.hasType('with'), withChain.getType() # As per Python's compound statement reference documentation. enter = manager.__enter__ exit = manager.__exit__ resource = enter() oops = False try: try: self.subrun(withChain.tail, interp, locals) except: oops = True if not exit(*sys.exc_info()): raise finally: if not oops: exit(None, None, None) def run_match(self, chains, interp, locals): # @[match E]...@[case C]...@[end match] # @[match E]...@[case C1]...@[case C2]...@[end match] # @[match E]...@[case C1]...@[case C2]...@[else]...@[end match] expression = self.rest.strip() if not expression: raise ParseError("control `match` expects an expression") matchChain = chains[0] self.subrun(matchChain.tail, interp, locals) assert matchChain.hasType('match'), matchChain.getType() if chains[-1].hasType('else'): elseChain = chains[-1] chains = chains[:-1] else: elseChain = None if len(chains) + bool(elseChain) <= 1: raise ParseError("control `match` expects at least one `case` or `else`") cases = [] for chain in chains[1:]: if not chain.hasType('case'): raise ParseError("contol `match` expects only `case` and at most one `else`") cases.append(Core.Case(chain.head.rest, chain.tail)) if elseChain: cases.append(Core.Case(self.elseCase, elseChain.tail)) interp.core.match(expression, cases, locals) def run_defined(self, chains, interp, locals): # @[defined N]...@[end defined] # @[defined N]...@[else]...@[end defined] testName = self.rest.strip() if not testName: raise ParseError("control `defined` expects an argument") definedChain = chains[0] assert definedChain.hasType('defined'), definedChain.getType() if len(chains) > 3: raise ParseError("control `defined` expects at most one `else`") if len(chains) == 2: elseChain = chains[1] else: elseChain = None if interp.defined(testName, locals): self.subrun(definedChain.tail, interp, locals) elif elseChain: self.subrun(elseChain.tail, interp, locals) def run_def(self, chains, interp, locals): # @[def F(...)]...@[end def] assert chains is None, chains signature = self.rest definition = self.substring() interp.core.define(signature, definition, locals) def run_continue(self, chains, interp, locals): # @[continue] assert chains is None, chains raise ContinueFlow("control `continue` encountered without loop control") def run_break(self, chains, interp, locals): # @[break] assert chains is None, chains raise BreakFlow("control `break` encountered without loop control") class CodedToken(ExpansionToken): """The abstract base class for a token that supports codings.""" def recode(self, result): return self.config.recode(result) class EscapeToken(CodedToken): """An escape markup: ``@\\...``""" first = BACKSLASH_CHAR def scan(self, scanner): try: code = scanner.chop(1) result = None if code in LITERAL_CHARS: # literals result = code elif code == '0': # NUL, null result = 0x00 elif code == 'a': # BEL, bell result = 0x07 elif code == 'b': # BS, backspace result = 0x08 elif code == 'B': # freeform binary code binaryCode = scanner.enclosure() result = int(binaryCode, 2) elif code == 'd': # three-digit decimal code decimalCode = scanner.chop(3) result = int(decimalCode, 10) elif code == 'D': # freeform decimal code decimalCode = scanner.enclosure() result = int(decimalCode, 10) elif code == 'e': # ESC, escape result = 0x1b elif code == 'f': # FF, form feed result = 0x0c elif code == 'h': # DEL, delete result = 0x7f elif code == 'k': # ACK, acknowledge result = 0x06 elif code == 'K': # NAK, negative acknowledge result = 0x15 elif code == 'n': # LF, linefeed; newline result = 0x0a elif code == 'N': # Unicode character name if unicodedata is None: raise ConfigurationError("unicodedata module not available; cannot use @\\N{...} markup") name = scanner.enclosure() try: name = name.replace('\n', ' ') result = unicodedata.lookup(name) except AttributeError: raise ConfigurationError("unicodedata.lookup function not available; cannot use @\\N{...} markup") except KeyError: raise ParseError("unknown Unicode character name: `%s`" % name) elif code == 'o': # three-digit octal code octalCode = scanner.chop(3) result = int(octalCode, 8) elif code == 'O': # freeform octal code octalCode = scanner.enclosure() result = int(octalCode, 8) elif code == 'q': # four-digit quaternary code quaternaryCode = scanner.chop(4) result = int(quaternaryCode, 4) elif code == 'Q': # freeform quaternary code quaternaryCode = scanner.enclosure() result = int(quaternaryCode, 4) elif code == 'r': # CR, carriage return result = 0x0d elif code == 's' or code in WHITESPACE_CHARS: # SP, space result = ' ' elif code == 'S': # NBSP, no-break space result = 0xa0 elif code == 't': # HT, horizontal tab result = 0x09 elif code == 'u': # 16-bit (four-digit) hexadecimal Unicode hexCode = scanner.chop(4) result = int(hexCode, 16) elif code == 'U': # 32-bit (eight-digit) hexadecimal Unicode hexCode = scanner.chop(8) result = int(hexCode, 16) elif code == 'v': # VT, vertical tab result = 0x0b elif code == 'V': # variation selector name = scanner.enclosure() try: selector = int(name) except ValueError: raise ParseError("variation selector must be int: `%s`" % name) if selector < 1 or selector > 256: raise ParseError("variation selector must be between 1 and 256 inclusive: %d" % selector) if selector <= 16: result = 0xfe00 + selector - 1 else: result = 0xe0100 + (selector - 17) elif code == 'w': # variation selector 15; text display result = 0xfe0e elif code == 'W': # variation selector 16; emoji display result = 0xfe0f elif code == 'x': # 8-bit (two-digit) hexadecimal code hexCode = scanner.chop(2) result = int(hexCode, 16) elif code == 'X': # freeform hexadecimal code hexCode = scanner.enclosure() result = int(hexCode, 16) elif code == 'y': # SUB, substitution result = 0x1a elif code == 'Y': # RC, replacement character result = 0xfffd elif code == 'z': # EOT, end of transmission result = 0x04 elif code == 'Z': # ZWNBSP/BOM, zero-width no-break space/byte order mark result = 0xfeff elif code == ',': # THSP, thin space result = 0x2009 elif code == '^': # control character controlCode = scanner.chop(1).upper() if controlCode == '{': if self.config.controls is None: raise ConfigurationError("controls not configured") name = scanner.grab('}') try: result = self.config.controls[name.upper()] except KeyError: raise ParseError("unknown control character name: `%s`" % name) elif controlCode >= '@' and controlCode <= '`': result = ord(controlCode) - ord('@') elif controlCode == '?': result = 0x7f else: raise ParseError("invalid escape control code") else: raise ParseError("unrecognized escape code: `%s`" % code) self.code = self.recode(result) except ValueError: raise ParseError("invalid numeric escape code") def string(self): """Return a general hexadecimal escape sequence rather than the exact one that was input.""" return self.config.escaped(ord(self.code), self.config.prefix + self.first) def run(self, interp, locals): if interp.invoke('preEscape', code=self.code): return interp.serialize(self.code) interp.invoke('postEscape') class DiacriticToken(CodedToken): """A diacritic markup: ``@^...``""" first = CARET_CHAR def scan(self, scanner): if self.config.diacritics is None: raise ConfigurationError("diacritics not configured") character = scanner.chop(1) diacritics = scanner.chop(1) if diacritics == '{': diacritics = scanner.grab('}') codes = [] try: for diacritic in diacritics: code = self.config.diacritics[diacritic] code = self.recode(code) codes.append(code) except KeyError: raise ParseError("unknown diacritical mark: `%s`" % diacritic) self.character = character self.codes = codes self.diacritics = diacritics def string(self): if len(self.diacritics) > 1: return '%s%s%s{%s}' % ( self.config.prefix, self.first, self.character, self.diacritics) else: return '%s%s%s%s' % ( self.config.prefix, self.first, self.character, self.diacritics) def run(self, interp, locals): combiners = ''.join([interp.core.serialize(x) for x in self.codes]) result = self.character + combiners if interp.invoke('preDiacritic', code=result): return try: if self.config.normalizationForm: result = unicodedata.normalize( self.config.normalizationForm, result) except AttributeError: raise ConfigurationError("unicodedata.normalize function not available; cannot use normalization form (must be blank or None)") except ValueError: pass interp.serialize(result) interp.invoke('postDiacritic') class IconToken(CodedToken): """An icon markup: ``@|...``""" first = STROKE_CHAR def scan(self, scanner): self.config.validateIcons() key = '' while True: key += scanner.chop(1) try: result = self.config.icons[key] except KeyError: raise ParseError("unknown icon sequence: `%s`" % key) if result is None: continue else: break self.key = key self.code = self.recode(result) def string(self): return '%s%s%s' % (self.config.prefix, self.first, self.key) def run(self, interp, locals): if interp.invoke('preIcon', code=self.code): return interp.serialize(self.code) interp.invoke('postIcon') class EmojiToken(CodedToken): """An emoji markup: ``@:...:``""" first = COLON_CHAR def scan(self, scanner): i = scanner.next(self.first) self.name = scanner.chop(i, 1) if not self.name: raise ParseError("emoji cannot be blank") def string(self): return '%s%s%s%s' % ( self.config.prefix, self.first, self.name, self.first) def run(self, interp, locals): if interp.invoke('preEmoji', name=self.name): return if (self.config.emojis is not None and self.name in self.config.emojis): code = self.config.emojis[self.name] else: code = self.config.substituteEmoji(self.name) if code is None: if self.config.emojiNotFoundIsError: raise UnknownEmojiError("emoji not found: `%s`" % self.name) else: code = '%s%s%s' % (self.first, self.name, self.first) code = self.recode(code) interp.serialize(code) interp.invoke('postEmoji') class SignificatorToken(ExpansionToken): """A significator markup: ``@%... ... NL``, ``@%!... ... NL``, ``@%%... ... %% NL``, ``@%%!... ... %% NL``""" first = PERCENT_CHAR def ending(self, multiline): if multiline: return (self.first * 2) + NEWLINE_CHAR else: return NEWLINE_CHAR def scan(self, scanner): self.multiline = self.stringized = False peek = scanner.read() if peek == self.first: self.multiline = True scanner.advance(1) peek = scanner.read() if peek == '!': self.stringized = True scanner.advance(1) loc = scanner.find(self.ending(self.multiline)) if loc >= 0: contents = scanner.chop(loc, len(self.ending(self.multiline))) if not contents: raise ParseError("significator must have nonblank key") contents = contents.strip() # Work around a subtle CPython-Jython difference by stripping the # string before splitting it: 'a '.split(None, 1) has two elements # in Jython 2.1). fields = contents.strip().split(None, 1) self.key = fields[0] if len(fields) > 1: self.value = fields[1].strip() else: self.value = '' if not self.value and not self.stringized: self.value = self.config.emptySignificator else: if self.multiline: raise TransientParseError("significator expects %s and then newline" % (self.first * 2)) else: raise TransientParseError("significator expects newline") def string(self): if self.value is None: return '%s%s%s%s\n' % ( self.config.prefix, self.first, ['', '!'][self.stringized], self.key) else: if self.multiline: return '%s%s%s%s %s%s\n' % ( self.config.prefix, self.first * 2, ['', '!'][self.stringized], self.key, self.value, self.first * 2) else: return '%s%s%s%s %s\n' % ( self.config.prefix, self.first, ['', '!'][self.stringized], self.key, self.value) def run(self, interp, locals): if interp.invoke('preSignificator', key=self.key, value=self.value, stringized=self.stringized): return value = self.value if not self.stringized: if value is not None and value != self.config.emptySignificator: value = interp.evaluate(value, locals, replace=False) interp.significate(self.key, value, locals) interp.invoke('postSignificator') class ContextToken(ExpansionToken): """A base class for the context tokens.""" pass class ContextNameToken(ContextToken): """A context name change markup: ``@?...``""" first = QUESTION_CHAR def scan(self, scanner): loc = scanner.find(NEWLINE_CHAR) if loc >= 0: self.name = scanner.chop(loc, 1).strip() else: raise TransientParseError("context name expects newline") def string(self): return '%s%s%s\n' % (self.config.prefix, self.first, self.name) def run(self, interp, locals): if interp.invoke('preContextName', name=self.name): return context = interp.getContext() context.name = self.name interp.invoke('postContextName', context=context) class ContextLineToken(ContextToken): """A context line change markup: ``@!...``""" first = EXCLAMATION_CHAR def scan(self, scanner): loc = scanner.find(NEWLINE_CHAR) if loc >= 0: try: self.line = int(scanner.chop(loc, 1)) except ValueError: raise ParseError("context line requires integer") else: raise TransientParseError("context line expects newline") def string(self): return '%s%s%d\n' % (self.config.prefix, self.first, self.line) def run(self, interp, locals): if interp.invoke('preContextLine', line=self.line): return context = interp.getContext() context.line = self.line interp.invoke('postContextLine', context=context) class ExtensionToken(ExpansionToken): """An extension markup, used for all customizable markup: ``@((...))``, ``@[[...]]``, ``@{{...}}``, ``@<...>``, etc.""" def scan(self, scanner): # Find the run of starting characters to match. self.depth = 1 start = scanner.last(self.first) self.depth += start scanner.advance(start) # Then match them with the same number of closing characters. loc = scanner.find(self.last * self.depth) if loc >= 0: self.contents = scanner.chop(loc, self.depth) else: raise TransientParseError("custom markup (%s) expects %d closing characters (%s)" % (self.first, self.depth, self.last)) def string(self): return '%s%s%s%s' % ( self.config.prefix, self.first * self.depth, self.contents, self.last * self.depth) def run(self, interp, locals): if interp.callback is not None: # Legacy custom callback behavior. if interp.invoke('preCustom', contents=self.contents): return result = interp.callExtension( self.name, self.contents, self.depth, locals) interp.invoke('postCustom', result=result) else: # New extension behavior. if interp.invoke('preExtension', name=self.name, contents=self.contents, depth=self.depth, locals=locals): return result = interp.callExtension( self.name, self.contents, self.depth, locals) interp.invoke('postExtension', result=result) Configuration.tokens = [ LineCommentToken, InlineCommentToken, WhitespaceToken, DisableToken, EnableToken, PrefixToken, StringToken, BackquoteToken, ExpressionToken, SimpleExpressionToken, InPlaceToken, StatementToken, ControlToken, EscapeToken, DiacriticToken, IconToken, EmojiToken, SignificatorToken, ContextNameToken, ContextLineToken, ] # # Factory # class Factory(Root): """Turn a first character sequence into a token class. Token classes have a first attribute which is either None to indicate whatever the current prefix is; a string in angle brackets to indicate a special test; or a character sequence; or a list of character sequences. Token classes are then retrieved by lookup table, or special test. Initialize this meta-factory with a list of factory classes and it will automatically setup the lookup tables based on their first attributes.""" addenda = { ')': "; the `@)` markup has been removed, just use `)` instead", ']': "; the `@]` markup has been removed, just use `]` instead", '}': "; the `@}` markup has been removed, just use `}` instead", '((': "; extension markup `@((...))` invoked with no installed extension", '[[': "; extension markup `@[[...]]` invoked with no installed extension", '{{': "; extension markup `@{{...}}` invoked with no installed extension", '<': "; extension markup `@<...>` invoked with no installed extension or callback", } def __init__(self, tokens): self.byChar = {} self.identifier = None self.whitespace = None for token in tokens: self.addToken(token) assert self.identifier is not None assert self.whitespace is not None def __contains__(self, first): return first in self.byChar def __getitem__(self, first): return self.byChar[first] def __call__(self, first): if first in self.byChar: return self.byChar[first] else: if first.isspace(): return self.whitespace elif isIdentifier(first): return self.identifier return None def addToken(self, token, protect=False): """Add another token class to the factory.""" first = token.first if first is None: # A prefix. if None in self.byChar and protect: raise ConfigurationError("will not replace prefix token; set protect to true") assert None not in self.byChar self.byChar[None] = token elif (isinstance(first, strType) and first.startswith('<') and first.endswith('>')): # A special case. if first == '': assert self.identifier is None, self.identifier self.identifier = token elif first == '': assert self.whitespace is None, self.whitespace self.whitespace = token else: raise ConsistencyError("unknown special token case: `%s`" % first) else: # A character sequence or list of them. if not isinstance(first, list): first = [first] for char in first: if char in self.byChar and protect: raise ConfigurationError("will not replace token with first `%s`; set protect to true" % char) self.byChar[char] = token def removeToken(self, first): """Remove token(s) from the mapping by first, which can be a string first or a list of strings firsts.""" if first.startswith('<') and first.endswith('>'): if first == '': self.identifier = None elif first == '': self.whitespace = None else: raise ConsistencyError("unknown special token case: `%s`" % first) else: del self.byChar[first] def removeTokens(self, firsts): for first in firsts: self.removeToken(first) def adjust(self, config): """Adjust this factory to swap the markup for a non-default prefix, if necessary.""" if not config.hasDefaultPrefix() and config.prefix in self: oldFactory = self[config.prefix] self.byChar[config.defaultPrefix] = oldFactory oldFactory._first = oldFactory.first oldFactory.first = None # config.defaultPrefix def addendum(self, first): """An optional addendum about unsupported markup sequence (for compatibility or future notes).""" return self.addenda.get(first, '') # # Scanner # class Scanner(Root): """A scanner holds a buffer for lookahead parsing and has the ability to scan for special symbols and indicators in that buffer.""" def __init__(self, config, context, currents, data=''): self.config = config self.context = context self.currents = currents self.head = 0 self.pointer = 0 self.buffer = data self.lock = 0 self.factory = config.getFactory() def __bool__(self): return self.head + self.pointer < len(self.buffer) # 3.x def __nonzero__(self): return self.head + self.pointer < len(self.buffer) # 2.x def __len__(self): return len(self.buffer) - self.pointer - self.head if major >= 3: def __getitem__(self, index): if isinstance(index, slice): assert index.step is None or index.step == 1, index.step return self.__getslice__(index.start, index.stop) else: return self.buffer[self.head + self.pointer + index] else: def __getitem__(self, index): return self.buffer[self.head + self.pointer + index] def __getslice__(self, start, stop): if start is None: start = 0 if stop is None: stop = len(self) if stop > len(self): stop = len(self) return self.buffer[self.head + self.pointer + start: self.head + self.pointer + stop] # Meta. def advance(self, count=1): """Advance the pointer count characters.""" self.pointer += count def retreat(self, count=1): self.pointer -= count if self.pointer < 0: raise ParseError("cannot retreat back over synced out chars") def set(self, data): """Start the scanner digesting a new batch of data; start the pointer over from scratch.""" self.head = 0 self.pointer = 0 self.buffer = data def feed(self, data): """Feed some more data to the scanner.""" self.rectify() if self.buffer: self.buffer += data else: self.buffer = data def acquire(self): """Lock the scanner so it doesn't destroy data on sync.""" self.lock += 1 def release(self): """Unlock the scanner.""" self.lock -= 1 def track(self): """Accumulate the moved pointer into the context.""" if self.pointer > 0: self.context.track(self.buffer, self.head, self.head + self.pointer) def accumulate(self): """Update the accumulated context into the actual context.""" self.context.accumulate() def rectify(self): """Reset the read head and trim down the buffer.""" if self.head + self.pointer > 0: self.buffer = self.buffer[self.head + self.pointer:] self.head = 0 self.pointer = 0 def sync(self): """Sync up the buffer with the read head.""" if self.lock == 0 and self.pointer > 0: self.track() self.head += self.pointer self.pointer = 0 def unsync(self): """Undo changes; reset the read head.""" if self.lock == 0: self.pointer = 0 def rest(self): """Get the remainder of the buffer.""" return self[:] # Active. def chop(self, count=None, slop=0): """Chop the first count + slop characters off the front, and return the first count, advancing the pointer past them. If count is not specified, then return everything.""" if count is None: assert slop == 0, slop count = len(self) if count > len(self): raise TransientParseError("not enough data to read") result = self[:count] self.advance(count + slop) return result def enclosure(self, begin='{', end='}'): """Consume and return the next enclosure (text wrapped in the given delimiters). The delimiters can be repeated.""" count = self.last(begin) self.advance(count) if count == 0: raise ParseError("enclosure must start with %s" % begin) loc = self.find(end * count) if loc < 0: raise TransientParseError("enclosure must end with %s" % (end * count)) return self.chop(loc, count) def read(self, start=0, count=1): """Read count chars starting from start; raise a transient error if there aren't enough characters remaining.""" if len(self) < start + count: raise TransientParseError("need more data to read") else: return self[start:start + count] def find(self, sub, start=0, end=None): """Find the next occurrence of the substring, or return -1.""" if end is None: end = len(self) return self.rest().find(sub, start, end) def trivial(self, sub, start=0, end=None): """Find the first occurrence of the substring where the previous character is _not_ the escape character `\\`).""" head = start while True: i = self.find(sub, head, end) if i == -1: raise TransientParseError("substring not found: `%s`" % sub) if i > 0 and self[i - 1] == BACKSLASH_CHAR: head = i + len(sub) continue return i def last(self, chars, start=0, end=None): """Find the first character that is _not_ one of the specified characters.""" if end is None: end = len(self) i = start while i < end: if self[i] not in chars: return i i += 1 else: raise TransientParseError("expecting other than %s" % chars) def grab(self, sub, start=0, end=None): """Find the next occurrence of the substring and chop the intervening characters, disposing the substring found.""" i = self.find(sub, start, end) if i >= 0: return self.chop(i, len(sub)) else: raise TransientParseError("delimiter not found: `%s`" % sub) def next(self, target, start=0, end=None, mandatory=False): """Scan for the next occurrence of one of the characters in the target string; optionally, make the scan mandatory.""" if mandatory: assert end is not None quote = None if end is None: end = len(self) i = start while i < end: newQuote = self.check(i, quote) if newQuote: if newQuote == quote: quote = None else: quote = newQuote i += len(newQuote) else: c = self[i] if quote: if c == '\\': i += 1 else: if c in target: return i i += 1 else: if mandatory: raise ParseError("expecting %s, not found" % target) else: raise TransientParseError("expecting ending character") def check(self, start=0, archetype=None): """Scan for the next single or triple quote, optionally with the specified archetype. Return the found quote or None.""" quote = None i = start if len(self) - i <= 1: raise TransientParseError("need to scan for rest of quote") if self[i] in QUOTE_CHARS: quote = self[i] if self[i + 1] == quote: if len(self) - i <= 2: raise TransientParseError("need more context to complete quote") if self[i + 2] == quote: quote *= 3 if quote is not None: if archetype is None: return quote else: if archetype == quote: return archetype elif len(archetype) < len(quote) and archetype[0] == quote[0]: return archetype else: return None else: return None def quote(self, start=0, end=None, mandatory=False): """Scan for the end of the next quote.""" assert self[start] in QUOTE_CHARS, self[start] quote = self.check(start) if end is None: end = len(self) i = start + len(quote) while i < end: newQuote = self.check(i, quote) if newQuote: i += len(newQuote) if newQuote == quote: return i else: c = self[i] if c == '\\': i += 1 i += 1 else: if mandatory: raise ParseError("expecting end of string literal") else: raise TransientParseError("expecting end of string literal") def nested(self, enter, exit, start=0, end=None): """Scan from start for an ending sequence, respecting entries and exits only.""" depth = 0 if end is None: end = len(self) i = start while i < end: c = self[i] if c == enter: depth += 1 elif c == exit: depth -= 1 if depth < 0: return i i += 1 else: raise TransientParseError("expecting end of complex expression") def complex(self, enter, exit, comment=OCTOTHORPE_CHAR, start=0, end=None, skip=None): """Scan from start for an ending sequence, respecting quotes, entries and exits.""" quote = None depth = 0 if end is None: end = len(self) lastNonQuote = None commented = False i = start while i < end: if commented: c = self[i] if c == '\n': commented = False elif c == exit: return i i += 1 else: newQuote = self.check(i, quote) if newQuote: if newQuote == quote: quote = None else: quote = newQuote i += len(newQuote) else: c = self[i] if quote: if c == '\\': i += 1 else: if skip is None or lastNonQuote != skip: if c == enter: depth += 1 elif c == exit: depth -= 1 if depth < 0: return i if c == comment and depth == 0: commented = True lastNonQuote = c i += 1 else: raise TransientParseError("expecting end of complex expression") def word(self, start=0, additional='._'): """Scan from start for a simple word.""" length = len(self) i = start while i < length: if not (self[i].isalnum() or self[i] in additional): return i i += 1 else: raise TransientParseError("expecting end of word") def phrase(self, start=0): """Scan from start for a phrase (e.g., 'word', 'f(a, b, c)', 'a[i]', or combinations like 'x[i](a)'.""" # Find the word. i = self.word(start) while i < len(self) and self[i] in PHRASE_OPENING_CHARS: enter = self[i] exit = ENDING_CHAR_MAP[enter] i = self.complex(enter, exit, None, i + 1) + 1 return i def simple(self, start=0): """Scan from start for a simple expression, which consists of one more phrases separated by dots. Return a tuple giving the end of the expression and a list of tuple pairs consisting of the simple expression extensions found, if any.""" i = self.phrase(start) length = len(self) while i < length and self[i] == DOT_CHAR: i = self.phrase(i) # Make sure we don't end with a trailing dot. while i > 0 and self[i - 1] == DOT_CHAR: i -= 1 return i def one(self, firebreaks=None): """Parse, scan, and return one token, or None if the scanner is empty. If the firebreaks argument is supplied, chop up text tokens before a character in that string.""" if not self: return None if not self.config.prefix: loc = -1 else: loc = self.find(self.config.prefix) if loc < 0: # If there's no prefix in the buffer, then set the location to the # end so the whole thing gets processed. loc = len(self) if loc == 0: # If there's a prefix at the beginning of the buffer, process # an expansion. prefix = self.chop(1) assert prefix == self.config.prefix, prefix try: first = self.chop(1) if first == self.config.prefix: first = None elif first in self.config.duplicativeFirsts: # If the first character is duplicative, there might be # more han one. Check if there is a second; if so, use # that as the first. if self.read() == first: first *= 2 tokenClass = self.factory(first) if tokenClass is None: raise ParseError("unknown markup sequence: `%s%s`%s" % (self.config.prefix, first, self.factory.addendum(first))) current = self.config.renderContext(self.context) self.currents.replace(current) token = tokenClass(current, self.config, first) token.scan(self) except TransientParseError: # If a transient parse error occurs, reset the buffer pointer # so we can (conceivably) try again later. self.unsync() raise else: # Process everything up to loc as a text token, unless there are # intervening firebreaks before loc. if firebreaks: for firebreak in firebreaks: i = self.find(firebreak, 0, loc) if i >= 0 and i < loc: loc = i data = self.chop(loc) current = self.config.renderContext(self.context) self.currents.replace(current) token = TextToken(current, data) self.sync() return token def all(self): """Yield a sequence of all tokens.""" while True: token = self.one() if token: yield token else: break # # Command ... # class Command(Root): """A generic high-level processing command.""" def __init__(self, noun): self.noun = noun def __str__(self): return self.noun def cleanup(self): pass def process(self, interp, n): """Run the command.""" raise NotImplementedError class ImportCommand(Command): """Import a Python module.""" def process(self, interp, n): name = '' % n context = interp.newContext(name) interp.pushContext(context) # Expand shortcuts. self.noun = self.noun.replace('+', ' ') self.noun = self.noun.replace('=', ' as ') method = interp.string if ':' in self.noun: first, second = self.noun.split(':', 1) target = '%s{from %s import %s}' % ( interp.config.prefix, first, second) else: target = '%s{import %s}' % (interp.config.prefix, self.noun) interp.protect(name, method, target) class DefineCommand(Command): """Define a Python variable.""" def process(self, interp, n): name = '' % n context = interp.newContext(name) interp.pushContext(context) if '=' in self.noun: interp.execute(self.noun) else: interp.atomic(self.noun.strip(), None) interp.popContext() class StringCommand(Command): """Define a Python string variable.""" def process(self, interp, n): if '=' in self.noun: key, value = self.noun.split('=', 1) key = key.strip() value = value.strip() else: key = self.noun.strip() value = '' interp.atomic(key, value) class DocumentCommand(Command): """Read and execute an EmPy document.""" def process(self, interp, n): name = self.noun method = interp.file self.target = None self.target = interp.config.open(self.noun, 'r') interp.protect(name, method, self.target) def cleanup(self): if self.target is not None: self.target.close() class ExecuteCommand(Command): """Execute a Python statement.""" def process(self, interp, n): name = '' % n context = interp.newContext(name) interp.pushContext(context) interp.execute(self.noun) interp.popContext() ExecCommand = ExecuteCommand # DEPRECATED class FileCommand(Command): """Load an execute a Python file.""" def process(self, interp, n): name = '' % n context = interp.newContext(name) interp.pushContext(context) try: file = interp.config.open(self.noun, 'r') try: data = file.read() finally: file.close() interp.execute(data) finally: interp.popContext() class ExpandCommand(Command): """Execute a Python statement.""" def process(self, interp, n): name = '' % n context = interp.newContext(name) interp.pushContext(context) try: interp.string(self.noun) finally: interp.popContext() # # Plugin # class Plugin(Root): """A plugin is an object associated with an interpreter that has a back-reference to it.""" def __init__(self, interp=None): if interp is not None: self.attach(interp) def attach(self, interp): """Attach this plugin to an interpreter. This needs to be a separate step since some methods require access to the interpreter.""" self.interp = interp def detach(self, interp=None): """Detach this plugin from an interpreter, or any interpreter if not specified. This breaks any cyclical links between the interpreter and the plugin.""" if interp is not None and interp is not self.interp: raise em.ConsistencyError("plugin not associated with this interpeter") self.interp = None def push(self): self.interp.push() def pop(self): self.interp.pop() # DEPRECATED: def register(self, interp): self.attach(interp) def deregister(self, interp=None): self.detach(interp) # # Core # class Core(Plugin): """A core encapsulates the functionality of the underlying language (Python by default). To create an object where this these are native methods to that class, derive a class from Core but do not call its constructor.""" casesVariable = '_EmPy_pairs' class Case: def __init__(self, expression, tokens): self.expression = expression self.tokens = tokens def __getitem__(self, index): if index == 0: return self.expression elif index == 1: return self.tokens else: raise IndexError def __len__(self): return 2 def __iter__(self): yield self.expression yield self.tokens def __init__(self, **kwargs): evaluate = extract(kwargs, 'evaluate', None) if evaluate is not None: self.evaluate = evaluate execute = extract(kwargs, 'execute', None) if execute is not None: self.execute = execute serialize = extract(kwargs, 'serialize', None) if serialize is not None: self.serialize = serialize define = extract(kwargs, 'define', None) if define is not None: self.define = define match = extract(kwargs, 'match', None) if match is not None: self.match = match interp = extract(kwargs, 'interp', None) if interp is not None: interp.insertCore(self) def quote(self, code): """Find the right quote for this code.""" if '"""' in code and "'''" in code: raise CoreError("cannot find proper quotes for code; code cannot contain both \'\'\' and \"\"\": %r" % code, code=code) if '"""' in code: return "'''" else: return '"""' # Implementation (override these) def evaluate(self, code, globals, locals=None): """Evaluate an expression and return it.""" if locals is None: return evalFunc(code, globals) else: return evalFunc(code, globals, locals) def execute(self, code, globals, locals=None): """Execute a statement(s); return value ignored.""" if locals is None: execFunc(code, globals) else: execFunc(code, globals, locals) def serialize(self, thing): """Return the string representation of an object.""" return toString(thing) def define(self, signature, definition, locals=None): """Implement @[def ...] markup; return value ignored.""" quote = self.quote(definition) quoted = quote + definition + quote code = ('def %s:\n' '\tr%s\n' '\treturn %s.expand(r%s, locals())\n' % (signature, quoted, self.interp.config.pseudomoduleName, quoted)) self.execute(code, self.interp.globals, locals) def match(self, expression, cases, locals=None): """Implement @[match ...] markup; return value ignored.""" if sys.version_info < (3, 10): raise CompatibilityError("`match` control requires `match` control structure (Python 3.10 and later)") if locals is None: locals = {} if cases and isinstance(cases[0], tuple): # Old-style form is that cases is a list of tuples. Transform them # into Cases. cases = [Core.Case(*x) for x in cases] locals[self.casesVariable] = cases lines = [] lines.append('match %s:\n' % expression) for i, case in enumerate(cases): lines.append('\tcase %s:\n' % case.expression) lines.append('\t\t%s.runSeveral(%s[%d].tokens, locals())\n' % ( self.interp.config.pseudomoduleName, self.casesVariable, i)) self.execute(''.join(lines), self.interp.globals, locals) # # Extension # class Extension(Plugin): """An extension plugin that the interpreter will defer to for non-standard markup.""" mapping = { '((': 'parentheses', '[[': 'square_brackets', '{{': 'curly_braces', '<': 'angle_brackets', } def __init__(self, mapping=None, **kwargs): if mapping is None: # The default class attribute will suffice. pass elif isinstance(mapping, dict): # A dict should be used directly. self.mapping = mapping elif isinstance(mapping, (list, set)): # A list of 2-tuples should be updated on top of the default. self.mapping = self.mapping.copy() self.mapping.update(mapping) else: raise ExtensionError("unknown mapping type (must be dict, list or None): %r" % mapping) for name, method in kwargs.items(): self.__dict__[name] = method # # Interpreter # class Interpreter(Root): """An interpreter can process chunks of EmPy code.""" # Compatibility. version = __version__ compat = compat # Constants. ASSIGN_TOKEN_RE = re.compile(r"[_a-zA-Z][_a-zA-Z0-9]*|\(|\)|,") AS_RE = re.compile(r"\bas\b") # Construction, initialization, destruction. def __init__(self, **kwargs): """Accept keyword arguments only, so users will never have to worry about the ordering of arguments.""" self.ok = None # is the interpreter initialized? self.shuttingDown = False # is the interpreter shutting down? config = extract(kwargs, 'config', None) if config is None: config = Configuration() core = extract(kwargs, 'core', None) if core is None: # Specifying the ...Func callbacks separately from the core is now # DEPRECATED. core = Core( evaluate=extract(kwargs, 'evalFunc', None), execute=extract(kwargs, 'execFunc', None), serialize=extract(kwargs, 'serializerFunc', None), define=extract(kwargs, 'definerFunc', None), match=extract(kwargs, 'matcherFunc', None), ) extension = extract(kwargs, 'extension', None) args = ( config, core, extension, extract(kwargs, 'ident', None), extract(kwargs, 'globals', None), extract(kwargs, 'output', None), extract(kwargs, 'executable', '?'), extract(kwargs, 'argv', None), extract(kwargs, 'filespec', None), extract(kwargs, 'hooks', None), extract(kwargs, 'finalizers', None), extract(kwargs, 'filters', None), extract(kwargs, 'callback', None), extract(kwargs, 'dispatcher', True), extract(kwargs, 'handler', None), extract(kwargs, 'input', sys.stdin), extract(kwargs, 'root', None), extract(kwargs, 'origin', False), extract(kwargs, 'immediately', True), ) if kwargs: # Any remaining keyword arguments are a mistake: either simple # typos, or an old-style specification of local variables in an # `expand` call. badKeys = [] for key in kwargs.keys(): if key not in config.ignoredConstructorArguments: badKeys.append(key) if badKeys: badKeys.sort() raise CompatibilityError("unrecognized Interpreter constructor keyword arguments; when calling expand, use locals dictionary instead of keywords: %s" % badKeys, keys=badKeys) self._initialize(*args) def __del__(self): self.shutdown() def __repr__(self): details = [] if self.ident: details.append(' "%s"' % self.ident) if self.config and self.config.name: details.append(' ("%s")' % self.config.name) return '<%s pseudomodule/interpreter object%s @ 0x%x>' % ( self.config.pseudomoduleName, ''.join(details), id(self)) def __bool__(self): return self.ok # 3.x def __nonzero__(self): return self.ok # 2.x def __enter__(self): self.check() return self def __exit__(self, *exc): self.shutdown() def _initialize(self, config=None, core=None, extension=None, ident=None, globals=None, output=None, executable=None, argv=None, filespec=None, hooks=None, finalizers=None, filters=None, callback=None, dispatcher=True, handler=None, input=sys.stdin, root=None, origin=False, immediately=True): """Initialize the interpreter with the given arguments (all of which have defaults). The number and order of arguments here is subject to change.""" self.ident = ident self.error = None # last error that occurred or None # Set up the configuration. if config is None: config = Configuration() self.config = config self.filespec = filespec self.globals = globals # Handle the executable and arguments. self.executable = executable if argv is None: argv = [None] if argv[0] is None: argv[0] = config.unknownScriptName self.argv = argv # The interpreter stacks. self.enabled = True self.contexts = Stack() self.streams = Stack() self.currents = Stack() # Initialize hooks. if hooks is None: hooks = [] self.hooks = [] self.hooksEnabled = None for hook in hooks: self.addHook(hook) # Initialize finalizers: if finalizers is None: finalizers = [] self.finalizers = [] self.setFinalizers(finalizers) # Initialize dispatcher. if dispatcher is True: dispatcher = self.dispatch elif dispatcher is False: dispatcher = self.reraise elif dispatcher is None: raise ConfigurationError("dispatcher cannot be None") self.dispatcher = dispatcher # Initialize handler. self.handler = None if handler is not None: self.setHandler(handler) # Install a proxy stdout if one hasn't been already. self.output = self.bottom(output) self.install(self.output) # Setup the execution core. self.insertCore(core) # Setup any extension. self.extension = None if extension is not None: self.installExtension(extension) # Initialize callback. self.callback = None if callback is not None: self.registerCallback(callback) # Setup the input file. self.input = input # Setup the root context. if root is None: root = self.config.defaultRoot self.root = root # Is this a top-level interpreter? self.origin = origin # Now declare that we've started up. self.ok = True self.invoke('atStartup') # Reset the state. self.reset(True) # Initialize filters (needs to be done after stacks are up). if filters: self.setFilterChain(filters) # Declare the interpreter ready. if immediately and not self.shuttingDown: self.ready() def _deinitialize(self): """Deinitialize by detaching all plugins. Called at the end of shutdown.""" self.clearHooks() self._deregisterCallback() self.clearFinalizers() self.resetHandler() self.uninstallExtension() self.ejectCore() def reset(self, clearStacks=False): """Completely reset the interpreter state. If clearStacks is true, wipe the call stacks. If immediately is true, declare the interpreter ready.""" self.ok = False self.error = None self.enabled = True # None is a special sentinel meaning "false until added." self.hooksEnabled = len(self.hooks) > 0 and True or None # Set up a diversions dictionary. self.diversions = {} # Significators. self.significators = {} # Now set up the globals. self.fixGlobals() self.globalsHistory = Stack() # Reset the command counter. self.command = 0 # Now, clear the state of all the stacks. if clearStacks: self.clear() self.current = None # Done. Now declare that we've started up. self.ok = True def ready(self): """Declare the interpreter ready for normal operations.""" self.invoke('atReady') def finalize(self): """Execute any remaining final routines.""" if self.finalizers: self.push() self.invoke('atFinalize') try: # Pop them off one at a time so they get executed in reverse # order and we remove them as they're executed in case # something bad happens. while self.finalizers: finalizer = self.finalizers.pop() if self.invoke('beforeFinalizer', finalizer=finalizer): continue finalizer() self.invoke('afterFinalizer') self.detach(finalizer) finally: self.pop() def install(self, output): """Given the desired output files, install any global apparatus.""" self.installProxy(output) if self.config.evocare() == 1: self.installFinder() def uninstall(self): """Uninstall any global apparatus. The apparatus should be installed.""" self.uninstallProxy() if self.config.evocare() is None: self.uninstallFinder() def succeeded(self): """Did the interpreter succeed? That is, is the logged error not an error?""" return self.config.isNotAnError(self.error) def pause(self): """Pause (at the end of processing).""" try: self.input.readline() except EOFError: pass def shutdown(self): """Declare this interpreting session over; close all the stream file objects, and if this is the last interpreter, uninstall the proxy and/or finder. This method is idempotent.""" if self.ok and not self.shuttingDown: self.shuttingDown = True # Finally, if we're supposed to go interactive afterwards, do it. if self.config.goInteractive: self.interact() # Wrap things up. self.ok = False succeeded = self.succeeded() try: self.finalize() self.invoke('atShutdown') while self.streams: stream = self.streams.pop() if self.streams: stream.close() else: # Don't close the bottom stream; auto-play diversions # and just flush it. if self.config.autoPlayDiversions and succeeded: stream.undivertAll() stream.flush() self.clear() finally: self.uninstall() if self.origin and self.evocare() is not None: raise ProxyError("proxy persists; did you not call shutdown?") # Deinitialize (detach all plugins). self._deinitialize() # Do a final flush of all the streams. self.flushAll() # Finally, pause if desired. if self.config.pauseAtEnd: self.pause() def check(self): """Check the verify this interpreter is still alive.""" if not self.ok: raise ConsistencyError("interpreter has already been shutdown") def failed(self): """Has this interpreter had an error (which we should not ignore)?""" return self.error and self.config.exitOnError # Installation delegates. def proxy(self, *args, **kwargs): return self.config.proxy(*args, **kwargs) def evocare(self, *args, **kwargs): return self.config.evocare(*args, **kwargs) def installProxy(self, *args, **kwargs): before = self.config.evocare() output = self.config.installProxy(*args, **kwargs) proxy = self.config.proxy() if proxy is not None: self.invoke('atInstallProxy', proxy=proxy, new=(before is None)) return output def uninstallProxy(self): proxy = self.config.proxy() self.config.uninstallProxy() after = self.config.evocare() self.invoke('atUninstallProxy', proxy=proxy, done=(after is None)) def checkProxy(self, *args, **kwargs): return self.config.checkProxy(*args, **kwargs) def installFinder(self, *args, **kwargs): self.config.installFinder(*args, **kwargs) finder = self.config.finder() self.invoke('atInstallFinder', finder=finder) def uninstallFinder(self): finder = self.config.finder() self.invoke('atUninstallFinder', finder=finder) self.config.uninstallFinder() # Writeable file-like methods. def enable(self, value=True): self.enabled = value def disable(self, value=False): self.enabled = value def write(self, data): stream = self.top() assert stream is not None stream.write(data) def writelines(self, lines): stream = self.top() assert stream is not None stream.writelines(lines) def flush(self): stream = self.top() assert stream is not None stream.flush() def flushAll(self): for stream in self.streams: stream.flush() def close(self): self.shutdown() def serialize(self, thing): """Output the string version of an object, or a special token if it is None.""" if thing is None: if self.config.noneSymbol is not None: self.write(self.config.noneSymbol) else: self.write(self.core.serialize(thing)) def bottom(self, output): """Get the underlying bottom file.""" # If there's no output, check the bottom file in the proxy first. if output is None: output = getattr(self.config.proxy(), '_EmPy_bottom', None) # Otherwise, default to the config's stdout. if output is None: output = self.config.defaultStdout return output # Stream stack-related activity. def top(self): """Get the top stream.""" return self.streams.top() def push(self): if self.config.useProxy and self.ok: try: sys.stdout._EmPy_push(self) except AttributeError: raise ProxyError("proxy lost; cannot push stream") def pop(self): if self.config.useProxy and self.ok: try: sys.stdout._EmPy_pop(self) except AttributeError: raise ProxyError("proxy lost; cannot pop stream") def clear(self): self.streams.purge() self.streams.push(Stream(self, self.output, self.diversions)) self.contexts.purge() context = self.newContext(self.root) self.contexts.push(context) self.currents.purge() self.currents.push(self.config.renderContext(context)) # Entry-level processing. def include(self, fileOrFilename, locals=None, name=None): """Do an include pass on a file or filename.""" close = False if isinstance(fileOrFilename, strType): # Either it's a string representing a filename ... filename = fileOrFilename if not name: name = filename file = self.config.open(filename, 'r') close = True else: # ... or a file object. file = fileOrFilename if not name: name = '<%s>' % toString(file.__class__.__name__) try: if self.invoke('beforeInclude', file=file, locals=locals, name=name): return if name: context = self.newContext(name) self.pushContext(context) self.file(file, locals) if name: self.popContext() finally: if close: file.close() self.invoke('afterInclude') def expand(self, data, locals=None, name='', dispatcher=False): """Do an explicit expansion on a subordinate stream in a new context. If dispatch is true, dispatch any exception through the interpreter; otherwise just reraise.""" if dispatcher is None: dispatcher = self.dispatcher elif dispatcher is True: dispatcher = self.dispatch elif dispatcher is False: dispatcher = self.reraise outFile = StringIO() stream = Stream(self, outFile, self.diversions) if self.invoke('beforeExpand', string=data, locals=locals, name=name, dispatcher=dispatcher): return self.push() self.streams.push(stream) try: if name: context = self.newContext(name) self.pushContext(context) try: self.string(data, locals, dispatcher) finally: if name: self.popContext() try: stream.flush() result = outFile.getvalue() except ValueError: # Premature termination will result in the file being closed; # ignore it. result = None self.invoke('afterExpand', result=result) return result finally: self.streams.pop() self.pop() # High-level processing. def go(self, inputFilename, inputMode, preprocessing=None, postprocessing=None): """Execute an interpreter stack at a high level.""" # Execute any preprocessing commands. if preprocessing is None: preprocessing = [] if postprocessing is None: postprocessing = [] self.processAll(preprocessing) # Ready! if not self.shuttingDown: self.ready() # Now process the primary file. method = self.file if inputFilename is None: # We'll be using stdin, so check the encoding. if not self.config.isDefaultEncodingErrors(asInput=True): self.config.reconfigure(sys.stdin, self.config.buffering, self.config.inputEncoding, self.config.inputErrors) self.config.goInteractive = True else: if inputFilename == '-': file = sys.stdin name = '' else: file = self.config.open(inputFilename, inputMode, self.config.buffering) name = inputFilename if self.config.relativePath: dirname = os.path.split(inputFilename)[0] sys.path.insert(0, dirname) try: self.protect(name, method, file) finally: if file is not sys.stdin: file.close() # Finally, execute any postprocessing commands. self.processAll(postprocessing) def protect(self, name, callable, *args, **kwargs): """Wrap around an application of a callable in a new context (named name).""" if name: context = self.newContext(name) self.pushContext(context) try: if kwargs is None: kwargs = {} callable(*args, **kwargs) finally: if name and self.contexts: self.popContext() def interact(self): """Perform interaction.""" self.invoke('atInteract') self.protect('', self.fileLines, self.input) def file(self, file, locals=None, dispatcher=None): """Parse a file according to the current buffering strategy.""" config = self.config if config.hasNoBuffering() or config.hasLineBuffering(): self.fileLines(file, locals, dispatcher) elif config.hasFullBuffering(): self.fileFull(file, locals, dispatcher) else: # if self.hasFixedBuffering() self.fileChunks(file, config.buffering, locals, dispatcher) def fileLines(self, file, locals=None, dispatcher=None): """Parse the entire contents of a file-like object, line by line.""" if self.invoke('beforeFileLines', file=file, locals=locals, dispatcher=dispatcher): return scanner = Scanner(self.config, self.getContext(), self.currents) done = False first = True while not done and not self.failed(): line = file.readline() if first: if self.config.ignoreBangpaths and self.config.prefix: if line.startswith(self.config.bangpath): line = self.config.prefix + line first = False if line: scanner.feed(line) else: done = True while not self.safe(scanner, done, locals, dispatcher): pass self.invoke('afterFileLines') def fileChunks(self, file, bufferSize=None, locals=None, dispatcher=None): """Parse the entire contents of a file-like object, in buffered chunks.""" if bufferSize is None: bufferSize = self.config.buffering assert bufferSize > 0, bufferSize if self.invoke('beforeFileChunks', file=file, bufferSize=bufferSize, locals=locals, dispatcher=dispatcher): return scanner = Scanner(self.config, self.getContext(), self.currents) done = False first = True while not done and not self.failed(): chunk = file.read(bufferSize) if first: if self.config.ignoreBangpaths and self.config.prefix: if chunk.startswith(self.config.bangpath): chunk = self.config.prefix + chunk first = False if chunk: scanner.feed(chunk) else: done = True while not self.safe(scanner, done, locals, dispatcher): pass self.invoke('afterFileChunks') def fileFull(self, file, locals=None, dispatcher=None): """Parse the entire contents of a file-like object, in one big chunk.""" if self.invoke('beforeFileFull', file=file, locals=locals, dispatcher=dispatcher): return scanner = Scanner(self.config, self.getContext(), self.currents) data = file.read() if self.config.ignoreBangpaths and self.config.prefix: if data.startswith(self.config.bangpath): data = self.config.prefix + data scanner.feed(data) while not self.safe(scanner, True, locals, dispatcher): pass self.invoke('afterFileFull') def string(self, string, locals=None, dispatcher=None): """Parse a string. Cleans up after itself.""" if self.invoke('beforeString', string=string, locals=locals, dispatcher=dispatcher): return scanner = Scanner(self.config, self.getContext(), self.currents, string) while not self.safe(scanner, True, locals, dispatcher): pass self.invoke('afterString') def safe(self, scanner, final=False, locals=None, dispatcher=None): """Do a protected parse. Catch transient parse errors; if final is true, then make a final pass with a terminator, otherwise ignore the transient parse error (more data is pending). Return true if the scanner is exhausted or if an error has occurred.""" if dispatcher is None: dispatcher = self.dispatcher try: return self.parse(scanner, locals) except TransientParseError: if final: buffer = scanner.rest() # If the buffer ends with a prefix, it's a real parse # error. if buffer and buffer.endswith(self.config.prefix): raise # Try tacking on a dummy terminator to take into account # greedy tokens. scanner.feed(self.config.prefix + NEWLINE_CHAR) try: # Any error thrown from here is a real parse error. self.parse(scanner, locals) except: if dispatcher(): return True return True except: if dispatcher(): return True def import_(self, filename, module, locals=None, dispatcher=None): """Import an EmPy module.""" if self.invoke('beforeImport', filename=filename, module=module, locals=locals, dispatcher=dispatcher): return globals = self.globals self.globals = vars(module) self.fixGlobals() switch = self.enabled if not self.config.enableImportOutput: self.disable() context = self.newContext(filename) self.pushContext(context) try: self.push() file = self.config.open(filename, 'r') try: self.file(file, locals, dispatcher) finally: file.close() self.pop() self.globals = globals self.enabled = switch self.invoke('afterImport') finally: self.popContext() def parse(self, scanner, locals=None): """Parse and run as much from this scanner as possible. Return true if the scanner ran out of tokens.""" self.invoke('atParse', scanner=scanner, locals=locals) while True: token = scanner.one() if token is None: break self.invoke('atToken', token=token) self.run(token, locals) scanner.accumulate() return True def process(self, command): """Process a command.""" if isinstance(command, list): # Backward compatibility: If process is called with a list, defer # to the explicit list version. self.processAll(command) return self.command += 1 if self.invoke('beforeProcess', command=command, n=self.command): return try: command.process(self, self.command) finally: command.cleanup() self.invoke('afterProcess') def processAll(self, commands): """Process a sequence of commands.""" for command in commands: self.process(command) # Medium-level processing. def tokens(self, tokens, locals=None): """Do an explicit result on a sequence of tokens. Cleans up after itself.""" outFile = StringIO() stream = Stream(self, outFile, self.diversions) if self.invoke('beforeTokens', tokens=tokens, locals=locals): return self.streams.push(stream) try: self.runSeveral(tokens, locals) stream.flush() result = outFile.getvalue() self.invoke('afterTokens', result=result) return result finally: self.streams.pop() def quote(self, data): """Quote the given string so that if it were expanded it would evaluate to the original.""" if self.invoke('beforeQuote', string=data): return scanner = Scanner(self.config, self.getContext(), self.currents, data) result = [] i = 0 try: j = scanner.next(self.config.prefix, i) result.append(data[i:j]) result.append(self.config.prefix * 2) i = j + 1 except TransientParseError: pass result.append(data[i:]) result = ''.join(result) self.invoke('afterQuote', result=result) return result def escape(self, data, more=''): """Escape a string so that nonprintable or non-ASCII characters are replaced with compatible EmPy expansions. Also treat characters in more as escapes.""" if self.invoke('beforeEscape', string=data, more=more): return result = [] for char in data: if char in more: result.append(self.config.prefix + '\\' + char) elif char < ' ' or char > '~': result.append(self.config.escaped(ord(char), self.config.prefix + '\\')) else: result.append(char) result = ''.join(result) self.invoke('afterEscape', result=result) return result def tokenize(self, name): """Take an lvalue string and return a name or a (possibly recursive) list of names.""" result = [] stack = [result] for garbage in self.ASSIGN_TOKEN_RE.split(name): garbage = garbage.strip() if garbage: raise ParseError("unexpected assignment token: `%s`" % garbage) tokens = self.ASSIGN_TOKEN_RE.findall(name) # While processing, put a None token at the start of any list in which # commas actually appear. for token in tokens: if token == '(': stack.append([]) elif token == ')': top = stack.pop() if len(top) == 1: top = top[0] # no None token means that it's not a 1-tuple elif top[0] is None: del top[0] # remove the None token for real tuples stack[-1].append(top) elif token == ',': if len(stack[-1]) == 1: stack[-1].insert(0, None) else: stack[-1].append(token) # If it's a 1-tuple at the top level, turn it into a real subsequence. if result and result[0] is None: result = [result[1:]] if len(result) == 1: return result[0] else: return result def atomic(self, name, value, locals=None): """Do an atomic assignment.""" if self.invoke('beforeAtomic', name=name, value=value, locals=locals): return if locals is None: self.globals[name] = value else: locals[name] = value self.invoke('afterAtomic') def multi(self, names, values, locals=None): """Do a (potentially recursive) assignment.""" if self.invoke('beforeMulti', names=names, values=values, locals=locals): return values = tuple(values) # to force an exception if not a sequence if len(names) != len(values): raise ValueError("unpack tuple of wrong size") for name, value in zip(names, values): if isinstance(name, strType): self.atomic(name, value, locals) else: self.multi(name, value, locals) self.invoke('afterMulti') def assign(self, name, value, locals=None): """Do a potentially complex (including tuple unpacking) assignment.""" left = self.tokenize(name) # The return value of tokenize can either be a string or a list of # (lists of) strings. if isinstance(left, strType): self.atomic(left, value, locals) else: self.multi(left, value, locals) def significate(self, key, value=None, locals=None): """Declare a significator.""" if self.invoke('beforeSignificate', key=key, value=value, locals=locals): return name = self.config.significatorFor(key) self.atomic(name, value, locals) self.significators[key] = value self.invoke('afterSignificate') def clause(self, catch, locals=None): """Given the string representation of an except clause, turn it into a 2-tuple consisting of the class name or tuple of names, and either a variable name or None. If the representation is None, then it's all exceptions and no name.""" if self.invoke('beforeClause', catch=catch, locals=locals): return done = False if catch is None: exceptionCode, variable = None, None done = True if not done: match = self.AS_RE.search(catch) if match: exceptionCode, variable = self.AS_RE.split(catch.strip(), 1) exceptionCode = exceptionCode.strip() variable = variable.strip() else: comma = catch.rfind(',') if comma >= 0: exceptionCode, variable = catch[:comma], catch[comma + 1:] exceptionCode = exceptionCode.strip() variable = variable.strip() else: exceptionCode, variable = catch.strip(), None if not exceptionCode: exception = self.config.baseException else: exception = self.evaluate(exceptionCode, locals) self.invoke('afterClause', exception=exception, variable=variable) return exception, variable def dictionary(self, code, locals=None): """Given a string representing a key-value argument list, turn it into a dictionary.""" code = code.strip() self.push() try: if self.invoke('beforeDictionary', code=code, locals=locals): return if code.strip(): result = self.evaluate('{%s}' % code, locals) else: result = {} self.invoke('afterDictionary', result=result) return result finally: self.pop() def literal(self, text, locals=None): """Process a string literal.""" if self.invoke('beforeLiteral', text=text, locals=locals): return result = self.evaluate(text, locals, replace=False) self.serialize(result) self.invoke('afterLiteral', result=result) def functional(self, code, tokensLists, locals=None): """Handle a functional expression like @f{x} and return the result. code is the Python code to evaluate tokensLists is a list of list of tokens.""" self.push() try: if self.invoke('beforeFunctional', code=code, lists=tokensLists, locals=locals): return function = self.evaluate(code, locals) arguments = [] for tokensSublist in tokensLists: arguments.append(self.tokens(tokensSublist, locals)) result = function(*tuple(arguments)) self.invoke('afterFunctional', result=result) return result finally: self.pop() # Low-level evaluation. def run(self, token, locals=None): """Run a token, tracking the current context.""" token.run(self, locals) def runSeveral(self, tokens, locals=None): """Run a sequence of tokens.""" for token in tokens: self.run(token, locals) def defined(self, name, locals=None): """Return a Boolean indicating whether or not the name is defined either in the locals or the globals.""" if self.invoke('beforeDefined', name=name, locals=locals): return result = False if locals is not None and name in locals: result = True elif name in self.globals: result = True self.invoke('afterDefined', result=result) return result def lookup(self, variable, locals=None): """Lookup the value of a variable.""" if locals is not None and variable in locals: return locals[variable] else: return self.globals[variable] def evaluate(self, expression, locals=None, replace=True): """Evaluate an expression. If replace is true, replace newlines in the expression with spaces if that config variable is set; otherwise, don't do it regardless.""" self.push() try: if self.invoke('beforeEvaluate', expression=expression, locals=locals, replace=replace): return if replace and self.config.replaceNewlines: expression = expression.replace('\n', ' ') if locals is not None: result = self.core.evaluate(expression, self.globals, locals) else: result = self.core.evaluate(expression, self.globals) self.invoke('afterEvaluate', result=result) return result finally: self.pop() def execute(self, statements, locals=None): """Execute a statement(s).""" # If there are any carriage returns (as opposed to linefeeds/newlines) # in the statements code, then remove them. Even on Windows platforms, # this will work in the Python interpreter. if CARRIAGE_RETURN_CHAR in statements: statements = statements.replace(CARRIAGE_RETURN_CHAR, '') # If there are no newlines in the statements code, then strip any # leading or trailing whitespace. if statements.find(NEWLINE_CHAR) < 0: statements = statements.strip() self.push() try: if self.invoke('beforeExecute', statements=statements, locals=locals): return self.core.execute(statements, self.globals, locals) self.invoke('afterExecute') finally: self.pop() def single(self, source, locals=None): """Execute an expression or statement, just as if it were entered into the Python interactive interpreter.""" self.push() try: if self.invoke('beforeSingle', source=source, locals=locals): return code = compile(source, '', 'single') result = self.core.execute(code, self.globals, locals) self.invoke('afterSingle', result=result) return result finally: self.pop() # # Pseudomodule routines. # # Identification. def identify(self): """Identify the topmost context with a tuple of the name and counters.""" return self.getContext().identify() # Contexts. def getContext(self): """Get the top context.""" return self.contexts.top() def newContext(self, name='', line=None, column=None, chars=None): """Create and return a new context.""" if isinstance(name, tuple): # If name is a tuple, then use it as an argument. return self.newContext(*name) elif isinstance(name, Context): # If it's a Context, create a fresh clone of it. context = Context('', 0, 0, startingLine=self.config.startingLine, startingColumn=self.config.startingColumn) context.restore(name) return context else: # Otherwise, build it up from scratch. if line is None: line = self.config.startingLine if column is None: column = self.config.startingColumn if chars is None: chars = 0 return Context(name, line, column, chars) def pushContext(self, context): """Push a new context on the stack.""" self.invoke('pushContext', context=context) self.contexts.push(context) self.currents.push(self.config.renderContext(context)) def popContext(self): """Pop the top context.""" context = self.contexts.pop() self.currents.pop() self.invoke('popContext', context=context) def setContext(self, context): """Replace the top context.""" self.contexts.replace(context) self.currents.replace(self.config.renderContext(context)) self.invoke('setContext', context=context) def setContextName(self, name): """Set the name of the topmost context.""" context = self.getContext() context.name = name self.currents.replace(self.config.renderContext(context)) self.invoke('setContext', context=context) def setContextLine(self, line): """Set the line number of the topmost context.""" context = self.getContext() context.line = line self.currents.replace(self.config.renderContext(context)) self.invoke('setContext', context=context) def setContextColumn(self, column): """Set the column number of the topmost context.""" context = self.getContext() context.column = column self.currents.replace(self.config.renderContext(context)) self.invoke('setContext', context=context) def setContextData(self, name=None, line=None, column=None, chars=None): """Set any of the name, line, or column of the topmost context.""" context = self.getContext() if name is not None: context.name = name if line is not None: context.line = line if column is not None: context.column = column if chars is not None: context.chars = chars self.currents.replace(self.config.renderContext(context)) self.invoke('setContext', context=context) def restoreContext(self, oldContext, strict=False): """Restore from an old context.""" context = self.getContext() context.restore(oldContext, strict) self.currents.replace(self.config.renderContext(context)) self.invoke('restoreContext', context=context) # Plugins. def attach(self, plugin): """Attach the plugin to this interpreter.""" if hasattr(plugin, 'attach'): plugin.attach(self) def detach(self, plugin): """Detach the plugin from this interpreter.""" if hasattr(plugin, 'detach'): plugin.detach(self) # Finalizers. def clearFinalizers(self): """Clear all finalizers.""" for finalizer in self.finalizers: self.detach(finalizer) self.finalizers = [] def appendFinalizer(self, finalizer): """Register a function to be called at exit.""" self.attach(finalizer) self.finalizers.append(finalizer) def prependFinalizer(self, finalizer): """Register a function to be called at exit.""" self.attach(finalizer) self.finalizers.insert(0, finalizer) def setFinalizers(self, finalizers): self.clearFinalizers() for finalizer in finalizers: self.attach(finalizer) self.finalizers = finalizers atExit = appendFinalizer # DEPRECATED # Globals. def fixGlobals(self): """Reset the globals, stamping in the pseudomodule.""" if self.globals is None: self.globals = {} # Make sure that there is no collision between two interpreters' # globals. if self.config.pseudomoduleName in self.globals: if self.globals[self.config.pseudomoduleName] is not self: raise ConsistencyError("interpreter pseudomodule collision in globals") # And finally, flatten the namespaces if that option has been set. if self.config.doFlatten: self.flattenGlobals() self.globals[self.config.pseudomoduleName] = self def unfixGlobals(self): """Remove the pseudomodule (if present) from the globals.""" for unwantedKey in self.config.unwantedGlobalsKeys: # None is a special sentinel that must be replaced with the name of # the pseudomodule. if unwantedKey is None: unwantedKey = self.config.pseudomoduleName if unwantedKey in self.globals: del self.globals[unwantedKey] def getGlobals(self): """Retrieve the globals.""" return self.globals def setGlobals(self, globals): """Set the globals to the specified dictionary.""" self.globals = globals self.fixGlobals() def updateGlobals(self, otherGlobals): """Merge another mapping object into this interpreter's globals.""" self.globals.update(otherGlobals) self.fixGlobals() def clearGlobals(self): """Clear out the globals with a brand new dictionary.""" self.globals = {} self.fixGlobals() def pushGlobals(self, globals): """Push a globals dictionary onto the history stack.""" self.globalsHistory.push(globals) def popGlobals(self): """Pop a globals dictinoary off the history stack and return it.""" return self.globalsHistory.pop() def saveGlobals(self, deep=True): """Save a copy of the globals off onto the history stack.""" if deep: copyMethod = copy.deepcopy else: copyMethod = copy.copy self.unfixGlobals() self.globalsHistory.push(copyMethod(self.globals)) self.fixGlobals() def restoreGlobals(self, destructive=True): """Restore the most recently saved copy of the globals.""" if destructive: fetchMethod = self.globalsHistory.pop else: fetchMethod = self.globalsHistory.top self.unfixGlobals() self.globals = fetchMethod() self.fixGlobals() def flattenGlobals(self, skipKeys=None): """Flatten the contents of the pseudo-module into the globals namespace.""" flattened = {} if skipKeys is None: skipKeys = self.config.unflattenableGlobalsKeys # The pseudomodule is really a class instance, so we need to fumble # using getattr instead of simply fumbling through the instance's # __dict__. for key in self.__dict__.keys(): if key not in skipKeys and not key.startswith('_'): flattened[key] = getattr(self, key) for key in self.__class__.__dict__.keys(): if key not in skipKeys and not key.startswith('_'): flattened[key] = getattr(self, key) # Stomp everything into the globals namespace. self.globals.update(flattened) # Prefix. def getPrefix(self): """Get the current prefix.""" return self.config.prefix def setPrefix(self, prefix): """Set the prefix.""" assert (prefix is None or (isinstance(prefix, strType) and len(prefix) == 1)), prefix self.config.prefix = prefix # Diversions. def stopDiverting(self): """Stop any diverting.""" self.top().revert() def createDiversion(self, name): """Create a diversion (but do not divert to it) if it does not already exist.""" self.top().create(name) def retrieveDiversion(self, name, *defaults): """Retrieve the diversion object associated with the name.""" return self.top().retrieve(name, *defaults) def startDiversion(self, name): """Start diverting to the given diversion name.""" self.top().divert(name) def playDiversion(self, name, drop=True): """Play the given diversion and then drop it.""" self.top().undivert(name, drop) def replayDiversion(self, name, drop=False): """Replay the diversion without dropping it.""" self.top().undivert(name, drop) def dropDiversion(self, name): """Eliminate the given diversion.""" self.top().drop(name) def playAllDiversions(self): """Play all existing diversions and then drop them.""" self.top().undivertAll(True) def replayAllDiversions(self): """Replay all existing diversions without dropping them.""" self.top().undivertAll(False) def dropAllDiversions(self): """Drop all existing diversions.""" self.top().dropAll() def getCurrentDiversionName(self): """Get the name of the current diversion.""" return self.top().current def getAllDiversionNames(self): """Get the names of all existing diversions.""" return self.top().names() def isExistingDiversionName(self, name): """Does a diversion with this name currently exist?""" return self.top().has(name) # Filters. def resetFilter(self): """Reset the filter stream so that it does no filtering.""" self.top().install(None) def getFilter(self): """Get the top-level filter.""" filter = self.top().sink if filter is self.top().file: return None else: return filter getFirstFilter = getFilter def getLastFilter(self): """Get the last filter in the current chain.""" return self.top().last() def getFilterCount(self): """Get the number of chained filters; 0 means no active filters.""" return self.top().count() def setFilter(self, *filters): """Set the filter.""" self.top().install(filters) def prependFilter(self, filter): """Attach a single filter to the end of the current filter chain.""" self.top().prepend(filter) def appendFilter(self, filter): """Attach a single filter to the end of the current filter chain.""" self.top().append(filter) attachFilter = appendFilter # DEPRECATED def setFilterChain(self, filters): """Set the filter.""" self.top().install(filters) # Core-related activity. def hasCore(self): """Does this interpreter have a core inserted?""" return self.core is not None def getCore(self): """Get this interpreter's core or None.""" return self.core def insertCore(self, core=None): """Insert and attach the execution core.""" if core is None: core = Core() self.attach(core) self.core = core def ejectCore(self): """Clear the execution core, breaking a potential cyclical link.""" if self.core is not None: self.detach(self.core) self.core = None def resetCore(self): """Reset the execution core to the default core.""" self.ejectCore() self.insertCore() # Extension-related activity. def hasExtension(self): """Does this interpreter have an extension installed?""" return self.extension is not None def installExtension(self, extension): """Install an extension.""" if self.extension is not None: raise ExtensionError("cannot replace an installed extension") self.extension = extension self.attach(extension) # Now make sure there are token classes for them. factory = self.config.getFactory() for first, name in extension.mapping.items(): factory.addToken(self.config.createExtensionToken(first, name)) def uninstallExtension(self): """Uninstall any extension. This should only be done by the interpreter itself at shutdown time.""" if self.extension is not None: self.detach(self.extension) self.extension = None def callExtension(self, name, contents, depth, locals): if self.extension is None: raise ExtensionError("no extension installed") method = getattr(self.extension, name, None) if method is None: raise ExtensionError("extension name `%s` not defined; define method on extension object" % name) if self.callback is not None: # Legacy callback behavior: only pass the contents argument. result = method(contents) else: result = method(contents, depth, locals) self.serialize(result) return result # Hooks. def invokeHook(self, _name, **kwargs): """Invoke the hook(s) associated with the hook name, should they exist. Stop and return on the first hook which returns a true result.""" if self.config.verbose: self.config.verboseFile.write("%s: %r\n" % (_name, kwargs)) if self.hooksEnabled: for hook in self.hooks: try: method = getattr(hook, _name) result = method(**kwargs) if result: return result finally: pass return None invoke = invokeHook def areHooksEnabled(self): """Return whether or not hooks are presently enabled.""" if self.hooksEnabled is None: # None is a special value indicate that hooks are enabled but none # have been added yet. It is equivalent to true for testing but # can be optimized away upon invocation. return True else: return self.hooksEnabled def enableHooks(self): """Enable hooks.""" self.hooksEnabled = True def disableHooks(self): """Disable hooks.""" self.hooksEnabled = False def getHooks(self): """Get the current hooks.""" return self.hooks def addHook(self, hook, prepend=False): """Add a new hook; optionally insert it rather than appending it.""" self.attach(hook) if self.hooksEnabled is None: self.hooksEnabled = True if prepend: self.hooks.insert(0, hook) else: self.hooks.append(hook) def appendHook(self, hook): """Append the given hook.""" self.addHook(hook, False) def prependHook(self, hook): """Prepend the given hook.""" self.addHook(hook, True) def removeHook(self, hook): """Remove a preexisting hook.""" self.detach(hook) self.hooks.remove(hook) def clearHooks(self): """Clear all hooks.""" for hook in self.hooks: self.detach(hook) self.hooks = [] self.hooksEnabled = None # Callbacks (DEPRECATED). def hasCallback(self): """Is there a custom callback registered?""" return self.callback is not None def getCallback(self): """Get the custom markup callback registered with this interpreter, or None.""" return self.callback def registerCallback(self, callback, extensionFactory=Extension): """Register a custom markup callback with this interpreter.""" if self.callback: raise ExtensionError("old-style callbacks cannot be reregistered; use extensions instead") if self.hasExtension(): raise ExtensionError("old-style callbacks cannot be registered over existing extension; add `angle_brackets` method to extension instead") self.callback = callback self.attach(callback) extension = extensionFactory(angle_brackets=callback) self.installExtension(extension) def deregisterCallback(self): """Remove any previously registered custom markup callback with this interpreter.""" raise ExtensionError("old-style callbacks cannot be deregistered; use extensions instead") def _deregisterCallback(self): """Remove any previously registered custom markup callback with this interpreter. Internal use only.""" if self.callback is not None: self.detach(self.callback) self.callback = None def invokeCallback(self, contents): """Call the custom markup callback.""" if self.invoke('beforeCallback', contents=contents): return if self.callback is None: raise ConfigurationError("custom markup `@<...>` invoked with no defined callback") else: result = self.callback(contents) self.invoke('afterCallback', result=result) return result # Error handling. def getExitCode(self): """Get the exit code corresponding for the current error (if any).""" return self.config.errorToExitCode(self.error) def exit(self, exitCode=None): """Exit. If exitCode is None, use the exit code from the current error (which may itself be None for no error).""" if exitCode is None: exitCode = self.getExitCode() # If we are supposed to delete the file on error, do it. if exitCode != self.config.successCode and self.config.deleteOnError: if self.filespec is not None: os.remove(self.filespec[0]) def reraise(self, *args): """Reraise an exception.""" raise def dispatch(self, triple=None): """Dispatch an exception.""" if self.config.ignoreErrors: return False if triple is None: triple = sys.exc_info() type, error, traceback = triple # If error is None, then this is a old-style string exception. if error is None: error = StringError(type) # If it's a keyboard interrupt, quit immediately. if isinstance(type, KeyboardInterrupt): fatal = True else: fatal = False # Now handle the exception. self.handle((type, error, traceback), fatal) return self.error is not None and self.config.exitOnError def handle(self, info, fatal=False): """Handle an actual error that occurred.""" self.invoke('atHandle', info=info, fatal=fatal, contexts=self.currents) type, self.error, traceback = info if self.config.isExitError(self.error): # No Python exception, but we're going to exit. fatal = True else: useDefault = True if self.handler is not None: # Call the customer handler. useDefault = self.handler(type, self.error, traceback) if useDefault and self.error is not None: # Call the default handler if there's still an error. self.defaultHandler(type, self.error, traceback) if self.config.rawErrors: raise if self.error is not None and (fatal or self.config.exitOnError): self.shutdown() self.exit() def defaultHandler(self, type, error, traceback): """Report an error.""" first = True self.flush() sys.stderr.write('\n') for current in self.currents: if current is None: current = self.config.renderContext(self.getContext()) if first: if error is not None: description = "error: %s" % self.config.formatError(error) else: description = "error" else: description = "from this context" first = False sys.stderr.write('%s: %s\n' % (current, description)) sys.stderr.flush() def getHandler(self): """Get the current handler, or None for the default.""" return self.handler def setHandler(self, handler, exitOnError=False): """Set the current handler. Additionally, specify whether errors should exit (defaults to false with a custom handler).""" if self.handler is not None: self.detach(self.handler) self.attach(handler) self.handler = handler if exitOnError is not None: self.config.exitOnError = exitOnError def resetHandler(self, exitOnError=None): """Reset the current handler to the default.""" if self.handler is not None: self.detach(self.handler) self.handler = None if exitOnError is not None: self.config.exitOnError = exitOnError def invokeHandler(self, *args): """Manually invoke the error handler with the given exception info 3-tuple or three arguments.""" if len(args) == 1: self.handler(*args[0]) else: self.handler(*args) # Emojis. def initializeEmojiModules(self, moduleNames=None): """Determine which emoji module to use. If moduleNames is not specified, use the defaults.""" return self.config.initializeEmojiModules(moduleNames) def getEmojiModule(self, moduleName): """Return an abstracted emoji module by name or return None.""" return self.config.emojiModules.get(moduleName) def getEmojiModuleNames(self): """Return the emoji module names in usage in their proper order.""" return self.config.emojiModuleNames def substituteEmoji(self, text): """Substitute an emoji text or return None.""" return self.config.substituteEmoji(text) # # functions # def extract(dict, key, default): """Retrieve the value of the given key in this dictionary, but delete it first. If the key is not present, use the given default.""" if key in dict: value = dict.get(key) del dict[key] else: value = default return value def details(level, config=None, prelim="Welcome to ", postlim=".\n", file=sys.stdout): """Write some details, using the details subsystem if available.""" if config is None: config = Configuration() config.installFinder(dryRun=True) try: write = file.write details = None if level > Version.VERSION: try: import emlib details = emlib.Details(config) except ImportError: raise ConfigurationError("missing emlib module; details subsystem not available") if details is not None: try: details.show(level, prelim, postlim, file) except TypeError: raise else: write("%s%s version %s%s" % (prelim, __project__, __version__, postlim)) sys.stdout.flush() finally: config.uninstallFinder() def expand(data, _globals=None, _argv=None, _prefix=None, _pseudo=None, _options=None, **kwargs): """Do a self-contained expansion of the given source data, creating and shutting down an interpreter dedicated to the task. Expects the same keyword arguments as the Interpreter constructor. Additionally, 'name' will identify the expansion filename and 'locals', if present, represents the locals dictionary to use. The sys.stdout object is saved off and then replaced before this function returns. Any exception that occurs will be raised to the caller.""" # For backward compatibility. These arguments (starting with an # underscore) are now DEPRECATED. if _globals is not None: if 'globals' in kwargs: raise CompatibilityError("keyword arguments contain extra `globals` key; use keyword arguments") kwargs['globals'] = _globals if _argv is not None: if 'argv' in kwargs: raise CompatibilityError("keyword arguments contain extra `argv` key; use keyword arguments") kwargs['argv'] = _argv if _prefix is not None: raise CompatibilityError("_prefix argument to expand no longer supported; use prefix configuration variable") if _pseudo is not None: raise CompatibilityError("_pseudo argument to expand no longer supported; use pseudomoduleName configuration variable") if _options is not None: raise CompatibilityError("options dictionary is no longer supported; use configurations") # Keyword argument compatibility checks. for key in ['filters', 'handler', 'input', 'output']: if kwargs.get(key): raise ConfigurationError("argument does not make sense with an ephemeral interpreter; use a non-ephemeral interpreter instead: `%s`" % key, key=key) # Set up the changed defaults. if 'dispatcher' not in kwargs: kwargs['dispatcher'] = False # And then the local variables. name = extract(kwargs, 'name', '') locals = extract(kwargs, 'locals', None) if isinstance(locals, dict) and len(locals) == 0: # If there were no keyword arguments specified, don't use a locals # dictionary at all. locals = None interp = None result = None try: interp = Interpreter(**kwargs) result = interp.expand(data, locals, name, dispatcher=None) finally: if interp: interp.shutdown() interp.unfixGlobals() # remove pseudomodule to prevent clashes return result def invoke(args, **kwargs): """Run a standalone instance of an EmPy interpreter with the given command line arguments. See the Interpreter constructor for the keyword arguments.""" # Get the defaults. config = extract(kwargs, 'config', None) errors = extract(kwargs, 'errors', ()) globals = extract(kwargs, 'globals', {}) hooks = extract(kwargs, 'hooks', []) output = extract(kwargs, 'output', None) for key in ['filespec', 'immediately']: if key in kwargs: raise ConfigurationError("argument cannot be specified with invoke: %s" % key, key=key) # Initialize the options. if config is None: config = Configuration() if errors is None: errors = config.topLevelErrors # Let's go! try: interp = None inputFilename = None inputMode = 'r' outputFilename = None outputMode = None nullFile = False preprocessing = [] postprocessing = [] preinitializers = [] postinitializers = [] configStatements = [] configPaths = [] immediately = False level = Version.NONE topics = None # Note any configuration files from the environment. configPath = config.environment(CONFIG_ENV) if configPath is not None: configPaths.append(configPath) # Get any extra arguments from the environment. extraArguments = config.environment(OPTIONS_ENV) if extraArguments is not None: extraArguments = extraArguments.split() args = extraArguments + args # Parse the arguments. try: SHORTS = 'VWZh?H:vp:qm:fkersidnc:Co:a:O:A:b:NLBP:Q:I:D:S:E:F:G:K:X:Y:wlux:y:z:gj' LONGS = ['version', 'info', 'details', 'help', 'topic=', 'topics=', 'extended-help=', 'verbose', 'prefix=', 'no-prefix', 'no-output', 'pseudomodule=', 'module=', 'flatten', 'keep-going', 'ignore-errors', 'raw-errors', 'brief-errors', 'verbose-errors', 'interactive', 'delete-on-error', 'no-proxy', 'no-override-stdout', 'config=', 'configuration=', 'config-file=', 'configuration-file=', 'config-variable=', 'configuration-variable=', 'ignore-missing-config', 'output=' 'append=', 'output-binary=', 'append-binary=', 'output-mode=', 'input-mode=', 'buffering=', 'default-buffering', 'no-buffering', 'line-buffering', 'full-buffering', 'preprocess=', 'postprocess=', 'import=', 'define=', 'string=', 'execute=', 'file=', 'postfile=', 'postexecute=', 'expand=', 'postexpand=', 'preinitializer=', 'postinitializer=', 'pause-at-end', 'relative-path', 'replace-newlines', 'no-replace-newlines', 'ignore-bangpaths', 'no-ignore-bangpaths', 'expand-user', 'no-expand-user', 'auto-validate-icons', 'no-auto-validate-icons', 'none-symbol=', 'no-none-symbol', 'starting-line=', 'starting-column=', 'emoji-modules=', 'no-emoji-modules', 'disable-emoji-modules', 'ignore-emoji-not-found', 'binary', 'input-binary', 'unicode', 'encoding=', 'unicode-encoding=', 'input-encoding=', 'unicode-input-encoding=', 'output-encoding=', 'unicode-output-encoding=', 'errors=', 'unicode-errors=', 'input-errors=', 'unicode-input-errors=', 'output-errors=', 'unicode-output-errors=', 'normalization-form=', 'unicode-normalization-form=', 'auto-play-diversions', 'no-auto-play-diversions', 'check-variables', 'no-check-variables', 'path-separator=', 'enable-modules', 'disable-modules', 'module-extension=', 'module-finder-index=', 'enable-import-output', 'disable-import-output', 'context-format=', 'success-code=', 'failure-code=', 'unknown-code=', 'null-hook', 'requirements='] pairs, argv = getopt.getopt(args, SHORTS, LONGS) except getopt.GetoptError: type, error, traceback = sys.exc_info() if error.args[1] in ['H', 'topic', 'topics', 'extended-help']: # A missing argument with -H should be interpreted as -H all. pairs = [] topics = 'all' else: raise InvocationError(*error.args) for option, argument in pairs: if option in ['-V', '--version']: level += 1 elif option in ['-W', '--info']: if level < Version.INFO: level = Version.INFO else: level += 1 elif option in ['-Z', '--details']: level = Version.ALL elif option in ['-h', '-?', '--help']: if not topics: topics = 'default' elif topics == 'default': topics = 'more' else: topics = 'all' elif option in ['-H', '--topic', '--topics', '--extended-help']: topics = argument if ',' in topics: topics = topics.split(',') else: topics = [topics] elif option in ['-v', '--verbose']: config.verbose = True elif option in ['-p', '--prefix']: config.prefix = argument elif option in ['--no-prefix']: config.prefix = None elif option in ['-q', '--no-output']: nullFile = True elif option in ['-m', '--pseudomodule', '--module']: config.pseudomoduleName = argument elif option in ['-f', '--flatten']: config.doFlatten = True elif option in ['-k', '--keep-going']: config.exitOnError = False elif option in ['-e', '--ignore-errors']: config.ignoreErrors = True config.exitOnError = False elif option in ['-r', '--raw-errors']: config.rawErrors = True elif option in ['-s', '--brief-errors']: config.verboseErrors = False elif option in ['--verbose-errors']: config.verboseErrors = True elif option in ['-i', '--interactive']: config.goInteractive = True elif option in ['-d', '--delete-on-error']: config.deleteOnError = True elif option in ['-n', '--no-proxy', '--no-override-stdout']: config.useProxy = False elif option in ['--config', '--configuration']: configStatements.append(argument) elif option in ['-c', '--config-file', '--configuration-file']: configPaths.append(argument) elif option in ['--config-variable', '--configuration-variable']: config.configVariableName = argument elif option in ['-C', '--ignore-missing-config']: config.missingConfigIsError = False elif option in ['-o', '--output']: outputFilename = argument outputMode = 'w' elif option in ['-a', '--append']: outputFilename = argument outputMode = 'a' elif option in ['-O', '--output-binary']: outputFilename = argument outputMode = 'wb' elif option in ['-A', '--append-binary']: outputFilename = argument outputMode = 'ab' elif option in ['--output-mode']: outputMode = argument elif option in ['--input-mode']: inputMode = argument elif option in ['-b', '--buffering']: config.setBuffering(argument) elif option in ['--default-buffering']: config.setBuffering(config.defaultBuffering) elif option in ['-N', '--no-buffering']: config.setBuffering(config.noBuffering) elif option in ['-L', '--line-buffering']: config.setBuffering(config.lineBuffering) elif option in ['-B', '--full-buffering']: config.setBuffering(config.fullBuffering) elif option in ['-I', '--import']: for module in argument.split(','): module = module.strip() preprocessing.append(ImportCommand(module)) elif option in ['-D', '--define']: preprocessing.append(DefineCommand(argument)) elif option in ['-S', '--string']: preprocessing.append(StringCommand(argument)) elif option in ['-P', '--preprocess']: preprocessing.append(DocumentCommand(argument)) elif option in ['-Q', '--postprocess']: postprocessing.append(DocumentCommand(argument)) elif option in ['-E', '--execute']: preprocessing.append(ExecuteCommand(argument)) elif option in ['-F', '--file']: preprocessing.append(FileCommand(argument)) elif option in ['-G', '--postfile']: postprocessing.append(FileCommand(argument)) elif option in ['-K', '--postexecute']: postprocessing.append(ExecuteCommand(argument)) elif option in ['-X', '--expand']: preprocessing.append(ExpandCommand(argument)) elif option in ['-Y', '--postexpand']: postprocessing.append(ExpandCommand(argument)) elif option in ['--preinitializer']: preinitializers.append(argument) elif option in ['--postinitializer']: postinitializers.append(argument) elif option in ['-w', '--pause-at-end']: config.pauseAtEnd = True elif option in ['-l', '--relative-path']: config.relativePath = True elif option in ['--replace-newlines']: config.replaceNewlines = True elif option in ['--no-replace-newlines']: config.replaceNewlines = False elif option in ['--ignore-bangpaths']: config.ignoreBangpaths = True elif option in ['--no-ignore-bangpaths']: config.ignoreBangpaths = False elif option in ['--expand-user']: config.expandUserConstructions = True elif option in ['--no-expand-user']: config.expandUserConstructions = False elif option in ['--auto-validate-icons']: config.autoValidateIcons = True elif option in ['--no-auto-validate-icons']: config.autoValidateIcons = False elif option in ['--none-symbol']: config.noneSymbol = argument elif option in ['--no-none-symbol']: config.noneSymbol = None elif option in ['--starting-line']: config.startingLine = int(argument) elif option in ['--starting-column']: config.startingColumn = int(argument) elif option in ['--emoji-modules']: moduleNames = [x.strip() for x in argument.split(',')] if moduleNames == ['None'] or moduleNames == ['']: moduleNames = None config.emojiModuleNames = moduleNames elif option in ['--no-emoji-modules']: config.emojiModuleNames = config.defaultNoEmojiModuleNames elif option in ['--disable-emoji-modules']: config.emojiModuleNames = None elif option in ['--ignore-emoji-not-found']: config.emojiNotFoundIsError = False elif option in ['-u', '--binary', '--input-binary', '--unicode']: config.enableBinary() elif option in ['-x', '--encoding', '--unicode-encoding']: config.enableBinary(major, minor) config.inputEncoding = config.outputEncoding = argument elif option in ['--input-encoding', '--unicode-input-encoding']: config.enableBinary(major, minor) config.inputEncoding = argument elif option in ['--output-encoding', '--unicode-output-encoding']: config.enableBinary(major, minor) config.outputEncoding = argument elif option in ['-y', '--errors', '--unicode-errors']: config.enableBinary(major, minor) config.inputErrors = config.outputErrors = argument elif option in ['--input-errors', '--unicode-input-errors']: config.enableBinary(major, minor) config.inputErrors = argument elif option in ['--output-errors', '--unicode-output-errors']: config.enableBinary(major, minor) config.outputErrors = argument elif option in ['-z', '--normalization-form', '--unicode-normalization-form']: if argument == 'none' or argument == 'None': argument = '' config.normalizationForm = argument elif option in ['--auto-play-diversions']: config.autoPlayDiversions = True elif option in ['--no-auto-play-diversions']: config.autoPlayDiversions = False elif option in ['--check-variables']: config.checkVariables = True elif option in ['--no-check-variables']: config.checkVariables = False elif option in ['--path-separator']: config.pathSeparator = argument elif option in ['--enable-modules']: config.supportModules = True elif option in ['-g', '--disable-modules']: config.supportModules = False config.moduleExtension = argument elif option in ['--module-extension']: config.moduleExtension = argument elif option in ['--module-finder-index']: config.moduleFinderIndex = int(argument) elif option in ['--enable-import-output']: config.enableImportOutput = True elif option in ['-j', '--disable-import-output']: config.enableImportOutput = False elif option in ['--context-format']: config.setContextFormat(argument) Context.format = config.contextFormat elif option in ['--success-code']: config.successCode = int(argument) elif option in ['--failure-code']: config.failureCode = int(argument) elif option in ['--unknown-code']: config.unknownCode = int(argument) elif option in ['--null-hook']: try: import emlib hooks.append(emlib.Hook()) except ImportError: raise InvocationError("missing emlib module; --null-hook not available") elif option in ['--requirements']: try: import emlib det = emlib.Details() if not det.checkRequirements(argument): sys.exit(config.skipCode) except ImportError: raise InvocationError("missing emlib module; cannot check requirements") else: assert False, "unhandled option: %s" % option # Show the details and exit if desired. if level > 0: details(level, config) return config.successCode # Load any configuration files. for configStatement in configStatements: config.run(configStatement) for configPath in configPaths: config.path(configPath) # Show the help if desired. if topics: try: import emhelp usage = emhelp.Usage(config) usage.hello() usage.show(topics) except ImportError: raise InvocationError("missing emhelp subsystem module; no help available") return config.successCode # Set up the main script filename and the arguments. if not argv: argv.append(None) else: inputFilename = argv[0] # Do sanity checks on the configuration. config.check(inputFilename, outputFilename) # Now initialize the output file. if nullFile: output = NullFile() filespec = None elif outputFilename is not None: if output is not None: raise InvocationError("cannot specify more than one output") filespec = outputFilename, outputMode, config.buffering output = config.open(*filespec) else: # So this is stdout. Check the encoding. if not config.isDefaultEncodingErrors(asInput=False): config.reconfigure(sys.stdout, config.buffering, config.outputEncoding, config.outputErrors) filespec = None # Run any pre-initializers. for initializer in preinitializers: file = config.open(initializer, 'r') try: data = file.read() execFunc(data, globals, locals()) finally: file.close() # Get ready! kwargs['argv'] = argv kwargs['config'] = config kwargs['filespec'] = filespec kwargs['globals'] = globals kwargs['hooks'] = hooks kwargs['immediately'] = immediately kwargs['output'] = output try: # Create the interpreter. interp = Interpreter(**kwargs) # Check it. interp.check() # Run it. interp.go( inputFilename, inputMode, preprocessing, postprocessing) exitCode = interp.getExitCode() finally: # Finally, handle any cleanup. if interp is not None: interp.shutdown() # Run any post-initializers. for initializer in postinitializers: try: file = config.open(initializer, 'r') data = file.read() execFunc(data, globals, locals()) finally: file.close() except SystemExit: type, error, traceback = sys.exc_info() if len(error.args) > 0: exitCode = error.args[0] # okay even if a string else: exitCode = config.successCode except KeyboardInterrupt: if config.rawErrors: raise type, error, traceback = sys.exc_info() sys.stderr.write(config.formatError(error, "ERROR: ", "\n")) exitCode = config.failureCode except errors: if config.rawErrors: raise type, error, traceback = sys.exc_info() if not interp: sys.stderr.write(config.formatError(error, "ERROR: ", "\n")) exitCode = config.unknownCode except: if config.rawErrors: raise type, error, traceback = sys.exc_info() if not interp: sys.stderr.write(config.formatError(error, "ERROR: ", "\n")) exitCode = config.errorToExitCode(error) # Old versions of Python 3.x don't flush sys.__stdout__ when redirecting # stdout for some reason. if sys.__stdout__ is not None: sys.__stdout__.flush() return exitCode # # main # def main(): exitCode = invoke(sys.argv[1:], executable=sys.argv[0], errors=None, origin=True) sys.exit(exitCode) if __name__ == '__main__': main() empy-4.2.1/empy.egg-info/0000755000175000017500000000000015142227214015056 5ustar jriverojriveroempy-4.2.1/empy.egg-info/top_level.txt0000644000175000017500000000002615142227213017605 0ustar jriverojriveroem emdoc emhelp emlib empy-4.2.1/empy.egg-info/dependency_links.txt0000644000175000017500000000000115142227213021123 0ustar jriverojrivero empy-4.2.1/empy.egg-info/PKG-INFO0000644000175000017500000000402015142227213016146 0ustar jriverojriveroMetadata-Version: 2.1 Name: empy Version: 4.2.1 Summary: A templating system for Python. Home-page: http://www.alcyone.com/software/empy/ Author: Erik Max Francis Author-email: software@alcyone.com License: BSD Platform: any Classifier: Development Status :: 6 - Mature Classifier: Environment :: Console Classifier: Intended Audience :: Developers Classifier: Intended Audience :: Other Audience Classifier: License :: OSI Approved :: BSD License Classifier: Operating System :: OS Independent Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Programming Language :: Python :: Implementation :: IronPython Classifier: Programming Language :: Python :: Implementation :: Jython Classifier: Programming Language :: Python :: Implementation :: PyPy Classifier: Programming Language :: Python :: Implementation :: Stackless Classifier: Topic :: Software Development :: Interpreters Classifier: Topic :: Software Development :: Libraries :: Python Modules Classifier: Topic :: Software Development :: Pre-processors Classifier: Topic :: Text Editors :: Text Processing Classifier: Topic :: Text Processing :: Filters Classifier: Topic :: Text Processing :: General Classifier: Topic :: Text Processing :: Markup Classifier: Topic :: Utilities Requires-Python: >=2.4 License-File: LICENSE.md License-File: LICENSE.md.pre EmPy is a powerful, robust and mature templating system for inserting Python code in template text. EmPy takes a source document, processes it, and produces output. This is accomplished via expansions, which are signals to the EmPy system where to act and are indicated with markup. Markup is set off by a customizable prefix (by default the at sign, `@`). EmPy can expand arbitrary Python expressions, statements and control structures in this way, as well as a variety of additional special forms. The remaining textual data is sent to the output, allowing Python to be used in effect as a markup language. empy-4.2.1/empy.egg-info/SOURCES.txt0000644000175000017500000000027615142227213016746 0ustar jriverojriveroLICENSE.md LICENSE.md.pre README.md em.py emdoc.py emhelp.py emlib.py setup.py empy.egg-info/PKG-INFO empy.egg-info/SOURCES.txt empy.egg-info/dependency_links.txt empy.egg-info/top_level.txt