[DOCS] EQL: Document substring function (#53867)

jrodewig · web-flow · commit f91d8ee3e788 · 2020-03-25T12:07:20.000-04:00
Adds documentation for the EQL `substring` function.

Supporting changes:

* Creates a new "EQL function reference" page
* Updates the title of the "EQL syntax reference" page for consistency
* Adds a brief "Functions" section to the EQL syntax docs
* Updates EQL limitations docs to state that only array functions are
  unsupported
diff --git a/docs/reference/eql/functions.asciidoc b/docs/reference/eql/functions.asciidoc
@@ -0,0 +1,66 @@
+[[eql-function-ref]]
+== EQL function reference
+++++
+<titleabbrev>Function reference</titleabbrev>
+++++
+
+experimental::[]
+
+{es} supports the following EQL functions:
+
+* <<eql-fn-substring>>
+
+[discrete]
+[[eql-fn-substring]]
+=== `substring`
+
+Extracts a substring from a source string at provided start and end positions.
+
+If no end position is provided, the function extracts the remaining string.
+
+[%collapsible]
+====
+*Example*
+[source,eql]
+----
+substring("start regsvr32.exe", 6)        // returns "regsvr32.exe"
+substring("start regsvr32.exe", 0, 5)     // returns "start"
+substring("start regsvr32.exe", 6, 14)    // returns "regsvr32"
+substring("start regsvr32.exe", -4)       // returns ".exe"
+substring("start regsvr32.exe", -4, -1)   // returns ".ex"
+----
+
+*Syntax*
+
+[source,txt]
+----
+substring(<source>, <start_pos>[, <end_pos>])
+----
+
+*Parameters*
+
+`<source>`::
+(Required, string)
+Source string.
+
+`<start_pos>`::
++
+--
+(Required, integer)
+Starting position for extraction.
+
+If this position is higher than the `<end_pos>` position or the length of the
+`<source>` string, the function returns an empty string.
+
+Positions are zero-indexed. Negative offsets are supported.
+--
+
+`<end_pos>`::
+(Optional, integer)
+Exclusive end position for extraction. If this position is not provided, the
+function returns the remaining string.
++
+Positions are zero-indexed. Negative offsets are supported.
+
+*Returns:* string
+====
diff --git a/docs/reference/eql/index.asciidoc b/docs/reference/eql/index.asciidoc
@@ -32,9 +32,11 @@ Consider using EQL if you:
 * <<eql-requirements>>
 * <<eql-search>>
 * <<eql-syntax>>
+* <<eql-function-ref>>
 * <<eql-limitations>>
 
 include::requirements.asciidoc[]
 include::search.asciidoc[]
 include::syntax.asciidoc[]
+include::functions.asciidoc[]
 include::limitations.asciidoc[]
diff --git a/docs/reference/eql/limitations.asciidoc b/docs/reference/eql/limitations.asciidoc
@@ -15,7 +15,10 @@ experimental::[]
 {es} supports a subset of {eql-ref}/index.html[EQL syntax]. {es} cannot run EQL
 queries that contain:
 
-* {eql-ref}/functions.html[Functions]
+* Array functions:
+** {eql-ref}/functions.html#arrayContains[`arrayContains`]
+** {eql-ref}/functions.html#arrayCount[`arrayCount`]
+** {eql-ref}/functions.html#arraySearch[`arraySearch`]
 
 * {eql-ref}/joins.html[Joins]
 
diff --git a/docs/reference/eql/syntax.asciidoc b/docs/reference/eql/syntax.asciidoc
@@ -2,6 +2,9 @@
 [testenv="basic"]
 [[eql-syntax]]
 == EQL syntax reference
+++++
+<titleabbrev>Syntax reference</titleabbrev>
+++++
 
 experimental::[]
 
@@ -283,3 +286,12 @@ dots (`.`), hyphens (`-`), or spaces, must be escaped using backticks (+++`+++).
 `my-field`
 `my field`
 ----
+
+[discrete]
+[[eql-functions]]
+=== Functions
+
+{es} supports several of EQL's built-in functions. You can use these functions
+to convert data types, perform math, manipulate strings, and more.
+
+For a list of supported functions, see <<eql-function-ref>>.
