Painless: Restructure Spec Documentation #31013

jdconrad · 2018-05-31T21:11:31Z

This splits general-syntax into the remaining spec sections statements, scripts, functions, lambdas, and regexes.

This also splits the operators into different sections in the Painless spec to reduce the size of the original operators page from enormous to manageable. Also includes clean up of the general operators section. Subsequent operators sections will be cleaned up in different PRs.

Note this PR looks huge, but it's actually not. Most of the lines are the split of operators into different pages.

examples are used.

debadair

Left some comments--where applicable, the changes can be carried forward to the other sections, I didn't repeat them in each case.

debadair · 2018-06-04T22:15:41Z

docs/painless/painless-casting.asciidoc

+
+The following tables list all allowed casts read as row (original type) to
+column (target type) with implicit as `I`, explicit as `E`, and not allowed as
+`-`:


I'd probably split this up. "The following tables show all allowed casts. Read the tables row by row, where the original type is shown in the first column, and each subsequent column indicates whether a cast to the specified type can be implicit (I), explicit (E), or is not allowed (-)."

debadair · 2018-06-04T22:18:00Z

docs/painless/painless-literals.asciidoc

@@ -44,7 +44,7 @@ HEX:     '-'? '0' [xX] [0-9a-fA-F]+ [lL]?;
 <5> `int -18` in octal
 <6> `int 3882` in hex

-[[floats]]
+[[float-literals]]
 ==== Floats


Beware that changing the anchors affects any cross-refs to these sections.

Thanks for the head up. I've been pretty good about compiling the docs and looking at the format each time I change something significant.

Note that I'm fairly confident nothing is referring to the headers outside the book since I've added the majority of them recently.

debadair · 2018-06-04T22:54:04Z

docs/painless/painless-operators-array.asciidoc

+initialize each dimension with are specified as a comma-separated list enclosed
+in braces. For example, `new int[] {1, 2, 3}` creates a one dimensional `int`
+array with a size of 3 and the values 1, 2, and 3.
+


This and the following two paragraphs feel redundant/repetitious. I'd be inclined to remove the second two sentences from the first paragraph.

debadair · 2018-06-04T23:08:45Z

docs/painless/painless-operators-boolean.asciidoc

+==== Boolean Not
+
+Boolean not will flip a boolean value from true to false or false to true using the bang operator.  The format is a bang operator followed by an expression.
+


I think I'd put not in code font or all caps to make it a bit easier to read correctly. I'd probably say: Boolean not flips a boolean value between true and false and is represented by the ! (bang) operator. The format is the bang operator followed by an expression.

Used caps, tried to do this consistently for all operators that it made sense for.

debadair · 2018-06-04T23:13:57Z

docs/painless/painless-operators-boolean.asciidoc

+----
+
+Note that def types will be assumed to be of the boolean type.  Any def type evaluated at run-time that does not represent a boolean will result in an error.  Non-boolean expressions will result in an error.
+


Generally avoid future tense. Also, runtime doesn't need to be hyphenated. I'd say "Note that def types are assumed to be of type boolean. Any def type evaluated at runtime that does not represent a boolean results in an error."

The last sentence is not clear--is that, "Preceding a non-boolean expression with the bang operator results in an error."?

debadair · 2018-06-04T23:16:37Z

docs/painless/painless-operators-boolean.asciidoc

+----
+
+A numeric promotion may occur during a less than operation.  A def type evaluated at run-time will follow the same promotion table at run-time following whatever type def represents. Non-numeric expressions will result in an error.
+


Same as previous.

debadair · 2018-06-04T23:25:35Z

docs/painless/painless-operators-boolean.asciidoc

+==== Boolean And
+
+Boolean and will and together two boolean expressions.  If the first expression is found to be false then it is known that the result will also be false, so evaluation of the second expression will be skipped.  The table below shows what the resultant boolean value will be based on the two boolean expressions.
+


I'd probably go with, "Boolean and ANDs two boolean expressions." Is it worth adding, "and evaluates to true if both expressions are true"?

(Also corresponding changes for the following sections.)

