Scanner-based parsing with support for element erasing

Also implement argv_file_scanner which provides support for reading command
line arguments from the argv array as well as files specified with command
line options. New examples: file. New tests: ctor, erase, file.

11 files changed, 649 insertions, 1 deletions

diff --git a/examples/README b/examples/README
index d333f11..84ef156 100644
--- a/examples/README
+++ b/examples/README
@@ -9,3 +9,7 @@ hello
 
 features
   Shows how to use various features of the CLI language.
+
+file
+  Shows how to allow the users of your application to supply options in 
+  files in addition to the command line.
diff --git a/examples/examples-8.0.sln b/examples/examples-8.0.sln
index 8b7e077..aded850 100644
--- a/examples/examples-8.0.sln
+++ b/examples/examples-8.0.sln
@@ -5,6 +5,8 @@ Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "hello", "hello\hello-8.0.vc
 EndProject

 Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "features", "features\features-8.0.vcproj", "{FA7FD071-4FF6-4EB3-96E0-95366AB2CA6F}"

 EndProject

+Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "file", "file\file-8.0.vcproj", "{ECCD3577-1DB2-4F38-9ED7-757433B8D66F}"

+EndProject

 Global

 	GlobalSection(SolutionConfigurationPlatforms) = preSolution

 		Debug|Win32 = Debug|Win32

@@ -19,6 +21,10 @@ Global
 		{FA7FD071-4FF6-4EB3-96E0-95366AB2CA6F}.Debug|Win32.Build.0 = Debug|Win32

 		{FA7FD071-4FF6-4EB3-96E0-95366AB2CA6F}.Release|Win32.ActiveCfg = Release|Win32

 		{FA7FD071-4FF6-4EB3-96E0-95366AB2CA6F}.Release|Win32.Build.0 = Release|Win32

+		{ECCD3577-1DB2-4F38-9ED7-757433B8D66F}.Debug|Win32.ActiveCfg = Debug|Win32

+		{ECCD3577-1DB2-4F38-9ED7-757433B8D66F}.Debug|Win32.Build.0 = Debug|Win32

+		{ECCD3577-1DB2-4F38-9ED7-757433B8D66F}.Release|Win32.ActiveCfg = Release|Win32

+		{ECCD3577-1DB2-4F38-9ED7-757433B8D66F}.Release|Win32.Build.0 = Release|Win32

 	EndGlobalSection

 	GlobalSection(SolutionProperties) = preSolution

 		HideSolutionNode = FALSE

diff --git a/examples/examples-9.0.sln b/examples/examples-9.0.sln
index 8a2d2b5..d0c1be5 100644
--- a/examples/examples-9.0.sln
+++ b/examples/examples-9.0.sln
@@ -5,6 +5,8 @@ Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "hello", "hello\hello-9.0.vc
 EndProject

 Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "features", "features\features-9.0.vcproj", "{A2A8DB0D-FA16-4F85-9775-8ADBDD06AE90}"

 EndProject

+Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "file", "file\file-9.0.vcproj", "{ECCD3577-1DB2-4F38-9ED7-757433B8D66F}"

+EndProject

 Global

 	GlobalSection(SolutionConfigurationPlatforms) = preSolution

 		Debug|Win32 = Debug|Win32

@@ -19,6 +21,10 @@ Global
 		{A2A8DB0D-FA16-4F85-9775-8ADBDD06AE90}.Debug|Win32.Build.0 = Debug|Win32

 		{A2A8DB0D-FA16-4F85-9775-8ADBDD06AE90}.Release|Win32.ActiveCfg = Release|Win32

 		{A2A8DB0D-FA16-4F85-9775-8ADBDD06AE90}.Release|Win32.Build.0 = Release|Win32

+		{ECCD3577-1DB2-4F38-9ED7-757433B8D66F}.Debug|Win32.ActiveCfg = Debug|Win32

+		{ECCD3577-1DB2-4F38-9ED7-757433B8D66F}.Debug|Win32.Build.0 = Debug|Win32

+		{ECCD3577-1DB2-4F38-9ED7-757433B8D66F}.Release|Win32.ActiveCfg = Release|Win32

