Compile Waivers Examples
------------------------

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - **Use Case**
     - **Solution**
   * - I want to hide all problems from a library that I do not control.
     - .. code-block:: 
        
            <waiver name="Disable all from library folder." severity="DISABLED">
                <match path="/path/to/library/*"/>
            </waiver>
   * - I want to hide some errors that I don't care about.
     - .. code-block::

            <waiver name="Disable all that match a specific message pattern." severity="DISABLED">
                <match message="*some message pattern*"/>
            </waiver>
   * - I want to turn NON_STANDARD warnings into errors.
     - .. code-block::

            <waiver name="Promote NON_STANDARD warnings to errors." severity="ERROR">
                <match message="NON_STANDARD*"/>
            </waiver>
   * - I want to see only the problems reported on files in a specific directory.
     - Create a waiver to disable all problems: 
        
       .. code-block::
        
            <waiver name="Disable all" severity="DISABLED">
                <match path="*"/>
            </waiver>

       After it, create a waiver to restore the severity of the problems inside a specific path: 
       
       .. code-block::
    
            <waiver name="Restore my problems" severity="DEFAULT">
                <match path="/my/path"/>
            </waiver>
   * - I want to hide some DVT false alarms until the issue causing them is fixed.
     - Use a message based and/or path based waiver.


Each problem message is in the form:

 <CHECK_ID>: <Failure Details>
 
or, for |non-top-files|:

 _<CHECK_ID>: <Failure Details>

See :ref:`Semantic Checks` for a complete list of all checks and their identifiers.

This allows you to change the severity by check id using a waiver like:

 <waiver name="Disable all <CHECK_ID>" severity="DISABLED">


Compile Waivers File Syntax (XML)
---------------------------------

.. code-block:: xml

    <!--
    XML file header; required.
    -->
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE waivers PUBLIC "-//DVT//waivers" "waivers.dtd" >

    <!--
    Root tag; required.
    Version attribute is required.
    The latest syntax version, illustrated by this example, is version 1.
    -->
    <waivers version="1">
    <!--
        You can include waivers from other waiver files. The syntax of the
        included files is the same as the one presented below. You may use
        environment variables in the path to the included waiver files.
        You can use either an absolute path or a relative path.
        If no file matches the path relative to the project's location, DVT will
        try to resolve it relative to the folder containing the including file.
        If no file is located in any of the specified locations an error will be
        displayed unless the optional attribute is set to "true". The default
        value of the optional attribute is "false".
    -->
    <include optional="true" path="$COMMON/path/to/included_waivers.xml"/>
    <!--
        The waiver tag must specify the NEW severity of the problems
        waived by this waiver; it can be one of ERROR, WARNING, DISABLED or DEFAULT.
    -->
    <waiver name="Optional short name of the waiver" severity="DISABLED">
        <description>An optional verbose description of the waiver.</description>
        <!--
            Each waiver must contain at least one match tag.
            Each match tag can specify any combination of the following attributes: message pattern, path pattern, default-severity.
            Any omitted attribute is implicitly matched.
            A match tag without any attributes will match all problems.

            A match tag matches a problem if ALL specified patterns and the default-severity match.
            The waiver will waive a problem if ANY of the match tags matches.
            NOTE:
                path pattern is matched against the problem's full path (NOT the project relative path)
                default-severity is matched against the problem's initial reported severity
                patterns may contain * or ? wildcards
        -->
        <match
            message="pattern to match against the problem's message"
            path="/pattern/to/match/against/the/problems/absolute/path"/>
        <match message="*message pattern*" path="/path/pattern*"/>
        <match message="*only by message*"/>
        <match path="/only/by/path*"/>
        <match path="/all/warnings/in/path/*" default-severity="WARNING"/>
    </waiver>
    <!-- Further example waivers -->
    <waiver name="Disable by message" severity="DISABLED">
        <description>
            This waiver disables all problems containing 'JUST_A_FOO_PROBLEM'
            inside their message.
        </description>
        <match message="*JUST_A_FOO_PROBLEM*"/>
    </waiver>
    <waiver name="Demote by path" severity="WARNING">
        <description>
            This waiver turns into warnings all problems reported
            under '/path/to/foo'
        </description>
        <match path="/path/to/foo/*"/>
    </waiver>
    <waiver name="Promote by path OR message" severity="ERROR">
        <description>
            This waiver turns into errors all problems that
            contain 'JUST_A_FOO_PROBLEM' inside their message OR were reported
            under '/path/to/foo'.</description>
        <match message="*JUST_A_FOO_PROBLEM*"/>
        <match path="/path/to/foo/*"/>
    </waiver>
    <waiver name="Disable by path AND message" severity="DISABLED">
        <description>
            This waiver disables all problems that contain 'JUST_A_FOO_PROBLEM'
            inside their message AND were reported
            under '/path/to/foo'.</description>
        <match message="*JUST_A_FOO_PROBLEM*" path="/path/to/foo/*"/>
    </waiver>
    </waivers>
 
.. note:: 
   
   Backslashes **\\** are always treated as path separators, regardless of the OS. Therefore, you cannot use **\\?** and **\\*** to escape wildcards.
