Merge pull request #5825 from johnhaddon/tweakPlugSubstitutions

TweakPlug : Support {source} token when replacing strings

Changes.md

@@ -15,6 +15,9 @@ Improvements
   - Added support for `uv.tangent` and `uv.tangent_sign` primitive variables to assist in rendering with normal maps (#5269).
 - AttributeQuery, PrimitiveVariableQuery, ContextQuery, OptionQuery, ShaderQuery : Added support for querying arrays of length 1 as their equivalent scalar types.
 - CodeWidget : Added <kbd>Ctrl</kbd>+<kbd>L</kbd> shortcut for selecting all text on the current line.
+- AttributeTweaks, CameraTweaks, ShaderTweaks, OptionTweaks, PrimitiveVariableTweaks :
+  - Added support for a `{source}` token which is substituted with the original value when tweaking a string in `Replace` mode.
+  - Added tooltips documenting the tweak modes.
 
 Fixes
 -----
@@ -28,6 +31,7 @@ API
 - PlugAlgo : `setValueFromData()` and `canSetValueFromData()` now support conversion of arrays of length 1 to their equivalent scalar types.
 - BoxPlug : Added Python bindings for `ValueType`, `PointType` and `ChildType` type aliases.
 - RenderPassEditor : Added `deregisterColumn()` method.
+- DocumentationAlgo : Added table and strikethrough support to `markdownToHTML()`.
 
 Build
 -----

include/Gaffer/TweakPlug.h

@@ -148,6 +148,8 @@ class GAFFER_API TweakPlug : public Gaffer::ValuePlug
 			const std::string &tweakName
 		) const;
 
+		void applyReplaceTweak( const IECore::Data *sourceData, IECore::Data *tweakData ) const;
+
 		static const char *modeToString( Gaffer::TweakPlug::Mode mode );
 
 };

include/Gaffer/TweakPlug.inl

@@ -149,6 +149,10 @@ bool TweakPlug::applyTweak(
 	{
 		applyListTweak( currentValue, newData.get(), newData.get(), mode, name );
 	}
+	else if( mode == TweakPlug::Replace )
+	{
+		applyReplaceTweak( currentValue, newData.get() );
+	}
 
 	if( mode != Gaffer::TweakPlug::CreateIfMissing )
 	{

python/GafferSceneUI/AttributeTweaksUI.py

@@ -99,6 +99,7 @@
 
 			"tweakPlugValueWidget:allowCreate", True,
 			"tweakPlugValueWidget:allowRemove", True,
+			"tweakPlugValueWidget:propertyType", "attribute",
 
 		],
 

python/GafferSceneUI/CameraTweaksUI.py

@@ -91,6 +91,7 @@
 
 			"tweakPlugValueWidget:allowRemove", True,
 			"tweakPlugValueWidget:allowCreate", True,
+			"tweakPlugValueWidget:propertyType", "parameter",
 
 		],
 

python/GafferSceneUI/OptionTweaksUI.py

@@ -85,6 +85,7 @@
 		"tweaks.*" : [
 
 			"tweakPlugValueWidget:allowCreate", True,
+			"tweakPlugValueWidget:propertyType", "option",
 
 		],
 

python/GafferSceneUI/ShaderTweaksUI.py

@@ -128,6 +128,7 @@
 			"noduleLayout:visible", False, # Can be shown individually using PlugAdder above
 			"tweakPlugValueWidget:allowCreate", True,
 			"tweakPlugValueWidget:allowRemove", True,
+			"tweakPlugValueWidget:propertyType", "parameter",
 
 		],
 

python/GafferTest/TweakPlugTest.py

@@ -451,5 +451,35 @@ def testStringListOperations( self ) :
 			self.assertTrue( plug.applyTweak( data ) )
 			self.assertEqual( data["v"], IECore.StringData( result ) )
 
