From e01d53b816c9fba25a068039e62d8ac9e5e2a971 Mon Sep 17 00:00:00 2001
From: Xavier Claessens <xavier.claessens@collabora.com>
Date: Thu, 2 Mar 2023 11:59:28 -0500
Subject: compiler: Add required keyword to has_* methods

add the "required" keyword to the functions

has_function
has_type
has_member
has_members
has_argument
has_multi_arguments
has_link_argument
has_multi_link_argument
has_function_attribute

Co-authored-by: Milan Hauth <milahu@gmail.com>
---
 .../snippets/required_keyword_for_has_functions.md | 19 ++++++++++
 docs/yaml/objects/compiler.yaml                    | 43 ++++++++++++++++++----
 2 files changed, 54 insertions(+), 8 deletions(-)
 create mode 100644 docs/markdown/snippets/required_keyword_for_has_functions.md

(limited to 'docs')

diff --git a/docs/markdown/snippets/required_keyword_for_has_functions.md b/docs/markdown/snippets/required_keyword_for_has_functions.md
new file mode 100644
index 0000000..0752ac7
--- /dev/null
+++ b/docs/markdown/snippets/required_keyword_for_has_functions.md
@@ -0,0 +1,19 @@
+## All compiler `has_*` methods support the `required` keyword
+
+Now instead of
+
+```meson
+assert(cc.has_function('some_function'))
+assert(cc.has_type('some_type'))
+assert(cc.has_member('struct some_type', 'x'))
+assert(cc.has_members('struct some_type', ['x', 'y']))
+```
+
+we can use
+
+```meson
+cc.has_function('some_function', required: true)
+cc.has_type('some_type', required: true)
+cc.has_member('struct some_type', 'x', required: true)
+cc.has_members('struct some_type', ['x', 'y'], required: true)
+```
diff --git a/docs/yaml/objects/compiler.yaml b/docs/yaml/objects/compiler.yaml
index 4bf69c3..14b61a8 100644
--- a/docs/yaml/objects/compiler.yaml
+++ b/docs/yaml/objects/compiler.yaml
@@ -143,6 +143,19 @@ methods:
         When set to a [`feature`](Build-options.md#features) option, the feature
         will control if it is searched and whether to fail if not found.
 
+- name: _required
+  returns: void
+  description: You have found a bug if you can see this!
+  kwargs:
+    required:
+      type: bool | feature
+      default: false
+      since: 1.1.0
+      description:
+        When set to `true`, Meson will halt if the check fails.
+
+        When set to a [`feature`](Build-options.md#features) option, the feature
+        will control if it is searched and whether to fail if not found.
 
 # Star of the actual functions
 - name: version
@@ -196,7 +209,9 @@ methods:
 - name: has_member
   returns: bool
   description: Returns true if the type has the specified member.
-  kwargs_inherit: compiler._common
+  kwargs_inherit:
+    - compiler._common
+    - compiler._required
   posargs:
     typename:
       type: str
@@ -208,7 +223,9 @@ methods:
 - name: has_members
   returns: bool
   description: Returns `true` if the type has *all* the specified members.
-  kwargs_inherit: compiler._common
+  kwargs_inherit:
+    - compiler._common
+    - compiler._required
   posargs:
     typename:
       type: str
@@ -225,7 +242,9 @@ methods:
     Returns true if the given function is provided
     by the standard library or a library passed in with the `args` keyword.
 
-  kwargs_inherit: compiler._common
+  kwargs_inherit:
+    - compiler._common
+    - compiler._required
   posargs:
     funcname:
       type: str
@@ -234,7 +253,9 @@ methods:
 - name: has_type
   returns: bool
   description: Returns `true` if the specified token is a type.
-  kwargs_inherit: compiler._common
+  kwargs_inherit:
+    - compiler._common
+    - compiler._required
   posargs:
     typename:
       type: str
@@ -457,6 +478,8 @@ methods:
     argument:
       type: str
       description: The argument to check.
+  kwargs_inherit:
+    - compiler._required
 
 - name: has_multi_arguments
   since: 0.37.0
@@ -469,6 +492,8 @@ methods:
     name: arg
     type: str
     description: The arguments to check.
+  kwargs_inherit:
+    - compiler._required
 
 - name: get_supported_arguments
   returns: list[str]
@@ -515,6 +540,8 @@ methods:
     argument:
       type: str
       description: The argument to check.
+  kwargs_inherit:
+    - compiler._required
 
 - name: has_multi_link_arguments
   since: 0.46.0
@@ -527,6 +554,8 @@ methods:
     name: arg
     type: str
     description: The link arguments to check.
+  kwargs_inherit:
+    - compiler._required
 
 - name: get_supported_link_arguments
   returns: list[str]
@@ -556,10 +585,6 @@ methods:
     Given a list of strings, returns the first argument that passes the
     [[compiler.has_link_argument]] test or an empty array if none pass.
 
-
-
-
-
 - name: has_function_attribute
   returns: bool
   since: 0.48.0
@@ -573,6 +598,8 @@ methods:
     name:
       type: str
       description: The attribute name to check.
+  kwargs_inherit:
+    - compiler._required
 
 - name: get_supported_function_attributes
   returns: list[str]
-- 
cgit v1.1