defun.c revision 146515 
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
33struct token_accumulator
34{
35  unsigned int length;
36  unsigned int index;
37  char **tokens;
38};
39
40static void
41initialize_token_accumulator (struct token_accumulator *accumulator)
42{
43  accumulator->length = 0;
44  accumulator->index = 0;
45  accumulator->tokens = NULL;
46}
47
48static void
49accumulate_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. */
63static int
64scan_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. */
104static char **
105args_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
230static void
231process_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
281static char *
282next_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
301enum insertion_type
302get_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
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. */
331static void
332defun_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. */
688void
689cm_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}
721