Painless: Restructure/Clean Up of Spec Documentation (#31013)

Full restructure of the spec into new sections for operators,
statements, scripts, functions, lambdas, and regexes.  Split
of operators into 6 sections, a table, reference, array,
numeric, boolean, and general.  Clean up of all operators
sections.  Sporadic clean up else where.

Author: jdconrad

docs/painless/painless-casting.asciidoc

@@ -6,9 +6,10 @@ 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.
+token are ignored. A comment is included anywhere within a script.
 
 *Grammar*
+
 [source,ANTLR4]
 ----
 SINGLE_LINE_COMMENT: '//' .*? [\n\r];

docs/painless/painless-comments.asciidoc

@@ -0,0 +1,24 @@
+[[painless-functions]]
+=== Functions
+
+A function is a named piece of code comprised of one-to-many statements to
+perform a specific task. A function is called multiple times in a single script
+to repeat its specific task. A parameter is a named type value available as a
+<<painless-variables, variable>> within the statement(s) of a function. A
+function specifies zero-to-many parameters, and when a function is called a
+value is specified per parameter. An argument is a value passed into a function
+at the point of call. A function specifies a return type value, though if the
+type is <<void-type, void>> then no value is returned.  Any non-void type return
+value is available for use within an <<painless-operators, operation>> or is
+discarded otherwise.
+
+You can declare functions at the beginning of a Painless script, for example:
+
+[source,painless]
+---------------------------------------------------------
+boolean isNegative(def x) { x < 0 }
+...
+if (isNegative(someVar)) {
+  ...
+}
+---------------------------------------------------------

docs/painless/painless-functions.asciidoc

@@ -3,8 +3,12 @@
 
 Use an identifier as a named token to specify a
 <<painless-variables, variable>>, <<painless-types, type>>,
-<<dot-operator, field>>, <<dot-operator, method>>, or function.
-<<painless-keywords, Keywords>> cannot be used as identifiers.
+<<field-access-operator, field>>, <<method-call-operator, method>>, or
+<<painless-functions, function>>.
+
+*Errors*
+
+If a <<painless-keywords, keyword>> is used as an identifier.
 
 *Grammar*
 [source,ANTLR4]

docs/painless/painless-general-syntax.asciidoc

@@ -1,9 +1,13 @@
 [[painless-keywords]]
 === Keywords
 
-Keywords are reserved tokens for built-in language features and cannot be used
-as <<painless-identifiers, identifiers>> within a script. The following are
-keywords:
+Keywords are reserved tokens for built-in language features.
+
+*Errors*
+
+If a keyword is used as an <<painless-identifiers, identifier>>.
+
+*Keywords*
 
 [cols="^1,^1,^1,^1,^1"]
 |====

docs/painless/painless-identifiers.asciidoc

@@ -0,0 +1,15 @@
+[[painless-lambdas]]
+=== Lambdas
+Lambda expressions and method references work the same as in https://docs.oracle.com/javase/tutorial/java/javaOO/lambdaexpressions.html[Java].
+
+[source,painless]
+---------------------------------------------------------
+list.removeIf(item -> item == 2);
+list.removeIf((int item) -> item == 2);
+list.removeIf((int item) -> { item == 2 });
+list.sort((x, y) -> x - y);
+list.sort(Integer::compare);
+---------------------------------------------------------
+
+You can make method references to functions within the script with `this`,
+for example `list.sort(this::mycompare)`.

docs/painless/painless-keywords.asciidoc

@@ -33,4 +33,22 @@ include::painless-casting.asciidoc[]
 
 include::painless-operators.asciidoc[]
 
-include::painless-general-syntax.asciidoc[]
+include::painless-operators-general.asciidoc[]
+
+include::painless-operators-numeric.asciidoc[]
+
+include::painless-operators-boolean.asciidoc[]
+
+include::painless-operators-reference.asciidoc[]
+
+include::painless-operators-array.asciidoc[]
+
+include::painless-statements.asciidoc[]
+
+include::painless-scripts.asciidoc[]
+
+include::painless-functions.asciidoc[]
+
+include::painless-lambdas.asciidoc[]
+
+include::painless-regexes.asciidoc[]

docs/painless/painless-lambdas.asciidoc

@@ -4,7 +4,7 @@
 Use a literal to specify a value directly in an
 <<painless-operators, operation>>.
 
-[[integers]]
+[[integer-literals]]
 ==== Integers
 
 Use an integer literal to specify an integer type value in decimal, octal, or
@@ -16,6 +16,7 @@ to specify an integer literal as octal, and use `0x` or `0X` as a prefix to
 specify an integer literal as hex.
 
 *Grammar*
+
 [source,ANTLR4]
 ----
 INTEGER: '-'? ( '0' | [1-9] [0-9]* ) [lLfFdD]?;
@@ -44,7 +45,7 @@ HEX:     '-'? '0' [xX] [0-9a-fA-F]+ [lL]?;
 <5> `int -18` in octal
 <6> `int 3882` in hex
 
-[[floats]]
+[[float-literals]]
 ==== Floats
 
 Use a floating point literal to specify a floating point type value of a
@@ -53,6 +54,7 @@ single letter designations to specify the primitive type: `f` or `F` for `float`
 and `d` or `D` for `double`. If not specified, the type defaults to `double`.
 
 *Grammar*
+
 [source,ANTLR4]
 ----
 DECIMAL: '-'? ( '0' | [1-9] [0-9]* ) (DOT [0-9]+)? EXPONENT? [fFdD]?;
@@ -78,7 +80,7 @@ EXPONENT: ( [eE] [+\-]? [0-9]+ );
 <4> `double -126.34`
 <5> `float 89.9`
 
-[[strings]]
+[[string-literals]]
 ==== Strings
 
 Use a string literal to specify a <<string-type, `String` type>> value with
@@ -88,6 +90,7 @@ 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]
 ----
 STRING: ( '"'  ( '\\"'  | '\\\\' | ~[\\"] )*? '"'  )
@@ -114,9 +117,9 @@ STRING: ( '"'  ( '\\"'  | '\\\\' | ~[\\"] )*? '"'  )
 "double-quoted with non-escaped 'single-quotes'"
 ----
 
-[[characters]]
+[[character-literals]]
 ==== Characters
 
-A character literal cannot be specified directly. Instead, use the
+Character literals are not specified directly. Instead, use the
 <<string-character-casting, cast operator>> to convert a `String` type value
 into a `char` type value.