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