Add 'disabler' argument to functions returning not-found objects

When dependency(), find_library(), find_program(), or
python.find_installation() return a not-found object and disabler is
true, they return a Disabler object instead.

3 files changed, 19 insertions, 0 deletions

diff --git a/docs/markdown/Python-module.md b/docs/markdown/Python-module.md
index 2bcad78..93005ea 100644
--- a/docs/markdown/Python-module.md
+++ b/docs/markdown/Python-module.md
@@ -48,6 +48,9 @@ Keyword arguments are the following:
   whether it was found or not. Since *0.48.0*  the value of a
   [`feature`](Build-options.md#features) option can also be passed to the
   `required` keyword argument.
+- `disabler`: if `true` and no python installation can be found, return a
+  [disabler object](#disabler-object) instead of a not-found object.
+  *Since 0.49.0*
 
 **Returns**: a [python installation][`python_installation` object]
 
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 69d895e..7a63d32 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -408,6 +408,9 @@ otherwise. This function supports the following keyword arguments:
 [library-specific](Dependencies.md#dependencies-with-custom-lookup-functionality)
 keywords may also be accepted (e.g. `modules` specifies submodules to use for
 dependencies such as Qt5 or Boost. )
+- `disabler` if `true` and the dependency couldn't be found, return a
+  [disabler object](#disabler-object) instead of a not-found dependency.
+  *Since 0.49.0*
 
 If dependency_name is `''`, the dependency is always not found.  So with
 `required: false`, this always returns a dependency object for which the
@@ -600,6 +603,10 @@ Keyword arguments are the following:
   defined there, then from the system. If set to `true`, the cross
   file is ignored and the program is only searched from the system.
 
+- `disabler` if `true` and the program couldn't be found, return a
+  [disabler object](#disabler-object) instead of a not-found object.
+  *Since 0.49.0*
+
 Meson will also autodetect scripts with a shebang line and run them
 with the executable/interpreter specified in it both on Windows
 (because the command invocator will reject the command otherwise) and
@@ -1666,6 +1673,9 @@ the following methods:
   argument, which can be either a string or a list of strings.  Since
   *0.47.0* the value of a [`feature`](Build-options.md#features)
   option can also be passed to the `required` keyword argument.
+  *Since 0.49.0* if the keyword argument `disabler` is `true` and the
+  dependency couldn't be found, return a [disabler object](#disabler-object)
+  instead of a not-found dependency.
 
 - `first_supported_argument(list_of_strings)`, given a list of
   strings, returns the first argument that passes the `has_argument`
diff --git a/docs/markdown/snippets/disabler.md b/docs/markdown/snippets/disabler.md
new file mode 100644
index 0000000..76874f6
--- /dev/null
+++ b/docs/markdown/snippets/disabler.md
@@ -0,0 +1,6 @@
+## Return `Disabler()` instead of not-found object
+
+Functions such as `dependency()`, `find_library()`, `find_program()`, and
+`python.find_installation()` have a new keyword argument: `disabler`. When set
+to `true` those functions return `Disabler()` objects instead of not-found
+objects.