+		{ECCD3577-1DB2-4F38-9ED7-757433B8D66F}.Release|Win32.Build.0 = Release|Win32

 	EndGlobalSection

 	GlobalSection(SolutionProperties) = preSolution

 		HideSolutionNode = FALSE

diff --git a/examples/file/README b/examples/file/README
new file mode 100644
index 0000000..289fc64
--- /dev/null
+++ b/examples/file/README
@@ -0,0 +1,38 @@
+This example shows how to allow the users of your application to supply
+options in files in addition to the command line.
+
+The example consists of the following files:
+
+options.cli
+  Command line interface description in the CLI language.
+
+options.hxx
+options.ixx
+options.cxx
+  Command line interface implementation in C++. These files are generated 
+  by the CLI compiler from options.cli using the following command line:
+
+  cli --generate-file-scanner hello.cli
+
+  We use the --generate-file-scanner CLI compiler option to include the 
+  argv_file_scanner scanner implementation which provides support for 
+  reading options from files in addition to the command line.
+
+driver.cxx
+  Driver for the example. It first creates the argv_file_scanner object 
+  and indicates that the values for the --options-file option should be 
+  recognized as files containing additional options. It then passes this
+  scanner object to the option class which parses the command line. The
+  driver then prints the option values.
+
+test.ops
+  Sample options file.
+
+To run this example you can try the following command line:
+
+$ ./driver --verbose 2 --val 1 --options-file test.ops --val 4
+
+The output will be:
+
+verbosity: 5
+values: 1 2 3 4
diff --git a/examples/file/driver.cxx b/examples/file/driver.cxx
new file mode 100644
index 0000000..df7a67c
--- /dev/null
+++ b/examples/file/driver.cxx
@@ -0,0 +1,36 @@
+// file      : examples/file/driver.cxx
+// author    : Boris Kolpackov <boris@codesynthesis.com>
+// copyright : Copyright (c) 2009 Code Synthesis Tools CC
+// license   : MIT; see accompanying LICENSE file
+
+#include <iostream>
+#include <iterator>
+#include <algorithm>
+
+#include "options.hxx"
+
+using namespace std;
+
+int
+main (int argc, char* argv[])
+{
+  try
+  {
+    cli::argv_file_scanner s (argc, argv, "--options-file");
+    options o (s);
+
+    cout << "verbosity: " << o.verbose () << endl
+         << "values: ";
+
+    copy (o.val ().begin (),
+          o.val ().end (),
+          ostream_iterator<int> (cout, " "));
+
+    cerr << endl;
+  }
+  catch (const cli::exception& e)
+  {
+    cerr << e << endl;
+    return 1;
+  }
+}
diff --git a/examples/file/file-8.0.vcproj b/examples/file/file-8.0.vcproj
new file mode 100644
index 0000000..0b1000b
--- /dev/null
+++ b/examples/file/file-8.0.vcproj
@@ -0,0 +1,237 @@
+<?xml version="1.0" encoding="Windows-1252"?>

+<VisualStudioProject

+	ProjectType="Visual C++"

+	Version="8.00"

+	Name="file"

+	ProjectGUID="{ECCD3577-1DB2-4F38-9ED7-757433B8D66F}"

+	RootNamespace="file"

+	Keyword="Win32Proj"

+	>

+	<Platforms>

+		<Platform

+			Name="Win32"

+		/>

+	</Platforms>

+	<ToolFiles>

+	</ToolFiles>

+	<Configurations>

+		<Configuration

+			Name="Debug|Win32"

+			OutputDirectory="$(ConfigurationName)"

+			IntermediateDirectory="$(ConfigurationName)"

+			ConfigurationType="1"

+			CharacterSet="1"

+			>

+			<Tool

+				Name="VCPreBuildEventTool"

+			/>

+			<Tool

+				Name="VCCustomBuildTool"

+			/>

+			<Tool

+				Name="VCXMLDataGeneratorTool"

+			/>

+			<Tool

+				Name="VCWebServiceProxyGeneratorTool"

+			/>

+			<Tool

+				Name="VCMIDLTool"

+			/>

+			<Tool

+				Name="VCCLCompilerTool"

+				Optimization="0"

+				PreprocessorDefinitions="WIN32;_DEBUG;_CONSOLE"

