.. Copyright 2011, 2012 David Malcolm <dmalcolm@redhat.com>
   Copyright 2011, 2012 Red Hat, Inc.

   This is free software: you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see
   <http://www.gnu.org/licenses/>.

gcc.Tree and its subclasses
===========================

The various language front-ends for GCC emit "tree" structures (which I believe
are actually graphs), used throughout the rest of the internal representation of
the code passing through GCC.

.. py:class:: gcc.Tree

   A ``gcc.Tree`` is a wrapper around GCC's `tree` type

   .. py:method:: debug()

      Dump the tree to stderr, using GCC's own diagnostic routines

   .. py:attribute:: type

      Instance of :py:class:`gcc.Tree` giving the type of the node

   .. py:attribute:: addr

     (long) The address of the underlying GCC object in memory

   The __str__ method is implemented using GCC's own pretty-printer for trees,
   so e.g.::

      str(t)

   might return::

      'int <T531> (int, char * *)'

   for a `gcc.FunctionDecl`

   .. py:attribute:: str_no_uid

      A string representation of this object, like str(), but without
      including any internal UIDs.

      This is intended for use in selftests that compare output against some
      expected value, to avoid embedding values that change into the expected
      output.

      For example, given the type declaration above, where `str(t)` might
      return::

         'int <T531> (int, char * *)'

      where the UID "531" is liable to change from compile to compile, whereas
      `t.str_no_uid` has value::

         'int <Txxx> (int, char * *)'

      which won't arbitrarily change each time.

There are numerous subclasses of :py:class:`gcc.Tree`, some with numerous
subclasses of their own.  Some important parts of the class hierarchy include:

==================================   =======================================
Subclass                             Meaning
==================================   =======================================
:py:class:`gcc.Binary`               A binary arithmetic expression, with
                                     numerous subclasses
:py:class:`gcc.Block`                A symbol-binding block
:py:class:`gcc.Comparison`           A relational operators (with various
                                     subclasses)
:py:class:`gcc.Constant`             Subclasses for constants
:py:class:`gcc.Constructor`          An aggregate value (e.g. in C, a
                                     structure or array initializer)
:py:class:`gcc.Declaration`          Subclasses relating to declarations
                                     (variables, functions, etc)
:py:class:`gcc.Expression`           Subclasses relating to expressions
:py:class:`gcc.IdentifierNode`       A name
:py:class:`gcc.Reference`            Subclasses for relating to reference to
                                     storage (e.g. pointer values)
:py:class:`gcc.SsaName`              A variable reference for SSA analysis
:py:class:`gcc.Statement`            Subclasses for statement expressions,
                                     which have side-effects
:py:class:`gcc.Type`                 Subclasses for describing the types of
                                     variables
:py:class:`gcc.Unary`                Subclasses for unary arithmetic
                                     expressions
==================================   =======================================

.. note::

   Each subclass of :py:class:`gcc.Tree` is typically named
   after either one of the `enum tree_code_class` or `enum tree_code` values,
   with the names converted to Camel Case:

   For example a :py:class:`gcc.Binary` is a wrapper around a `tree` of type
   `tcc_binary`, and  a :py:class:`gcc.PlusExpr` is a wrapper around a `tree`
   of type `PLUS_EXPR`.

   As of this writing, only a small subset of the various fields of the different
   subclasses have been wrapped yet, but it's generally easy to add new ones.  To
   add new fields, I've found it easiest to look at `gcc/tree.h` and
   `gcc/print-tree.c` within the GCC source tree and use the `print_node` function
   to figure out what the valid fields are.  With that information, you should
   then look at `generate-tree-c.py`, which is the code that generates the Python
   wrapper classes (it's used when building the plugin to create
   `autogenerated-tree.c`).  Ideally when exposing a field to Python you should
   also add it to the API documentation, and add a test case.

.. py:function:: gccutils.pformat(tree)

   This function attempts to generate a debug dump of a :py:class:`gcc.Tree`
   and all of its "interesting" attributes, recursively.  It's loosely modelled
   on Python's `pprint` module and GCC's own `debug_tree` diagnostic routine
   using indentation to try to show the structure.

   It returns a string.

   It differs from :py:meth:`gcc.Tree.debug()` in that it shows the Python
   wrapper objects, rather than the underlying GCC data structures
   themselves.  For example, it can't show attributes that haven't been
   wrapped yet.

   Objects that have already been reported within this call are abbreviated
   to "..." to try to keep the output readable.

   Example output::

      <FunctionDecl
        repr() = gcc.FunctionDecl('main')
        superclasses = (<type 'gcc.Declaration'>, <type 'gcc.Tree'>)
        .function = gcc.Function('main')
        .location = /home/david/coding/gcc-python/test.c:15
        .name = 'main'
        .type = <FunctionType
                  repr() = <gcc.FunctionType object at 0x2f62a60>
                  str() = 'int <T531> (int, char * *)'
                  superclasses = (<type 'gcc.Type'>, <type 'gcc.Tree'>)
                  .name = None
                  .type = <IntegerType
                            repr() = <gcc.IntegerType object at 0x2f629d0>
                            str() = 'int'
                            superclasses = (<type 'gcc.Type'>, <type 'gcc.Tree'>)
                            .const = False
                            .name = <TypeDecl
                                      repr() = gcc.TypeDecl('int')
                                      superclasses = (<type 'gcc.Declaration'>, <type 'gcc.Tree'>)
                                      .location = None
                                      .name = 'int'
                                      .pointer = <PointerType
                                                   repr() = <gcc.PointerType object at 0x2f62b80>
                                                   str() = ' *'
                                                   superclasses = (<type 'gcc.Type'>, <type 'gcc.Tree'>)
                                                   .dereference = ... ("gcc.TypeDecl('int')")
                                                   .name = None
                                                   .type = ... ("gcc.TypeDecl('int')")
                                                 >
                                      .type = ... ('<gcc.IntegerType object at 0x2f629d0>')
                                    >
                            .precision = 32
                            .restrict = False
                            .type = None
                            .unsigned = False
                            .volatile = False
                          >
                >
      >

