Functions and classes for applying templates with variable expressions to 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_scene_types.h"

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)
blender::bke::path_templates::VariableMap	BKE_build_template_variables_for_render_path (const RenderData *render_data)
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)
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 applying templates with variable expressions to filepaths.

Definition in file BKE_path_templates.hh.

Function Documentation

◆ 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 115 of file path_templates.cc.

References BKE_build_template_variables_for_render_path(), BLI_assert_msg, BLI_assert_unreachable, C, CTX_data_scene(), GS, ID_SCE, PROP_PATH_SUPPORTS_TEMPLATES, PROP_VARIABLES_NONE, PROP_VARIABLES_RENDER_OUTPUT, ptr, Scene::r, RNA_property_flag(), and RNA_property_path_template_type().

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

◆ BKE_build_template_variables_for_render_path()

blender::bke::path_templates::VariableMap BKE_build_template_variables_for_render_path ( const RenderData * render_data )

Build a template variable map for render output paths.

All parameters are allowed to be null, in which case the variables derived from those parameters will simply not be included.

This is typically used to create the variables passed to BKE_path_apply_template().

Parameters

blend_file_path full path to the blend file, including the file name. Typically you should fetch this with ID_BLEND_PATH(), but there are exceptions. The key thing is that this should be the path to the relevant blend file for the context that the variables are going to be used in. For example, if the context is a linked ID then this path should (very likely) be the path to that ID's library blend file, not the currently opened one.

render_data used for output resolution and fps. 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(); BLI_path_abs()

Definition at line 175 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_main_blendfile_path_from_global(), BKE_render_resolution(), BLI_path_basename(), BLI_path_extension_or_end(), DATA_, RenderData::frs_sec, and RenderData::frs_sec_base.

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

◆ 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 693 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 )

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_max_length 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. */ blender::Vector<blender::bke::path_templates::Error> BKE_path_apply_template( char *path, int path_max_length, const blender::bke::path_templates::VariableMap &template_variables); /** Produces a human-readable error message for the given template error.

Definition at line 851 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(), 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 892 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 904 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 827 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 877 of file path_templates.cc.

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

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

Classes

Namespaces

Enumerations

Functions

Detailed Description

Function Documentation

◆ BKE_build_template_variables_for_prop()

◆ BKE_build_template_variables_for_render_path()

◆ BKE_path_contains_template_syntax()

◆ BKE_path_template_error_to_string()

◆ BKE_path_template_format_float()

◆ BKE_path_template_format_int()

◆ BKE_path_validate_template()

◆ BKE_report_path_template_errors()