+				MinimalRebuild="true"

+				BasicRuntimeChecks="3"

+				RuntimeLibrary="3"

+				UsePrecompiledHeader="0"

+				WarningLevel="3"

+				Detect64BitPortabilityProblems="true"

+				DebugInformationFormat="4"

+			/>

+			<Tool

+				Name="VCManagedResourceCompilerTool"

+			/>

+			<Tool

+				Name="VCResourceCompilerTool"

+			/>

+			<Tool

+				Name="VCPreLinkEventTool"

+			/>

+			<Tool

+				Name="VCLinkerTool"

+				LinkIncremental="2"

+				GenerateDebugInformation="true"

+				SubSystem="1"

+				TargetMachine="1"

+			/>

+			<Tool

+				Name="VCALinkTool"

+			/>

+			<Tool

+				Name="VCManifestTool"

+			/>

+			<Tool

+				Name="VCXDCMakeTool"

+			/>

+			<Tool

+				Name="VCBscMakeTool"

+			/>

+			<Tool

+				Name="VCFxCopTool"

+			/>

+			<Tool

+				Name="VCAppVerifierTool"

+			/>

+			<Tool

+				Name="VCWebDeploymentTool"

+			/>

+			<Tool

+				Name="VCPostBuildEventTool"

+			/>

+		</Configuration>

+		<Configuration

+			Name="Release|Win32"

+			OutputDirectory="$(ConfigurationName)"

+			IntermediateDirectory="$(ConfigurationName)"

+			ConfigurationType="1"

+			CharacterSet="1"

+			WholeProgramOptimization="1"

+			>

+			<Tool

+				Name="VCPreBuildEventTool"

+			/>

+			<Tool

+				Name="VCCustomBuildTool"

+			/>

+			<Tool

+				Name="VCXMLDataGeneratorTool"

+			/>

+			<Tool

+				Name="VCWebServiceProxyGeneratorTool"

+			/>

+			<Tool

+				Name="VCMIDLTool"

+			/>

+			<Tool

+				Name="VCCLCompilerTool"

+				PreprocessorDefinitions="WIN32;NDEBUG;_CONSOLE"

+				RuntimeLibrary="2"

+				UsePrecompiledHeader="0"

+				WarningLevel="3"

+				Detect64BitPortabilityProblems="true"

+				DebugInformationFormat="3"

+			/>

+			<Tool

+				Name="VCManagedResourceCompilerTool"

+			/>

+			<Tool

+				Name="VCResourceCompilerTool"

+			/>

+			<Tool

+				Name="VCPreLinkEventTool"

+			/>

+			<Tool

+				Name="VCLinkerTool"

+				LinkIncremental="1"

+				GenerateDebugInformation="true"

+				SubSystem="1"

+				OptimizeReferences="2"

+				EnableCOMDATFolding="2"

+				TargetMachine="1"

+			/>

+			<Tool

+				Name="VCALinkTool"

+			/>

+			<Tool

+				Name="VCManifestTool"

+			/>

+			<Tool

+				Name="VCXDCMakeTool"

+			/>

+			<Tool

+				Name="VCBscMakeTool"

+			/>

+			<Tool

+				Name="VCFxCopTool"

+			/>

+			<Tool

+				Name="VCAppVerifierTool"

+			/>

+			<Tool

+				Name="VCWebDeploymentTool"

+			/>

+			<Tool

+				Name="VCPostBuildEventTool"

+			/>

+		</Configuration>

+	</Configurations>

+	<References>

+	</References>

+	<Files>

+		<Filter

+			Name="Source Files"

+			Filter="cpp;c;cc;cxx;def;odl;idl;hpj;bat;asm;asmx"

+			UniqueIdentifier="{53E343D0-A5BB-4C2A-A5B1-7C54774D5071}"

+			>

+			<File

+				RelativePath=".\driver.cxx"

+				>

+			</File>

+			<File

+				RelativePath=".\options.cxx"

+				>

+			</File>

+		</Filter>

+		<Filter

+			Name="Header Files"

+			Filter="h;hpp;hxx;hm;inl;inc;xsd"

+			UniqueIdentifier="{5409EE27-2176-4719-B660-DBD88D351153}"