Changed, used caps.

debadair · 2018-06-04T23:37:04Z

docs/painless/painless-operators-general.asciidoc

+==== Precedence
+
+An expression encapsulated within a *precedence operator* overrides
+existing precedence relationships between operators and is evaluated


Need to call out the use of parens. The use of "precedence operator" seems a bit awkward in this case--and doesn't need to be highlighted, especially on the second occurrence. I might be inclined to go with something like, "An expression encapsulated by the precedence operator (enclosed in parentheses)..."

Cleaned up. I removed the format sentence from each operator given the grammar and examples. Is this something I should add back in for each operator?

Also removed the bolding of the operators from all of the general section.

debadair · 2018-06-04T23:44:44Z

docs/painless/painless-operators-numeric.asciidoc

+==== Post Increment
+
+A variable/field representing a numerical value can be possibly evaluated as part of an expression, and then increased by 1 for its respective type.  The format starts with a variable name followed by a plus and ends with a plus.
+


Should follow the same format used for the other operators--something like, "use the post increment operator (++) to increase the value of a variable by one after it has been evaluated. The format is the variable name followed by ++.

debadair · 2018-06-04T23:44:59Z

docs/painless/painless-operators-numeric.asciidoc

+==== Pre Increment
+
+A variable/field representing a numerical value can be increased by 1 for its respective type, and then possibly evaluated as part of an expression.  The format starts with a plus followed by a plus and ends with a variable name.
+


See prev comment.

jdconrad · 2018-06-05T22:50:27Z

@debadair Thank you so much for the first pass!

As we discussed, I've merged ALL changes to the operators section into this PR. I apologize profusely that it's so huge, I realize the most that can be done as a second pass is a broad overview and will need editing again when you have more time, but I think it makes sense to get these changes in as I consider them an large improvement over the existing docs.

I did my best to apply comments from the previous pass as appropriate to the different operators, so hopefully it's better moving forward.

Note - I also merged in more structural changes as I figured I may as well try to lay out the structure for the spec all at once so you don't have to request so many hyperlinks in upcoming new documentation.

The sections are the following:

painless-lang-spec.asciidoc
** painless-comments.asciidoc
**painless-keywords.asciidoc
**painless-literals.asciidoc
**painless-identifiers.asciidoc
**painless-variables.asciidoc
**painless-types.asciidoc
**painless-casting.asciidoc
**painless-operators.asciidoc
**painless-operators-general.asciidoc
**painless-operators-numeric.asciidoc
**painless-operators-boolean.asciidoc
**painless-operators-reference.asciidoc
**painless-operators-array.asciidoc
**painless-statements.asciidoc
**painless-scripts.asciidoc
**painless-functions.asciidoc
**painless-lambdas.asciidoc
**painless-regexes.asciidoc

debadair

A few more very minor comments. This is definitely feeling like a big improvement--nice work! Totally agree with getting this merged!

debadair · 2018-06-07T18:41:59Z

docs/painless/painless-casting.asciidoc

@@ -343,12 +347,12 @@ reference type to its corresponding primitive type.

 Implicit boxing/unboxing occurs during the following operations:

-* Conversions between a `def` type and a primitive type will be implicitly
+* Conversions between a `def` type and a primitive type is implicitly
  boxed/unboxed as necessary, though this is referred to as an implicit cast


debadair · 2018-06-07T18:44:30Z

docs/painless/painless-literals.asciidoc

 ==== Characters

-A character literal cannot be specified directly. Instead, use the
+A character literal is not specified directly. Instead, use the
 <<string-character-casting, cast operator>> to convert a `String` type value


I would change this to "Character literals are not..." It just reads strange to me in the singular. :-)

Agreed and changed.

debadair · 2018-06-07T18:52:43Z

docs/painless/painless-scripts.asciidoc

+
+Scripts are composed of one-to-many <<painless-statements, statements>> and are
+run in a sandbox that determines what local variables are immediately available
+along with what API's are whitelisted for use.


No apostrophe necessary in APIs

