r10829: Documentation updates

Update TODO
Some small fixes to the modules
(This used to be commit 0c53e7c3cf7fd91fd34c48a5e68c1bcf70569854)

8 files changed, 180 insertions, 100 deletions

diff --git a/source4/pidl/TODO b/source4/pidl/TODO
index 9fc3a7d904..ca5047c0d7 100644
--- a/source4/pidl/TODO
+++ b/source4/pidl/TODO
@@ -1,16 +1,17 @@
-- True multiple dimension array / strings in arrays support
+- true multiple dimension array / strings in arrays support
 
 - compatibility mode for generating MIDL-readable data:
  - strip out pidl-specific properties
- - convert subcontext() to an array of uint8.
- - perhaps replace subcontext() with something more generic? The argument
- to subcontext() isn't really intuitive at the moment
 
 - don't be so strict on array boundaries.. arrays can and will be empty when 
   a (regular) remote error occurs
  
 - support nested elements
 
-- Don't output [ref] pointers for Samba 4?
+- auto-alloc [ref] pointers for Samba4 during pull if they were NULL
  
-- alternative to subcontext()
+- better replacement for subcontext()
+
+- --explain-ndr option that dumps out parse tree
+
+- fix test suite
diff --git a/source4/pidl/lib/Parse/Pidl/Dump.pm b/source4/pidl/lib/Parse/Pidl/Dump.pm
index 80219a8f1a..3a1cec1b59 100644
--- a/source4/pidl/lib/Parse/Pidl/Dump.pm
+++ b/source4/pidl/lib/Parse/Pidl/Dump.pm
@@ -1,8 +1,22 @@
 ###################################################
 # dump function for IDL structures
 # Copyright tridge@samba.org 2000
+# Copyright jelmer@samba.org 2005
 # released under the GNU GPL
 
+=pod
+
+=head1 NAME
+
+Parse::Pidl::Dump - Dump support
+
+=head1 DESCRIPTION
+
+This module provides functions that can generate IDL code from 
+internal pidl data structures.
+
+=cut
+
 package Parse::Pidl::Dump;
 
 use Exporter;
diff --git a/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm b/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm
index 706a259306..1b550ae1e7 100644
--- a/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm
+++ b/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm
@@ -3,6 +3,81 @@
 # Copyright jelmer@samba.org 2005
 # released under the GNU GPL
 
