Merge topic 'FindBISON-DEFINES_FILE'

6863c0d5 Help: Add notes for topic 'FindBISON-DEFINES_FILE'
12e534c2 FindBISON: Add DEFINES_FILE option to pass --defines=FILE
eb859263 FindBISON: Use CMAKE_PARSE_ARGUMENTS to parse arguments
29985ad8 FindBISON: Use BISON_TARGET macro argument names internally
801b799f FindBISON: Improve documentation formatting

2 files changed, 100 insertions, 61 deletions

diff --git a/Help/release/dev/FindBISON-DEFINES_FILE.rst b/Help/release/dev/FindBISON-DEFINES_FILE.rst
new file mode 100644
index 0000000..815d560
--- /dev/null
+++ b/Help/release/dev/FindBISON-DEFINES_FILE.rst
@@ -0,0 +1,6 @@
+FindBISON-DEFINES_FILE
+----------------------
+
+* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a
+  new ``DEFINES_FILE`` option to specify a custom output header
+  to be generated.
diff --git a/Modules/FindBISON.cmake b/Modules/FindBISON.cmake
index ec3ee78..7d81276 100644
--- a/Modules/FindBISON.cmake
+++ b/Modules/FindBISON.cmake
@@ -2,60 +2,75 @@
 # FindBISON
 # ---------
 #
-# Find bison executable and provides macros to generate custom build rules
+# Find ``bison`` executable and provide a macro to generate custom build rules.
 #
 # The module defines the following variables:
 #
-# ::
+# ``BISON_EXECUTABLE``
+#   path to the ``bison`` program
 #
-#   BISON_EXECUTABLE - path to the bison program
-#   BISON_VERSION - version of bison
-#   BISON_FOUND - true if the program was found
+# ``BISON_VERSION``
+#   version of ``bison``
 #
+# ``BISON_FOUND``
+#   true if the program was found
 #
+# The minimum required version of ``bison`` can be specified using the
+# standard CMake syntax, e.g.  ``find_package(BISON 2.1.3)``.
 #
-# The minimum required version of bison can be specified using the
-# standard CMake syntax, e.g.  find_package(BISON 2.1.3)
+# If ``bison`` is found, the module defines the macro::
 #
-# If bison is found, the module defines the macros:
+#   BISON_TARGET(<Name> <YaccInput> <CodeOutput>
+#                [COMPILE_FLAGS <flags>]
+#                [DEFINES_FILE <file>]
+#                [VERBOSE <file>]
+#                )
 #
-# ::
+# which will create a custom rule to generate a parser.  ``<YaccInput>`` is
+# the path to a yacc file.  ``<CodeOutput>`` is the name of the source file
+# generated by bison.  A header file is also be generated, and contains
+# the token list.
 #
-#   BISON_TARGET(<Name> <YaccInput> <CodeOutput> [VERBOSE <file>]
-#               [COMPILE_FLAGS <string>])
+# The options are:
 #
-# which will create a custom rule to generate a parser.  <YaccInput> is
-# the path to a yacc file.  <CodeOutput> is the name of the source file
-# generated by bison.  A header file is also be generated, and contains
-# the token list.  If COMPILE_FLAGS option is specified, the next
-# parameter is added in the bison command line.  if VERBOSE option is
-# specified, <file> is created and contains verbose descriptions of the
-# grammar and parser.  The macro defines a set of variables:
+# ``COMPILE_FLAGS <flags>``
+#   Specify flags to be added to the ``bison`` command line.
+#
+# ``DEFINES_FILE <file>``
+#   Specify a non-default header ``<file>`` to be generated by ``bison``.
+#
+# ``VERBOSE <file>``
+#   Tell ``bison`` to write verbose descriptions of the grammar and
+#   parser to the given ``<file>``.
 #
-# ::
+# The macro defines the following variables:
 #
