honeymoose/OpenSearch
1
0
Fork 0
mirror of https://github.com/honeymoose/OpenSearch.git synced 2025-02-17 02:14:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Painless: Docs Clean Up (#29592)

Browse Source 
As part of the lang spec: separated identifiers into its own section, and cleaned up variables section.
This commit is contained in:
Jack Conradson 2018-04-25 09:38:41 -07:00 committed by GitHub
parent c02b895653
commit 5a9a1cda53
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 178 additions and 139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/painless/painless-comments.asciidoc
View File

@ -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-

29
docs/painless/painless-identifiers.asciidoc Normal file
View File

@ -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
----

4
docs/painless/painless-keywords.asciidoc
View File

@ -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"]
|====

2
docs/painless/painless-lang-spec.asciidoc
View File

@ -23,6 +23,8 @@ include::painless-keywords.asciidoc[]
include::painless-literals.asciidoc[]
include::painless-identifiers.asciidoc[]
include::painless-variables.asciidoc[]
include::painless-types.asciidoc[]

73
docs/painless/painless-literals.asciidoc
View File

@ -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";

1
docs/painless/painless-operators.asciidoc
View File

@ -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.

186
docs/painless/painless-variables.asciidoc
View File

@ -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`