1 /* Generate doc-string file for GNU Emacs from source files.
3 Copyright (C) 1985-1986, 1992-1994, 1997, 1999-2017 Free Software
6 This file is part of GNU Emacs.
8 GNU Emacs is free software: you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation, either version 3 of the License, or (at
11 your option) any later version.
13 GNU Emacs is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License
19 along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. */
22 /* The arguments given to this program are all the C and Lisp source files
23 of GNU Emacs. .elc and .el and .c files are allowed.
24 A .o file can also be specified; the .c file it was made from is used.
25 This helps the makefile pass the correct list of files.
26 Option -d DIR means change to DIR before looking for files.
28 The results, which go to standard output or to a file
29 specified with -a or -o (-a to append, -o to start from nothing),
30 are entries containing function or variable names and their documentation.
31 Each entry starts with a ^_ character.
32 Then comes F for a function or V for a variable.
33 Then comes the function or variable name, terminated with a newline.
34 Then comes the documentation for that function or variable.
45 #include <binary-io.h>
48 #include <unlocked-io.h>
51 /* Defined to be sys_fopen in ms-w32.h, but only #ifdef emacs, so this
52 is really just insurance. */
55 #endif /* WINDOWSNT */
58 /* Defined to be sys_chdir in ms-w32.h, but only #ifdef emacs, so this
59 is really just insurance.
61 Similarly, msdos defines this as sys_chdir, but we're not linking with the
62 file where that function is defined. */
64 #define IS_SLASH(c) ((c) == '/' || (c) == '\\' || (c) == ':')
65 #else /* not DOS_NT */
66 #define IS_SLASH(c) ((c) == '/')
67 #endif /* not DOS_NT */
69 static void scan_file (char *filename
);
70 static void scan_lisp_file (const char *filename
, const char *mode
);
71 static void scan_c_file (char *filename
, const char *mode
);
72 static void scan_c_stream (FILE *infile
);
73 static void start_globals (void);
74 static void write_globals (void);
78 /* Name this program was invoked with. */
79 static char *progname
;
81 /* True if this invocation is generating globals.h. */
82 static bool generate_globals
;
84 /* Print error message. Args are like vprintf. */
86 static void ATTRIBUTE_FORMAT_PRINTF (1, 0)
87 verror (char const *m
, va_list ap
)
89 fprintf (stderr
, "%s: ", progname
);
90 vfprintf (stderr
, m
, ap
);
91 fprintf (stderr
, "\n");
94 /* Print error message. Args are like printf. */
96 static void ATTRIBUTE_FORMAT_PRINTF (1, 2)
97 error (char const *m
, ...)
105 /* Print error message and exit. Args are like printf. */
107 static _Noreturn
void ATTRIBUTE_FORMAT_PRINTF (1, 2)
108 fatal (char const *m
, ...)
117 static _Noreturn
void
118 memory_exhausted (void)
120 fatal ("virtual memory exhausted");
123 /* Like malloc but get fatal error if memory is exhausted. */
126 xmalloc (ptrdiff_t size
)
128 void *result
= malloc (size
);
134 /* Like realloc but get fatal error if memory is exhausted. */
137 xrealloc (void *arg
, ptrdiff_t size
)
139 void *result
= realloc (arg
, size
);
147 main (int argc
, char **argv
)
153 /* If first two args are -o FILE, output to FILE. */
155 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-o"))
157 if (! freopen (argv
[i
+ 1], "w", stdout
))
159 perror (argv
[i
+ 1]);
164 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-a"))
166 if (! freopen (argv
[i
+ 1], "a", stdout
))
168 perror (argv
[i
+ 1]);
173 if (argc
> i
+ 1 && !strcmp (argv
[i
], "-d"))
175 if (chdir (argv
[i
+ 1]) != 0)
177 perror (argv
[i
+ 1]);
182 if (argc
> i
&& !strcmp (argv
[i
], "-g"))
184 generate_globals
= true;
188 set_binary_mode (fileno (stdout
), O_BINARY
);
190 if (generate_globals
)
194 scan_c_stream (stdin
);
197 int first_infile
= i
;
198 for (; i
< argc
; i
++)
201 /* Don't process one file twice. */
202 for (j
= first_infile
; j
< i
; j
++)
203 if (strcmp (argv
[i
], argv
[j
]) == 0)
210 if (generate_globals
)
213 if (ferror (stdout
) || fclose (stdout
) != 0)
214 fatal ("write error");
219 /* Add a source file name boundary marker in the output file. */
221 put_filename (char *filename
)
225 for (tmp
= filename
; *tmp
; tmp
++)
227 if (IS_DIRECTORY_SEP (*tmp
))
231 printf ("\037S%s\n", filename
);
234 /* Read file FILENAME and output its doc strings to stdout.
235 Return true if file is found, false otherwise. */
238 scan_file (char *filename
)
240 ptrdiff_t len
= strlen (filename
);
242 if (!generate_globals
)
243 put_filename (filename
);
244 if (len
> 4 && !strcmp (filename
+ len
- 4, ".elc"))
245 scan_lisp_file (filename
, "rb");
246 else if (len
> 3 && !strcmp (filename
+ len
- 3, ".el"))
247 scan_lisp_file (filename
, "r");
249 scan_c_file (filename
, "r");
255 puts ("/* This file was auto-generated by make-docfile. */");
256 puts ("/* DO NOT EDIT. */");
257 puts ("struct emacs_globals {");
260 static char input_buffer
[128];
262 /* Some state during the execution of `read_c_string_or_comment'. */
265 /* A count of spaces and newlines that have been read, but not output. */
266 intmax_t pending_spaces
, pending_newlines
;
268 /* Where we're reading from. */
271 /* If non-zero, a buffer into which to copy characters. */
273 /* If non-zero, a file into which to copy characters. */
276 /* A keyword we look for at the beginning of lines. If found, it is
277 not copied, and SAW_KEYWORD is set to true. */
279 /* The current point we've reached in an occurrence of KEYWORD in
281 const char *cur_keyword_ptr
;
282 /* Set to true if we saw an occurrence of KEYWORD. */
286 /* Output CH to the file or buffer in STATE. Any pending newlines or
287 spaces are output first. */
290 put_char (char ch
, struct rcsoc_state
*state
)
295 if (state
->pending_newlines
> 0)
297 state
->pending_newlines
--;
300 else if (state
->pending_spaces
> 0)
302 state
->pending_spaces
--;
309 putc (out_ch
, state
->out_file
);
311 *state
->buf_ptr
++ = out_ch
;
313 while (out_ch
!= ch
);
316 /* If in the middle of scanning a keyword, continue scanning with
317 character CH, otherwise output CH to the file or buffer in STATE.
318 Any pending newlines or spaces are output first, as well as any
319 previously scanned characters that were thought to be part of a
320 keyword, but were in fact not. */
323 scan_keyword_or_put_char (char ch
, struct rcsoc_state
*state
)
326 && *state
->cur_keyword_ptr
== ch
327 && (state
->cur_keyword_ptr
> state
->keyword
328 || state
->pending_newlines
> 0))
329 /* We might be looking at STATE->keyword at some point.
330 Keep looking until we know for sure. */
332 if (*++state
->cur_keyword_ptr
== '\0')
333 /* Saw the whole keyword. Set SAW_KEYWORD flag to true. */
335 state
->saw_keyword
= true;
337 /* Reset the scanning pointer. */
338 state
->cur_keyword_ptr
= state
->keyword
;
340 /* Canonicalize whitespace preceding a usage string. */
341 state
->pending_newlines
= 2;
342 state
->pending_spaces
= 0;
344 /* Skip any whitespace between the keyword and the
348 c
= getc (state
->in_file
);
349 while (c
== ' ' || c
== '\n');
351 /* Output the open-paren we just read. */
353 fatal ("Missing '(' after keyword");
356 /* Skip the function name and replace it with `fn'. */
359 c
= getc (state
->in_file
);
361 fatal ("Unexpected EOF after keyword");
363 while (c
!= ' ' && c
!= ')');
364 put_char ('f', state
);
365 put_char ('n', state
);
367 /* Put back the last character. */
368 ungetc (c
, state
->in_file
);
373 if (state
->keyword
&& state
->cur_keyword_ptr
> state
->keyword
)
374 /* We scanned the beginning of a potential usage
375 keyword, but it was a false alarm. Output the
380 for (p
= state
->keyword
; p
< state
->cur_keyword_ptr
; p
++)
381 put_char (*p
, state
);
383 state
->cur_keyword_ptr
= state
->keyword
;
386 put_char (ch
, state
);
391 /* Skip a C string or C-style comment from INFILE, and return the
392 byte that follows, or EOF. COMMENT means skip a comment. If
393 PRINTFLAG is positive, output string contents to stdout. If it is
394 negative, store contents in buf. Convert escape sequences \n and
395 \t to newline and tab; discard \ followed by newline.
396 If SAW_USAGE is non-null, then any occurrences of the string "usage:"
397 at the beginning of a line will be removed, and *SAW_USAGE set to
398 true if any were encountered. */
401 read_c_string_or_comment (FILE *infile
, int printflag
, bool comment
,
405 struct rcsoc_state state
;
407 state
.in_file
= infile
;
408 state
.buf_ptr
= (printflag
< 0 ? input_buffer
: 0);
409 state
.out_file
= (printflag
> 0 ? stdout
: 0);
410 state
.pending_spaces
= 0;
411 state
.pending_newlines
= 0;
412 state
.keyword
= (saw_usage
? "usage:" : 0);
413 state
.cur_keyword_ptr
= state
.keyword
;
414 state
.saw_keyword
= false;
418 while (c
== '\n' || c
== '\r' || c
== '\t' || c
== ' ')
423 while (c
!= EOF
&& (comment
? c
!= '*' : c
!= '"'))
428 if (c
== '\n' || c
== '\r')
440 state
.pending_spaces
++;
443 state
.pending_newlines
++;
444 state
.pending_spaces
= 0;
447 scan_keyword_or_put_char (c
, &state
);
463 scan_keyword_or_put_char ('*', &state
);
470 /* If we had a "", concatenate the two strings. */
479 *saw_usage
= state
.saw_keyword
;
486 /* Write to stdout the argument names of function FUNC, whose text is in BUF.
487 MINARGS and MAXARGS are the minimum and maximum number of arguments. */
490 write_c_args (char *func
, char *buf
, int minargs
, int maxargs
)
493 bool in_ident
= false;
494 char *ident_start UNINIT
;
495 ptrdiff_t ident_length
= 0;
497 fputs ("(fn", stdout
);
502 for (p
= buf
; *p
; p
++)
506 /* Notice when a new identifier starts. */
507 if ((('A' <= c
&& c
<= 'Z')
508 || ('a' <= c
&& c
<= 'z')
509 || ('0' <= c
&& c
<= '9')
521 ident_length
= p
- ident_start
;
525 /* Found the end of an argument, write out the last seen
527 if (c
== ',' || c
== ')')
529 if (ident_length
== 0)
531 error ("empty arg list for '%s' should be (void), not ()", func
);
535 if (strncmp (ident_start
, "void", ident_length
) == 0)
540 if (minargs
== 0 && maxargs
> 0)
541 fputs ("&optional ", stdout
);
546 /* In C code, `default' is a reserved word, so we spell it
547 `defalt'; demangle that here. */
548 if (ident_length
== 6 && memcmp (ident_start
, "defalt", 6) == 0)
549 fputs ("DEFAULT", stdout
);
551 while (ident_length
-- > 0)
554 if (c
>= 'a' && c
<= 'z')
555 /* Upcase the letter. */
558 /* Print underscore as hyphen. */
568 /* The types of globals. These are sorted roughly in decreasing alignment
569 order to avoid allocation gaps, except that symbols and functions
581 /* A single global. */
584 enum global_type type
;
594 /* Bit values for FLAGS field from the above. Applied for DEFUNs only. */
595 enum { DEFUN_noreturn
= 1, DEFUN_const
= 2, DEFUN_noinline
= 4 };
597 /* All the variable names we saw while scanning C sources in `-g'
599 static ptrdiff_t num_globals
;
600 static ptrdiff_t num_globals_allocated
;
601 static struct global
*globals
;
603 static struct global
*
604 add_global (enum global_type type
, char const *name
, int value
,
607 /* Ignore the one non-symbol that can occur. */
608 if (strcmp (name
, "..."))
610 if (num_globals
== num_globals_allocated
)
612 ptrdiff_t num_globals_max
= (min (PTRDIFF_MAX
, SIZE_MAX
)
614 if (num_globals_allocated
== num_globals_max
)
616 if (num_globals_allocated
< num_globals_max
/ 2)
617 num_globals_allocated
= 2 * num_globals_allocated
+ 1;
619 num_globals_allocated
= num_globals_max
;
620 globals
= xrealloc (globals
, num_globals_allocated
* sizeof *globals
);
625 ptrdiff_t namesize
= strlen (name
) + 1;
626 char *buf
= xmalloc (namesize
+ (svalue
? strlen (svalue
) + 1 : 0));
627 globals
[num_globals
- 1].type
= type
;
628 globals
[num_globals
- 1].name
= strcpy (buf
, name
);
630 globals
[num_globals
- 1].v
.svalue
= strcpy (buf
+ namesize
, svalue
);
632 globals
[num_globals
- 1].v
.value
= value
;
633 globals
[num_globals
- 1].flags
= 0;
634 return globals
+ num_globals
- 1;
640 compare_globals (const void *a
, const void *b
)
642 const struct global
*ga
= a
;
643 const struct global
*gb
= b
;
645 if (ga
->type
!= gb
->type
)
646 return ga
->type
- gb
->type
;
648 /* Consider "nil" to be the least, so that iQnil is zero. That
649 way, Qnil's internal representation is zero, which is a bit faster. */
650 if (ga
->type
== SYMBOL
)
652 bool a_nil
= strcmp (ga
->name
, "Qnil") == 0;
653 bool b_nil
= strcmp (gb
->name
, "Qnil") == 0;
655 return b_nil
- a_nil
;
658 return strcmp (ga
->name
, gb
->name
);
662 close_emacs_globals (ptrdiff_t num_symbols
)
665 "extern struct emacs_globals globals;\n"
667 "#ifndef DEFINE_SYMBOLS\n"
671 " struct Lisp_Symbol alignas (GCALIGNMENT) s;\n"
672 "} lispsym[%td];\n"),
680 bool seen_defun
= false;
681 ptrdiff_t symnum
= 0;
682 ptrdiff_t num_symbols
= 0;
683 qsort (globals
, num_globals
, sizeof (struct global
), compare_globals
);
686 for (i
= 0; i
< num_globals
; i
++)
688 while (i
+ 1 < num_globals
689 && strcmp (globals
[i
].name
, globals
[i
+ 1].name
) == 0)
691 if (globals
[i
].type
== FUNCTION
692 && globals
[i
].v
.value
!= globals
[i
+ 1].v
.value
)
693 error ("function '%s' defined twice with differing signatures",
695 free (globals
[i
].name
);
698 num_symbols
+= globals
[i
].type
== SYMBOL
;
699 globals
[j
++] = globals
[i
];
703 for (i
= 0; i
< num_globals
; ++i
)
705 char const *type
= 0;
707 switch (globals
[i
].type
)
716 type
= "Lisp_Object";
722 close_emacs_globals (num_symbols
);
728 fatal ("not a recognized DEFVAR_");
733 printf (" %s f_%s;\n", type
, globals
[i
].name
);
734 printf ("#define %s globals.f_%s\n",
735 globals
[i
].name
, globals
[i
].name
);
737 else if (globals
[i
].type
== SYMBOL
)
738 printf (("#define i%s %td\n"
739 "DEFINE_LISP_SYMBOL (%s)\n"),
740 globals
[i
].name
, symnum
++, globals
[i
].name
);
743 if (globals
[i
].flags
& DEFUN_noreturn
)
744 fputs ("_Noreturn ", stdout
);
745 if (globals
[i
].flags
& DEFUN_noinline
)
746 fputs ("NO_INLINE ", stdout
);
748 printf ("EXFUN (%s, ", globals
[i
].name
);
749 if (globals
[i
].v
.value
== -1)
750 fputs ("MANY", stdout
);
751 else if (globals
[i
].v
.value
== -2)
752 fputs ("UNEVALLED", stdout
);
754 printf ("%d", globals
[i
].v
.value
);
757 if (globals
[i
].flags
& DEFUN_const
)
758 fputs (" ATTRIBUTE_CONST", stdout
);
765 close_emacs_globals (num_symbols
);
767 puts ("#ifdef DEFINE_SYMBOLS");
768 puts ("static char const *const defsym_name[] = {");
769 for (ptrdiff_t i
= 0; i
< num_globals
; i
++)
770 if (globals
[i
].type
== SYMBOL
)
771 printf ("\t\"%s\",\n", globals
[i
].v
.svalue
);
775 puts ("#define Qnil builtin_lisp_symbol (0)");
776 puts ("#if DEFINE_NON_NIL_Q_SYMBOL_MACROS");
778 for (ptrdiff_t i
= 0; i
< num_globals
; i
++)
779 if (globals
[i
].type
== SYMBOL
&& num_symbols
++ != 0)
780 printf ("# define %s builtin_lisp_symbol (%td)\n",
781 globals
[i
].name
, num_symbols
- 1);
786 /* Read through a c file. If a .o file is named,
787 the corresponding .c or .m file is read instead.
788 Looks for DEFUN constructs such as are defined in ../src/lisp.h.
789 Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED. */
792 scan_c_file (char *filename
, const char *mode
)
795 char extension
= filename
[strlen (filename
) - 1];
797 if (extension
== 'o')
798 filename
[strlen (filename
) - 1] = 'c';
800 infile
= fopen (filename
, mode
);
802 if (infile
== NULL
&& extension
== 'o')
805 filename
[strlen (filename
) - 1] = 'm';
806 infile
= fopen (filename
, mode
);
808 filename
[strlen (filename
) - 1] = 'c'; /* Don't confuse people. */
817 /* Reset extension to be able to detect duplicate files. */
818 filename
[strlen (filename
) - 1] = extension
;
819 scan_c_stream (infile
);
822 /* Return 1 if next input from INFILE is equal to P, -1 if EOF,
823 0 if input doesn't match. */
826 stream_match (FILE *infile
, const char *p
)
830 int c
= getc (infile
);
840 scan_c_stream (FILE *infile
)
842 int commas
, minargs
, maxargs
;
845 while (!feof (infile
))
847 bool doc_keyword
= false;
848 bool defunflag
= false;
849 bool defvarperbufferflag
= false;
850 bool defvarflag
= false;
851 enum global_type type
= INVALID
;
852 static char name
[sizeof input_buffer
];
854 if (c
!= '\n' && c
!= '\r')
882 if (c
!= ' ' && c
!= '\t' && c
!= '(')
901 defvarperbufferflag
= (c
== 'P');
902 if (generate_globals
)
905 type
= EMACS_INTEGER
;
913 /* We need to distinguish between DEFVAR_BOOL and
914 DEFVAR_BUFFER_DEFAULTS. */
915 if (generate_globals
&& type
== BOOLEAN
&& c
!= 'O')
930 defunflag
= c
== 'U';
935 && (!defvarflag
|| defvarperbufferflag
|| type
== INVALID
)
936 && !defunflag
&& type
!= SYMBOL
)
948 /* Lisp variable or function name. */
952 c
= read_c_string_or_comment (infile
, -1, false, 0);
955 if (generate_globals
)
958 char const *svalue
= 0;
960 /* Skip "," and whitespace. */
965 while (c
== ',' || c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r');
967 /* Read in the identifier. */
972 input_buffer
[i
++] = c
;
973 if (sizeof input_buffer
<= i
)
974 fatal ("identifier too long");
977 while (! (c
== ',' || c
== ' ' || c
== '\t'
978 || c
== '\n' || c
== '\r'));
979 input_buffer
[i
] = '\0';
980 memcpy (name
, input_buffer
, i
+ 1);
986 while (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r');
989 c
= read_c_string_or_comment (infile
, -1, false, 0);
990 svalue
= input_buffer
;
995 add_global (type
, name
, 0, svalue
);
1003 /* DEFVAR_LISP ("name", addr, "doc")
1004 DEFVAR_LISP ("name", addr /\* doc *\/)
1005 DEFVAR_LISP ("name", addr, doc: /\* doc *\/) */
1008 commas
= generate_globals
? 4 : 5;
1009 else if (defvarperbufferflag
)
1011 else if (defvarflag
)
1013 else /* For DEFSIMPLE and DEFPRED. */
1022 if (defunflag
&& (commas
== 1 || commas
== 2))
1027 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t');
1031 if (commas
== 2) /* Pick up minargs. */
1032 scanned
= fscanf (infile
, "%d", &minargs
);
1033 else /* Pick up maxargs. */
1034 if (c
== 'M' || c
== 'U') /* MANY || UNEVALLED */
1036 if (generate_globals
)
1037 maxargs
= (c
== 'M') ? -1 : -2;
1042 scanned
= fscanf (infile
, "%d", &maxargs
);
1053 if (generate_globals
)
1055 struct global
*g
= add_global (FUNCTION
, name
, maxargs
, 0);
1059 /* The following code tries to recognize function attributes
1060 specified after the docstring, e.g.:
1062 DEFUN ("foo", Ffoo, Sfoo, X, Y, Z,
1064 attributes: attribute1 attribute2 ...)
1065 (Lisp_Object arg...)
1067 Now only ’const’, ’noinline’ and 'noreturn' attributes
1070 /* Advance to the end of docstring. */
1074 int d
= getc (infile
);
1079 if (c
== '*' && d
== '/')
1081 c
= d
, d
= getc (infile
);
1085 /* Skip spaces, if any. */
1092 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t');
1093 /* Check for 'attributes:' token. */
1094 if (c
== 'a' && stream_match (infile
, "ttributes:"))
1096 char *p
= input_buffer
;
1097 /* Collect attributes up to ')'. */
1105 if (p
- input_buffer
> sizeof (input_buffer
))
1110 if (strstr (input_buffer
, "noreturn"))
1111 g
->flags
|= DEFUN_noreturn
;
1112 if (strstr (input_buffer
, "const"))
1113 g
->flags
|= DEFUN_const
;
1114 if (strstr (input_buffer
, "noinline"))
1115 g
->flags
|= DEFUN_noinline
;
1120 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
1124 c
= read_c_string_or_comment (infile
, 0, false, 0);
1126 while (c
!= EOF
&& c
!= ',' && c
!= '/')
1131 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
1133 while ((c
>= 'a' && c
<= 'z') || (c
>= 'Z' && c
<= 'Z'))
1139 while (c
== ' ' || c
== '\n' || c
== '\r' || c
== '\t')
1146 && (c
= getc (infile
),
1150 bool comment
= c
!= '"';
1153 printf ("\037%c%s\n", defvarflag
? 'V' : 'F', input_buffer
);
1156 getc (infile
); /* Skip past `*'. */
1157 c
= read_c_string_or_comment (infile
, 1, comment
, &saw_usage
);
1159 /* If this is a defun, find the arguments and print them. If
1160 this function takes MANY or UNEVALLED args, then the C source
1161 won't give the names of the arguments, so we shouldn't bother
1162 trying to find them.
1164 Various doc-string styles:
1165 0: DEFUN (..., "DOC") (args) [!comment]
1166 1: DEFUN (..., /\* DOC *\/ (args)) [comment && !doc_keyword]
1167 2: DEFUN (..., doc: /\* DOC *\/) (args) [comment && doc_keyword]
1169 if (defunflag
&& maxargs
!= -1 && !saw_usage
)
1171 char argbuf
[1024], *p
= argbuf
;
1173 if (!comment
|| doc_keyword
)
1181 /* Skip into arguments. */
1188 /* Copy arguments into ARGBUF. */
1191 *p
++ = c
= getc (infile
);
1195 fputs ("\n\n", stdout
);
1196 write_c_args (input_buffer
, argbuf
, minargs
, maxargs
);
1198 else if (defunflag
&& maxargs
== -1 && !saw_usage
)
1199 /* The DOC should provide the usage form. */
1200 fprintf (stderr
, "Missing 'usage' for function '%s'.\n",
1205 if (ferror (infile
) || fclose (infile
) != 0)
1206 fatal ("read error");
1209 /* Read a file of Lisp code, compiled or interpreted.
1211 (defun NAME ARGS DOCSTRING ...)
1212 (defmacro NAME ARGS DOCSTRING ...)
1213 (defsubst NAME ARGS DOCSTRING ...)
1214 (autoload (quote NAME) FILE DOCSTRING ...)
1215 (defvar NAME VALUE DOCSTRING)
1216 (defconst NAME VALUE DOCSTRING)
1217 (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
1218 (fset (quote NAME) #[... DOCSTRING ...])
1219 (defalias (quote NAME) #[... DOCSTRING ...])
1220 (custom-declare-variable (quote NAME) VALUE DOCSTRING ...)
1221 starting in column zero.
1222 (quote NAME) may appear as 'NAME as well.
1224 We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
1225 When we find that, we save it for the following defining-form,
1226 and we use that instead of reading a doc string within that defining-form.
1228 For defvar, defconst, and fset we skip to the docstring with a kludgy
1229 formatting convention: all docstrings must appear on the same line as the
1230 initial open-paren (the one in column zero) and must contain a backslash
1231 and a newline immediately after the initial double-quote. No newlines
1232 must appear between the beginning of the form and the first double-quote.
1233 For defun, defmacro, and autoload, we know how to skip over the
1234 arglist, but the doc string must still have a backslash and newline
1235 immediately after the double quote.
1236 The only source files that must follow this convention are preloaded
1237 uncompiled ones like loaddefs.el; aside from that, it is always the .elc
1238 file that we should look at, and they are no problem because byte-compiler
1239 output follows this convention.
1240 The NAME and DOCSTRING are output.
1241 NAME is preceded by `F' for a function or `V' for a variable.
1242 An entry is output only if DOCSTRING has \ newline just after the opening ".
1246 skip_white (FILE *infile
)
1249 while (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r')
1255 read_lisp_symbol (FILE *infile
, char *buffer
)
1258 char *fillp
= buffer
;
1260 skip_white (infile
);
1265 *(++fillp
) = getc (infile
);
1266 else if (c
== ' ' || c
== '\t' || c
== '\n' || c
== '\r' || c
== '(' || c
== ')')
1277 fprintf (stderr
, "## expected a symbol, got '%c'\n", c
);
1279 skip_white (infile
);
1283 search_lisp_doc_at_eol (FILE *infile
)
1285 int c
= 0, c1
= 0, c2
= 0;
1287 /* Skip until the end of line; remember two previous chars. */
1288 while (c
!= '\n' && c
!= '\r' && c
!= EOF
)
1295 /* If two previous characters were " and \,
1296 this is a doc string. Otherwise, there is none. */
1297 if (c2
!= '"' || c1
!= '\\')
1300 fprintf (stderr
, "## non-docstring found\n");
1308 #define DEF_ELISP_FILE(fn) { #fn, sizeof(#fn) - 1 }
1311 scan_lisp_file (const char *filename
, const char *mode
)
1315 char *saved_string
= 0;
1316 /* These are the only files that are loaded uncompiled, and must
1317 follow the conventions of the doc strings expected by this
1318 function. These conventions are automatically followed by the
1319 byte compiler when it produces the .elc files. */
1323 } const uncompiled
[] = {
1324 DEF_ELISP_FILE (loaddefs
.el
),
1325 DEF_ELISP_FILE (loadup
.el
),
1326 DEF_ELISP_FILE (charprop
.el
),
1327 DEF_ELISP_FILE (cp51932
.el
),
1328 DEF_ELISP_FILE (eucjp
-ms
.el
)
1331 int flen
= strlen (filename
);
1333 if (generate_globals
)
1334 fatal ("scanning lisp file when -g specified");
1335 if (flen
> 3 && !strcmp (filename
+ flen
- 3, ".el"))
1338 for (i
= 0; i
< sizeof (uncompiled
) / sizeof (uncompiled
[0]); i
++)
1340 if (uncompiled
[i
].fl
<= flen
1341 && !strcmp (filename
+ flen
- uncompiled
[i
].fl
, uncompiled
[i
].fn
)
1342 && (flen
== uncompiled
[i
].fl
1343 || IS_SLASH (filename
[flen
- uncompiled
[i
].fl
- 1])))
1350 fatal ("uncompiled lisp file %s is not supported", filename
);
1353 infile
= fopen (filename
, mode
);
1357 exit (EXIT_FAILURE
);
1361 while (!feof (infile
))
1363 char buffer
[BUFSIZ
];
1366 /* If not at end of line, skip till we get to one. */
1367 if (c
!= '\n' && c
!= '\r')
1372 /* Skip the line break. */
1373 while (c
== '\n' || c
== '\r')
1375 /* Detect a dynamic doc string and save it for the next expression. */
1381 ptrdiff_t length
= 0;
1384 /* Read the length. */
1385 while ((c
= getc (infile
),
1386 c
>= '0' && c
<= '9'))
1388 if (INT_MULTIPLY_WRAPV (length
, 10, &length
)
1389 || INT_ADD_WRAPV (length
, c
- '0', &length
)
1390 || SIZE_MAX
< length
)
1391 memory_exhausted ();
1395 fatal ("invalid dynamic doc string length");
1398 fatal ("space not found after dynamic doc string length");
1400 /* The next character is a space that is counted in the length
1401 but not part of the doc string.
1402 We already read it, so just ignore it. */
1405 /* Read in the contents. */
1406 free (saved_string
);
1407 saved_string
= xmalloc (length
);
1408 for (i
= 0; i
< length
; i
++)
1409 saved_string
[i
] = getc (infile
);
1410 /* The last character is a ^_.
1411 That is needed in the .elc file
1412 but it is redundant in DOC. So get rid of it here. */
1413 saved_string
[length
- 1] = 0;
1414 /* Skip the line break. */
1415 while (c
== '\n' || c
== '\r')
1417 /* Skip the following line. */
1418 while (c
!= '\n' && c
!= '\r')
1427 read_lisp_symbol (infile
, buffer
);
1429 if (! strcmp (buffer
, "defun")
1430 || ! strcmp (buffer
, "defmacro")
1431 || ! strcmp (buffer
, "defsubst"))
1434 read_lisp_symbol (infile
, buffer
);
1436 /* Skip the arguments: either "nil" or a list in parens. */
1439 if (c
== 'n') /* nil */
1441 if ((c
= getc (infile
)) != 'i'
1442 || (c
= getc (infile
)) != 'l')
1444 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
1451 fprintf (stderr
, "## unparsable arglist in %s (%s)\n",
1458 skip_white (infile
);
1460 /* If the next three characters aren't `dquote bslash newline'
1461 then we're not reading a docstring.
1463 if ((c
= getc (infile
)) != '"'
1464 || (c
= getc (infile
)) != '\\'
1465 || ((c
= getc (infile
)) != '\n' && c
!= '\r'))
1468 fprintf (stderr
, "## non-docstring in %s (%s)\n",
1475 /* defcustom can only occur in uncompiled Lisp files. */
1476 else if (! strcmp (buffer
, "defvar")
1477 || ! strcmp (buffer
, "defconst")
1478 || ! strcmp (buffer
, "defcustom"))
1481 read_lisp_symbol (infile
, buffer
);
1483 if (saved_string
== 0)
1484 if (!search_lisp_doc_at_eol (infile
))
1488 else if (! strcmp (buffer
, "custom-declare-variable")
1489 || ! strcmp (buffer
, "defvaralias")
1496 read_lisp_symbol (infile
, buffer
);
1502 "## unparsable name in custom-declare-variable in %s\n",
1506 read_lisp_symbol (infile
, buffer
);
1507 if (strcmp (buffer
, "quote"))
1510 "## unparsable name in custom-declare-variable in %s\n",
1514 read_lisp_symbol (infile
, buffer
);
1519 "## unparsable quoted name in custom-declare-variable in %s\n",
1525 if (saved_string
== 0)
1526 if (!search_lisp_doc_at_eol (infile
))
1530 else if (! strcmp (buffer
, "fset") || ! strcmp (buffer
, "defalias"))
1536 read_lisp_symbol (infile
, buffer
);
1541 fprintf (stderr
, "## unparsable name in fset in %s\n",
1545 read_lisp_symbol (infile
, buffer
);
1546 if (strcmp (buffer
, "quote"))
1548 fprintf (stderr
, "## unparsable name in fset in %s\n",
1552 read_lisp_symbol (infile
, buffer
);
1557 "## unparsable quoted name in fset in %s\n",
1563 if (saved_string
== 0)
1564 if (!search_lisp_doc_at_eol (infile
))
1568 else if (! strcmp (buffer
, "autoload"))
1573 read_lisp_symbol (infile
, buffer
);
1578 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1582 read_lisp_symbol (infile
, buffer
);
1583 if (strcmp (buffer
, "quote"))
1585 fprintf (stderr
, "## unparsable name in autoload in %s\n",
1589 read_lisp_symbol (infile
, buffer
);
1594 "## unparsable quoted name in autoload in %s\n",
1599 skip_white (infile
);
1600 if ((c
= getc (infile
)) != '\"')
1602 fprintf (stderr
, "## autoload of %s unparsable (%s)\n",
1606 read_c_string_or_comment (infile
, 0, false, 0);
1608 if (saved_string
== 0)
1609 if (!search_lisp_doc_at_eol (infile
))
1614 else if (! strcmp (buffer
, "if")
1615 || ! strcmp (buffer
, "byte-code"))
1622 fprintf (stderr
, "## unrecognized top-level form, %s (%s)\n",
1628 /* At this point, we should either use the previous dynamic doc string in
1629 saved_string or gobble a doc string from the input file.
1630 In the latter case, the opening quote (and leading backslash-newline)
1631 have already been read. */
1633 printf ("\037%c%s\n", type
, buffer
);
1636 fputs (saved_string
, stdout
);
1637 /* Don't use one dynamic doc string twice. */
1638 free (saved_string
);
1642 read_c_string_or_comment (infile
, 1, false, 0);
1644 free (saved_string
);
1645 if (ferror (infile
) || fclose (infile
) != 0)
1646 fatal ("%s: read error", filename
);
1650 /* make-docfile.c ends here */