From 4ded401aab760d77f597efee528f593cd32f3c3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Ban=C3=A1k?= <58399088+Filip62@users.noreply.github.com> Date: Tue, 26 Jan 2021 19:16:29 +0100 Subject: [PATCH] Add initial support for an escape character (#2361) Add a config parser method which, for now, deals only with escaping the literal backslash character and logs an error message to inform the user of the coming change. The error message includes a properly escaped value for the user. As a result of introducing an escape character('\'): - Warn the user of any unescaped backslashes, as they will not be treated as a literal character in the future - For now, still treat a single backslash as a literal character - Treat two consecutive backslashes as a single properly escaped literal backslash Also: - Add documentation about the escape character to polybar(5) manpage - Add info about the escape character to changelog - Add testcases for ParseLineKeyTest - Add new test ParseEscapedValueTest Resolves: First step in #2354 Improve value parsing - Take value arg in as an rvalue reference and move parsed value back - Remove unnecessary if statement - Rename function - Improve error message - Improve function description - Format Add escape character documentation to manpages Add information about the escape character to the polybar(5) manpage. Add info about the esacape character to changelog Add test cases for ParseLineKeyTest Fix ParseLineKeyTest test cases Also make config parser method parse_escaped_value private. Add tests for escaped_value_parser method Also remove unsued include statement Simplify parse_escaped_value in config_parser Remove unnecessary escaped value generation, so we do not have to keep track of index differences. Fix ParseEscapedValueTest test cases Fix parse_escaped_value Add more test cases for ParseLineKeyTest Update CHANGELOG.md Co-authored-by: Patrick Ziegler Adress review - Adjust documentation - Small code changes Improve parse_escaped_value Add initial support for an escape character Add a config parser method which, for now, deals only with escaping the literal backslash character and logs an error message to inform the user of the coming change. The error message includes a properly escaped value for the user. As a result of introducing an escape character('\'): - Warn the user of any unescaped backslashes, as they will not be treated as a literal character in the future - For now, still treat a single backslash as a literal character - Treat two consecutive backslashes as a single properly escaped literal backslash Resolves: First step in #2354 Improve value parsing - Take value arg in as an rvalue reference and move parsed value back - Remove unnecessary if statement - Rename function - Improve error message - Improve function description - Format Add info about the esacape character to changelog Add test cases for ParseLineKeyTest Fix ParseLineKeyTest test cases Also make config parser method parse_escaped_value private. Add tests for escaped_value_parser method Also remove unsued include statement Simplify parse_escaped_value in config_parser Remove unnecessary escaped value generation, so we do not have to keep track of index differences. Fix ParseEscapedValueTest test cases Add more test cases for ParseLineKeyTest Adress review - Adjust documentation - Small code changes Remove duplicate testcase from ParseLineKeyTest Add initial support for an escape character Add a config parser method which, for now, deals only with escaping the literal backslash character and logs an error message to inform the user of the coming change. The error message includes a properly escaped value for the user. As a result of introducing an escape character('\'): - Warn the user of any unescaped backslashes, as they will not be treated as a literal character in the future - For now, still treat a single backslash as a literal character - Treat two consecutive backslashes as a single properly escaped literal backslash Resolves: First step in #2354 Improve value parsing - Take value arg in as an rvalue reference and move parsed value back - Remove unnecessary if statement - Rename function - Improve error message - Improve function description - Format Fix ParseLineKeyTest test cases Also make config parser method parse_escaped_value private. Remove duplicate testcase from ParseLineKeyTest --- CHANGELOG.md | 10 +++++ doc/man/polybar.5.rst | 17 +++++++- include/components/config_parser.hpp | 6 +++ src/components/config_parser.cpp | 23 +++++++++++ tests/unit_tests/components/config_parser.cpp | 40 +++++++++++++++++++ 5 files changed, 95 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e86fcb45..4850759a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Breaking +- We added the backslash escape character (\\) for configuration values. This + means that the literal backslash character now has special meaning in + configuration files, therefore if you want to use it in a value as a literal + backslash, you need to escape it with the backslash escape character. The + parser logs an error if any unescaped backslashes are found in a value. This + affects you only if you are using two consecutive backslashes in a value, + which will now be interpreted as a single literal backslash. + [`#2354`](https://github.com/polybar/polybar/issues/2354) - We rewrote our tag parser. This shouldn't break anything, if you experience any problems, please let us know. The new parser now gives errors for certain invalid tags where the old parser @@ -42,6 +50,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 repository. ### Added +- The backslash escape character (\\). + [`#2354`](https://github.com/polybar/polybar/issues/2354) - Warn states for the cpu, memory, fs, and battery modules. ([`#570`](https://github.com/polybar/polybar/issues/570), [`#956`](https://github.com/polybar/polybar/issues/956), diff --git a/doc/man/polybar.5.rst b/doc/man/polybar.5.rst index 4c2b1761..9970c986 100644 --- a/doc/man/polybar.5.rst +++ b/doc/man/polybar.5.rst @@ -128,7 +128,22 @@ in double-quotes: name = " value " -Here ``name`` has a leading and trailing whitespace. +Here the value of the ``name`` key has a leading and trailing whitespace. + +To treat characters with special meaning as literal characters, you need to +prepend them with the backslash (``\``) escape character: + +:: + + name = "value\\value\\value" + +Value of this key ``name`` results in ``value\value\value``. + +.. note:: + + The only character with a special meaning right now is the backslash character + (``\``), which serves as the escape character. + More will be added in the future. Empty Lines & Comments ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/include/components/config_parser.hpp b/include/components/config_parser.hpp index 2fc38a19..f341074a 100644 --- a/include/components/config_parser.hpp +++ b/include/components/config_parser.hpp @@ -190,6 +190,12 @@ class config_parser { */ std::pair parse_key(const string& line); + /** + * \brief Parses the given value, checks if the given value contains + * one or more unescaped backslashes and logs an error if yes + */ + string parse_escaped_value(string&& value, const string& key); + /** * \brief Name of all the files the config includes values from * diff --git a/src/components/config_parser.cpp b/src/components/config_parser.cpp index dca093ea..eb97a2c0 100644 --- a/src/components/config_parser.cpp +++ b/src/components/config_parser.cpp @@ -257,6 +257,8 @@ std::pair config_parser::parse_key(const string& line) { throw invalid_name_error("Key", key); } + value = parse_escaped_value(move(value), key); + /* * Only if the string is surrounded with double quotes, do we treat them * not as part of the value and remove them. @@ -292,4 +294,25 @@ bool config_parser::is_valid_name(const string& name) { return true; } +string config_parser::parse_escaped_value(string&& value, const string& key) { + string cfg_value = value; + bool log = false; + auto backslash_pos = value.find('\\'); + while (backslash_pos != string::npos) { + if (backslash_pos == value.size() - 1 || value[backslash_pos + 1] != '\\') { + log = true; + } else { + value = value.replace(backslash_pos, 2, "\\"); + } + backslash_pos = value.find('\\', backslash_pos + 1); + } + if (log) { + // TODO Log filename, and line number + m_log.err( + "Value '%s' of key '%s' contains one or more unescaped backslashes, please prepend them with the backslash " + "escape character.", + cfg_value, key); + } + return move(value); +} POLYBAR_NS_END diff --git a/tests/unit_tests/components/config_parser.cpp b/tests/unit_tests/components/config_parser.cpp index 921815bb..71b118c7 100644 --- a/tests/unit_tests/components/config_parser.cpp +++ b/tests/unit_tests/components/config_parser.cpp @@ -24,6 +24,9 @@ class TestableConfigParser : public config_parser { public: using config_parser::parse_line; + public: + using config_parser::parse_escaped_value; + public: using config_parser::m_files; }; @@ -64,6 +67,12 @@ vector, string>> parse_line_key_list = { {{"key", "value"}, " key = value"}, {{"key", ""}, " key\t = \"\""}, {{"key", "\""}, " key\t = \"\"\""}, + {{"key", "\\"}, " key = \\"}, + {{"key", "\\"}, " key = \\\\"}, + {{"key", "\\val\\ue\\"}, " key = \\val\\ue\\"}, + {{"key", "\\val\\ue\\"}, " key = \\\\val\\\\ue\\\\"}, + {{"key", "\\val\\ue\\"}, " key = \"\\val\\ue\\\""}, + {{"key", "\\val\\ue\\"}, " key = \"\\\\val\\\\ue\\\\\""}, }; INSTANTIATE_TEST_SUITE_P(Inst, ParseLineInValidTest, ::testing::ValuesIn(parse_line_invalid_list)); @@ -236,3 +245,34 @@ TEST_F(ParseHeaderTest, throwsSyntaxError) { EXPECT_THROW(parser->parse_header("[root]"), syntax_error); } // }}} + +// ParseEscapedValueTest {{{ + +/** + * \brief Class for parameterized tests on parse_escaped_value + * + * The first element of the pair is the expected value and the second + * element is the escaped string to be parsed. + */ +class ParseEscapedValueTest : public ConfigParser, public ::testing::WithParamInterface> {}; + +vector> parse_escaped_value_list = { + {"\\", "\\"}, + {"\\", "\\\\"}, + {"\\val\\ue\\", "\\val\\ue\\"}, + {"\\val\\ue\\", "\\\\val\\\\ue\\\\"}, + {"\"\\val\\ue\\\"", "\"\\val\\ue\\\""}, + {"\"\\val\\ue\\\"", "\"\\\\val\\\\ue\\\\\""}, +}; + +INSTANTIATE_TEST_SUITE_P(Inst, ParseEscapedValueTest, ::testing::ValuesIn(parse_escaped_value_list)); + +/** + * Parameterized test for parse_escaped_value with valid line + */ +TEST_P(ParseEscapedValueTest, correctness) { + string value = GetParam().second; + value = parser->parse_escaped_value(move(value), "key"); + EXPECT_EQ(GetParam().first, value); +} +// }}}