[mirror_ubuntu-bionic-kernel.git] / Documentation / sphinx / parse-headers.pl

#!/usr/bin/perl
use strict;
use Text::Tabs;
use Getopt::Long;
use Pod::Usage;

my $debug;
my $help;
my $man;

GetOptions(
	"debug" => \$debug,
	'help|?' => \$help,
	man => \$man
) or pod2usage(2);

pod2usage(1) if $help;
pod2usage(-exitstatus => 0, -verbose => 2) if $man;
pod2usage(2) if (scalar @ARGV < 2 || scalar @ARGV > 3);

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

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

require Data::Dumper if ($debug);

#
# read the file and get identifiers
#

my $is_enum = 0;
my $is_comment = 0;
open IN, $file_in or die "Can't open $file_in";
while (<IN>) {
	$data .= $_;

	my $ln = $_;
	if (!$is_comment) {
		$ln =~ s,/\*.*(\*/),,g;

		$is_comment = 1 if ($ln =~ s,/\*.*,,);
	} else {
		if ($ln =~ s,^(.*\*/),,) {
			$is_comment = 0;
		} else {
			next;
		}
	}

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

		$enum_symbols{$s} =  "\\ :ref:`$s <$n>`\\ ";

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

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

		$ioctls{$s} = "\\ :ref:`$s <$n>`\\ ";
		next;
	}

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

		$defines{$s} = "\\ :ref:`$s <$n>`\\ ";
		next;
	}

	if ($ln =~ m/^\s*typedef\s+([_\w][\w\d_]+)\s+(.*)\s+([_\w][\w\d_]+);/) {
		my $s = $2;
		my $n = $3;

		$typedefs{$n} = "\\ :c:type:`$n <$s>`\\ ";
		next;
	}
	if ($ln =~ m/^\s*enum\s+([_\w][\w\d_]+)\s+\{/
	    || $ln =~ m/^\s*enum\s+([_\w][\w\d_]+)$/
	    || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)\s+\{/
	    || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)$/) {
		my $s = $1;

		$enums{$s} =  "enum :c:type:`$s`\\ ";

		$is_enum = $1;
		next;
	}
	if ($ln =~ m/^\s*struct\s+([_\w][\w\d_]+)\s+\{/
	    || $ln =~ m/^\s*struct\s+([[_\w][\w\d_]+)$/
	    || $ln =~ m/^\s*typedef\s*struct\s+([_\w][\w\d_]+)\s+\{/
	    || $ln =~ m/^\s*typedef\s*struct\s+([[_\w][\w\d_]+)$/
	    ) {
		my $s = $1;

		$structs{$s} = "struct :c:type:`$s`\\ ";
		next;
	}
}
close IN;

#
# Handle multi-line typedefs
#

my @matches = ($data =~ m/typedef\s+struct\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,
	       $data =~ m/typedef\s+enum\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,);
foreach my $m (@matches) {
	my $s = $m;

	$typedefs{$s} = "\\ :c:type:`$s`\\ ";
	next;
}

#
# Handle exceptions, if any
#

my %def_reftype = (
	"ioctl"   => ":ref",
	"define"  => ":ref",
	"symbol"  => ":ref",
	"typedef" => ":c:type",
	"enum"    => ":c:type",
	"struct"  => ":c:type",
);

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;
		}
		if (m/^ignore\s+symbol\s+(\S+)/) {
			delete $enum_symbols{$1} if (exists($enum_symbols{$1}));
			next;
		}

		# Parsers to replace a symbol
		my ($type, $old, $new, $reftype);

		if (m/^replace\s+(\S+)\s+(\S+)\s+(\S+)/) {
			$type = $1;
			$old = $2;
			$new = $3;
		} else {
			die "Can't parse $file_exceptions: $_";
		}

		if ($new =~ m/^\:c\:(data|func|macro|type)\:\`(.+)\`/) {
			$reftype = ":c:$1";
			$new = $2;
		} elsif ($new =~ m/\:ref\:\`(.+)\`/) {
			$reftype = ":ref";
			$new = $1;
		} else {
			$reftype = $def_reftype{$type};
		}
		$new = "$reftype:`$old <$new>`";

		if ($type eq "ioctl") {
			$ioctls{$old} = $new if (exists($ioctls{$old}));
			next;
		}
		if ($type eq "define") {
			$defines{$old} = $new if (exists($defines{$old}));
			next;
		}
		if ($type eq "symbol") {
			$enum_symbols{$old} = $new if (exists($enum_symbols{$old}));
			next;
		}
		if ($type eq "typedef") {
			$typedefs{$old} = $new if (exists($typedefs{$old}));
			next;
		}
		if ($type eq "enum") {
			$enums{$old} = $new if (exists($enums{$old}));
			next;
		}
		if ($type eq "struct") {
			$structs{$old} = $new if (exists($structs{$old}));
			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 $s = $ioctls{$r};

	$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 $s = $defines{$r};

	$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 $s = $enum_symbols{$r};

	$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 $s = $enums{$r};

	$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 $s = $structs{$r};

	$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 $s = $typedefs{$r};

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

	print "$r -> $s\n" if ($debug);
	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
}

$data =~ s/\\ ([\n\s])/\1/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;

__END__

=head1 NAME

parse_headers.pl - parse a C file, in order to identify functions, structs,
enums and defines and create cross-references to a Sphinx book.

=head1 SYNOPSIS

B<parse_headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]

Where <options> can be: --debug, --help or --man.

=head1 OPTIONS

=over 8

=item B<--debug>

Put the script in verbose mode, useful for debugging.

=item B<--help>

Prints a brief help message and exits.

=item B<--man>

Prints the manual page and exits.

=back

=head1 DESCRIPTION

Convert a C header or source file (C_FILE), into a ReStructured Text
included via ..parsed-literal block with cross-references for the
documentation files that describe the API. It accepts an optional
EXCEPTIONS_FILE with describes what elements will be either ignored or
be pointed to a non-default reference.

The output is written at the (OUT_FILE).

It is capable of identifying defines, functions, structs, typedefs,
enums and enum symbols and create cross-references for all of them.
It is also capable of distinguish #define used for specifying a Linux
ioctl.

The EXCEPTIONS_FILE contain two types of statements: B<ignore> or B<replace>.

The syntax for the ignore tag is:

=over 8

ignore B<type> B<name>

=back

The B<ignore> means that it won't generate cross references for a
B<name> symbol of type B<type>.

The syntax for the replace tag is:

=over 8

replace B<type> B<name> B<new_value>

=back

The B<replace> means that it will generate cross references for a
B<name> symbol of type B<type>, but, instead of using the default
replacement rule, it will use B<new_value>.

For both statements, B<type> can be either one of the following:

=over 8

=item B<ioctl>

The ignore or replace statement will apply to ioctl definitions like:

#define	VIDIOC_DBG_S_REGISTER 	 _IOW('V', 79, struct v4l2_dbg_register)

=item B<define>

The ignore or replace statement will apply to any other #define found
at C_FILE.

=item B<typedef>

The ignore or replace statement will apply to typedef statements at C_FILE.

=item B<struct>

The ignore or replace statement will apply to the name of struct statements
at C_FILE.

=item B<enum>

The ignore or replace statement will apply to the name of enum statements
at C_FILE.

=item B<symbol>

The ignore or replace statement will apply to the name of enum statements
at C_FILE.


For replace statements, B<new_value> will automatically use :c:type:
references for B<typedef>, B<enum> and B<struct> types. It will use :ref:
for B<ioctl>, B<define> and B<symbol> types. The type of reference can
also be explicitly defined at the replace statement.

=back

=head1 EXAMPLES

ignore define _VIDEODEV2_H

=over 8


Ignore a #define _VIDEODEV2_H at the C_FILE.

=back

ignore symbol PRIVATE

=over 8

On a struct like:

enum foo { BAR1, BAR2, PRIVATE };

It won't generate cross-references for B<PRIVATE>.

=back

replace symbol BAR1 :c:type:`foo`
replace symbol BAR2 :c:type:`foo`

=over 8

On a struct like:

enum foo { BAR1, BAR2, PRIVATE };

It will make the BAR1 and BAR2 enum symbols to cross reference the foo
symbol at the C domain.

=back

=head1 BUGS

Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com>

=head1 COPYRIGHT

Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.

License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.

This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

=cut
Commit	Line	Data
dabf8be3 MCC	1	#!/usr/bin/perl
	2	use strict;
	3	use Text::Tabs;
327f5a75 MCC	4	use Getopt::Long;
327f5a75 MCC	5	use Pod::Usage;
dabf8be3	6
327f5a75 MCC	7	my $debug;
	8	my $help;
	9	my $man;
dabf8be3	10
327f5a75 MCC	11	GetOptions(
	12	"debug" => \$debug,
	13	'help\|?' => \$help,
	14	man => \$man
	15	) or pod2usage(2);
bcec7c21	16
327f5a75 MCC	17	pod2usage(1) if $help;
	18	pod2usage(-exitstatus => 0, -verbose => 2) if $man;
	19	pod2usage(2) if (scalar @ARGV < 2 \|\| scalar @ARGV > 3);
dabf8be3 MCC	20
	21	my ($file_in, $file_out, $file_exceptions) = @ARGV;
	22
	23	my $data;
	24	my %ioctls;
	25	my %defines;
	26	my %typedefs;
	27	my %enums;
	28	my %enum_symbols;
	29	my %structs;
	30
327f5a75 MCC	31	require Data::Dumper if ($debug);
327f5a75 MCC	32
dabf8be3 MCC	33	#
	34	# read the file and get identifiers
	35	#
	36
	37	my $is_enum = 0;
034e6c8e	38	my $is_comment = 0;
dabf8be3 MCC	39	open IN, $file_in or die "Can't open $file_in";
dabf8be3 MCC	40	while (<IN>) {
034e6c8e MCC	41	$data .= $_;
034e6c8e MCC	42
9afe5112	43	my $ln = $_;
034e6c8e MCC	44	if (!$is_comment) {
034e6c8e MCC	45	$ln =~ s,/\.(\*/),,g;
9afe5112	46
034e6c8e MCC	47	$is_comment = 1 if ($ln =~ s,/\.,,);
	48	} else {
	49	if ($ln =~ s,^(.\/),,) {
	50	$is_comment = 0;
	51	} else {
	52	next;
	53	}
	54	}
dabf8be3	55
9c80c745	56	if ($is_enum && $ln =~ m/^\s([_\w][\w\d_]+)\s[\,=]?/) {
dabf8be3 MCC	57	my $s = $1;
	58	my $n = $1;
	59	$n =~ tr/A-Z/a-z/;
	60	$n =~ tr/_/-/;
	61
22c40033	62	$enum_symbols{$s} = "\\ :ref:`$s <$n>`\\ ";
dabf8be3 MCC	63
	64	$is_enum = 0 if ($is_enum && m/\}/);
	65	next;
	66	}
	67	$is_enum = 0 if ($is_enum && m/\}/);
	68
9c80c745	69	if ($ln =~ m/^\s#\sdefine\s+([_\w][\w\d_]+)\s+_IO/) {
dabf8be3 MCC	70	my $s = $1;
	71	my $n = $1;
	72	$n =~ tr/A-Z/a-z/;
	73
22c40033	74	$ioctls{$s} = "\\ :ref:`$s <$n>`\\ ";
dabf8be3 MCC	75	next;
	76	}
	77
9c80c745	78	if ($ln =~ m/^\s#\sdefine\s+([_\w][\w\d_]+)\s+/) {
dabf8be3 MCC	79	my $s = $1;
	80	my $n = $1;
	81	$n =~ tr/A-Z/a-z/;
	82	$n =~ tr/_/-/;
	83
22c40033	84	$defines{$s} = "\\ :ref:`$s <$n>`\\ ";
dabf8be3 MCC	85	next;
	86	}
	87
22c40033 MCC	88	if ($ln =~ m/^\stypedef\s+([_\w][\w\d_]+)\s+(.)\s+([_\w][\w\d_]+);/) {
	89	my $s = $2;
	90	my $n = $3;
dabf8be3	91
22c40033	92	$typedefs{$n} = "\\ :c:type:`$n <$s>`\\ ";
dabf8be3 MCC	93	next;
dabf8be3 MCC	94	}
9c80c745	95	if ($ln =~ m/^\s*enum\s+([_\w][\w\d_]+)\s+\{/
6c4c7dad MCC	96	\|\| $ln =~ m/^\s*enum\s+([_\w][\w\d_]+)$/
	97	\|\| $ln =~ m/^\stypedef\senum\s+([_\w][\w\d_]+)\s+\{/
	98	\|\| $ln =~ m/^\stypedef\senum\s+([_\w][\w\d_]+)$/) {
dabf8be3	99	my $s = $1;
dabf8be3	100
22c40033	101	$enums{$s} = "enum :c:type:`$s`\\ ";
dabf8be3 MCC	102
	103	$is_enum = $1;
	104	next;
	105	}
9c80c745	106	if ($ln =~ m/^\s*struct\s+([_\w][\w\d_]+)\s+\{/
6c4c7dad MCC	107	\|\| $ln =~ m/^\s*struct\s+([[_\w][\w\d_]+)$/
	108	\|\| $ln =~ m/^\stypedef\sstruct\s+([_\w][\w\d_]+)\s+\{/
	109	\|\| $ln =~ m/^\stypedef\sstruct\s+([[_\w][\w\d_]+)$/
	110	) {
dabf8be3	111	my $s = $1;
dabf8be3	112
22c40033	113	$structs{$s} = "struct :c:type:`$s`\\ ";
dabf8be3 MCC	114	next;
	115	}
	116	}
	117	close IN;
	118
	119	#
	120	# Handle multi-line typedefs
	121	#
	122
4ff916a0 MCC	123	my @matches = ($data =~ m/typedef\s+struct\s+\S+?\s\{[^\}]+\}\s(\S+)\s*\;/g,
4ff916a0 MCC	124	$data =~ m/typedef\s+enum\s+\S+?\s\{[^\}]+\}\s(\S+)\s*\;/g,);
dabf8be3	125	foreach my $m (@matches) {
22c40033	126	my $s = $m;
dabf8be3	127
22c40033	128	$typedefs{$s} = "\\ :c:type:`$s`\\ ";
dabf8be3 MCC	129	next;
	130	}
	131
	132	#
	133	# Handle exceptions, if any
	134	#
	135
22c40033 MCC	136	my %def_reftype = (
	137	"ioctl" => ":ref",
	138	"define" => ":ref",
	139	"symbol" => ":ref",
	140	"typedef" => ":c:type",
	141	"enum" => ":c:type",
	142	"struct" => ":c:type",
	143	);
	144
dabf8be3 MCC	145	if ($file_exceptions) {
	146	open IN, $file_exceptions or die "Can't read $file_exceptions";
	147	while (<IN>) {
	148	next if (m/^\s$/ \|\| m/^\s#/);
	149
	150	# Parsers to ignore a symbol
	151
	152	if (m/^ignore\s+ioctl\s+(\S+)/) {
	153	delete $ioctls{$1} if (exists($ioctls{$1}));
	154	next;
	155	}
	156	if (m/^ignore\s+define\s+(\S+)/) {
	157	delete $defines{$1} if (exists($defines{$1}));
	158	next;
	159	}
	160	if (m/^ignore\s+typedef\s+(\S+)/) {
	161	delete $typedefs{$1} if (exists($typedefs{$1}));
	162	next;
	163	}
	164	if (m/^ignore\s+enum\s+(\S+)/) {
	165	delete $enums{$1} if (exists($enums{$1}));
	166	next;
	167	}
	168	if (m/^ignore\s+struct\s+(\S+)/) {
	169	delete $structs{$1} if (exists($structs{$1}));
	170	next;
	171	}
526b8848 MCC	172	if (m/^ignore\s+symbol\s+(\S+)/) {
	173	delete $enum_symbols{$1} if (exists($enum_symbols{$1}));
	174	next;
	175	}
dabf8be3 MCC	176
dabf8be3 MCC	177	# Parsers to replace a symbol
22c40033	178	my ($type, $old, $new, $reftype);
dabf8be3	179
22c40033 MCC	180	if (m/^replace\s+(\S+)\s+(\S+)\s+(\S+)/) {
	181	$type = $1;
	182	$old = $2;
	183	$new = $3;
	184	} else {
	185	die "Can't parse $file_exceptions: $_";
	186	}
	187
	188	if ($new =~ m/^\:c\:(data\|func\|macro\|type)\:\`(.+)\`/) {
	189	$reftype = ":c:$1";
	190	$new = $2;
	191	} elsif ($new =~ m/\:ref\:\`(.+)\`/) {
	192	$reftype = ":ref";
	193	$new = $1;
	194	} else {
	195	$reftype = $def_reftype{$type};
	196	}
	197	$new = "$reftype:`$old <$new>`";
	198
	199	if ($type eq "ioctl") {
	200	$ioctls{$old} = $new if (exists($ioctls{$old}));
dabf8be3 MCC	201	next;
dabf8be3 MCC	202	}
22c40033 MCC	203	if ($type eq "define") {
22c40033 MCC	204	$defines{$old} = $new if (exists($defines{$old}));
dabf8be3 MCC	205	next;
dabf8be3 MCC	206	}
22c40033 MCC	207	if ($type eq "symbol") {
22c40033 MCC	208	$enum_symbols{$old} = $new if (exists($enum_symbols{$old}));
dabf8be3 MCC	209	next;
dabf8be3 MCC	210	}
22c40033 MCC	211	if ($type eq "typedef") {
22c40033 MCC	212	$typedefs{$old} = $new if (exists($typedefs{$old}));
dabf8be3 MCC	213	next;
dabf8be3 MCC	214	}
22c40033 MCC	215	if ($type eq "enum") {
22c40033 MCC	216	$enums{$old} = $new if (exists($enums{$old}));
dabf8be3 MCC	217	next;
dabf8be3 MCC	218	}
22c40033 MCC	219	if ($type eq "struct") {
22c40033 MCC	220	$structs{$old} = $new if (exists($structs{$old}));
dabf8be3 MCC	221	next;
	222	}
	223
	224	die "Can't parse $file_exceptions: $_";
	225	}
	226	}
	227
	228	if ($debug) {
	229	print Data::Dumper->Dump([\%ioctls], [qw(*ioctls)]) if (%ioctls);
	230	print Data::Dumper->Dump([\%typedefs], [qw(*typedefs)]) if (%typedefs);
	231	print Data::Dumper->Dump([\%enums], [qw(*enums)]) if (%enums);
	232	print Data::Dumper->Dump([\%structs], [qw(*structs)]) if (%structs);
	233	print Data::Dumper->Dump([\%defines], [qw(*defines)]) if (%defines);
	234	print Data::Dumper->Dump([\%enum_symbols], [qw(*enum_symbols)]) if (%enum_symbols);
	235	}
	236
	237	#
	238	# Align block
	239	#
	240	$data = expand($data);
	241	$data = " " . $data;
	242	$data =~ s/\n/\n /g;
	243	$data =~ s/\n\s+$/\n/g;
	244	$data =~ s/\n\s+\n/\n\n/g;
	245
	246	#
	247	# Add escape codes for special characters
	248	#
999d998e	249	$data =~ s,([\_\`\*\<\>\&\\\\:\/\\|\%\$\#\{\}\~\^]),\\$1,g;
dabf8be3	250
7d95fa8d MCC	251	$data =~ s,DEPRECATED,DEPRECATED,g;
7d95fa8d MCC	252
dabf8be3 MCC	253	#
	254	# Add references
	255	#
	256
6fe79d1e MCC	257	my $start_delim = "[ \n\t\(\=\*\@]";
6fe79d1e MCC	258	my $end_delim = "(\\s\|,\|\\\\=\|\\\\:\|\\;\|\\\)\|\\}\|\\{)";
dabf8be3 MCC	259
dabf8be3 MCC	260	foreach my $r (keys %ioctls) {
22c40033	261	my $s = $ioctls{$r};
dabf8be3 MCC	262
	263	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	264
	265	print "$r -> $s\n" if ($debug);
	266
6fe79d1e	267	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
dabf8be3 MCC	268	}
	269
	270	foreach my $r (keys %defines) {
22c40033	271	my $s = $defines{$r};
dabf8be3 MCC	272
	273	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	274
	275	print "$r -> $s\n" if ($debug);
	276
6fe79d1e	277	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
dabf8be3 MCC	278	}
	279
	280	foreach my $r (keys %enum_symbols) {
22c40033	281	my $s = $enum_symbols{$r};
dabf8be3 MCC	282
	283	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	284
	285	print "$r -> $s\n" if ($debug);
	286
6fe79d1e	287	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
dabf8be3 MCC	288	}
	289
	290	foreach my $r (keys %enums) {
22c40033	291	my $s = $enums{$r};
dabf8be3 MCC	292
	293	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	294
	295	print "$r -> $s\n" if ($debug);
	296
6fe79d1e	297	$data =~ s/enum\s+($r)$end_delim/$s$2/g;
dabf8be3 MCC	298	}
	299
	300	foreach my $r (keys %structs) {
22c40033	301	my $s = $structs{$r};
dabf8be3 MCC	302
	303	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	304
	305	print "$r -> $s\n" if ($debug);
	306
6fe79d1e	307	$data =~ s/struct\s+($r)$end_delim/$s$2/g;
dabf8be3 MCC	308	}
	309
	310	foreach my $r (keys %typedefs) {
22c40033	311	my $s = $typedefs{$r};
dabf8be3 MCC	312
	313	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	314
	315	print "$r -> $s\n" if ($debug);
6fe79d1e	316	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
dabf8be3 MCC	317	}
dabf8be3 MCC	318
22c40033	319	$data =~ s/\\ ([\n\s])/\1/g;
fb6fc6c9	320
dabf8be3 MCC	321	#
	322	# Generate output file
	323	#
	324
	325	my $title = $file_in;
	326	$title =~ s,.*/,,;
	327
	328	open OUT, "> $file_out" or die "Can't open $file_out";
	329	print OUT ".. -- coding: utf-8; mode: rst --\n\n";
	330	print OUT "$title\n";
	331	print OUT "=" x length($title);
	332	print OUT "\n\n.. parsed-literal::\n\n";
	333	print OUT $data;
	334	close OUT;
327f5a75 MCC	335
	336	__END__
	337
	338	=head1 NAME
	339
	340	parse_headers.pl - parse a C file, in order to identify functions, structs,
	341	enums and defines and create cross-references to a Sphinx book.
	342
	343	=head1 SYNOPSIS
	344
	345	B<parse_headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
	346
	347	Where <options> can be: --debug, --help or --man.
	348
	349	=head1 OPTIONS
	350
	351	=over 8
	352
	353	=item B<--debug>
	354
	355	Put the script in verbose mode, useful for debugging.
	356
	357	=item B<--help>
	358
	359	Prints a brief help message and exits.
	360
	361	=item B<--man>
	362
	363	Prints the manual page and exits.
	364
	365	=back
	366
	367	=head1 DESCRIPTION
	368
	369	Convert a C header or source file (C_FILE), into a ReStructured Text
	370	included via ..parsed-literal block with cross-references for the
	371	documentation files that describe the API. It accepts an optional
	372	EXCEPTIONS_FILE with describes what elements will be either ignored or
	373	be pointed to a non-default reference.
	374
	375	The output is written at the (OUT_FILE).
	376
	377	It is capable of identifying defines, functions, structs, typedefs,
	378	enums and enum symbols and create cross-references for all of them.
	379	It is also capable of distinguish #define used for specifying a Linux
	380	ioctl.
	381
	382	The EXCEPTIONS_FILE contain two types of statements: B<ignore> or B<replace>.
	383
	384	The syntax for the ignore tag is:
	385
	386	=over 8
	387
	388	ignore B<type> B<name>
	389
	390	=back
	391
	392	The B<ignore> means that it won't generate cross references for a
	393	B<name> symbol of type B<type>.
	394
	395	The syntax for the replace tag is:
	396
	397	=over 8
	398
399	replace B<type> B<name> B<new_value>
400
401	=back
402
403	The B<replace> means that it will generate cross references for a
404	B<name> symbol of type B<type>, but, instead of using the default
405	replacement rule, it will use B<new_value>.
406
407	For both statements, B<type> can be either one of the following:
408
409	=over 8
410
411	=item B<ioctl>
412
413	The ignore or replace statement will apply to ioctl definitions like:
414
415	#define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
416
417	=item B<define>
418
419	The ignore or replace statement will apply to any other #define found
420	at C_FILE.
421
422	=item B<typedef>
423
424	The ignore or replace statement will apply to typedef statements at C_FILE.
425
426	=item B<struct>
427
428	The ignore or replace statement will apply to the name of struct statements
429	at C_FILE.
430
431	=item B<enum>
432
433	The ignore or replace statement will apply to the name of enum statements
434	at C_FILE.
435
436	=item B<symbol>
437
438	The ignore or replace statement will apply to the name of enum statements
439	at C_FILE.
440
441
442	For replace statements, B<new_value> will automatically use :c:type:
443	references for B<typedef>, B<enum> and B<struct> types. It will use :ref:
444	for B<ioctl>, B<define> and B<symbol> types. The type of reference can
445	also be explicitly defined at the replace statement.
446
447	=back
448
449	=head1 EXAMPLES
450
451	ignore define _VIDEODEV2_H
452
453	=over 8
454
455
456	Ignore a #define _VIDEODEV2_H at the C_FILE.
457
458	=back
459
460	ignore symbol PRIVATE
461
462	=over 8
463
464	On a struct like:
465
466	enum foo { BAR1, BAR2, PRIVATE };
467
468	It won't generate cross-references for B<PRIVATE>.
469
470	=back
471
472	replace symbol BAR1 :c:type:`foo`
473	replace symbol BAR2 :c:type:`foo`
474
475	=over 8
476
477	On a struct like:
478
479	enum foo { BAR1, BAR2, PRIVATE };
480
481	It will make the BAR1 and BAR2 enum symbols to cross reference the foo
482	symbol at the C domain.
483
484	=back
485
486	=head1 BUGS
487
488	Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com>
489
490	=head1 COPYRIGHT
491
492	Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
493
494	License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
495
496	This is free software: you are free to change and redistribute it.
497	There is NO WARRANTY, to the extent permitted by law.
498
499	=cut