+			>

+			<File

+				RelativePath=".\options.hxx"

+				>

+			</File>

+		</Filter>

+		<Filter

+			Name="CLI Files"

+			Filter="*.cli"

+			>

+			<File

+				RelativePath=".\options.cli"

+				>

+				<FileConfiguration

+					Name="Debug|Win32"

+					>

+					<Tool

+						Name="VCCustomBuildTool"

+						Description="cli options.cli"

+						CommandLine="..\..\cli\cli.exe --generate-file-scanner options.cli"

+						Outputs="options.hxx;options.ixx;options.cxx"

+					/>

+				</FileConfiguration>

+				<FileConfiguration

+					Name="Release|Win32"

+					>

+					<Tool

+						Name="VCCustomBuildTool"

+						Description="cli options.cli"

+						CommandLine="..\..\cli\cli.exe --generate-file-scanner options.cli"

+						Outputs="options.hxx;options.ixx;options.cxx"

+					/>

+				</FileConfiguration>

+			</File>

+		</Filter>

+		<Filter

+			Name="Inline Files"

+			Filter="*.ixx"

+			>

+			<File

+				RelativePath=".\options.ixx"

+				>

+			</File>

+		</Filter>

+	</Files>

+	<Globals>

+	</Globals>

+</VisualStudioProject>

diff --git a/examples/file/file-9.0.vcproj b/examples/file/file-9.0.vcproj
new file mode 100644
index 0000000..c2a78e5
--- /dev/null
+++ b/examples/file/file-9.0.vcproj
@@ -0,0 +1,233 @@
+<?xml version="1.0" encoding="Windows-1252"?>

+<VisualStudioProject

+	ProjectType="Visual C++"

+	Version="9.00"

+	Name="file"

+	ProjectGUID="{ECCD3577-1DB2-4F38-9ED7-757433B8D66F}"

+	RootNamespace="file"

+	Keyword="Win32Proj"

+	TargetFrameworkVersion="196613"

+	>

+	<Platforms>

+		<Platform

+			Name="Win32"

+		/>

+	</Platforms>

+	<ToolFiles>

+	</ToolFiles>

+	<Configurations>

+		<Configuration

+			Name="Debug|Win32"

+			OutputDirectory="$(ConfigurationName)"

+			IntermediateDirectory="$(ConfigurationName)"

+			ConfigurationType="1"

+			CharacterSet="1"

+			>

+			<Tool

+				Name="VCPreBuildEventTool"

+			/>

+			<Tool

+				Name="VCCustomBuildTool"

+			/>

+			<Tool

+				Name="VCXMLDataGeneratorTool"

+			/>

+			<Tool

+				Name="VCWebServiceProxyGeneratorTool"

+			/>

+			<Tool

+				Name="VCMIDLTool"

+			/>

+			<Tool

+				Name="VCCLCompilerTool"

+				Optimization="0"

+				PreprocessorDefinitions="WIN32;_DEBUG;_CONSOLE"

+				MinimalRebuild="true"

+				BasicRuntimeChecks="3"

+				RuntimeLibrary="3"

+				UsePrecompiledHeader="0"

+				WarningLevel="3"

+				DebugInformationFormat="4"

+			/>

+			<Tool

+				Name="VCManagedResourceCompilerTool"

+			/>

+			<Tool

+				Name="VCResourceCompilerTool"

+			/>

+			<Tool

+				Name="VCPreLinkEventTool"

+			/>

+			<Tool

+				Name="VCLinkerTool"

+				LinkIncremental="2"

+				GenerateDebugInformation="true"

+				SubSystem="1"

+				TargetMachine="1"

+			/>

+			<Tool

+				Name="VCALinkTool"

+			/>

+			<Tool

+				Name="VCManifestTool"

+			/>

+			<Tool

+				Name="VCXDCMakeTool"

+			/>

+			<Tool

+				Name="VCBscMakeTool"

+			/>

+			<Tool

+				Name="VCFxCopTool"

+			/>

+			<Tool

+				Name="VCAppVerifierTool"

+			/>

+			<Tool

+				Name="VCPostBuildEventTool"

+			/>

+		</Configuration>

+		<Configuration

+			Name="Release|Win32"

