[unix-history] / usr / src / old / cpp / README

#
# @(#)README 1.2 %G%
#
August 30, 1982
Fixed by Kurt Shoens, UCB
If the "#line n name" occurs, then all future references
to the current file are generated in terms of "name", instead
of the name of file given to cpp in its command argument

August 25, 1978

Files in this directory form the C preprocessor, which handles '#include'
files and macro definition and expansion for the C compiler.
This new version was written by John F. Reiser and is from 5 to 12
times faster (on UNIX systems) than the old.

To create the executable file 'cpp' in the current directory:
	make

To install the preprocessor 'cpp' so it will be used by the C compiler:
	: safety first: backup the existing version
	cp /lib/cpp /lib/ocpp
	: install the new version
	cp cpp /lib/cpp

Invocation
	cpp [-CEPR] [-Dname] ... [-Dname=def] ... [-Idirectory] ...
		[-Uname] ... [<infile>] [<outfile>]

	If there are two non-flag arguments then the first is the name of the
	input file and the second is the name of the output file.  If there is
	one non-flag argument then it is the name of the input file and the
	output is written on the standard output.  If there are no non-flag
	arguments then the input is taken from the standard input and the output
	is written on the standard output.  Flag arguments are:

		-C	retain comments in output
		-Dname	define name as "1"
		-Dname=def	define name as def
		-E	ignored
		-Idirectory	add directory to search list for #include files
		-P	don't insert lines "# 12 \"foo.c\"" into output
		-R	allow recursive macros
		-Uname	undefine name
		
Documentation clarifications:
	Symbols defined on the command line by "-Dfoo" are defined as "1",
		i.e., as if they had been defined by "#define foo 1" or "-Dfoo=1".
	The directory search order for #include files is
		1) the directory of the file which contains the #include request
		   (e.g. #include is relative to the file being scanned when
		   the request is made)
		2) the directories specified by -I, in left-to-right order
		3) the standard directory(s) (which for UNIX is /usr/include)
	An unescaped linefeed (the single character "\n") terminates a
		character constant or quoted string.
	An escaped linefeed (the two-character sequence "\\\n") may be
		used in the body of a '#define' statement to continue
		the definition onto the next line.  The escaped linefeed is
		not included in the macro body.
	Comments are uniformly removed (except if the argument -C is specified).
		They are also ignored, except that a comment terminates a token.
		Thus "foo/* la di da */bar" may expand 'foo' and 'bar' but
		will never expand 'foobar'.  If neither 'foo' nor 'bar' is a
		macro then the output is "foobar", even if 'foobar'
		is defined as something else.  The file
			#define foo(a,b)b/**/a
			foo(1,2)
		produces "21" because the comment causes a break which enables
		the recognition of 'b' and 'a' as formals in the string "b/**/a".
	Macro formal parameters are recognized in '#define' bodies even inside
		character constants and quoted strings.  The output from
			#define foo(a) '\a'
			foo(bar)
		is the seven characters " '\\bar'".  Macro names are not recognized
		inside character constants or quoted strings during the regular scan.
		Thus
			#define foo bar
			printf("foo");
		does not expand 'foo' in the second line, because it is inside
		a quoted string which is not part of a '#define' macro definition.
	Macros are not expanded while processing a '#define' or '#undef'.
		Thus
			#define foo bletch
			#define bar foo
			#undef foo
			bar
		produces "foo".  The token appearing immediately after a
		'#ifdef' or '#ifndef' is not expanded (of course!).
	Macros are not expanded during the scan which determines the actual
		parameters to another macro call.  Thus
			#define foo(a,b)b a
			#define bar hi
			foo(bar,
			#define bar bye
			)
		produces " bye" (and warns about the redefinition of 'bar').

