From 479acf411b6769e17a13068ae37f91651d08a790 Mon Sep 17 00:00:00 2001
From: WeekendWarrior1 <c.halton.93@gmail.com>
Date: Thu, 30 Sep 2021 07:25:11 +1000
Subject: [PATCH] text sensor filter documentation (#1497)

* text sensor filter documentation

* document on raw value automation

* Apply suggestions from code review

thanks Oxan!

Co-authored-by: Oxan van Leeuwen <oxan@oxanvanleeuwen.nl>

Co-authored-by: Oxan van Leeuwen <oxan@oxanvanleeuwen.nl>
---
 components/text_sensor/index.rst | 135 +++++++++++++++++++++++++++++++
 1 file changed, 135 insertions(+)

diff --git a/components/text_sensor/index.rst b/components/text_sensor/index.rst
index 25bdc10f0..7911a29a2 100644
--- a/components/text_sensor/index.rst
+++ b/components/text_sensor/index.rst
@@ -38,6 +38,121 @@ Automations:
 
 - **on_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
   when a new value is published. See :ref:`text_sensor-on_value`.
+- **on_raw_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
+  when a new value is received that hasn't passed through any filters. See :ref:`text_sensor-on_raw_value`.
+
+.. _text_sensor-filters:
+
+Text Sensor Filters
+-------------------
+
+ESPHome allows you to do some basic pre-processing of
+text_sensor values before they’re sent to Home Assistant. This is for example
+useful if you want to manipulate the text_sensor string in some fashion.
+
+There are a lot of filters that sensors support. You define them by adding a ``filters``
+block in the text_sensor configuration (at the same level as ``platform``; or inside each text_sensor block
+for platforms with multiple sensors).
+
+Filters are processed in the order they are defined in your configuration.
+
+.. code-block:: yaml
+
+    # Example filters:
+    filters:
+      - to_upper:
+      - to_lower:
+      - append: "_prefix"
+      - prepend: "suffix_"
+      - substitute:
+        - "suf -> foo"
+        - "pre -> bar"
+      - lambda: return {"Hello World"};
+
+``to_upper``
+************
+
+Converts all characters within a string to uppercase (only the English alphabet is supported at this time).
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    - platform: template
+      # ...
+      filters:
+        - to_upper:
+
+``to_lower``
+************
+
+Converts all characters within a string to lowercase (only the English alphabet is supported at this time).
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    - platform: template
+      # ...
+      filters:
+        - to_lower:
+
+``append``
+**********
+
+Adds a string to the end of the current string.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    - platform: template
+      # ...
+      filters:
+        - append: "_prefix"
+
+``prepend``
+***********
+
+Adds a string to the start of the current string.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    - platform: template
+      # ...
+      filters:
+        - prepend: "suffix_"
+
+``substitute``
+**************
+
+Search the current value of the text sensor for a string, and replace it with another string.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    - platform: template
+      # ...
+      filters:
+        - substitute:
+          - "suf -> foo"
+          - "pre -> bar"
+
+The arguments are a list of substitutions, each in the form ``TO_FIND -> REPLACEMENT``.
+
+``lambda``
+**********
+
+Perform a advanced operations on the text sensor value. The input string is ``x`` and
+the result of the lambda is used as the output (use ``return``).
+
+.. code-block:: yaml
+
+    filters:
+      - lambda: |-
+          if (x == "Hello") {
+            return x + "bar";
+          } else {
+            return x + "foo";
+          }
 
 Text Sensor Automation
 ----------------------
@@ -65,6 +180,26 @@ In :ref:`Lambdas <config-lambda>` you can get the value from the trigger with ``
 
 Configuration variables: See :ref:`Automation <automation>`.
 
+.. _text_sensor-on_raw_value:
+
+``on_raw_value``
+****************
+
+This automation will be triggered when a new value is received that hasn't passed
+through any filters. In :ref:`Lambdas <config-lambda>` you can get the value from the trigger with ``x``.
+
+.. code-block:: yaml
+
+    text_sensor:
+      - platform: version
+        # ...
+        on_raw_value:
+          then:
+            - lambda: |-
+                ESP_LOGD("main", "The current version is %s", x.c_str());
+
+Configuration variables: See :ref:`Automation <automation>`.
+
 .. _text_sensor-state_condition:
 
 ``text_sensor.state`` Condition