+=pod
+
+=head1 NAME
+
+Parse::Pidl::Ethereal::Conformance - Conformance file parser for Ethereal
+
+=head1 DESCRIPTION
+
+This module supports parsing Ethereal conformance files (*.cnf).
+
+=head1 FILE FORMAT
+
+Pidl needs additional data for ethereal output. This data is read from 
+so-called conformance files. This section describes the format of these 
+files.
+
+Conformance files are simple text files with a single command on each line.
+Empty lines and lines starting with a '#' character are ignored.
+Arguments to commands are seperated by spaces.
+
+The following commands are currently supported:
+
+=over 4
+
+=item I<TYPE> name dissector ft_type base_type mask valsstring alignment
+
+Register new data type with specified name, what dissector function to call 
+and what properties to give header fields for elements of this type.
+
+=item I<NOEMIT> type
+
+Suppress emitting a dissect_type function for the specified type
+
+=item I<PARAM_VALUE> type param
+
+Set parameter to specify to dissector function for given type.
+
+=item I<HF_FIELD> hf title filter ft_type base_type valsstring mask description
+
+Generate a custom header field with specified properties.
+
+=item I<HF_RENAME> old_hf_name new_hf_name
+
+Force the use of new_hf_name when the parser generator was going to 
+use old_hf_name.
+
+This can be used in conjunction with HF_FIELD in order to make more then 
+one element use the same filter name.
+
+=item I<STRIP_PREFIX> prefix
+
+Remove the specified prefix from all function names (if present).
+	
+=item I<PROTOCOL> longname shortname filtername
+
+Change the short-, long- and filter-name for the current interface in
+Ethereal.
+
+=item I<FIELD_DESCRIPTION> field desc
+
+Change description for the specified header field. `field' is the hf name of the field.
+
+=item I<IMPORT> dissector code...
+
+Code to insert when generating the specified dissector. @HF@ and 
+@PARAM@ will be substituted.
+
+=back
+
+=head1 EXAMPLE
+
+	INFO_KEY OpenKey.Ke
+
+=cut
+
 package Parse::Pidl::Ethereal::Conformance;
 
 require Exporter;
diff --git a/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm b/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm
index be542638ef..8a4c0ed60c 100644
--- a/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm
+++ b/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm
@@ -6,6 +6,14 @@
 # Portions based on idl2eth.c by Ronnie Sahlberg
 # released under the GNU GPL
 
+=pod
+
+=head1 NAME
+
+Parse::Pidl::Ethereal::NDR - Parser generator for Ethereal
+
+=cut
+
 package Parse::Pidl::Ethereal::NDR;
 
 use strict;
diff --git a/source4/pidl/lib/Parse/Pidl/NDR.pm b/source4/pidl/lib/Parse/Pidl/NDR.pm
index 64190e87b8..f975e07b15 100644
--- a/source4/pidl/lib/Parse/Pidl/NDR.pm
+++ b/source4/pidl/lib/Parse/Pidl/NDR.pm
@@ -5,6 +5,26 @@
 # Copyright jelmer@samba.org 2004-2005
 # released under the GNU GPL
 
+=pod
+
+=head1 NAME
+
+Parse::Pidl::NDR - NDR parsing information generator
+
+=head1 DESCRIPTION
+
+#####################################################################
+# return a table describing the order in which the parts of an element
+# should be parsed
+# Possible level types:
+#  - POINTER
+#  - ARRAY
+#  - SUBCONTEXT
+#  - SWITCH
+#  - DATA
+
+=cut
+
 package Parse::Pidl::NDR;
 
 require Exporter;
@@ -62,15 +82,6 @@ sub fatal($$)
 	die("$pos->{FILE}:$pos->{LINE}:$s\n");
 }
 
-#####################################################################
-# return a table describing the order in which the parts of an element
-# should be parsed
-# Possible level types:
-#  - POINTER
-#  - ARRAY
-#  - SUBCONTEXT
-#  - SWITCH
-#  - DATA
 sub GetElementLevelTable($)
 {
 	my $e = shift;
@@ -394,6 +405,7 @@ sub ParseUnion($)
 
 	if (has_property($e, "nodiscriminant")) { $switch_type = undef; }
 	
+	my $hasdefault = 0;
 	foreach my $x (@{$e->{ELEMENTS}}) 
 	{
 		my $t;
@@ -404,6 +416,7 @@ sub ParseUnion($)
 		}
 		if (has_property($x, "default")) {
 			$t->{CASE} = "default";
+			$hasdefault = 1;
 		} elsif (defined($x->{PROPERTIES}->{case})) {
 			$t->{CASE} = "case $x->{PROPERTIES}->{case}";
 		} else {
@@ -417,6 +430,7 @@ sub ParseUnion($)
 		SWITCH_TYPE => $switch_type,
 		ELEMENTS => \@elements,
 		PROPERTIES => $e->{PROPERTIES},
+		HAS_DEFAULT => $hasdefault,
 		ORIGINAL => $e
 	};
 }
diff --git a/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm b/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm
index 78bd8fe339..25102e511a 100644
--- a/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm
+++ b/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm
@@ -31,7 +31,6 @@ sub ParseElement($)
 			return if ($l->{POINTER_TYPE} eq "ref" and $l->{LEVEL} eq "top");
 			pidl "\tuint32 ptr$l->{POINTER_INDEX}_$e->{NAME};";
 		} elsif ($l->{TYPE} eq "SWITCH") {
-			pidl "\tuint32 level_$e->{NAME};";
 		} elsif ($l->{TYPE} eq "DATA") {
 			pidl "\t" . DeclShort($e) . ";";
 		} elsif ($l->{TYPE} eq "ARRAY") {
@@ -106,30 +105,28 @@ sub ParseUnion($$$)
 
 	my $extra = {};
 	
-	unless (has_property($u, "nodiscriminant")) {
-		$extra->{switch_value} = 1;
-	}
+	$extra->{switch_value} = $u->{SWITCH_TYPE};
 
 	foreach my $e (@{$u->{ELEMENTS}}) {
 		foreach my $l (@{$e->{LEVELS}}) {
 			if ($l->{TYPE} eq "ARRAY") {
 				if ($l->{IS_CONFORMANT}) {
-					$extra->{"size"} = 1;
+					$extra->{"size"} = "uint32";
 				}
 				if ($l->{IS_VARYING}) {
-					$extra->{"length"} = $extra->{"offset"} = 1;
+					$extra->{"length"} = $extra->{"offset"} = "uint32";
 				}
 			} elsif ($l->{TYPE} eq "POINTER") {
-				$extra->{"ptr$l->{POINTER_INDEX}"} = 1;
+				$extra->{"ptr$l->{POINTER_INDEX}"} = "uint32";
 			} elsif ($l->{TYPE} eq "SWITCH") {
-				$extra->{"level"} = 1;
+				$extra->{"level"} = "uint32";
 			}
 		}
 	}
 
 	pidl "typedef struct $if->{NAME}_$n\_ctr {";
 	indent;
-	pidl "uint32 $_;" foreach (keys %$extra);
+	pidl "$extra->{$_} $_;" foreach (keys %$extra);
 	pidl "union $if->{NAME}_$n {";
 	indent;
 	foreach (@{$u->{ELEMENTS}}) {
diff --git a/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm b/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm
index eaab50b553..c6cc188391 100644
--- a/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm
+++ b/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm
@@ -75,8 +75,18 @@ sub ParseElementLevelData($$$$$$$)
 
 	# See if we need to add a level argument because we're parsing a union
 	foreach (@{$e->{LEVELS}}) {
-		push (@args, ParseExpr("level_$e->{NAME}", $env)) 
-			if ($_->{TYPE} eq "SWITCH");
+		next unless ($_->{TYPE} eq "SWITCH");
+		my $t = getType($l->{DATA_TYPE});
+
+		# Set 0 here because one of the variables referenced in SWITCH_IS 
+		# might be an in variable while this one is [out]
+		if (grep(/in/, @{$e->{DIRECTION}}) or 
+			not defined($t) or 
+			has_property($t->{DATA}, "nodiscriminant")) {
+			push (@args, ParseExpr($_->{SWITCH_IS}, $env));
+		} else {
+			push (@args, -1);
+		}	
 	}
 
 	my $c = DissectType(@args);
@@ -263,7 +273,6 @@ sub GenerateEnvElement($$)
 		} elsif ($l->{TYPE} eq "POINTER") {
 			$env->{"ptr$l->{POINTER_INDEX}_$e->{NAME}"} = "v->ptr$l->{POINTER_INDEX}_$e->{NAME}";
 		} elsif ($l->{TYPE} eq "SWITCH") {
-			$env->{"level_$e->{NAME}"} = "v->level_$e->{NAME}";
 		} elsif ($l->{TYPE} eq "ARRAY") {
 			$env->{"length_$e->{NAME}"} = "v->length_$e->{NAME}";
 			$env->{"size_$e->{NAME}"} = "v->size_$e->{NAME}";
@@ -368,7 +377,6 @@ sub UnionGenerateEnvElement($)
 		} elsif ($l->{TYPE} eq "POINTER") {
 			$env->{"ptr$l->{POINTER_INDEX}_$e->{NAME}"} = "v->ptr$l->{POINTER_INDEX}";
 		} elsif ($l->{TYPE} eq "SWITCH") {
-			$env->{"level_$e->{NAME}"} = "v->level";
 		} elsif ($l->{TYPE} eq "ARRAY") {
 			$env->{"length_$e->{NAME}"} = "v->length";
 			$env->{"size_$e->{NAME}"} = "v->size";
@@ -394,15 +402,20 @@ sub ParseUnion($$$)
 	indent;
 	DeclareArrayVariables($u->{ELEMENTS});
 
-	unless (has_property($u, "nodiscriminant")) {
-		pidl "if (!prs_uint32(\"switch_value\", ps, depth, &v->switch_value))";
+	if (defined ($u->{SWITCH_TYPE})) {
+		pidl "if (MARSHALLING(ps)) ";
+		pidl "\tv->switch_value = level;";
+		pidl "";
+		pidl "if (!prs_$u->{SWITCH_TYPE}(\"switch_value\", ps, depth, &v->switch_value))";
 		pidl "\treturn False;";
 		pidl "";
+	} else {
+		pidl "v->switch_value = level;";
 	}
 
 	# Maybe check here that level and v->switch_value are equal?
 
-	pidl "switch (level) {";
+	pidl "switch (v->switch_value) {";
 	indent;
 
 	foreach (@{$u->{ELEMENTS}}) {
@@ -420,19 +433,30 @@ sub ParseUnion($$$)
 		pidl "";
 	}
 
+	unless ($u->{HAS_DEFAULT}) {
+		pidl "default:";
+		pidl "\treturn False;";
+		pidl "";
+	}
+
 	deindent;
 	pidl "}";
 	pidl "";
 	pidl "return True;";
 	deindent;
 	pidl "}";
+	pidl "";
 
 	pidl "BOOL $dfn(const char *desc, $sn* v, uint32 level, prs_struct *ps, int depth)";
 	pidl "{";
 	indent;
 	DeclareArrayVariables($u->{ELEMENTS});
 
-	pidl "switch (level) {";
+	if (defined($u->{SWITCH_TYPE})) {
+		pidl "switch (v->switch_value) {";
+	} else {
+		pidl "switch (level) {";
+	}
 	indent;
 
 	foreach (@{$u->{ELEMENTS}}) {
diff --git a/source4/pidl/pidl b/source4/pidl/pidl
index 07bfefa956..1e77b59be9 100755
--- a/source4/pidl/pidl
+++ b/source4/pidl/pidl
@@ -8,13 +8,15 @@
 # released under the GNU GPL
 
 =pod
+
 =head1 NAME
 
-pidl - IDL Compiler written in Perl
+pidl - An IDL compiler written in Perl
 
 =head1 SYNOPSIS
 
 pidl --help
+
 pidl [--outputdir[=OUTNAME]] [--parse-idl-tree] [--dump-idl-tree] [--dump-ndr-tree] [--ndr-header[=OUTPUT]] [--header[=OUTPUT]] [--ejs[=OUTPUT]] [--swig[=OUTPUT]] [--uint-enums] [--ndr-parser[=OUTPUT]] [--client] [--server] [--dcom-proxy] [--com-header] [--warn-compat] [--quiet] [--verbose] [--template] [--eth-parser[=OUTPUT]] [--diff] [--dump-idl] [--tdr-header=[OUTPUT]] [--tdr-parser[=OUTPUT]] [--samba3-header[=OUTPUT]] [--samba3-parser=[OUTPUT]] [--samba3-server=[OUTPUT]] [--samba3-template[=OUTPUT]] [--samba3-client[=OUTPUT]] [<idlfile>.idl]...
 
 =head1 DESCRIPTION
@@ -95,8 +97,8 @@ packet-dcerpc-OUTNAME.h.
 	
 Pidl will read additional data from an ethereal conformance file if present. 
 Such a file should have the same location as the IDL file but with the 
-extension I<cnf> rather then I<idl>. See below for details on the format of 
-this file.
+extension I<cnf> rather then I<idl>. See L<Parse::Pidl::Ethereal::Conformance>
+for details on the format of this file.
 
 =item I<--diff>
 
@@ -354,82 +356,26 @@ oleautomation, optional, pragma, propget, propputref, propput, readonly,
 requestedit, restricted, retval, source, transmit_as, uidefault, 
 usesgetlasterror, vararg, vi_progid, wire_marshal. 
 
-=head1 ETHEREAL CONFORMANCE FILES
-
-Pidl needs additional data for ethereal output. This data is read from 
-so-called conformance files. This section describes the format of these 
-files.
-
-Conformance files are simple text files with a single command on each line.
-Empty lines and lines starting with a '#' character are ignored.
-Arguments to commands are seperated by spaces.
-
-The following commands are currently supported:
-
-=over 4
-
-=item I<TYPE> name dissector ft_type base_type mask valsstring alignment
-
-Register new data type with specified name, what dissector function to call 
-and what properties to give header fields for elements of this type.
-
-=item I<NOEMIT> type
-
-Suppress emitting a dissect_type function for the specified type
-
-=item I<PARAM_VALUE> type param
-
-Set parameter to specify to dissector function for given type.
-
-=item I<HF_FIELD> hf title filter ft_type base_type valsstring mask description
-
-Generate a custom header field with specified properties.
-
-=item I<HF_RENAME> old_hf_name new_hf_name
-
-Force the use of new_hf_name when the parser generator was going to 
-use old_hf_name.
-
-This can be used in conjunction with HF_FIELD in order to make more then 
-one element use the same filter name.
-
-=item I<STRIP_PREFIX> prefix
-
-Remove the specified prefix from all function names (if present).
-	
-=item I<PROTOCOL> longname shortname filtername
-
-Change the short-, long- and filter-name for the current interface in
-Ethereal.
-
-=item I<FIELD_DESCRIPTION> field desc
-
-Change description for the specified header field. `field' is the hf name of the field.
-
-=item I<IMPORT> dissector code...
-
-Code to insert when generating the specified dissector. @HF@ and 
-@PARAM@ will be substituted.
-
-=back
-
 =head1 EXAMPLES
 
 	# Generating an ethereal parser
 	$ ./pidl --eth-parser -- atsvc.idl
 	
