yagdoc.scanner.Declaration

Package yagdoc :: Module scanner :: Class Declaration

[show private | hide private]

Type Declaration

object --+
         |
        Declaration

One documentable declaration.

It supports comparison protocol, comparison is by position in the input file.

Method Summary
	`__init__(self, kind, name)`
	`__ge__(self, other)`
	`__gt__(self, other)`
	`__le__(self, other)`
	`__lt__(self, other)`
`bool`	`is_type_func(self)` Test whether declaration is a GType get-type function.
`str`	`origin(self)` Get declaration origin.
`list` of `str`	`subnames(self)` Find all subordinate symbol names of a declaration.
`int`	`supersedes(self, other)` Check whether declaration supersedes another.
Inherited from `object`: `__delattr__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__str__`

Instance Variable Summary
`str`	`kind`: Parse tree node name (e.g.
`str`	`macro_kind`: Macro subtype, only for macros.
`str`	`name`: Declared symbol name.
`tuple` of `int`	`pos`: Position in source code `(line, column)`.
`str`	`source`: Header file name.
`list` of `str`	`symbols`: Subordinate symbol list.
sequence of `Token`	`tokens`: Token list, only for macros.
`Tree`	`tree`: Parse tree, only for non-macros.

Method Details

is_type_func(self)

Test whether declaration is a GType get-type function.

The declaration must be a protype of the form (sans decorators):

   GType whatever_get_type(void);

More precisely:

name must end with '_get_type' (but not equal to it),
return type must be exactly 'GType',
argument list must be exactly 'void' (not empty)

These rules should effectively filter out all functions with similar names but a different purpose.

Returns:: True if declaration is a get-type function, False if it is not.
(type=bool)

origin(self)

Get declaration origin.

Returns:: Source header base name with extension removed.
(type=str)

subnames(self)

Find all subordinate symbol names of a declaration.

Typical subordinate symbols are function arguments, struct fields or enum values. Function return values also form subordinate symbols with the name 'return'. Ellipsis forms symbol '...'. Since subsymbols can have their own structure, nesting can occur, '/' is then used to separate levels.

For instance the declarations:

   int foo(int x);
   void bar(void* (*f)(int x));
   struct baz {
       void* (*quux)(int x);
       union {
           int i;
           char c[4];
       } v;
   };

have the following subordinate symbols:

   foo: x, return
   bar: f, f/return, f/x
   baz: quux, quux/return, quux/x, v, v/i, v/c

This function instantiates the symbols field for non-macros. Next calls will not attempt to scan the symbols again, they will just return the value of symbols. Should you even want to rescan subsymbols, delete symbols first.

Returns:: List of subordinate symbols found.
(type=list of str)

supersedes(self, other)

Check whether declaration supersedes another.

If a declaration supersedes another, it will silently replace it (i.e. no warning is issued) when a name clash occurs. This facility is primarily used to select the preferred declaration in common cases of multiple declaration of the same symbol.

For instance

'struct_def' supersedes 'struct_forward'
'enum_def' supersedes 'enum_forward'
'prototype' supersedes parameter-less 'macro'
'prototype' supersedes 'inline_function'
the first occurence of 'macro' supersedes all following provided they have the same arguments
the first occurence of a forward declaration supersedes all following
of a set of identical declarations the first supersedes all following

Parameters:: other - The other declaration.
(type=Declaration)

Returns:

Similarly to rich comparison functions:

positive value if this declaration supersedes other,
negative value if other supersedes this declaration,
zero if the precedence could not be determined

(type=int)

Instance Variable Details

kind

Parse tree node name (e.g. 'prototype', 'enum_def', also 'macro').

Type:: str

macro_kind

Macro subtype, only for macros. Set by classify_macros, see its documentation.

Type:: str

name

Declared symbol name. This is the identifier that introduces the source code docstring.

Type:: str

pos

Position in source code (line, column).

Type:: tuple of int

source

Header file name.

Type:: str

symbols

Subordinate symbol list. For macros it is the argument list, available immediately. Other declarations gain this attribute after subnames. It is a list of tuples (name, kind, ...) where name is the symbol name, with '/' as path separator, kind is the symbol kind:

'argument'
'return'
'enum_value'
'struct_field'

These two can be follows by specific classifiers.

Type:: list of str

tokens

Token list, only for macros.

Type:: sequence of Token

tree

Parse tree, only for non-macros.

Type:: Tree

Generated by Epydoc 2.1 on Fri Oct 5 00:36:53 2007

http://epydoc.sf.net