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.h"
#include "BLI_string_ref.hh"
#include "BLI_string_utils.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::Error

Namespaces
namespace	blender
namespace	blender::bke
namespace	blender::bke::path_templates

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< blender::bke::path_templates::VariableMap >	BKE_build_template_variables_for_prop (const bContext *C, PointerRNA *ptr, PropertyRNA *prop)
void	BKE_add_template_variables_general (blender::bke::path_templates::VariableMap &variables, const ID *path_owner_id)
void	BKE_add_template_variables_for_render_path (blender::bke::path_templates::VariableMap &variables, const Scene &scene)
void	BKE_add_template_variables_for_node (blender::bke::path_templates::VariableMap &variables, const bNode &owning_node)
bool	BKE_path_contains_template_syntax (blender::StringRef path)
blender::Vector< blender::bke::path_templates::Error >	BKE_path_validate_template (blender::StringRef path, const blender::bke::path_templates::VariableMap &template_variables)
blender::Vector< blender::bke::path_templates::Error >	BKE_path_apply_template (char *path, int path_maxncpy, const blender::bke::path_templates::VariableMap &template_variables)
std::string	BKE_path_template_error_to_string (const blender::bke::path_templates::Error &error, blender::StringRef path)
void	BKE_report_path_template_errors (ReportList *reports, eReportType report_type, blender::StringRef path, blender::Span< blender::bke::path_templates::Error > errors)
std::optional< std::string >	BKE_path_template_format_float (blender::StringRef format_specifier, double value)
std::optional< std::string >	BKE_path_template_format_int (blender::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);

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.

Function Documentation

BKE_add_template_variables_for_node()

void BKE_add_template_variables_for_node	(	blender::bke::path_templates::VariableMap &	variables,
		const bNode &	owning_node )

Add the variables that should be available for paths owned by a node.

This is typically used when building a variable map to pass to BKE_path_apply_template().

Parameters

owning_node

the node that owns the path property that will be evaluated with the produced variable map.

See also

BKE_path_apply_template()

Definition at line 330 of file path_templates.cc.

References blender::bke::path_templates::VariableMap::add_string(), and bNode::name.

Referenced by BKE_build_template_variables_for_prop(), and blender::nodes::node_composite_file_output_cc::compute_image_path().

BKE_add_template_variables_for_render_path()

void BKE_add_template_variables_for_render_path	(	blender::bke::path_templates::VariableMap &	variables,
		const Scene &	scene )

Add the variables that should be available for render output paths.

Corresponds to #PropertyPathTemplateType::PROP_VARIABLES_RENDER_OUTPUT.

This is typically used when building a variable map to pass to BKE_path_apply_template().

Parameters

scene

scene to use to get the variable values. Note for the future: when we add a "current frame number" variable it should not come from this parameter, but be passed separately. This is because the callers of this function sometimes have the current frame defined separately from the available RenderData (see e.g. do_makepicstring()).

See also

BKE_path_apply_template()

Definition at line 302 of file path_templates.cc.

References blender::bke::path_templates::VariableMap::add_float(), blender::bke::path_templates::VariableMap::add_integer(), blender::bke::path_templates::VariableMap::add_string(), BKE_render_resolution(), Scene::camera, RenderData::frs_sec, RenderData::frs_sec_base, Object::id, Scene::id, ID::name, and Scene::r.

Referenced by BKE_build_template_variables_for_prop(), blender::nodes::node_composite_file_output_cc::compute_image_path(), do_write_image_or_movie(), RE_RenderAnim(), RE_RenderFrame(), screen_opengl_render_anim_step(), screen_opengl_render_write(), and write_result().

BKE_add_template_variables_general()

void BKE_add_template_variables_general	(	blender::bke::path_templates::VariableMap &	variables,
		const ID *	path_owner_id )

Add the general variables that should be available for all path templates.

This is typically used when building a variable map to pass to BKE_path_apply_template().