.. py:function:: gccutils.pprint(tree)

   Similar to :py:meth:`gccutils.pformat()`, but prints the output to stdout.

   (should this be stderr instead? probably should take a stream as an arg, but
   what should the default be?)


Blocks
------

.. py:class:: gcc.Block

   A symbol binding block, such as the global symbols within a compilation unit.

   .. py:attribute:: vars

      The list of :py:class:`gcc.Tree` for the declarations and labels in this
      block

Declarations
------------

.. py:class:: gcc.Declaration

   A subclass of :py:class:`gcc.Tree` indicating a declaration

   Corresponds to the `tcc_declaration` value of `enum tree_code_class` within
   GCC's own C sources.

   .. py:attribute:: name

      (string) the name of this declaration


   .. py:attribute:: location

      The :py:class:`gcc.Location` for this declaration

   .. py:attribute:: is_artificial

      (bool) Is this declaration a compiler-generated entity, rather than
      one provided by the user?

      An example of such an "artificial" declaration occurs within the
      arguments of C++ methods: the initial `this` argument is a
      compiler-generated :py:class:`gcc.ParmDecl`.

   .. py:attribute:: is_builtin

      (bool) Is this declaration a compiler-builtin?

.. py:class:: gcc.FieldDecl

   A subclass of :py:class:`gcc.Declaration` indicating the declaration of a
   field within a structure.

   .. py:attribute:: name

      (string) The name of this field


.. py:class:: gcc.FunctionDecl

   A subclass of :py:class:`gcc.Declaration` indicating the declaration of a
   function.   Internally, this wraps a `(struct tree_function_decl *)`

   .. py:attribute:: function

      The :py:class:`gcc.Function` for this declaration

   .. py:attribute:: arguments

      List of :py:class:`gcc.ParmDecl` representing the arguments of this
      function

   .. py:attribute:: result

      The :py:class:`gcc.ResultDecl` representing the return value of this
      function

   .. py:attribute:: fullname

      .. note:: This attribute is only usable with C++ code.  Attempting to use
         it from another language will lead to a `RuntimeError` exception.

      (string) The "full name" of this function, including the scope, return
      type and default arguments.

      For example, given this code:

      .. code-block:: c++

         namespace Example {
             struct Coord {
                 int x;
                 int y;
             };

             class Widget {
             public:
                 void set_location(const struct Coord& coord);
             };
         };

      `set_location`'s fullname is::

         'void Example::Widget::set_location(const Example::Coord&)'

   .. py:attribute:: callgraph_node

      The :py:class:`gcc.CallgraphNode` for this function declaration, or
      `None`

   .. py:attribute:: is_public

      (bool) For C++: is this declaration "public"

   .. py:attribute:: is_private

      (bool) For C++: is this declaration "private"

   .. py:attribute:: is_protected

      (bool) For C++: is this declaration "protected"

   .. py:attribute:: is_static

      (bool) For C++: is this declaration "static"

.. py:class:: gcc.ParmDecl

   A subclass of :py:class:`gcc.Declaration` indicating the declaration of a
   parameter to a function or method.

.. py:class:: gcc.ResultDecl

   A subclass of :py:class:`gcc.Declaration` declararing a dummy variable that
   will hold the return value from a function.

.. py:class:: gcc.VarDecl

   A subclass of :py:class:`gcc.Declaration` indicating the declaration of a
   variable (e.g. a global or a local).

   .. py:attribute:: initial

      The initial value for this variable as a :py:class:`gcc.Constructor`,
      or None

   .. py:attribute:: static

      (boolean) Is this variable to be allocated with static storage?

.. py:class:: gcc.NamespaceDecl

   A subclass of :py:class:`gcc.Declaration` representing a C++ namespace

   .. py:attribute:: alias_of

      The :py:class:`gcc.NamespaceDecl` which this namespace is an alias of
      or None if this namespace is not an alias.

   .. py:attribute:: declarations

      .. note:: This attribute is only usable with non-alias namespaces.
                Accessing it on an alias will lead to a RuntimeError exception.

      List of :py:class:`gcc.Declaration` objects in this namespace.
      This attribute is only valid for non-aliases

   .. py:attribute:: namespaces

      .. note:: This attribute is only usable with non-alias namespaces.
                Accessing it on an alias will lead to a RuntimeError exception.

      List of :py:class:`gcc.NamespaceDecl` objects nested in this namespace.
      This attribute is only valid for non-aliases

   .. py:method:: lookup(name)

      Locate the given name within the namespace, returning a
      :py:class:`gcc.Tree` or `None`

   .. py:method:: unalias()

      Always returns a :py:class:`gcc.NamespaceDecl` object which is not an alias.
      Returns self if this namespace is not an alias.


  ..        Declaration
  ..            ClassMethodDecl
  ..            ConstDecl
  ..            DebugExprDecl
  ..            FieldDecl
  ..            FunctionDecl
  ..            ImportedDecl
  ..            InstanceMethodDecl
  ..            KeywordDecl
  ..            LabelDecl
  ..            NamespaceDecl
  ..            ParmDecl
  ..            PropertyDecl
  ..            ResultDecl
  ..            TemplateDecl
  ..            TranslationUnitDecl
  ..            TypeDecl
  ..            UsingDecl
  ..            VarDecl


Types
-----

