ENH: Updated DEFINE_PROPERTY command to be more extendible and more consistent with new SET_PROPERTY and GET_PROPERTY signatures.

2 files changed, 121 insertions, 26 deletions

diff --git a/Source/cmDefinePropertyCommand.cxx b/Source/cmDefinePropertyCommand.cxx
index 685f50d..fbdefed 100644
--- a/Source/cmDefinePropertyCommand.cxx
+++ b/Source/cmDefinePropertyCommand.cxx
@@ -21,52 +21,124 @@
 bool cmDefinePropertyCommand
 ::InitialPass(std::vector<std::string> const& args, cmExecutionStatus &)
 {
-  if(args.size() < 5 )
+  if(args.size() < 1)
     {
     this->SetError("called with incorrect number of arguments");
     return false;
     }
 
-  // determine the scope
+  // Get the scope in which to define the property.
   cmProperty::ScopeType scope;
-  if (args[1] == "GLOBAL")
+  if(args[0] == "GLOBAL")
     {
     scope = cmProperty::GLOBAL;
     }
-  else if (args[1] == "DIRECTORY")
+  else if(args[0] == "DIRECTORY")
     {
     scope = cmProperty::DIRECTORY;
     }
-  else if (args[1] == "TARGET")
+  else if(args[0] == "TARGET")
     {
     scope = cmProperty::TARGET;
     }
-  else if (args[1] == "SOURCE_FILE")
+  else if(args[0] == "SOURCE")
     {
     scope = cmProperty::SOURCE_FILE;
     }
-  else if (args[1] == "TEST")
+  else if(args[0] == "TEST")
     {
     scope = cmProperty::TEST;
     }
-  else if (args[1] == "VARIABLE")
+  else if(args[0] == "VARIABLE")
     {
     scope = cmProperty::VARIABLE;
     }
-  else if (args[1] == "CACHED_VARIABLE")
+  else if (args[0] == "CACHED_VARIABLE")
     {
     scope = cmProperty::CACHED_VARIABLE;
     }
   else
     {
-    this->SetError("called with illegal arguments.");
+    cmOStringStream e;
+    e << "given invalid scope " << args[0] << ".  "
+      << "Valid scopes are "
+      << "GLOBAL, DIRECTORY, TARGET, SOURCE, "
+      << "TEST, VARIABLE, CACHED_VARIABLE.";
+    this->SetError(e.str().c_str());
     return false;
     }
 
+  // Parse remaining arguments.
+  bool inherited = false;
+  enum Doing { DoingNone, DoingProperty, DoingBrief, DoingFull };
+  Doing doing = DoingNone;
+  for(unsigned int i=1; i < args.size(); ++i)
+    {
+    if(args[i] == "PROPERTY")
+      {
+      doing = DoingProperty;
+      }
+    else if(args[i] == "BRIEF_DOCS")
+      {
+      doing = DoingBrief;
+      }
+    else if(args[i] == "FULL_DOCS")
+      {
+      doing = DoingFull;
+      }
+    else if(args[i] == "INHERITED")
+      {
+      doing = DoingNone;
+      inherited = true;
+      }
+    else if(doing == DoingProperty)
+      {
+      doing = DoingNone;
+      this->PropertyName = args[i];
+      }
+    else if(doing == DoingBrief)
+      {
+      doing = DoingNone;
+      this->BriefDocs = args[i];
+      }
+    else if(doing == DoingFull)
+      {
+      doing = DoingNone;
+      this->FullDocs = args[i];
+      }
+    else
+      {
+      cmOStringStream e;
+      e << "given invalid argument \"" << args[i] << "\".";
+      this->SetError(e.str().c_str());
+      return false;
+      }
+    }
+
+  // Make sure a property name was found.
+  if(this->PropertyName.empty())
+    {
+    this->SetError("not given a PROPERTY <name> argument.");
+    return false;
+    }
+
+  // Make sure documentation was given.
+  if(this->BriefDocs.empty())
+    {
+    this->SetError("not given a BRIEF_DOCS <brief-doc> argument.");
+    return false;
+    }
+  if(this->FullDocs.empty())
+    {
+    this->SetError("not given a FULL_DOCS <full-doc> argument.");
+    return false;
+    }
+
+  // Actually define the property.
   this->Makefile->GetCMakeInstance()->DefineProperty
-    (args[0].c_str(), scope,args[2].c_str(), args[3].c_str(),
-     cmSystemTools::IsOn(args[4].c_str()));
-  
+    (this->PropertyName.c_str(), scope,
+     this->BriefDocs.c_str(), this->FullDocs.c_str(), inherited);
+
   return true;
 }
 