Parameters

path_owner_id

the ID that owns the path property that will be evaluated with the produced variable map. Passing a nullptr is allowed, but doing so has semantic meaning: it means that there is no owning ID. Only pass nullptr when that is actually true, not just out of convenience, because it alters the produced variables.

See also

BKE_path_apply_template()

Definition at line 273 of file path_templates.cc.

References blender::bke::path_templates::VariableMap::add_filename_only(), blender::bke::path_templates::VariableMap::add_path_up_to_file(), BKE_main_blendfile_path_from_global(), DATA_, and ID_BLEND_PATH_FROM_GLOBAL.

Referenced by BKE_build_template_variables_for_prop(), blender::nodes::node_composite_file_output_cc::compute_image_path(), do_write_image_or_movie(), RE_RenderAnim(), RE_RenderFrame(), screen_opengl_render_anim_step(), screen_opengl_render_write(), and write_result().

BKE_build_template_variables_for_prop()

std::optional< blender::bke::path_templates::VariableMap > BKE_build_template_variables_for_prop	(	const bContext *	C,
		PointerRNA *	ptr,
		PropertyRNA *	prop )

Build a template variable map for the passed RNA property.

Parameters

C	the context to use for building some variables. This is needed in some cases when the property and its owner do not provide the data needed for a variable. This parameter can be null, but the variables it's needed for will then be absent in the returned variable map.

Returns

On success, returns the template variables for the property. If no property is provided or if the property doesn't support path templates, returns #std::nullopt.

Definition at line 190 of file path_templates.cc.

References BKE_add_template_variables_for_node(), BKE_add_template_variables_for_render_path(), BKE_add_template_variables_general(), C, CTX_data_scene(), GS, ID_SCE, PROP_PATH_SUPPORTS_TEMPLATES, PROP_VARIABLES_NONE, PROP_VARIABLES_RENDER_OUTPUT, ptr, RNA_property_flag(), RNA_property_path_template_type(), and RNA_struct_search_closest_ancestor_by_type().

Referenced by file_browse_invoke(), ui_item_with_label(), and ui_tooltip_data_from_button_or_extra_icon().

BKE_path_apply_template()

blender::Vector< blender::bke::path_templates::Error > BKE_path_apply_template	(	char *	path,
		int	path_maxncpy,
		const blender::bke::path_templates::VariableMap &	template_variables )

Perform variable substitution and escaping on the given path.

This mutates the path in-place. path must be a null-terminated string.