.. py:class:: gcc.Type

   A subclass of `gcc.Tree` indicating a type

   Corresponds to the `tcc_type` value of `enum tree_code_class` within
   GCC's own C sources.

   .. py:attribute:: name

      The :py:class:`gcc.IdentifierNode` for the name of the type, or `None`.

   .. py:attribute:: pointer

      The :py:class:`gcc.PointerType` representing the `(this_type *)` type

   .. py:attribute:: attributes

      The user-defined attributes on this type (using GCC's `__attribute`
      syntax), as a dictionary (mapping from attribute names to list of
      values).  Typically this will be the empty dictionary.

   .. py:attribute:: sizeof

      `sizeof()` this type, as an `int`, or raising `TypeError` for those
      types which don't have a well-defined size

      .. note:: This attribute is not usable from within `lto1`; attempting
         to use it there will lead to a `RuntimeError` exception.

Additional attributes for various :py:class:`gcc.Type` subclasses:

   .. py:attribute:: const

      (Boolean) Does this type have the `const` modifier?

   .. py:attribute:: const_equivalent

      The :py:class:`gcc.Type` for the `const` version of this type

   .. py:attribute:: volatile

      (Boolean) Does this type have the `volatile` modifier?

   .. py:attribute:: volatile_equivalent

      The :py:class:`gcc.Type` for the `volatile` version of this type

   .. py:attribute:: restrict

      (Boolean) Does this type have the `restrict` modifier?

   .. py:attribute:: restrict_equivalent

      The :py:class:`gcc.Type` for the `restrict` version of this type

   .. py:attribute:: unqualified_equivalent

      The :py:class:`gcc.Type` for the version of this type that does
      not have any qualifiers.


   The standard C types are accessible via class methods of :py:class:`gcc.Type`.
   They are only created by GCC after plugins are loaded, and so they're
   only visible during callbacks, not during the initial run of the code.
   (yes, having them as class methods is slightly clumsy).

   Each of the following returns a :py:class:`gcc.Type` instance representing
   the given type (or None at startup before any passes, when the types don't
   yet exist)

      =============================  =====================
      Class method                   C Type
      =============================  =====================
      gcc.Type.void()                `void`
      gcc.Type.size_t()              `size_t`
      gcc.Type.char()                `char`
      gcc.Type.signed_char()         `signed char`
      gcc.Type.unsigned_char()       `unsigned char`
      gcc.Type.double()              `double`
      gcc.Type.float()               `float`
      gcc.Type.short()               `short`
      gcc.Type.unsigned_short()      `unsigned short`
      gcc.Type.int()                 `int`
      gcc.Type.unsigned_int()        `unsigned int`
      gcc.Type.long()                `long`
      gcc.Type.unsigned_long()       `unsigned long`
      gcc.Type.long_double()         `long double`
      gcc.Type.long_long()           `long long`
      gcc.Type.unsigned_long_long()  `unsigned long long`
      gcc.Type.int128()              `int128`
      gcc.Type.unsigned_int128()     `unsigned int128`
      gcc.Type.uint32()              `uint32`
      gcc.Type.uint64()              `uint64`
      =============================  =====================

.. py:class:: gcc.IntegerType

   Subclass of :py:class:`gcc.Type`, adding a few properties:

   .. py:attribute:: unsigned

      (Boolean) True for 'unsigned', False for 'signed'

   .. py:attribute:: precision

      (int) The precision of this type in bits, as an int (e.g. 32)

   .. py:attribute:: signed_equivalent

      The gcc.IntegerType for the signed version of this type

      .. note:: This attribute is not usable from within `lto1`; attempting
         to use it there will lead to a `RuntimeError` exception.

   .. py:attribute:: unsigned_equivalent

      The gcc.IntegerType for the unsigned version of this type

      .. note:: This attribute is not usable from within `lto1`; attempting
         to use it there will lead to a `RuntimeError` exception.

   .. py:attribute:: max_value

      The maximum possible value for this type, as a
      :py:class:`gcc.IntegerCst`

   .. py:attribute:: min_value

      The minimum possible value for this type, as a
      :py:class:`gcc.IntegerCst`

.. py:class:: gcc.FloatType

   Subclass of :py:class:`gcc.Type` representing C's `float` and `double` types

   .. py:attribute:: precision

      (int) The precision of this type in bits (32 for `float`; 64 for
      `double`)

.. py:class:: gcc.PointerType

   Subclass of :py:class:`gcc.Type` representing a pointer type, such as
   an `int *`

   .. py:attribute:: dereference

      The :py:class:`gcc.Type` that this type points to.  In the above
      example (`int *`), this would be the `int` type.

.. py:class:: gcc.EnumeralType

   Subclass of :py:class:`gcc.Type` representing an enumeral type.

   .. py:attribute:: values

      A list of tuple representing the constants defined in this
      enumeration.  Each tuple consists of two elements; the first
      being the name of the constant, a :py:class:`gcc.IdentifierNode`;
      and the second being the value, a :py:class:`gcc.Constant`.

.. py:class:: gcc.ArrayType

   Subclass of :py:class:`gcc.Type` representing an array type.  For example,
   in a C declaration such as::

      char buf[16]

   we have a :py:class:`gcc.VarDecl` for `buf`, and its type is an instance of
   :py:class:`gcc.ArrayType`, representing `char [16]`.

   .. py:attribute:: dereference

      The :py:class:`gcc.Type` that this type points to.  In the above
      example, this would be the `char` type.

   .. py:attribute:: range

      The :py:class:`gcc.Type` that represents the range of the
      array's indices.  If the array has a known range, then this will
      ordinarily be an :py:class:`gcc.IntegerType` whose `min_value`
      and `max_value` are the (inclusive) bounds of the array.  If the
      array does not have a known range, then this attribute will be
      `None`.

      That is, in the example above, `range.min_val` is `0`, and
      `range.max_val` is `15`.

      But, for a C declaration like::

         extern char array[];

      the type's `range` would be `None`.

