[linux-2.6-block.git] / Documentation / sphinx / parse-headers.pl

#!/usr/bin/perl
use strict;
use Text::Tabs;

# Uncomment if debug is needed
#use Data::Dumper;

# change to 1 to generate some debug prints
my $debug = 0;

if (scalar @ARGV < 2 || scalar @ARGV > 3) {
	die "Usage:\n\t$0 <file in> <file out> [<exceptions file>]\n";
}

my ($file_in, $file_out, $file_exceptions) = @ARGV;

my $data;
my %ioctls;
my %defines;
my %typedefs;
my %enums;
my %enum_symbols;
my %structs;

#
# read the file and get identifiers
#

my $is_enum = 0;
open IN, $file_in or die "Can't open $file_in";
while (<IN>) {
	my $ln = $_;
	$ln =~ s,/\*.*\*/,,;

	$data .= $_;

	if ($is_enum && $ln =~ m/^\s*([_A-Z][^\s\}\,\=]+)\s*[\,=]?/) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;
		$n =~ tr/_/-/;

		$enum_symbols{$s} = $n;

		$is_enum = 0 if ($is_enum && m/\}/);
		next;
	}
	$is_enum = 0 if ($is_enum && m/\}/);

	if ($ln =~ m/^\s*#\s*define\s+([_A-Z]\S+)\s+_IO/) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;

		$ioctls{$s} = $n;
		next;
	}

	if ($ln =~ m/^\s*#\s*define\s+([_A-Z]\S+)\s+/) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;
		$n =~ tr/_/-/;

		$defines{$s} = $n;
		next;
	}

	if ($ln =~ m/^\s*typedef\s+.*\s+([_\w]\S+);/) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;
		$n =~ tr/_/-/;

		$typedefs{$s} = $n;
		next;
	}
	if ($ln =~ m/^\s*enum\s+(\S+)\s+\{/
	    || $ln =~ m/^\s*enum\s+(\S+)$/) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;
		$n =~ tr/_/-/;

		$enums{$s} = $n;

		$is_enum = $1;
		next;
	}
	if ($ln =~ m/^\s*struct\s+([_A-Za-z_]\S+)\s+\{/
	    || $ln =~ m/^\s*struct\s+([A-Za-z_]\S+)$/) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;
		$n =~ tr/_/-/;

		$structs{$s} = $n;
		next;
	}
}
close IN;

#
# Handle multi-line typedefs
#

my @matches = $data =~ m/typedef\s+struct\s+\S+\s*\{[^\}]+\}\s*(\S+)\s*\;/g;
foreach my $m (@matches) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;
		$n =~ tr/_/-/;

		$typedefs{$s} = $n;
	next;
}

#
# Handle exceptions, if any
#

