#include <fmt/format.h>
#include "BLT_translation.hh"
#include "BLI_math_base.hh"
#include "BLI_path_utils.hh"
#include "BLI_span.hh"
#include "BKE_context.hh"
#include "BKE_library.hh"
#include "BKE_main.hh"
#include "BKE_path_templates.hh"
#include "BKE_scene.hh"
#include "RNA_access.hh"
#include "RNA_prototypes.hh"
#include "DNA_ID_enums.h"
#include "DNA_node_types.h"

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

Macros
#define	FORMAT_BUFFER_SIZE 512

Functions
bool	blender::bke::path_templates::operator== (const Error &left, const Error &right)
std::optional< VariableMap >	BKE_build_template_variables_for_prop (const bContext C, PointerRNA ptr, PropertyRNA *prop)
void	BKE_add_template_variables_general (VariableMap &variables, const ID *path_owner_id)
void	BKE_add_template_variables_for_render_path (VariableMap &variables, const Scene &scene)
void	BKE_add_template_variables_for_node (blender::bke::path_templates::VariableMap &variables, const bNode &owning_node)
static int	format_int_to_string (const FormatSpecifier &format, const int64_t integer_value, char r_output_string[FORMAT_BUFFER_SIZE])
static int	format_float_to_string (const FormatSpecifier &format, const double float_value, char r_output_string[FORMAT_BUFFER_SIZE])
static FormatSpecifier	parse_format_specifier (blender::StringRef format_specifier)
static std::optional< Token >	next_token (blender::StringRef path, const int from_char)
static blender::Vector< Token >	parse_template (blender::StringRef path)
static std::optional< Error >	token_to_syntax_error (const Token &token)
bool	BKE_path_contains_template_syntax (blender::StringRef path)
static blender::Vector< Error >	eval_template (char *out_path, const int out_path_maxncpy, blender::StringRef in_path, const VariableMap &template_variables)
blender::Vector< Error >	BKE_path_validate_template (blender::StringRef path, const blender::bke::path_templates::VariableMap &template_variables)
blender::Vector< Error >	BKE_path_apply_template (char *path, int path_maxncpy, const VariableMap &template_variables)
std::string	BKE_path_template_error_to_string (const Error &error, blender::StringRef path)
void	BKE_report_path_template_errors (ReportList *reports, const eReportType report_type, blender::StringRef path, blender::Span< Error > errors)
std::optional< std::string >	BKE_path_template_format_float (const blender::StringRef format_specifier, const double value)
std::optional< std::string >	BKE_path_template_format_int (const blender::StringRef format_specifier, const int64_t value)

Macro Definition Documentation

◆ FORMAT_BUFFER_SIZE

#define FORMAT_BUFFER_SIZE 512

Definition at line 338 of file path_templates.cc.

Referenced by BKE_path_template_format_float(), BKE_path_template_format_int(), eval_template(), format_float_to_string(), and format_int_to_string().

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< 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< 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< 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().

◆ eval_template()

blender::Vector< Error > eval_template	(	char *	out_path,
		const int	out_path_maxncpy,
		blender::StringRef	in_path,
		const VariableMap &	template_variables )

static

Evaluates the path template in in_path and writes the result to out_path if provided.

Parameters

out_path	buffer to write the evaluated path to. May be null, in which case writing is skipped, and this function just acts to validate the templating in the path.
out_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 out_path.
template_variables	map of variables and their values to use during template substitution.

Returns: An empty vector on success, or a vector of templating errors on failure. Note that even if there are errors, out_path may get modified, and it should be treated as bogus data in that case.

Definition at line 834 of file path_templates.cc.

References blender::Vector< T, InlineBufferCapacity, Allocator >::append(), BLI_assert_msg, BLI_path_make_safe_filename(), BLI_string_replace_range(), blender::StringRefBase::copy_bytes_truncated(), error(), FORMAT_BUFFER_SIZE, format_float_to_string(), format_int_to_string(), blender::bke::path_templates::FORMAT_SPECIFIER, blender::bke::path_templates::VariableMap::get_filepath(), blender::bke::path_templates::VariableMap::get_float(), blender::bke::path_templates::VariableMap::get_integer(), blender::bke::path_templates::VariableMap::get_string(), blender::Vector< T, InlineBufferCapacity, Allocator >::is_empty(), parse_template(), STRNCPY(), token_to_syntax_error(), and blender::bke::path_templates::UNKNOWN_VARIABLE.

Referenced by BKE_path_apply_template(), and BKE_path_validate_template().

◆ format_float_to_string()

int format_float_to_string	(	const FormatSpecifier &	format,
		const double	float_value,
		char	r_output_string[FORMAT_BUFFER_SIZE] )

static

Format a floating point number into a string, according to format.

Note: if format is not valid for floating point numbers, the resulting string will be empty.

Returns: length of the produced string. Zero indicates an error

Definition at line 504 of file path_templates.cc.

References BLI_assert, BLI_assert_msg, FORMAT_BUFFER_SIZE, and format_int_to_string().

Referenced by BKE_path_template_format_float(), and eval_template().

◆ format_int_to_string()

int format_int_to_string	(	const FormatSpecifier &	format,
		const int64_t	integer_value,
		char	r_output_string[FORMAT_BUFFER_SIZE] )

static

Format an integer into a string, according to format.

Note: if format is not valid for integers, the resulting string will be empty.

Returns: length of the produced string. Zero indicates an error.

Definition at line 420 of file path_templates.cc.

References BLI_assert, BLI_assert_msg, FORMAT_BUFFER_SIZE, and i.

Referenced by BKE_path_template_format_int(), eval_template(), and format_float_to_string().

◆ next_token()

std::optional< Token > next_token	(	blender::StringRef	path,
		const int	from_char )

static

Find and parse the next valid token in path starting from index from_char.

Parameters

path	The path string to parse.
from_char	The char index to start from.

Returns: The parsed token information, or #std::nullopt if no token is found in path.

Definition at line 648 of file path_templates.cc.

References blender::IndexRange::from_begin_end(), parse_format_specifier(), blender::StringRefBase::size(), and blender::StringRefBase::substr().

Referenced by parse_template().

◆ parse_format_specifier()

FormatSpecifier parse_format_specifier ( blender::StringRef format_specifier )

static

Parse the "format specifier" part of a variable expression.

The format specifier is e.g. the "##.###" in "{name:##.###}". The specifier string should be passed alone (just the "##.###"), without the rest of the variable expression.

Definition at line 590 of file path_templates.cc.

References blender::StringRefBase::find_first_not_of(), blender::StringRefBase::find_first_of(), blender::StringRefBase::find_last_of(), blender::StringRefBase::is_empty(), left, blender::StringRefBase::size(), and blender::StringRefBase::substr().

Referenced by BKE_path_template_format_float(), BKE_path_template_format_int(), and next_token().