Painless Spec Documentation Clean Up

docs/painless/index.asciidoc

@@ -5,39 +5,8 @@ include::../Versions.asciidoc[]
 
 include::painless-getting-started.asciidoc[]
 
-// include::painless-examples.asciidoc[]
-
-// include::painless-design.asciidoc[]
-
 include::painless-lang-spec.asciidoc[]
 
-include::painless-syntax.asciidoc[]
+include::painless-general-syntax.asciidoc[]
 
 include::painless-api-reference.asciidoc[]
-
-////
-Proposed Outline (WIP)
-Getting Started with Painless
-  Accessing Doc Values
-  Updating Fields
-  Working with Dates
-  Using Regular Expressions
-  Debugging Painless Scripts
-
-Example Scripts
-  Using Painless in Script Fields
-  Using Painless in Watches
-  Using Painless in Function Score Queries
-  Using Painless in Script Queries
-  Using Painless When Updating Docs
-  Using Painless When Reindexing
-
-How Painless Works
-  Painless Architecture
-  Dispatching Functions
-
-Painless Language Specification
-Painless API
-////
-
-Painless API Reference

docs/painless/painless-api-reference.asciidoc

@@ -1,17 +1,14 @@
-["appendix",id="painless-api-reference"]
+[appendix]
+[[painless-api-reference]]
 = Painless API Reference
 
-Painless has a strict whitelist for methods and
-classes to make sure that all painless scripts are secure and fast. Most of
-these methods are exposed directly from the JRE while others are part of
-Elasticsearch or Painless itself. Below is a list of all available methods
-grouped under the classes on which you can call them. Clicking on the method
-name takes you to the documentation for the method.
-
-NOTE: Methods defined in the JRE also have a `(java 9)` link which can be used
-to see the method's documentation in Java 9 while clicking on the method's name
-goes to the Java 8 documentation. Usually these aren't different but it is
-worth going to the version that matches the version of Java you are using to
-run Elasticsearch just in case.
+Painless has a strict whitelist for methods and classes to ensure all
+painless scripts are secure. Most of these methods are exposed directly
+from the Java Runtime Enviroment (JRE) while others are part of
+Elasticsearch or Painless itself. Below is a list of all available
+classes grouped with their respected methods. Clicking on the method
+name takes you to the documentation for that specific method.  Methods
+defined in the JRE also have a `(java 9)` link which can be used to see
+the method's documentation in Java 9.
 
 include::painless-api-reference/index.asciidoc[]

docs/painless/painless-basic-syntax.asciidoc