+			OutputDirectory="$(ConfigurationName)"

+			IntermediateDirectory="$(ConfigurationName)"

+			ConfigurationType="1"

+			CharacterSet="1"

+			WholeProgramOptimization="1"

+			>

+			<Tool

+				Name="VCPreBuildEventTool"

+			/>

+			<Tool

+				Name="VCCustomBuildTool"

+			/>

+			<Tool

+				Name="VCXMLDataGeneratorTool"

+			/>

+			<Tool

+				Name="VCWebServiceProxyGeneratorTool"

+			/>

+			<Tool

+				Name="VCMIDLTool"

+			/>

+			<Tool

+				Name="VCCLCompilerTool"

+				Optimization="2"

+				EnableIntrinsicFunctions="true"

+				PreprocessorDefinitions="WIN32;NDEBUG;_CONSOLE"

+				RuntimeLibrary="2"

+				EnableFunctionLevelLinking="true"

+				UsePrecompiledHeader="0"

+				WarningLevel="3"

+				DebugInformationFormat="3"

+			/>

+			<Tool

+				Name="VCManagedResourceCompilerTool"

+			/>

+			<Tool

+				Name="VCResourceCompilerTool"

+			/>

+			<Tool

+				Name="VCPreLinkEventTool"

+			/>

+			<Tool

+				Name="VCLinkerTool"

+				LinkIncremental="1"

+				GenerateDebugInformation="true"

+				SubSystem="1"

+				OptimizeReferences="2"

+				EnableCOMDATFolding="2"

+				TargetMachine="1"

+			/>

+			<Tool

+				Name="VCALinkTool"

+			/>

+			<Tool

+				Name="VCManifestTool"

+			/>

+			<Tool

+				Name="VCXDCMakeTool"

+			/>

+			<Tool

+				Name="VCBscMakeTool"

+			/>

+			<Tool

+				Name="VCFxCopTool"

+			/>

+			<Tool

+				Name="VCAppVerifierTool"

+			/>

+			<Tool

+				Name="VCPostBuildEventTool"

+			/>

+		</Configuration>

+	</Configurations>

+	<References>

+	</References>

+	<Files>

+		<Filter

+			Name="Source Files"

+			Filter="cpp;c;cc;cxx;def;odl;idl;hpj;bat;asm;asmx"

+			UniqueIdentifier="{53E343D0-A5BB-4C2A-A5B1-7C54774D5071}"

+			>

+			<File

+				RelativePath=".\driver.cxx"

+				>

+			</File>

+			<File

+				RelativePath=".\options.cxx"

+				>

+			</File>

+		</Filter>

+		<Filter

+			Name="Header Files"

+			Filter="h;hpp;hxx;hm;inl;inc;xsd"

+			UniqueIdentifier="{5409EE27-2176-4719-B660-DBD88D351153}"

+			>

+			<File

+				RelativePath=".\options.hxx"

+				>

+			</File>

+		</Filter>

+		<Filter

+			Name="Inline Files"

+			Filter="*.ixx"

+			>

+			<File

+				RelativePath=".\options.ixx"

+				>

+			</File>

+		</Filter>

+		<Filter

+			Name="CLI Files"

+			Filter="*.cli"

+			>

+			<File

+				RelativePath=".\options.cli"

+				>

+				<FileConfiguration

+					Name="Debug|Win32"

+					>

+					<Tool

+						Name="VCCustomBuildTool"

+						Description="cli options.cli"

+						CommandLine="..\..\cli\cli.exe --generate-file-scanner options.cli"

+						Outputs="options.hxx;options.ixx;options.cxx"

+					/>

+				</FileConfiguration>

+				<FileConfiguration

+					Name="Release|Win32"

+					>

+					<Tool

+						Name="VCCustomBuildTool"

+						Description="cli options.cli"

+						CommandLine="..\..\cli\cli.exe --generate-file-scanner options.cli"

+						Outputs="options.hxx;options.ixx;options.cxx"

+					/>

+				</FileConfiguration>

+			</File>

+		</Filter>

+	</Files>

+	<Globals>

+	</Globals>

+</VisualStudioProject>

