Blender V5.3
BKE_path_templates.hh File Reference

Functions and classes for evaluating template expressions in filepaths. More...

#include <cmath>
#include <optional>
#include "BLI_map.hh"
#include "BLI_path_utils.hh"
#include "BLI_string.hh"
#include "BLI_string_ref.hh"
#include "BLI_string_utils.hh"
#include "BKE_blender_project.hh"
#include "BKE_report.hh"
#include "DNA_node_types.h"
#include "DNA_scene_types.h"

Go to the source code of this file.

Classes

class  blender::bke::path_templates::VariableMap
struct  blender::bke::path_templates::ExpressionInfo
struct  blender::bke::path_templates::Error

Namespaces

namespace  blender
 BMesh Iterators.
namespace  blender::bke
namespace  blender::bke::path_templates

Macros

#define BKE_TEMPLATE_EXPRESSION_ABBREVIATION   "{" BLI_STR_UTF8_HORIZONTAL_ELLIPSIS "}"

Enumerations

enum class  blender::bke::path_templates::ErrorType { blender::bke::path_templates::UNESCAPED_CURLY_BRACE , blender::bke::path_templates::VARIABLE_SYNTAX , blender::bke::path_templates::FORMAT_SPECIFIER , blender::bke::path_templates::UNKNOWN_VARIABLE }

Functions

bool blender::bke::path_templates::operator== (const Error &left, const Error &right)
std::optional< ExpressionInfo > blender::bke::path_templates::next_template_variable_expression (StringRef text, size_t starting_offset)
std::optional< bke::path_templates::VariableMap > blender::BKE_build_template_variables_for_prop (const bContext *C, PointerRNA *ptr, PropertyRNA *prop)
void blender::BKE_add_template_variables_for_project (bke::path_templates::VariableMap &variables, const bke::BlenderProject &project)
void blender::BKE_add_template_variables_general (bke::path_templates::VariableMap &variables, const ID *path_owner_id, const bke::BlenderProject *project)
void blender::BKE_add_template_variables_for_render_path (bke::path_templates::VariableMap &variables, const Scene &scene)
void blender::BKE_add_template_variables_for_node (bke::path_templates::VariableMap &variables, const bNode &owning_node)
std::string blender::BKE_path_template_escape (StringRef text)
bool blender::BKE_path_contains_template_syntax (StringRef path)
Vector< bke::path_templates::Error > blender::BKE_path_validate_template (StringRef path, const bke::path_templates::VariableMap &template_variables)
Vector< bke::path_templates::Error > blender::BKE_path_apply_template (char *path, int path_maxncpy, const bke::path_templates::VariableMap &template_variables)
Vector< bke::path_templates::Error > blender::BKE_path_apply_template_alloc (char **path, int path_maxncpy, const bke::path_templates::VariableMap &template_variables)
std::string blender::BKE_path_template_error_to_string (const bke::path_templates::Error &error, StringRef path)
void blender::BKE_report_path_template_errors (ReportList *reports, eReportType report_type, StringRef path, Span< bke::path_templates::Error > errors)
std::optional< std::string > blender::BKE_path_template_format_float (StringRef format_specifier, double value)
std::optional< std::string > blender::BKE_path_template_format_int (StringRef format_specifier, int64_t value)

Detailed Description

Functions and classes for evaluating template expressions in filepaths.

To add support for path templates to a path property:

  1. Enable #PROP_PATH_SUPPORTS_TEMPLATES in its RNA property flags.
  2. Optionally set its RNA path template type (#PropertyPathTemplateType) via #RNA_def_property_path_template_type(), if you want it to have access to any purpose-specific variables (see further below).
  3. Wherever the evaluated path is needed, generate an appropriate #VariableMap for it via the #BKE_add_template_variables_*() functions, and use that to evaluate the path via #BKE_path_apply_template().

An example of what step 3 might look like:

VariableMap template_variables;
BKE_add_template_variables_general(template_variables, owner_id);
BKE_add_template_variables_for_render_path(template_variables, scene);
BKE_add_template_variables_for_node(template_variables, owner_node);
BKE_path_apply_template(filepath, FILE_MAX, template_variables);
#define FILE_MAX

This calls three functions to build the #VariableMap, one for each "kind" of variable (see below).

Currently the path template system has three kinds of variables that can be used in expressions:

  • General variables, which are made available to all paths that support path templates. For example, the name of the current blend file.
  • Purpose-specific variables, which are determined by the path property's #PropertyPathTemplateType flag. For example, render output paths will be marked as #PROP_VARIABLES_RENDER_OUTPUT, and will therefore get access to variables like fps, which are rendering-specific.
  • Type-specific variables, which are variables made available to all path-template paths owned by a particular type of struct. For example, paths owned by a #bNode will have access to the node_name variable, which provides the name of the owning node.

At the moment there is no strict code structure that enforces this, just the following conventions:

  • All general variables are added by #BKE_add_template_variables_general().
  • Purpose-specific variables are organized into multiple functions: one function per variant in #PropertyPathTemplateType, with all variables for a variant going into the same function. Example: #BKE_add_template_variables_for_render_path()
  • Type-specific variables are organized into multiple functions: one per struct type, with all variables for a struct type going into the same function. Example: #BKE_add_template_variables_for_node()

When adding new #PropertyPathTemplateType variants or adding support for new owning struct types, make sure that you also call their variable-adding functions from #BKE_build_template_variables_for_prop(), which is used for highlighting template path errors in the UI for users.

Definition in file BKE_path_templates.hh.

Macro Definition Documentation

◆ BKE_TEMPLATE_EXPRESSION_ABBREVIATION

#define BKE_TEMPLATE_EXPRESSION_ABBREVIATION   "{" BLI_STR_UTF8_HORIZONTAL_ELLIPSIS "}"