.. py:class:: gcc.VectorType

   .. py:attribute:: dereference

      The :py:class:`gcc.Type` that this type points to

.. py:class:: gcc.FunctionType

   Subclass of :py:class:`gcc.Type` representing the type of a given function
   (or or a typedef to a function type, e.g. for callbacks).

   See also :py:class:`gcc.FunctionType`

   The `type` attribute holds the return type.

   .. py:attribute:: is_variadic

      True if this type represents a variadic function.  Note that for
      a variadic function, the final `...` argument is not explicitly
      represented in `argument_types`.

   .. py:attribute:: argument_types

      A tuple of :py:class:`gcc.Type` instances, representing the function's
      argument types

   .. py:function:: gccutils.get_nonnull_arguments(funtype)

      This is a utility function for working with the `"nonnull"` custom
      attribute on function types:

      http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html

      Return a `frozenset` of 0-based integers, giving the arguments for
      which we can assume "nonnull-ness", handling the various cases of:

          * the attribute isn't present (returning the empty frozenset)

          * the attribute is present, without args (all pointer args are
            non-NULL)

          * the attribute is present, with a list of 1-based argument indices
            (Note that the result is still 0-based)

.. py:class:: gcc.MethodType

   Subclass of :py:class:`gcc.Type` representing the type of a given method.
   Similar to :py:class:`gcc.FunctionType`

   The `type` attribute holds the return type.

   .. py:attribute:: argument_types

      A tuple of :py:class:`gcc.Type` instances, representing the function's
      argument types

.. py:class:: gcc.RecordType

   A compound type, such as a C `struct`

   .. py:attribute:: fields

      The fields of this type, as a list of :py:class:`gcc.FieldDecl` instances

   .. py:attribute:: methods

      The methods of this type, as a list of :py:class:`gcc.MethodType` instances

   You can look up C structures by looking within the top-level
   :py:class:`gcc.Block` within the current translation unit.  For example,
   given this sample C code:

    .. literalinclude:: ../tests/examples/c/struct/input.c
      :lines: 20-30
      :language: c

  then the following Python code:

    .. literalinclude:: ../tests/examples/c/struct/script.py
      :lines: 21-40

  will generate this output:

    .. literalinclude:: ../tests/examples/c/struct/stdout.txt

Constants
---------

.. py:class:: gcc.Constant

   Subclass of :py:class:`gcc.Tree` indicating a constant value.

   Corresponds to the `tcc_constant` value of `enum tree_code_class` within
   GCC's own C sources.

   .. py:attribute:: constant

      The actual value of this constant, as the appropriate Python type:

      ==============================  ===============
      Subclass                        Python type
      ==============================  ===============
      .. py:class:: ComplexCst
      .. py:class:: FixedCst
      .. py:class:: IntegerCst        `int` or `long`
      .. py:class:: PtrmemCst
      .. py:class:: RealCst           `float`
      .. py:class:: StringCst         `str`
      .. py:class:: VectorCst
      ==============================  ===============


Binary Expressions
------------------

.. py:class:: gcc.Binary

   Subclass of :py:class:`gcc.Tree` indicating a binary expression.

   Corresponds to the `tcc_binary` value of `enum tree_code_class` within
   GCC's own C sources.

   .. py:attribute:: location

      The :py:class:`gcc.Location` for this binary expression

   .. py:classmethod:: get_symbol()

      Get the symbol used in debug dumps for this :py:class:`gcc.Binary`
      subclass, if any, as a `str`.  A table showing these strings can be
      seen :ref:`here <get_symbols>`.

   Has subclasses for the various kinds of binary expression.  These
   include:

   .. These tables correspond to GCC's "tree.def"

   Simple arithmetic:

      ============================    ======================  ==============
      Subclass                        C/C++ operators         enum tree_code
      ============================    ======================  ==============
      .. py:class:: gcc.PlusExpr      `+`                     PLUS_EXPR
      .. py:class:: gcc.MinusExpr     `-`                     MINUS_EXPR
      .. py:class:: gcc.MultExpr      `*`                     MULT_EXPR
      ============================    ======================  ==============

   Pointer addition:

      =================================    =================  =================
      Subclass                             C/C++ operators    enum tree_code
      =================================    =================  =================
      .. py:class:: gcc.PointerPlusExpr                       POINTER_PLUS_EXPR
      =================================    =================  =================

   Various division operations:

      ==============================  ===============
      Subclass                        C/C++ operators
      ==============================  ===============
      .. py:class:: gcc.TruncDivExr
      .. py:class:: gcc.CeilDivExpr
      .. py:class:: gcc.FloorDivExpr
      .. py:class:: gcc.RoundDivExpr
      ==============================  ===============

   The remainder counterparts of the above division operators:

      ==============================  ===============
      Subclass                        C/C++ operators
      ==============================  ===============
      .. py:class:: gcc.TruncModExpr
      .. py:class:: gcc.CeilModExpr
      .. py:class:: gcc.FloorModExpr
      .. py:class:: gcc.RoundModExpr
      ==============================  ===============

   Division for reals:

      ===================================  ======================
      Subclass                             C/C++ operators
      ===================================  ======================
      .. py:class:: gcc.RdivExpr
      ===================================  ======================

   Division that does not need rounding (e.g. for pointer subtraction in C):

      ===================================  ======================
      Subclass                             C/C++ operators
      ===================================  ======================
      .. py:class:: gcc.ExactDivExpr
      ===================================  ======================

   Max and min:

      ===================================  ======================
      Subclass                             C/C++ operators
      ===================================  ======================
      .. py:class:: gcc.MaxExpr
      .. py:class:: gcc.MinExpr
      ===================================  ======================

    Shift and rotate operations:

      ===================================  ======================
      Subclass                             C/C++ operators
      ===================================  ======================
      .. py:class:: gcc.LrotateExpr
      .. py:class:: gcc.LshiftExpr         `<<`, `<<=`
      .. py:class:: gcc.RrotateExpr
      .. py:class:: gcc.RshiftExpr         `>>`, `>>=`
      ===================================  ======================

   Bitwise binary expressions:

      ===================================  =========================
      Subclass                             C/C++ operators
      ===================================  =========================
      .. py:class:: gcc.BitAndExpr         `&`, `&=` (bitwise "and")
      .. py:class:: gcc.BitIorExpr         `|`, `|=` (bitwise "or")
      .. py:class:: gcc.BitXorExpr         `^`, `^=` (bitwise "xor")
      ===================================  =========================

  Other gcc.Binary subclasses:

      ========================================  ==================================
      Subclass                                  Usage
      ========================================  ==================================
      .. py:class:: gcc.CompareExpr
      .. py:class:: gcc.CompareGExpr
      .. py:class:: gcc.CompareLExpr
      .. py:class:: gcc.ComplexExpr
      .. py:class:: gcc.MinusNomodExpr
      .. py:class:: gcc.PlusNomodExpr
      .. py:class:: gcc.RangeExpr
      .. py:class:: gcc.UrshiftExpr
      .. py:class:: gcc.VecExtractevenExpr
      .. py:class:: gcc.VecExtractoddExpr
      .. py:class:: gcc.VecInterleavehighExpr
      .. py:class:: gcc.VecInterleavelowExpr
      .. py:class:: gcc.VecLshiftExpr
      .. py:class:: gcc.VecPackFixTruncExpr
      .. py:class:: gcc.VecPackSatExpr
      .. py:class:: gcc.VecPackTruncExpr
      .. py:class:: gcc.VecRshiftExpr
      .. py:class:: gcc.WidenMultExpr
      .. py:class:: gcc.WidenMultHiExpr
      .. py:class:: gcc.WidenMultLoExpr
      .. py:class:: gcc.WidenSumExpr
      ========================================  ==================================
 