jdconrad · 2018-06-07T21:10:53Z

@debadair Thanks again for the feedback! Made the changes as requested.

jdconrad · 2018-06-07T21:15:50Z

@debadair Thank you so much! Will commit this as soon as the build passes. I will try to keep the next rounds much, much smaller.

jdconrad · 2018-06-07T21:16:18Z

@elasticmachine Please test this.

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.

* elastic/master: (53 commits) Painless: Restructure/Clean Up of Spec Documentation (#31013) Update ignore_unmapped serialization after backport Add back dropped substitution on merge high level REST api: cancel task (#30745) Enable engine factory to be pluggable (#31183) Remove vestiges of animal sniffer (#31178) Rename elasticsearch-nio to nio (#31186) Rename elasticsearch-core to core (#31185) Move cli sub-project out of server to libs (#31184) [DOCS] Fixes broken link in auditing settings QA: Better seed nodes for rolling restart [DOCS] Moves ML content to stack-docs [DOCS] Clarifies recommendation for audit index output type (#31146) Add nio-transport as option for http smoke tests (#31162) QA: Set better node names on rolling restart tests Add support for ignore_unmapped to geo sort (#31153) Share common parser in some AcknowledgedResponses (#31169) Fix random failure on SearchQueryIT#testTermExpansionExceptionOnSpanFailure Remove reference to multiple fields with one name (#31127) Remove BlobContainer.move() method (#31100) ...

* elastic/6.x: (50 commits) Painless: Restructure/Clean Up of Spec Documentation (#31013) Add support for ignore_unmapped to geo sort (#31153) Enable engine factory to be pluggable (#31183) Remove vestiges of animal sniffer (#31178) Rename elasticsearch-core to core (#31185) Move cli sub-project out of server to libs (#31184) QA: Fixup rolling restart tests QA: Better seed nodes for rolling restart [DOCS] Fixes broken link in release notes [DOCS] Fixes broken link in auditing settings [DOCS] Moves ML content to stack-docs [DOCS] Clarifies recommendation for audit index output type (#31146) QA: Set better node names on rolling restart tests QA: Skip mysterious failing rolling upgrade tests Share common parser in some AcknowledgedResponses (#31169) Fix random failure on SearchQueryIT#testTermExpansionExceptionOnSpanFailure Remove reference to multiple fields with one name (#31127) Remove BlobContainer.move() method (#31100) [Docs] Correct minor typos in templates.asciidoc (#31167) Use ESBlobStoreRepositoryIntegTestCase to test the repository-s3 plugin (#29315) ...

jdconrad added 30 commits April 17, 2018 16:45

Separate identifiers into its own section. Clean up variables.

153d376

More docs.

6729d5f

Merge branch 'master' into docs1

84048e4

Merge branch 'master' into docs1

10fca6c

Modify language used to describe shallow copies.

c2c3448

Move examples into lists to make sections flow better when multiple

1cdf013

examples are used.

Update primitive types.

862962b

Cleaned up reference types.

73883ac

Clean up dynamic types.

7dfb034

String and void type clean up.

75f1498

Merge branch 'master' into docs2

f75d50e

Merge branch 'master' into docs2

956a188

Fixes.

bce78ed

Merge branch 'master' into docs2

b034cff

Clean up types section.

e82a1e0

Merge branch 'master' into docs2

1da1704

Merge branch 'master' into docs3

48b3aee

Some casting and example clean up.

8bc0c74

Merge branch 'master' into docs3

275c2e7

Updated examples.

00ba531

More changes.

7bcd114

Merge branch 'master' into docs3

84ea43d

Merge branch 'master' into docs3

1cf2f0b

More example clean up.

68059ae

More casting clean up.

73a24f0

More clean up.

c3fcd67

More changes.

19abc56

Merge branch 'master' into docs3

00cf5df

More fixes.

0cb3e66

Merge branch 'master' into docs3

bc4509f

Merge branch 'docs8' into docs9

2e38982

debadair reviewed Jun 4, 2018

View reviewed changes

jdconrad added 10 commits June 4, 2018 17:16

Response to PR review.

c688199

Merge branch 'master' into docs5

542f52e

Merge branch 'docs5' into docs6

e0e7dce

PR response to numeric operators.

603e5e5

Merge branch 'docs6' into docs7

afdc961

Response to PR comments for reference operators.

12fb54d

Merge branch 'docs7' into docs8

c83ecaf

Cleaned up array operators based on PR feedback.

be37bf1

Merge branch 'docs8' into docs9

f0bd472

Clean up boolean operators based on PR feedback.

c35e977

Accidentally left in modified test.

0760a41

debadair reviewed Jun 7, 2018

View reviewed changes

jdconrad added 2 commits June 7, 2018 14:03

Response to more PR feedback.

c361792

Merge branch 'master' into docs5

038dd80

debadair approved these changes Jun 7, 2018

View reviewed changes

Merge branch 'master' into docs5

d20d5d8

jdconrad merged commit d6a4c14 into elastic:master Jun 8, 2018

jdconrad added the backport pending label Jun 8, 2018

jdconrad removed the backport pending label Jun 8, 2018

jimczi added v7.0.0-beta1 and removed v7.0.0 labels Feb 7, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Painless: Restructure Spec Documentation #31013

Painless: Restructure Spec Documentation #31013

jdconrad commented May 31, 2018 •

edited

Loading

debadair left a comment

debadair Jun 4, 2018

jdconrad Jun 5, 2018

debadair Jun 4, 2018

jdconrad Jun 5, 2018

jdconrad Jun 5, 2018

debadair Jun 4, 2018

jdconrad Jun 5, 2018

debadair Jun 4, 2018

jdconrad Jun 5, 2018

debadair Jun 4, 2018

jdconrad Jun 5, 2018

debadair Jun 4, 2018

jdconrad Jun 5, 2018

debadair Jun 4, 2018

jdconrad Jun 5, 2018

debadair Jun 4, 2018

jdconrad Jun 5, 2018

jdconrad Jun 5, 2018

debadair Jun 4, 2018

jdconrad Jun 5, 2018

debadair Jun 4, 2018

jdconrad Jun 5, 2018

jdconrad commented Jun 5, 2018

debadair left a comment

debadair Jun 7, 2018

jdconrad Jun 7, 2018

debadair Jun 7, 2018

jdconrad Jun 7, 2018

debadair Jun 7, 2018

jdconrad Jun 7, 2018

jdconrad commented Jun 7, 2018

jdconrad commented Jun 7, 2018

jdconrad commented Jun 7, 2018

		==== Boolean Not

		Boolean not will flip a boolean value from true to false or false to true using the bang operator. The format is a bang operator followed by an expression.

		----

		Note that def types will be assumed to be of the boolean type. Any def type evaluated at run-time that does not represent a boolean will result in an error. Non-boolean expressions will result in an error.

		----

		A numeric promotion may occur during a less than operation. A def type evaluated at run-time will follow the same promotion table at run-time following whatever type def represents. Non-numeric expressions will result in an error.

		==== Boolean And

		Boolean and will and together two boolean expressions. If the first expression is found to be false then it is known that the result will also be false, so evaluation of the second expression will be skipped. The table below shows what the resultant boolean value will be based on the two boolean expressions.

		==== Post Increment

		A variable/field representing a numerical value can be possibly evaluated as part of an expression, and then increased by 1 for its respective type. The format starts with a variable name followed by a plus and ends with a plus.

		==== Pre Increment

		A variable/field representing a numerical value can be increased by 1 for its respective type, and then possibly evaluated as part of an expression. The format starts with a plus followed by a plus and ends with a variable name.

Painless: Restructure Spec Documentation #31013

Painless: Restructure Spec Documentation #31013

Conversation

jdconrad commented May 31, 2018 • edited Loading

debadair left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jdconrad commented Jun 5, 2018

debadair left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jdconrad commented Jun 7, 2018

jdconrad commented Jun 7, 2018

jdconrad commented Jun 7, 2018

jdconrad commented May 31, 2018 •

edited

Loading