From 153d37694a4938b2f9e6c4f7015a43913ce84c8a Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Tue, 17 Apr 2018 16:45:49 -0700 Subject: [PATCH 1/4] Separate identifiers into its own section. Clean up variables. --- docs/painless/painless-identifiers.asciidoc | 29 ++++ docs/painless/painless-keywords.asciidoc | 4 +- docs/painless/painless-lang-spec.asciidoc | 2 + docs/painless/painless-literals.asciidoc | 22 +-- docs/painless/painless-operators.asciidoc | 1 + docs/painless/painless-variables.asciidoc | 170 +++++++++++--------- 6 files changed, 136 insertions(+), 92 deletions(-) create mode 100644 docs/painless/painless-identifiers.asciidoc diff --git a/docs/painless/painless-identifiers.asciidoc b/docs/painless/painless-identifiers.asciidoc new file mode 100644 index 0000000000000..4b61b4f3d62ee --- /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 99b5b4060d24e..cb3bafbd20f13 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 b324ad301141c..ba6595000ae2f 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 3f91c9299c0ad..191f3adb0c923 100644 --- a/docs/painless/painless-literals.asciidoc +++ b/docs/painless/painless-literals.asciidoc @@ -28,12 +28,12 @@ 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` @@ -65,11 +65,11 @@ 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` diff --git a/docs/painless/painless-operators.asciidoc b/docs/painless/painless-operators.asciidoc index 11ee97def66ba..915d811fa441b 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 08725b328a3c2..b63558f9a25ec 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -1,122 +1,134 @@ [[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 +<> type. [[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 +<> 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] +*Examples* + +Different variations of variable declaration. + +[source,Painless] ---- -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 +<1> int x; +<2> List y; +<3> int x, y, z; +<4> def[] d; +<5> int i = 10; ---- -[[variable-assignment]] -==== Assignment +<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` -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. +[[assignment]] +==== Assignment -*Grammar:* +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. + +Assignment of <> will cause the value to be +copied. Assignment of <> will cause the +value to be referred to with the exception of the <> +which is copied. Assignment of <> will +cause the value to be copied or referred to based on what the +<> represents. All types of assignment follow +the standard Java memory model. + +*Grammar* [source,ANTLR4] ---- assignment: ID '=' expression ---- +*Examples* -*Examples:* +Variable assignment with an <>. -Assigning a literal of the appropriate type directly to a declared variable. - -[source,Java] +[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. +<1> declare `int i` +<2> assign a copy of `10` to `i` + +<> combined with immediate variable assignment. -[source,Java] +[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. +<1> declare `int i`; assign a copy of `10` to `i` +<2> declare `double j`; assign a copy of `2.0` to `j` -[source,Java] +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. +<1> declare `int i`; assign a copy of `10` to `i` +<2> declare `int j`; assign a copy of `j` to `i` + +Assignment with reference types using the <>. -[source,Java] +[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. +<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 downcast -[source,Java] +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 downcast +<2> declare `List k`; assign a reference of `l` to `k` +<3> declare `List m`; +<4> assign a reference of `k` to `m` From 6729d5f821361bcccc3d9909cc7417159bb3cf23 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 18 Apr 2018 08:57:02 -0700 Subject: [PATCH 2/4] More docs. --- docs/painless/painless-comments.asciidoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/painless/painless-comments.asciidoc b/docs/painless/painless-comments.asciidoc index d1d2e47a143a6..04fec002a746f 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] From c2c34484efd9c811e1c0ff0a9aec7cc23378286d Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 18 Apr 2018 17:10:00 -0700 Subject: [PATCH 3/4] Modify language used to describe shallow copies. --- docs/painless/painless-variables.asciidoc | 41 ++++++++++------------- 1 file changed, 18 insertions(+), 23 deletions(-) diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-variables.asciidoc index b63558f9a25ec..bf3c5437638d6 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -3,8 +3,9 @@ <> variables to <> values for <> in expressions. Specify variables as a -<>, <>, or -<> type. +<>, <>, or +<>. Variable operations follow the structure of a +standard JVM in relation to instruction execution and memory usage. [[declaration]] ==== Declaration @@ -12,10 +13,11 @@ 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 -<> 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 <>. +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* [source,ANTLR4] @@ -53,14 +55,7 @@ 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. - -Assignment of <> will cause the value to be -copied. Assignment of <> will cause the -value to be referred to with the exception of the <> -which is copied. Assignment of <> will -cause the value to be copied or referred to based on what the -<> represents. All types of assignment follow -the standard Java memory model. +<> values are shallow-copied when assigned. *Grammar* [source,ANTLR4] @@ -79,7 +74,7 @@ Variable assignment with an <>. ---- <1> declare `int i` -<2> assign a copy of `10` to `i` +<2> assign `10` to `i` <> combined with immediate variable assignment. @@ -89,8 +84,8 @@ Variable assignment with an <>. <2> double j = 2.0; ---- -<1> declare `int i`; assign a copy of `10` to `i` -<2> declare `double j`; assign a copy of `2.0` to `j` +<1> declare `int i`; assign `10` to `i` +<2> declare `double j`; assign `2.0` to `j` Assignment of one variable to another using <>. @@ -101,8 +96,8 @@ Assignment of one variable to another using <2> int j = i; ---- -<1> declare `int i`; assign a copy of `10` to `i` -<2> declare `int j`; assign a copy of `j` to `i` +<1> declare `int i`; assign `10` to `i` +<2> declare `int j`; assign `j` to `i` Assignment with reference types using the <>. @@ -114,7 +109,7 @@ Assignment with reference types using the <>. <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 downcast + with an implicit cast to `Map` Assignment of one variable to another using <>. @@ -128,7 +123,7 @@ Assignment of one variable to another using ---- <1> declare `List l`; assign a newly-allocated `Arraylist` to `l` - with an implicit downcast -<2> declare `List k`; assign a reference of `l` to `k` + 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 reference of `k` to `m` +<4> assign a shallow-copy of `k` to `m` From 1cdf013388f127bf8ed13ed1f891f96377a31cc6 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 18 Apr 2018 18:05:37 -0700 Subject: [PATCH 4/4] Move examples into lists to make sections flow better when multiple examples are used. --- docs/painless/painless-comments.asciidoc | 10 ++-- docs/painless/painless-identifiers.asciidoc | 4 +- docs/painless/painless-literals.asciidoc | 51 ++++++++++----------- docs/painless/painless-variables.asciidoc | 45 +++++++++--------- 4 files changed, 55 insertions(+), 55 deletions(-) diff --git a/docs/painless/painless-comments.asciidoc b/docs/painless/painless-comments.asciidoc index 04fec002a746f..588e464d97f78 100644 --- a/docs/painless/painless-comments.asciidoc +++ b/docs/painless/painless-comments.asciidoc @@ -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 index 4b61b4f3d62ee..17073e3d4c415 100644 --- a/docs/painless/painless-identifiers.asciidoc +++ b/docs/painless/painless-identifiers.asciidoc @@ -14,8 +14,8 @@ ID: [_a-zA-Z] [_a-zA-Z-0-9]*; *Examples* -Variations of identifiers. - +* Variations of identifiers. ++ [source,Painless] ---- a diff --git a/docs/painless/painless-literals.asciidoc b/docs/painless/painless-literals.asciidoc index 191f3adb0c923..441cb264f1e15 100644 --- a/docs/painless/painless-literals.asciidoc +++ b/docs/painless/painless-literals.asciidoc @@ -24,8 +24,8 @@ HEX: '-'? '0' [xX] [0-9a-fA-F]+ [lL]?; *Examples* -Integer literals. - +* Integer literals. ++ [source,Painless] ---- <1> 0 @@ -35,7 +35,7 @@ Integer literals. <5> -022 <6> 0xF2A ---- - ++ <1> `int 0` <2> `double 0.0` <3> `long 1234` @@ -61,8 +61,8 @@ EXPONENT: ( [eE] [+\-]? [0-9]+ ); *Examples* -Floating point literals. - +* Floating point literals. ++ [source,Painless] ---- <1> 0.0 @@ -71,7 +71,7 @@ Floating point literals. <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-variables.asciidoc b/docs/painless/painless-variables.asciidoc index bf3c5437638d6..9756676a08b5b 100644 --- a/docs/painless/painless-variables.asciidoc +++ b/docs/painless/painless-variables.asciidoc @@ -29,8 +29,8 @@ assignment: '=' expression; *Examples* -Different variations of variable declaration. - +* Different variations of variable declaration. ++ [source,Painless] ---- <1> int x; @@ -39,7 +39,7 @@ Different variations of variable declaration. <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` @@ -65,55 +65,56 @@ assignment: ID '=' expression *Examples* -Variable assignment with an <>. - +* Variable assignment with an <>. ++ [source,Painless] ---- <1> int i; <2> i = 10; ---- - ++ <1> declare `int i` <2> assign `10` to `i` - -<> combined with immediate variable assignment. - ++ +* <> combined with immediate variable assignment. ++ [source,Painless] ---- <1> int i = 10; <2> double j = 2.0; ---- - ++ <1> declare `int i`; assign `10` to `i` <2> declare `double j`; assign `2.0` to `j` - -Assignment of one variable to another using ++ +* Assignment of one variable to another using <>. - ++ [source,Painless] ---- <1> int i = 10; <2> int j = i; ---- - ++ <1> declare `int i`; assign `10` to `i` <2> declare `int j`; assign `j` to `i` - -Assignment with reference types using the <>. - ++ +* Assignment with <> using the +<>. ++ [source,Painless] ---- <1> ArrayList l = new ArrayList(); <2> Map m = new HashMap(); ---- - ++ <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 ++ +* Assignment of one variable to another using <>. - ++ [source,Painless] ---- <1> List l = new ArrayList(); @@ -121,7 +122,7 @@ Assignment of one variable to another using <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`