diff --git a/Source/cmDefinePropertyCommand.h b/Source/cmDefinePropertyCommand.h
index 4f95d46..36c6913 100644
--- a/Source/cmDefinePropertyCommand.h
+++ b/Source/cmDefinePropertyCommand.h
@@ -44,7 +44,7 @@ public:
    */
   virtual const char* GetTerseDocumentation() 
     {
-    return "Define properties used by CMake.";
+    return "Define and document custom properties.";
     }
   
   /**
@@ -53,21 +53,44 @@ public:
   virtual const char* GetFullDocumentation()
     {
       return
-        "  define_property(property_name scope_value\n"
-        "                  short_description\n"
-        "                  full_description inherit)\n"
-        "Define a property for a scope. scope_value is either GLOBAL, "
-        "DIRECTORY, TARGET, TEST, SOURCE_FILE, VARIABLE or CACHED_VARIABLE. "
-        "The short and full descriptions are used to document the property. "
-        "If inherit is TRUE, it will inherit its value from the next more "
-        "global property if it hasn't been set at the specified scope. "
-        "This means that e.g. a TARGET property inherits it's value from the "
-        "DIRECTORY property with the same name if it hasn't been set for the "
-        "target, and then from GLOBAL if it hasn't been set for the directory."
-        ;
+        "  define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |\n"
+        "                   TEST | VARIABLE | CACHED_VARIABLE>\n"
+        "                   PROPERTY <name> [INHERITED]\n"
+        "                   BRIEF_DOCS <brief-doc>\n"
+        "                   FULL_DOCS <full-doc>)\n"
+        "Define one property in a scope for use with the "
+        "set_property and get_property commands.  "
+        "This is primarily useful to associate documentation with property "
+        "names that may be retrieved with the get_property command.  "
+        "The first argument determines the kind of scope in which the "
+        "property should be used.  It must be one of the following:\n"
+        "  GLOBAL    = associated with the global namespace\n"
+        "  DIRECTORY = associated with one directory\n"
+        "  TARGET    = associated with one target\n"
+        "  SOURCE    = associated with one source file\n"
+        "  TEST      = associated with a test named with add_test command\n"
+        "  VARIABLE  = documents a CMake language variable\n"
+        "  CACHED_VARIABLE = documents a CMake cache variable\n"
+        "Note that unlike set_property and get_property no actual scope "
+        "needs to be given; only the kind of scope is important.\n"
+        "The required PROPERTY option is immediately followed by the name "
+        "of the property being defined.\n"
+        "If the INHERITED option then the get_property command will chain "
+        "up to the next higher scope when the requested property is not "
+        "set in the scope given to the command.  "
+        "DIRECTORY scope chains to GLOBAL.  "
+        "TARGET, SOURCE, and TEST chain to DIRECTORY.\n"
+        "The BRIEF_DOCS and FULL_DOCS options are followed by strings to be "
+        "associated with the property as its brief and full documentation.  "
+        "Corresponding options to the get_property command will retrieve the "
+        "documentation.";
     }
   
   cmTypeMacro(cmDefinePropertyCommand, cmCommand);
+private:
+  std::string PropertyName;
+  std::string BriefDocs;
+  std::string FullDocs;
 };