+	def testStringSubstitutions( self ) :
+
+		for source, tweakMode, tweakValue, result in [
+			# Create modes don't support substitutions.
+			( None, Gaffer.TweakPlug.Mode.Create, "{source}", "{source}" ),
+			( None, Gaffer.TweakPlug.Mode.CreateIfMissing, "{source}", "{source}" ),
+			( IECore.StringData( "a" ), Gaffer.TweakPlug.Mode.Create, "{source}", "{source}" ),
+			( IECore.StringData( "a" ), Gaffer.TweakPlug.Mode.CreateIfMissing, "{source}", "a" ),
+			# Neither do list modes.
+			( IECore.StringData( "a" ), Gaffer.TweakPlug.Mode.ListAppend, "{source}", "a {source}" ),
+			( IECore.StringData( "a" ), Gaffer.TweakPlug.Mode.ListPrepend, "{source}", "{source} a" ),
+			# Replace mode does support substitutions.
+			( IECore.StringData( "a" ), Gaffer.TweakPlug.Mode.Replace, "{source}", "a" ),
+			( IECore.StringData( "a" ), Gaffer.TweakPlug.Mode.Replace, "prefix{source}", "prefixa" ),
+			( IECore.StringData( "a" ), Gaffer.TweakPlug.Mode.Replace, "{source}suffix", "asuffix" ),
+			( IECore.StringData( "a" ), Gaffer.TweakPlug.Mode.Replace, "{source} {source}", "a a" ),
+			# And works with InternedStringData too.
+			( IECore.InternedStringData( "a" ), Gaffer.TweakPlug.Mode.Replace, "{source}", "a" ),
+			( IECore.InternedStringData( "a" ), Gaffer.TweakPlug.Mode.Replace, "prefix{source}", "prefixa" ),
+			( IECore.InternedStringData( "a" ), Gaffer.TweakPlug.Mode.Replace, "{source}suffix", "asuffix" ),
+			( IECore.InternedStringData( "a" ), Gaffer.TweakPlug.Mode.Replace, "{source} {source}", "a a" ),
+		] :
+			with self.subTest( source = source, tweakMode = tweakMode, tweakValue = tweakValue ) :
+				plug = Gaffer.TweakPlug( "v", tweakValue, tweakMode )
+				data = IECore.CompoundData( { "v" : source } )
+				self.assertTrue( plug.applyTweak( data ) )
+				if source is not None :
+					self.assertIs( type( data["v"] ), type( source ) )
+				self.assertEqual( data["v"].value, result )
+
 if __name__ == "__main__":
 	unittest.main()

python/GafferUI/ContextVariableTweaksUI.py

@@ -85,6 +85,7 @@
 		"tweaks.*" : [
 
 			"tweakPlugValueWidget:allowCreate", True,
+			"tweakPlugValueWidget:propertyType", "context variable",
 
 		]
 

python/GafferUI/DocumentationAlgo.py

@@ -206,8 +206,22 @@ def markdownToHTML( markdown ) :
 	if cmark is None :
 		return markdown
 
+	parser = cmark.cmark_parser_new( cmark.CMARK_OPT_DEFAULT )
+	for extension in [ "table", "strikethrough" ] :
+		cmark.cmark_parser_attach_syntax_extension(
+			parser, cmark.cmark_find_syntax_extension( bytes( extension, "UTF-8" ) )
+		)
+
 	markdown = markdown.encode( "UTF-8" )
-	return cmark.cmark_markdown_to_html( markdown, len( markdown ), cmark.CMARK_OPT_UNSAFE ).decode( "UTF-8" )
+	cmark.cmark_parser_feed( parser, markdown, len( markdown ) )
+	document = cmark.cmark_parser_finish( parser )
+
+	result = cmark.cmark_render_html( document, cmark.CMARK_OPT_UNSAFE, cmark.cmark_parser_get_syntax_extensions( parser ) ).decode( "UTF-8")
+
+	cmark.cmark_parser_free( parser )
+	cmark.cmark_node_free( document )
+
+	return result
 
 def __nodeDocumentation( node ) :
 
@@ -301,30 +315,62 @@ def __tocString() :
 	return tocString
 
 __cmarkDLL = ""
+__cmarkExtensionsDLL = None
 def __cmark() :
 
 	global __cmarkDLL
+	global __cmarkExtensionsDLL
 	if __cmarkDLL != "" :
 		return __cmarkDLL
 
 	sys = platform.system()
 
 	if sys == "Darwin" :
-		libName = "libcmark-gfm.dylib"
+		prefix = "lib"
+		suffix = ".dylib"
 	elif sys == "Windows" :
-		libName = "cmark-gfm.dll"
+		prefix = ""
+		suffix = ".dll"
 	else :
-		libName = "libcmark-gfm.so"
+		prefix = "lib"
+		suffix = ".so"
 
 	try :
-		__cmarkDLL = ctypes.CDLL( libName )
+		__cmarkDLL = ctypes.CDLL( f"{prefix}cmark-gfm{suffix}" )
+		__cmarkExtensionsDLL = ctypes.CDLL( f"{prefix}cmark-gfm-extensions{suffix}" )
 	except :
 		__cmarkDLL = None
 		return __cmarkDLL
 
