Speedup find_* commands (#11412)

Delay computation of the command documentation until it is needed.
It is wasteful to do it in the constructor on every call.

Inspired-By: Christian Ehrlicher <Ch.Ehrlicher@gmx.de>

14 files changed, 88 insertions, 42 deletions

diff --git a/Source/cmFindBase.cxx b/Source/cmFindBase.cxx
index e1188d5..0416538 100644
--- a/Source/cmFindBase.cxx
+++ b/Source/cmFindBase.cxx
@@ -13,11 +13,17 @@
   
 cmFindBase::cmFindBase()
 {
-  cmSystemTools::ReplaceString(this->GenericDocumentationPathsOrder,
-                               "FIND_ARGS_XXX", "<VAR> NAMES name");
   this->AlreadyInCache = false;
   this->AlreadyInCacheWithoutMetaInfo = false;
-  this->GenericDocumentation = 
+}
+
+//----------------------------------------------------------------------------
+void cmFindBase::GenerateDocumentation()
+{
+  this->cmFindCommon::GenerateDocumentation();
+  cmSystemTools::ReplaceString(this->GenericDocumentationPathsOrder,
+                               "FIND_ARGS_XXX", "<VAR> NAMES name");
+  this->GenericDocumentation =
     "   FIND_XXX(<VAR> name1 [path1 path2 ...])\n"
     "This is the short-hand signature for the command that "
     "is sufficient in many cases.  It is the same "
@@ -97,7 +103,18 @@ cmFindBase::cmFindBase()
   this->GenericDocumentation += this->GenericDocumentationRootPath;
   this->GenericDocumentation += this->GenericDocumentationPathsOrder;
 }
-  
+
+//----------------------------------------------------------------------------
+const char* cmFindBase::GetFullDocumentation()
+{
+  if(this->GenericDocumentation.empty())
+    {
+    this->GenerateDocumentation();
+    }
+  return this->GenericDocumentation.c_str();
+}
+
+//----------------------------------------------------------------------------
 bool cmFindBase::ParseArguments(std::vector<std::string> const& argsIn)
 {
   if(argsIn.size() < 2 )
diff --git a/Source/cmFindBase.h b/Source/cmFindBase.h
index 2f1727e..de319b1 100644
--- a/Source/cmFindBase.h
+++ b/Source/cmFindBase.h
@@ -31,10 +31,10 @@ public:
   virtual bool ParseArguments(std::vector<std::string> const& args);
   cmTypeMacro(cmFindBase, cmFindCommon);
   
-  virtual const char* GetFullDocumentation()
-    {return this->GenericDocumentation.c_str();}
+  virtual const char* GetFullDocumentation();
 
 protected:
+  virtual void GenerateDocumentation();
   void PrintFindStuff();
   void ExpandPaths();
   void AddPathSuffixes();
diff --git a/Source/cmFindCommon.cxx b/Source/cmFindCommon.cxx
index b7d3e52..a05e337 100644
--- a/Source/cmFindCommon.cxx
+++ b/Source/cmFindCommon.cxx
@@ -34,7 +34,11 @@ cmFindCommon::cmFindCommon()
   this->SearchFrameworkLast = false;
   this->SearchAppBundleOnly = false;
   this->SearchAppBundleLast = false;
+}
 
+//----------------------------------------------------------------------------
+void cmFindCommon::GenerateDocumentation()
+{
   // Documentation components.
   this->GenericDocumentationMacPolicy =
     "On Darwin or systems supporting OS X Frameworks, the cmake variable"
diff --git a/Source/cmFindCommon.h b/Source/cmFindCommon.h
index a4866ba..875c223 100644
--- a/Source/cmFindCommon.h
+++ b/Source/cmFindCommon.h
@@ -56,6 +56,8 @@ protected:
   /** Compute the current default bundle/framework search policy.  */
   void SelectDefaultMacMode();
 
+  virtual void GenerateDocumentation();
+
   cmStdString CMakePathName;
   RootPathMode FindRootPathMode;
 
diff --git a/Source/cmFindFileCommand.cxx b/Source/cmFindFileCommand.cxx
index 897b4bb..fa66fa1 100644
--- a/Source/cmFindFileCommand.cxx
+++ b/Source/cmFindFileCommand.cxx
@@ -15,11 +15,16 @@
 cmFindFileCommand::cmFindFileCommand()
 {
   this->IncludeFileInPath = true;
+}
+
+void cmFindFileCommand::GenerateDocumentation()
+{
+  this->cmFindPathCommand::GenerateDocumentation();
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "find_path", "find_file");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
-                               "directory containing the named file", 
+                               "directory containing the named file",
                                "full path to named file");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
-                                "file in a directory", "full path to a file");
+                               "file in a directory", "full path to a file");
 }
