contrib/texinfo/makeinfo/defun.c

   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
  30 struct token_accumulator
  31 {
  32   unsigned int length;
  33   unsigned int index;
  34   char **tokens;
  35 };
  36
  37 static void
  38 initialize_token_accumulator (accumulator)
  39      struct token_accumulator *accumulator;
  40 {
  41   accumulator->length = 0;
  42   accumulator->index = 0;
  43   accumulator->tokens = NULL;
  44 }
  45
  46 static void
  47 accumulate_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. */
  63 static int
  64 scan_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. */
 105 static char **
 106 args_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
 215 static void
 216 process_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
 268 static char *
 269 next_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
 289 enum insertion_type
 290 get_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 \f
 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. */
 319 static void
 320 defun_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. */
 698 void
 699 cm_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 }