Unary Expressions
-----------------


.. py:class:: gcc.Unary

   Subclass of :py:class:`gcc.Tree` indicating a unary expression (i.e. taking a
   single argument).

   Corresponds to the `tcc_unary` value of `enum tree_code_class` within
   GCC's own C sources.

   .. py:attribute:: operand

      The operand of this operator, as a :py:class:`gcc.Tree`.

   .. py:attribute:: location

      The :py:class:`gcc.Location` for this unary expression

   .. py:classmethod:: get_symbol()

      Get the symbol used in debug dumps for this :py:class:`gcc.Unary`
      subclass, if any, as a `str`.  A table showing these strings can be
      seen :ref:`here <get_symbols>`.

   Subclasses include:

      ======================================  ==================================================
      Subclass                                Meaning; C/C++ operators
      ======================================  ==================================================
      .. py:class:: gcc.AbsExpr               Absolute value
      .. py:class:: gcc.AddrSpaceConvertExpr  Conversion of pointers between address spaces
      .. py:class:: gcc.BitNotExpr            `~` (bitwise "not")
      .. py:class:: gcc.CastExpr
      .. py:class:: gcc.ConjExpr              For complex types: complex conjugate
      .. py:class:: gcc.ConstCastExpr
      .. py:class:: gcc.ConvertExpr
      .. py:class:: gcc.DynamicCastExpr
      .. py:class:: gcc.FixTruncExpr          Convert real to fixed-point, via truncation
      .. py:class:: gcc.FixedConvertExpr
      .. py:class:: gcc.FloatExpr             Convert integer to real
      .. py:class:: gcc.NegateExpr            Unary negation
      .. py:class:: gcc.NoexceptExpr
      .. py:class:: gcc.NonLvalueExpr
      .. py:class:: gcc.NopExpr
      .. py:class:: gcc.ParenExpr
      .. py:class:: gcc.ReducMaxExpr
      .. py:class:: gcc.ReducMinExpr
      .. py:class:: gcc.ReducPlusExpr
      .. py:class:: gcc.ReinterpretCastExpr
      .. py:class:: gcc.StaticCastExpr
      .. py:class:: gcc.UnaryPlusExpr
      ======================================  ==================================================


Comparisons
------------

.. py:class:: gcc.Comparison

   Subclass of :py:class:`gcc.Tree` for comparison expressions

   Corresponds to the `tcc_comparison` value of `enum tree_code_class` within
   GCC's own C sources.

   .. py:attribute:: location

      The :py:class:`gcc.Location` for this comparison

   .. py:classmethod:: get_symbol()

      Get the symbol used in debug dumps for this :py:class:`gcc.Comparison`
      subclass, if any, as a `str`.  A table showing these strings can be
      seen :ref:`here <get_symbols>`.

   Subclasses include:

      =====================================  ======================
      Subclass                               C/C++ operators
      =====================================  ======================
      .. py:class:: EqExpr                   `==`
      .. py:class:: GeExpr                   `>=`
      .. py:class:: GtExpr                   `>`
      .. py:class:: LeExpr                   `<=`
      .. py:class:: LtExpr                   `<`
      .. py:class:: LtgtExpr
      .. py:class:: NeExpr                   `!=`
      .. py:class:: OrderedExpr
      .. py:class:: UneqExpr
      .. py:class:: UngeExpr
      .. py:class:: UngtExpr
      .. py:class:: UnleExpr
      .. py:class:: UnltExpr
      .. py:class:: UnorderedExpr
      =====================================  ======================


References to storage
---------------------

