diff --git a/docs/user/ppl/general/comments.rst b/docs/user/ppl/general/comments.rst new file mode 100644 index 0000000000..a0994e970c --- /dev/null +++ b/docs/user/ppl/general/comments.rst @@ -0,0 +1,44 @@ +======== +Comments +======== + +.. rubric:: Table of contents + +.. contents:: + :local: + :depth: 2 + + +Comments are not evaluated texts. PPL supports both line comments and block comments. + +Line Comments +------------- +Line comments begin with two slashes ( // ) and end with a new line. + +Example:: + + os> source=accounts | top gender // finds most common gender of all the accounts + fetched rows / total rows = 2/2 + +----------+ + | gender | + |----------| + | M | + | F | + +----------+ + +Block Comments +-------------- +Block comments begin with a slash followed by an asterisk ( /\* ) and end with an asterisk followed by a slash ( \*/ ). + +Example:: + + os> source=accounts | dedup 2 gender /* dedup the document with gender field keep 2 duplication */ | fields account_number, gender + fetched rows / total rows = 3/3 + +------------------+----------+ + | account_number | gender | + |------------------+----------| + | 1 | M | + | 6 | M | + | 13 | F | + +------------------+----------+ + diff --git a/integ-test/src/test/java/org/opensearch/sql/ppl/CommentIT.java b/integ-test/src/test/java/org/opensearch/sql/ppl/CommentIT.java new file mode 100644 index 0000000000..2ef2ecbb5b --- /dev/null +++ b/integ-test/src/test/java/org/opensearch/sql/ppl/CommentIT.java @@ -0,0 +1,94 @@ +/* + * Copyright OpenSearch Contributors + * SPDX-License-Identifier: Apache-2.0 + */ + +package org.opensearch.sql.ppl; + +import static org.opensearch.sql.legacy.TestsConstants.TEST_INDEX_ACCOUNT; +import static org.opensearch.sql.util.MatcherUtils.rows; +import static org.opensearch.sql.util.MatcherUtils.verifyDataRows; + +import java.io.IOException; +import org.json.JSONObject; +import org.junit.jupiter.api.Test; + +public class CommentIT extends PPLIntegTestCase { + @Override + public void init() throws IOException { + loadIndex(Index.ACCOUNT); + } + + @Test + public void testMultipleLinesCommand() throws IOException { + // source=accounts + // | fields firstname + // | where firstname='Amber' + // | fields firstname + JSONObject result = + executeQuery( + String.format( + "source=%s \\n" + + "| fields firstname \\n" + + "| where firstname='Amber' \\n" + + "| fields firstname", + TEST_INDEX_ACCOUNT)); + verifyDataRows(result, rows("Amber")); + } + + @Test + public void testLineComment() throws IOException { + // // line comment + // source=accounts | fields firstname // line comment + // | where firstname='Amber' // line comment + // | fields firstname // line comment + // /////////line comment + JSONObject result = + executeQuery( + String.format( + "// line comment\\n" + + "source=%s | fields firstname // line comment\\n" + + "| where firstname='Amber' // line comment\\n" + + "| fields firstname // line comment\\n" + + "/////////line comment", + TEST_INDEX_ACCOUNT)); + verifyDataRows(result, rows("Amber")); + } + + @Test + public void testBlockComment() throws IOException { + // /* + // This is a + // multiple + // line block + // comment */ + // search /* block comment */ source=accounts /* block comment */ + // | fields /* + // This is a + // multiple + // line + // block + // comment */ firstname + // | /* block comment */ where firstname='Amber' + // | fields /* block comment */ firstname + JSONObject result = + executeQuery( + String.format( + "/*\\n" + + "This is a\\n" + + " multiple\\n" + + "line block\\n" + + " comment */\\n" + + "search /* block comment */ source=%s /* block comment */\\n" + + "| fields /*\\n" + + " This is a\\n" + + " multiple\\n" + + " line\\n" + + " block\\n" + + " comment */ firstname\\n" + + "| /* block comment */ where firstname='Amber'\\n" + + "| fields /* block comment */ firstname", + TEST_INDEX_ACCOUNT)); + verifyDataRows(result, rows("Amber")); + } +} diff --git a/ppl/src/main/antlr/OpenSearchPPLLexer.g4 b/ppl/src/main/antlr/OpenSearchPPLLexer.g4 index 9f707c13cd..5da64adc41 100644 --- a/ppl/src/main/antlr/OpenSearchPPLLexer.g4 +++ b/ppl/src/main/antlr/OpenSearchPPLLexer.g4 @@ -397,5 +397,7 @@ SQUOTA_STRING: '\'' ('\\'. | '\'\'' | ~('\'' | '\\'))* '\'' BQUOTA_STRING: '`' ( '\\'. | '``' | ~('`'|'\\'))* '`'; fragment DEC_DIGIT: [0-9]; +LINE_COMMENT: '//' ('\\\n' | ~[\r\n])* '\r'? '\n'? -> channel(HIDDEN); +BLOCK_COMMENT: '/*' .*? '*/' -> channel(HIDDEN); ERROR_RECOGNITION: . -> channel(ERRORCHANNEL); diff --git a/ppl/src/test/java/org/opensearch/sql/ppl/antlr/PPLSyntaxParserTest.java b/ppl/src/test/java/org/opensearch/sql/ppl/antlr/PPLSyntaxParserTest.java index 943953d416..94c03b4d60 100644 --- a/ppl/src/test/java/org/opensearch/sql/ppl/antlr/PPLSyntaxParserTest.java +++ b/ppl/src/test/java/org/opensearch/sql/ppl/antlr/PPLSyntaxParserTest.java @@ -417,4 +417,43 @@ public void testCanParseTimestampdiffFunction() { new PPLSyntaxParser() .parse("SOURCE=test | eval k = TIMESTAMPDIFF(WEEK,'2003-01-02','2003-01-02')")); } + + @Test + public void testLineCommentShouldPass() { + assertNotNull(new PPLSyntaxParser().parse("search source=t a=1 b=2 //this is a comment")); + assertNotNull(new PPLSyntaxParser().parse("search source=t a=1 b=2 // this is a comment ")); + assertNotNull( + new PPLSyntaxParser() + .parse( + """ + // test is a new line comment \ + search source=t a=1 b=2 // test is a line comment at the end of ppl command \ + | fields a,b // this is line comment inner ppl command\ + ////this is a new line comment + """)); + } + + @Test + public void testBlockCommentShouldPass() { + assertNotNull(new PPLSyntaxParser().parse("search source=t a=1 b=2 /*block comment*/")); + assertNotNull(new PPLSyntaxParser().parse("search source=t a=1 b=2 /* block comment */")); + assertNotNull( + new PPLSyntaxParser() + .parse( + """ + /* + This is a\ + multiple\ + line\ + block\ + comment */\ + search /* block comment */ source=t /* block comment */ a=1 b=2 + |/* + This is a\ + multiple\ + line\ + block\ + comment */ fields a,b /* block comment */ \ + """)); + } }