Painless: Docs Clean Up (#29592)
As part of the lang spec: separated identifiers into its own section, and cleaned up variables section.
This commit is contained in:
Jack Conradson
GitHub
parent
c02b895653
commit
5a9a1cda53
|
|
@ -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-
|
||||
|
|
|
|||
|
|
@ -0,0 +1,29 @@
|
|||
[[painless-identifiers]]
|
||||
=== Identifiers
|
||||
|
||||
Specify identifiers to <<declaration, declare>>, <<assignment, assign>>, and
|
||||
<<painless-operators, use>> variables, <<dot-operator, access fields>>, and
|
||||
<<dot-operator, call methods>>. <<painless-keywords, Keywords>> and
|
||||
<<painless-types, types>> 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
|
||||
----
|
||||
|
|
@ -2,8 +2,8 @@
|
|||
=== Keywords
|
||||
|
||||
The keywords in the table below are reserved for built-in language
|
||||
features. These keywords cannot be used as <<identifiers, identifiers>> or
|
||||
<<painless-types, types>>.
|
||||
features. These keywords cannot be used as
|
||||
<<painless-identifiers, identifiers>> or <<painless-types, types>>.
|
||||
|
||||
[cols="^1,^1,^1,^1,^1"]
|
||||
|====
|
||||
|
|
|
|||
|
|
@ -23,6 +23,8 @@ include::painless-keywords.asciidoc[]
|
|||
|
||||
include::painless-literals.asciidoc[]
|
||||
|
||||
include::painless-identifiers.asciidoc[]
|
||||
|
||||
include::painless-variables.asciidoc[]
|
||||
|
||||
include::painless-types.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
|
||||
<<string-type, String type>> 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 <<string-type, String>> 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 <<primitive-types, char>> values.
|
||||
|
||||
* Casting string literals into <<primitive-types, char>> values.
|
||||
+
|
||||
[source,Painless]
|
||||
----
|
||||
(char)"C"
|
||||
(char)'c'
|
||||
----
|
||||
|
||||
Casting a <<string-type, String>> value into a <<primitive-types, char>> value.
|
||||
|
||||
+
|
||||
* Casting a <<string-type, String>> value into a <<primitive-types, char>> value.
|
||||
+
|
||||
[source,Painless]
|
||||
----
|
||||
String s = "s";
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -1,122 +1,130 @@
|
|||
[[painless-variables]]
|
||||
=== Variables
|
||||
|
||||
Variables in Painless must be declared and can be
|
||||
statically or <<dynamic-types, dynamically typed>>.
|
||||
|
||||
[[identifiers]]
|
||||
==== Identifiers
|
||||
|
||||
Specify variable identifiers using the following grammar. Variable identifiers
|
||||
must start with a letter or underscore. You cannot use
|
||||
<<painless-keywords, keywords>> or <<painless-types, types>> as identifiers.
|
||||
|
||||
*Grammar:*
|
||||
[source,ANTLR4]
|
||||
----
|
||||
ID: [_a-zA-Z] [_a-zA-Z-0-9]*;
|
||||
----
|
||||
|
||||
*Examples:*
|
||||
[source,Java]
|
||||
----
|
||||
a
|
||||
Z
|
||||
id
|
||||
list
|
||||
list0
|
||||
MAP25
|
||||
_map25
|
||||
----
|
||||
<<declaration, Declare>> variables to <<assignment, assign>> values for
|
||||
<<painless-operators, use>> in expressions. Specify variables as a
|
||||
<<primitive-types, primitive type>>, <<reference-types, reference type>>, or
|
||||
<<dynamic-types, dynamic type>>. 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 <<painless-types, type>>
|
||||
<<painless-identifiers, identifier>>. Specify a comma-separated list of
|
||||
<<painless-identifiers, identifiers>> following the <<painless-types, type>>
|
||||
to declare multiple variables in a single statement. Use an
|
||||
<<assignment, assignment>> 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
|
||||
<<painless-types, type>>.
|
||||
|
||||
*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
|
||||
<<painless-types, types>> are the same or the resultant
|
||||
<<painless-types, type>> can be implicitly <<painless-casting, cast>> to
|
||||
the variable <<painless-types, type>>. Otherwise, an error will occur.
|
||||
<<reference-types, Reference type>> 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 <<integers, integer literal>>.
|
||||
+
|
||||
[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`
|
||||
+
|
||||
* <<declaration, Declaration>> 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
|
||||
<<primitive-types, primitive types>>.
|
||||
+
|
||||
[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 <<reference-types, reference types>> using the
|
||||
<<constructor-call, new operator>>.
|
||||
+
|
||||
[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
|
||||
<<reference-types, reference types>>.
|
||||
+
|
||||
[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`
|
||||
|
|
|
|||
Loading…
Reference in New Issue