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