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