contrib/texinfo/makeinfo/defun.c

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