diff --git a/docs/painless/painless-comments.asciidoc b/docs/painless/painless-comments.asciidoc index d1d2e47a143..588e464d97f 100644 --- a/docs/painless/painless-comments.asciidoc +++ b/docs/painless/painless-comments.asciidoc @@ -1,12 +1,12 @@ [[painless-comments]] === Comments -Painless supports both single-line and multi-line comments. Comments can be -included anywhere within a script. Use the `//` token anywhere on a line to -specify a single-line comment. All characters from the `//` token to the end -of the line are ignored. Use an opening `/*` token and a closing `*/` token -to specify a multi-line comment. Multi-line comments can start anywhere on a -line, and all characters in between the `/*` token and `*/` token are ignored. +Use the `//` token anywhere on a line to specify a single-line comment. All +characters from the `//` token to the end of the line are ignored. Use an +opening `/*` token and a closing `*/` token to specify a multi-line comment. +Multi-line comments can start anywhere on a line, and all characters in between +the `/*` token and `*/` token are ignored. Comments can be included anywhere +within a script. *Grammar* [source,ANTLR4] @@ -17,17 +17,17 @@ MULTI_LINE_COMMENT: '/*' .*? '*/'; *Examples* -Single-line comments. - +* Single-line comments. ++ [source,Painless] ---- // single-line comment int value; // single-line comment ---- - -Multi-line comments. - ++ +* Multi-line comments. ++ [source,Painless] ---- /* multi- diff --git a/docs/painless/painless-identifiers.asciidoc b/docs/painless/painless-identifiers.asciidoc new file mode 100644 index 00000000000..17073e3d4c4 --- /dev/null +++ b/docs/painless/painless-identifiers.asciidoc @@ -0,0 +1,29 @@ +[[painless-identifiers]] +=== Identifiers + +Specify identifiers to <>, <>, and +<> variables, <>, and +<>. <> and +<> cannot be used as identifiers. + +*Grammar* +[source,ANTLR4] +---- +ID: [_a-zA-Z] [_a-zA-Z-0-9]*; +---- + +*Examples* + +* Variations of identifiers. ++ +[source,Painless] +---- +a +Z +id +list +list0 +MAP25 +_map25 +Map_25 +---- diff --git a/docs/painless/painless-keywords.asciidoc b/docs/painless/painless-keywords.asciidoc index 99b5b4060d2..cb3bafbd20f 100644 --- a/docs/painless/painless-keywords.asciidoc +++ b/docs/painless/painless-keywords.asciidoc @@ -2,8 +2,8 @@ === Keywords The keywords in the table below are reserved for built-in language -features. These keywords cannot be used as <> or -<>. +features. These keywords cannot be used as +<> or <>. [cols="^1,^1,^1,^1,^1"] |==== diff --git a/docs/painless/painless-lang-spec.asciidoc b/docs/painless/painless-lang-spec.asciidoc index b324ad30114..ba6595000ae 100644 --- a/docs/painless/painless-lang-spec.asciidoc +++ b/docs/painless/painless-lang-spec.asciidoc @@ -23,6 +23,8 @@ include::painless-keywords.asciidoc[] include::painless-literals.asciidoc[] +include::painless-identifiers.asciidoc[] + include::painless-variables.asciidoc[] include::painless-types.asciidoc[] diff --git a/docs/painless/painless-literals.asciidoc b/docs/painless/painless-literals.asciidoc index 3f91c9299c0..441cb264f1e 100644 --- a/docs/painless/painless-literals.asciidoc +++ b/docs/painless/painless-literals.asciidoc @@ -24,18 +24,18 @@ HEX: '-'? '0' [xX] [0-9a-fA-F]+ [lL]?; *Examples* -Integer literals. - +* Integer literals. ++ [source,Painless] ---- -0 <1> -0D <2> -1234L <3> --90f <4> --022 <5> -0xF2A <6> +<1> 0 +<2> 0D +<3> 1234L +<4> -90f +<5> -022 +<6> 0xF2A ---- - ++ <1> `int 0` <2> `double 0.0` <3> `long 1234` @@ -61,17 +61,17 @@ EXPONENT: ( [eE] [+\-]? [0-9]+ ); *Examples* -Floating point literals. - +* Floating point literals. ++ [source,Painless] ---- -0.0 <1> -1E6 <2> -0.977777 <3> --126.34 <4> -89.9F <5> +<1> 0.0 +<2> 1E6 +<3> 0.977777 +<4> -126.34 +<5> 89.9F ---- - ++ <1> `double 0.0` <2> `double 1000000.0` in exponent notation <3> `double 0.977777` @@ -81,12 +81,11 @@ Floating point literals. [[strings]] ==== Strings -Use string literals to specify string values of the -<> with either single-quotes or double-quotes. -Use a `\"` token to include a double-quote as part of a double-quoted string -literal. Use a `\'` token to include a single-quote as part of a single-quoted -string literal. Use a `\\` token to include a backslash as part of any string -literal. +Use string literals to specify <> values with +either single-quotes or double-quotes. Use a `\"` token to include a +double-quote as part of a double-quoted string literal. Use a `\'` token to +include a single-quote as part of a single-quoted string literal. Use a `\\` +token to include a backslash as part of any string literal. *Grammar* [source,ANTLR4] @@ -97,22 +96,22 @@ STRING: ( '"' ( '\\"' | '\\\\' | ~[\\"] )*? '"' ) *Examples* -String literals using single-quotes. - +* String literals using single-quotes. ++ [source,Painless] ---- 'single-quoted string literal' -'\'single-quoted string with escaped single-quotes\' and backslash \\' -'single-quoted string with non-escaped "double-quotes"' +'\'single-quoted with escaped single-quotes\' and backslash \\' +'single-quoted with non-escaped "double-quotes"' ---- - -String literals using double-quotes. - ++ +* String literals using double-quotes. ++ [source,Painless] ---- "double-quoted string literal" -"\"double-quoted string with escaped double-quotes\" and backslash: \\" -"double-quoted string with non-escaped 'single-quotes'" +"\"double-quoted with escaped double-quotes\" and backslash: \\" +"double-quoted with non-escaped 'single-quotes'" ---- [[characters]] @@ -126,16 +125,16 @@ or an error will occur. *Examples* -Casting string literals into <> values. - +* Casting string literals into <> values. ++ [source,Painless] ---- (char)"C" (char)'c' ---- - -Casting a <> value into a <> value. - ++ +* Casting a <> value into a <> value. ++ [source,Painless] ---- String s = "s"; diff --git a/docs/painless/painless-operators.asciidoc b/docs/painless/painless-operators.asciidoc index 11ee97def66..915d811fa44 100644 --- a/docs/painless/painless-operators.asciidoc +++ b/docs/painless/painless-operators.asciidoc @@ -704,6 +704,7 @@ e = ~d; // sets e the negation of d The cast operator can be used to explicitly convert one type to another. See casting [MARK] for more information. +[[constructor-call]] ==== Constructor Call A constructor call is a special type of method call [MARK] used to allocate a reference type instance using the new operator. The format is the new operator followed by a type, an opening parenthesis, arguments if any, and a closing parenthesis. Arguments are a series of zero-to-many expressions delimited by commas. Auto-boxing and auto-unboxing will be applied automatically for arguments passed into a constructor call. See boxing and unboxing [MARK] for more information on this topic. Constructor argument types can always be resolved at run-time; if appropriate type conversions (casting) cannot be applied an error will occur. Once a reference type instance has been allocated, its members may be used as part of other expressions. diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index 08725b328a3..9756676a08b 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -1,122 +1,130 @@ [[painless-variables]] === Variables -Variables in Painless must be declared and can be -statically or <>. - -[[identifiers]] -==== Identifiers - -Specify variable identifiers using the following grammar. Variable identifiers -must start with a letter or underscore. You cannot use -<> or <> as identifiers. - -*Grammar:* -[source,ANTLR4] ----- -ID: [_a-zA-Z] [_a-zA-Z-0-9]*; ----- - -*Examples:* -[source,Java] ----- -a -Z -id -list -list0 -MAP25 -_map25 ----- +<> variables to <> values for +<> in expressions. Specify variables as a +<>, <>, or +<>. Variable operations follow the structure of a +standard JVM in relation to instruction execution and memory usage. [[declaration]] ==== Declaration -Variables must be declared before you use them. The format is `type-name -identifier-name`. To declare multiple variables of the same type, specify a -comma-separated list of identifier names. You can immediately assign a value to -a variable when you declare it. +Declare variables before use with the format of <> +<>. Specify a comma-separated list of +<> following the <> +to declare multiple variables in a single statement. Use an +<> statement combined with a declaration statement to +immediately assign a value to a variable. Variables not immediately assigned a +value will have a default value assigned implicitly based on the +<>. -*Grammar:* +*Grammar* [source,ANTLR4] ---- +declaration : type ID assignment? (',' ID assignment?)*; type: ID ('[' ']')*; -declaration : type ID (',' ID)*; +assignment: '=' expression; ---- -*Examples:* -[source,Java] ----- -int x; // Declare a variable with type int and id x -List y; // Declare a variable with type List and id y -int x, y, z; // Declare variables with type int and ids x, y, and z -def[] d; // Declare the variable d with type def[] -int i = 10; // Declare the int variable i and set it to the int literal 10 ----- +*Examples* -[[variable-assignment]] +* Different variations of variable declaration. ++ +[source,Painless] +---- +<1> int x; +<2> List y; +<3> int x, y, z; +<4> def[] d; +<5> int i = 10; +---- ++ +<1> declare a variable of type `int` and identifier `x` +<2> declare a variable of type `List` and identifier `y` +<3> declare three variables of type `int` and identifiers `x`, `y`, `z` +<4> declare a variable of type `def[]` and identifier `d` +<5> declare a variable of type `int` and identifier `i`; + assign the integer literal `10` to `i` + +[[assignment]] ==== Assignment -Use the equals operator (`=`) to assign a value to a variable. The format is -`identifier-name = value`. Any value expression can be assigned to any variable -as long as the types match or the expression's type can be implicitly cast to -the variable's type. An error occurs if the types do not match. +Use the `equals` operator (`=`) to assign a value to a variable. Any expression +that produces a value can be assigned to any variable as long as the +<> are the same or the resultant +<> can be implicitly <> to +the variable <>. Otherwise, an error will occur. +<> values are shallow-copied when assigned. -*Grammar:* +*Grammar* [source,ANTLR4] ---- assignment: ID '=' expression ---- +*Examples* -*Examples:* - -Assigning a literal of the appropriate type directly to a declared variable. - -[source,Java] +* Variable assignment with an <>. ++ +[source,Painless] ---- -int i;   // Declare an int i -i = 10;  // Set the int i to the int literal 10 +<1> int i; +<2> i = 10; ---- - -Immediately assigning a value when declaring a variable. - -[source,Java] ++ +<1> declare `int i` +<2> assign `10` to `i` ++ +* <> combined with immediate variable assignment. ++ +[source,Painless] ---- -int i = 10; // Declare the int variable i and set it the int literal 1 -double j = 2.0; // Declare the double variable j and set it to the double - // literal 2.0 +<1> int i = 10; +<2> double j = 2.0; ---- - -Assigning a variable of one primitive type to another variable of the same -type. - -[source,Java] ++ +<1> declare `int i`; assign `10` to `i` +<2> declare `double j`; assign `2.0` to `j` ++ +* Assignment of one variable to another using +<>. ++ +[source,Painless] ---- -int i = 10; // Declare the int variable i and set it to the int literal 10 -int j = i;  // Declare the int variable j and set it to the int variable i +<1> int i = 10; +<2> int j = i; ---- - -Assigning a reference type to a new heap allocation with the `new` operator. - -[source,Java] ++ +<1> declare `int i`; assign `10` to `i` +<2> declare `int j`; assign `j` to `i` ++ +* Assignment with <> using the +<>. ++ +[source,Painless] ---- -ArrayList l = new ArrayList();  // Declare an ArrayList variable l and set it - // to a newly allocated ArrayList -Map m = new HashMap(); // Declare a Map variable m and set it - // to a newly allocated HashMap +<1> ArrayList l = new ArrayList(); +<2> Map m = new HashMap(); ---- - -Assigning a variable of one reference type to another variable of the same type. - -[source,Java] ++ +<1> declare `ArrayList l`; assign a newly-allocated `Arraylist` to `l` +<2> declare `Map m`; assign a newly-allocated `HashMap` to `m` + with an implicit cast to `Map` ++ +* Assignment of one variable to another using +<>. ++ +[source,Painless] ---- -List l = new ArrayList(); // Declare List variable l and set it a newly - // allocated ArrayList -List k = l;  // Declare List variable k and set it to the - // value of the List variable l -List m;                   // Declare List variable m and set it the - // default value null -m = k;                    // Set the value of List variable m to the value - // of List variable k +<1> List l = new ArrayList(); +<2> List k = l; +<3> List m; +<4> m = k; ---- ++ +<1> declare `List l`; assign a newly-allocated `Arraylist` to `l` + with an implicit cast to `List` +<2> declare `List k`; assign a shallow-copy of `l` to `k` +<3> declare `List m`; +<4> assign a shallow-copy of `k` to `m`