3 # code generator to help with writing Tcl extensions
4 # Copyright 2006-2012 Ian Jackson
6 # This program is free software; you can redistribute it and/or
7 # modify it under the terms of the GNU General Public License as
8 # published by the Free Software Foundation; either version 2 of the
9 # License, or (at your option) any later version.
11 # This program is distributed in the hope that it will be useful, but
12 # WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 # General Public License for more details.
16 # You should have received a copy of the GNU General Public License
17 # along with this library; if not, see <http://www.gnu.org/licenses/>.
20 # Input format is line-based, ws-significant, offside rule (some kind
23 # Type TYPE: C-TYPE-DECLARATOR
24 # Defines TYPE as a type (for arguments and return values)
25 # which corresponds to the C type specified. C-TYPE-DECLARATOR
26 # must contain one `@' where the identifier would go.
27 # The type may contain allocated memory, etc., in which case
28 # `Init' and `Fini' must be used.
30 # TYPE may be either TYPENAME or TYPENAME(ARGS) - in this case,
31 # ARGS should be C argument declarations as for in a function
32 # prototype, of extra arguments for the application-supplied
33 # parser/returner functions. Each time a TYPE is used elsewhere,
34 # the ARGS should be the actual arguments to pass, and will be
35 # textually copied into the calls to the parser/returner
38 # `Type' causes declarations in the .h file of these functions:
39 # int cht_pat_TYPENAME(Tcl_Interp*, Tcl_Obj *obj, C-TYPE *val, ARGS);
40 # Tcl_Obj *cht_ret_TYPENAME(Tcl_Interp*, C-TYPE val, ARGS);
42 # cht_pat_... must attempt to parse obj into the appropriate type.
43 # val will already have been initialised with `Init' statements if
44 # relevant. Whether cht_pat_... fails or succeeds it may allocate
45 # memory into the object and must leave the object valid (for
48 # cht_ret_... must convert the value back to a new Tcl_Obj. It may
51 # Init TYPENAME C-STATEMENTS
52 # Provides some statements which are used to initialise a variable
53 # of type TYPENAME. C-STATEMENTS should contain one or more `@',
54 # which will be replaced by the actual variable name. The
55 # variable will have been declared with the C declarator specified
56 # with `Type'. C-STATEMENTS may not fail or longjmp, and they may
57 # not allocate memory or other resources. If no `Init' is
58 # supplied then there is no invariant (so no `Fini' may be
59 # supplied either, and the type is `flat' - no memory, external
62 # Fini TYPENAME C-STATEMENTS
63 # Provides some statements (like `Init') which are used to free a
64 # variable of type TYPENAME. The variable will already have been
65 # initialised with the `Init' statements, and may have been
66 # modified since by application per-type or per-command code. Its
67 # invariant will be satisfied before C-STATEMENTS. Afterwards the
68 # invariant may or may not be satisfied, but it may not have any
69 # memory or other resources allocated. C-STATEMENTS may not fail
72 # H-Include C-INCLUDE-SPECIFIER
73 # Arranges for generated .h files to #include the specified
74 # file. C-INCLUDE-SPECIFIER should include the <..> or "..".
76 # Table [*]TABLENAME C-ENTRY-TYPE
77 # Starts a table of commands or subcommands. The generated .h
78 # will contain a definition of C-ENTRY-TYPE containing
80 # Tcl_ObjCmdProc *func;
81 # and the generated .c will contain
82 # const C-ENTRY-TYPE C-ARRAY-NAME[];
83 # where C-ARRAY-NAME is TABLENAME, with `_entries' appended
84 # and `cht_' prepended. The entries are indented one level (one
85 # or more spaces) and look like this:
86 # ENTRYNAME [ C-EXTRA-ENTRY-VALUES ]
90 # This will cause the declaration of
91 # int cht_do_TABLENAME_ENTRYNAME(ClientData cd, Tcl_Interp *ip,
92 # FORMAL-ARGUMENTS, RESULT-C-TYPE*);
93 # which is the procedure which the application must supply to
94 # implement the function. If the `=> RESULT-TYPE' is omitted, so
95 # is the result argument to the function. Each argument to the
96 # function is of the C type corresponding to the specified type.
97 # TYPE may be `...', in which case the C function will be passed
98 # two args (int objc, Tcl_Obj *const *objv) for the remaining
101 # The cht_do_... function should not eat any memory associated with
102 # the arguments. The result buffer (if any) will be initialised
103 # using the `Init' and should on success contain the relevant
104 # result. On failure it should leave the result unmodified (or at
105 # least, not in need of freeing).
107 # As an alternative, the arguments can be replaced with just
108 # dispatch(TYPE-ARGS-FOR-ENUM)
109 # which is a shorthand for
110 # subcmd enum(TYPE-ARGS-FOR-ENUM)
112 # and also generates and uses a standard dispatch function.
114 # There will be an entry in C-ARRAY-NAME for every table entry.
115 # The name will be ENTRYNAME, and the func will be a function
116 # suitable for use as a Tcl command procedure, which parses the
117 # arguments, processes the command, and sets any result, as
120 # `*' should be used if the table name is not useful for error
121 # messages. It suppresses `TABLENAME ' from the front of the
122 # autogenerated argument parsing error strings.
124 # EntryExtra C-ENTRY-TYPE
125 # Introduces a section of additional C code which will be inserted
126 # into the definition of C-ENTRY-TYPE by `Table'. The C
127 # code, which follows on several indented lines, should be
128 # structure member definitions.
130 # When EntryExtra is used, in the corresponding Table, each
131 # ENTRYNAME should be followed on the same line by whitespace and
132 # EXTRA-VALUES; the EXTRA-VALUES are used as initialisers for the
133 # additional structure elements.
135 # NoEntryDefine C-ENTRY-TYPE
136 # Prevents the definition of C-ENTRY-TYPE by Table.
137 # The C type must be defined elsewhere.
139 # Also expected are these functions:
140 # void cht_setstringresult(Tcl_Interp*, const char*);
141 # sets the Tcl result from the supplied string
142 # int cht_pat_enum(Tcl_Interp*, Tcl_Obj*, const void **c_e_t_array,
143 # const void *c_e_t_return, size_t c_e_t_sz, const char *what);
144 # scans a table of C-ENTRY-TYPEs looking for the
145 # string matching the string supplied by the script
146 # (as a Tcl_Obj). On error sets the result, using
147 # what (a noun phrase describing the type of thing).
148 # Assumes (unportably!) that the name and func members
149 # are in the same places no matter what the rest of
150 # the struct contains.
151 # and the two predefined types `int' (C `int') and `obj' (Tcl_Obj*,
152 # unmodified.) The corresponding definitions are in tcmdiflib.c.
159 our ($prefix, $write, $output);
160 our (%tables, %table_x, %entrytype_x);
161 our (%types, %type_init, %type_fini);
164 sub subst_in_decl ($$;$);
167 sub make_decl ($$$;$);
168 sub make_decl_init ($$$$;$);
170 parse('builtins','DATA');
174 if (m/^\-p([-_0-9a-z]+)$/) {
177 } elsif (m/^\-w(c|h)$/) {
179 } elsif (m/^\-o(.+)$/) {
182 die "unknown option $_\n";
184 if (!defined $prefix) { $prefix= $_; $prefix =~ s/\.[^.]+$//; }
185 my $x= new IO::File $_,'r' or die "$_: $!\n";
190 die "must say -w<something>\n" if !defined $write;
192 our ($c_entry, $c_entrytype);
193 our ($c_table, $c_entryextra, $c_of);
203 $a =~ m:/(.*),: or die "invalid enum type \`$a'\n";
204 my ($a_tab, $ee_type, $estr) = ($`,$1,$');
205 if ($ee_type !~ m/^[^_]/) {
206 $ee_type= $a_tab.$ee_type;
207 $a_tab= lc($a_tab).'_entries';
209 return ($a_tab, $ee_type, $estr);
215 while (defined($_= $f->getline)) {
219 while (s/\t/ ' 'x(8 - (length $`) % 8) /e) { }
222 my $this_indent= length $&;
223 while (@i && $this_indent < $i[0]) {
226 if ($this_indent && (!@i || $this_indent > $i[0])) {
227 unshift @i, $this_indent;
230 if (@i==0 && m/^Table\s+(\*?)(\w+)\s+(\w+)$/) {
233 $table_x{$c_table}{T}= $1;
234 $table_x{$c_table}{C}= $3;
235 $entrytype_x{$3}= '' unless exists $entrytype_x{$3};
236 } elsif (@i==0 && m/^Untabled$/) {
239 } elsif (@i==0 && m/^(C|H)\-Include\s+(\S.*)$/) {
240 o(lc $1, 30, "#include $2\n");
241 } elsif (@i==0 && m/^EntryExtra\s+(\w+)$/) {
244 } elsif (@i==0 && m/^NoEntryDefine\s+(\w+)$/) {
246 $entrytype_x{$1}= " ";
247 } elsif (@i>=1 && defined $c_entryextra) {
248 $entrytype_x{$c_entryextra} .= " $_\n";
249 } elsif (@i==1 && m/^[a-z].*$/ && defined $c_table) {
250 if (m/^[-_0-9A-Za-z]+$/) {
252 } elsif (m/^([-_0-9A-Za-z]+)\s+(\S.*)$/) {
254 $tables{$c_table}{$c_entry}{I} .= ", $2";
256 badsyntax($wh,$.,"bad entry");
258 $tables{$c_table}{$c_entry}{A} = [ ];
259 } elsif (@i==2 && m/^\.\.\.\s+(\w+)$/ && defined $c_entry) {
260 $tables{$c_table}{$c_entry}{V}= $1;
261 } elsif (@i==2 && m:^dispatch\(((.*)/(.*)\,.*)\)$: && defined $c_entry) {
263 my $subcmdtype= $2.$3;
264 $tables{$c_table}{$c_entry}{D}= $subcmdtype;
265 $tables{$c_table}{$c_entry}{V}= 'obj';
266 push @{ $tables{$c_table}{$c_entry}{A} },
267 { N => 'subcmd', T => 'enum', A => $enumargs, O => '' };
268 } elsif (@i==2 && m/^(\??)([a-z]\w*)\s*(\S.*)/
269 && defined $c_entry) {
270 my ($opt, $var, $typea) = ($1,$2,$3);
271 my ($type, $xtypeargs) = split_type_args($wh,$typea);
272 push @{ $tables{$c_table}{$c_entry}{A} },
273 { N => $var, T => $type, A => $xtypeargs, O => ($opt eq '?') };
274 } elsif (@i==2 && m/^\=\>\s*(\S.*)$/ && defined $c_entry) {
275 my ($type, $xtypeargs) = split_type_args($wh,$1);
276 $tables{$c_table}{$c_entry}{R}= $type;
277 $tables{$c_table}{$c_entry}{X}= $xtypeargs;
278 } elsif (@i==0 && m/^Type\s+([^\:]+)\:\s+(\S.*)$/) {
279 my ($typenamea,$ctype)= ($1,$2);
280 $ctype .= ' @' unless $ctype =~ m/\@/;
281 my ($typename,$xtypeargs) = split_type_args($wh,$typenamea);
282 $types{$typename}= { C => $ctype, X => $xtypeargs };
283 } elsif (@i==0 && s/^Init\s+(\w+)\s+(\S.*)//) {
285 } elsif (@i==0 && s/^Fini\s+(\w+)\s+(\S.*)//) {
288 badsyntax($wh,$., sprintf
289 "bad directive (indent level %d)", scalar @i);
292 $f->error and die $!;
296 #print Dumper(\%tables),"\n";
297 #print Dumper(\%types),"\n";
299 foreach my $t (sort keys %types) {
300 my $type= $types{$t};
303 my $decl= "int cht_pat_$t(Tcl_Interp *ip, Tcl_Obj *obj, ";
304 $decl .= subst_in_decl('*val', $c, "type $t");
305 $decl .= ", $xta", if length $xta;
309 $decl= "Tcl_Obj *cht_ret_$t(Tcl_Interp *ip, ".subst_in_decl('val',$c);
310 $decl .= ", $xta" if length $xta;
315 foreach $c_entrytype (sort keys %entrytype_x) {
316 next if $entrytype_x{$c_entrytype} =~ m/^\s$/;
317 o('h', 20, "typedef struct $c_entrytype $c_entrytype;\n");
319 "struct $c_entrytype {\n".
320 " const char *name;\n".
321 " Tcl_ObjCmdProc *func;\n".
322 $entrytype_x{$c_entrytype}.
326 our (%dispatch_done);
328 foreach $c_table (sort keys %tables) {
329 my $r_table= $tables{$c_table};
330 my $x_table= $table_x{$c_table};
333 foreach $c_entry (sort keys %$r_table) {
334 my $c_entry_c= $c_entry; $c_entry_c =~ y/-/_/;
335 my $r_entry= $r_table->{$c_entry};
336 my $pa_decl= "int pa_${c_table}_${c_entry_c}(ClientData cd,".
337 " Tcl_Interp *ip, int objc, Tcl_Obj *const *objv)";
338 my $pa_func= "cht_do_${c_table}_${c_entry_c}";
339 if (exists $r_entry->{D}) {
340 $pa_func= "cht_dispatch_$r_entry->{D}";
342 my $do_decl= "int $pa_func(";
343 my @do_al= ('ClientData cd', 'Tcl_Interp *ip');
344 my @do_aa= qw(cd ip);
346 my $pa_argc= " objc--; objv++;\n";
347 my $pa_vars= " int rc;\n";
357 $pa_hint .= "$c_table " if length $c_table &&
358 !length $table_x{$c_table}{T};
360 foreach my $arg (@{ $r_entry->{A} }) {
364 push @do_al, make_decl($n, $t, $arg->{A},
365 "table $c_table entry $c_entry arg $n");
366 $pa_vars .= make_decl_init("a_$n", $t, $a, \$pa_init, "pa_vars");
373 $pa_body .= " if (!objc--) goto end_optional;\n";
377 $pa_body .= " if (!objc--) goto wrong_count_args;\n";
385 $pa_vars .= " const void *v_$n= 0;\n";
387 $pafin= "\n a_$n= v_$n; ";
388 my ($a_tab, $ee_type, $estr) = enumargs($a);
389 $a = "cht_$a_tab, sizeof($ee_type), $estr";
390 o('h', 210, "extern const $ee_type cht_$a_tab".'[]'.";\n");
392 if (exists $type_fini{$t}) {
393 $pa_fini .= ' '.subst_in("a_$n", $type_fini{$t})."\n";
395 $pa_body .= " rc= cht_pat_$t(ip, *objv++, $paarg";
396 $pa_body .= ", ".$a if length $a;
397 $pa_body .= ");$pafin if (rc) goto rc_err;\n";
400 if (exists $r_entry->{V}) {
402 my $va= $r_entry->{V};
403 push @do_al, subst_in_decl("${va}c", 'int @');
404 push @do_al, subst_in_decl("${va}v", 'Tcl_Obj *const *@');
405 push @do_aa, "objc+1", "objv-1";
408 $pa_body .= " if (objc) goto wrong_count_args;\n";
413 $pa_body .= "end_optional:\n";
415 if (exists $r_entry->{R}) {
416 my $t= $r_entry->{R};
417 my $xta= $r_entry->{X};
418 push @do_al, make_decl("*result", $t, "cht_do_al result");
419 $pa_vars .= make_decl_init("result", $t, $xta, \$pa_init,
421 push @do_aa, "&result";
422 $pa_rslt .= " Tcl_SetObjResult(ip, cht_ret_$t(ip, result";
423 $pa_rslt .= ", $xta" if length $xta;
427 $pa_body .= " rc= $pa_func(";
428 $pa_body .= join ', ', @do_aa;
430 $pa_body .= " if (rc) goto rc_err;\n";
432 $pa_rslt .= " rc= TCL_OK;\n\n";
433 $pa_rslt .= "rc_err:\n";
435 $pa_fini .= " return rc;\n";
437 $pa_fini .= "\nwrong_count_args:\n";
438 $pa_fini .= " e=\"wrong # args: should be \\\"$pa_hint\\\"\";\n";
439 $pa_fini .= " goto e_err;";
443 $pa_vars .= " const char *e;\n";
445 $pa_fini .= "e_err:\n";
446 $pa_fini .= " cht_setstringresult(ip,e);\n";
447 $pa_fini .= " rc= TCL_ERROR; goto rc_err;\n";
450 $pa_init .= "\n" if length $pa_init;
454 if (length $c_table) {
458 o('h',90, "$pa_decl;\n");
461 $static.$pa_decl." {\n".
469 $do_decl .= join ', ', @do_al;
472 if (exists $r_entry->{D}) {
473 my $subcmdtype= $r_entry->{D};
474 if (!exists $dispatch_done{$subcmdtype}) {
476 $di_body .= "static $do_decl {\n";
477 $di_body .= " return subcmd->func(0,ip,objc,objv);\n";
479 o('c',50, $di_body) or die $!;
482 o('h',100, $do_decl.";\n") or die $!;
484 $op_tab .= sprintf(" { %-20s %-40s%s },\n",
486 "pa_${c_table}_${c_entry_c}",
487 ($r_entry->{I}) // '');
489 if (length $c_table) {
490 my $decl= "const $x_table->{C} cht_${c_table}_entries[]";
491 o('h', 500, "extern $decl;\n");
500 o('c', 0, "#include \"$prefix.h\"\n");
503 "#ifndef INCLUDED_\U${prefix}_H\n".
504 "#define INCLUDED_\U${prefix}_H\n\n");
507 "#endif /*INCLUDED_\U${prefix}_H*/\n");
509 if (defined $output) {
510 $oh= new IO::File "$output.tmp", 'w' or die "$output.tmp: $!\n";
515 print $oh "/* AUTOGENERATED - DO NOT EDIT */\n" or die $!;
516 foreach my $pr (sort keys %{ $o{$write} }) {
517 print $oh "\n" or die $!;
518 print $oh $o{$write}{$pr} or die $!;
522 die $! unless $oh->close;
524 if (defined $output) {
525 rename "$output.tmp", $output or die $!;
529 my ($wh,$pr,$s) = @_;
530 $o{$wh}{sprintf "%010d", $pr} .= $s;
533 sub split_type_args ($$) {
536 if ($type =~ m/^\w+$/) {
538 } elsif ($type =~ m/^(\w+)\((.+)\)$/) {
542 badsyntax($wh,$.,"bad type name/args \`$type'\n");
544 return ($type,$xtypeargs);
547 sub make_decl_init ($$$$;$) {
548 my ($n, $t, $a, $initcode, $why) = @_;
550 $o= make_decl($n,$t,$a,"$why _init");
551 if (exists $type_init{$t}) {
552 $init= $type_init{$t};
553 $$initcode .= " ".subst_in("$n", $init)."\n"
561 sub make_decl ($$$;$) {
562 my ($n, $t, $ta, $why) = @_;
565 my ($a_tab, $ee_type, $estr) = enumargs($ta);
566 $c= "const $ee_type* @";
568 defined $types{$t} or die "unknown type $t ($why)\n";
571 return subst_in_decl($n,$c);
574 sub subst_in_decl ($$;$) {
575 my ($val, $pat, $why) = @_;
576 local ($_) = subst_in($val, $pat, $why);
581 sub subst_in ($$;$) {
582 my ($val, $pat, $why) = @_;
583 $pat =~ m/\@/ or die "$pat for $val in $why ?";
588 sub badsyntax ($$$) {
589 die "$_[0]:$_[1]: $_[2]\n";