diff --git a/examples/file/makefile b/examples/file/makefile
new file mode 100644
index 0000000..04c45a7
--- /dev/null
+++ b/examples/file/makefile
@@ -0,0 +1,74 @@
+# file      : examples/file/makefile
+# author    : Boris Kolpackov <boris@codesynthesis.com>
+# copyright : Copyright (c) 2009 Code Synthesis Tools CC
+# license   : MIT; see accompanying LICENSE file
+
+include $(dir $(lastword $(MAKEFILE_LIST)))../../build/bootstrap.make
+
+cli := options.cli
+cxx := driver.cxx
+
+obj := $(addprefix $(out_base)/,$(cxx:.cxx=.o) $(cli:.cli=.o))
+dep := $(obj:.o=.o.d)
+
+driver   := $(out_base)/driver
+install  := $(out_base)/.install
+clean    := $(out_base)/.clean
+
+# Build.
+#
+$(driver): $(obj)
+
+$(obj) $(dep): cpp_options := -I$(out_base)
+
+genf := $(cli:.cli=.hxx) $(cli:.cli=.ixx) $(cli:.cli=.cxx)
+gen  := $(addprefix $(out_base)/,$(genf))
+
+$(gen): cli := $(out_root)/cli/cli
+$(gen): cli_options := --generate-file-scanner
+$(gen): $(out_root)/cli/cli
+
+$(call include-dep,$(dep),$(obj),$(gen))
+
+# Convenience alias for default target.
+#
+$(out_base)/: $(driver)
+
+# Install
+#
+$(install): path := $(subst $(src_root)/,,$(src_base))
+$(install):
+	$(call install-data,$(src_base)/driver.cxx,$(install_doc_dir)/cli/$(path)/driver.cxx)
+	$(call install-data,$(src_base)/options.cli,$(install_doc_dir)/cli/$(path)/options.cli)
+	$(call install-data,$(src_base)/README,$(install_doc_dir)/cli/$(path)/README)
+	$(call install-data,$(src_base)/test.ops,$(install_doc_dir)/cli/$(path)/test.ops)
+
+# Clean.
+#
+$(clean): $(driver).o.clean                            \
+  $(addsuffix .cxx.clean,$(obj))                       \
+  $(addsuffix .cxx.clean,$(dep))                       \
+  $(addprefix $(out_base)/,$(cli:.cli=.cxx.cli.clean))
+
+# Generated .gitignore.
+#
+ifeq ($(out_base),$(src_base))
+$(gen): | $(out_base)/.gitignore
+$(driver): | $(out_base)/.gitignore
+
+$(out_base)/.gitignore: files := driver $(genf)
+$(clean): $(out_base)/.gitignore.clean
+
+$(call include,$(bld_root)/git/gitignore.make)
+endif
+
+# How to.
+#
+$(call include,$(bld_root)/cxx/o-e.make)
+$(call include,$(bld_root)/cxx/cxx-o.make)
+$(call include,$(bld_root)/cxx/cxx-d.make)
+$(call include,$(scf_root)/cli/cli-cxx.make)
+
+# Dependencies.
+#
+$(call import,$(src_root)/cli/makefile)
diff --git a/examples/file/options.cli b/examples/file/options.cli
new file mode 100644
index 0000000..3e6db5a
--- /dev/null
+++ b/examples/file/options.cli
@@ -0,0 +1,7 @@
+include <vector>;
+
+class options
+{
+  int --verbose;
+  std::vector<int> --val;
+};
diff --git a/examples/file/test.ops b/examples/file/test.ops
new file mode 100644
index 0000000..47097fb
--- /dev/null
+++ b/examples/file/test.ops
@@ -0,0 +1,7 @@
+# Sample options file. Empty lines and lines starting with '#' are
+# ignored.
+#
+--verbose 5
+
+--val 2
+--val 3
diff --git a/examples/makefile b/examples/makefile
index 135b9bb..9b1de12 100644
--- a/examples/makefile
+++ b/examples/makefile
@@ -5,7 +5,7 @@
 
 include $(dir $(lastword $(MAKEFILE_LIST)))../build/bootstrap.make
 
-examples := hello features
+examples := hello features file
 
 default   := $(out_base)/
 install   := $(out_base)/.install