@@ -0,0 +1,304 @@
+[[painless-basic-syntax]]
+=== Basic Syntax
+
+[[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.
+
+*Grammar:*
+[source,ANTLR4]
+----
+SINGLE_LINE_COMMENT: '//' .*? [\n\r];
+MULTI_LINE_COMMENT: '/*' .*? '*/';
+----
+
+*Examples:*
+
+Single-line and multi-line comments where `<code>` represents tokens within a
+script.
+
+[source,Java]
+----
+// single-line comment
+
+<code> // single-line comment
+
+/* multi-
+   line
+   comment */
+
+<code> /* multi-line
+          comment */ <code>
+
+<code> /* multi-line comment */ <code>
+----
+
+[[keywords]]
+==== Keywords
+
+The keywords in the table below are reserved for built-in language
+features. These keywords cannot be used as identifiers or types.
+
+[cols="^1,^1,^1,^1,^1"]
+|====
+| if | else | while | do | for
+| in | continue | break | return | new
+| try | catch | throw | this | instanceof
+|====
+
+[[literals]]
+==== Literals
+
+Use literals to specify different types of values directly in a script.
+
+[[integers]]
+===== Integers
+
+Use integer literals to specify an integer value in decimal, octal, or hex
+notation of the <<primitive-types, primitive types>> int, long, float, or
+double. Use the following single letter designations to specify the
+<<primitive-types, primitive type>>: `l` or `L` for `long`, `f` or `F` for
+`float`, and `d` or `D` for `double`. If not specified, the type defaults to
+`int`.  Use `0` as a prefix 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]?;
+OCTAL:   '-'? '0' [0-7]+ [lL]?;
+HEX:     '-'? '0' [xX] [0-9a-fA-F]+ [lL]?;
+----
+
+*Examples:*
+
+Integer literals of `int 0`, `double 0.0`, `long 1234`,
+`float -90.0`, `int -18` in octal, and `int 3882` in hex.
+
+[source,Java]
+----
+0
+0D
+1234L
+-90f
+-022
+0xF2A
+----
+
+[[floats]]
+===== Floats
+
+Use floating point literals to specify a floating point value of the
+<<primitive-types, primitive types>> float or double. Use the following single
+letter designations for the <<primitive-types, primitive type>>: `f` for
+`float` and `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]?;
+EXPONENT: ( [eE] [+\-]? [0-9]+ );
+----
+
+*Examples:*
+
+Floating point literals of `double 0.0`, `double 1000000.0` in
+exponent notation, `double 0.977777`, `double -126.34`, and `float 89.9`.
+
+[source,Java]
+----
+0.0
+1E6
+0.977777
+-126.34
+89.9F
+----
+
+[[strings]]
+===== Strings
+
+Use string literals to specify string values of the
+<<string-type, String type>> with either single 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]
+----
+STRING: ( '"'  ( '\\"'  | '\\\\' | ~[\\"] )*? '"'  )
+      | ( '\'' ( '\\\'' | '\\\\' | ~[\\'] )*? '\'' );
+----
+
+*Examples:*
+
+String literals using both single-quotes and double-quotes.
+
+[source,Java]
+----
+"double-quoted String literal"
+'single-quoted String literal'
+"\"double-quoted String with escaped double-quotes\" and backslash: \\"
+'\'single-quoted String with escaped single-quotes\' and backslash \\'
+"double-quoted String with non-escaped 'single-quotes'"
+'single-quoted String with non-escaped "double-quotes"'
+----
+
+[[characters]]
+===== Characters
+
+Use the <<casting, casting operator>> to convert string literals or
+<<string-type, String type>> values into <<primitive-types, char type>> values.
+<<string-type, String type>> values converted into
+<<primitive-types, char type>> values must be exactly one character in length
+or an error will occur.
+
+*Examples:*
+
+Casting string literals into <<primitive-types, char type>> values.
+
+[source,Java]
+----
+(char)"C"
+(char)'c'
+----
+
+Casting a <<string-type, String type>> value into a
+<<primitive-types, char type>> value.
+
+[source,Java]
+----
+String s = "s";
+char c = (char)s;
+----
+
+[[variables]]
+==== Variables
+
+Variables in Painless must be declared and can be statically or <<dynamic-types,
+dynamically typed>>.
+
+[[variable-identifiers]]
+===== Variable Identifiers
+
+Specify variable identifiers using the following grammar. Variable identifiers
+must start with a letter or underscore. You cannot use <<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
+----
+
+[[variable-declaration]]
+===== Variable 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.
+
+*Grammar:*
+[source,ANTLR4]
+----
+type: ID ('[' ']')*;
+declaration : type ID (',' ID)*;
+----
+
+*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
+----
+
+[[variable-assignment]]
+===== Variable 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.
+
+*Grammar:*
+[source,ANTLR4]
+----
+assignment: ID '=' expression
+----
+
+
+*Examples:*
+
+Assigning a literal of the appropriate type directly to a declared variable.
+
+[source,Java]
+----
+int i;   // Declare an int i
+i = 10;  // Set the int i to the int literal 10
+----
+
+Immediately assigning a value when declaring a variable.
+
+[source,Java]
+----
+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
+----
+
+Assigning a variable of one primitive type to another variable of the same
+type.
+
+[source,Java]
+----
+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
+----
+
+Assigning a reference type to a new heap allocation with the `new` operator.
+
+[source,Java]
+----
+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
+----
+
+Assigning a variable of one reference type to another variable of the same type.
+
+[source,Java]
+----
+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
+----

docs/painless/painless-description.asciidoc

@@ -2,7 +2,7 @@ _Painless_ is a simple, secure scripting language designed specifically for use
 with Elasticsearch. It is the default scripting language for Elasticsearch and
 can safely be used for inline and stored scripts. For a detailed description of
 the Painless syntax and language features, see the
-{painless}/painless-specification.html[Painless Language Specification].
+{painless}/painless-lang-spec.html[Painless Language Specification].
 
 [[painless-features]]
 You can use Painless anywhere scripts can be used in Elasticsearch. Painless

docs/painless/painless-syntax.asciidoc → docs/painless/painless-general-syntax.asciidoc

@@ -1,5 +1,5 @@
-[[painless-syntax]]
-=== Painless Syntax
+[[painless-general-syntax]]
+=== General Syntax
 
 [float]
 [[control-flow]]