.. py:class:: gcc.Reference

   Subclass of :py:class:`gcc.Tree` for expressions involving a reference to
   storage.

   Corresponds to the `tcc_reference` value of `enum tree_code_class` within
   GCC's own C sources.

   .. py:attribute:: location

      The :py:class:`gcc.Location` for this storage reference

   .. py:classmethod:: get_symbol()

      Get the symbol used in debug dumps for this :py:class:`gcc.Reference`
      subclass, if any, as a `str`.  A table showing these strings can be
      seen :ref:`here <get_symbols>`.

.. py:class:: gcc.ArrayRef

   A subclass of :py:class:`gcc.Reference` for expressions involving an array
   reference:

   .. code-block:: c

      unsigned char buffer[4096];
      ...
      /* The left-hand side of this gcc.GimpleAssign is a gcc.ArrayRef: */
      buffer[42] = 0xff;

   .. py:attribute:: array

      The :py:class:`gcc.Tree` for the array within the reference
      (`gcc.VarDecl('buffer')` in the example above)

   .. py:attribute:: index

      The :py:class:`gcc.Tree` for the index within the reference
      (`gcc.IntegerCst(42)` in the example above)

.. py:class:: gcc.ComponentRef

   A subclass of :py:class:`gcc.Reference` for expressions involving a field
   lookup.

   This can mean either a direct field lookup, as in:

   .. code-block:: c

      struct mystruct s;
      ...
      s.idx = 42;

   or dereferenced field lookup:

   .. code-block:: c

      struct mystruct *p;
      ...
      p->idx = 42;

   .. py:attribute:: target

      The :py:class:`gcc.Tree` for the container of the field (either `s` or
      `*p` in the examples above)

   .. py:attribute:: field

      The :py:class:`gcc.FieldDecl` for the field within the target.

.. py:class:: gcc.MemRef

   A subclass of :py:class:`gcc.Reference` for expressions involving
   dereferencing a pointer:

   .. code-block:: c

      int p, *q;
      ...
      p = *q;

   .. py:attribute:: operand

      The :py:class:`gcc.Tree` for the expression describing the target of the
      pointer

Other subclasses of :py:class:`gcc.Reference` include:

      =====================================  ======================
      Subclass                               C/C++ operators
      =====================================  ======================
      .. py:class:: ArrayRangeRef
      .. py:class:: AttrAddrExpr
      .. py:class:: BitFieldRef
      .. py:class:: ImagpartExpr
      .. py:class:: IndirectRef
      .. py:class:: MemberRef
      .. py:class:: OffsetRef
      .. py:class:: RealpartExpr
      .. py:class:: ScopeRef
      .. py:class:: TargetMemRef
      .. py:class:: UnconstrainedArrayRef
      .. py:class:: ViewConvertExpr
      =====================================  ======================


Other expression subclasses
---------------------------

.. py:class:: gcc.Expression

   Subclass of :py:class:`gcc.Tree` indicating an expression that doesn't fit
   into the other categories.

   Corresponds to the `tcc_expression` value of `enum tree_code_class` within
   GCC's own C sources.

   .. py:attribute:: location

      The :py:class:`gcc.Location` for this expression

   .. py:classmethod:: get_symbol()

      Get the symbol used in debug dumps for this :py:class:`gcc.Expression`
      subclass, if any, as a `str`.  A table showing these strings can be
      seen :ref:`here <get_symbols>`.

   Subclasses include:

      =====================================  ======================
      Subclass                               C/C++ operators
      =====================================  ======================
      .. py:class:: gcc.AddrExpr
      .. py:class:: gcc.AlignofExpr
      .. py:class:: gcc.ArrowExpr
      .. py:class:: gcc.AssertExpr
      .. py:class:: gcc.AtEncodeExpr
      .. py:class:: gcc.BindExpr
      .. py:class:: gcc.CMaybeConstExpr
      .. py:class:: gcc.ClassReferenceExpr
      .. py:class:: gcc.CleanupPointExpr
      .. py:class:: gcc.CompoundExpr
      .. py:class:: gcc.CompoundLiteralExpr
      .. py:class:: gcc.CondExpr
      .. py:class:: gcc.CtorInitializer
      .. py:class:: gcc.DlExpr
      .. py:class:: gcc.DotProdExpr
      .. py:class:: gcc.DotstarExpr
      .. py:class:: gcc.EmptyClassExpr
      .. py:class:: gcc.ExcessPrecisionExpr
      .. py:class:: gcc.ExprPackExpansion
      .. py:class:: gcc.ExprStmt
      .. py:class:: gcc.FdescExpr
      .. py:class:: gcc.FmaExpr
      .. py:class:: gcc.InitExpr
      .. py:class:: gcc.MessageSendExpr
      .. py:class:: gcc.ModifyExpr
      .. py:class:: gcc.ModopExpr
      .. py:class:: gcc.MustNotThrowExpr
      .. py:class:: gcc.NonDependentExpr
      .. py:class:: gcc.NontypeArgumentPack
      .. py:class:: gcc.NullExpr
      .. py:class:: gcc.NwExpr
      .. py:class:: gcc.ObjTypeRef
      .. py:class:: gcc.OffsetofExpr
      .. py:class:: gcc.PolynomialChrec
      .. py:class:: gcc.PostdecrementExpr
      .. py:class:: gcc.PostincrementExpr
      .. py:class:: gcc.PredecrementExpr
      .. py:class:: gcc.PredictExpr
      .. py:class:: gcc.PreincrementExpr
      .. py:class:: gcc.PropertyRef
      .. py:class:: gcc.PseudoDtorExpr
      .. py:class:: gcc.RealignLoad
      .. py:class:: gcc.SaveExpr
      .. py:class:: gcc.ScevKnown
      .. py:class:: gcc.ScevNotKnown
      .. py:class:: gcc.SizeofExpr
      .. py:class:: gcc.StmtExpr
      .. py:class:: gcc.TagDefn
      .. py:class:: gcc.TargetExpr
      .. py:class:: gcc.TemplateIdExpr
      .. py:class:: gcc.ThrowExpr
      .. py:class:: gcc.TruthAndExpr
      .. py:class:: gcc.TruthAndifExpr
      .. py:class:: gcc.TruthNotExpr
      .. py:class:: gcc.TruthOrExpr
      .. py:class:: gcc.TruthOrifExpr
      .. py:class:: gcc.TruthXorExpr
      .. py:class:: gcc.TypeExpr
      .. py:class:: gcc.TypeidExpr
      .. py:class:: gcc.VaArgExpr
      .. py:class:: gcc.VecCondExpr
      .. py:class:: gcc.VecDlExpr
      .. py:class:: gcc.VecInitExpr
      .. py:class:: gcc.VecNwExpr
      .. py:class:: gcc.WidenMultMinusExpr
      .. py:class:: gcc.WidenMultPlusExpr
      .. py:class:: gcc.WithCleanupExpr
      .. py:class:: gcc.WithSizeExpr
      =====================================  ======================