-	# Generating a TDR parser
+	# Generating a TDR parser and header
 	$ ./pidl --tdr-parser --tdr-header --header -- regf.idl
 
-=head1 VERSION
+	# Generating a Samba3 parser, client and server
+	$ ./pidl --samba3-parser --samba3-server --samba3-client -- dfs.idl
 
-This man page is correct for version 4.0 of the Samba suite. L<http://www.samba.org/>.
+	# Generating a Samba4 NDR parser, client and server
+	$ ./pidl --ndr-parser --ndr-client --ndr-server -- samr.idl
 
 =head1 SEE ALSO
 
 L<http://msdn.microsoft.com/library/en-us/rpc/rpc/field_attributes.asp>,
 L<http://wiki.ethereal.com/DCE/RPC>, 
-yapp(1)
+L<http://www.samba.org/>,
+L<yapp(1)>
 
 =head1 LICENSE
 
@@ -438,7 +384,7 @@ pidl is licensed under the GNU General Public License L<http://www.gnu.org/licen
 =head1 AUTHOR
 
 pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim Potter and Jelmer 
-Vernooij. 
+Vernooij. The current maintainer is Jelmer Vernooij.
 
 This manpage was written by Jelmer Vernooij, partially based on the original 
 pidl README by Andrew Tridgell. 
@@ -536,7 +482,8 @@ my($opt_warn_compat) = 0;
 sub ShowHelp()
 {
 print "perl IDL parser and code generator
-Copyright (C) tridge\@samba.org
+Copyright (C) Andrew Tridgell <tridge\@samba.org>
+Copyright (C) Jelmer Vernooij <jelmer\@samba.org>
 
 Usage: pidl [options] [--] <idlfile> [<idlfile>...]