if ($file_exceptions) {
	open IN, $file_exceptions or die "Can't read $file_exceptions";
	while (<IN>) {
		next if (m/^\s*$/ || m/^\s*#/);

		# Parsers to ignore a symbol

		if (m/^ignore\s+ioctl\s+(\S+)/) {
			delete $ioctls{$1} if (exists($ioctls{$1}));
			next;
		}
		if (m/^ignore\s+define\s+(\S+)/) {
			delete $defines{$1} if (exists($defines{$1}));
			next;
		}
		if (m/^ignore\s+typedef\s+(\S+)/) {
			delete $typedefs{$1} if (exists($typedefs{$1}));
			next;
		}
		if (m/^ignore\s+enum\s+(\S+)/) {
			delete $enums{$1} if (exists($enums{$1}));
			next;
		}
		if (m/^ignore\s+struct\s+(\S+)/) {
			delete $structs{$1} if (exists($structs{$1}));
			next;
		}

		# Parsers to replace a symbol

		if (m/^replace\s+ioctl\s+(\S+)\s+(\S+)/) {
			$ioctls{$1} = $2 if (exists($ioctls{$1}));
			next;
		}
		if (m/^replace\s+define\s+(\S+)\s+(\S+)/) {
			$defines{$1} = $2 if (exists($defines{$1}));
			next;
		}
		if (m/^replace\s+typedef\s+(\S+)\s+(\S+)/) {
			$typedefs{$1} = $2 if (exists($typedefs{$1}));
			next;
		}
		if (m/^replace\s+enum\s+(\S+)\s+(\S+)/) {
			$enums{$1} = $2 if (exists($enums{$1}));
			next;
		}
		if (m/^replace\s+symbol\s+(\S+)\s+(\S+)/) {
			$enum_symbols{$1} = $2 if (exists($enum_symbols{$1}));
			next;
		}
		if (m/^replace\s+struct\s+(\S+)\s+(\S+)/) {
			$structs{$1} = $2 if (exists($structs{$1}));
			next;
		}

		die "Can't parse $file_exceptions: $_";
	}
}

if ($debug) {
	print Data::Dumper->Dump([\%ioctls], [qw(*ioctls)]) if (%ioctls);
	print Data::Dumper->Dump([\%typedefs], [qw(*typedefs)]) if (%typedefs);
	print Data::Dumper->Dump([\%enums], [qw(*enums)]) if (%enums);
	print Data::Dumper->Dump([\%structs], [qw(*structs)]) if (%structs);
	print Data::Dumper->Dump([\%defines], [qw(*defines)]) if (%defines);
	print Data::Dumper->Dump([\%enum_symbols], [qw(*enum_symbols)]) if (%enum_symbols);
}

#
# Align block
#
$data = expand($data);
$data = "    " . $data;
$data =~ s/\n/\n    /g;
$data =~ s/\n\s+$/\n/g;
$data =~ s/\n\s+\n/\n\n/g;

#
# Add escape codes for special characters
#
$data =~ s,([\_\`\*\<\>\&\\\\:\/]),\\$1,g;

$data =~ s,DEPRECATED,**DEPRECATED**,g;

#
# Add references
#

my $start_delim = "[ \n\t\(\=\*\@]";
my $end_delim = "(\\s|,|\\\\=|\\\\:|\\;|\\\)|\\}|\\{)";

foreach my $r (keys %ioctls) {
	my $n = $ioctls{$r};

	my $s = "\\ :ref:`$r <$n>`\\ ";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
}

foreach my $r (keys %defines) {
	my $n = $defines{$r};

	my $s = "\\ :ref:`$r <$n>`\\ ";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
}

foreach my $r (keys %enum_symbols) {
	my $n = $enum_symbols{$r};

	my $s = "\\ :ref:`$r <$n>`\\ ";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
}

foreach my $r (keys %enums) {
	my $n = $enums{$r};

	my $s = "\\ :ref:`enum $r <$n>`\\ ";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/enum\s+($r)$end_delim/$s$2/g;
}

foreach my $r (keys %structs) {
	my $n = $structs{$r};

	my $s = "\\ :ref:`struct $r <$n>`\\ ";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/struct\s+($r)$end_delim/$s$2/g;
}

foreach my $r (keys %typedefs) {
	my $n = $typedefs{$r};

	my $s = "\\ :ref:`$r <$n>`\\ ";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
}

#
# Generate output file
#

my $title = $file_in;
$title =~ s,.*/,,;

open OUT, "> $file_out" or die "Can't open $file_out";
print OUT ".. -*- coding: utf-8; mode: rst -*-\n\n";
print OUT "$title\n";
print OUT "=" x length($title);
print OUT "\n\n.. parsed-literal::\n\n";
print OUT $data;
close OUT;
Commit	Line	Data
dabf8be3 MCC	1	#!/usr/bin/perl
	2	use strict;
	3	use Text::Tabs;
	4
	5	# Uncomment if debug is needed
	6	#use Data::Dumper;
	7
	8	# change to 1 to generate some debug prints
	9	my $debug = 0;
	10
	11	if (scalar @ARGV < 2 \|\| scalar @ARGV > 3) {
	12	die "Usage:\n\t$0 <file in> <file out> [<exceptions file>]\n";
	13	}
	14
	15	my ($file_in, $file_out, $file_exceptions) = @ARGV;
	16
	17	my $data;
	18	my %ioctls;
	19	my %defines;
	20	my %typedefs;
	21	my %enums;
	22	my %enum_symbols;
	23	my %structs;
	24
	25	#
	26	# read the file and get identifiers
	27	#
	28
	29	my $is_enum = 0;
	30	open IN, $file_in or die "Can't open $file_in";
	31	while (<IN>) {
9afe5112 MCC	32	my $ln = $_;
	33	$ln =~ s,/\.\*/,,;
	34
dabf8be3 MCC	35	$data .= $_;
dabf8be3 MCC	36
9afe5112	37	if ($is_enum && $ln =~ m/^\s([_A-Z][^\s\}\,\=]+)\s[\,=]?/) {
dabf8be3 MCC	38	my $s = $1;
	39	my $n = $1;
	40	$n =~ tr/A-Z/a-z/;
	41	$n =~ tr/_/-/;
	42
	43	$enum_symbols{$s} = $n;
	44
	45	$is_enum = 0 if ($is_enum && m/\}/);
	46	next;
	47	}
	48	$is_enum = 0 if ($is_enum && m/\}/);
	49
9afe5112	50	if ($ln =~ m/^\s#\sdefine\s+([_A-Z]\S+)\s+_IO/) {
dabf8be3 MCC	51	my $s = $1;
	52	my $n = $1;
	53	$n =~ tr/A-Z/a-z/;
	54
	55	$ioctls{$s} = $n;
	56	next;
	57	}
	58
9afe5112	59	if ($ln =~ m/^\s#\sdefine\s+([_A-Z]\S+)\s+/) {
dabf8be3 MCC	60	my $s = $1;
	61	my $n = $1;
	62	$n =~ tr/A-Z/a-z/;
	63	$n =~ tr/_/-/;
	64
	65	$defines{$s} = $n;
	66	next;
	67	}
	68
9afe5112	69	if ($ln =~ m/^\stypedef\s+.\s+([_\w]\S+);/) {
dabf8be3 MCC	70	my $s = $1;
	71	my $n = $1;
	72	$n =~ tr/A-Z/a-z/;
	73	$n =~ tr/_/-/;
	74
	75	$typedefs{$s} = $n;
	76	next;
	77	}
9afe5112 MCC	78	if ($ln =~ m/^\s*enum\s+(\S+)\s+\{/
9afe5112 MCC	79	\|\| $ln =~ m/^\s*enum\s+(\S+)$/) {
dabf8be3 MCC	80	my $s = $1;
	81	my $n = $1;
	82	$n =~ tr/A-Z/a-z/;
	83	$n =~ tr/_/-/;
	84
	85	$enums{$s} = $n;
	86
	87	$is_enum = $1;
	88	next;
	89	}
9afe5112 MCC	90	if ($ln =~ m/^\s*struct\s+([_A-Za-z_]\S+)\s+\{/
9afe5112 MCC	91	\|\| $ln =~ m/^\s*struct\s+([A-Za-z_]\S+)$/) {
dabf8be3 MCC	92	my $s = $1;
	93	my $n = $1;
	94	$n =~ tr/A-Z/a-z/;
	95	$n =~ tr/_/-/;
	96
	97	$structs{$s} = $n;
	98	next;
	99	}
	100	}
	101	close IN;
	102
	103	#
	104	# Handle multi-line typedefs
	105	#
	106
	107	my @matches = $data =~ m/typedef\s+struct\s+\S+\s\{[^\}]+\}\s(\S+)\s*\;/g;
	108	foreach my $m (@matches) {
	109	my $s = $1;
	110	my $n = $1;
	111	$n =~ tr/A-Z/a-z/;
	112	$n =~ tr/_/-/;
	113
	114	$typedefs{$s} = $n;
	115	next;
	116	}
	117
	118	#
	119	# Handle exceptions, if any
	120	#
	121
	122	if ($file_exceptions) {
	123	open IN, $file_exceptions or die "Can't read $file_exceptions";
	124	while (<IN>) {
	125	next if (m/^\s$/ \|\| m/^\s#/);
	126
	127	# Parsers to ignore a symbol
	128
	129	if (m/^ignore\s+ioctl\s+(\S+)/) {
	130	delete $ioctls{$1} if (exists($ioctls{$1}));
	131	next;
	132	}
	133	if (m/^ignore\s+define\s+(\S+)/) {
	134	delete $defines{$1} if (exists($defines{$1}));
	135	next;
	136	}
	137	if (m/^ignore\s+typedef\s+(\S+)/) {
	138	delete $typedefs{$1} if (exists($typedefs{$1}));
	139	next;
	140	}
	141	if (m/^ignore\s+enum\s+(\S+)/) {
	142	delete $enums{$1} if (exists($enums{$1}));
	143	next;
	144	}
	145	if (m/^ignore\s+struct\s+(\S+)/) {
	146	delete $structs{$1} if (exists($structs{$1}));
	147	next;
	148	}
	149
	150	# Parsers to replace a symbol
	151
	152	if (m/^replace\s+ioctl\s+(\S+)\s+(\S+)/) {
	153	$ioctls{$1} = $2 if (exists($ioctls{$1}));
	154	next;
	155	}
156	if (m/^replace\s+define\s+(\S+)\s+(\S+)/) {
157	$defines{$1} = $2 if (exists($defines{$1}));
158	next;
159	}
160	if (m/^replace\s+typedef\s+(\S+)\s+(\S+)/) {
161	$typedefs{$1} = $2 if (exists($typedefs{$1}));
162	next;
163	}
164	if (m/^replace\s+enum\s+(\S+)\s+(\S+)/) {
165	$enums{$1} = $2 if (exists($enums{$1}));
166	next;
167	}
168	if (m/^replace\s+symbol\s+(\S+)\s+(\S+)/) {
169	$enum_symbols{$1} = $2 if (exists($enum_symbols{$1}));
170	next;
171	}
172	if (m/^replace\s+struct\s+(\S+)\s+(\S+)/) {
173	$structs{$1} = $2 if (exists($structs{$1}));
174	next;
175	}
176
177	die "Can't parse $file_exceptions: $_";
178	}
179	}
180
181	if ($debug) {
182	print Data::Dumper->Dump([\%ioctls], [qw(*ioctls)]) if (%ioctls);
183	print Data::Dumper->Dump([\%typedefs], [qw(*typedefs)]) if (%typedefs);
184	print Data::Dumper->Dump([\%enums], [qw(*enums)]) if (%enums);
185	print Data::Dumper->Dump([\%structs], [qw(*structs)]) if (%structs);
186	print Data::Dumper->Dump([\%defines], [qw(*defines)]) if (%defines);
187	print Data::Dumper->Dump([\%enum_symbols], [qw(*enum_symbols)]) if (%enum_symbols);
188	}
189
190	#
191	# Align block
192	#
193	$data = expand($data);
194	$data = " " . $data;
195	$data =~ s/\n/\n /g;
196	$data =~ s/\n\s+$/\n/g;
197	$data =~ s/\n\s+\n/\n\n/g;
198
199	#
200	# Add escape codes for special characters
201	#
202	$data =~ s,([\_\`\*\<\>\&\\\\:\/]),\\$1,g;
203
7d95fa8d MCC	204	$data =~ s,DEPRECATED,DEPRECATED,g;
7d95fa8d MCC	205
dabf8be3 MCC	206	#
	207	# Add references
	208	#
	209
6fe79d1e MCC	210	my $start_delim = "[ \n\t\(\=\*\@]";
6fe79d1e MCC	211	my $end_delim = "(\\s\|,\|\\\\=\|\\\\:\|\\;\|\\\)\|\\}\|\\{)";
dabf8be3 MCC	212
	213	foreach my $r (keys %ioctls) {
	214	my $n = $ioctls{$r};
	215
6fe79d1e	216	my $s = "\\ :ref:`$r <$n>`\\ ";
dabf8be3 MCC	217
	218	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	219
	220	print "$r -> $s\n" if ($debug);
	221
6fe79d1e	222	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
dabf8be3 MCC	223	}
	224
	225	foreach my $r (keys %defines) {
	226	my $n = $defines{$r};
	227
6fe79d1e	228	my $s = "\\ :ref:`$r <$n>`\\ ";
dabf8be3 MCC	229
	230	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	231
	232	print "$r -> $s\n" if ($debug);
	233
6fe79d1e	234	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
dabf8be3 MCC	235	}
	236
	237	foreach my $r (keys %enum_symbols) {
	238	my $n = $enum_symbols{$r};
	239
6fe79d1e	240	my $s = "\\ :ref:`$r <$n>`\\ ";
dabf8be3 MCC	241
	242	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	243
	244	print "$r -> $s\n" if ($debug);
	245
6fe79d1e	246	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
dabf8be3 MCC	247	}
	248
	249	foreach my $r (keys %enums) {
	250	my $n = $enums{$r};
	251
6fe79d1e	252	my $s = "\\ :ref:`enum $r <$n>`\\ ";
dabf8be3 MCC	253
	254	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	255
	256	print "$r -> $s\n" if ($debug);
	257
6fe79d1e	258	$data =~ s/enum\s+($r)$end_delim/$s$2/g;
dabf8be3 MCC	259	}
	260
	261	foreach my $r (keys %structs) {
	262	my $n = $structs{$r};
	263
6fe79d1e	264	my $s = "\\ :ref:`struct $r <$n>`\\ ";
dabf8be3 MCC	265
	266	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	267
	268	print "$r -> $s\n" if ($debug);
	269
6fe79d1e	270	$data =~ s/struct\s+($r)$end_delim/$s$2/g;
dabf8be3 MCC	271	}
	272
	273	foreach my $r (keys %typedefs) {
	274	my $n = $typedefs{$r};
	275
6fe79d1e	276	my $s = "\\ :ref:`$r <$n>`\\ ";
dabf8be3 MCC	277
	278	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	279
	280	print "$r -> $s\n" if ($debug);
	281
6fe79d1e	282	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
dabf8be3 MCC	283	}
	284
	285	#
	286	# Generate output file
	287	#
	288
	289	my $title = $file_in;
	290	$title =~ s,.*/,,;
	291
	292	open OUT, "> $file_out" or die "Can't open $file_out";
	293	print OUT ".. -- coding: utf-8; mode: rst --\n\n";
	294	print OUT "$title\n";
	295	print OUT "=" x length($title);
	296	print OUT "\n\n.. parsed-literal::\n\n";
	297	print OUT $data;
	298	close OUT;