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

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 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:
	: backup the existing version
	cp /lib/cpp /lib/ocpp
	: install the new version
	cp cpp /lib/cpp

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".
	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.  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 formals are recognized even inside character constants
		and quoted strings.  The output from
			#define foo(a) '\a'
			foo(bar)
		is the seven characters " '\\bar'".
	Macros are not expanded while processing a '#define' or '#undef'.
		Thus
			#define foo bletch
			#define bar foo
			#undef foo
			bar
		produces "foo".
	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
	Recursion in macro definitions is strictly obeyed (to the extent that
		space is available).  In particular,
			#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.
	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
8150d190 KT	1	Files in this directory form the C preprocessor, which handles '#include'
	2	files and macro definition and expansion for the C compiler.
	3	This new version was written by John F. Reiser and is from 5 to 12
	4	times faster than the old.
	5
	6	To create the executable file 'cpp' in the current directory:
	7	make
	8
	9	To install the preprocessor 'cpp' so it will be used by the C compiler:
	10	: backup the existing version
	11	cp /lib/cpp /lib/ocpp
	12	: install the new version
	13	cp cpp /lib/cpp
	14
	15	Documentation clarifications:
	16	Symbols defined on the command line by "-Dfoo" are defined as "1",
	17	i.e., as if they had been defined by "#define foo 1" or "-Dfoo=1".
	18	An unescaped linefeed (the single character "\n") terminates a
	19	character constant or quoted string.
	20	An escaped linefeed (the two-character sequence "\\\n") may be
	21	used in the body of a '#define' statement to continue
	22	the definition onto the next line. The escaped linefeed is
	23	not included in the macro body.
	24	Comments are uniformly removed. They are also ignored, except
	25	that a comment terminates a token.
	26	Thus "foo/* la di da */bar" may expand 'foo' and 'bar' but
	27	will never expand 'foobar'. If neither 'foo' nor 'bar' is a
	28	macro then the output is "foobar", even if 'foobar'
	29	is defined as something else. The file
	30	#define foo(a,b)b/**/a
	31	foo(1,2)
	32	produces "21" because the comment causes a break which enables
	33	the recognition of 'b' and 'a' as formals in the string "b/**/a".
	34	Macro formals are recognized even inside character constants
	35	and quoted strings. The output from
	36	#define foo(a) '\a'
	37	foo(bar)
	38	is the seven characters " '\\bar'".
	39	Macros are not expanded while processing a '#define' or '#undef'.
	40	Thus
	41	#define foo bletch
	42	#define bar foo
	43	#undef foo
	44	bar
	45	produces "foo".
	46	Macros are not expanded during the scan which determines the actual
	47	parameters to another macro call. Thus
	48	#define foo(a,b)b a
	49	#define bar hi
	50	foo(bar,
	51	#define bar bye
	52	)
	53	produces " bye" (and warns about the redefinition of 'bar').
	54
	55	There are some differences between the new and the old preprocessor.
	56	Bugs fixed:
	57	"1.e4" is recognized as a floating-point number, rather than as an
	58	opportunity to expand the possible macro name "e4".
	59	Any kind and amount of white space (space, tab, linefeed, vertical tab,
	60	formfeed, carriage return) is allowed between a macro name and
	61	the left parenthesis which introduces its actual parameters.
	62	The comma operator is legal in preprocessor '#if' statements.
	63	Macros with parameters are legal in preprocessor '#if' statements.
	64	Single-character character constants are legal in preprocessor '#if' statements.
65	Linefeeds are put out in the proper place when a multiline comment
66	is not passed through to the output.
67	The following example expands to "# # #" :
68	#define foo #
69	foo foo foo
70	Recursion in macro definitions is strictly obeyed (to the extent that
71	space is available). In particular,
72	#define a a
73	a
74	causes an infinite loop with very little output. The tail recursion
75	#define a <b
76	#define b >a
77	a
78	causes the string "<>" to be output infinitely many times. The
79	non-tail recursion
80	#define a b>
81	#define b a<
82	a
83	complains "too much pushback", dumps the pushback, and continues
84	(again, infinitely).
85
86	Stylistic choice:
87	Nothing (not even linefeeds) is output while a false '#if', '#ifdef',
88	or '#ifndef' is in effect. Thus when all conditions become true
89	a line of the form "# 12345 foo.c" is output.
90	Error and warning messages always appear on standard error (file
91	descriptor 2).
92	Mismatch between the number of formals and actuals in a macro call
93	produces only a warning, and not an error. Excess actuals
94	are ignored; missing actuals are turned into null strings.
95
96	Incompatibility:
97	The virgule '/' in "a=/*b" is interpreted as the first character of
98	the pair "/*" which introduces a comment, rather than as the
99	second character of the divide-and-replace operator "=/".
100	This incompatibility reflects the recent change in the C language
101	which made "a/=*b" the legal way to write such a statement
102	if the meaning "a=a/ *b" is intended.