Source/cmIfCommand.h

   1 /*============================================================================
   2   CMake - Cross Platform Makefile Generator
   3   Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
   4
   5   Distributed under the OSI-approved BSD License (the "License");
   6   see accompanying file Copyright.txt for details.
   7
   8   This software is distributed WITHOUT ANY WARRANTY; without even the
   9   implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  10   See the License for more information.
  11 ============================================================================*/
  12 #ifndef cmIfCommand_h
  13 #define cmIfCommand_h
  14
  15 #include "cmCommand.h"
  16 #include "cmFunctionBlocker.h"
  17
  18 class cmIfFunctionBlocker : public cmFunctionBlocker
  19 {
  20 public:
  21   cmIfFunctionBlocker() {
  22     this->HasRun = false; this->ScopeDepth = 0; }
  23   virtual ~cmIfFunctionBlocker() {}
  24   virtual bool IsFunctionBlocked(const cmListFileFunction& lff,
  25                                  cmMakefile &mf,
  26                                  cmExecutionStatus &);
  27   virtual bool ShouldRemove(const cmListFileFunction& lff,
  28                             cmMakefile &mf);
  29
  30   std::vector<cmListFileArgument> Args;
  31   std::vector<cmListFileFunction> Functions;
  32   bool IsBlocking;
  33   bool HasRun;
  34   unsigned int ScopeDepth;
  35 };
  36
  37 /// Starts an if block
  38 class cmIfCommand : public cmCommand
  39 {
  40 public:
  41   /**
  42    * This is a virtual constructor for the command.
  43    */
  44   virtual cmCommand* Clone()
  45     {
  46     return new cmIfCommand;
  47     }
  48
  49   /**
  50    * This overrides the default InvokeInitialPass implementation.
  51    * It records the arguments before expansion.
  52    */
  53   virtual bool InvokeInitialPass(const std::vector<cmListFileArgument>& args,
  54                                  cmExecutionStatus &);
  55
  56   /**
  57    * This is called when the command is first encountered in
  58    * the CMakeLists.txt file.
  59    */
  60   virtual bool InitialPass(std::vector<std::string> const&,
  61                            cmExecutionStatus &) { return false;};
  62
  63   /**
  64    * The name of the command as specified in CMakeList.txt.
  65    */
  66   virtual const char* GetName() const { return "if";}
  67
  68   /**
  69    * Succinct documentation.
  70    */
  71   virtual const char* GetTerseDocumentation() const
  72     {
  73     return "Conditionally execute a group of commands.";
  74     }
  75
  76   /**
  77    * This determines if the command is invoked when in script mode.
  78    */
  79   virtual bool IsScriptable() const { return true; }
  80
  81   /**
  82    * More documentation.
  83    */
  84   virtual const char* GetFullDocumentation() const
  85     {
  86     return
  87       "  if(expression)\n"
  88       "    # then section.\n"
  89       "    COMMAND1(ARGS ...)\n"
  90       "    COMMAND2(ARGS ...)\n"
  91       "    ...\n"
  92       "  elseif(expression2)\n"
  93       "    # elseif section.\n"
  94       "    COMMAND1(ARGS ...)\n"
  95       "    COMMAND2(ARGS ...)\n"
  96       "    ...\n"
  97       "  else(expression)\n"
  98       "    # else section.\n"
  99       "    COMMAND1(ARGS ...)\n"
 100       "    COMMAND2(ARGS ...)\n"
 101       "    ...\n"
 102       "  endif(expression)\n"
 103       "Evaluates the given expression.  If the result is true, the commands "
 104       "in the THEN section are invoked.  Otherwise, the commands in the "
 105       "else section are invoked.  The elseif and else sections are "
 106       "optional. You may have multiple elseif clauses. Note that "
 107       "the expression in the else and endif clause is optional. Long "
 108       "expressions can be used and there is a traditional order of "
 109       "precedence. "
 110       "Parenthetical expressions are evaluated first followed by unary "
 111       "operators such as EXISTS, COMMAND, and DEFINED. "
 112       "Then any EQUAL, LESS, GREATER, STRLESS, STRGREATER, STREQUAL, MATCHES "
 113       "will be evaluated. Then NOT operators and finally AND, OR operators "
 114       "will be evaluated. Possible expressions are:\n"
 115       "  if(<constant>)\n"
 116       "True if the constant is 1, ON, YES, TRUE, Y, or a non-zero number.  "
 117       "False if the constant is 0, OFF, NO, FALSE, N, IGNORE, NOTFOUND, '', "
 118       "or ends in the suffix '-NOTFOUND'.  "
 119       "Named boolean constants are case-insensitive.  "
 120       "If the argument is not one of these constants, "
 121       "it is treated as a variable:"
 122       "\n"
 123       "  if(<variable>)\n"
 124       "True if the variable is defined to a value that is not a false "
 125       "constant.  False otherwise.  "
 126       "(Note macro arguments are not variables.)"
 127       "\n"
 128       "  if(NOT <expression>)\n"
 129       "True if the expression is not true."
 130       "\n"
 131       "  if(<expr1> AND <expr2>)\n"
 132       "True if both expressions would be considered true individually."
 133       "\n"
 134       "  if(<expr1> OR <expr2>)\n"
 135       "True if either expression would be considered true individually."
 136       "\n"
 137       "  if(COMMAND command-name)\n"
 138       "True if the given name is a command, macro or function that can be "
 139       "invoked.\n"
 140       "  if(POLICY policy-id)\n"
 141       "True if the given name is an existing policy "
 142       "(of the form CMP<NNNN>).\n"
 143       "  if(TARGET target-name)\n"
 144       "True if the given name is an existing target, built or imported.\n"
 145       "  if(EXISTS file-name)\n"
 146       "  if(EXISTS directory-name)\n"
 147       "True if the named file or directory exists.  "
 148       "Behavior is well-defined only for full paths.\n"
 149       "  if(file1 IS_NEWER_THAN file2)\n"
 150       "True if file1 is newer than file2 or if one of the two files "
 151       "doesn't exist. "
 152       "Behavior is well-defined only for full paths. "
 153       "If the file time stamps are exactly the same, an "
 154       "IS_NEWER_THAN comparison returns true, so that any dependent "
 155       "build operations will occur in the event of a tie. "
 156       "This includes the case of passing the same file name for both "
 157       "file1 and file2.\n"
 158       "  if(IS_DIRECTORY directory-name)\n"
 159       "True if the given name is a directory.  "
 160       "Behavior is well-defined only for full paths.\n"
 161       "  if(IS_SYMLINK file-name)\n"
 162       "True if the given name is a symbolic link.  "
 163       "Behavior is well-defined only for full paths.\n"
 164       "  if(IS_ABSOLUTE path)\n"
 165       "True if the given path is an absolute path.\n"
 166       "  if(<variable|string> MATCHES regex)\n"
 167       "True if the given string or variable's value matches the given "
 168       "regular expression.\n"
 169       "  if(<variable|string> LESS <variable|string>)\n"
 170       "  if(<variable|string> GREATER <variable|string>)\n"
 171       "  if(<variable|string> EQUAL <variable|string>)\n"
 172       "True if the given string or variable's value is a valid number and "
 173       "the inequality or equality is true.\n"
 174       "  if(<variable|string> STRLESS <variable|string>)\n"
 175       "  if(<variable|string> STRGREATER <variable|string>)\n"
 176       "  if(<variable|string> STREQUAL <variable|string>)\n"
 177       "True if the given string or variable's value is lexicographically "
 178       "less (or greater, or equal) than the string or variable on the right.\n"
 179       "  if(<variable|string> VERSION_LESS <variable|string>)\n"
 180       "  if(<variable|string> VERSION_EQUAL <variable|string>)\n"
 181       "  if(<variable|string> VERSION_GREATER <variable|string>)\n"
 182       "Component-wise integer version number comparison (version format is "
 183       "major[.minor[.patch[.tweak]]]).\n"
 184       "  if(DEFINED <variable>)\n"
 185       "True if the given variable is defined. It does not matter if the "
 186       "variable is true or false just if it has been set.\n"
 187       "  if((expression) AND (expression OR (expression)))\n"
 188       "The expressions inside the parenthesis are evaluated first and "
 189       "then the remaining expression is evaluated as in the previous "
 190       "examples. Where there are nested parenthesis the innermost are "
 191       "evaluated as part of evaluating the expression "
 192       "that contains them."
 193       "\n"
 194
 195       "The if command was written very early in CMake's history, predating "
 196       "the ${} variable evaluation syntax, and for convenience evaluates "
 197       "variables named by its arguments as shown in the above signatures.  "
 198       "Note that normal variable evaluation with ${} applies before the "
 199       "if command even receives the arguments.  "
 200       "Therefore code like\n"
 201       "  set(var1 OFF)\n"
 202       "  set(var2 \"var1\")\n"
 203       "  if(${var2})\n"
 204       "appears to the if command as\n"
 205       "  if(var1)\n"
 206       "and is evaluated according to the if(<variable>) case "
 207       "documented above.  "
 208       "The result is OFF which is false.  "
 209       "However, if we remove the ${} from the example then the command sees\n"
 210       "  if(var2)\n"
 211       "which is true because var2 is defined to \"var1\" which is not "
 212       "a false constant."
 213       "\n"
 214       "Automatic evaluation applies in the other cases whenever the "
 215       "above-documented signature accepts <variable|string>:\n"
 216
 217       "1) The left hand argument to MATCHES is first checked to see "
 218       "if it is a defined variable, if so the variable's value is "
 219       "used, otherwise the original value is used. \n"
 220
 221       "2) If the left hand argument to MATCHES is missing it returns "
 222       "false without error \n"
 223
 224       "3) Both left and right hand arguments to LESS GREATER EQUAL "
 225       "are independently tested to see if they are defined variables, "
 226       "if so their defined values are used otherwise the original "
 227       "value is used. \n"
 228
 229       "4) Both left and right hand arguments to STRLESS STREQUAL "
 230       "STRGREATER are independently tested to see if they are defined "
 231       "variables, if so their defined values are used otherwise the "
 232       "original value is used. \n"
 233
 234       "5) Both left and right hand argumemnts to VERSION_LESS "
 235       "VERSION_EQUAL VERSION_GREATER are independently tested to see "
 236       "if they are defined variables, if so their defined values are "
 237       "used otherwise the original value is used. \n"
 238
 239       "6) The right hand argument to NOT is tested to see if it is a "
 240       "boolean constant, if so the value is used, otherwise it is "
 241       "assumed to be a variable and it is dereferenced. \n"
 242
 243       "7) The left and right hand arguments to AND OR are "
 244       "independently tested to see if they are boolean constants, if "
 245       "so they are used as such, otherwise they are assumed to be "
 246       "variables and are dereferenced. \n"
 247       ;
 248     }
 249
 250   // this is a shared function for both If and Else to determine if the
 251   // arguments were valid, and if so, was the response true. If there is
 252   // an error, the errorString will be set.
 253   static bool IsTrue(const std::vector<std::string> &args,
 254     std::string &errorString, cmMakefile *mf,
 255     cmake::MessageType &status);
 256
 257   // Get a definition from the makefile.  If it doesn't exist,
 258   // return the original string.
 259   static const char* GetVariableOrString(const char* str,
 260                                          const cmMakefile* mf);
 261
 262   cmTypeMacro(cmIfCommand, cmCommand);
 263 };
 264
 265
 266 #endif