+	__cmarkExtensionsDLL.cmark_gfm_core_extensions_ensure_registered()
+
+	__cmarkDLL.cmark_parser_new.restype = ctypes.c_void_p
+	__cmarkDLL.cmark_parser_new.argtypes = [ctypes.c_int]
+
+	__cmarkDLL.cmark_parser_attach_syntax_extension.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
+
+	__cmarkDLL.cmark_parser_get_syntax_extensions.restype = ctypes.c_void_p
+	__cmarkDLL.cmark_parser_get_syntax_extensions.argtypes = [ctypes.c_void_p]
+
+	__cmarkDLL.cmark_parser_feed.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_int]
+
+	__cmarkDLL.cmark_parser_finish.restype = ctypes.c_void_p
+	__cmarkDLL.cmark_parser_finish.argtypes = [ctypes.c_void_p]
+
+	__cmarkDLL.cmark_parser_free.argtypes = [ctypes.c_void_p]
+
+	__cmarkDLL.cmark_find_syntax_extension.restype = ctypes.c_void_p
+	__cmarkDLL.cmark_find_syntax_extension.argtypes = [ctypes.c_char_p]
+
+	__cmarkDLL.cmark_node_free.argtypes = [ctypes.c_void_p]
+
+	__cmarkDLL.cmark_render_html.restype = ctypes.c_char_p
+	__cmarkDLL.cmark_render_html.argtypes = [ctypes.c_void_p, ctypes.c_int, ctypes.c_void_p]
+
 	__cmarkDLL.cmark_markdown_to_html.restype = ctypes.c_char_p
 	__cmarkDLL.cmark_markdown_to_html.argtypes = [ctypes.c_char_p, ctypes.c_long, ctypes.c_long]
 
+	__cmarkDLL.CMARK_OPT_DEFAULT = 0
 	__cmarkDLL.CMARK_OPT_UNSAFE = 1 << 17
 
 	return __cmarkDLL

python/GafferUI/TweakPlugValueWidget.py

@@ -34,6 +34,7 @@
 #
 ##########################################################################
 
+import inspect
 import functools
 import re
 
@@ -150,10 +151,12 @@ def __childPlugs( plugs, childName ) :
 
 Gaffer.Metadata.registerValue( Gaffer.TweakPlug, "deletable", lambda plug : plug.getFlags( Gaffer.Plug.Flags.Dynamic ) )
 
-Gaffer.Metadata.registerValue(
-	Gaffer.TweakPlug, "name",
-	"description", "The name of the parameter to apply the tweak to."
-)
+def __nameDescription( plug ) :
+
+	property = Gaffer.Metadata.value( plug.parent(), "tweakPlugValueWidget:propertyType" ) or "property"
+	return f"The name of the {property} to apply the tweak to."
+
+Gaffer.Metadata.registerValue( Gaffer.TweakPlug, "name", "description", __nameDescription )
 
 Gaffer.Metadata.registerValue(
 	Gaffer.TweakPlug, "mode",
@@ -213,6 +216,97 @@ def __validModes( plug ) :
 	"presetValues", lambda plug : IECore.IntVectorData( [ int( x ) for x in __validModes( plug ) ] )
 )
 
