30 requires std::convertible_to<F, T (*)(X...)>
38 [[deprecated(
"Lambda return type does not match TemplatableFn<T> — use the correct type in "
40 requires(!std::convertible_to<F, T (*)(X...)>) && std::invocable<F, X...> &&
41 std::convertible_to<std::invoke_result_t<F, X...>, T> && std::is_empty_v<F> && std::default_initializable<F>
42 :
f_([](X...
x) -> T { return static_cast<T>(F{}(
x...)); }) {}
47 requires std::invocable<F, X...> && (!std::convertible_to<F, T (*)(X...)>) &&
48 (!std::is_empty_v<F> || !std::convertible_to<std::invoke_result_t<F, X...>, T> ||
49 !std::default_initializable<F>)
58 requires(!std::invocable<V, X...>) && (!std::convertible_to<V, T (*)(X...)>)
60 static_assert(
sizeof(V) == 0,
"Missing cg.templatable(...) in Python codegen for this TEMPLATABLE_VALUE "
61 "field. The wrapper was always required; it worked by accident because the old "
62 "TemplatableValue implicitly converted raw constants. TemplatableFn cannot. See "
63 "https://developers.esphome.io/blog/2026/04/09/"
64 "templatablefn-4-byte-templatable-storage-for-trivially-copyable-types/");
67 bool has_value()
const {
return this->f_ !=
nullptr; }
69 T
value(X...
x)
const {
return this->f_ ? this->f_(
x...) : T{}; }
74 return this->f_(
x...);
77 T
value_or(X...
x, T default_value)
const {
return this->f_ ? this->f_(
x...) : default_value; }
80 T (*f_)(X...){
nullptr};
88 this->code_.func = func;
92 this->code_.data = data;
97 const uint8_t *
data()
const {
return this->code_.data; }
99 size_t size()
const {
return static_cast<size_t>(this->len_); }
100 std::vector<uint8_t>
value(
const Ts &...
x)
const {
102 return this->code_.func(
x...);
103 return to_vector(this->code_.data, this->size());
107 template<
size_t N = 64,
typename F>
void visit(F &&fn,
const Ts &...
x)
const {
108 if (this->len_ < 0) {
109 const std::vector<uint8_t> bytes = this->code_.func(
x...);
110 fn(bytes.data(), bytes.size());
117 fn(buf.
get(), this->size());
119 fn(this->code_.data, this->size());
124 static std::vector<uint8_t>
to_vector(
const uint8_t *data,
size_t len) {
125 std::vector<uint8_t>
out(
len);
133 std::vector<uint8_t> (*func)(Ts...);
139#define TEMPLATABLE_BYTES(name) \
141 TemplatableBytes<Ts...> name##_{}; \
144 void set_##name##_template(std::vector<uint8_t> (*func)(Ts...)) { this->name##_.set_template(func); } \
145 void set_##name##_static(const uint8_t *data, uint16_t len) { this->name##_.set_static(data, len); }
148template<
typename T,
typename... X>
class TemplatableValue;
153template<
typename T,
typename... X>
157#define TEMPLATABLE_VALUE_(type, name) \
159 TemplatableStorage<type, Ts...> name##_{}; \
162 template<typename V> void set_##name(V name) { this->name##_ = name; }
164#define TEMPLATABLE_VALUE(type, name) TEMPLATABLE_VALUE_(type, name)
177 requires(!std::invocable<V, X...>)
179 new (&this->storage_.value_) T(
static_cast<T
>(std::move(value)));
185 requires std::convertible_to<F, T (*)(X...)>
187 this->storage_.f_ = f;
192 [[deprecated(
"Lambda return type does not match TemplatableValue<T> — use the correct type in "
194 requires(!std::convertible_to<F, T (*)(X...)>) && std::invocable<F, X...> &&
195 std::convertible_to<std::invoke_result_t<F, X...>, T> && std::is_empty_v<F> && std::default_initializable<F>
197 this->storage_.f_ = [](X...
x) -> T {
return static_cast<T
>(F{}(
x...)); };
203 requires std::invocable<F, X...> && (!std::convertible_to<F, T (*)(X...)>) &&
204 (!std::is_empty_v<F> || !std::convertible_to<std::invoke_result_t<F, X...>, T> ||
205 !std::default_initializable<F>)
209 if (this->tag_ == VALUE) {
211 }
else if (this->tag_ == FN) {
217 if (this->tag_ == VALUE) {
218 new (&this->storage_.value_) T(std::move(other.storage_.value_));
220 }
else if (this->tag_ == FN) {
221 this->storage_.f_ = other.storage_.f_;
227 if (
this != &other) {
229 this->tag_ = other.tag_;
230 if (this->tag_ == VALUE) {
232 }
else if (this->tag_ == FN) {
240 if (
this != &other) {
242 this->tag_ = other.tag_;
243 if (this->tag_ == VALUE) {
244 new (&this->storage_.value_) T(std::move(other.storage_.value_));
246 }
else if (this->tag_ == FN) {
247 this->storage_.f_ = other.storage_.f_;
259 if (this->tag_ == FN)
260 return this->storage_.f_(
x...);
261 if (this->tag_ == VALUE)
262 return this->storage_.value_;
267 if (this->tag_ == NONE)
269 return this->value(
x...);
273 if (this->tag_ == NONE)
274 return default_value;
275 return this->value(
x...);
280 if constexpr (!std::is_trivially_destructible_v<T>) {
281 if (this->tag_ == VALUE)
282 this->storage_.value_.~T();
286 enum Tag : uint8_t { NONE, VALUE, FN } tag_{NONE};
313 this->static_str_ =
reinterpret_cast<const char *
>(str);
319 requires(!std::invocable<F, X...>)
321 this->value_ =
new std::string(std::move(value));
327 requires std::invocable<F, X...> && std::convertible_to<F, std::string (*)(X...)>
328 : type_(STATELESS_LAMBDA) {
329 this->stateless_f_ = f;
335 requires std::invocable<F, X...> && (!std::convertible_to<F, std::string (*)(X...)>)
337 this->f_ =
new std::function<std::string(X...)>(std::move(f));
342 if (this->type_ == VALUE) {
343 this->value_ =
new std::string(*other.value_);
344 }
else if (this->type_ == LAMBDA) {
345 this->f_ =
new std::function<std::string(X...)>(*other.f_);
346 }
else if (this->type_ == STATELESS_LAMBDA) {
347 this->stateless_f_ = other.stateless_f_;
348 }
else if (this->type_ == STATIC_STRING || this->type_ == FLASH_STRING) {
349 this->static_str_ = other.static_str_;
355 if (this->type_ == VALUE) {
356 this->value_ = other.value_;
357 other.value_ =
nullptr;
358 }
else if (this->type_ == LAMBDA) {
361 }
else if (this->type_ == STATELESS_LAMBDA) {
362 this->stateless_f_ = other.stateless_f_;
363 }
else if (this->type_ == STATIC_STRING || this->type_ == FLASH_STRING) {
364 this->static_str_ = other.static_str_;
371 if (
this != &other) {
379 if (
this != &other) {
387 if (this->type_ == VALUE) {
389 }
else if (this->type_ == LAMBDA) {
397 bool is_lambda()
const {
return this->type_ == LAMBDA || this->type_ == STATELESS_LAMBDA; }
400 switch (this->type_) {
401 case STATELESS_LAMBDA:
402 return this->stateless_f_(
x...);
404 return (*this->f_)(
x...);
406 return *this->value_;
408 return std::string(this->static_str_);
420 if (!this->has_value())
422 return this->value(
x...);
425 std::string
value_or(X...
x, std::string default_value)
const {
426 if (!this->has_value())
427 return default_value;
428 return this->value(
x...);
435 ESPDEPRECATED(
"Read the value with ref_or_copy_to() instead. Removed in 2027.4.0",
"2026.10.0")
436 bool is_static_string()
const {
return this->type_ == STATIC_STRING; }
441 ESPDEPRECATED(
"Use ref_or_copy_to() instead. Removed in 2027.4.0",
"2026.10.0")
442 const
char *get_static_string()
const {
return this->static_str_; }
448 switch (this->type_) {
452 return this->static_str_ ==
nullptr || this->static_str_[0] ==
'\0';
456 return this->static_str_ ==
nullptr ||
460 return this->value_->empty();
462 return this->value().empty();
474 switch (this->type_) {
478 if (this->static_str_ ==
nullptr)
480 return StringRef(this->static_str_, strlen(this->static_str_));
483 if (this->static_str_ ==
nullptr)
487 size_t len = strlen_P(this->static_str_);
488 size_t copy_len = std::min(
len, lambda_buf_size - 1);
489 memcpy_P(lambda_buf, this->static_str_, copy_len);
490 lambda_buf[copy_len] =
'\0';
495 return StringRef(this->value_->data(), this->value_->size());
497 std::string result = this->value();
498 size_t copy_len = std::min(result.size(), lambda_buf_size - 1);
499 memcpy(lambda_buf, result.data(), copy_len);
500 lambda_buf[copy_len] =
'\0';
517 std::function<std::string(X...)> *
f_;
518 std::string (*stateless_f_)(X...);
528 std::conditional_t<std::is_copy_constructible_v<std::remove_cvref_t<T>>, std::remove_cvref_t<T>, T>;
541 return this->check_tuple_(tuple, std::make_index_sequence<
sizeof...(Ts)>{});
545 template<
size_t... S>
bool check_tuple_(
const std::tuple<Ts...> &tuple, std::index_sequence<S...> ) {
546 return this->check(std::get<S>(tuple)...);
550template<
typename... Ts>
class Automation;
557 inline void trigger(
const Ts &...
x) ESPHOME_ALWAYS_INLINE {
558 if (this->automation_parent_ ==
nullptr)
560 this->automation_parent_->trigger(
x...);
566 if (this->automation_parent_ ==
nullptr)
568 this->automation_parent_->stop();
572 if (this->automation_parent_ ==
nullptr)
574 return this->automation_parent_->is_running();
581template<
typename... Ts>
class ActionList;
586 this->num_running_++;
588 this->play_next_(
x...);
593 this->num_running_ = 0;
598 bool is_running() {
return this->num_running_ > 0 || this->is_running_next_(); }
603 int total = this->num_running_;
605 total +=
next->num_running_total();
613 virtual void play(
const Ts &...
x) = 0;
615 if (this->num_running_ > 0) {
616 this->num_running_--;
617 if (this->next_is_owner_()) {
618 this->owner_()->play(
x...);
619 }
else if (this->next_ !=
nullptr) {
620 this->next_->play_complex(
x...);
624 template<
size_t... S>
void play_next_tuple_(
const std::tuple<Ts...> &tuple, std::index_sequence<S...> ) {
625 this->play_next_(std::get<S>(tuple)...);
628 this->play_next_tuple_(tuple, std::make_index_sequence<
sizeof...(Ts)>{});
634 next->stop_complex();
639 return next !=
nullptr &&
next->is_running();
644 static constexpr uintptr_t OWNER_TAG = 1;
645 bool next_is_owner_()
const {
return reinterpret_cast<uintptr_t
>(this->next_) & OWNER_TAG; }
647 Action *
owner_()
const {
return reinterpret_cast<Action *
>(
reinterpret_cast<char *
>(this->next_) - OWNER_TAG); }
650 return reinterpret_cast<Action *
>(
reinterpret_cast<char *
>(owner) + OWNER_TAG);
661static_assert(
alignof(Action<>) >= 2,
"the owner tag needs a free low bit in Action object pointers");
667 *this->tail_() = action;
671 Action<Ts...> **tail = this->tail_();
672 for (
auto *action : actions) {
674 tail = &action->next_;
680 if (this->actions_ ==
nullptr)
686 inline void play(
const Ts &...
x) ESPHOME_ALWAYS_INLINE {
687 if (this->actions_ !=
nullptr)
688 this->actions_->play_complex(
x...);
691 this->play_tuple_(tuple, std::make_index_sequence<
sizeof...(Ts)>{});
694 if (this->actions_ !=
nullptr)
695 this->actions_->stop_complex();
697 bool empty()
const {
return this->actions_ ==
nullptr; }
701 if (this->actions_ ==
nullptr)
703 return this->actions_->is_running();
707 if (this->actions_ ==
nullptr)
709 return this->actions_->num_running_total();
713 template<
size_t... S>
void play_tuple_(
const std::tuple<Ts...> &tuple, std::index_sequence<S...> ) {
714 this->play(std::get<S>(tuple)...);
718 Action<Ts...> **tail = &this->actions_;
719 while (*tail !=
nullptr) {
722 ESPHOME_DEBUG_ASSERT(!(*tail)->next_is_owner_());
723 tail = &(*tail)->next_;
742 void stop() { this->actions_.stop(); }
746 inline void trigger(
const Ts &...
x) ESPHOME_ALWAYS_INLINE { this->actions_.play(
x...); }
758template<
typename... Ts>
760 for (
auto *automation : automations)
761 automation->trigger(
x...);
768 bool empty()
const {
return this->automations_.empty(); }
770 template<
typename... Args>
void trigger(Args &&...
x) {
771 if (this->automations_.empty())
785 void operator()(
const Ts &...args)
const { this->automation->trigger(args...); }
810static_assert(
sizeof(TriggerForwarder<>) <=
sizeof(
void *));
811static_assert(
sizeof(TriggerOnTrueForwarder) <=
sizeof(
void *));
812static_assert(
sizeof(TriggerOnFalseForwarder) <=
sizeof(
void *));
813static_assert(std::is_trivially_copyable_v<TriggerForwarder<>>);
814static_assert(std::is_trivially_copyable_v<TriggerOnTrueForwarder>);
815static_assert(std::is_trivially_copyable_v<TriggerOnFalseForwarder>);
bool is_running()
Check if this or any of the following actions are currently running.
Action * chain_next_() const
Action * owner_() const
Only valid when next_is_owner_().
static Action * tag_owner(Action *owner)
void play_next_(const Ts &...x)
virtual void play(const Ts &...x)=0
For a branch owner (if, while), play() runs when the branch finishes.
void play_next_tuple_(const std::tuple< Ts... > &tuple)
int num_running_total()
The total number of actions that are currently running in this plus any of the following actions in t...
void play_next_tuple_(const std::tuple< Ts... > &tuple, std::index_sequence< S... >)
bool next_is_owner_() const
virtual void play_complex(const Ts &...x)
void add_action(Action< Ts... > *action)
void play_tuple(const std::tuple< Ts... > &tuple)
bool is_running()
Check if any action in this action list is currently running.
void add_actions(const std::initializer_list< Action< Ts... > * > &actions)
Action< Ts... > ** tail_()
void play_tuple_(const std::tuple< Ts... > &tuple, std::index_sequence< S... >)
void play(const Ts &...x) ESPHOME_ALWAYS_INLINE
void set_owner(Action< Ts... > *owner)
Resume owner via play() when the list finishes; call once, after adding actions.
int num_running()
Return the number of actions in this action list that are currently running.
void add_action(Action< Ts... > *action)
int num_running()
Return the number of actions in the action part of this automation that are currently running.
void trigger(const Ts &...x) ESPHOME_ALWAYS_INLINE
Automation(Trigger< Ts... > *trigger)
void add_actions(const std::initializer_list< Action< Ts... > * > &actions)
ActionList< Ts... > actions_
constexpr Automation() noexcept
Default constructor for use with TriggerForwarder (no Trigger object needed).
Automations a component triggers itself, sized at codegen time (count from cg.slot_counter).
void trigger(Args &&...x)
Arguments convert to Ts only when the list is not empty (e.g. const char * to std::string).
void add(Automation< Ts... > *automation)
StaticVector< Automation< Ts... > *, N > automations_
Base class for all automation conditions.
bool check_tuple_(const std::tuple< Ts... > &tuple, std::index_sequence< S... >)
bool check_tuple(const std::tuple< Ts... > &tuple)
Call check with a tuple of values as parameter.
virtual bool check(const Ts &...x)=0
Check whether this condition passes. This condition check must be instant, and not cause any delays.
Helper class for efficient buffer allocation - uses stack for small sizes, heap for large This is use...
Minimal static vector - saves memory by avoiding std::vector overhead.
StringRef is a reference to a string owned by something else.
Byte payload that is either a stateless lambda or a static table, which may be in PROGMEM.
static std::vector< uint8_t > to_vector(const uint8_t *data, size_t len)
void visit(F &&fn, const Ts &...x) const
Calls fn(const uint8_t *data, size_t len) with the payload readable from RAM: a lambda's vector,...
size_t size() const
Only valid when is_static().
void set_static(const uint8_t *data, uint16_t len)
void set_template(std::vector< uint8_t >(*func)(Ts...))
std::vector< uint8_t > value(const Ts &...x) const
const uint8_t * data() const
Only valid when is_static(); may point to PROGMEM, so read it with progmem_memcpy or progmem_read_byt...
Function-pointer-only templatable storage (4 bytes on 32-bit).
constexpr TemplatableFn()=default
T value_or(X... x, T default_value) const
constexpr TemplatableFn(F f)
TemplatableFn(std::nullptr_t)=delete
optional< T > optional_value(X... x) const
TemplatableValue(const __FlashStringHelper *str)
ESPDEPRECATED("Read the value with ref_or_copy_to() instead. Removed in 2027.4.0", "2026.10.0") bool is_static_string() const
Check if this holds a static string (const char* stored without allocation) The pointer is always dir...
TemplatableValue(TemplatableValue &&other) noexcept
TemplatableValue(const char *str)
TemplatableValue & operator=(const TemplatableValue &other)
bool is_lambda() const
Whether the value comes from a lambda, so it may differ between reads.
bool is_empty() const
Check if the string value is empty without allocating.
TemplatableValue(const TemplatableValue &other)
TemplatableValue & operator=(TemplatableValue &&other) noexcept
TemplatableValue(F value)
StringRef ref_or_copy_to(char *lambda_buf, size_t lambda_buf_size) const
Get a StringRef to the string value without heap allocation when possible.
std::string value_or(X... x, std::string default_value) const
ESPDEPRECATED("Use ref_or_copy_to() instead. Removed in 2027.4.0", "2026.10.0") const char *get_static_string() const
Get the static string pointer (only valid if is_static_string() returns true) The pointer is always d...
std::string value(X... x) const
optional< std::string > optional_value(X... x) const
std::function< std::string(X...)> * f_
Primary TemplatableValue: stores either a constant value or a function pointer.
TemplatableValue(const TemplatableValue &other)
TemplatableValue & operator=(TemplatableValue &&other) noexcept
union esphome::TemplatableValue::Storage storage_
TemplatableValue(V value)
TemplatableValue(TemplatableValue &&other) noexcept
optional< T > optional_value(X... x) const
TemplatableValue()=default
TemplatableValue & operator=(const TemplatableValue &other)
TemplatableValue(F)=delete
T value_or(X... x, T default_value) const
TemplatableValue(std::nullptr_t)=delete
void stop_action()
Stop any action connected to this trigger.
bool is_action_running()
Returns true if any action connected to this trigger is running.
void set_automation_parent(Automation< Ts... > *automation_parent)
void trigger(const Ts &...x) ESPHOME_ALWAYS_INLINE
Inform the parent automation that the event has triggered.
std::vector< uint8_t > & out
std::string progmem_string(ProgmemStr str)
Copies a string stored with ESPHOME_F into a std::string.
std::conditional_t< std::is_copy_constructible_v< std::remove_cvref_t< T > >, std::remove_cvref_t< T >, T > stored_trigger_arg_t
How deferring actions store a trigger argument: a copy, since a referenced object may be gone once th...
void progmem_memcpy(void *dst, const void *src, size_t len)
std::conditional_t< std::is_trivially_copyable_v< T >, TemplatableFn< T, X... >, TemplatableValue< T, X... > > TemplatableStorage
Selects TemplatableFn (4 bytes) for trivially copyable types, TemplatableValue (8 bytes) otherwise.
void trigger_automations(std::span< Automation< Ts... > *const > automations, const std::type_identity_t< Ts > &...x)
Triggers each automation in order; shared by every AutomationList size with the same arguments.
uint8_t progmem_read_byte(const uint8_t *addr)
const __FlashStringHelper * ProgmemStr
Callback forwarder that triggers an Automation directly.
Automation< Ts... > * automation
void operator()(const Ts &...args) const
Callback forwarder that triggers an Automation<> only when the bool arg is false.
void operator()(bool state) const
Callback forwarder that triggers an Automation<> only when the bool arg is true.
void operator()(bool state) const