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