+__modeDescriptions = {
+	Gaffer.TweakPlug.Mode.Replace :
+	"""
+	Replaces an existing {property}. Errors if the {property} doesn't exist,
+	unless `ignoreMissing` is set, in which case the tweak is skipped.
+
+	When replacing a string {property}, the new value may contain a `{{source}}`
+	token, which will be substituted with the original value.
+	""",
+	Gaffer.TweakPlug.Mode.Add :
+	"""
+	Adds to an existing numeric {property}. Errors if the {property} doesn't exist,
+	unless `ignoreMissing` is set, in which case the tweak is skipped.
+	""",
+	Gaffer.TweakPlug.Mode.Subtract :
+	"""
+	Subtracts from an existing numeric {property}. Errors if the {property} doesn't exist,
+	unless `ignoreMissing` is set, in which case the tweak is skipped.
+	""",
+	Gaffer.TweakPlug.Mode.Multiply :
+	"""
+	Multiplies an existing numeric {property}. Errors if the {property} doesn't exist,
+	unless `ignoreMissing` is set, in which case the tweak is skipped.
+	""",
+	Gaffer.TweakPlug.Mode.Remove :
+	"""
+	Removes an existing {property}. Does not error if the property doesn't exist.
+	""",
+	Gaffer.TweakPlug.Mode.Create :
+	"""
+	Sets the value of {a} {property}, creating it if it doesn't exist yet.
+	""",
+	Gaffer.TweakPlug.Mode.Min :
+	"""
+	Sets an existing numeric {property} to the minimum of its current value and
+	the tweak value. Errors if the {property} doesn't exist, unless
+	`ignoreMissing` is set, in which case the tweak is skipped.
+	""",
+	Gaffer.TweakPlug.Mode.Max :
+	"""
+	Sets an existing numeric {property} to the maximum of its current value and
+	the tweak value. Errors if the {property} doesn't exist, unless
+	`ignoreMissing` is set, in which case the tweak is skipped.
+	""",
+	Gaffer.TweakPlug.Mode.ListAppend :
+	"""
+	Appends new values on the end of a list of values. Any values already
+	in the list are moved to the end, so that duplicates are not created.
+	If the {property} doesn't exist yet, it is created.
+	""",
+	Gaffer.TweakPlug.Mode.ListPrepend :
+	"""
+	Appends new values at the front of a list of values. Any values already
+	in the list are moved to the front, so that duplicates are not created.
+	If the {property} doesn't exist yet, it is created.
+	""",
+	Gaffer.TweakPlug.Mode.ListRemove :
+	"""
+	Removes values from an existing list. Does not error if the property doesn't exist.
+	""",
+	Gaffer.TweakPlug.Mode.CreateIfMissing :
+	"""
+	Like `Create`, but does nothing if the {property} already exists.
+	"""
+
+}
+
+def __modeDescription( plug ) :
+
+	property = Gaffer.Metadata.value( plug.parent(), "tweakPlugValueWidget:propertyType" ) or "property"
+
+	result =  "| Mode | Description |\n"
+	result += "| :--- | :---------- |\n"
+
+	for mode in __validModes( plug ) :
+		description = inspect.cleandoc( __modeDescriptions[mode] ).format(
+			property = property,
+			a = "an" if property[0] in "aeiou" else "a"
+		)
+		result += "| {} | {} |\n".format(
+			IECore.CamelCase.toSpaced( str( mode ) ),
+			description.replace( "\n", " " )
+		)
+
+	return result
+
+Gaffer.Metadata.registerValue(
+	Gaffer.TweakPlug, "mode",
+	"description", __modeDescription
+)
+
 def __noduleLabel( plug ) :
 
 	if not isinstance( plug, Gaffer.TweakPlug ) :

python/GafferUITest/DocumentationAlgoTest.py

@@ -34,6 +34,8 @@
 #
 ##########################################################################
 
+import inspect
+
 import GafferUI
 import GafferUITest
 
@@ -46,5 +48,21 @@ def testMarkdownToHTML( self ) :
 			"<h1>Heading</h1>\n"
 		)
 
+		self.assertIn(
+			"<table>",
+			GafferUI.DocumentationAlgo.markdownToHTML( inspect.cleandoc(
+				"""
+				Heading1 | Heading2
+				-------- | --------
+				Cell1    | Cell2
+				"""
+			) )
+		)
+
+		self.assertEqual(
+			GafferUI.DocumentationAlgo.markdownToHTML( "~text~" ),
+			"<p><del>text</del></p>\n",
+		)
+
 if __name__ == "__main__":
 	unittest.main()

src/Gaffer/TweakPlug.cpp

@@ -46,6 +46,7 @@
 #include "IECore/TypeTraits.h"
 
 #include "boost/algorithm/string/join.hpp"
+#include "boost/algorithm/string/replace.hpp"
 
 #include "fmt/format.h"
 
@@ -412,6 +413,21 @@ void TweakPlug::applyListTweak(
 	);
 }
 
+void TweakPlug::applyReplaceTweak( const IECore::Data *sourceData, IECore::Data *tweakData ) const
+{
+	if( auto stringData = IECore::runTimeCast<IECore::StringData>( tweakData ) )
+	{
+		boost::replace_all( stringData->writable(), "{source}", static_cast<const IECore::StringData *>( sourceData )->readable() );
+	}
+	else if( auto internedStringData = IECore::runTimeCast<IECore::InternedStringData>( tweakData ) )
+	{
+		internedStringData->writable() = boost::replace_all_copy(
+			internedStringData->readable().string(),
+			"{source}", static_cast<const IECore::InternedStringData *>( sourceData )->readable().string()
+		);
+	}
+}
+
 const char *TweakPlug::modeToString( Gaffer::TweakPlug::Mode mode )
 {
 	switch( mode )