The syntax for template expressions is {variable_name} or {variable_name:format_spec}. The format specification syntax currently only applies to numerical values (integer or float), and uses hash symbols (#) to indicate the number of digits to print the number with. It can be in any of the following forms:

• ####: format as an integer with at least 4 digits, padding with zeros as needed.
• .###: format as a float with precisely 3 fractional digits.
• ##.###: format as a float with at least 2 integer-part digits (padded with zeros as necessary) and precisely 3 fractional-part digits.

This function also processes a simple escape sequence for writing literal { and }: like Python format strings, double braces {{ and }} are treated as escape sequences for { and }, and are substituted appropriately. Note that this substitution only happens outside of the variable syntax, and therefore cannot e.g. be used inside variable names.

If any errors are encountered, the path is left unaltered and a list of all errors encountered is returned. Errors include:

• Variable expression syntax errors.
• Unescaped curly braces.
• Referenced variables that cannot be found.
• Format specifications that don't apply to the type of variable they're paired with.

Parameters

path_maxncpy

The maximum length that template expansion is allowed to make the template-expanded path (in bytes), including the null terminator. In general, this should be the size of the underlying allocation of path.

Returns

On success, an empty vector. If there are errors, a vector of all errors encountered.

Definition at line 960 of file path_templates.cc.

References BLI_assert, BLI_strncpy(), blender::Vector< T, InlineBufferCapacity, Allocator >::data(), eval_template(), blender::Vector< T, InlineBufferCapacity, Allocator >::is_empty(), and blender::Vector< T, InlineBufferCapacity, Allocator >::size().

Referenced by do_makepicstring(), file_browse_invoke(), and blender::bke::tests::TEST().

BKE_path_contains_template_syntax()

bool BKE_path_contains_template_syntax

(

blender::StringRef

path

)

Check if a path contains any templating syntax at all.

This is primarily intended to be used as a pre-check in performance-sensitive code to skip path template processing when it's not needed.

Returns

False if the path contains no templating syntax (no template processing is needed). True if the path does contain templating syntax (template processing is needed).

Definition at line 809 of file path_templates.cc.

References blender::StringRefBase::find_first_of().

Referenced by ui_item_with_label(), and ui_tooltip_data_from_button_or_extra_icon().

BKE_path_template_error_to_string()

std::string BKE_path_template_error_to_string	(	const blender::bke::path_templates::Error &	error,
		blender::StringRef	path )

Produces a human-readable error message for the given template error.

Definition at line 978 of file path_templates.cc.

References BLI_assert_msg, error(), blender::bke::path_templates::FORMAT_SPECIFIER, blender::StringRefBase::substr(), blender::bke::path_templates::UNESCAPED_CURLY_BRACE, blender::bke::path_templates::UNKNOWN_VARIABLE, and blender::bke::path_templates::VARIABLE_SYNTAX.

Referenced by BKE_report_path_template_errors(), blender::nodes::node_composite_file_output_cc::output_path_layout(), and ui_tooltip_data_from_button_or_extra_icon().

BKE_path_template_format_float()

std::optional< std::string > BKE_path_template_format_float	(	blender::StringRef	format_specifier,
		double	value )

Format the given floating point value with the provided format specifier. The format specifier is e.g. the ##.### in {name:##.###}.

Returns

#std::nullopt if the format specifier is invalid.

Definition at line 1019 of file path_templates.cc.

References FORMAT_BUFFER_SIZE, format_float_to_string(), and parse_format_specifier().

Referenced by blender::nodes::node_fn_format_string_cc::format_with_hash_syntax().

BKE_path_template_format_int()

std::optional< std::string > BKE_path_template_format_int	(	blender::StringRef	format_specifier,
		int64_t	value )

Same as BKE_path_template_format_float but for formatting an integer value.

Definition at line 1031 of file path_templates.cc.

References FORMAT_BUFFER_SIZE, format_int_to_string(), and parse_format_specifier().

Referenced by blender::nodes::node_fn_format_string_cc::format_with_hash_syntax().

BKE_path_validate_template()

blender::Vector< blender::bke::path_templates::Error > BKE_path_validate_template	(	blender::StringRef	path,
		const blender::bke::path_templates::VariableMap &	template_variables )

Validate the templating in the given path.

This produces identical errors as BKE_path_apply_template(), but without modifying the path on success.

Returns

An empty vector if the templating in the path is valid, or a vector of the errors if invalid.

See also

BKE_path_apply_template()

Definition at line 954 of file path_templates.cc.

References eval_template().

Referenced by blender::bke::tests::TEST(), ui_item_with_label(), and ui_tooltip_data_from_button_or_extra_icon().

BKE_report_path_template_errors()

void BKE_report_path_template_errors	(	ReportList *	reports,
		eReportType	report_type,
		blender::StringRef	path,
		blender::Span< blender::bke::path_templates::Error >	errors )

Logs a report for the given template errors, with human-readable error messages.

Definition at line 1004 of file path_templates.cc.

References BKE_path_template_error_to_string(), BKE_report(), BLI_assert, error(), and blender::Span< T >::is_empty().

Referenced by do_write_image_or_movie(), file_browse_invoke(), RE_RenderAnim(), RE_RenderFrame(), screen_opengl_render_anim_step(), screen_opengl_render_write(), and write_result().