TODO

Statements
----------

.. py:class:: gcc.Statement

   A subclass of :py:class:`gcc.Tree` for statements

   Corresponds to the `tcc_statement` value of `enum tree_code_class` within
   GCC's own C sources.

.. py:class:: gcc.CaseLabelExpr

   A subclass of :py:class:`gcc.Statement` for the `case` and `default` labels
   within a `switch` statement.

   .. py:attribute:: low

      * for single-valued case labels, the value, as a :py:class:`gcc.Tree`

      * for range-valued case labels, the lower bound, as a :py:class:`gcc.Tree`

      * `None` for the default label

   .. py:attribute:: high

      For range-valued case labels, the upper bound, as a :py:class:`gcc.Tree`.

      `None` for single-valued case labels, and for the default label

   .. py:attribute:: target

      The target of the case label, as a :py:class:`gcc.LabelDecl`

SSA Names
---------

.. py:class:: gcc.SsaName

   A subclass of :py:class:`gcc.Tree` representing a variable references
   during SSA analysis.  New SSA names are created every time a variable
   is assigned a new value.

   .. py:attribute:: var

      The variable being referenced, as a :py:class:`gcc.VarDecl` or
      :py:class:`gcc.ParmDecl`

   .. py:attribute:: def_stmt

      The :py:class:`gcc.Gimple` statement which defines this SSA name

   .. py:attribute:: version

      An `int` value giving the version number of this SSA name

  .. Here's a dump of the class hierarchy, from help(gcc):
  ..    Tree
  ..        ArgumentPackSelect
  ..        Baselink
  ..        Binary
  ..            BitAndExpr
  ..            BitIorExpr
  ..            BitXorExpr
  ..            CeilDivExpr
  ..            CeilModExpr
  ..            CompareExpr
  ..            CompareGExpr
  ..            CompareLExpr
  ..            ComplexExpr
  ..            ExactDivExpr
  ..            FloorDivExpr
  ..            FloorModExpr
  ..            LrotateExpr
  ..            LshiftExpr
  ..            MaxExpr
  ..            MinExpr
  ..            MinusExpr
  ..            MinusNomodExpr
  ..            MultExpr
  ..            PlusExpr
  ..            PlusNomodExpr
  ..            PointerPlusExpr
  ..            RangeExpr
  ..            RdivExpr
  ..            RoundDivExpr
  ..            RoundModExpr
  ..            RrotateExpr
  ..            RshiftExpr
  ..            TruncDivExpr
  ..            TruncModExpr
  ..            UrshiftExpr
  ..            VecExtractevenExpr
  ..            VecExtractoddExpr
  ..            VecInterleavehighExpr
  ..            VecInterleavelowExpr
  ..            VecLshiftExpr
  ..            VecPackFixTruncExpr
  ..            VecPackSatExpr
  ..            VecPackTruncExpr
  ..            VecRshiftExpr
  ..            WidenMultExpr
  ..            WidenMultHiExpr
  ..            WidenMultLoExpr
  ..            WidenSumExpr
  ..        Block
  ..        Comparison
  ..            EqExpr
  ..            GeExpr
  ..            GtExpr
  ..            LeExpr
  ..            LtExpr
  ..            LtgtExpr
  ..            NeExpr
  ..            OrderedExpr
  ..            UneqExpr
  ..            UngeExpr
  ..            UngtExpr
  ..            UnleExpr
  ..            UnltExpr
  ..            UnorderedExpr
  ..        Constant
  ..            ComplexCst
  ..            FixedCst
  ..            IntegerCst
  ..            PtrmemCst
  ..            RealCst
  ..            StringCst
  ..            VectorCst
  ..        Constructor
  ..        Declaration
  ..            ClassMethodDecl
  ..            ConstDecl
  ..            DebugExprDecl
  ..            FieldDecl
  ..            FunctionDecl
  ..            ImportedDecl
  ..            InstanceMethodDecl
  ..            KeywordDecl
  ..            LabelDecl
  ..            NamespaceDecl
  ..            ParmDecl
  ..            PropertyDecl
  ..            ResultDecl
  ..            TemplateDecl
  ..            TranslationUnitDecl
  ..            TypeDecl
  ..            UsingDecl
  ..            VarDecl
  ..        DefaultArg
  ..        ErrorMark
  ..        Expression
  ..            AddrExpr
  ..            AlignofExpr
  ..            ArrowExpr
  ..            AssertExpr
  ..            AtEncodeExpr
  ..            BindExpr
  ..            CMaybeConstExpr
  ..            ClassReferenceExpr
  ..            CleanupPointExpr
  ..            CompoundExpr
  ..            CompoundLiteralExpr
  ..            CondExpr
  ..            CtorInitializer
  ..            DlExpr
  ..            DotProdExpr
  ..            DotstarExpr
  ..            EmptyClassExpr
  ..            ExcessPrecisionExpr
  ..            ExprPackExpansion
  ..            ExprStmt
  ..            FdescExpr
  ..            FmaExpr
  ..            InitExpr
  ..            MessageSendExpr
  ..            ModifyExpr
  ..            ModopExpr
  ..            MustNotThrowExpr
  ..            NonDependentExpr
  ..            NontypeArgumentPack
  ..            NullExpr
  ..            NwExpr
  ..            ObjTypeRef
  ..            OffsetofExpr
  ..            PolynomialChrec
  ..            PostdecrementExpr
  ..            PostincrementExpr
  ..            PredecrementExpr
  ..            PredictExpr
  ..            PreincrementExpr
  ..            PropertyRef
  ..            PseudoDtorExpr
  ..            RealignLoad
  ..            SaveExpr
  ..            ScevKnown
  ..            ScevNotKnown
  ..            SizeofExpr
  ..            StmtExpr
  ..            TagDefn
  ..            TargetExpr
  ..            TemplateIdExpr
  ..            ThrowExpr
  ..            TruthAndExpr
  ..            TruthAndifExpr
  ..            TruthNotExpr
  ..            TruthOrExpr
  ..            TruthOrifExpr
  ..            TruthXorExpr
  ..            TypeExpr
  ..            TypeidExpr
  ..            VaArgExpr
  ..            VecCondExpr
  ..            VecDlExpr
  ..            VecInitExpr
  ..            VecNwExpr
  ..            WidenMultMinusExpr
  ..            WidenMultPlusExpr
  ..            WithCleanupExpr
  ..            WithSizeExpr
  ..        IdentifierNode
  ..        LambdaExpr
  ..        OmpClause
  ..        OptimizationNode
  ..        Overload
  ..        PlaceholderExpr
  ..        Reference
  ..            ArrayRangeRef
  ..            ArrayRef
  ..            AttrAddrExpr
  ..            BitFieldRef
  ..            ComponentRef
  ..            ImagpartExpr
  ..            IndirectRef
  ..            MemRef
  ..            MemberRef
  ..            OffsetRef
  ..            RealpartExpr
  ..            ScopeRef
  ..            TargetMemRef
  ..            UnconstrainedArrayRef
  ..            ViewConvertExpr
  ..        SsaName
  ..        Statement
  ..            AsmExpr
  ..            BreakStmt
  ..            CaseLabelExpr
  ..            CatchExpr
  ..            CleanupStmt
  ..            ContinueStmt
  ..            DeclExpr
  ..            DoStmt
  ..            EhFilterExpr
  ..            EhSpecBlock
  ..            ExitExpr
  ..            ExitStmt
  ..            ForStmt
  ..            GotoExpr
  ..            Handler
  ..            IfStmt
  ..            LabelExpr
  ..            LoopExpr
  ..            LoopStmt
  ..            OmpAtomic
  ..            OmpCritical
  ..            OmpFor
  ..            OmpMaster
  ..            OmpOrdered
  ..            OmpParallel
  ..            OmpSection
  ..            OmpSections
  ..            OmpSingle
  ..            OmpTask
  ..            RangeForStmt
  ..            ReturnExpr
  ..            StmtStmt
  ..            SwitchExpr
  ..            SwitchStmt
  ..            TryBlock
  ..            TryCatchExpr
  ..            TryFinally
  ..            UsingDirective
  ..            WhileStmt
  ..        StatementList
  ..        StaticAssert
  ..        TargetOptionNode
  ..        TemplateInfo
  ..        TemplateParmIndex
  ..        TraitExpr
  ..        TreeBinfo
  ..        TreeList
  ..        TreeVec
  ..        Type
  ..            ArrayType
  ..            BooleanType
  ..            BoundTemplateTemplateParm
  ..            CategoryImplementationType
  ..            CategoryInterfaceType
  ..            ClassImplementationType
  ..            ClassInterfaceType
  ..            ComplexType
  ..            DecltypeType
  ..            EnumeralType
  ..            FixedPointType
  ..            FunctionType
  ..            IntegerType
  ..            LangType
  ..            MethodType
  ..            NullptrType
  ..            OffsetType
  ..            PointerType
  ..            ProtocolInterfaceType
  ..            QualUnionType
  ..            RealType
  ..            RecordType
  ..            ReferenceType
  ..            TemplateTemplateParm
  ..            TemplateTypeParm
  ..            TypeArgumentPack
  ..            TypePackExpansion
  ..            TypenameType
  ..            TypeofType
  ..            UnboundClassTemplate
  ..            UnconstrainedArrayType
  ..            UnionType
  ..            VectorType
  ..            VoidType
  ..        Unary
  ..            AbsExpr
  ..            AddrSpaceConvertExpr
  ..            BitNotExpr
  ..            CastExpr
  ..            ConjExpr
  ..            ConstCastExpr
  ..            ConvertExpr
  ..            DynamicCastExpr
  ..            FixTruncExpr
  ..            FixedConvertExpr
  ..            FloatExpr
  ..            NegateExpr
  ..            NoexceptExpr
  ..            NonLvalueExpr
  ..            NopExpr
  ..            ParenExpr
  ..            ReducMaxExpr
  ..            ReducMinExpr
  ..            ReducPlusExpr
  ..            ReinterpretCastExpr
  ..            StaticCastExpr
  ..            UnaryPlusExpr
  ..            VecUnpackFloatHiExpr
  ..            VecUnpackFloatLoExpr
  ..            VecUnpackHiExpr
  ..            VecUnpackLoExpr
  ..        VlExp
  ..            AggrInitExpr
  ..            CallExpr

