contrib/texinfo-4/makeinfo/defun.c

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