Fixed unhelpful coredump when parsing (invalid) command-line arguments,
[dyninst.git] / igen / docs / NEW_IGEN
1
2 New features in Igen.
3
4 1) Arrays must be declared before they are used.  
5 2) No more Strings 
6 3) Pointers
7 4) Classes
8 5) Type checking for xdr code, thread code.
9 6) Examples
10 7) Recursive data structures
11 8) Const types
12
13 1) Arrays must be declared before they are used.
14     Why:  Try specifying a pointer to an array of pointers
15           to type char*.
16
17           function ($array char* *cantParse);  
18   
19           How are the "*"s get parsed? 
20
21   The syntax is:
22     $remote array <Array_type> <ptrs> <Array_name>;
23          <Array_type>: identifier, must be "known" if xdr code
24                        is being generated
25          <ptrs>: 0 or more "*"s
26          <Array_name>: identifier, to keep the names consistent
27                        with those that have been used, append
28                        "_Array" to the end of the element type.
29
30     The data structure generated is the same.
31
32 2) No more Strings 
33     There had been a typedef in rpcUtil.h, "typedef char* String"
34     The reason for its existence was to allow igen to treat char*
35     as a special case, since it did not allow pointers to any 
36     basic types.  It still does not allow pointers to basic types
37     (for xdr code), but "char*" is allowed (for xdr code).
38
39     Since String_Array is used throughout paradyn, the .I files 
40     contain "array char * String_Array;"
41
42 3) Pointers
43     Xdr code can now handle pointers to classes and pointers to
44     structures.  One level of indirection is allowed.  Pointers
45     to arrays are also acceptable.
46
47     Pointers can cause problems.  If a recursive data structure
48     is passed into an igen bundler, the bundler may not return.
49
50 4) Classes
51     Igen can generate classes.  The syntax is...
52
53     $remote class <className> [: <parent> ] { 
54     <member variables>
55     [ $ignore $ignore ]
56     };
57
58     An example is...
59     $remote class1 {
60         int a;
61         int b;
62     };
63
64     $remote class2 : class1 {
65           // these are public member variables (FOR NOW)
66         char z;
67         char x;
68         $ignore
69           // text between the ignore tokens will be passed thru to the client 
70           // and the server
71           // this is the current solution to allow member functions to be defined
72           getX() { return x;}
73         $ignore
74     };
75
76     Inheritance is supported for the caller and callee.
77     More information will be provided on this at a later data.
78
79 5) Type checking for xdr code, thread code.
80     Igen does not care about the type names used if you are generating
81     thread code because igen does not generate any bundlers when thread
82     code is used.  If you specify a type name that is unknown, the compiler,
83     not igen, will inform you.
84
85     Igen is concerned about the type names used when xdr code is being 
86     generated since it must generate bundlers for those types.  The basic
87     rule is that a type name must be a basic type (ie, float or integer), 
88     or it must be a type that has been defined using igen keywords:
89     $remote array, $remote class, $remote typedef.
90
91 6) Examples
92    igen/tests has plenty of purified examples.
93
94 7) Recursive data structures
95    igen can handle recursive data structures.  However, it igen bundlers
96    will currently go into an endless loop if it attempts to bundle a 
97    recursive data structure.  If you need this support, let me know.
98
99 8) Const types.  
100    igen allows a type name to be modified with "const" (as ANSI C does?).
101    This eliminated a large number of compiler warnings.  Igen generated
102    functions taking "char*" as argument types, were receiving "const char *"
103    as actual argument types.  "const" is can be used with any type name.