defun.c revision 100513
1/* defun.c -- @defun and friends. 2 $Id: defun.c,v 1.19 2002/03/18 16:54:54 karl Exp $ 3 4 Copyright (C) 1998, 99, 2000, 01, 02 Free Software Foundation, Inc. 5 6 This program is free software; you can redistribute it and/or modify 7 it under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 2, or (at your option) 9 any later version. 10 11 This program is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 GNU General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with this program; if not, write to the Free Software Foundation, 18 Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ 19 20#include "system.h" 21#include "defun.h" 22#include "docbook.h" 23#include "insertion.h" 24#include "makeinfo.h" 25 26 27#define DEFUN_SELF_DELIMITING(c) \ 28 ((c) == '(' || (c) == ')' || (c) == '[' || (c) == ']') 29 30struct token_accumulator 31{ 32 unsigned int length; 33 unsigned int index; 34 char **tokens; 35}; 36 37static void 38initialize_token_accumulator (accumulator) 39 struct token_accumulator *accumulator; 40{ 41 accumulator->length = 0; 42 accumulator->index = 0; 43 accumulator->tokens = NULL; 44} 45 46static void 47accumulate_token (accumulator, token) 48 struct token_accumulator *accumulator; 49 char *token; 50{ 51 if (accumulator->index >= accumulator->length) 52 { 53 accumulator->length += 10; 54 accumulator->tokens = xrealloc (accumulator->tokens, 55 (accumulator->length * sizeof (char *))); 56 } 57 accumulator->tokens[accumulator->index] = token; 58 accumulator->index += 1; 59} 60 61/* Given STRING_POINTER pointing at an open brace, skip forward and return a 62 pointer to just past the matching close brace. */ 63static int 64scan_group_in_string (string_pointer) 65 char **string_pointer; 66{ 67 char *scan_string = (*string_pointer) + 1; 68 unsigned int level = 1; 69 int started_command = 0; 70 71 for (;;) 72 { 73 int c; 74 if (level == 0) 75 { 76 *string_pointer = scan_string; 77 return 1; 78 } 79 c = *scan_string++; 80 if (c == 0) 81 { 82 /* Tweak line_number to compensate for fact that 83 we gobbled the whole line before coming here. */ 84 line_number--; 85 line_error (_("Missing `}' in @def arg")); 86 line_number++; 87 *string_pointer = scan_string - 1; 88 return 0; 89 } 90 91 if (c == '{' && !started_command) 92 level++; 93 if (c == '}' && !started_command) 94 level--; 95 96 /* remember if at @. */ 97 started_command = (c == '@' && !started_command); 98 } 99} 100 101/* Return a list of tokens from the contents of STRING. 102 Commands and brace-delimited groups count as single tokens. 103 Contiguous whitespace characters are converted to a token 104 consisting of a single space. */ 105static char ** 106args_from_string (string) 107 char *string; 108{ 109 struct token_accumulator accumulator; 110 char *token_start, *token_end; 111 char *scan_string = string; 112 113 initialize_token_accumulator (&accumulator); 114 115 while (*scan_string) 116 { /* Replace arbitrary whitespace by a single space. */ 117 if (whitespace (*scan_string)) 118 { 119 scan_string += 1; 120 while (whitespace (*scan_string)) 121 scan_string += 1; 122 accumulate_token ((&accumulator), (xstrdup (" "))); 123 continue; 124 } 125 126 /* Commands count as single tokens. */ 127 if (*scan_string == COMMAND_PREFIX) 128 { 129 token_start = scan_string; 130 scan_string += 1; 131 if (self_delimiting (*scan_string)) 132 scan_string += 1; 133 else 134 { 135 int c; 136 while (1) 137 { 138 c = *scan_string++; 139 140 if ((c == 0) || (c == '{') || (whitespace (c))) 141 { 142 scan_string -= 1; 143 break; 144 } 145 } 146 147 if (*scan_string == '{') 148 { 149 char *s = scan_string; 150 (void) scan_group_in_string (&s); 151 scan_string = s; 152 } 153 } 154 token_end = scan_string; 155 } 156 157 /* Parentheses and brackets are self-delimiting. */ 158 else if (DEFUN_SELF_DELIMITING (*scan_string)) 159 { 160 token_start = scan_string; 161 scan_string += 1; 162 token_end = scan_string; 163 } 164 165 /* Open brace introduces a group that is a single token. */ 166 else if (*scan_string == '{') 167 { 168 char *s = scan_string; 169 int balanced = scan_group_in_string (&s); 170 171 token_start = scan_string + 1; 172 scan_string = s; 173 token_end = balanced ? (scan_string - 1) : scan_string; 174 } 175 176 /* Otherwise a token is delimited by whitespace, parentheses, 177 brackets, or braces. A token is also ended by a command. */ 178 else 179 { 180 token_start = scan_string; 181 182 for (;;) 183 { 184 int c; 185 186 c = *scan_string++; 187 188 /* Do not back up if we're looking at a }; since the only 189 valid }'s are those matched with {'s, we want to give 190 an error. If we back up, we go into an infinite loop. */ 191 if (!c || whitespace (c) || DEFUN_SELF_DELIMITING (c) 192 || c == '{') 193 { 194 scan_string--; 195 break; 196 } 197 198 /* If we encounter a command embedded within a token, 199 then end the token. */ 200 if (c == COMMAND_PREFIX) 201 { 202 scan_string--; 203 break; 204 } 205 } 206 token_end = scan_string; 207 } 208 209 accumulate_token (&accumulator, substring (token_start, token_end)); 210 } 211 accumulate_token (&accumulator, NULL); 212 return accumulator.tokens; 213} 214 215static void 216process_defun_args (defun_args, auto_var_p) 217 char **defun_args; 218 int auto_var_p; 219{ 220 int pending_space = 0; 221 222 for (;;) 223 { 224 char *defun_arg = *defun_args++; 225 226 if (defun_arg == NULL) 227 break; 228 229 if (defun_arg[0] == ' ') 230 { 231 pending_space = 1; 232 continue; 233 } 234 235 if (pending_space) 236 { 237 add_char (' '); 238 pending_space = 0; 239 } 240 241 if (DEFUN_SELF_DELIMITING (defun_arg[0])) 242 add_char (defun_arg[0]); 243 else if (defun_arg[0] == '&') 244 if (html) 245 { 246 defun_arg = escape_string (xstrdup (defun_arg)); 247 add_word (defun_arg); 248 free (defun_arg); 249 } 250 else 251 add_word (defun_arg); 252 else if (defun_arg[0] == COMMAND_PREFIX) 253 execute_string ("%s", defun_arg); 254 else if (auto_var_p) 255 if (html) 256 { 257 defun_arg = escape_string (xstrdup (defun_arg)); 258 add_word (defun_arg); 259 free (defun_arg); 260 } 261 else 262 add_word (defun_arg); 263 else 264 add_word (defun_arg); 265 } 266} 267 268static char * 269next_nonwhite_defun_arg (arg_pointer) 270 char ***arg_pointer; 271{ 272 char **scan = (*arg_pointer); 273 char *arg = (*scan++); 274 275 if ((arg != 0) && (*arg == ' ')) 276 arg = *scan++; 277 278 if (arg == 0) 279 scan -= 1; 280 281 *arg_pointer = scan; 282 283 return (arg == 0) ? "" : arg; 284} 285 286 287/* This is needed also in insertion.c. */ 288 289enum insertion_type 290get_base_type (type) 291 enum insertion_type type; 292{ 293 enum insertion_type base_type; 294 switch (type) 295 { 296 case defivar: base_type = defcv; break; 297 case defmac: base_type = deffn; break; 298 case defmethod: base_type = defop; break; 299 case defopt: base_type = defvr; break; 300 case defspec: base_type = deffn; break; 301 case deftypefun: base_type = deftypefn; break; 302 case deftypeivar: base_type = deftypeivar; break; 303 case deftypemethod: base_type = deftypemethod; break; 304 case deftypeop: base_type = deftypeop; break; 305 case deftypevar: base_type = deftypevr; break; 306 case defun: base_type = deffn; break; 307 case defvar: base_type = defvr; break; 308 default: 309 base_type = type; 310 break; 311 } 312 313 return base_type; 314} 315 316/* Make the defun type insertion. 317 TYPE says which insertion this is. 318 X_P, if nonzero, says not to start a new insertion. */ 319static void 320defun_internal (type, x_p) 321 enum insertion_type type; 322 int x_p; 323{ 324 enum insertion_type base_type; 325 char **defun_args, **scan_args; 326 char *category, *defined_name, *type_name, *type_name2; 327 328 { 329 char *line; 330 331 /* The @def.. line is the only place in Texinfo where you are 332 allowed to use unquoted braces that don't delimit arguments of 333 a command or a macro; in any other place it will trigger an 334 error message from the reader loop. The special handling of 335 this case inside `args_from_string' is an extra special hack 336 which allows this. The side effect is that if we try to expand 337 the rest of the line below, the recursive reader loop will 338 signal an error if there are brace-delimited arguments on that line. 339 340 The best solution to this would be to change the syntax of 341 @def.. commands so that it doesn't violate Texinfo's own rules. 342 But it's probably too late for this now, as it will break a lot 343 of existing manuals. 344 345 Unfortunately, this means that you can't call macros, use @value, etc. 346 inside @def.. commands, sigh. */ 347 get_rest_of_line (0, &line); 348 defun_args = (args_from_string (line)); 349 free (line); 350 } 351 352 scan_args = defun_args; 353 354 /* Get base type and category string. */ 355 base_type = get_base_type (type); 356 357 /* xx all these const strings should be determined upon 358 documentlanguage argument and NOT via gettext (kama). */ 359 switch (type) 360 { 361 case defun: 362 case deftypefun: 363 category = _("Function"); 364 break; 365 case defmac: 366 category = _("Macro"); 367 break; 368 case defspec: 369 category = _("Special Form"); 370 break; 371 case defvar: 372 case deftypevar: 373 category = _("Variable"); 374 break; 375 case defopt: 376 category = _("User Option"); 377 break; 378 case defivar: 379 case deftypeivar: 380 category = _("Instance Variable"); 381 break; 382 case defmethod: 383 case deftypemethod: 384 category = _("Method"); 385 break; 386 default: 387 category = next_nonwhite_defun_arg (&scan_args); 388 break; 389 } 390 391 /* The class name. */ 392 if ((base_type == deftypefn) 393 || (base_type == deftypevr) 394 || (base_type == defcv) 395 || (base_type == defop) 396 || (base_type == deftypeivar) 397 || (base_type == deftypemethod) 398 || (base_type == deftypeop) 399 ) 400 type_name = next_nonwhite_defun_arg (&scan_args); 401 402 /* The type name for typed languages. */ 403 if ((base_type == deftypemethod) 404 || (base_type == deftypeivar) 405 || (base_type == deftypeop) 406 ) 407 type_name2 = next_nonwhite_defun_arg (&scan_args); 408 409 /* The function or whatever that's actually being defined. */ 410 defined_name = next_nonwhite_defun_arg (&scan_args); 411 412 /* This hack exists solely for the purposes of formatting the Texinfo 413 manual. I couldn't think of a better way. The token might be a 414 simple @@ followed immediately by more text. If this is the case, 415 then the next defun arg is part of this one, and we should 416 concatenate them. */ 417 if (*scan_args && **scan_args && !whitespace (**scan_args) 418 && STREQ (defined_name, "@@")) 419 { 420 char *tem = xmalloc (3 + strlen (scan_args[0])); 421 422 sprintf (tem, "@@%s", scan_args[0]); 423 424 free (scan_args[0]); 425 scan_args[0] = tem; 426 scan_args++; 427 defined_name = tem; 428 } 429 430 /* It's easy to write @defun foo(arg1 arg2), but a following ( is 431 misparsed by texinfo.tex and this is next to impossible to fix. 432 Warn about it. */ 433 if (*scan_args && **scan_args && **scan_args == '(') 434 warning ("`%c' follows defined name `%s' instead of whitespace", 435 **scan_args, defined_name); 436 437 if (!x_p) 438 begin_insertion (type); 439 440 /* Write the definition header line. 441 This should start at the normal indentation. */ 442 current_indent -= default_indentation_increment; 443 start_paragraph (); 444 445 if (!x_p) { 446 /* Start the definition on new paragraph. */ 447 if (html) 448 add_word ("<p>\n"); 449 if (docbook) 450 docbook_begin_paragraph (); 451 } 452 453 if (!html && !docbook) 454 switch (base_type) 455 { 456 case deffn: 457 case defvr: 458 case deftp: 459 execute_string (" -- %s: %s", category, defined_name); 460 break; 461 case deftypefn: 462 case deftypevr: 463 execute_string (" -- %s: %s %s", category, type_name, defined_name); 464 break; 465 case defcv: 466 execute_string (" -- %s %s %s: %s", category, _("of"), type_name, 467 defined_name); 468 break; 469 case deftypeivar: 470 execute_string (" -- %s %s %s: %s %s", category, _("of"), type_name, 471 type_name2, defined_name); 472 break; 473 case defop: 474 execute_string (" -- %s %s %s: %s", category, _("on"), type_name, 475 defined_name); 476 break; 477 case deftypeop: 478 execute_string (" -- %s %s %s: %s %s", category, _("on"), type_name, 479 type_name2, defined_name); 480 break; 481 case deftypemethod: 482 execute_string (" -- %s %s %s: %s %s", category, _("on"), type_name, 483 type_name2, defined_name); 484 break; 485 } 486 487 if (html) 488 { 489 /* If this is not a @def...x version, it could only 490 be a normal version @def.... So start the table here. */ 491 if (!x_p) 492 { 493 add_html_elt ("<table width="); 494 add_word ("\"100%\">\n"); 495 } 496 497 /* If this is an @def...x there has to be an other @def... before 498 it, so this is only a new row within an existing table. With 499 two complete standalone tables the gap between them is too big. */ 500 add_word ("<tr>\n"); 501 add_html_elt ("<td align=\"left\">"); 502 503 switch (base_type) 504 { 505 case deffn: 506 case defvr: 507 case deftp: 508 /* <i> is for the following function arguments. */ 509 add_word ("<b>"); 510 execute_string ("%s", defined_name); 511 add_word ("</b><i>"); 512 break; 513 case deftypefn: 514 case deftypevr: 515 execute_string ("%s ", type_name); 516 add_word ("<b>"); 517 execute_string ("%s", defined_name); 518 add_word ("</b><i>"); 519 break; 520 case defcv: 521 case defop: 522 add_word ("<b>"); 523 execute_string ("%s", defined_name); 524 add_word ("</b><i>"); 525 break; 526 case deftypemethod: 527 case deftypeop: 528 case deftypeivar: 529 execute_string ("%s ", type_name2); 530 add_word ("<b>"); 531 execute_string ("%s", defined_name); 532 add_word ("</b><i>"); 533 break; 534 } 535 } /* if (html)... */ 536 537 if (docbook) 538 { 539 switch (base_type) 540 { 541 case deffn: 542 case defvr: 543 case deftp: 544 case defcv: 545 case defop: 546 add_word_args ("<%s>%s</%s>", DB_FUNCTION, defined_name, 547 DB_FUNCTION); 548 break; 549 case deftypefn: 550 case deftypevr: 551 add_word_args ("%s <%s>%s</%s>", type_name, DB_FUNCTION, 552 defined_name, DB_FUNCTION); 553 break; 554 case deftypemethod: 555 case deftypeop: 556 case deftypeivar: 557 add_word_args ("%s <%s>%s</%s>", type_name2, DB_FUNCTION, 558 defined_name, DB_FUNCTION); 559 break; 560 } 561 562 } /* if (docbook)... */ 563 564 current_indent += default_indentation_increment; 565 566 /* Now process the function arguments, if any. If these carry onto 567 the next line, they should be indented by two increments to 568 distinguish them from the body of the definition, which is indented 569 by one increment. */ 570 current_indent += default_indentation_increment; 571 572 switch (base_type) 573 { 574 case deffn: 575 case defop: 576 process_defun_args (scan_args, 1); 577 break; 578 579 /* Through Makeinfo 1.67 we processed remaining args only for deftp, 580 deftypefn, and deftypemethod. But the libc manual, for example, 581 needs to say: 582 @deftypevar {char *} tzname[2] 583 And simply allowing the extra text seems far simpler than trying 584 to invent yet more defn commands. In any case, we should either 585 output it or give an error, not silently ignore it. */ 586 default: 587 process_defun_args (scan_args, 0); 588 break; 589 } 590 591 current_indent -= default_indentation_increment; 592 close_single_paragraph (); 593 594 if (html) 595 { 596 /* xx The single words (on, off) used here, should depend on 597 documentlanguage and NOT on gettext --kama. */ 598 switch (base_type) 599 { 600 case deffn: 601 case defvr: 602 case deftp: 603 case deftypefn: 604 case deftypevr: 605 add_word ("</i>"); /* close italic area for arguments */ 606 /* put the rest into the second column */ 607 add_word ("</td>\n"); 608 add_html_elt ("<td align=\"right\">"); 609 execute_string ("%s", category); 610 break; 611 612 case defcv: 613 add_word ("</td>\n"); 614 add_html_elt ("<td align=\"right\">"); 615 execute_string ("%s %s %s", category, _("of"), type_name); 616 break; 617 618 case defop: 619 case deftypemethod: 620 case deftypeop: 621 add_word ("</i>"); 622 add_word ("</td>\n"); 623 add_html_elt ("<td align=\"right\">"); 624 execute_string ("%s %s %s", category, _("on"), type_name); 625 break; 626 627 case deftypeivar: 628 add_word ("</i>"); 629 add_word ("</td>\n"); 630 add_html_elt ("<td align=\"right\">"); 631 execute_string ("%s %s %s", category, _("of"), type_name); 632 break; 633 } /* switch (base_type)... */ 634 635 add_word ("</td>\n"); /* close second column */ 636 add_word ("</tr>\n"); /* close row */ 637 638 /* This is needed because I have to know if the next line is 639 normal text or another @def..x. If text follows, create a new 640 table to get the indentation for the following text. 641 642 This construction would fail if someone uses: 643 @deffn 644 @sp 2 645 @deffnx 646 . 647 @end deffn 648 But we don't care. */ 649 if (!looking_at ("@def")) 650 { 651 add_word ("</table>\n"); 652 add_html_elt ("<table width=\"95%\" align=\"center\">"); 653 add_word ("\n<tr><td>\n"); 654 } 655 656 } /* if (html)... */ 657 658 /* Make an entry in the appropriate index. */ 659 switch (base_type) 660 { 661 case deffn: 662 case deftypefn: 663 execute_string ("@findex %s\n", defined_name); 664 break; 665 case defvr: 666 case deftypevr: 667 case defcv: 668 execute_string ("@vindex %s\n", defined_name); 669 break; 670 case deftypeivar: 671 execute_string ("@vindex %s %s %s\n", defined_name, _("of"), type_name); 672 break; 673 case defop: 674 case deftypeop: 675 case deftypemethod: 676 execute_string ("@findex %s %s %s\n", defined_name, _("on"), type_name); 677 break; 678 case deftp: 679 execute_string ("@tindex %s\n", defined_name); 680 break; 681 } 682 683 /* Deallocate the token list. */ 684 scan_args = defun_args; 685 while (1) 686 { 687 char * arg = (*scan_args++); 688 if (arg == NULL) 689 break; 690 free (arg); 691 } 692 free (defun_args); 693} 694 695/* Add an entry for a function, macro, special form, variable, or option. 696 If the name of the calling command ends in `x', then this is an extra 697 entry included in the body of an insertion of the same type. */ 698void 699cm_defun () 700{ 701 int x_p; 702 enum insertion_type type; 703 char *temp = xstrdup (command); 704 705 x_p = (command[strlen (command) - 1] == 'x'); 706 707 if (x_p) 708 temp[strlen (temp) - 1] = 0; 709 710 type = find_type_from_name (temp); 711 free (temp); 712 713 /* If we are adding to an already existing insertion, then make sure 714 that we are already in an insertion of type TYPE. */ 715 if (x_p && (!insertion_level || insertion_stack->insertion != type)) 716 { 717 line_error (_("Must be in `%s' insertion to use `%sx'"), 718 command, command); 719 discard_until ("\n"); 720 return; 721 } 722 723 defun_internal (type, x_p); 724} 725