Package pygccxml :: Package declarations :: Module matcher'

# Source Code for Module pygccxml.declarations.matcher'

     1  # Copyright 2004-2008 Roman Yakovenko.
     2  # Distributed under the Boost Software License, Version 1.0. (See
     3  # accompanying file LICENSE_1_0.txt or copy at
     4  # http://www.boost.org/LICENSE_1_0.txt)
     5
     6  """implements few "find" algorithms on declarations tree"""
     7
     8  import types
     9  import algorithm
    10
    11 -class matcher:
    12      """class-namespace, contains implementation of few "find" algorithms and
    13      definition of related exception classes"""
    14
    15 -    class declaration_not_found_t( RuntimeError ):
    16          """exception, that will be raised, if the declaration could not be found"""
    17 -        def __init__( self, matcher ):
    18              RuntimeError.__init__( self )
    19              self.matcher = matcher
    20
    21 -        def __str__( self ):
    22              return "Unable to find declaration.  matcher: [%s]"%str(self.matcher)
    23
    24 -    class multiple_declarations_found_t( RuntimeError ):
    25          """exception, that will be raised, if more than one declaration was found"""
    26 -        def __init__( self, matcher ):
    27              RuntimeError.__init__( self )
    28              self.matcher = matcher
    29
    30 -        def __str__( self ):
    31              return "Multiple declarations has been found. matcher: [%s]"%str(self.matcher)
    32
    33      @staticmethod
    34 -    def find( decl_matcher, decls, recursive=True ):
    35          """returns a list of declarations that match "decl_matcher" defined criretia or None
    36
    37          @param decl_matcher: Python callable object, that takes one argument - reference to declaration
    38          @param decls: reference to declaration or list of declarations to be searched in
    39          @param recursive: boolean, if True the method will run decl_matcher, on internal declarations too
    40          """
    41
    42          where = []
    43          if isinstance( decls, types.ListType ):
    44              where.extend( decls )
    45          else:
    46              where.append( decls )
    47          if recursive:
    48              where = algorithm.make_flatten( where )
    49          return filter( decl_matcher, where )
    50
    51      @staticmethod
    52 -    def find_single( decl_matcher, decls, recursive=True ):
    53          """returns a reference to declaration, that match "decl_matcher" defined
    54          criretia, if a unique declaration could not be found the method will return
    55          None.
    56
    57          @param decl_matcher: Python callable object, that takes one argument - reference to declaration
    58          @param decls: reference to declaration or list of declarations to be searched in
    59          @param recursive: boolean, if True the method will run decl_matcher, on internal declarations too
    60          """
    61          answer = matcher.find( decl_matcher, decls, recursive )
    62          if len(answer) == 1:
    63              return answer[0]
    64
    65      @staticmethod
    66 -    def get_single( decl_matcher, decls, recursive=True ):
    67          """returns a reference to declaration, that match "decl_matcher" defined
    68          criretia, if a unique declaration could not be found, an appropriate
    69          exception will be raised.
    70
    71          @param decl_matcher: Python callable object, that takes one argument - reference to declaration
    72          @param decls: reference to declaration or list of declarations to be searched in
    73          @param recursive: boolean, if True the method will run decl_matcher, on internal declarations too
    74          """
    75          answer = matcher.find( decl_matcher, decls, recursive )
    76          if len(answer) == 1:
    77              return answer[0]
    78          elif len(answer) == 0:
    79              raise matcher.declaration_not_found_t( decl_matcher )
    80          else:
    81              raise matcher.multiple_declarations_found_t( decl_matcher )
    82