Ticket #3485: trac3485-sage_input-v2.patch

File trac3485-sage_input-v2.patch, 105.6 KB (added by Carl Witty, 14 years ago)
  • sage/misc/all.py

    # HG changeset patch
    # User Carl Witty <cwitty@newtonlabs.com>
    # Date 1214502253 25200
    # Node ID fe6b1dd63297d817c70d8de2dc579ae1f76dfac6
    # Parent  f8b52491b39354c78a2c377fbeebeb395065badf
    new sage_input framework
    
    diff -r f8b52491b393 -r fe6b1dd63297 sage/misc/all.py
    a b  
    6363from interpreter import preparser
    6464
    6565from sage_eval import sage_eval, sageobj
     66
     67from sage_input import sage_input
    6668
    6769from cython import cython_lambda
    6870from cython_c import cython
  • new file sage/misc/sage_input.py

    diff -r f8b52491b393 -r fe6b1dd63297 sage/misc/sage_input.py
    - +  
     1r"""
     2Sage Input Formatting
     3
     4AUTHORS:
     5    -- Carl Witty (2008-04): new file
     6
     7This module provides a function \function{sage_input}.  This function
     8takes an arbitrary \sage value and produces a sequence of commands
     9that, if typed at the \code{sage:} prompt, will recreate the value.
     10(If this is not implemented for a particular value, then an exception
     11is raised instead.)  This might be useful in understanding a part of
     12Sage, or for debugging.  (For instance, if you have a value produced
     13in a complicated way in the middle of a debugging session, you could
     14use \function{sage_input} to find a simple way to produce the same
     15value.)  We attempt to produce commands that are readable and
     16idiomatic.
     17
     18sage: sage_input(3)
     193
     20sage: sage_input((polygen(RR) + RR(pi))^2, verify=True)
     21# Verified
     22R.<x> = RR[]
     23x^2 + 6.2831853071795862*x + 9.8696044010893580
     24
     25With \code{verify=True}, \function{sage_input} also verifies the
     26results, by calling sage_eval on the result and verifying that it is
     27equal to the input.
     28
     29sage: sage_input(GF(2)(1), verify=True)
     30# Verified
     31GF(2)(1)
     32
     33We can generate code that works without the preparser, with
     34\code{preparse=False}; or we can generate code that will work whether
     35or not the preparser is enabled, with \code{preparse=None}.
     36Generating code with \code{preparse=False} may be useful to see how to
     37create a certain value in a Python or Cython source file.
     38
     39sage: sage_input(5, verify=True)
     40# Verified
     415
     42sage: sage_input(5, preparse=False)
     43ZZ(5)
     44sage: sage_input(5, preparse=None)
     45ZZ(5)
     46sage: sage_input(5r, verify=True)
     47# Verified
     485r
     49sage: sage_input(5r, preparse=False)
     505
     51sage: sage_input(5r, preparse=None)
     52int(5)
     53
     54Adding \function{sage_input} support to your own classes is
     55straightforward.  You need to add a \method{_sage_input_} method which
     56returns a \class{SageInputExpression} (henceforth abbreviated as SIE)
     57which will reconstruct this instance of your class.
     58
     59A \method{_sage_input_} method takes two parameters, conventionally
     60named \var{sib} and \var{coerced}.  The first argument is a
     61\class{SageInputBuilder}; it has methods to build SIEs.  The second
     62argument, \var{coerced}, is a boolean.  This is only useful if your
     63class is a subclass of \class{Element} (although it is always
     64present).  If \var{coerced} is \code{False}, then your method must
     65generate an expression which will evaluate to a value of the correct
     66type with the correct parent.  If \var{coerced} is \code{True}, then
     67your method may generate an expression of a type that has a canonical
     68coercion to your type.
     69
     70Let's work through some examples.  We'll build a sequence of functions
     71that would be acceptable as \method{_sage_input_} methods for the
     72\class{Rational} class.
     73
     74Here's the first and simplest version.
     75
     76sage: def qq_sage_input_v1(self, sib, coerced):
     77...       return sib(self.numerator())/sib(self.denominator())
     78
     79We see that given a \class{SageInputBuilder} \var{sib}, you can
     80construct a SIE for a value \var{v} simply with \code{sib(v)}, and you
     81can construct a SIE for a quotient with the division operator.  Of course,
     82the other operators also work, and so do function calls, method calls,
     83subscripts, etc.
     84
     85We'll test with the following code, which you don't need to understand.
     86(It produces a list of 8 results, showing the formatted versions of
     87-5/7 and 3, with the preparser either enabled or disabled and either
     88with or without an automatic coercion to QQ.)
     89
     90sage: from sage.misc.sage_input import SageInputBuilder
     91sage: def test_qq_formatter(fmt):
     92...       results = []
     93...       for v in [-5/7, QQ(3)]:
     94...           for pp in [False, True]:
     95...               for coerced in [False, True]:
     96...                   sib = SageInputBuilder(preparse=pp)
     97...                   results.append(sib.result(fmt(v, sib, coerced)))
     98...       return results
     99
     100sage: test_qq_formatter(qq_sage_input_v1)
     101[-ZZ(5)/ZZ(7), -ZZ(5)/ZZ(7), -5/7, -5/7, ZZ(3)/ZZ(1), ZZ(3)/ZZ(1), 3/1, 3/1]
     102
     103Let's try for some shorter, perhaps nicer-looking output.  We'll start
     104by getting rid of the \code{ZZ} in the denominators; even without the
     105preparser, \code{-ZZ(5)/7 == -ZZ(5)/ZZ(7)}.
     106
     107sage: def qq_sage_input_v2(self, sib, coerced):
     108...       return sib(self.numerator())/sib.int(self.denominator())
     109
     110The \method{int} method on \class{SageInputBuilder} returns a SIE for
     111an integer that is always represented in the simple way, without
     112coercions.  (So, depending on the preparser mode, it might read in as an
     113\class{Integer}, an \class{int}, or a \class{long}.)
     114
     115sage: test_qq_formatter(qq_sage_input_v2)
     116[-ZZ(5)/7, -ZZ(5)/7, -5/7, -5/7, ZZ(3)/1, ZZ(3)/1, 3/1, 3/1]
     117
     118Next let's get rid of the divisions by 1.  These are more complicated,
     119since if we're not careful we'll get results in \ZZ instead of \QQ.
     120
     121sage: def qq_sage_input_v3(self, sib, coerced):
     122...       if self.denominator() == 1:
     123...           if coerced:
     124...               return sib.int(self.numerator())
     125...           else:
     126...               return sib.name('QQ')(sib.int(self.numerator()))
     127...       return sib(self.numerator())/sib.int(self.denominator())
     128
     129We see that the \method{name} method gives an SIE representing a \sage
     130constant or function.
     131
     132sage: test_qq_formatter(qq_sage_input_v3)
     133[-ZZ(5)/7, -ZZ(5)/7, -5/7, -5/7, QQ(3), 3, QQ(3), 3]
     134
     135This is the prettiest output we're going to get, but let's make one
     136further refinement.  Other \class{_sage_input_} methods, like the one
     137for polynomials, analyze the structure of SIEs; they work better (give
     138prettier output) if negations are at the outside.
     139
     140sage: def qq_sage_input_v4(self, sib, coerced):
     141...       num = self.numerator()
     142...       neg = (num < 0)
     143...       if neg: num = -num
     144...       if self.denominator() == 1:
     145...           if coerced:
     146...               v = sib.int(num)
     147...           else:
     148...               v = sib.name('QQ')(sib.int(num))
     149...       else:
     150...           v = sib(num)/sib.int(self.denominator())
     151...       if neg: v = -v
     152...       return v
     153
     154sage: test_qq_formatter(qq_sage_input_v4)
     155[-ZZ(5)/7, -ZZ(5)/7, -5/7, -5/7, QQ(3), 3, QQ(3), 3]
     156
     157"""
     158
     159from sage.misc.functional import parent
     160
     161##########################################################################
     162#
     163#       Copyright (C) 2008 Carl Witty <Carl.Witty@gmail.com>
     164#
     165#  Distributed under the terms of the GNU General Public License (GPL)
     166#
     167#                  http://www.gnu.org/licenses/
     168#
     169##########################################################################
     170
     171def sage_input(x, preparse=True, verify=False, allow_locals=False):
     172    r"""
     173    INPUTS:
     174        x -- the value we want to find an ``input form'' for
     175        preparse -- (default \code{True}) Whether to generate code
     176            that requires the preparser.  With \code{True}, generated
     177            code requires the preparser.  With \code{False}, generated
     178            code requires that the preparser not be used.  With \code{None},
     179            generated code will work whether or not the preparser is used.
     180        verify -- (default \code{False}) If \code{True}, then the
     181            answer will be evaluated with \function{sage_eval}, and
     182            an exception will be raised if the result is not equal to
     183            the original value.  (In fact, for \code{verify=True},
     184            \function{sage_input} is effectively run three times,
     185            with \var{preparse} set to \code{True}, \code{False}, and
     186            \code{None}, and all three results are checked.)  This is
     187            particularly useful for doctests.
     188        allow_locals -- (default \code{False}) If \code{True}, then
     189            values that \function{sage_input} cannot handle are returned
     190            in a dictionary, and the returned code assumes that this
     191            dictionary is passed as the \var{locals} parameter of
     192            \function{sage_eval}.  (Otherwise, if \function{sage_input}
     193            cannot handle a value, an exception is raised.)
     194
     195    EXAMPLES:
     196        sage: sage_input(GF(2)(1))
     197        GF(2)(1)
     198        sage: sage_input((GF(2)(0), GF(2)(1)), verify=True)
     199        # Verified
     200        GF_2 = GF(2)
     201        (GF_2(0), GF_2(1))
     202
     203    When the preparser is enabled, we use the \sage generator syntax.
     204
     205        sage: K.<x> = GF(5)[]
     206        sage: sage_input(x^3 + 2*x, verify=True)
     207        # Verified
     208        R.<x> = GF(5)[]
     209        x^3 + 2*x
     210        sage: sage_input(x^3 + 2*x, preparse=False)
     211        R = GF(5)['x']
     212        x = R.gen()
     213        x**3 + 2*x
     214
     215    The result of \function{sage_input} is actually a pair of strings with
     216    a special \method{__repr__} method to print nicely.
     217
     218        sage: r = sage_input(RealField(20)(pi), verify=True)
     219        sage: r
     220        # Verified
     221        RealField(20)(3.1415939)
     222        sage: isinstance(r, tuple)
     223        True
     224        sage: len(r)
     225        2
     226        sage: tuple(r)
     227        ('# Verified\n', 'RealField(20)(3.1415939)')
     228
     229    We cannot find an input form for a function.
     230
     231        sage: sage_input((3, lambda x: x))
     232        Traceback (most recent call last):
     233        ...
     234        ValueError: Can't convert <function <lambda> at 0x...> to sage_input form
     235
     236    But we can have \function{sage_input} continue anyway, and return
     237    an input form for the rest of the expression, with
     238    \code{allow_locals=True}.
     239
     240        sage: r = sage_input((3, lambda x: x), verify=True, allow_locals=True)
     241        sage: r
     242        LOCALS:
     243            _sil1: <function <lambda> at 0x...>
     244        # Verified
     245        (3, _sil1)
     246        sage: tuple(r)
     247        ('# Verified\n', '(3, _sil1)', {'_sil1': <function <lambda> at 0x...>})
     248    """
     249    if not verify:
     250        sib = SageInputBuilder(allow_locals=allow_locals, preparse=preparse)
     251        return sib.result(sib(x))
     252
     253    # In verify mode, we actually compute and verify the answer with
     254    # all three settings of preparse.
     255
     256    for pp in (True, False, None):
     257        sib = SageInputBuilder(allow_locals=allow_locals, preparse=pp)
     258        ans = sib.result(sib(x))
     259        verify_si_answer(x, ans, pp)
     260        if pp == preparse:
     261            ans_l = list(ans)
     262            ans_l[0] = '# Verified\n' + ans_l[0]
     263            final_answer = SageInputAnswer(*ans_l)
     264
     265    return final_answer
     266
     267class SageInputBuilder:
     268    r"""
     269    An instance of this class is passed to \method{_sage_input_} methods.
     270    It keeps track of the current state of the \method{_sage_input_} process,
     271    and contains many utility methods for building \class{SageInputExpression}
     272    objects.
     273
     274    In normal use, instances of \class{SageInputBuilder} are created
     275    internally by \function{sage_input}, but it may be useful to create
     276    an instance directly for testing or doctesting.
     277
     278    EXAMPLES:
     279        sage: from sage.misc.sage_input import SageInputBuilder
     280       
     281    We can create a \class{SageInputBuilder}, use it to create some
     282    \class{SageInputExpression}s, and get a result.  (As mentioned
     283    above, this is only useful for testing or doctesting; normally
     284    you would just use \function{sage_input}.)
     285
     286        sage: sib = SageInputBuilder()
     287        sage: sib.result((sib(3) + sib(4)) * (sib(5) + sib(6)))
     288        (3 + 4)*(5 + 6)
     289    """
     290
     291    def __init__(self, allow_locals=False, preparse=True):
     292        r"""
     293        Initialize an instance of \class{SageInputBuilder}.
     294
     295        In normal use, instances of \class{SageInputBuilder} are created
     296        internally by \function{sage_input}, but it may be useful to create
     297        an instance directly for testing or doctesting.
     298
     299        INPUTS:
     300            allow_locals -- (default \code{False}) If true, then values
     301                that cannot be converted to input form will be stored in
     302                a dictionary, which must be passed as the \var{locals}
     303                when evaluating the result.
     304            preparse -- (default \code{True}) If true, then the result
     305                will assume that the preparser is enabled.  If false, then
     306                the result will assume that the preparser is disabled.
     307                If \code{None}, then the result will work whether or
     308                not the preparser is enabled.
     309
     310        EXAMPLES:
     311            sage: from sage.misc.sage_input import SageInputBuilder
     312            sage: SageInputBuilder().preparse()
     313            True
     314            sage: SageInputBuilder(preparse=False).preparse()
     315            False
     316        """
     317        self._allow_locals = allow_locals
     318        self._preparse = preparse
     319        self._cached_types = set()
     320        self._cache = {}
     321        self._parent_gens = {}
     322        self._next_local = 1
     323        self._locals = {}
     324
     325    def __call__(self, x, coerced=False):
     326        r"""
     327        Tries to convert an arbitrary value \var{x} into a
     328        \class{SageInputExpression} (an SIE).
     329
     330        We first check to see if an SIE has been cached for \var{x};
     331        if so, we return it.  If \var{x} is already an SIE, we return
     332        it unchanged.
     333
     334        If \var{x} has a \method{_sage_input_} method, we call that
     335        method.
     336
     337        Otherwise, if \var{x} is a value of some Python type that
     338        we know how to deal with, we convert it directly.
     339
     340        Finally, for values we don't know how to convert, if
     341        \code{self._allow_locals} is true, we add it to a
     342        ``locals'' dictionary.
     343
     344        EXAMPLES:
     345            sage: from sage.misc.sage_input import SageInputBuilder
     346
     347            sage: sib = SageInputBuilder()
     348            sage: sib.result(sib(sib(3)))
     349            3
     350
     351            sage: sib = SageInputBuilder()
     352            sage: sib.result(sib(GF(17)(5)))
     353            GF(17)(5)
     354
     355        The argument \code{coerced=True} will get passed to the
     356        \method{_sage_input_} method of the argument.
     357            sage: sib = SageInputBuilder()
     358            sage: sib.result(sib(GF(17)(5), True))
     359            5
     360
     361        Since \function{sage_input} directly calls this method, all
     362        of the following are indirect doctests.
     363            sage: sage_input(True)
     364            True
     365            sage: sage_input(-5r, verify=True)
     366            # Verified
     367            -5r
     368            sage: sage_input(7r, preparse=False, verify=True)
     369            # Verified
     370            7
     371            sage: sage_input(-11r, preparse=None, verify=True)
     372            # Verified
     373            -int(11)
     374            sage: sage_input(long(-5), verify=True)
     375            # Verified
     376            -long(5)
     377            sage: sage_input(long(-7), preparse=False, verify=True)
     378            # Verified
     379            -7L
     380            sage: sage_input(long(11), preparse=None, verify=True)
     381            # Verified
     382            long(11)
     383            sage: sage_input(long(2^70), verify=True)
     384            # Verified
     385            1180591620717411303424r
     386            sage: sage_input(-long(2^80), preparse=False, verify=True)
     387            # Verified
     388            -1208925819614629174706176
     389            sage: sage_input(long(2^75), preparse=None, verify=True)
     390            # Verified
     391            long(37778931862957161709568)
     392            sage: sage_input("Hello, world\n", verify=True)
     393            # Verified
     394            'Hello, world\n'
     395            sage: sage_input("'", verify=True)
     396            # Verified
     397            "'"
     398            sage: sage_input('"', verify=True)
     399            # Verified
     400            '"'
     401            sage: sage_input(''' "'Hi,' she said." ''', verify=True)
     402            # Verified
     403            ' "\'Hi,\' she said." '
     404            sage: sage_input('Icky chars: \0\n\t\b\'\"\200\300\234', verify=True)
     405            # Verified
     406            'Icky chars: \x00\n\t\x08\'"\x80\xc0\x9c'
     407            sage: sage_input((2, 3.5, 'Hi'), verify=True)
     408            # Verified
     409            (2, RR(3.5000000000000000), 'Hi')
     410            sage: sage_input(lambda x: x)
     411            Traceback (most recent call last):
     412            ...
     413            ValueError: Can't convert <function <lambda> at 0x...> to sage_input form
     414            sage: sage_input(lambda x: x, allow_locals=True, verify=True)
     415            LOCALS:
     416              _sil1: <function <lambda> at 0x...>
     417            # Verified
     418            _sil1
     419        """
     420        # We want to look up x in our cache, to see if we've seen it before.
     421        # However, we don't want to assume that hashing x is always
     422        # efficient, so we only try the lookup if some value of the same
     423        # type as x has been cached.
     424        if type(x) in self._cached_types:
     425            v = self._cache.get((parent(x), x))
     426            if v is not None: return v
     427
     428        if isinstance(x, SageInputExpression):
     429            return x
     430
     431        if hasattr(x, '_sage_input_'):
     432            return x._sage_input_(self, coerced)
     433
     434        if isinstance(x, bool):
     435            return SIE_literal_stringrep(self, str(x))
     436
     437        if isinstance(x, int) or \
     438                (isinstance(x, long) and isinstance(int(x), long)):
     439            # For longs that don't fit in an int, we just use the int
     440            # code; it will get extended to long automatically.           
     441            if self._preparse == True:
     442                if x < 0:
     443                    return -SIE_literal_stringrep(self, str(-x) + 'r')
     444                else:
     445                    return SIE_literal_stringrep(self, str(x) + 'r')
     446            elif self._preparse == False:
     447                return self.int(x)
     448            else:
     449                tyname = 'int' if isinstance(x, int) else 'long'
     450                if x < 0:
     451                    return -self.name(tyname)(self.int(-x))
     452                else:
     453                    return self.name(tyname)(self.int(x))
     454
     455        if isinstance(x, long):
     456            # This must be a long that does fit in an int, so we need either
     457            # long(x) or an 'L' suffix.
     458            # With the current preparser, 1Lr does not work.
     459            # 1rL does work; but that's just ugly, so I don't use it.
     460            if self._preparse == False:
     461                if x < 0:
     462                    return -SIE_literal_stringrep(self, str(-x) + 'L')
     463                else:
     464                    return SIE_literal_stringrep(self, str(x) + 'L')
     465            else:
     466                if x < 0:
     467                    return -self.name('long')(self.int(-x))
     468                else:
     469                    return self.name('long')(self.int(x))           
     470
     471        if isinstance(x, str):
     472            return SIE_literal_stringrep(self, repr(x))
     473
     474        if isinstance(x, tuple):
     475            return SIE_tuple(self, map(self, x))
     476
     477        if self._allow_locals:
     478            loc = self._next_local
     479            self._next_local += 1
     480            loc_name = '_sil%d' % loc
     481            self._locals[loc_name] = x
     482            return SIE_literal_stringrep(self, loc_name)
     483        else:
     484            raise ValueError, "Can't convert %r to sage_input form"%x
     485
     486    def preparse(self):
     487        r"""
     488        Checks the preparse status of this \class{SageInputBuilder}.
     489        (\code{True} if the preparser will be enabled, \code{False}
     490        if it will be disabled, and \code{None} if the result must
     491        work whether or not the preparser is enabled.)
     492
     493        For example, this is useful in the \method{_sage_input_}
     494        methods of \class{Integer} and \class{RealNumber}; but most
     495        \method{_sage_input_} methods will not need to examine this.
     496
     497        EXAMPLES:
     498            sage: from sage.misc.sage_input import SageInputBuilder
     499            sage: SageInputBuilder().preparse()
     500            True
     501            sage: SageInputBuilder(preparse=False).preparse()
     502            False
     503        """
     504        return self._preparse
     505
     506    def int(self, n):
     507        r"""
     508        Given an integer (an \class{Integer}, an \class{int}, or a
     509        \class{long}), produce a \class{SageInputExpression} that displays
     510        the integer with no marking for what kind of integer it is
     511        (so it may read back as an \class{Integer}, an \class{int}, or
     512        a \class{long}, depending on its size and whether the preparser
     513        is enabled).
     514
     515        EXAMPLES:
     516            sage: from sage.misc.sage_input import SageInputBuilder
     517
     518            sage: sib = SageInputBuilder()
     519            sage: sib.result(sib.int(-3^50))
     520            -717897987691852588770249
     521           
     522            sage: sib = SageInputBuilder()
     523            sage: sib.result(sib.int(long(2^65)))
     524            36893488147419103232
     525
     526            sage: sib = SageInputBuilder()
     527            sage: sib.result(sib.int(-42r))
     528            -42
     529        """
     530        if n < 0:
     531            return -SIE_literal_stringrep(self, -n)
     532        else:
     533            return SIE_literal_stringrep(self, n)
     534
     535    def float_str(self, n):
     536        r"""
     537        Given a string representing a floating-point number,
     538        produces a \class{SageInputExpression} that formats as that
     539        string.
     540
     541        EXAMPLES:
     542            sage: from sage.misc.sage_input import SageInputBuilder
     543
     544            sage: sib = SageInputBuilder()
     545            sage: sib.result(sib.float_str(repr(RR(e))))
     546            2.71828182845905
     547        """
     548        return SIE_literal_stringrep(self, n)
     549
     550    def name(self, n):
     551        r"""
     552        Given a string representing a Python name,
     553        produces a \class{SageInputExpression} for that name.
     554
     555        EXAMPLES:
     556            sage: from sage.misc.sage_input import SageInputBuilder
     557
     558            sage: sib = SageInputBuilder()
     559            sage: sib.result(sib.name('pi') + sib.name('e'))
     560            pi + e
     561        """
     562        return SIE_literal_stringrep(self, n)
     563
     564    def cache(self, x, sie, name):
     565        r"""
     566        INPUTS:
     567            x -- an arbitrary value
     568            sie -- a \class{SageInputExpression}
     569            name -- a requested variable name
     570
     571        Enters \var{x} and \var{sie} in a cache, so that subsequent calls
     572        \code{self(x)} will directly return \var{sie}.  Also, marks the
     573        requested name of this \var{sie} to be \var{name}.
     574
     575        This should almost always be called as part of the
     576        \method{_sage_input_} method of a parent.  It may also be called
     577        on values of an arbitrary type, which may be useful if the values
     578        are both large and likely to be used multiple times in a single
     579        expression.
     580
     581        EXAMPLES:
     582            sage: from sage.misc.sage_input import SageInputBuilder
     583
     584            sage: sib = SageInputBuilder()
     585            sage: sie42 = sib(GF(101)(42))
     586            sage: sib.cache(GF(101)(42), sie42, 'the_ultimate_answer')
     587            sage: sib.result(sib(GF(101)(42)) + sib(GF(101)(42)))
     588            the_ultimate_answer = GF(101)(42)
     589            the_ultimate_answer + the_ultimate_answer
     590
     591        Note that we don't assign the result to a variable if the value
     592        is only used once.
     593            sage: sib = SageInputBuilder()
     594            sage: sie42 = sib(GF(101)(42))
     595            sage: sib.cache(GF(101)(42), sie42, 'the_ultimate_answer')
     596            sage: sib.result(sib(GF(101)(42)) + sib(GF(101)(43)))
     597            GF_101 = GF(101)
     598            GF_101(42) + GF_101(43)
     599        """
     600        self._cached_types.add(type(x))
     601        self._cache[(parent(x), x)] = sie
     602        sie._sie_preferred_varname = name
     603
     604    def empty_subscript(self, parent):
     605        r"""
     606        Given a \class{SageInputExpression} representing \code{foo},
     607        produces a \class{SageInputExpression} representing \code{foo[]}.
     608        Since this is not legal Python syntax, it is useful only for
     609        producing the \sage generator syntax for a polynomial ring.
     610
     611        EXAMPLES:
     612            sage: from sage.misc.sage_input import SageInputBuilder
     613
     614            sage: sib = SageInputBuilder()
     615            sage: sib.result(sib.empty_subscript(sib(2) + sib(3)))
     616            (2 + 3)[]
     617
     618        The following calls this method indirectly.
     619            sage: sage_input(polygen(ZZ['y']))
     620            R.<x> = ZZ['y'][]
     621            x
     622        """
     623        return SIE_subscript(self, parent, None)
     624
     625    def parent_with_gens(self, parent, sie, gen_names, name, gens_syntax=None):
     626        r"""
     627        This method is used for parents with generators, to manage the
     628        \sage preparser generator syntax (like \code{K.<x> = QQ[]}).
     629
     630        The \method{_sage_input_} method of a parent class with
     631        generators should construct a \class{SageInputExpression} for
     632        the parent, and then call this method with the parent itself,
     633        the constructed SIE, a sequence containing the names of the
     634        generators, and (optionally) another SIE to use if the \sage
     635        generator syntax is used; typically this will be the same as
     636        the first SIE except omitting a \var{names} parameter.
     637
     638        EXAMPLES:
     639            sage: from sage.misc.sage_input import SageInputBuilder
     640
     641
     642            sage: def test_setup(use_gens=True, preparse=True):
     643            ...       sib = SageInputBuilder(preparse=preparse)
     644            ...       gen_names=('foo', 'bar')
     645            ...       parent = "some parent"
     646            ...       normal_sie = sib.name('make_a_parent')(names=gen_names)
     647            ...       if use_gens:
     648            ...           gens_sie = sib.name('make_a_parent')()
     649            ...       else:
     650            ...           gens_sie = None
     651            ...       name = 'the_thing'
     652            ...       result = sib.parent_with_gens(parent, normal_sie,
     653            ...                                     gen_names, name,
     654            ...                                     gens_syntax=gens_sie)
     655            ...       return sib, result
     656
     657            sage: sib, par_sie = test_setup()
     658            sage: sib.result(par_sie)
     659            make_a_parent(names=('foo', 'bar'))
     660
     661            sage: sib, par_sie = test_setup()
     662            sage: sib.result(sib(3) * sib.gen("some parent", 0))
     663            the_thing.<foo,bar> = make_a_parent()
     664            3*foo
     665
     666            sage: sib, par_sie = test_setup(preparse=False)
     667            sage: sib.result(par_sie)
     668            make_a_parent(names=('foo', 'bar'))
     669
     670            sage: sib, par_sie = test_setup(preparse=False)
     671            sage: sib.result(sib(3) * sib.gen("some parent", 0))
     672            the_thing = make_a_parent(names=('foo', 'bar'))
     673            foo,bar = the_thing.gens()
     674            ZZ(3)*foo
     675
     676            sage: sib, par_sie = test_setup(use_gens=False)
     677            sage: sib.result(par_sie)
     678            make_a_parent(names=('foo', 'bar'))
     679
     680            sage: sib, par_sie = test_setup(use_gens=False)
     681            sage: sib.result(sib(3) * sib.gen("some parent", 0))
     682            the_thing = make_a_parent(names=('foo', 'bar'))
     683            foo,bar = the_thing.gens()
     684            3*foo
     685
     686            sage: sib, par_sie = test_setup()
     687            sage: sib.result(par_sie - sib.gen("some parent", 1))
     688            the_thing.<foo,bar> = make_a_parent()
     689            the_thing - bar           
     690        """
     691        v = SIE_gens_constructor(self, sie, gen_names, gens_syntax=gens_syntax)
     692        self.cache(parent, v, name)
     693        gens = [SIE_gen(self, v, n) for n in gen_names]
     694        self._parent_gens[parent] = gens
     695        v._sie_gens = gens
     696        return v
     697
     698    def gen(self, parent, n=0):
     699        r"""
     700        Given a parent, returns a \class{SageInputExpression} for
     701        the $n$th (default 0) generator of the parent.
     702
     703        EXAMPLES:
     704            sage: from sage.misc.sage_input import SageInputBuilder
     705
     706            sage: sib = SageInputBuilder()
     707            sage: sib.result(sib.gen(ZZ['y']))
     708            R.<y> = ZZ[]
     709            y
     710        """
     711        if not parent in self._parent_gens:
     712            self(parent)
     713            if not parent in self._parent_gens:
     714                raise ValueError, "%s did not register generators for sage_input" % parent
     715
     716        gens = self._parent_gens[parent]
     717
     718        if n > len(gens):
     719            raise ValueError, "%s registered only %d generators for sage_input" % (parent, len(gens))
     720
     721        return gens[n]
     722       
     723    def prod(self, factors, simplify=False):
     724        r"""
     725        Given a sequence, returns a \class{SageInputExpression}
     726        for the product of the elements.
     727
     728        With \code{simplify=True}, performs some simplifications
     729        first.  If any element is formatted as a string \code{'0'},
     730        then that element is returned directly.  If any element is
     731        formatted as a string \code{'1'}, then it is removed
     732        from the sequence (unless it is the only element in the sequence).
     733        And any negations are removed from the elements and moved to the
     734        outside of the product.
     735
     736        EXAMPLES:
     737            sage: from sage.misc.sage_input import SageInputBuilder
     738
     739            sage: sib = SageInputBuilder()
     740            sage: sib.result(sib.prod([-1, 0, 1, -2]))
     741            -1*0*1*-2
     742
     743            sage: sib = SageInputBuilder()
     744            sage: sib.result(sib.prod([-1, 0, 1, 2], simplify=True))
     745            0
     746
     747            sage: sib = SageInputBuilder()
     748            sage: sib.result(sib.prod([-1, 2, -3, -4], simplify=True))
     749            -2*3*4
     750
     751            sage: sib = SageInputBuilder()
     752            sage: sib.result(sib.prod([-1, 1, -1, -1], simplify=True))
     753            -1
     754
     755            sage: sib = SageInputBuilder()
     756            sage: sib.result(sib.prod([1, 1, 1], simplify=True))
     757            1
     758        """
     759        neg = False
     760        factors = [self(factor) for factor in factors]
     761        if simplify:
     762            i = 0
     763            while i < len(factors):
     764                factor = factors[i]
     765                while isinstance(factor, SIE_unary) and factor._sie_op == '-':
     766                    neg = not neg
     767                    factor = factor._sie_operand
     768                    factors[i] = factor
     769                if isinstance(factor, SIE_literal_stringrep) and factor._sie_value == '0':
     770                    factors = [factor]
     771                    neg = False
     772                    break
     773                if isinstance(factor, SIE_literal_stringrep) and factor._sie_value == '1':
     774                    factors[i:i+1] = []
     775                else:
     776                    i += 1
     777            if len(factors) == 0:
     778                factors.append(SIE_literal_stringrep(self, '1'))
     779
     780        prod = factors[0]
     781        for factor in factors[1:]:
     782            prod = prod * factor
     783        if neg:
     784            prod = -prod
     785        return prod
     786
     787    def sum(self, terms, simplify=False):
     788        r"""
     789        Given a sequence, returns a \class{SageInputExpression}
     790        for the product of the elements.
     791
     792        With \code{simplify=True}, performs some simplifications
     793        first.  If any element is formatted as a string \code{'0'},
     794        then it is removed from the sequence (unless it is the only
     795        element in the sequence); and any instances of \code{a + -b}
     796        are changed to \code{a - b}.
     797
     798        EXAMPLES:
     799            sage: from sage.misc.sage_input import SageInputBuilder
     800
     801            sage: sib = SageInputBuilder()
     802            sage: sib.result(sib.sum([-1, 0, 1, 0, -1]))
     803            -1 + 0 + 1 + 0 + -1
     804
     805            sage: sib = SageInputBuilder()
     806            sage: sib.result(sib.sum([-1, 0, 1, 0, -1], simplify=True))
     807            -1 + 1 - 1
     808
     809            sage: sib = SageInputBuilder()
     810            sage: sib.result(sib.sum([0, 0, 0], simplify=True))
     811            0
     812        """
     813        terms = [self(term) for term in terms]
     814        if simplify:
     815            i = 0
     816            while i < len(terms):
     817                term = terms[i]
     818                if isinstance(term, SIE_literal_stringrep) and term._sie_value == '0':
     819                    terms[i:i+1] = []
     820                else:
     821                    i += 1
     822            if len(terms) == 0:
     823                terms.append(SIE_literal_stringrep(self, '0'))
     824
     825        sum = terms[0]
     826        for term in terms[1:]:
     827            if simplify and isinstance(term, SIE_unary) and term._sie_op == '-':
     828                sum = sum - term._sie_operand
     829            else:
     830                sum = sum + term
     831        return sum
     832
     833    def result(self, e):
     834        r"""
     835        Given a \class{SageInputExpression} constructed using \code{self},
     836        returns a tuple of a list of commands and an expression
     837        (and possibly a dictionary of local variables) suitable for
     838        \function{sage_eval}.
     839
     840        EXAMPLES:
     841            sage: from sage.misc.sage_input import SageInputBuilder
     842
     843            sage: sib = SageInputBuilder()
     844            sage: r = sib.result(sib(6) * sib(7)); r
     845            6*7
     846            sage: tuple(r)
     847            ('', '6*7')
     848        """
     849        sif = SageInputFormatter()
     850
     851        e._sie_prepare(sif)
     852
     853        s = sif.format(e, 0)
     854
     855        locals = self._locals
     856        if len(locals):
     857            return SageInputAnswer(sif._commands, sif.format(e, 0), locals)
     858        else:
     859            return SageInputAnswer(sif._commands, sif.format(e, 0))
     860
     861# Python's precedence levels.  Hand-transcribed from section 5.14 of
     862# the Python reference manual.
     863_prec_lambda = 2
     864_prec_or = 4
     865_prec_and = 6
     866_prec_not = 8
     867_prec_membership = 10
     868_prec_identity = 12
     869_prec_comparison = 14
     870_prec_bitor = 16
     871_prec_bitxor = 18
     872_prec_bitand = 20
     873_prec_shift = 22
     874_prec_addsub = 24
     875_prec_muldiv = 26
     876_prec_negate = 28
     877_prec_not = 30
     878_prec_exponent = 32
     879_prec_attribute = 34
     880_prec_subscript = 36
     881_prec_slicing = 38
     882_prec_funcall = 40
     883_prec_atomic = 42
     884
     885class SageInputExpression(object):
     886    r"""
     887    Subclasses of this class represent expressions for \function{sage_input}.
     888    \sage classes should define a \method{_sage_input_} method, which
     889    will return an instance of \class{SageInputExpression}, created using
     890    methods of \class{SageInputBuilder}.
     891
     892    To the extent possible, operations on \class{SageInputExpression} objects
     893    construct a new \class{SageInputExpression} representing that operation.
     894    That is, if \var{a} is a \class{SageInputExpression}, then \code{a + b}
     895    constructs a \class{SageInputExpression} representing this sum.
     896    This also works for attribute access, function calls, subscripts, etc.
     897    Since arbitrary attribute accesses might be used to construct a new
     898    attribte-access expression, all internal attributes and methods
     899    have names that begin with \code{_sie_} to reduce the chance of
     900    collisions.
     901
     902    It is expected that instances of this class will not be directly
     903    created outside this module; instead, instances will be created
     904    using methods of \class{SageInputBuilder} and \class{SageInputExpression}.
     905
     906    Values of type \class{SageInputExpression} print in a fairly ugly
     907    way, that reveals the internal structure of the expression tree.
     908    """
     909
     910    def __init__(self, sib):
     911        r"""
     912        Initialize a \class{SageInputExpression}.
     913
     914        EXAMPLES:
     915            sage: from sage.misc.sage_input import SageInputBuilder
     916
     917            sage: sib = SageInputBuilder()
     918            sage: sie = sib(3) # indirect doctest
     919            sage: sie
     920            {atomic:3}
     921            sage: sie._sie_builder is sib
     922            True
     923        """
     924        self._sie_refcount = 0
     925        self._sie_builder = sib
     926        self._sie_context = None
     927        self._sie_preferred_varname = None
     928        self._sie_varname = None
     929        self._sie_use_var = False
     930        self._sie_requested_varname = False
     931
     932    def _sie_is_simple(self):
     933        r"""
     934        Returns \code{True} if this \class{SageInputExpression} is simple
     935        enough that duplicate uses are not worth caching.  Normally
     936        this will be true if the expression represents a single token.
     937
     938        EXAMPLES:
     939            sage: from sage.misc.sage_input import SageInputBuilder
     940
     941            sage: sib = SageInputBuilder()
     942            sage: sib.name('QQ')._sie_is_simple()
     943            True
     944            sage: sib(GF(2))._sie_is_simple()
     945            False
     946        """
     947        return False
     948
     949    def _sie_referenced(self):
     950        r"""
     951        Returns a list of the immediate subexpressions of this
     952        \class{SageInputExpression}.
     953
     954        EXAMPLES:
     955            sage: from sage.misc.sage_input import SageInputBuilder
     956
     957            sage: sib = SageInputBuilder()
     958            sage: len(sib(GF(2))._sie_referenced())
     959            2
     960            sage: sib(5)._sie_referenced()
     961            []
     962        """
     963        return []
     964
     965    def _sie_prepare(self, sif):
     966        r"""
     967        We traverse the entire expression DAG to prepare for printing.
     968        Here, we notice nodes with more than one parent, and mark them
     969        to replace with a variable (rather than generating the value
     970        multiple times).
     971
     972        EXAMPLES:
     973            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     974
     975            sage: sib = SageInputBuilder()
     976            sage: sif = SageInputFormatter()
     977            sage: pair = sib((GF(2), GF(2)))
     978            sage: single = sib(GF(2))
     979            sage: single._sie_refcount
     980            0
     981            sage: single._sie_use_var
     982            False
     983            sage: sib((GF(2), GF(2)))._sie_prepare(sif)
     984            sage: single._sie_refcount
     985            2
     986            sage: single._sie_use_var
     987            True
     988        """
     989        if self._sie_context is not sif:
     990            self._sie_context = sif
     991            self._sie_refcount = 0
     992        self._sie_refcount += 1
     993        if not self._sie_is_simple():
     994            if self._sie_refcount == 2:
     995                self._sie_require_varname(sif)
     996                self._sie_use_var = True
     997        if self._sie_refcount == 1:
     998            for r in self._sie_referenced():
     999                r._sie_prepare(sif)
     1000
     1001    def _sie_require_varname(self, sif):
     1002        r"""
     1003        Mark this \class{SageInputExpression} as requiring a variable name,
     1004        and register it with a \class{SageInputFormatter} (which will
     1005        allocate a variable name at the end of the preparatory phase).
     1006
     1007        EXAMPLES:
     1008            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     1009
     1010            sage: sib = SageInputBuilder()
     1011            sage: sif = SageInputFormatter()
     1012            sage: sie = sib(3)
     1013            sage: sie._sie_require_varname(sif)
     1014            sage: sie._sie_requested_varname
     1015            True
     1016        """
     1017        if not self._sie_requested_varname:
     1018            sif.register_name(self._sie_preferred_varname)
     1019            self._sie_requested_varname = True
     1020            self._sie_generated = False
     1021
     1022    def _sie_get_varname(self, sif):
     1023        r"""
     1024        Get the variable name that the \class{SageInputFormatter} allocated
     1025        for this \class{SageInputExpression}.
     1026
     1027        EXAMPLES:
     1028            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     1029
     1030            sage: sib = SageInputBuilder()
     1031            sage: sif = SageInputFormatter()
     1032            sage: sie = sib(3)
     1033            sage: sie._sie_require_varname(sif)
     1034            sage: sie._sie_get_varname(sif)
     1035            'si'
     1036        """
     1037        if self._sie_varname is None:
     1038            self._sie_varname = sif.get_name(self._sie_preferred_varname)
     1039
     1040        return self._sie_varname
     1041
     1042    def __call__(self, *args, **kwargs):
     1043        r"""
     1044        Given a \class{SageInputExpression}, build a new
     1045        \class{SageInputExpression} representing a function call node
     1046        (with \code{self} as the function).
     1047
     1048        EXAMPLES:
     1049            sage: from sage.misc.sage_input import SageInputBuilder
     1050
     1051            sage: sib = SageInputBuilder()
     1052            sage: sie = sib(3)
     1053            sage: sie(4)
     1054            {call: {atomic:3}({atomic:4})}
     1055        """
     1056        args = map(self._sie_builder, args)
     1057        for k in kwargs:
     1058            kwargs[k] = self._sie_builder(kwargs[k])
     1059        return SIE_call(self._sie_builder, self, args, kwargs)
     1060           
     1061    def __getitem__(self, key):
     1062        r"""
     1063        Given a \class{SageInputExpression}, build a new
     1064        \class{SageInputExpression} representing a subscript expression
     1065        (with \code{self} as the value being subscripted).
     1066
     1067        Currently, slices are not supported.
     1068
     1069        EXAMPLES:
     1070            sage: from sage.misc.sage_input import SageInputBuilder
     1071
     1072            sage: sib = SageInputBuilder()
     1073            sage: sie = sib(3)
     1074            sage: sie[4]
     1075            {subscr: {atomic:3}[{atomic:4}]}
     1076            sage: sie[sib.name('x'), sib.name('y')]
     1077            {subscr: {atomic:3}[{tuple: ({atomic:x}, {atomic:y})}]}
     1078        """
     1079        skey = self._sie_builder(key)
     1080        return SIE_subscript(self._sie_builder, self, skey)
     1081
     1082    def __pow__(self, other):
     1083        r"""
     1084        Compute an expression tree for \code{self ** other}.
     1085
     1086        EXAMPLES:
     1087            sage: from sage.misc.sage_input import SageInputBuilder
     1088
     1089            sage: sib = SageInputBuilder()
     1090            sage: sie = sib(3)
     1091            sage: sie ^ 4
     1092            {binop:** {atomic:3} {atomic:4}}
     1093        """
     1094        return self._sie_binop('**', other)
     1095
     1096    def __mul__(self, other):
     1097        r"""
     1098        Compute an expression tree for \code{self * other}.
     1099
     1100        EXAMPLES:
     1101            sage: from sage.misc.sage_input import SageInputBuilder
     1102
     1103            sage: sib = SageInputBuilder()
     1104            sage: sie = sib(3)
     1105            sage: sie * 4
     1106            {binop:* {atomic:3} {atomic:4}}
     1107        """
     1108        return self._sie_binop('*', other)
     1109
     1110    def __div__(self, other):
     1111        r"""
     1112        Compute an expression tree for \code{self / other}.
     1113
     1114        EXAMPLES:
     1115            sage: from sage.misc.sage_input import SageInputBuilder
     1116
     1117            sage: sib = SageInputBuilder()
     1118            sage: sie = sib(3)
     1119            sage: sie / 4
     1120            {binop:/ {atomic:3} {atomic:4}}
     1121        """
     1122        return self._sie_binop('/', other)
     1123
     1124    def __add__(self, other):
     1125        r"""
     1126        Compute an expression tree for \code{self + other}.
     1127
     1128        EXAMPLES:
     1129            sage: from sage.misc.sage_input import SageInputBuilder
     1130
     1131            sage: sib = SageInputBuilder()
     1132            sage: sie = sib(3)
     1133            sage: sie + 4
     1134            {binop:+ {atomic:3} {atomic:4}}
     1135        """
     1136        return self._sie_binop('+', other)
     1137
     1138    def __sub__(self, other):
     1139        r"""
     1140        Compute an expression tree for \code{self - other}.
     1141
     1142        EXAMPLES:
     1143            sage: from sage.misc.sage_input import SageInputBuilder
     1144
     1145            sage: sib = SageInputBuilder()
     1146            sage: sie = sib(3)
     1147            sage: sie - 4
     1148            {binop:- {atomic:3} {atomic:4}}
     1149        """
     1150        return self._sie_binop('-', other)
     1151
     1152    def _sie_binop(self, op, other):
     1153        r"""
     1154        Compute an expression tree for \code{self OP other},
     1155        where OP is a string representing a binary operator (such as
     1156        '+' or '**').
     1157
     1158        EXAMPLES:
     1159            sage: from sage.misc.sage_input import SageInputBuilder
     1160
     1161            sage: sib = SageInputBuilder()
     1162            sage: v = sib.name('x')._sie_binop('%', sib.name('y'))
     1163            sage: type(v)
     1164            <class 'sage.misc.sage_input.SIE_binary'>
     1165            sage: (v)._sie_op
     1166            '%'
     1167            sage: v
     1168            {binop:% {atomic:x} {atomic:y}}
     1169        """
     1170        return SIE_binary(self._sie_builder, op, self, self._sie_builder(other))
     1171
     1172    def __neg__(self):
     1173        r"""
     1174        Compute an expression tree for \code{-self}.
     1175
     1176        EXAMPLES:
     1177            sage: from sage.misc.sage_input import SageInputBuilder
     1178
     1179            sage: sib = SageInputBuilder()
     1180            sage: sie = sib(3)
     1181            sage: -sie
     1182            {unop:- {atomic:3}}
     1183        """
     1184        return self._sie_unop('-')
     1185
     1186    def _sie_unop(self, op):
     1187        r"""
     1188        Compute an expression tree for \code{OP self},
     1189        where OP is a string representing a unary operator (such as
     1190        '-' or '~').
     1191
     1192        EXAMPLES:
     1193            sage: from sage.misc.sage_input import SageInputBuilder
     1194
     1195            sage: sib = SageInputBuilder()
     1196            sage: sie = sib(3)
     1197            sage: v = sie._sie_unop('~')
     1198            sage: type(v)
     1199            <class 'sage.misc.sage_input.SIE_unary'>
     1200            sage: (v)._sie_op
     1201            '~'
     1202            sage: v
     1203            {unop:~ {atomic:3}}
     1204        """
     1205        return SIE_unary(self._sie_builder, op, self)
     1206
     1207    def _sie_format(self, sif):
     1208        r"""
     1209        Return the formatted string value of this expression, and the
     1210        precedence of the top-level operator in the expression.
     1211
     1212        EXAMPLES:
     1213
     1214        Actually, all of these are examples of the \method{_sie_format}
     1215        method on subclasses of \class{SageInputExpression};
     1216        \class{SageInputExpression} itself is an abstract base class
     1217        (that cannot be instantiated).
     1218       
     1219            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     1220
     1221            sage: sib = SageInputBuilder()
     1222            sage: sif = SageInputFormatter()
     1223            sage: sie = sib(3)
     1224
     1225            sage: for v in (sie, sie+7, sie/5):
     1226            ...       v._sie_prepare(sif)
     1227            ...       v._sie_format(sif)
     1228            ('3', 42)
     1229            ('3 + 7', 24)
     1230            ('3/5', 26)
     1231        """
     1232        raise NotImplementedError
     1233
     1234class SIE_literal(SageInputExpression):
     1235    r"""
     1236    An abstract base class for ``literals'' (basically, values which
     1237    consist of a single token).
     1238
     1239    EXAMPLES:
     1240        sage: from sage.misc.sage_input import SageInputBuilder, SIE_literal
     1241
     1242        sage: sib = SageInputBuilder()
     1243        sage: sie = sib(3)
     1244        sage: sie
     1245        {atomic:3}
     1246        sage: isinstance(sie, SIE_literal)
     1247        True
     1248    """
     1249
     1250    def _sie_is_simple(self):
     1251        r"""
     1252        Report that \class{SIE_literal} values are not worth replacing by
     1253        variables (for ``common subexpression elimination'') even if they
     1254        occur multiple times in an expression.
     1255
     1256        EXAMPLES:
     1257            sage: from sage.misc.sage_input import SageInputBuilder
     1258
     1259            sage: sib = SageInputBuilder()
     1260            sage: sie = sib(3)
     1261            sage: sie._sie_is_simple()
     1262            True
     1263        """
     1264        # Perhaps this should actually look at the formatted length of self,
     1265        # and sometimes return false?  If some 50-digit integer occurs multiple
     1266        # times in an expression, it might be better to do the replacement.
     1267        return True
     1268
     1269class SIE_literal_stringrep(SIE_literal):
     1270    r"""
     1271    Values in this class are leaves in a \function{sage_input} expression
     1272    tree.  Typically they represent a single token, and consist of the
     1273    string representation of that token.  They are used for integer,
     1274    floating-point, and string literals, and for name expressions.
     1275
     1276    EXAMPLES:
     1277        sage: from sage.misc.sage_input import SageInputBuilder, SIE_literal_stringrep
     1278
     1279        sage: sib = SageInputBuilder()
     1280        sage: isinstance(sib(3), SIE_literal_stringrep)
     1281        True
     1282        sage: isinstance(sib(3.14159, True), SIE_literal_stringrep)
     1283        True
     1284        sage: isinstance(sib.name('pi'), SIE_literal_stringrep)
     1285        True
     1286        sage: isinstance(sib(False), SIE_literal_stringrep)
     1287        True
     1288        sage: sib(False)
     1289        {atomic:False}
     1290    """
     1291
     1292    def __init__(self, sib, n):
     1293        r"""
     1294        Initialize a \class{SIE_literal_stringrep} value.
     1295
     1296        INPUTS:
     1297            sib -- a \class{SageInputBuilder}
     1298            n -- a string; the value to be printed for this expression
     1299
     1300        EXAMPLES:
     1301            sage: from sage.misc.sage_input import SageInputBuilder
     1302
     1303            sage: sib = SageInputBuilder()
     1304            sage: sib(3)
     1305            {atomic:3}
     1306            sage: sib(3)._sie_value
     1307            '3'
     1308        """
     1309        super(SIE_literal_stringrep, self).__init__(sib)
     1310        self._sie_value = str(n)
     1311
     1312    def __repr__(self):
     1313        r"""
     1314        Returns a string representing this \class{SIE_literal_stringrep}
     1315        value.
     1316
     1317        EXAMPLES:
     1318            sage: from sage.misc.sage_input import SageInputBuilder
     1319
     1320            sage: sib = SageInputBuilder()
     1321            sage: sib(3)
     1322            {atomic:3}
     1323            sage: sib("\n")
     1324            {atomic:'\n'}
     1325        """
     1326        return "{atomic:%s}" % self._sie_value
     1327
     1328    def _sie_format(self, sif):
     1329        r"""
     1330        Return the formatted string value of this expression, and an indication
     1331        that it is ``atomic'' (never needs to be parenthesized).
     1332
     1333        EXAMPLES:
     1334            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     1335
     1336            sage: sib = SageInputBuilder()
     1337            sage: sif = SageInputFormatter()
     1338            sage: sie = sib(True)
     1339            sage: sie._sie_prepare(sif)
     1340            sage: sie._sie_format(sif)
     1341            ('True', 42)
     1342        """
     1343        return self._sie_value, _prec_atomic
     1344       
     1345class SIE_call(SageInputExpression):
     1346    r"""
     1347    This class represents a function-call node in a \function{sage_input}
     1348    expression tree.
     1349
     1350    EXAMPLES:
     1351        sage: from sage.misc.sage_input import SageInputBuilder
     1352
     1353        sage: sib = SageInputBuilder()
     1354        sage: sie = sib.name('GF')
     1355        sage: sie(49)
     1356        {call: {atomic:GF}({atomic:49})}
     1357    """
     1358
     1359    def __init__(self, sib, func, args, kwargs):
     1360        r"""
     1361        Initialize an instance of \class{SIE_call}.
     1362
     1363        INPUTS:
     1364            sib -- a \class{SageInputBuilder}
     1365            func -- a \class{SageInputExpression} representing a function
     1366            args -- a list of \class{SageInputExpression}s representing the
     1367                    positional arguments
     1368            kwargs -- a dictionary mapping strings to
     1369                    \class{SageInputExpression}s representing the keyword
     1370                    arguments
     1371
     1372        EXAMPLES:
     1373            sage: from sage.misc.sage_input import SageInputBuilder
     1374
     1375            sage: sib = SageInputBuilder()
     1376            sage: sie = sib('RealField')(53, rnd='RNDZ')
     1377        """
     1378        super(SIE_call, self).__init__(sib)
     1379        self._sie_func = func
     1380        self._sie_args = args
     1381        self._sie_kwargs = kwargs
     1382
     1383    def __repr__(self):
     1384        r"""
     1385        Returns a string representing this \class{SIE_call} value.
     1386
     1387        EXAMPLES:
     1388            sage: from sage.misc.sage_input import SageInputBuilder
     1389
     1390            sage: sib = SageInputBuilder()
     1391            sage: sie = sib('RealField')(53, rnd='RNDZ')
     1392        """
     1393        func = repr(self._sie_func)
     1394        args = [repr(arg) for arg in self._sie_args]
     1395        kwargs = sorted(k + '=' + repr(v) for k, v in self._sie_kwargs.iteritems())
     1396        all_args = ', '.join(args + kwargs)
     1397        return "{call: %s(%s)}" % (func, all_args)
     1398
     1399    def _sie_referenced(self):
     1400        r"""
     1401        Returns a list of the immediate subexpressions of this \class{SIE_call}.
     1402
     1403        EXAMPLES:
     1404            sage: from sage.misc.sage_input import SageInputBuilder
     1405
     1406            sage: sib = SageInputBuilder()
     1407            sage: sie = sib('RealField')(53, rnd='RNDZ')
     1408            sage: sie._sie_referenced()
     1409            [{atomic:53}, {atomic:'RealField'}, {atomic:'RNDZ'}]
     1410        """
     1411        refs = self._sie_args[:]
     1412        refs.append(self._sie_func)
     1413        refs.extend(self._sie_kwargs.itervalues())
     1414        return refs
     1415
     1416    def _sie_format(self, sif):
     1417        r"""
     1418        Return the formatted string value of this expression, and an indication
     1419        that it is a function call.
     1420
     1421        EXAMPLES:
     1422            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     1423
     1424            sage: sib = SageInputBuilder()
     1425            sage: sif = SageInputFormatter()
     1426            sage: sie = sib.name('RealField')(53, rnd='RNDZ')
     1427            sage: sie._sie_prepare(sif)
     1428            sage: sie._sie_format(sif)
     1429            ("RealField(53, rnd='RNDZ')", 40)
     1430        """
     1431        func = sif.format(self._sie_func, _prec_attribute)
     1432        args = [sif.format(arg, 0) for arg in self._sie_args]
     1433        kwargs = sorted(k + '=' + sif.format(v, 0) for k, v in self._sie_kwargs.iteritems())
     1434        all_args = ', '.join(args + kwargs)
     1435        return ('%s(%s)' % (func, all_args), _prec_funcall)
     1436
     1437class SIE_subscript(SageInputExpression):
     1438    r"""
     1439    This class represents a subscript node in a \function{sage_input}
     1440    expression tree.
     1441
     1442    EXAMPLES:
     1443        sage: from sage.misc.sage_input import SageInputBuilder
     1444
     1445        sage: sib = SageInputBuilder()
     1446        sage: sie = sib.name('QQ')['x,y']
     1447        sage: sie
     1448        {subscr: {atomic:QQ}[{atomic:'x,y'}]}
     1449    """
     1450
     1451    def __init__(self, sib, coll, key):
     1452        r"""
     1453        Initialize an instance of \class{SIE_subscript}.
     1454
     1455        INPUTS:
     1456            sib -- a \class{SageInputBuilder}
     1457            func -- a \class{SageInputExpression} representing a collection
     1458            key -- a \class{SageInputExpression} representing the subscript/key
     1459
     1460        As a special case, \var{key} may be \code{None}; this represents an
     1461        empty subscript.  This is not legal Python syntax, but it is legal
     1462        in the \sage preparser in examples like \code{K.<x> = QQ[]}.
     1463
     1464        EXAMPLES:
     1465            sage: from sage.misc.sage_input import SageInputBuilder
     1466
     1467            sage: sib = SageInputBuilder()
     1468            sage: sib.name('QQ')['x']
     1469            {subscr: {atomic:QQ}[{atomic:'x'}]}
     1470            sage: sib.name('x')[1,2,3]
     1471            {subscr: {atomic:x}[{tuple: ({atomic:1}, {atomic:2}, {atomic:3})}]}
     1472            sage: sib.empty_subscript(sib.name('QQ'))
     1473            {subscr: {atomic:QQ}[]}
     1474        """
     1475        super(SIE_subscript, self).__init__(sib)
     1476        self._sie_coll = coll
     1477        self._sie_key = key
     1478
     1479    def __repr__(self):
     1480        r"""
     1481        Returns a string representing this \class{SIE_subscript} value.
     1482
     1483        EXAMPLES:
     1484            sage: from sage.misc.sage_input import SageInputBuilder
     1485
     1486            sage: sib = SageInputBuilder()
     1487            sage: sib.name('ZZ')['x,y']
     1488            {subscr: {atomic:ZZ}[{atomic:'x,y'}]}
     1489        """
     1490        coll = repr(self._sie_coll)
     1491        if self._sie_key is None:
     1492            key = ''
     1493        else:
     1494            key = repr(self._sie_key)
     1495        return "{subscr: %s[%s]}" % (coll, key)
     1496
     1497    def _sie_referenced(self):
     1498        r"""
     1499        Returns a list of the immediate subexpressions of this
     1500        \class{SIE_subscript}.
     1501
     1502        EXAMPLES:
     1503            sage: from sage.misc.sage_input import SageInputBuilder
     1504
     1505            sage: sib = SageInputBuilder()
     1506            sage: sie = sib.name('GF')(5)['x,y']
     1507            sage: sie._sie_referenced()
     1508            [{call: {atomic:GF}({atomic:5})}, {atomic:'x,y'}]
     1509        """
     1510        refs = [self._sie_coll]
     1511        if self._sie_key is not None:
     1512            refs.append(self._sie_key)
     1513        return refs
     1514
     1515    def _sie_format(self, sif):
     1516        r"""
     1517        Return the formatted string value of this expression, and an
     1518        indication that it is a subscript.
     1519
     1520        EXAMPLES:
     1521            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     1522
     1523            sage: sib = SageInputBuilder()
     1524            sage: sif = SageInputFormatter()
     1525            sage: sie = sib.name('QQ')['x']
     1526            sage: sie._sie_prepare(sif)
     1527            sage: sie._sie_format(sif)
     1528            ("QQ['x']", 36)
     1529        """
     1530        coll = sif.format(self._sie_coll, _prec_attribute)
     1531        if self._sie_key is None:
     1532            key = ''
     1533        else:
     1534            key = sif.format(self._sie_key, 0)
     1535        return '%s[%s]' % (coll, key), _prec_subscript
     1536
     1537class SIE_tuple(SageInputExpression):
     1538    r"""
     1539    This class represents a tuple node in a \function{sage_input}
     1540    expression tree.
     1541
     1542    EXAMPLES:
     1543        sage: from sage.misc.sage_input import SageInputBuilder
     1544
     1545        sage: sib = SageInputBuilder()
     1546        sage: sib((1, 'howdy'))
     1547        {tuple: ({atomic:1}, {atomic:'howdy'})}
     1548    """
     1549
     1550    def __init__(self, sib, values):
     1551        r"""
     1552        Initialize an instance of \class{SIE_tuple}.
     1553
     1554        INPUTS:
     1555            sib -- a \class{SageInputBuilder}
     1556            values -- a list of \class{SageInputExpression}s representing
     1557                 the elements of this tuple
     1558
     1559        EXAMPLES:
     1560            sage: from sage.misc.sage_input import SageInputBuilder
     1561
     1562            sage: sib = SageInputBuilder()
     1563            sage: sib((3.5, -2))
     1564            {tuple: ({call: {atomic:RR}({atomic:3.5000000000000000})}, {unop:- {atomic:2}})}
     1565        """
     1566        super(SIE_tuple, self).__init__(sib)
     1567        self._sie_values = values
     1568
     1569    def __repr__(self):
     1570        r"""
     1571        Returns a string representing this \class{SIE_tuple} value.
     1572
     1573        EXAMPLES:
     1574            sage: from sage.misc.sage_input import SageInputBuilder
     1575
     1576            sage: sib = SageInputBuilder()
     1577            sage: sib((2,3,5))
     1578            {tuple: ({atomic:2}, {atomic:3}, {atomic:5})}
     1579        """
     1580        return "{tuple: (%s)}" % ', '.join([repr(v) for v in self._sie_values])
     1581
     1582    def _sie_referenced(self):
     1583        r"""
     1584        Returns a list of the immediate subexpressions of this
     1585        \class{SIE_tuple}.
     1586
     1587        EXAMPLES:
     1588            sage: from sage.misc.sage_input import SageInputBuilder
     1589
     1590            sage: sib = SageInputBuilder()
     1591            sage: sie = sib((ZZ, GF(5)))
     1592            sage: sie._sie_referenced()
     1593            [{atomic:ZZ}, {call: {atomic:GF}({atomic:5})}]
     1594        """
     1595        return self._sie_values
     1596
     1597    def _sie_format(self, sif):
     1598        r"""
     1599        Return the formatted string value of this tuple, and an
     1600        indication that it is atomic (never needs to be parenthesized).
     1601
     1602        EXAMPLES:
     1603            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     1604
     1605            sage: sib = SageInputBuilder()
     1606            sage: sif = SageInputFormatter()
     1607            sage: for v in ((), (1,), (1,2)):
     1608            ...        sie = sib(v)
     1609            ...        sie._sie_prepare(sif)
     1610            ...        sie._sie_format(sif)
     1611            ('()', 42)
     1612            ('(1,)', 42)
     1613            ('(1, 2)', 42)
     1614        """
     1615        values = [sif.format(val, 0) for val in self._sie_values]
     1616        if len(values) == 1:
     1617            return '(%s,)' % values[0], _prec_atomic
     1618        else:
     1619            return '(%s)' % ', '.join(values), _prec_atomic
     1620
     1621class SIE_binary(SageInputExpression):
     1622    r"""
     1623    This class represents an arithmetic expression with a binary operator
     1624    and its two arguments, in a \function{sage_input} expression tree.
     1625
     1626    EXAMPLES:
     1627        sage: from sage.misc.sage_input import SageInputBuilder
     1628
     1629        sage: sib = SageInputBuilder()
     1630        sage: sib(3)+5
     1631        {binop:+ {atomic:3} {atomic:5}}
     1632    """
     1633
     1634    def __init__(self, sib, op, lhs, rhs):
     1635        r"""
     1636        Initialize an instance of \class{SIE_binary}.
     1637
     1638        INPUTS:
     1639            sib -- a \class{SageInputBuilder}
     1640            op -- a string representing a binary operator, such as '*' or '%'
     1641            lhs -- a \class{SageInputExpression}
     1642            rhs -- a \class{SageInputExpression}
     1643
     1644        EXAMPLES:
     1645            sage: from sage.misc.sage_input import SageInputBuilder
     1646
     1647            sage: sib = SageInputBuilder()
     1648            sage: sib(3)*5
     1649            {binop:* {atomic:3} {atomic:5}}
     1650           
     1651        """
     1652        super(SIE_binary, self).__init__(sib)
     1653        self._sie_op = op
     1654        self._sie_operands = (lhs, rhs)
     1655
     1656    def __repr__(self):
     1657        r"""
     1658        Returns a string representing this \class{SIE_binary} value.
     1659
     1660        EXAMPLES:
     1661            sage: from sage.misc.sage_input import SageInputBuilder
     1662
     1663            sage: sib = SageInputBuilder()
     1664            sage: sib(7)/9
     1665            {binop:/ {atomic:7} {atomic:9}}
     1666        """
     1667        return "{binop:%s %s %s}" % (self._sie_op, repr(self._sie_operands[0]), repr(self._sie_operands[1]))
     1668
     1669    def _sie_referenced(self):
     1670        r"""
     1671        Returns a tuple of the immediate subexpressions of this
     1672        \class{SIE_binary}.
     1673
     1674        EXAMPLES:
     1675            sage: from sage.misc.sage_input import SageInputBuilder
     1676
     1677            sage: sib = SageInputBuilder()
     1678            sage: sie = sib.name('x') + 5
     1679            sage: sie._sie_referenced()
     1680            ({atomic:x}, {atomic:5})
     1681        """
     1682        return self._sie_operands
     1683
     1684    def _sie_format(self, sif):
     1685        r"""
     1686        Return the formatted string value of this expression,
     1687        and the precedence of the top-level operator in the expression.
     1688
     1689        EXAMPLES:
     1690            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     1691
     1692            sage: sib = SageInputBuilder()
     1693            sage: sif = SageInputFormatter()
     1694            sage: x = sib.name('x')
     1695            sage: y = sib.name('y')
     1696            sage: for v in (x+y, x*y, x**y):
     1697            ...       v._sie_prepare(sif)
     1698            ...       v._sie_format(sif)
     1699            ('x + y', 24)
     1700            ('x*y', 26)
     1701            ('x^y', 32)
     1702
     1703        Note that the printing for $x^y$ varies depending on whether the
     1704        preparser is enabled.
     1705            sage: sibnp = SageInputBuilder(preparse=False)
     1706            sage: sif = SageInputFormatter()
     1707            sage: v = x**y
     1708            sage: v._sie_prepare(sif)
     1709            sage: v._sie_format(sif)
     1710            ('x^y', 32)
     1711
     1712        TESTS:
     1713            sage: x = sib.name('x')
     1714            sage: y = sib.name('y')
     1715            sage: z = sib.name('z')
     1716            sage: sib.result((x+y)+z)
     1717            x + y + z
     1718            sage: sib.result(x+(y+z))
     1719            x + (y + z)
     1720            sage: sib.result((x*y)*z)
     1721            x*y*z
     1722            sage: sib.result(x*(y*z))
     1723            x*(y*z)
     1724            sage: sib.result(x+(y*z))
     1725            x + y*z
     1726            sage: sib.result((x+y)*z)
     1727            (x + y)*z
     1728            sage: sib.result((x^y)^z)
     1729            (x^y)^z
     1730            sage: sib.result(x^(y^z))
     1731            x^y^z
     1732        """
     1733        op = self._sie_op
     1734        fop = op
     1735        if op == '**':
     1736            lhs = sif.format(self._sie_operands[0], _prec_exponent+1)
     1737            rhs = sif.format(self._sie_operands[1], _prec_exponent)
     1738            if self._sie_builder.preparse():
     1739                return '%s^%s' % (lhs, rhs), _prec_exponent
     1740            else:
     1741                return '%s**%s' % (lhs, rhs), _prec_exponent
     1742
     1743        if op == '*':
     1744            prec = _prec_muldiv
     1745        elif op == '/':
     1746            prec = _prec_muldiv
     1747        elif op == '+':
     1748            fop = ' + '
     1749            prec = _prec_addsub
     1750        elif op == '-':
     1751            fop = ' - '
     1752            prec = _prec_addsub
     1753        else:
     1754            raise ValueError, 'Unhandled op %s in SIE_binary' % op
     1755
     1756        lhs = sif.format(self._sie_operands[0], prec)
     1757        rhs = sif.format(self._sie_operands[1], prec+1)
     1758        return '%s%s%s' % (lhs, fop, rhs), prec
     1759
     1760class SIE_unary(SageInputExpression):
     1761    r"""
     1762    This class represents an arithmetic expression with a unary operator
     1763    and its argument, in a \function{sage_input} expression tree.
     1764
     1765    EXAMPLES:
     1766        sage: from sage.misc.sage_input import SageInputBuilder
     1767
     1768        sage: sib = SageInputBuilder()
     1769        sage: -sib(256)
     1770        {unop:- {atomic:256}}
     1771    """
     1772
     1773    def __init__(self, sib, op, operand):
     1774        r"""
     1775        Initialize an instance of \class{SIE_unary}.
     1776
     1777        INPUTS:
     1778            sib -- a \class{SageInputBuilder}
     1779            op -- a string representing a unary operator, such as '-'
     1780            operand -- a \class{SageInputExpression}
     1781
     1782        EXAMPLES:
     1783            sage: from sage.misc.sage_input import SageInputBuilder
     1784
     1785            sage: sib = SageInputBuilder()
     1786            sage: -sib(3)
     1787            {unop:- {atomic:3}}           
     1788        """
     1789        super(SIE_unary, self).__init__(sib)
     1790        self._sie_op = op
     1791        self._sie_operand = operand
     1792
     1793    def __repr__(self):
     1794        r"""
     1795        Returns a string representing this \class{SIE_unary} value.
     1796
     1797        EXAMPLES:
     1798            sage: from sage.misc.sage_input import SageInputBuilder
     1799
     1800            sage: sib = SageInputBuilder()
     1801            sage: -sib(15)
     1802            {unop:- {atomic:15}}
     1803        """
     1804        return "{unop:%s %s}" % (self._sie_op, repr(self._sie_operand))
     1805
     1806    def _sie_referenced(self):
     1807        r"""
     1808        Returns a list of the immediate subexpressions of this
     1809        \class{SIE_unary}.
     1810
     1811        EXAMPLES:
     1812            sage: from sage.misc.sage_input import SageInputBuilder
     1813
     1814            sage: sib = SageInputBuilder()
     1815            sage: sie = -sib.name('x')
     1816            sage: sie._sie_referenced()
     1817            [{atomic:x}]
     1818        """
     1819
     1820        return [self._sie_operand]
     1821
     1822    def _sie_format(self, sif):
     1823        r"""
     1824        Return the formatted string value of this expression,
     1825        and the precedence of the top-level operator in the expression.
     1826
     1827        EXAMPLES:
     1828            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     1829
     1830            sage: sib = SageInputBuilder()
     1831            sage: sif = SageInputFormatter()
     1832            sage: x = sib.name('x')
     1833            sage: v = -x
     1834            sage: v._sie_prepare(sif)
     1835            sage: v._sie_format(sif)
     1836            ('-x', 28)
     1837
     1838        TESTS:
     1839            sage: x = sib.name('x')
     1840            sage: y = sib.name('y')
     1841            sage: sib.result((-x)+y)
     1842            -x + y
     1843            sage: sib.result(x+(-y))
     1844            x + -y
     1845            sage: sib.result(-(x+y))
     1846            -(x + y)
     1847            sage: sib.result(-(-x))
     1848            --x
     1849            sage: sib.result(x-(-y))
     1850            x - -y
     1851
     1852        We assume that -(x*y) is always equal to (-x)*y.  Using this
     1853        assumption, we print -(x*y) as -x*y, which parses as (-x)*y.
     1854            sage: sib.result(-(x*y))
     1855            -x*y
     1856            sage: sib.result((-x)*y)
     1857            -x*y
     1858            sage: sib.result(x*(-y))
     1859            x*-y
     1860        """
     1861        op = self._sie_op
     1862        fop = op
     1863        rprec = None
     1864        if op == '-':
     1865            # We print -(a*b) as -a*b, even though that will parse as
     1866            # (-a)*b.
     1867            prec = _prec_muldiv
     1868            rprec = _prec_negate
     1869        else:
     1870            raise ValueError, 'Unhandled op %s in SIE_unary' % op
     1871           
     1872        if rprec is None: rprec = prec
     1873
     1874        return '%s%s' % (fop, sif.format(self._sie_operand, prec)), rprec
     1875
     1876class SIE_gens_constructor(SageInputExpression):
     1877    r"""
     1878    This class represents an expression that can create a \sage parent
     1879    with named generators, optionally using the \sage preparser
     1880    generators syntax (like \code{K.<x> = QQ[]}).
     1881
     1882    EXAMPLES:
     1883        sage: from sage.misc.sage_input import SageInputBuilder
     1884
     1885        sage: sib = SageInputBuilder()
     1886        sage: qq = sib.name('QQ')
     1887        sage: sib.parent_with_gens("some parent", qq['x'],
     1888        ...                        ('x',), 'QQx',
     1889        ...                        gens_syntax=sib.empty_subscript(qq))
     1890        {constr_parent: {subscr: {atomic:QQ}[{atomic:'x'}]} with gens: ('x',)}
     1891    """
     1892
     1893    def __init__(self, sib, constr, gen_names, gens_syntax=None):
     1894        r"""
     1895        Initialize an instance of \class{SIE_gens_constructor}.
     1896
     1897        INPUTS:
     1898            sib -- a \class{SageInputBuilder}
     1899            constr -- a \class{SageInputExpression} for constructing
     1900                this parent ``normally''
     1901            gen_names -- a tuple of generator names
     1902            gens_syntax -- an optional \class{SageInputExpression}
     1903                for constructing this parent using the \sage preparser
     1904                generators syntax
     1905
     1906        EXAMPLES:
     1907            sage: from sage.misc.sage_input import SageInputBuilder
     1908
     1909            sage: sib = SageInputBuilder()
     1910            sage: qq = sib.name('QQ')
     1911            sage: sib.parent_with_gens("some parent", qq['x'],
     1912            ...                        ('x',), 'QQx',
     1913            ...                        gens_syntax=sib.empty_subscript(qq))
     1914            {constr_parent: {subscr: {atomic:QQ}[{atomic:'x'}]} with gens: ('x',)}
     1915        """
     1916        super(SIE_gens_constructor, self).__init__(sib)
     1917        self._sie_constr = constr
     1918        self._sie_gen_names = gen_names
     1919        self._sie_gens = None # will be overwritten from .parent_with_gens()
     1920        self._sie_gens_constr = gens_syntax
     1921        self._sie_assign_gens = False
     1922        self._sie_generated = False
     1923
     1924    def __repr__(self):
     1925        r"""
     1926        Returns a string representing this \class{SIE_gens_constructor} value.
     1927
     1928        EXAMPLES:
     1929            sage: from sage.misc.sage_input import SageInputBuilder
     1930
     1931            sage: sib = SageInputBuilder()
     1932            sage: qq = sib.name('QQ')
     1933            sage: sib.parent_with_gens("some parent", qq['x'],
     1934            ...                        ('x',), 'QQx',
     1935            ...                        gens_syntax=sib.empty_subscript(qq))
     1936            {constr_parent: {subscr: {atomic:QQ}[{atomic:'x'}]} with gens: ('x',)}
     1937        """
     1938        return "{constr_parent: %s with gens: %s}" % (repr(self._sie_constr), self._sie_gen_names)
     1939
     1940    def _sie_referenced(self):
     1941        r"""
     1942        Returns a list of the immediate subexpressions of this
     1943        \class{SIE_gens_constructor}.
     1944
     1945
     1946        EXAMPLES:
     1947            sage: from sage.misc.sage_input import SageInputBuilder
     1948
     1949            sage: sib = SageInputBuilder()
     1950            sage: qq = sib.name('QQ')
     1951            sage: gc = sib.parent_with_gens("some parent", qq['x'],
     1952            ...                             ('x',), 'QQx',
     1953            ...                             gens_syntax=sib.empty_subscript(qq))
     1954            sage: gc._sie_referenced()
     1955            [{subscr: {atomic:QQ}[{atomic:'x'}]}]
     1956        """
     1957        # This is used to determine if some expressions should be replaced
     1958        # by variables (if the expression has more than one parent in
     1959        # the expression DAG).  We assume that all expressions in
     1960        # self._sie_gens_constr also occur in self._sie_constr.
     1961        return [self._sie_constr]
     1962           
     1963    def _sie_gens_referenced(self, sif):
     1964        r"""
     1965        Mark that at least one of the generators in this
     1966        \class{SIE_gens_constructor} is used.  (This means we will actually
     1967        construct all of the generators.)
     1968
     1969        EXAMPLES:
     1970            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     1971
     1972            sage: sib = SageInputBuilder()
     1973            sage: sif = SageInputFormatter()
     1974            sage: qq = sib.name('QQ')
     1975            sage: gc = sib.parent_with_gens("some parent", qq['x'],
     1976            ...                             ('x',), 'QQx',
     1977            ...                             gens_syntax=sib.empty_subscript(qq))
     1978            sage: gc._sie_assign_gens
     1979            False
     1980            sage: gc._sie_gens_referenced(sif)
     1981            sage: gc._sie_assign_gens
     1982            True
     1983        """
     1984        self._sie_assign_gens = True
     1985        self._sie_require_varname(sif)
     1986        for gen in self._sie_gens:
     1987            gen._sie_require_varname(sif)
     1988
     1989    def _sie_add_command(self, sif):
     1990        r"""
     1991        Build commands to construct this parent and (if necessary)
     1992        its associated generators.
     1993
     1994        EXAMPLES:
     1995            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     1996
     1997            sage: sib = SageInputBuilder()
     1998            sage: sif = SageInputFormatter()
     1999            sage: qq = sib.name('QQ')
     2000            sage: gc = sib.parent_with_gens("some parent", qq['x'],
     2001            ...                             ('x',), 'QQx',
     2002            ...                             gens_syntax=sib.empty_subscript(qq))
     2003            sage: gc._sie_gens_referenced(sif)
     2004            sage: gc._sie_prepare(sif)
     2005            sage: gc._sie_add_command(sif)
     2006            sage: sif._commands
     2007            'QQx.<x> = QQ[]\n'
     2008
     2009        TESTS:
     2010        There are several tricky cases here.
     2011
     2012        We prefer the \sage preparser generators syntax:
     2013            sage: sage_input(polygen(ZZ))
     2014            R.<x> = ZZ[]
     2015            x
     2016
     2017        But of course we can't use that without the preparser:
     2018            sage: sage_input(polygen(ZZ), preparse=False)
     2019            R = ZZ['x']
     2020            x = R.gen()
     2021            x
     2022
     2023        We also can't use the preparser syntax if there is a conflict
     2024        between generator names.  For example, this works:
     2025            sage: sage_input((polygen(ZZ), polygen(GF(17), 'y')))
     2026            R1.<x> = ZZ[]
     2027            R2.<y> = GF(17)[]
     2028            (x, y)
     2029
     2030        but this can't use the preparser syntax.
     2031            sage: sage_input((polygen(ZZ), polygen(GF(17))))
     2032            R1 = ZZ['x']
     2033            x1 = R1.gen()
     2034            R2 = GF(17)['x']
     2035            x2 = R2.gen()
     2036            (x1, x2)
     2037           
     2038        If we never use the generators, then we don't bother with the
     2039        preparser syntax.
     2040            sage: sage_input((ZZ['x'], ZZ['x'], GF(17)['y']))
     2041            R = ZZ['x']
     2042            (R, R, GF(17)['y'])
     2043        """
     2044        if not self._sie_generated:
     2045            if self._sie_builder.preparse() and \
     2046                    self._sie_gens_constr is not None and \
     2047                    all(g._sie_got_preferred(sif) for g in self._sie_gens):
     2048                s, _ = self._sie_gens_constr._sie_format(sif)
     2049                sif._commands += '%s.<%s> = %s\n' % (self._sie_get_varname(sif), ','.join(self._sie_gen_names), s)
     2050            else:
     2051                s, _ = self._sie_constr._sie_format(sif)
     2052                sif._commands += '%s = %s\n' % (self._sie_get_varname(sif), s)
     2053                if self._sie_assign_gens:
     2054                    if len(self._sie_gens) == 1:
     2055                        sif._commands += '%s = %s.gen()\n' % (self._sie_gens[0]._sie_get_varname(sif), self._sie_get_varname(sif))
     2056                    else:
     2057                        sif._commands += '%s = %s.gens()\n' % (','.join([g._sie_get_varname(sif) for g in self._sie_gens]), self._sie_get_varname(sif))
     2058            self._sie_generated = True
     2059       
     2060    def _sie_format(self, sif):
     2061        r"""
     2062        Return the formatted string value of this parent-construction
     2063        expression, and its precedence.
     2064
     2065        As a side effect, if the generators of this parent are used,
     2066        this adds commands to assign the generators to names.
     2067
     2068        EXAMPLES:
     2069            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     2070
     2071            sage: sib = SageInputBuilder()
     2072            sage: sif = SageInputFormatter()
     2073            sage: qq = sib.name('QQ')
     2074            sage: gc = sib.parent_with_gens("some parent", qq['x'],
     2075            ...                             ('x',), 'QQx',
     2076            ...                             gens_syntax=sib.empty_subscript(qq))
     2077            sage: gc._sie_gens_referenced(sif)
     2078            sage: gc._sie_prepare(sif)
     2079            sage: gc._sie_format(sif)
     2080            ('QQx', 42)
     2081            sage: sif._commands
     2082            'QQx.<x> = QQ[]\n'
     2083        """
     2084        if self._sie_assign_gens:
     2085            self._sie_add_command(sif)
     2086            return self._sie_get_varname(sif), _prec_atomic
     2087
     2088        return self._sie_constr._sie_format(sif)
     2089
     2090class SIE_gen(SageInputExpression):
     2091    r"""
     2092    This class represents a named generator of a parent with named
     2093    generators.
     2094
     2095    EXAMPLES:
     2096        sage: from sage.misc.sage_input import SageInputBuilder
     2097
     2098        sage: sib = SageInputBuilder()
     2099        sage: sib.gen(ZZ['x'])
     2100        {gen:x {constr_parent: {subscr: {atomic:ZZ}[{atomic:'x'}]} with gens: ('x',)}}
     2101    """
     2102
     2103    def __init__(self, sib, parent, name):
     2104        r"""
     2105        Initializes an instance of \class{SIE_gen}.
     2106
     2107        INPUTS:
     2108            sib -- a \class{SageInputBuilder}
     2109            parent -- a \class{SIE_gens_constructor}
     2110            name -- a string with the name of this generator
     2111
     2112        EXAMPLES:
     2113            sage: from sage.misc.sage_input import SageInputBuilder
     2114
     2115            sage: sib = SageInputBuilder()
     2116            sage: sib.gen(ZZ['x']) # indirect doctest
     2117            {gen:x {constr_parent: {subscr: {atomic:ZZ}[{atomic:'x'}]} with gens: ('x',)}}
     2118        """
     2119        super(SIE_gen, self).__init__(sib)
     2120        self._sie_parent = parent
     2121        self._sie_preferred_varname = name
     2122
     2123    def __repr__(self):
     2124        r"""
     2125        Returns a string representing this \class{SIE_gen} value.
     2126
     2127        EXAMPLES:
     2128            sage: from sage.misc.sage_input import SageInputBuilder
     2129
     2130            sage: sib = SageInputBuilder()
     2131            sage: sib.gen(ZZ['x']) # indirect doctest
     2132            {gen:x {constr_parent: {subscr: {atomic:ZZ}[{atomic:'x'}]} with gens: ('x',)}}
     2133        """
     2134        return "{gen:%s %s}" % (self._sie_preferred_varname, repr(self._sie_parent))
     2135
     2136    def _sie_is_simple(self):
     2137        r"""
     2138        Report that \class{SIE_gen} values are single tokens.
     2139
     2140        EXAMPLES:
     2141            sage: from sage.misc.sage_input import SageInputBuilder
     2142
     2143            sage: sib = SageInputBuilder()
     2144            sage: sib.gen(ZZ['x'])._sie_is_simple()
     2145            True
     2146        """
     2147        return True
     2148
     2149    def _sie_prepare(self, sif):
     2150        r"""
     2151        We override the \method{_sie_prepare} method from
     2152        \class{SageInputExpression} to additionally mark the parent of this
     2153        generator that the generator names must be assigned.
     2154
     2155        EXAMPLES:
     2156            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     2157
     2158            sage: sib = SageInputBuilder()
     2159            sage: sif = SageInputFormatter()
     2160            sage: sie = sib.gen(GF(13)['z'])
     2161            sage: sie._sie_parent._sie_assign_gens
     2162            False
     2163            sage: sie._sie_prepare(sif)
     2164            sage: sie._sie_parent._sie_assign_gens
     2165            True
     2166        """
     2167        super(SIE_gen, self)._sie_prepare(sif)
     2168        self._sie_parent._sie_gens_referenced(sif)
     2169
     2170    def _sie_format(self, sif):
     2171        r"""
     2172        Return the formatted string value of this named generator,
     2173        and an indication that it is atomic.
     2174
     2175        As a side effect, this generates commands to assign the generators
     2176        of the parent to variables.
     2177
     2178        EXAMPLES:
     2179            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     2180
     2181            sage: sib = SageInputBuilder()
     2182            sage: sif = SageInputFormatter()
     2183            sage: sie = sib.gen(GF(41)['x'])
     2184            sage: sie._sie_prepare(sif)
     2185            sage: sie._sie_format(sif)
     2186            ('x', 42)
     2187            sage: sif._commands
     2188            'R.<x> = GF(41)[]\n'
     2189        """
     2190        self._sie_parent._sie_add_command(sif)
     2191        return self._sie_get_varname(sif), _prec_atomic
     2192
     2193    def _sie_got_preferred(self, sif):
     2194        r"""
     2195        Check whether the \class{SageInputFormatter} assigned us a
     2196        variable name which is the same as the name of the generator
     2197        name.
     2198
     2199        EXAMPLES:
     2200            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     2201
     2202        First we verify that if we use two generators with different
     2203        names, then they get their preferred names.
     2204            sage: sib = SageInputBuilder()
     2205            sage: sif = SageInputFormatter()
     2206            sage: v = sib.gen(GF(2)['x']); w = sib.gen(GF(3)['y'])
     2207            sage: v._sie_prepare(sif); w._sie_prepare(sif)
     2208            sage: v._sie_got_preferred(sif)
     2209            True
     2210            sage: w._sie_got_preferred(sif)
     2211            True
     2212
     2213        Now, we repeat the experiment, except that the generators now
     2214        have the same names.  In this case, the \class{SageInputFormatter}
     2215        will not use the generator name as the variable name, because
     2216        of this conflict.
     2217            sage: sib = SageInputBuilder()
     2218            sage: sif = SageInputFormatter()
     2219            sage: v = sib.gen(GF(2)['x']); w = sib.gen(GF(3)['x'])
     2220            sage: v._sie_prepare(sif); w._sie_prepare(sif)
     2221            sage: v._sie_got_preferred(sif)
     2222            False
     2223            sage: w._sie_got_preferred(sif)
     2224            False
     2225        """
     2226        return self._sie_get_varname(sif) == self._sie_preferred_varname
     2227
     2228class SageInputFormatter:
     2229    r"""
     2230    An instance of this class is used to keep track of variable names
     2231    and a sequence of generated commands during the \function{sage_input}
     2232    formatting process.
     2233    """
     2234
     2235    def __init__(self):
     2236        r"""
     2237        Initialize an instance of \class{SageInputFormatter}.
     2238
     2239        EXAMPLES:
     2240            sage: from sage.misc.sage_input import SageInputFormatter
     2241
     2242            sage: sif = SageInputFormatter()
     2243        """
     2244        self._commands = ''
     2245        self._names = set()
     2246        self._dup_names = {}
     2247
     2248    def format(self, e, prec):
     2249        r"""
     2250        Format a \class{SageInputExpression} into a string.
     2251
     2252        INPUTS:
     2253            e -- a \class{SageInputExpression}
     2254            prec -- an integer representing a precedence level
     2255
     2256        First, we check to see if \var{e} should be replaced by a variable.
     2257        If so, we generate the command to assign the variable, and return
     2258        the name of the variable.
     2259
     2260        Otherwise, we format the expression by calling its \method{_sie_format}
     2261        method, and add parentheses if necessary.
     2262
     2263        EXAMPLES:
     2264            sage: from sage.misc.sage_input import SageInputBuilder, SageInputFormatter
     2265
     2266            sage: sib = SageInputBuilder()
     2267            sage: sif = SageInputFormatter()
     2268            sage: sie = sib(GF(5))
     2269
     2270        Here we ``cheat'' by calling \method{_sie_prepare} twice, to make it
     2271        use a variable.
     2272            sage: sie._sie_prepare(sif)
     2273            sage: sie._sie_prepare(sif)
     2274            sage: sif._commands
     2275            ''
     2276            sage: sif.format(sie, 0)
     2277            'GF_5'
     2278            sage: sif._commands
     2279            'GF_5 = GF(5)\n'
     2280        """
     2281        if e._sie_use_var:
     2282            if not e._sie_generated:
     2283                s, _ = e._sie_format(self)
     2284                self._commands += '%s = %s\n' % (e._sie_get_varname(self), s)
     2285                e._sie_generated = True
     2286
     2287            return e._sie_get_varname(self)
     2288
     2289        s, iprec = e._sie_format(self)
     2290        if iprec < prec:
     2291            s = '(' + s + ')'
     2292        return s
     2293
     2294    def register_name(self, name):
     2295        r"""
     2296        Register that some value would like to use a given name.
     2297        If only one request for a name is received, then we will use the
     2298        requested name; otherwise, we will add numbers to the end of the
     2299        name to make it unique.
     2300
     2301        If the input name is \code{None}, then it is treated as a name of
     2302        \code{'si'}.
     2303
     2304        EXAMPLES:
     2305            sage: from sage.misc.sage_input import SageInputFormatter
     2306
     2307            sage: sif = SageInputFormatter()
     2308            sage: sif._names, sif._dup_names
     2309            (set([]), {})
     2310            sage: sif.register_name('x')
     2311            sage: sif.register_name('y')
     2312            sage: sif._names, sif._dup_names
     2313            (set(['y', 'x']), {})
     2314            sage: sif.register_name('x')
     2315            sage: sif._names, sif._dup_names
     2316            (set(['y', 'x']), {'x': 0})
     2317        """
     2318        if name is None: name = 'si'
     2319
     2320        if name in self._names:
     2321            self._dup_names[name] = 0
     2322        else:
     2323            self._names.add(name)
     2324
     2325    def get_name(self, name):
     2326        r"""
     2327        Return a name corresponding to a given requested name.
     2328        If only one request for a name is received, then we will use the
     2329        requested name; otherwise, we will add numbers to the end of the
     2330        name to make it unique.
     2331
     2332        If the input name is \code{None}, then it is treated as a name of
     2333        \code{'si'}.
     2334
     2335        EXAMPLES:
     2336            sage: from sage.misc.sage_input import SageInputFormatter
     2337
     2338            sage: sif = SageInputFormatter()
     2339            sage: names = ('x', 'x', 'y', 'z')
     2340            sage: for n in names: sif.register_name(n)
     2341            sage: for n in names: sif.get_name(n)
     2342            'x1'
     2343            'x2'
     2344            'y'
     2345            'z'
     2346        """
     2347        if name is None: name = 'si'
     2348
     2349        if name in self._dup_names:
     2350            next = self._dup_names[name] + 1
     2351            self._dup_names[name] = next
     2352            return name + str(next)
     2353        else:
     2354            return name
     2355
     2356def verify_same(a, b):
     2357    r"""
     2358    Verify that two \sage values are the same.  This is an extended equality
     2359    test; it checks that the values are equal and that their parents are equal.
     2360    (For values which are not Elements, the types are checked instead.)
     2361
     2362    If the values are the same, we return \code{None}; otherwise,
     2363    we raise an exception.
     2364
     2365    EXAMPLES:
     2366        sage: from sage.misc.sage_input import verify_same
     2367        sage: verify_same(1, 1)
     2368        sage: verify_same(1, 2)
     2369        Traceback (most recent call last):
     2370        ...
     2371            assert(a == b)
     2372        AssertionError
     2373        sage: verify_same(1, 1r)
     2374        Traceback (most recent call last):
     2375        ...
     2376        AttributeError: 'int' object has no attribute 'parent'
     2377        sage: verify_same(1r, 1)
     2378        Traceback (most recent call last):
     2379        ...
     2380            assert(type(a) == type(b))
     2381        AssertionError
     2382        sage: verify_same(5, GF(7)(5))
     2383        Traceback (most recent call last):
     2384        ...
     2385            assert(a.parent() == b.parent())
     2386        AssertionError
     2387    """
     2388    from sage.structure.element import is_Element
     2389    if is_Element(a):
     2390        assert(a.parent() == b.parent())
     2391    else:
     2392        assert(type(a) == type(b))
     2393    assert(a == b)               
     2394
     2395def verify_si_answer(x, answer, preparse):
     2396    r"""
     2397    INPUTS:
     2398        x -- an arbitrary \sage value
     2399        answer -- a string, or a \class{SageInputAnswer}
     2400        preparse -- \code{True}, \code{False}, or \code{None}
     2401
     2402    Verify that evaluating \var{answer} gives a value equal to \var{x}
     2403    (with the same parent/type).  If \var{preparse} is \code{True} or
     2404    \code{False}, then we evaluate \var{answer} with the preparser
     2405    enabled or disabled, respectively; if \var{preparse} is \code{None},
     2406    then we evaluate \var{answer} both with the preparser enabled and
     2407    disabled and check both results.
     2408
     2409    On success, we return \code{None}; on failure, we raise an exception.
     2410
     2411    EXAMPLES:
     2412        sage: from sage.misc.sage_input import verify_si_answer
     2413        sage: verify_si_answer(1, '1', True)
     2414        sage: verify_si_answer(1, '1', False)
     2415        Traceback (most recent call last):
     2416        ...
     2417        AttributeError: 'int' object has no attribute 'parent'
     2418        sage: verify_si_answer(1, 'ZZ(1)', None)
     2419    """
     2420    from sage.misc.sage_eval import sage_eval
     2421    if preparse is None:
     2422        verify_same(x, sage_eval(answer, preparse=True))
     2423        verify_same(x, sage_eval(answer, preparse=False))
     2424    else:
     2425        verify_same(x, sage_eval(answer, preparse=preparse))
     2426
     2427class SageInputAnswer(tuple):
     2428    r"""
     2429    This class inherits from tuple, so it acts like a tuple when passed
     2430    to \function{sage_eval}; but it prints as a sequence of commands.
     2431
     2432    EXAMPLES:
     2433        sage: from sage.misc.sage_input import SageInputAnswer
     2434        sage: v = SageInputAnswer('x = 22\n', 'x/7'); v
     2435        x = 22
     2436        x/7
     2437        sage: isinstance(v, tuple)
     2438        True
     2439        sage: v[0]
     2440        'x = 22\n'
     2441        sage: v[1]
     2442        'x/7'
     2443        sage: len(v)
     2444        2
     2445        sage: v = SageInputAnswer('', 'sin(3.14)', {'sin': math.sin}); v
     2446        LOCALS:
     2447          sin: <built-in function sin>
     2448        sin(3.14)
     2449        sage: v[0]
     2450        ''
     2451        sage: v[1]
     2452        'sin(3.14)'
     2453        sage: v[2]
     2454        {'sin': <built-in function sin>}
     2455    """
     2456
     2457    def __new__(cls, cmds, expr, locals=None):
     2458        r"""
     2459        Construct an instance of \class{SageInputAnswer}.
     2460
     2461        EXAMPLES:
     2462            sage: from sage.misc.sage_input import SageInputAnswer
     2463            sage: v = SageInputAnswer('', 'sin(3.14)', {'sin': math.sin}); v
     2464            LOCALS:
     2465              sin: <built-in function sin>
     2466            sin(3.14)
     2467            sage: v[0]
     2468            ''
     2469            sage: v[1]
     2470            'sin(3.14)'
     2471            sage: v[2]       
     2472            {'sin': <built-in function sin>}
     2473        """
     2474        if locals:
     2475            return tuple.__new__(cls, (cmds, expr, locals))
     2476        else:
     2477            return tuple.__new__(cls, (cmds, expr))
     2478
     2479    def __repr__(self):
     2480        r"""
     2481        Return a string representation for a \class{SageInputAnswer},
     2482        such that if you evaluate this \class{SageInputAnswer} at the
     2483        \sage command line, you get a result in a nice form ready to
     2484        copy-and-paste.
     2485
     2486        EXAMPLES:
     2487            sage: from sage.misc.sage_input import SageInputAnswer
     2488            sage: v = SageInputAnswer('', 'sin(3.14)', {'sin': math.sin}); v
     2489            LOCALS:
     2490              sin: <built-in function sin>
     2491            sin(3.14)
     2492        """
     2493        if len(self) == 2:
     2494            return self[0] + self[1]
     2495
     2496        locals = self[2]
     2497        locals_text = ''.join('  %s: %r\n' % (k, v) for k, v in locals.iteritems())
     2498        return 'LOCALS:\n' + locals_text + self[0] + self[1]
     2499   
  • sage/rings/integer.pyx

    diff -r f8b52491b393 -r fe6b1dd63297 sage/rings/integer.pyx
    a b  
    29272927        """
    29282928        return str(self)
    29292929
     2930    def _sage_input_(self, sib, coerced):
     2931        r"""
     2932        Produce an expression which will reproduce this value when evaluated.
     2933
     2934        EXAMPLES:
     2935            sage: sage_input(1, verify=True)
     2936            # Verified
     2937            1
     2938            sage: sage_input(1, preparse=False)
     2939            ZZ(1)
     2940            sage: sage_input(-12435, verify=True)
     2941            # Verified
     2942            -12435
     2943            sage: sage_input(0, verify=True)
     2944            # Verified
     2945            0
     2946            sage: sage_input(-3^70, verify=True)
     2947            # Verified
     2948            -2503155504993241601315571986085849
     2949            sage: sage_input(-37, preparse=False)
     2950            -ZZ(37)
     2951            sage: sage_input(-37 * polygen(ZZ), preparse=False)
     2952            R = ZZ['x']
     2953            x = R.gen()
     2954            -37*x
     2955            sage: from sage.misc.sage_input import SageInputBuilder
     2956            sage: (-314159)._sage_input_(SageInputBuilder(preparse=False), False)
     2957            {unop:- {call: {atomic:ZZ}({atomic:314159})}}
     2958            sage: (314159)._sage_input_(SageInputBuilder(preparse=False), True)
     2959            {atomic:314159}
     2960        """
     2961        if coerced or sib.preparse():
     2962            return sib.int(self)
     2963        else:
     2964            if self < 0:
     2965                return -sib.name('ZZ')(sib.int(-self))
     2966            else:
     2967                return sib.name('ZZ')(sib.int(self))
     2968
    29302969    def isqrt(self):
    29312970        r"""
    29322971        Returns the integer floor of the square root of self, or raises
  • sage/rings/integer_mod.pyx

    diff -r f8b52491b393 -r fe6b1dd63297 sage/rings/integer_mod.pyx
    a b  
    362362            1
    363363        """
    364364        return '%s!%s'%(self.parent()._magma_init_(), self)
     365
     366    def _sage_input_(self, sib, coerced):
     367        r"""
     368        Produce an expression which will reproduce this value when evaluated.
     369
     370        EXAMPLES:
     371            sage: K = GF(7)
     372            sage: sage_input(K(5), verify=True)
     373            # Verified
     374            GF(7)(5)
     375            sage: sage_input(K(5) * polygen(K), verify=True)
     376            # Verified
     377            R.<x> = GF(7)[]
     378            5*x
     379            sage: from sage.misc.sage_input import SageInputBuilder
     380            sage: K(5)._sage_input_(SageInputBuilder(), False)
     381            {call: {call: {atomic:GF}({atomic:7})}({atomic:5})}
     382            sage: K(5)._sage_input_(SageInputBuilder(), True)
     383            {atomic:5}
     384        """
     385        v = sib.int(self.lift())
     386        if coerced:
     387            return v
     388        else:
     389            return sib(self.parent())(v)
    365390
    366391    def log(self, b=None):
    367392        r"""
  • sage/rings/integer_ring.pyx

    diff -r f8b52491b393 -r fe6b1dd63297 sage/rings/integer_ring.pyx
    a b  
    815815        """
    816816        return 'IntegerRing()'
    817817
     818    def _sage_input_(self, sib, coerced):
     819        r"""
     820        Produce an expression which will reproduce this value when evaluated.
     821
     822        EXAMPLES:
     823            sage: sage_input(ZZ, verify=True)
     824            # Verified
     825            ZZ
     826            sage: from sage.misc.sage_input import SageInputBuilder
     827            sage: ZZ._sage_input_(SageInputBuilder(), False)
     828            {atomic:ZZ}
     829        """
     830        return sib.name('ZZ')
     831
    818832ZZ = IntegerRing_class()
    819833Z = ZZ
    820834
  • sage/rings/polynomial/polynomial_element.pyx

    diff -r f8b52491b393 -r fe6b1dd63297 sage/rings/polynomial/polynomial_element.pyx
    a b  
    11361136            return "0"
    11371137        return s[1:].lstrip().rstrip()
    11381138       
     1139    def _sage_input_(self, sib, coerced):
     1140        r"""
     1141        Produce an expression which will reproduce this value when evaluated.
     1142
     1143        EXAMPLES:
     1144            sage: K.<x> = ZZ[]
     1145            sage: sage_input(K(0), verify=True)
     1146            # Verified
     1147            ZZ['x'](0)
     1148            sage: sage_input(K(-54321), preparse=False, verify=True)
     1149            # Verified
     1150            ZZ['x'](-54321)
     1151            sage: sage_input(x, verify=True)
     1152            # Verified
     1153            R.<x> = ZZ[]
     1154            x
     1155            sage: sage_input(x, preparse=False)
     1156            R = ZZ['x']
     1157            x = R.gen()
     1158            x
     1159            sage: sage_input((3*x-2)^3, verify=True)
     1160            # Verified
     1161            R.<x> = ZZ[]
     1162            27*x^3 - 54*x^2 + 36*x - 8
     1163            sage: L.<y> = K[]
     1164            sage: sage_input(L(0), verify=True)
     1165            # Verified
     1166            ZZ['x']['y'](0)
     1167            sage: sage_input((x+y+1)^2, verify=True)
     1168            # Verified
     1169            R1.<x> = ZZ[]
     1170            R2.<y> = R1[]
     1171            y^2 + (2*x + 2)*y + (x^2 + 2*x + 1)
     1172            sage: sage_input(RR(pi) * polygen(RR), verify=True)
     1173            # Verified
     1174            R.<x> = RR[]
     1175            3.1415926535897931*x
     1176            sage: sage_input(polygen(GF(7)) + 12, verify=True)
     1177            # Verified
     1178            R.<x> = GF(7)[]
     1179            x + 5
     1180            sage: from sage.misc.sage_input import SageInputBuilder
     1181            sage: K(0)._sage_input_(SageInputBuilder(), True)
     1182            {atomic:0}
     1183            sage: (x^2 - 1)._sage_input_(SageInputBuilder(), False)
     1184            {binop:- {binop:** {gen:x {constr_parent: {subscr: {atomic:ZZ}[{atomic:'x'}]} with gens: ('x',)}} {atomic:2}} {atomic:1}}
     1185        """       
     1186        if self.degree() > 0:
     1187            gen = sib.gen(self.parent())
     1188            coeffs = self.list()
     1189            terms = []
     1190            for i in range(len(coeffs)-1, -1, -1):
     1191                if i > 0:
     1192                    if i > 1:
     1193                        gen_pow = gen**sib.int(i)
     1194                    else:
     1195                        gen_pow = gen
     1196                    terms.append(sib.prod((sib(coeffs[i], True), gen_pow), simplify=True))
     1197                else:
     1198                    terms.append(sib(coeffs[i], True))
     1199            return sib.sum(terms, simplify=True)
     1200        elif coerced:
     1201            return sib(self.constant_coefficient(), True)
     1202        else:
     1203            return sib(self.parent())(sib(self.constant_coefficient(), True))
    11391204       
    11401205    def __setitem__(self, n, value):
    11411206        """
  • sage/rings/polynomial/polynomial_ring.py

    diff -r f8b52491b393 -r fe6b1dd63297 sage/rings/polynomial/polynomial_ring.py
    a b  
    375375
    376376    def _gap_init_(self):
    377377        return 'PolynomialRing(%s, ["%s"])'%(self.base_ring()._gap_init_(), self.variable_name())
     378
     379    def _sage_input_(self, sib, coerced):
     380        r"""
     381        Produce an expression which will reproduce this value when evaluated.
     382
     383        EXAMPLES:
     384            sage: sage_input(GF(5)['x']['y'], verify=True)
     385            # Verified
     386            GF(5)['x']['y']
     387            sage: from sage.misc.sage_input import SageInputBuilder
     388            sage: ZZ['z']._sage_input_(SageInputBuilder(), False)
     389            {constr_parent: {subscr: {atomic:ZZ}[{atomic:'z'}]} with gens: ('z',)}
     390        """
     391        base = sib(self.base_ring())
     392        sie = base[self.variable_name()]
     393        gens_syntax = sib.empty_subscript(base)
     394        return sib.parent_with_gens(self, sie, self.variable_names(), 'R',
     395                                    gens_syntax=gens_syntax)
    378396
    379397    def _is_valid_homomorphism_(self, codomain, im_gens):
    380398        try:
  • sage/rings/real_mpfr.pyx

    diff -r f8b52491b393 -r fe6b1dd63297 sage/rings/real_mpfr.pyx
    a b  
    268268
    269269    def _latex_(self):
    270270        return "\\mathbf{R}"
     271
     272    def _sage_input_(self, sib, coerce):
     273        r"""
     274        Produce an expression which will reproduce this value when evaluated.
     275       
     276        EXAMPLES:
     277            sage: sage_input(RR, verify=True)
     278            # Verified
     279            RR
     280            sage: sage_input(RealField(25, rnd='RNDZ'), verify=True)
     281            # Verified
     282            RealField(25, rnd='RNDZ')
     283            sage: k = (RR, RealField(75, rnd='RNDU'), RealField(13))
     284            sage: sage_input(k, verify=True)
     285            # Verified
     286            (RR, RealField(75, rnd='RNDU'), RealField(13))
     287            sage: sage_input((k, k), verify=True)
     288            # Verified
     289            RR75u = RealField(75, rnd='RNDU')
     290            RR13 = RealField(13)
     291            ((RR, RR75u, RR13), (RR, RR75u, RR13))
     292            sage: from sage.misc.sage_input import SageInputBuilder
     293            sage: RealField(99, rnd='RNDD')._sage_input_(SageInputBuilder(), False)
     294            {call: {atomic:RealField}({atomic:99}, rnd={atomic:'RNDD'})}
     295        """
     296        if self.rnd == GMP_RNDN and self.prec() == 53:
     297            return sib.name('RR')
     298
     299        if self.rnd != GMP_RNDN:
     300            rnd_abbrev = self.rnd_str[-1:].lower()
     301            v = sib.name('RealField')(sib.int(self.prec()), rnd=self.rnd_str)
     302        else:
     303            rnd_abbrev = ''
     304            v = sib.name('RealField')(sib.int(self.prec()))
     305
     306        name = 'RR%d%s' % (self.prec(), rnd_abbrev)
     307        sib.cache(self, v, name)
     308        return v
    271309
    272310    def is_exact(self):
    273311        return False
     
    912950            True
    913951        """
    914952        return self.str(10, no_sci=True, truncate=False)
     953
     954    def _sage_input_(self, sib, coerced):
     955        r"""
     956        Produce an expression which will reproduce this value when evaluated.
     957       
     958        EXAMPLES:
     959            sage: for prec in (2, 53, 200):
     960            ...       for rnd_dir in ('RNDN', 'RNDD', 'RNDU', 'RNDZ'):
     961            ...           fld = RealField(prec, rnd=rnd_dir)
     962            ...           var = polygen(fld)
     963            ...           for v in [NaN, -infinity, -20, -e, 0, 1, 2^500, -2^4000, -2^-500, 2^-4000] + [fld.random_element() for _ in range(5)]:
     964            ...               for preparse in (True, False, None):
     965            ...                   _ = sage_input(fld(v), verify=True, preparse=preparse)
     966            ...                   _ = sage_input(fld(v) * var, verify=True, preparse=preparse)
     967            sage: from sage.misc.sage_input import SageInputBuilder
     968            sage: sib = SageInputBuilder()
     969            sage: sib_np = SageInputBuilder(preparse=False)
     970            sage: RR(-infinity)._sage_input_(sib, True)
     971            {unop:- {call: {atomic:RR}({atomic:Infinity})}}
     972            sage: RR(NaN)._sage_input_(sib, True)
     973            {call: {atomic:RR}({atomic:NaN})}
     974            sage: RR(12345)._sage_input_(sib, True)
     975            {atomic:12345}
     976            sage: RR(-12345)._sage_input_(sib, False)
     977            {unop:- {call: {atomic:RR}({atomic:12345})}}
     978            sage: RR(1.579)._sage_input_(sib, True)
     979            {atomic:1.5790000000000000}
     980            sage: RR(1.579)._sage_input_(sib_np, True)
     981            {atomic:1.5790000000000000}
     982            sage: RealField(150)(pi)._sage_input_(sib, True)
     983            {atomic:3.1415926535897932384626433832795028841971694008}
     984            sage: RealField(150)(pi)._sage_input_(sib_np, True)
     985            {call: {call: {atomic:RealField}({atomic:150})}({atomic:'3.1415926535897932384626433832795028841971694008'})}
     986        """
     987        # We have a bewildering array of conditions to deal with:
     988        # 1) number, or NaN or infinity
     989        # 2) rounding direction: up, down, or nearest
     990        # 3) preparser enabled: yes, no, or maybe
     991        # 4) is this number equal to some Python float: yes or no
     992        # 5) coerced
     993
     994        # First, handle NaN and infinity
     995        if not mpfr_number_p(self.value):
     996            if mpfr_inf_p(self.value):
     997                v = sib.name('Infinity')
     998            else:
     999                v = sib.name('NaN')
     1000            v = sib(self._parent)(v)
     1001            if mpfr_sgn(self.value) < 0:
     1002                v = -v
     1003            return v
     1004               
     1005        from sage.rings.integer_ring import ZZ
     1006
     1007        cdef mpfr_rnd_t rnd = (<RealField>self._parent).rnd
     1008
     1009        cdef bint negative = mpfr_sgn(self.value) < 0
     1010        if negative:
     1011            self = -self
     1012
     1013        # There are five possibilities for printing this floating-point
     1014        # number, ordered from prettiest to ugliest (IMHO).
     1015        # 1) An integer: 42
     1016        # 2) A simple literal: 3.14159
     1017        # 3) A coerced integer: RR(42)
     1018        # 4) A coerced literal: RR(3.14159)
     1019        # 5) A coerced string literal: RR('3.14159')
     1020
     1021        # To use choice 1 or choice 3, this number must be an integer.
     1022        cdef bint can_use_int_literal = \
     1023            self.abs() < (Integer(1) << self.prec()) and self in ZZ
     1024
     1025        # To use choice 2 or choice 4, we must be able to read
     1026        # numbers of this precision as a literal.  We support this
     1027        # only for the default rounding mode; "pretty" output for
     1028        # other rounding modes is a lot of work for very little gain
     1029        # (since other rounding modes are very rarely used).
     1030        # (One problem is that we don't know whether it will be the
     1031        # positive or negative value that will be coerced into the
     1032        # desired parent; for example, this differs between "x^2 - 1.3*x"
     1033        # and "-1.3*x".)
     1034        cdef bint can_use_float_literal = \
     1035            rnd == GMP_RNDN and (sib.preparse() or
     1036                                 float(str(float(self))) == self)
     1037
     1038        if can_use_int_literal or can_use_float_literal:
     1039            if can_use_int_literal:
     1040                v = sib.int(self._integer_())
     1041            else:
     1042                s = self.str(truncate=False)
     1043                v = sib.float_str(s)
     1044            if not coerced:
     1045                v = sib(self.parent())(v)
     1046        else:
     1047            if rnd == GMP_RNDN:
     1048                s = self.str(truncate=False)
     1049            else:
     1050                # This is tricky.  str() uses mpfr_get_str() with
     1051                # reqdigits=0; this guarantees to give enough digits
     1052                # to recreate the input, if we print and read with
     1053                # round-to-nearest.  However, we are not going to
     1054                # read with round-to-nearest, so we might need more digits.
     1055                # If we're going to read with round-down, then we need
     1056                # to print with round-up; and we'll use one more bit
     1057                # to make sure we have enough digits.
     1058                # Since we always read nonnegative numbers, reading with
     1059                # RNDZ is the same as reading with RNDD.
     1060                if rnd == GMP_RNDD or rnd == GMP_RNDZ:
     1061                    fld = RealField(self.prec() + 1, rnd='RNDU')
     1062                else:
     1063                    fld = RealField(self.prec() + 1, rnd='RNDD')
     1064                s = fld(self).str(truncate=False)
     1065            v = sib(self.parent())(sib.float_str(repr(s)))
     1066
     1067        if negative:
     1068            v = -v
     1069
     1070        return v           
    9151071
    9161072    def __hash__(self):
    9171073        """
  • sage/rings/ring.pyx

    diff -r f8b52491b393 -r fe6b1dd63297 sage/rings/ring.pyx
    a b  
    15051505        p = self.polynomial()
    15061506        return "ext< %s | %s >"%(B._magma_init_(),p._magma_init_())
    15071507   
     1508    def _sage_input_(self, sib, coerced):
     1509        r"""
     1510        Produce an expression which will reproduce this value when evaluated.
     1511       
     1512        EXAMPLES:
     1513            sage: sage_input(GF(5), verify=True)
     1514            # Verified
     1515            GF(5)
     1516            sage: sage_input(GF(32, 'a'), verify=True)
     1517            # Verified
     1518            R.<x> = GF(2)[]
     1519            GF(2^5, 'a', x^5 + x^2 + 1)
     1520            sage: K = GF(125, 'b')
     1521            sage: sage_input((K, K), verify=True)
     1522            # Verified
     1523            R.<x> = GF(5)[]
     1524            GF_5_3 = GF(5^3, 'b', x^3 + 3*x + 3)
     1525            (GF_5_3, GF_5_3)
     1526            sage: from sage.misc.sage_input import SageInputBuilder
     1527            sage: GF(81, 'a')._sage_input_(SageInputBuilder(), False)
     1528            {call: {atomic:GF}({binop:** {atomic:3} {atomic:4}}, {atomic:'a'}, {binop:+ {binop:+ {binop:** {gen:x {constr_parent: {subscr: {call: {atomic:GF}({atomic:3})}[{atomic:'x'}]} with gens: ('x',)}} {atomic:4}} {binop:* {atomic:2} {binop:** {gen:x {constr_parent: {subscr: {call: {atomic:GF}({atomic:3})}[{atomic:'x'}]} with gens: ('x',)}} {atomic:3}}}} {atomic:2}})}
     1529        """
     1530        if self.degree() == 1:
     1531            v = sib.name('GF')(sib.int(self.characteristic()))
     1532            name = 'GF_%d' % self.characteristic()
     1533        else:
     1534            v = sib.name('GF')(sib.int(self.characteristic()) ** sib.int(self.degree()),
     1535                               self.variable_name(),
     1536                               self.modulus())
     1537            name = 'GF_%d_%d' % (self.characteristic(), self.degree())
     1538        sib.cache(self, v, name)
     1539        return v
     1540
    15081541    cdef int _cmp_c_impl(left, Parent right) except -2:
    15091542        """
    15101543        Compares this finite field with other.