From 5ac2ddd2beb859d41266d92cbef63ea524ddc7b9 Mon Sep 17 00:00:00 2001 From: debadair Date: Fri, 12 May 2017 16:17:06 -0700 Subject: [DOCS] Setting up separate Painless book. --- docs/painless/painless-lang-spec.asciidoc | 73 +++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/painless/painless-lang-spec.asciidoc (limited to 'docs/painless/painless-lang-spec.asciidoc') diff --git a/docs/painless/painless-lang-spec.asciidoc b/docs/painless/painless-lang-spec.asciidoc new file mode 100644 index 0000000000..dbad00931a --- /dev/null +++ b/docs/painless/painless-lang-spec.asciidoc @@ -0,0 +1,73 @@ +[[painless-specification]] +== Painless Language Specification + +Painless uses a Java-style syntax that is similar to Groovy. In fact, most +Painless scripts are also valid Groovy, and simple Groovy scripts are typically +valid Painless. This specification assumes you have at least a passing +familiarity with Java and related languages. + +Painless is essentially a subset of Java with some additional scripting +language features that make scripts easier to write. However, there are some +important differences, particularly with the casting model. For more detailed +conceptual information about the basic constructs that Java and Painless share, +refer to the corresponding topics in the +https://docs.oracle.com/javase/specs/jls/se8/html/index.html[Java Language +Specification]. + +Painless scripts are parsed and compiled using the http://www.antlr.org/[ANTLR4] +and http://asm.ow2.org/[ASM] libraries. Painless scripts are compiled directly +into Java byte code and executed against a standard Java Virtual Machine. This +specification uses ANTLR4 grammar notation to describe the allowed syntax. +However, the actual Painless grammar is more compact than what is shown here. + +[float] +[[comments]] +==== Comments + +Painless supports both single-line and multi-line comments. You can include +comments anywhere within a script. + +Single-line comments are preceded by two slashes: `// comment`. They can be +placed anywhere on a line. All characters from the two slashes to the end of +the line are ignored. + +Multi-line comments are preceded by a slash-star `/*` and closed by +star-slash `*/`. Multi-line comments can start anywhere on a line. All +characters from the opening `/*` to the closing `*/` are ignored. + +*Examples:* + +[source,Java] +---- +// single-line comment + + // single-line comment + +/* multi- + line + comment */ + + /* multi-line + comment */ + + /* multi-line comment */ +---- + +[float] +[[keywords]] +==== Keywords + +Painless reserves the following keywords for built-in language features. +These keywords cannot be used used in other contexts, such as identifiers. + +[cols="^1,^1,^1,^1,^1"] +|==== +| if | else | while | do | for +| in | continue | break | return | new +| try | catch | throw | this | instanceof +|==== + +include::painless-literals.asciidoc[] +include::painless-variables.asciidoc[] +include::painless-types.asciidoc[] +include::painless-operators.asciidoc[] -- cgit v1.2.3