There are some differences between the new and the old preprocessor.
Bugs fixed:
	"1.e4" is recognized as a floating-point number, rather than as an
		opportunity to expand the possible macro name "e4".
	Any kind and amount of white space (space, tab, linefeed, vertical tab,
		formfeed, carriage return) is allowed between a macro name and
		the left parenthesis which introduces its actual parameters.
	The comma operator is legal in preprocessor '#if' statements.
	Macros with parameters are legal in preprocessor '#if' statements.
	Single-character character constants are legal in preprocessor '#if' statements.
	Linefeeds are put out in the proper place when a multiline comment
		is not passed through to the output.
	The following example expands to "# # #" :
		#define foo #
		foo foo foo
	If the -R flag is not specified then the invocation of some recursive
		macros is trapped and the recursion forcibly terminated with an
		error message.  The recursions that are trapped are the ones
		in which the nesting level is non-decreasing from some point on.
		In particular,
			#define a a
			a
		will be detected.  (Use "#undef a" if that is what you want.)
		The recursion
			#define a c b
			#define b c a
			#define c foo
			a
		will not be detected because the nesting level decreases after
		each expansion of "c".
	The -R flag specifically allows recursive macros and recursion will
		be strictly obeyed (to the extent that space is available).
		Assuming that -R is specified:
			#define a a
			a
		causes an infinite loop with very little output.  The tail recursion
			#define a <b
			#define b >a
			a
		causes the string "<>" to be output infinitely many times.  The
		non-tail recursion
			#define a b>
			#define b a<
			a
		complains "too much pushback", dumps the pushback, and continues
		(again, infinitely).
	
Stylistic choice:
	Nothing (not even linefeeds) is output while a false '#if', '#ifdef',
		or '#ifndef' is in effect.  Thus when all conditions become true
		a line of the form "# 12345 \"foo.c\"" is output (unless -P).
	Error and warning messages always appear on standard error (file
		descriptor 2).
	Mismatch between the number of formals and actuals in a macro call
		produces only a warning, and not an error.  Excess actuals
		are ignored; missing actuals are turned into null strings.

Incompatibility:
	The virgule '/' in "a=/*b" is interpreted as the first character of
		the pair "/*" which introduces a comment, rather than as the
		second character of the divide-and-replace operator "=/".
		This incompatibility reflects the recent change in the C language
		which made "a/=*b" the legal way to write such a statement
		if the meaning "a=a/ *b" is intended.
Commit	Line	Data
f23cb965	1	#
9372792e	2	# @(#)README 1.2 %G%
f23cb965	3	#
9372792e RH	4	August 30, 1982
	5	Fixed by Kurt Shoens, UCB
	6	If the "#line n name" occurs, then all future references
	7	to the current file are generated in terms of "name", instead
	8	of the name of file given to cpp in its command argument
	9
f23cb965 RH	10	August 25, 1978
	11
	12	Files in this directory form the C preprocessor, which handles '#include'
	13	files and macro definition and expansion for the C compiler.
	14	This new version was written by John F. Reiser and is from 5 to 12
	15	times faster (on UNIX systems) than the old.
	16
	17	To create the executable file 'cpp' in the current directory:
	18	make
	19
	20	To install the preprocessor 'cpp' so it will be used by the C compiler:
	21	: safety first: backup the existing version
	22	cp /lib/cpp /lib/ocpp
	23	: install the new version
	24	cp cpp /lib/cpp
	25
	26	Invocation
	27	cpp [-CEPR] [-Dname] ... [-Dname=def] ... [-Idirectory] ...
	28	[-Uname] ... [<infile>] [<outfile>]
	29
	30	If there are two non-flag arguments then the first is the name of the
	31	input file and the second is the name of the output file. If there is
	32	one non-flag argument then it is the name of the input file and the
	33	output is written on the standard output. If there are no non-flag
	34	arguments then the input is taken from the standard input and the output
	35	is written on the standard output. Flag arguments are:
	36
	37	-C retain comments in output
	38	-Dname define name as "1"
	39	-Dname=def define name as def
	40	-E ignored
	41	-Idirectory add directory to search list for #include files
	42	-P don't insert lines "# 12 \"foo.c\"" into output
	43	-R allow recursive macros
	44	-Uname undefine name
	45
	46	Documentation clarifications:
	47	Symbols defined on the command line by "-Dfoo" are defined as "1",
	48	i.e., as if they had been defined by "#define foo 1" or "-Dfoo=1".
	49	The directory search order for #include files is
	50	1) the directory of the file which contains the #include request
	51	(e.g. #include is relative to the file being scanned when
	52	the request is made)
	53	2) the directories specified by -I, in left-to-right order
	54	3) the standard directory(s) (which for UNIX is /usr/include)
	55	An unescaped linefeed (the single character "\n") terminates a
	56	character constant or quoted string.
	57	An escaped linefeed (the two-character sequence "\\\n") may be
	58	used in the body of a '#define' statement to continue
	59	the definition onto the next line. The escaped linefeed is
	60	not included in the macro body.
	61	Comments are uniformly removed (except if the argument -C is specified).
	62	They are also ignored, except that a comment terminates a token.
	63	Thus "foo/* la di da */bar" may expand 'foo' and 'bar' but
	64	will never expand 'foobar'. If neither 'foo' nor 'bar' is a
	65	macro then the output is "foobar", even if 'foobar'
	66	is defined as something else. The file
	67	#define foo(a,b)b/**/a
	68	foo(1,2)
	69	produces "21" because the comment causes a break which enables
	70	the recognition of 'b' and 'a' as formals in the string "b/**/a".
	71	Macro formal parameters are recognized in '#define' bodies even inside
	72	character constants and quoted strings. The output from
	73	#define foo(a) '\a'
