name: feature
long_name: Feature option object
since: 0.47.0
description: Meson object representing a [`feature` options](Build-options.md#features)

methods:
- name: enabled
  returns: bool
  description: Returns whether the feature was set to `'enabled'`

- name: disabled
  returns: bool
  description: Returns whether the feature was set to `'disabled'`

- name: auto
  returns: bool
  description: Returns whether the feature was set to `'auto'`

- name: allowed
  since: 0.59.0
  returns: bool
  description: Returns whether the feature was set to `'enabled'` or `'auto'`

- name: disable_auto_if
  since: 0.59.0
  returns: feature
  description: |
    Returns the feature, with `'auto'` converted to `'disabled'` if value is true.

    | Feature / Condition | `value = true` | `value = false` |
    | ------------------- | -------------- | --------------- |
    | Enabled             | Enabled        | Enabled         |
    | Disabled            | Disabled       | Disabled        |
    | Auto                | Disabled       | Auto            |

  posargs:
    value:
      type: bool
      description: See the table above

- name: enable_auto_if
  since: 1.1.0
  returns: feature
  description: |
    Returns the feature, with `'auto'` converted to `'enabled'` if value is true.

    | Feature / Condition | `value = true` | `value = false` |
    | ------------------- | -------------- | --------------- |
    | Enabled             | Enabled        | Enabled         |
    | Disabled            | Disabled       | Disabled        |
    | Auto                | Enabled        | Auto            |

  posargs:
    value:
      type: bool
      description: See the table above

- name: require
  returns: feature
  since: 0.59.0
  description: |
    Returns the object itself if the value is true; an error if the object is
    `'enabled'` and the value is false; a disabled feature if the object
    is `'auto'` or `'disabled'` and the value is false.

  example: |
    `require` is useful to restrict the applicability of `'auto'` features,
    for example based on other features or on properties of the host machine:

    ```
    if get_option('directx').require(host_machine.system() == 'windows',
          error_message: 'DirectX only available on Windows').allowed() then
      src += ['directx.c']
      config.set10('HAVE_DIRECTX', true)
    endif
    ```

  posargs:
    value:
      type: bool
      description: The value to check

  kwargs:
    error_message:
      type: str
      default: "''"
      description: The error Message to print if the check fails

- name: enable_if
  returns: feature
  since: 1.1.0
  description: |
    Returns the object itself if the value is false; an error if the object is
    `'disabled'` and the value is true; an enabled feature if the object
    is `'auto'` or `'enabled'` and the value is true.

  example: |
    `enable_if` is useful to restrict the applicability of `'auto'` features,
    particularly when passing them to [[dependency]]:

    ```
    use_llvm = get_option('llvm').enable_if(with_clang).enable_if(with_llvm_libs)
    dep_llvm = dependency('llvm', require : use_llvm)
    ```

  posargs:
    value:
      type: bool
      description: The value to check

  kwargs:
    error_message:
      type: str
      default: "''"
      description: The error Message to print if the check fails

- name: disable_if
  returns: feature
  since: 1.1.0
  description: |
    Returns the object itself if the value is false; an error if the object is
    `'enabled'` and the value is true; a disabled feature if the object
    is `'auto'` or `'disabled'` and the value is true.

    This is equivalent to `feature_opt.require(not condition)`, but may make
    code easier to reason about, especially when mixed with `enable_if`

  example: |
    `disable_if` is useful to restrict the applicability of `'auto'` features,
    particularly when passing them to [[dependency]]:

    ```
    use_os_feature = get_option('foo') \
      .disable_if(host_machine.system() == 'darwin', error_message : 'os feature not supported on MacOS')
    dep_os_feature = dependency('os_feature', require : use_os_feature)
    ```

  posargs:
    value:
      type: bool
      description: The value to check

  kwargs:
    error_message:
      type: str
      default: "''"
      description: The error Message to print if the check fails