home *** CD-ROM | disk | FTP | other *** search
/ Power GUI Programming with VisualAge C++ / powergui.iso / trialva / ibmcppw / include / demangle.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-02-16  |  20.7 KB  |  553 lines
  1. #ifndef __DEMANGLEH
  2. #define __DEMANGLEH
  3.  
  4. /********************************************************************/
  5. /*  <demangle.h> header file                                        */
  6. /*                                                                  */
  7. /*  VisualAge for C++ for Windows, Version 3.5                      */
  8. /*    Licensed Material - Property of IBM                           */
  9. /*                                                                  */
  10. /*  5801-ARR and Other Materials                                    */
  11. /*                                                                  */
  12. /*  (c) Copyright IBM Corp 1991, 1996. All rights reserved.         */
  13. /*                                                                  */
  14. /********************************************************************/
  15.  
  16. /*************************************************************************
  17.  
  18.     demangle.h
  19.  
  20. This file contains the C and C++ interfaces to the C++ name demangler.
  21.  
  22. The library provides the function "Demangle" and a number of classes.
  23. "Demangle" is used to convert mangled C++ names to (pointers to) instances
  24. of the "Name" class (or some class derived from "Name"). Once such an object
  25. has been created, the user can find out certain characteristics of the name.
  26.  
  27. There are six subclasses of "Name", organized in the following way:
  28.  
  29.                           Name
  30.                        /  |  \  \
  31.             SpecialName  / \  \  ClassName
  32.                         /   \  LongName
  33.                        /     \
  34.                       /    FunctionName
  35.                      /           \
  36.                     /             \
  37.           MemberVarName         MemberFunctionName
  38.  
  39. The "SpecialName" class is for special compiler generated class objects,
  40. while the "ClassName" class is for names that are mangled class names.
  41. The "LongName" class is reserved for names that, when mangled, are "too
  42. long". "Too long" is system dependent, and determined by the compiler. See
  43. below.
  44.  
  45. The objects that the other subclasses represent should be self-evident.
  46.  
  47. The demangler will only demangle "special" names and names that are only
  48. class names when the "SpecialNames" and "ClassNames" flags, respectively,
  49. are supplied to the demangler in the "options" parameter. This parameter
  50. takes the default value of "RegularNames", and so it will by default
  51. demangle only regular names. "SpecialNames", "ClassNames" and "RegularNames"
  52. can be specified in any combination simply by "bit-or"ing them together.
  53.  
  54. One can also request that the text of the individual parameters of functions
  55. be kept around by specifying the option "ParameterText". It should be noted
  56. that this increases the amount of storage required to store a demangled name
  57. and can amount to alot when many names are being demangled and kept around.
  58.  
  59. One can also request that the text of the individual members of a qualifier
  60. list can be kept around by specifying the option "QualifierText". It should
  61. be noted that this increases the amount of storage required to store a
  62. demangled name. The "Qualifier" class is an auxiliary class that represents
  63. a member name's qualifier. Normally, only the text is available, but if
  64. QualifierText is specified as an option, the text of individual class names
  65. is available, both in full and without template arguments.
  66.  
  67. An important feature of the demangler is that, while it is a C++ program, it
  68. uses no features requiring the C++ runtime library, and hence it is not
  69. necessary to link libC.a to the program containing demangle.o. This affects
  70. the interface in only one way. Normally, the class "Name" would be a virtual
  71. class, but due to the lack of libC.a, pure virtual functions cannot be used.
  72. The user should always treat the Name class as though it is a virtual.
  73.  
  74. The most common operation is expected to be simply the retrieval of the
  75. string representation of the demangled name, and is accomplished by the
  76. virtual "Name" member "Text", which returns a pointer to a string. This
  77. string is part of the Name object; if a user wants to change it or have
  78. it exist beyond the lifetime of the object, s/he must make a copy of the
  79. string. There is also a "char *" conversion operator for "Name" (and its
  80. derived classes).
  81.  
  82. Other information about a demangled name is available. This is accomplished
  83. by first determining the actual kind of the given name, via the virtual
  84. method "Kind" of "Name", which returns a "NameKind" value (see below). Once
  85. this value is determined, the "Name *" can be cast to the appropriate
  86. derived class, and the methods of this class can then be called. These
  87. methods are defined below.
  88.  
  89. ***********************************************************************/
  90.  
  91. #include <stddef.h>
  92.  
  93. typedef enum { False = 0, True = 1 } Boolean;
  94.  
  95. typedef enum { VirtualName, MemberVar, Function, MemberFunction, Class,
  96.                Special, Long } NameKind;
  97. typedef enum { RegularNames = 0x1, ClassNames = 0x2, SpecialNames = 0x4,
  98.                ParameterText = 0x8, QualifierText = 0x10 } DemanglingOptions;
  99.  
  100. #pragma pack(4)
  101.  
  102. #ifdef __cplusplus
  103.  
  104. class CommonType;
  105. class TypeList;
  106. class Argument;
  107. class ArgumentList;
  108.  
  109. class Name;
  110.  
  111. /*
  112.  * Demangle. Given a valid C "name" and the address of a char pointer, this
  113.  * function creates a "Name" instance and returns its address. A valid C name
  114.  * is one starting with an "_" or letter followed by a number of letters, digits
  115.  * and "_"s. The name is assumed to start at the beginning of the string, but
  116.  * there may be trailing characters not part of the mangled name. A pointer
  117.  * into "name" at the first character not part of the mangled name is returned
  118.  * in "rest".
  119.  *     Demangle will return NULL when the text of the demangled name is the
  120.  * same as the text of the mangled name. Thus, when NULL is returned, the
  121.  * character string given as Demangle's first argument is in fact the
  122.  * demangled name, too.
  123.  */
  124.  
  125. Name *Demangle(char *name, char *&rest, unsigned long options = RegularNames);
  126.  
  127. class Name {
  128.     public:
  129.         virtual ~Name();
  130.         virtual NameKind Kind();
  131.  
  132.         virtual char *Text();
  133.         operator char *();
  134. };
  135.  
  136. // ClassName: representation of a demangled (possibly nested) class name
  137. /*
  138.  *     Kind: returns the kind of the name (Class)
  139.  *     Text: returns the text of the demangled name
  140.  *     operator Qualifier *: returns the associated qualifier
  141.  */
  142.  
  143. class Qualifier;
  144.  
  145. class ClassName: public Name {
  146.         friend Name *BufferedDemangle(char *, char *&, unsigned long = RegularNames);
  147.  
  148.         Qualifier *qualifier;
  149.  
  150.         ClassName(Qualifier *);
  151.     public:
  152.         ~ClassName();
  153.         virtual NameKind Kind();
  154.  
  155.         operator Qualifier *();
  156.  
  157.         char *Text();
  158. };
  159.  
  160. // SpecialName: representation of a demangled compiler-generated name
  161. /*
  162.  *     Kind: returns the kind of the name (Special)
  163.  *     Text: return the text of the demangled name
  164.  */
  165.  
  166. class SpecialName: public Name {
  167.         friend Name *BufferedDemangle(char *, char *&, unsigned long = RegularNames);
  168.  
  169.         char *text;
  170.  
  171.         SpecialName(char *);
  172.     public:
  173.         virtual ~SpecialName();
  174.  
  175.         virtual NameKind Kind();
  176.         virtual char *Text();
  177. };
  178.  
  179. // LongName: representation of a demangled long name
  180. /*
  181.  *     Kind: returns the kind of the name (LongName)
  182.  *     ProbableKind: returns the probable kind of the name, but if the
  183.  *           name is extremely long, the value might be wrong (e.g. a
  184.  *           member function name might be confused for a member var
  185.  *           name).
  186.  *     Text: return the text of the demangled name
  187.  */
  188.  
  189. class LongName: public Name {
  190.         friend Name *BufferedDemangle(char *, char *&, unsigned long = RegularNames);
  191.  
  192.         char *text;
  193.         NameKind probableKind;
  194.  
  195.         LongName(Name *);
  196.         LongName(char *);
  197.     public:
  198.         virtual ~LongName();
  199.  
  200.         virtual NameKind Kind();
  201.         virtual NameKind ProbableKind();
  202.         virtual char *Text();
  203. };
  204.  
  205. // MemberVarName: representation of a demangled static member variable name
  206. /*
  207.  *     Kind: returns the kind of the name (MemberVar)
  208.  *     VarName: returns the unqualified name of the member variable
  209.  *     Scope: returns the qualifier of the member variable
  210.  *     Text: return the text of the demangled name
  211.  *
  212.  *     IsConstant: returns whether the function is a constant function
  213.  *     IsVolatile: returns whether the function is a volatile function
  214.  *     IsStatic: returns whether the function is a static member function
  215.  */
  216.  
  217. class MemberVarName: public Name {
  218.         friend Name *BufferedDemangle(char *, char *&, unsigned long = RegularNames);
  219.  
  220.         char *text;
  221.         char *name;
  222.         Qualifier *qualifier;
  223.  
  224.         Boolean isConstant:8;
  225.         Boolean isStatic:8;
  226.         Boolean isVolatile:8;
  227.  
  228.         MemberVarName(char *, unsigned long, Qualifier *, Boolean, Boolean,
  229.                       Boolean);
  230.     public:
  231.         virtual ~MemberVarName();
  232.  
  233.         virtual NameKind Kind();
  234.         char *VarName();
  235.         Qualifier *Scope();
  236.         virtual char *Text();
  237.  
  238.         Boolean IsConstant();
  239.         Boolean IsStatic();
  240.         Boolean IsVolatile();
  241. };
  242.  
  243. // FunctionName: representation of a demangled function name
  244. /*
  245.  *     Kind: returns the kind of the name (Function)
  246.  *     RootName: returns the unqualified name of the function
  247.  *     Text: returns the text of the demangled name
  248.  *
  249.  * Further, if the option "ParameterText" was supplied to Demangle, the
  250.  * function "ParamDataKept" is True, and the following functions are
  251.  * useful:
  252.  *
  253.  *     nArguments: returns the number of arguments of the function
  254.  *     Arguments: returns the text of the function's argument string
  255.  *     Argument: returns the text of the i'th argument (numbered from 0) of
  256.  *       the function. If i < 0 or i >= n, where n is the number of arguments
  257.  *       of the function, NULL is returned.
  258.  */
  259.  
  260. class FunctionName: public Name {
  261.         friend Name *BufferedDemangle(char *, char *&, unsigned long = RegularNames);
  262.  
  263.     protected:
  264.         Boolean paramDataKept;
  265.         char *name;
  266.         TypeList *arguments;
  267.  
  268.         char *text;
  269.         FunctionName(char *, unsigned long, TypeList *, Boolean);
  270.  
  271.     public:
  272.         virtual ~FunctionName();
  273.  
  274.         virtual NameKind Kind();
  275.         char *RootName();
  276.         virtual char *Text();
  277.  
  278.         Boolean ParamDataKept();
  279.         long nArguments();
  280.         char *Arguments();
  281.         char *Argument(unsigned long);
  282. };
  283.  
  284. // MemberFunctionName: representation of a demangled member function name
  285. /*
  286.  *     Kind: returns the kind of the name (MemberFunction)
  287.  *     Scope: returns a pointer to the qualifier of the name
  288.  *     Text: returns the text of the demangled name
  289.  *
  290.  *     IsConstant: returns whether the function is a constant function
  291.  *     IsVolatile: returns whether the function is a volatile function
  292.  *     IsStatic: returns whether the function is a static member function
  293.  */
  294.  
  295. class MemberFunctionName: public FunctionName {
  296.         friend Name *BufferedDemangle(char *, char *&, unsigned long = RegularNames);
  297.  
  298.         Qualifier *qualifier;
  299.         Boolean isConstant: 8;
  300.         Boolean isStatic: 8;
  301.         Boolean isVolatile: 8;
  302.         Boolean isContravariant: 4;
  303.         Boolean isUnaligned: 2;
  304.         Boolean isTDispThunk: 2;
  305.  
  306.         char *text;
  307.  
  308.         MemberFunctionName(char *, unsigned long, Qualifier *, TypeList *,
  309.                            Boolean, Boolean, Boolean, Boolean, Boolean);
  310.     public:
  311.         virtual ~MemberFunctionName();
  312.  
  313.         virtual NameKind Kind();
  314.         Qualifier *Scope();
  315.         virtual char *Text();
  316.  
  317.         Boolean IsConstant();
  318.         Boolean IsStatic();
  319.         Boolean IsVolatile();
  320.         Boolean IsContravariant();
  321.         Boolean IsUnaligned();
  322.         Boolean IsTDispThunk();
  323. };
  324.  
  325. // Qualifier: representation of a demangled (possibly nested) class name.
  326. /*
  327.  *     Text: returns the text of the qualifier
  328.  *
  329.  * Additionally, if the option "QualifierText" was specified, "ClassDataKept"
  330.  * is True, and the following members are useful:
  331.  *
  332.  *     NQualifiers: returns the number of segments in the qualifier name; i.e.,
  333.  *                  the number of levels the class name is nested, plus one.
  334.  *     operator[]: returns a pointer to the Qualifier::Class of the given
  335.  *                 class of the qualifier. These are numbered starting at zero
  336.  *                 on the left, and increasing to the right. Thus, in X::Y,
  337.  *                 "X" has number zero and "Y" number one.
  338.  *
  339.  * The nested class "Class" provides the information about one of the
  340.  * classes of the qualification. This information is available only if
  341.  * "ClassDataKept" is True. Its public members are:
  342.  *     Name: returns a pointer to the raw name of the class, excluding any
  343.  *           template arguments).
  344.  *     Text: returns a pointer to the full class name, including template
  345.  *           arguments.
  346.  */
  347.  
  348. class Qualifier {
  349.     public:
  350.         class Class {
  351.                 friend class Qualifier;
  352.                 friend Class *ValidClassName(char *, unsigned long &, Boolean);
  353.  
  354.                 char *name;
  355.                 char *text;
  356.             public:
  357.                 char *Name();
  358.                 char *Text();
  359.         };
  360.  
  361.     private:
  362.         friend Qualifier *ValidQualifier(char *, unsigned long &, Boolean);
  363.         friend class MemberVarName;
  364.         friend class MemberFunctionName;
  365.  
  366.         unsigned long nQNames;
  367.         Class **qualifiers;
  368.  
  369.         char *text;
  370.         Boolean classDataKept;
  371.  
  372.         Qualifier(Class **, unsigned long nQNames, Boolean keepClassData);
  373.     public:
  374.         ~Qualifier();
  375.  
  376.         virtual char *Text();
  377.         unsigned long nQualifiers();
  378.  
  379.         Boolean ClassDataKept();
  380.         Class *operator[](unsigned long qualifier);
  381. };
  382.  
  383. // inline function definitions
  384.  
  385. inline          Name::~Name() { }
  386. inline NameKind Name::Kind() { return VirtualName; }
  387. inline char *   Name::Text() { return (char *)NULL; }
  388. inline          Name::operator char *() { return Text(); }
  389.  
  390. inline unsigned long Qualifier::nQualifiers() { return nQNames; }
  391. inline char *   Qualifier::Class::Name() { return name; }
  392. inline char *   Qualifier::Class::Text() { return text; }
  393. inline Boolean  Qualifier::ClassDataKept() { return classDataKept; }
  394.  
  395. inline          ClassName::~ClassName() { delete qualifier; }
  396. inline NameKind ClassName::Kind() { return Class; }
  397. inline          ClassName::operator Qualifier *() { return qualifier; }
  398. inline char *   ClassName::Text() { return qualifier->Text(); }
  399.  
  400. inline          SpecialName::SpecialName(char *t) { text = t; }
  401. inline          SpecialName::~SpecialName() { delete text; }
  402. inline NameKind SpecialName::Kind() { return Special; }
  403. inline char *   SpecialName::Text() { return text; }
  404.  
  405. inline          LongName::~LongName() { delete text; }
  406. inline NameKind LongName::Kind() { return Long; }
  407. inline NameKind LongName::ProbableKind() { return probableKind; }
  408. inline char *   LongName::Text() { return text; }
  409.  
  410. inline NameKind MemberVarName::Kind() { return MemberVar; }
  411. inline char *   MemberVarName::VarName() { return name; }
  412. inline Qualifier *MemberVarName::Scope() { return qualifier; }
  413. inline char *   MemberVarName::Text() { return text; }
  414. inline Boolean  MemberVarName::IsConstant() { return (Boolean)isConstant; }
  415. inline Boolean  MemberVarName::IsStatic() { return (Boolean)isStatic; }
  416. inline Boolean  MemberVarName::IsVolatile() { return (Boolean)isVolatile; }
  417.  
  418. inline NameKind FunctionName::Kind() { return Function; }
  419. inline char *   FunctionName::RootName() { return name; }
  420. inline char *   FunctionName::Text() { return text; }
  421. inline Boolean  FunctionName::ParamDataKept() { return paramDataKept; }
  422.  
  423. inline NameKind MemberFunctionName::Kind() { return MemberFunction; }
  424. inline Qualifier *MemberFunctionName::Scope() { return qualifier; }
  425. inline char *   MemberFunctionName::Text() { return text; }
  426. inline Boolean  MemberFunctionName::IsConstant() { return (Boolean)isConstant; }
  427. inline Boolean  MemberFunctionName::IsStatic() { return (Boolean)isStatic; }
  428. inline Boolean  MemberFunctionName::IsVolatile() { return (Boolean)isVolatile; }
  429. inline Boolean  MemberFunctionName::IsContravariant() { return (Boolean)isContravariant; }
  430. inline Boolean  MemberFunctionName::IsUnaligned() { return (Boolean)isUnaligned; }
  431. inline Boolean  MemberFunctionName::IsTDispThunk() { return (Boolean)isTDispThunk; }
  432.  
  433. #else
  434.  
  435. /*
  436.  * The C Interface
  437.  */
  438.  
  439. /*
  440.  *     demangle. Given a valid C++ "name" and the address of a char pointer,
  441.  * this function creates a "Name" instance and returns its address. A valid C++
  442.  * name is one starting with an "_" or letter followed by a number of letters,
  443.  * digits and "_"s. The name is assumed to start at the beginning of the
  444.  * string, but there may be trailing characters not part of the mangled name.
  445.  * A pointer into "name" at the first character not part of the mangled name
  446.  * is returned in "rest".
  447.  */
  448.  
  449.     typedef struct Name *Name;
  450.  
  451.     Name *demangle(/* char *name, char **rest, unsigned long options */);
  452.  
  453. /*
  454.  * Each of the following functions takes a pointer to a Name as its only
  455.  * parameter.
  456.  */
  457.  
  458.     NameKind kind(/* Name * */);
  459.  
  460.     /* return the character representation of a given Name */
  461.     char *text(/* Name * */);
  462.  
  463.     /* return the probable type of a given LongName-type Name */
  464.     NameKind probableKind(/* Name * */);
  465.  
  466.     /* return the actual name of a given Var- or MemberVar-type Name */
  467.     char *varName(/* Name * */);
  468.  
  469.     /* return the qualifier text of the given Member-type Name */
  470.     char *qualifier(/* Name * */);
  471.  
  472.     /* return the actual name of a given Function- or MemberFunction- */
  473.     /* type Name                                                      */
  474.     char *functionName(/* Name * */);
  475.  
  476.  
  477.     /* returns whether the parameter information was maintained for a */
  478.     /* particular Function- or MemberFunction- type Name.             */
  479.     Boolean paramDataKept(/* Name * */);
  480.  
  481.     /* returns whether the qualifier information was maintained for a */
  482.     /* particular Member- type Name.                                  */
  483.     Boolean classDataKept(/* Name * */);
  484.  
  485.     /*
  486.      * The next three functions require that option "ParameterText" was given
  487.      * to Demangle.
  488.      */
  489.  
  490.     /* return the number of arguments of a given Function- or Member- */
  491.     /* Function type Name.                                            */
  492.     long nArguments(/* Name * */);
  493.  
  494.     /* return the text of the argument list of a given Function- or Member- */
  495.     /* Function- type Name. (char *)NULL is returned if the name wasn't     */
  496.     /* demangled with option ParameterText, and "" is returned if the arg-  */
  497.     /* ument list is empty.                                                 */
  498.     char *argumentsText(/* Name * */);
  499.  
  500.     /* return the text of the nth argument of a given Function- or Member- */
  501.     /* Function- type Name. (char *)NULL is returned if the name wasn't    */
  502.     /* demangled with option ParameterText, or the function doesn't have n */
  503.     /* arguments. The arguments of a function are numbered from 0.         */
  504.     char *argumentText(/* Name *, int n */);
  505.  
  506.     /*
  507.      * The next three functions require that option "QualifierText" was given
  508.      * to Demangle.
  509.      */
  510.  
  511.     /* return the number of qualifiers of the given Member- type Name */
  512.     unsigned long nQualifiers(/* Name * */);
  513.  
  514.     /* return the text of the nth qualifier of a given Member- type Name. */
  515.     /* (char *)NULL is returned if "n" is out of range. The qualifiers of */
  516.     /* a name are numbered from the left starting at zero.                */
  517.     char *qualifierText(/* Name *, unsigned long n */);
  518.  
  519.     /* return the text of the class name of the nth qualifier of a given    */
  520.     /* Member- type Name. (char *)NULL is returned if "n" is out of range.  */
  521.     /* This function will return a value different from the preceding func- */
  522.     /* tion only if the class is a template class. The qualifiers of a name */
  523.     /* are numbered from the left starting at zero.                         */
  524.     char *qualifierNameText(/* Name *, unsigned long n */);
  525.  
  526.  
  527.     /* is a Member-type Name constant? */
  528.     Boolean isConstant(/* Name * */);
  529.  
  530.     /* is a Member-type Name static? */
  531.     Boolean isStatic(/* Name * */);
  532.  
  533.     /* is a Member-type Name volatile? */
  534.     Boolean isVolatile(/* Name * */);
  535.  
  536.     /* is a MemberFunction-type Name a contravariant function? */
  537.     Boolean isContravariant(/* Name * */);
  538.  
  539.     /* is a MemberFunction-type Name a tdisp thunk function? */
  540.     Boolean isTDispThunk(/* Name * */);
  541.  
  542.     /* is a MemberFunction-type Name __unaligned? */
  543.     Boolean isUnaligned(/* Name * */);
  544.  
  545.     /* delete the Name instance */
  546.     void erase(/* Name * */);
  547.  
  548. #endif
  549.  
  550. #pragma pack()
  551.  
  552. #endif
  553.