-#   BISON_${Name}_DEFINED - true is the macro ran successfully
-#   BISON_${Name}_INPUT - The input source file, an alias for <YaccInput>
-#   BISON_${Name}_OUTPUT_SOURCE - The source file generated by bison
-#   BISON_${Name}_OUTPUT_HEADER - The header file generated by bison
-#   BISON_${Name}_OUTPUTS - The sources files generated by bison
-#   BISON_${Name}_COMPILE_FLAGS - Options used in the bison command line
+# ``BISON_<Name>_DEFINED``
+#   true is the macro ran successfully
 #
+# ``BISON_<Name>_INPUT``
+#   The input source file, an alias for <YaccInput>
 #
+# ``BISON_<Name>_OUTPUT_SOURCE``
+#   The source file generated by bison
 #
-# ::
+# ``BISON_<Name>_OUTPUT_HEADER``
+#   The header file generated by bison
 #
-#   ====================================================================
-#   Example:
+# ``BISON_<Name>_OUTPUTS``
+#   The sources files generated by bison
 #
+# ``BISON_<Name>_COMPILE_FLAGS``
+#   Options used in the ``bison`` command line
 #
+# Example usage:
 #
-# ::
+# .. code-block:: cmake
 #
-#    find_package(BISON)
-#    BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
-#    add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
-#   ====================================================================
+#   find_package(BISON)
+#   BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
+#                DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
+#   add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
 
 #=============================================================================
 # Copyright 2009 Kitware, Inc.
@@ -74,6 +89,8 @@
 find_program(BISON_EXECUTABLE NAMES bison win_bison DOC "path to the bison executable")
 mark_as_advanced(BISON_EXECUTABLE)
 
+include(CMakeParseArguments)
+
 if(BISON_EXECUTABLE)
   # the bison commands should be executed with the C locale, otherwise
   # the message (which are parsed) may be translated
@@ -128,6 +145,12 @@ if(BISON_EXECUTABLE)
     list(APPEND BISON_TARGET_cmdopt ${BISON_TARGET_extraopts})
   endmacro()
 
+  # internal macro
+  macro(BISON_TARGET_option_defines Header)
+    set(BISON_TARGET_output_header "${Header}")
+    list(APPEND BISON_TARGET_cmdopt --defines=${BISON_TARGET_output_header})
+  endmacro()
+
   #============================================================
   # BISON_TARGET (public macro)
   #============================================================
@@ -136,51 +159,61 @@ if(BISON_EXECUTABLE)
     set(BISON_TARGET_output_header "")
     set(BISON_TARGET_cmdopt "")
     set(BISON_TARGET_outputs "${BisonOutput}")
-    if(NOT ${ARGC} EQUAL 3 AND NOT ${ARGC} EQUAL 5 AND NOT ${ARGC} EQUAL 7)
+
+    # Parsing parameters
+    set(BISON_TARGET_PARAM_OPTIONS)
+    set(BISON_TARGET_PARAM_ONE_VALUE_KEYWORDS
+      VERBOSE
+      COMPILE_FLAGS
+      DEFINES_FILE
+      )
+    set(BISON_TARGET_PARAM_MULTI_VALUE_KEYWORDS)
+    cmake_parse_arguments(
+        BISON_TARGET_ARG
+        "${BISON_TARGET_PARAM_OPTIONS}"
+        "${BISON_TARGET_PARAM_ONE_VALUE_KEYWORDS}"
+        "${BISON_TARGET_PARAM_MULTI_VALUE_KEYWORDS}"
+        ${ARGN}
+    )
+
+    if(NOT "${BISON_TARGET_ARG_UNPARSED_ARGUMENTS}" STREQUAL "")
       message(SEND_ERROR "Usage")
     else()