diff --git a/Source/cmFindFileCommand.h b/Source/cmFindFileCommand.h
index aa0d25e..dd2e01d 100644
--- a/Source/cmFindFileCommand.h
+++ b/Source/cmFindFileCommand.h
@@ -44,6 +44,8 @@ public:
     }
   
   cmTypeMacro(cmFindFileCommand, cmFindPathCommand);
+protected:
+  virtual void GenerateDocumentation();
 };
 
 
diff --git a/Source/cmFindLibraryCommand.cxx b/Source/cmFindLibraryCommand.cxx
index 9077c8e..b309376 100644
--- a/Source/cmFindLibraryCommand.cxx
+++ b/Source/cmFindLibraryCommand.cxx
@@ -16,6 +16,13 @@
 
 cmFindLibraryCommand::cmFindLibraryCommand()
 { 
+  this->EnvironmentPath = "LIB";
+}
+
+//----------------------------------------------------------------------------
+void cmFindLibraryCommand::GenerateDocumentation()
+{
+  this->cmFindBase::GenerateDocumentation();
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "FIND_XXX", "find_library");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
@@ -29,7 +36,7 @@ cmFindLibraryCommand::cmFindLibraryCommand()
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "XXX_SYSTEM", "LIB");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
-                               "CMAKE_SYSTEM_XXX_PATH", 
+                               "CMAKE_SYSTEM_XXX_PATH",
                                "CMAKE_SYSTEM_LIBRARY_PATH");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "SEARCH_XXX_DESC", "library");
@@ -38,11 +45,9 @@ cmFindLibraryCommand::cmFindLibraryCommand()
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "XXX_SUBDIR", "lib");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
-                               "CMAKE_FIND_ROOT_PATH_MODE_XXX", 
+                               "CMAKE_FIND_ROOT_PATH_MODE_XXX",
                                "CMAKE_FIND_ROOT_PATH_MODE_LIBRARY");
-
-  this->EnvironmentPath = "LIB";
-  this->GenericDocumentation += 
+  this->GenericDocumentation +=
     "\n"
     "If the library found is a framework, then VAR will be set to "
     "the full path to the framework <fullPath>/A.framework. "
diff --git a/Source/cmFindLibraryCommand.h b/Source/cmFindLibraryCommand.h
index 486c2cf..7930f52 100644
--- a/Source/cmFindLibraryCommand.h
+++ b/Source/cmFindLibraryCommand.h
@@ -64,6 +64,7 @@ protected:
   void AddArchitecturePaths(const char* suffix);
   void AddLib64Paths();
   std::string FindLibrary();
+  virtual void GenerateDocumentation();
 private:
   std::string FindNormalLibrary();
   std::string FindFrameworkLibrary();
diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index ef0197a..fdc1a01 100644
--- a/Source/cmFindPackageCommand.cxx
+++ b/Source/cmFindPackageCommand.cxx
@@ -51,13 +51,6 @@ void cmFindPackageNeedBackwardsCompatibility(const std::string& variable,
 //----------------------------------------------------------------------------
 cmFindPackageCommand::cmFindPackageCommand()
 {
-  cmSystemTools::ReplaceString(this->GenericDocumentationRootPath,
-                               "CMAKE_FIND_ROOT_PATH_MODE_XXX",
-                               "CMAKE_FIND_ROOT_PATH_MODE_PACKAGE");
-  cmSystemTools::ReplaceString(this->GenericDocumentationPathsOrder,
-                               "FIND_ARGS_XXX", "<package>");
-  cmSystemTools::ReplaceString(this->GenericDocumentationPathsOrder,
-                               "FIND_XXX", "find_package");
   this->CMakePathName = "PACKAGE";
   this->Quiet = false;
   this->Required = false;
@@ -78,6 +71,19 @@ cmFindPackageCommand::cmFindPackageCommand()
   this->VersionFoundPatch = 0;
   this->VersionFoundTweak = 0;
   this->VersionFoundCount = 0;
+}
+
+//----------------------------------------------------------------------------
+void cmFindPackageCommand::GenerateDocumentation()
+{
+  this->cmFindCommon::GenerateDocumentation();
+  cmSystemTools::ReplaceString(this->GenericDocumentationRootPath,
+                               "CMAKE_FIND_ROOT_PATH_MODE_XXX",
+                               "CMAKE_FIND_ROOT_PATH_MODE_PACKAGE");
+  cmSystemTools::ReplaceString(this->GenericDocumentationPathsOrder,
+                               "FIND_ARGS_XXX", "<package>");
+  cmSystemTools::ReplaceString(this->GenericDocumentationPathsOrder,
+                               "FIND_XXX", "find_package");
   this->CommandDocumentation =
     "  find_package(<package> [version] [EXACT] [QUIET]\n"
     "               [[REQUIRED|COMPONENTS] [components...]]\n"
@@ -318,6 +324,10 @@ cmFindPackageCommand::cmFindPackageCommand()
 //----------------------------------------------------------------------------
 const char* cmFindPackageCommand::GetFullDocumentation()
 {
+  if(this->CommandDocumentation.empty())
+    {
+    this->GenerateDocumentation();
+    }
   return this->CommandDocumentation.c_str();
 }
 
diff --git a/Source/cmFindPackageCommand.h b/Source/cmFindPackageCommand.h
index 57aeab9..19d2b10 100644
--- a/Source/cmFindPackageCommand.h
+++ b/Source/cmFindPackageCommand.h
@@ -65,6 +65,8 @@ public:
   virtual const char* GetFullDocumentation();
 
   cmTypeMacro(cmFindPackageCommand, cmFindCommon);
+protected:
+  virtual void GenerateDocumentation();
 private:
   void AppendSuccessInformation();
   void AppendToProperty(const char* propertyName);
diff --git a/Source/cmFindPathCommand.cxx b/Source/cmFindPathCommand.cxx
index cca243a..83b651b 100644
--- a/Source/cmFindPathCommand.cxx
+++ b/Source/cmFindPathCommand.cxx
@@ -18,6 +18,11 @@ cmFindPathCommand::cmFindPathCommand()
 {
   this->EnvironmentPath = "INCLUDE";
   this->IncludeFileInPath = false;
+}
+
+void cmFindPathCommand::GenerateDocumentation()
+{
+  this->cmFindBase::GenerateDocumentation();
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "FIND_XXX", "find_path");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
@@ -31,27 +36,21 @@ cmFindPathCommand::cmFindPathCommand()
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "XXX_SYSTEM", "INCLUDE");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
-                               "CMAKE_SYSTEM_XXX_PATH", 
-                               "CMAKE_SYSTEM_INCLUDE_PATH"); 
+                               "CMAKE_SYSTEM_XXX_PATH",
+                               "CMAKE_SYSTEM_INCLUDE_PATH");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
-                               "SEARCH_XXX_DESC", 
+                               "SEARCH_XXX_DESC",
                                "directory containing the named file");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "SEARCH_XXX", "file in a directory");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "XXX_SUBDIR", "include");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
-                               "CMAKE_FIND_ROOT_PATH_MODE_XXX", 
+                               "CMAKE_FIND_ROOT_PATH_MODE_XXX",
                                "CMAKE_FIND_ROOT_PATH_MODE_INCLUDE");
-
-  this->ExtraDocAdded = false;
-}
-
-const char* cmFindPathCommand::GetFullDocumentation()
-{
-  if(!this->ExtraDocAdded && !this->IncludeFileInPath)
+  if(!this->IncludeFileInPath)
     {
-    this->GenericDocumentation += 
+    this->GenericDocumentation +=
       "\n"
       "When searching for frameworks, if the file is specified as "
       "A/b.h, then the framework search will look for "
@@ -59,9 +58,7 @@ const char* cmFindPathCommand::GetFullDocumentation()
       "If that is found the path will be set to the path to the framework. "
       "CMake will convert this to the correct -F option to include the "
       "file. ";
-    this->ExtraDocAdded = true;
     }
-  return this->GenericDocumentation.c_str();
 }
 
 // cmFindPathCommand
diff --git a/Source/cmFindPathCommand.h b/Source/cmFindPathCommand.h
index 3c04343..bd94779 100644
--- a/Source/cmFindPathCommand.h
+++ b/Source/cmFindPathCommand.h
@@ -59,10 +59,10 @@ public:
     return "Find the directory containing a file.";
     }
 
-  virtual const char* GetFullDocumentation();
   cmTypeMacro(cmFindPathCommand, cmFindBase);
   bool IncludeFileInPath;
