defun.c revision 1.1.1.2 
1/* defun.c -- @defun and friends.
2   $Id: defun.c,v 1.1.1.2 2002/06/10 13:21:15 espie Exp $
3
4   Copyright (C) 1998, 99, 2000, 01, 02 Free Software Foundation, Inc.
5
6   This program is free software; you can redistribute it and/or modify
7   it under the terms of the GNU General Public License as published by
8   the Free Software Foundation; either version 2, or (at your option)
9   any later version.
10
11   This program is distributed in the hope that it will be useful,
12   but WITHOUT ANY WARRANTY; without even the implied warranty of
13   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14   GNU General Public License for more details.
15
16   You should have received a copy of the GNU General Public License
17   along with this program; if not, write to the Free Software Foundation,
18   Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
19
20#include "system.h"
21#include "defun.h"
22#include "docbook.h"
23#include "insertion.h"
24#include "makeinfo.h"
25
26
27#define DEFUN_SELF_DELIMITING(c) \
28  ((c) == '(' || (c) == ')' || (c) == '[' || (c) == ']')
29
30struct token_accumulator
31{
32  unsigned int length;
33  unsigned int index;
34  char **tokens;
35};
36
37static void
38initialize_token_accumulator (accumulator)
39     struct token_accumulator *accumulator;
40{
41  accumulator->length = 0;
42  accumulator->index = 0;
43  accumulator->tokens = NULL;
44}
45
46static void
47accumulate_token (accumulator, token)
48     struct token_accumulator *accumulator;
49     char *token;
50{
51  if (accumulator->index >= accumulator->length)
52    {
53      accumulator->length += 10;
54      accumulator->tokens = xrealloc (accumulator->tokens,
55                                      (accumulator->length * sizeof (char *)));
56    }
57  accumulator->tokens[accumulator->index] = token;
58  accumulator->index += 1;
59}
60
61/* Given STRING_POINTER pointing at an open brace, skip forward and return a
62   pointer to just past the matching close brace. */
63static int
64scan_group_in_string (string_pointer)
65     char **string_pointer;
66{
67  char *scan_string = (*string_pointer) + 1;
68  unsigned int level = 1;
69  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. */
105static char **
106args_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
215static void
216process_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
268static char *
269next_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
289enum insertion_type
290get_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
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. */
319static void
320defun_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. */
698void
699cm_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}
725