1 files changed, 55 insertions, 0 deletions
diff --git a/indra/llcommon/llsdutil.h b/indra/llcommon/llsdutil.h
index 501600f1d9..0752f8aff1 100644
--- a/indra/llcommon/llsdutil.h
+++ b/indra/llcommon/llsdutil.h
@@ -104,6 +104,61 @@ BOOL compare_llsd_with_template(
 	const LLSD& template_llsd,
 	LLSD& resultant_llsd);
 
+/**
+ * Recursively determine whether a given LLSD data block "matches" another
+ * LLSD prototype. The returned string is empty() on success, non-empty() on
+ * mismatch.
+ *
+ * This function tests structure (types) rather than data values. It is
+ * intended for when a consumer expects an LLSD block with a particular
+ * structure, and must succinctly detect whether the arriving block is
+ * well-formed. For instance, a test of the form:
+ * @code
+ * if (! (data.has("request") && data.has("target") && data.has("modifier") ...))
+ * @endcode
+ * could instead be expressed by initializing a prototype LLSD map with the
+ * required keys and writing:
+ * @code
+ * if (! llsd_matches(prototype, data).empty())
+ * @endcode
+ *
+ * A non-empty return value is an error-message fragment intended to indicate
+ * to (English-speaking) developers where in the prototype structure the
+ * mismatch occurred.
+ *
+ * * If a slot in the prototype isUndefined(), then anything is valid at that
+ *   place in the real object. (Passing prototype == LLSD() matches anything
+ *   at all.)
+ * * An array in the prototype must match a data array at least that large.
+ *   (Additional entries in the data array are ignored.) Every isDefined()
+ *   entry in the prototype array must match the corresponding entry in the
+ *   data array.
+ * * A map in the prototype must match a map in the data. Every key in the
+ *   prototype map must match a corresponding key in the data map. (Additional
+ *   keys in the data map are ignored.) Every isDefined() value in the
+ *   prototype map must match the corresponding key's value in the data map.
+ * * Scalar values in the prototype are tested for @em type rather than value.
+ *   For instance, a String in the prototype matches any String at all. In
+ *   effect, storing an Integer at a particular place in the prototype asserts
+ *   that the caller intends to apply asInteger() to the corresponding slot in
+ *   the data.
+ * * A String in the prototype matches String, Boolean, Integer, Real, UUID,
+ *   Date and URI, because asString() applied to any of these produces a
+ *   meaningful result.
+ * * Similarly, a Boolean, Integer or Real in the prototype can match any of
+ *   Boolean, Integer or Real in the data -- or even String.
+ * * UUID matches UUID or String.
+ * * Date matches Date or String.
+ * * URI matches URI or String.
+ * * Binary in the prototype matches only Binary in the data.
+ *
+ * @TODO: when a Boolean, Integer or Real in the prototype matches a String in
+ * the data, we should examine the String @em value to ensure it can be
+ * meaningfully converted to the requested type. The same goes for UUID, Date
+ * and URI.
+ */
+std::string llsd_matches(const LLSD& prototype, const LLSD& data, const std::string& pfx="");
+
 // Simple function to copy data out of input & output iterators if
 // there is no need for casting.
 template<typename Input> LLSD llsd_copy_array(Input iter, Input end)