-  bool ExtraDocAdded;
+protected:
+  virtual void GenerateDocumentation();
 private:
   std::string FindHeaderInFramework(std::string const& file,
                                     std::string const& dir);
diff --git a/Source/cmFindProgramCommand.cxx b/Source/cmFindProgramCommand.cxx
index 519f862..71cfdcb 100644
--- a/Source/cmFindProgramCommand.cxx
+++ b/Source/cmFindProgramCommand.cxx
@@ -16,9 +16,10 @@
 #if defined(__APPLE__)
 #include <CoreFoundation/CoreFoundation.h>
 #endif
-  
-cmFindProgramCommand::cmFindProgramCommand()
+
+void cmFindProgramCommand::GenerateDocumentation()
 {
+  this->cmFindBase::GenerateDocumentation();
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "FIND_XXX", "find_program");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
@@ -32,8 +33,8 @@ cmFindProgramCommand::cmFindProgramCommand()
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "XXX_SYSTEM", "");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
-                               "CMAKE_SYSTEM_XXX_PATH", 
-                               "CMAKE_SYSTEM_PROGRAM_PATH"); 
+                               "CMAKE_SYSTEM_XXX_PATH",
+                               "CMAKE_SYSTEM_PROGRAM_PATH");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "SEARCH_XXX_DESC", "program");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
@@ -41,7 +42,7 @@ cmFindProgramCommand::cmFindProgramCommand()
   cmSystemTools::ReplaceString(this->GenericDocumentation,
                                "XXX_SUBDIR", "[s]bin");
   cmSystemTools::ReplaceString(this->GenericDocumentation,
-                               "CMAKE_FIND_ROOT_PATH_MODE_XXX", 
+                               "CMAKE_FIND_ROOT_PATH_MODE_XXX",
                                "CMAKE_FIND_ROOT_PATH_MODE_PROGRAM");
 }
 
diff --git a/Source/cmFindProgramCommand.h b/Source/cmFindProgramCommand.h
index ae790a3..654e834 100644
--- a/Source/cmFindProgramCommand.h
+++ b/Source/cmFindProgramCommand.h
@@ -25,7 +25,6 @@
 class cmFindProgramCommand : public cmFindBase
 {
 public:
-  cmFindProgramCommand();
   /**
    * This is a virtual constructor for the command.
    */
@@ -63,6 +62,7 @@ public:
 
 protected:
   std::string FindProgram(std::vector<std::string> names);
+  virtual void GenerateDocumentation();
 
 private:
   std::string FindAppBundle(std::vector<std::string> names);

path: root/doc/while.n

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
.so man.macros
.TH while n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
while \- Execute script repeatedly as long as a condition is met
.SH SYNOPSIS
\fBwhile \fItest body\fR
.BE
.SH DESCRIPTION
.PP
The \fBwhile\fR command evaluates \fItest\fR as an expression
(in the same way that \fBexpr\fR evaluates its argument).
The value of the expression must a proper boolean
value; if it is a true value
then \fIbody\fR is executed by passing it to the Tcl interpreter.
Once \fIbody\fR has been executed then \fItest\fR is evaluated
again, and the process repeats until eventually \fItest\fR
evaluates to a false boolean value.  \fBContinue\fR
commands may be executed inside \fIbody\fR to terminate the current
iteration of the loop, and \fBbreak\fR
commands may be executed inside \fIbody\fR to cause immediate
termination of the \fBwhile\fR command.  The \fBwhile\fR command
always returns an empty string.
.PP
Note: \fItest\fR should almost always be enclosed in braces.  If not,
variable substitutions will be made before the \fBwhile\fR
command starts executing, which means that variable changes
made by the loop body will not be considered in the expression.
This is likely to result in an infinite loop.  If \fItest\fR is
enclosed in braces, variable substitutions are delayed until the
expression is evaluated (before
each loop iteration), so changes in the variables will be visible.
For an example, try the following script with and without the braces
around \fB$x<10\fR:
.PP
.CS
set x 0
\fBwhile\fR {$x<10} {
    puts "x is $x"
    incr x
}
.CE
.SH EXAMPLE
.PP
Read lines from a channel until we get to the end of the stream, and
print them out with a line-number prepended:
.PP
.CS
set lineCount 0
\fBwhile\fR {[gets $chan line] >= 0} {
    puts "[incr lineCount]: $line"
}
.CE
.SH "SEE ALSO"
break(n), continue(n), for(n), foreach(n)
.SH KEYWORDS
boolean, loop, test, while