74	foo(bar)
75	is the seven characters " '\\bar'". Macro names are not recognized
76	inside character constants or quoted strings during the regular scan.
77	Thus
78	#define foo bar
79	printf("foo");
80	does not expand 'foo' in the second line, because it is inside
81	a quoted string which is not part of a '#define' macro definition.
82	Macros are not expanded while processing a '#define' or '#undef'.
83	Thus
84	#define foo bletch
85	#define bar foo
86	#undef foo
87	bar
88	produces "foo". The token appearing immediately after a
89	'#ifdef' or '#ifndef' is not expanded (of course!).
90	Macros are not expanded during the scan which determines the actual
91	parameters to another macro call. Thus
92	#define foo(a,b)b a
93	#define bar hi
94	foo(bar,
95	#define bar bye
96	)
97	produces " bye" (and warns about the redefinition of 'bar').
98
99	There are some differences between the new and the old preprocessor.
100	Bugs fixed:
101	"1.e4" is recognized as a floating-point number, rather than as an
102	opportunity to expand the possible macro name "e4".
103	Any kind and amount of white space (space, tab, linefeed, vertical tab,
104	formfeed, carriage return) is allowed between a macro name and
105	the left parenthesis which introduces its actual parameters.
106	The comma operator is legal in preprocessor '#if' statements.
107	Macros with parameters are legal in preprocessor '#if' statements.
108	Single-character character constants are legal in preprocessor '#if' statements.
109	Linefeeds are put out in the proper place when a multiline comment
110	is not passed through to the output.
111	The following example expands to "# # #" :
112	#define foo #
113	foo foo foo
114	If the -R flag is not specified then the invocation of some recursive
115	macros is trapped and the recursion forcibly terminated with an
116	error message. The recursions that are trapped are the ones
117	in which the nesting level is non-decreasing from some point on.
118	In particular,
119	#define a a
120	a
121	will be detected. (Use "#undef a" if that is what you want.)
122	The recursion
123	#define a c b
124	#define b c a
125	#define c foo
126	a
127	will not be detected because the nesting level decreases after
128	each expansion of "c".
129	The -R flag specifically allows recursive macros and recursion will
130	be strictly obeyed (to the extent that space is available).
131	Assuming that -R is specified:
132	#define a a
133	a
134	causes an infinite loop with very little output. The tail recursion
135	#define a <b
136	#define b >a
137	a
138	causes the string "<>" to be output infinitely many times. The
139	non-tail recursion
140	#define a b>
141	#define b a<
142	a
143	complains "too much pushback", dumps the pushback, and continues
144	(again, infinitely).
145
146	Stylistic choice:
147	Nothing (not even linefeeds) is output while a false '#if', '#ifdef',
148	or '#ifndef' is in effect. Thus when all conditions become true
149	a line of the form "# 12345 \"foo.c\"" is output (unless -P).
150	Error and warning messages always appear on standard error (file
151	descriptor 2).
152	Mismatch between the number of formals and actuals in a macro call
153	produces only a warning, and not an error. Excess actuals
154	are ignored; missing actuals are turned into null strings.
155
156	Incompatibility:
157	The virgule '/' in "a=/*b" is interpreted as the first character of
158	the pair "/*" which introduces a comment, rather than as the
159	second character of the divide-and-replace operator "=/".
160	This incompatibility reflects the recent change in the C language
161	which made "a/=*b" the legal way to write such a statement
162	if the meaning "a=a/ *b" is intended.