1# Copyright 2019 - The Android Open Source Project
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15"""The dom_util module.
16
17This module is a collection of the help functions to operate with the minidom
18relevant objects.
19"""
20
21# The temporary pylint disable statements are only used for the skeleton upload.
22# pylint: disable=unused-argument
23# pylint: disable=unnecessary-pass
24
25
26def find_special_node(parent, element_name, attributes=None):
27    """Finds the node contains the specific element.
28
29    Find the node of the element contains the tag of element_name and the
30    attribute values listed in the attributes dict. There're two cases as
31    follows,
32        1. The case with attributes is as below <component name="...">.
33        2. The case without attributes is as below <findStrings>.
34            <component name="FindInProjectRecents">
35              <findStrings>
36                <find>StackInfo</find>
37                <find>attachStartupAgents</find>
38              </findStrings>
39            </component>
40
41    Args:
42        parent: A dom node object hierarchically contains the target_name
43                element object.
44        element_name: A string of the specific element name.
45        attributes: A dict of {'name': 'value', ...} for the attributes used to
46                    match the element.
47
48    Returns:
49        A node object if the element_name target is found, otherwise None.
50    """
51    pass
52
53
54def compare_element_with_attributes(element, attributes=None):
55    """Compares whether the element contains the multiple attributes.
56
57    Args:
58        element: A dom element object which is used to compare with.
59        attributes: A dict of {'name': 'value', ...} for the attributes used to
60                    match the element.
61
62    Returns:
63        boolean: True if the input element contains attributes the same with
64                   the attributes, otherwise False.
65    """
66    pass
67
68
69def update_element_attributes(node, element_name, attribute_set):
70    """Updates attribute values into the matched element in the node.
71
72    Use the element_name and the dict in attribute_set to find the first
73    matched element and update its value with the last two items in
74    attribute_set which are the name and value.
75
76    Example:
77        The following section demonstrates how to use this method to update
78        the PORT value to 3000.
79
80            <component name="RunManager">
81              <configuration name="aidegen_jvm" type="Remote">
82                <module name="remote_template_test" />
83                <option name="HOST" value="localhost" />
84                <option name="PORT" value="5005" />
85              </configuration>
86            </component>
87
88    Args:
89        node: The minidom node object contains the child element to be updated.
90              In the example, it represents the RunManager component node.
91
92        element_name: the string of the element tag, which is the 'option' in
93                      the example.
94
95        attribute_set: A set with 3 parts, ({'name': 'value', ,..}, name, value)
96
97            {'name': 'value', ,..}: A dict of {'name': 'value', ...} for the
98                                    attributes used to match the element.
99            name: A string of the attribute name to update.
100            value: An object with integer or string type used to update to the
101                   name attribute.
102
103            In the example, the ({'name': 'PORT'}, 'value', 3000) is the value
104            of the attribute_set.
105
106    Returns:
107        True if update is successful.
108
109    Raises:
110        TypeError and AttributeError in bad input case.
111    """
112    pass
113
114
115def update_element_with_condition(element, attributes, target_name,
116                                  target_value):
117    """Updates an element if it's fully matched with the compared condition.
118
119    If all the attribute data of the element are the same as attributes,
120    assign target_value to the target_name attribute in it.
121
122    Args:
123        element: The minidom element object.
124        attributes: A dict of {'name 1': 'value 1', ..., 'name n': 'value n'}
125                    for the attributes of the element.
126        target_name: The string of the attribute name.
127        target_value: An integer or string used to set value.
128
129    Returns:
130        boolean: False means there's no such element can be updated.
131
132    Raises:
133        TypeError and AttributeError in bad input case.
134    """
135    pass
136
137
138def insert_element_data(element, attributes, target_name, target_value):
139    """Inserts attribute data to an element.
140
141    Args:
142        element: The minidom element object.
143        attributes: A dict of {'name 1': 'value 1', ..., 'name n': 'value n'}
144                    for the attributes of the element.
145        target_name: The string of the attribute name.
146        target_value: An integer or string used to set value.
147
148    Returns:
149        True if update is successful.
150    """
151    pass
152