-      # Parsing parameters
-      if(${ARGC} GREATER 5 OR ${ARGC} EQUAL 5)
-        if("${ARGV3}" STREQUAL "VERBOSE")
-          BISON_TARGET_option_verbose(${Name} ${BisonOutput} "${ARGV4}")
-        endif()
-        if("${ARGV3}" STREQUAL "COMPILE_FLAGS")
-          BISON_TARGET_option_extraopts("${ARGV4}")
-        endif()
+      if(NOT "${BISON_TARGET_ARG_VERBOSE}" STREQUAL "")
+        BISON_TARGET_option_verbose(${Name} ${BisonOutput} "${BISON_TARGET_ARG_VERBOSE}")
       endif()
-
-      if(${ARGC} EQUAL 7)
-        if("${ARGV5}" STREQUAL "VERBOSE")
-          BISON_TARGET_option_verbose(${Name} ${BisonOutput} "${ARGV6}")
-        endif()
-
-        if("${ARGV5}" STREQUAL "COMPILE_FLAGS")
-          BISON_TARGET_option_extraopts("${ARGV6}")
-        endif()
+      if(NOT "${BISON_TARGET_ARG_COMPILE_FLAGS}" STREQUAL "")
+        BISON_TARGET_option_extraopts("${BISON_TARGET_ARG_COMPILE_FLAGS}")
+      endif()
+      if(NOT "${BISON_TARGET_ARG_DEFINES_FILE}" STREQUAL "")
+        BISON_TARGET_option_defines("${BISON_TARGET_ARG_DEFINES_FILE}")
       endif()
 
-      # Header's name generated by bison (see option -d)
-      list(APPEND BISON_TARGET_cmdopt "-d")
-      string(REGEX REPLACE "^(.*)(\\.[^.]*)$" "\\2" _fileext "${ARGV2}")
-      string(REPLACE "c" "h" _fileext ${_fileext})
-      string(REGEX REPLACE "^(.*)(\\.[^.]*)$" "\\1${_fileext}"
-          BISON_${Name}_OUTPUT_HEADER "${ARGV2}")
-      list(APPEND BISON_TARGET_outputs "${BISON_${Name}_OUTPUT_HEADER}")
+      if("${BISON_TARGET_output_header}" STREQUAL "")
+        # Header's name generated by bison (see option -d)
+        list(APPEND BISON_TARGET_cmdopt "-d")
+        string(REGEX REPLACE "^(.*)(\\.[^.]*)$" "\\2" _fileext "${BisonOutput}")
+        string(REPLACE "c" "h" _fileext ${_fileext})
+        string(REGEX REPLACE "^(.*)(\\.[^.]*)$" "\\1${_fileext}"
+            BISON_TARGET_output_header "${BisonOutput}")
+      endif()
+      list(APPEND BISON_TARGET_outputs "${BISON_TARGET_output_header}")
 
       add_custom_command(OUTPUT ${BISON_TARGET_outputs}
         ${BISON_TARGET_extraoutputs}
         COMMAND ${BISON_EXECUTABLE}
-        ARGS ${BISON_TARGET_cmdopt} -o ${ARGV2} ${ARGV1}
-        DEPENDS ${ARGV1}
+        ARGS ${BISON_TARGET_cmdopt} -o ${BisonOutput} ${BisonInput}
+        DEPENDS ${BisonInput}
         COMMENT "[BISON][${Name}] Building parser with bison ${BISON_VERSION}"
         WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
 
       # define target variables
       set(BISON_${Name}_DEFINED TRUE)
-      set(BISON_${Name}_INPUT ${ARGV1})
+      set(BISON_${Name}_INPUT ${BisonInput})
       set(BISON_${Name}_OUTPUTS ${BISON_TARGET_outputs})
       set(BISON_${Name}_COMPILE_FLAGS ${BISON_TARGET_cmdopt})
       set(BISON_${Name}_OUTPUT_SOURCE "${BisonOutput}")
+      set(BISON_${Name}_OUTPUT_HEADER "${BISON_TARGET_output_header}")
 
     endif()
   endmacro()