1# -*- coding:utf-8 -*-
2# Copyright 2016 The Android Open Source Project
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8#      http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15
16"""Functions for working with shell code."""
17
18from __future__ import print_function
19
20import os
21import sys
22
23_path = os.path.realpath(__file__ + '/../..')
24if sys.path[0] != _path:
25    sys.path.insert(0, _path)
26del _path
27
28# pylint: disable=wrong-import-position
29from rh.sixish import string_types
30
31
32# For use by ShellQuote.  Match all characters that the shell might treat
33# specially.  This means a number of things:
34#  - Reserved characters.
35#  - Characters used in expansions (brace, variable, path, globs, etc...).
36#  - Characters that an interactive shell might use (like !).
37#  - Whitespace so that one arg turns into multiple.
38# See the bash man page as well as the POSIX shell documentation for more info:
39#   http://www.gnu.org/software/bash/manual/bashref.html
40#   http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html
41_SHELL_QUOTABLE_CHARS = frozenset('[|&;()<> \t!{}[]=*?~$"\'\\#^')
42# The chars that, when used inside of double quotes, need escaping.
43# Order here matters as we need to escape backslashes first.
44_SHELL_ESCAPE_CHARS = r'\"`$'
45
46
47def shell_quote(s):
48    """Quote |s| in a way that is safe for use in a shell.
49
50    We aim to be safe, but also to produce "nice" output.  That means we don't
51    use quotes when we don't need to, and we prefer to use less quotes (like
52    putting it all in single quotes) than more (using double quotes and escaping
53    a bunch of stuff, or mixing the quotes).
54
55    While python does provide a number of alternatives like:
56     - pipes.quote
57     - shlex.quote
58    They suffer from various problems like:
59     - Not widely available in different python versions.
60     - Do not produce pretty output in many cases.
61     - Are in modules that rarely otherwise get used.
62
63    Note: We don't handle reserved shell words like "for" or "case".  This is
64    because those only matter when they're the first element in a command, and
65    there is no use case for that.  When we want to run commands, we tend to
66    run real programs and not shell ones.
67
68    Args:
69      s: The string to quote.
70
71    Returns:
72      A safely (possibly quoted) string.
73    """
74    if isinstance(s, bytes):
75        s = s.encode('utf-8')
76
77    # See if no quoting is needed so we can return the string as-is.
78    for c in s:
79        if c in _SHELL_QUOTABLE_CHARS:
80            break
81    else:
82        return s if s else u"''"
83
84    # See if we can use single quotes first.  Output is nicer.
85    if "'" not in s:
86        return u"'%s'" % s
87
88    # Have to use double quotes.  Escape the few chars that still expand when
89    # used inside of double quotes.
90    for c in _SHELL_ESCAPE_CHARS:
91        if c in s:
92            s = s.replace(c, r'\%s' % c)
93    return u'"%s"' % s
94
95
96def shell_unquote(s):
97    """Do the opposite of ShellQuote.
98
99    This function assumes that the input is a valid escaped string.
100    The behaviour is undefined on malformed strings.
101
102    Args:
103      s: An escaped string.
104
105    Returns:
106      The unescaped version of the string.
107    """
108    if not s:
109        return ''
110
111    if s[0] == "'":
112        return s[1:-1]
113
114    if s[0] != '"':
115        return s
116
117    s = s[1:-1]
118    output = ''
119    i = 0
120    while i < len(s) - 1:
121        # Skip the backslash when it makes sense.
122        if s[i] == '\\' and s[i + 1] in _SHELL_ESCAPE_CHARS:
123            i += 1
124        output += s[i]
125        i += 1
126    return output + s[i] if i < len(s) else output
127
128
129def cmd_to_str(cmd):
130    """Translate a command list into a space-separated string.
131
132    The resulting string should be suitable for logging messages and for
133    pasting into a terminal to run.  Command arguments are surrounded by
134    quotes to keep them grouped, even if an argument has spaces in it.
135
136    Examples:
137      ['a', 'b'] ==> "'a' 'b'"
138      ['a b', 'c'] ==> "'a b' 'c'"
139      ['a', 'b\'c'] ==> '\'a\' "b\'c"'
140      [u'a', "/'$b"] ==> '\'a\' "/\'$b"'
141      [] ==> ''
142      See unittest for additional (tested) examples.
143
144    Args:
145      cmd: List of command arguments.
146
147    Returns:
148      String representing full command.
149    """
150    # Use str before repr to translate unicode strings to regular strings.
151    return ' '.join(shell_quote(arg) for arg in cmd)
152
153
154def boolean_shell_value(sval, default):
155    """See if |sval| is a value users typically consider as boolean."""
156    if sval is None:
157        return default
158
159    if isinstance(sval, string_types):
160        s = sval.lower()
161        if s in ('yes', 'y', '1', 'true'):
162            return True
163        if s in ('no', 'n', '0', 'false'):
164            return False
165
166    raise ValueError('Could not decode as a boolean value: %r' % (sval,))
167