1r"""Utilities to compile possibly incomplete Python source code.
2
3This module provides two interfaces, broadly similar to the builtin
4function compile(), that take progam text, a filename and a 'mode'
5and:
6
7- Return a code object if the command is complete and valid
8- Return None if the command is incomplete
9- Raise SyntaxError, ValueError or OverflowError if the command is a
10  syntax error (OverflowError and ValueError can be produced by
11  malformed literals).
12
13Approach:
14
15First, check if the source consists entirely of blank lines and
16comments; if so, replace it with 'pass', because the built-in
17parser doesn't always do the right thing for these.
18
19Compile three times: as is, with \n, and with \n\n appended.  If it
20compiles as is, it's complete.  If it compiles with one \n appended,
21we expect more.  If it doesn't compile either way, we compare the
22error we get when compiling with \n or \n\n appended.  If the errors
23are the same, the code is broken.  But if the errors are different, we
24expect more.  Not intuitive; not even guaranteed to hold in future
25releases; but this matches the compiler's behavior from Python 1.4
26through 2.2, at least.
27
28Caveat:
29
30It is possible (but not likely) that the parser stops parsing with a
31successful outcome before reaching the end of the source; in this
32case, trailing symbols may be ignored instead of causing an error.
33For example, a backslash followed by two newlines may be followed by
34arbitrary garbage.  This will be fixed once the API for the parser is
35better.
36
37The two interfaces are:
38
39compile_command(source, filename, symbol):
40
41    Compiles a single command in the manner described above.
42
43CommandCompiler():
44
45    Instances of this class have __call__ methods identical in
46    signature to compile_command; the difference is that if the
47    instance compiles program text containing a __future__ statement,
48    the instance 'remembers' and compiles all subsequent program texts
49    with the statement in force.
50
51The module also provides another class:
52
53Compile():
54
55    Instances of this class act like the built-in function compile,
56    but with 'memory' in the sense described above.
57"""
58
59# import internals, not guaranteed interface
60from org.python.core import Py,CompilerFlags,CompileMode
61from org.python.core.CompilerFlags import PyCF_DONT_IMPLY_DEDENT
62
63# public interface
64
65__all__ = ["compile_command", "Compile", "CommandCompiler"]
66
67def compile_command(source, filename="<input>", symbol="single"):
68    r"""Compile a command and determine whether it is incomplete.
69
70    Arguments:
71
72    source -- the source string; may contain \n characters
73    filename -- optional filename from which source was read; default
74                "<input>"
75    symbol -- optional grammar start symbol; "single" (default) or "eval"
76
77    Return value / exceptions raised:
78
79    - Return a code object if the command is complete and valid
80    - Return None if the command is incomplete
81    - Raise SyntaxError, ValueError or OverflowError if the command is a
82      syntax error (OverflowError and ValueError can be produced by
83      malformed literals).
84    """
85    if symbol not in ['single','eval']:
86        raise ValueError,"symbol arg must be either single or eval"
87    symbol = CompileMode.getMode(symbol)
88    return Py.compile_command_flags(source,filename,symbol,Py.getCompilerFlags(),0)
89
90class Compile:
91    """Instances of this class behave much like the built-in compile
92    function, but if one is used to compile text containing a future
93    statement, it "remembers" and compiles all subsequent program texts
94    with the statement in force."""
95    def __init__(self):
96        self._cflags = CompilerFlags()
97
98    def __call__(self, source, filename, symbol):
99        symbol = CompileMode.getMode(symbol)
100        return Py.compile_flags(source, filename, symbol, self._cflags)
101
102class CommandCompiler:
103    """Instances of this class have __call__ methods identical in
104    signature to compile_command; the difference is that if the
105    instance compiles program text containing a __future__ statement,
106    the instance 'remembers' and compiles all subsequent program texts
107    with the statement in force."""
108
109    def __init__(self,):
110        self._cflags = CompilerFlags()
111
112    def __call__(self, source, filename="<input>", symbol="single"):
113        r"""Compile a command and determine whether it is incomplete.
114
115        Arguments:
116
117        source -- the source string; may contain \n characters
118        filename -- optional filename from which source was read;
119                    default "<input>"
120        symbol -- optional grammar start symbol; "single" (default) or
121                  "eval"
122
123        Return value / exceptions raised:
124
125        - Return a code object if the command is complete and valid
126        - Return None if the command is incomplete
127        - Raise SyntaxError, ValueError or OverflowError if the command is a
128          syntax error (OverflowError and ValueError can be produced by
129          malformed literals).
130        """
131        if symbol not in ['single','eval']:
132            raise ValueError,"symbol arg must be either single or eval"
133        symbol = CompileMode.getMode(symbol)
134        return Py.compile_command_flags(source,filename,symbol,self._cflags,0)
135