Changes done for v1.1.4.

Author: Senthil Nathan

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changes
 
+## v1.1.4
+* Jan/07/2023
+* Added a new function get_tuple_schema_and_attribute_info to fetch the tuple schema literal string along with the tuple attribute information map with fully qualified tuple attribute names and their SPL type names as key/value pairs in that map. 
+
 ## v1.1.3
 * Oct/16/2021
 * Enhanced the compare_tuple_attributes function to give back two lists i.e. one with the attribute names that have matching values and another with the attribute names that have differing values.

README.md

@@ -184,6 +184,39 @@ if(error == 0) {
 // It is a void function that returns nothing.
 ```
 
+**get_tuple_schema_and_attribute_info** is another C++ native function provided via this toolkit. This function fetches the tuple schema literal string along with the tuple attribute information as a map with fully qualified tuple attribute names and their SPL type names as key/value pairs in that map.
+
+```
+// This namespace usage declaration is needed at the top of an application.
+use com.ibm.streamsx.eval_predicate::*;
+
+mutable rstring tupleSchema = "";
+mutable map<rstring, rstring> attributeInfo = {};
+					
+get_tuple_schema_and_attribute_info(myTuple1, tupleSchema,
+   attributeInfo, error, $EVAL_PREDICATE_TRACING);
+
+if(error == 0) {
+   printStringLn("Get tuple schema function returned successfully. " +
+      ", tupleSchema = " + tupleSchema + 
+      ", attributeInfo = " + (rstring)attributeInfo);
+   } else {
+      printStringLn("Get tuple schema function returned an error. Error=" + (rstring)error);
+   }
+
+// Following is the usage description for the get_tuple_schema_and_attribute_info function.
+// Arg1: Your tuple
+// Arg2: A mutable variable of rstring type in which the
+//       tuple schema literal string will be returned.
+// Arg3: A mutable variable of map<string, rstring> type in which the
+//       tuple attribute information will be returned. Map keys will
+//       carry the fully qualified tuple attribute names and the
+//       map values will carry the SPL type name of the attributes.
+// Arg4: A mutable int32 variable to receive non-zero error code if any.
+// Arg5: A boolean value to enable debug tracing inside this function.
+// It is a void function that returns nothing.
+```
+
 ## Design considerations
 This toolkit came into existence for a specific need with which a large enterprise customer approached the author of this toolkit. There is already a built-in function named *evalPredicate* that is available in the official IBM Streams product. However, that function has certain limitations. To fill that gap, this toolkit with its own **eval_predicate** function is being made available freely via the publicly accessible IBMStreams GitHub. The **eval_predicate** function from this toolkit differs from the *evalPredicate* built-in function in the IBM Streams product in the following ways.
 

com.ibm.streamsx.eval_predicate/EvalPredicateExample.spl

@@ -1,14 +1,14 @@
 /*
 ==============================================
 # Licensed Materials - Property of IBM
-# Copyright IBM Corp. 2021
+# Copyright IBM Corp. 2021, 2023
 ==============================================
 */
 
 /*
 ==================================================================
 First created on: Mar/05/2021
-Last modified on: Oct/16/2021
+Last modified on: Jan/07/2023
 
 This is an example application that shows how to use the
 eval_predicate function to evaluate an SPL expression a.k.a
@@ -109,6 +109,12 @@ attribute names that differ in their values. In this example,
 you can search for compare_tuple_attributes to see a few
 test cases on that topic.
 
+Another feature available in the eval_predicate toolkit is to
+get the schema literal string of a given tuple along with the 
+fully qualified attribute names and their SPL type names.
+In this example, you can search for get_tuple_schema_and_attribute_info
+to see a few test cases on that topic.
+
 How can you use this new eval_predicate function?
 -------------------------------------------------
 Any other application that wants to use this function must
@@ -489,6 +495,30 @@ composite EvalPredicateExample {
 					} else {
 						printStringLn("Testcase 2.8: Compare tuple attributes function returned an error. Error=" + (rstring)error);
 					}
+
+					// 2.9
+					// Get tuple schema literal string along with its attribute information.
+					//
+					mutable rstring tupleSchema = "";
+					mutable map<rstring, rstring> attributeInfo = {};
+					
+					// Call the specific function that can do this for us.
+					// It will return the tuple schema literal string in the 
+					// mutable string variable passed as a second function argument.
+					// It will return the tuple attribute information in the
+					// mutable map variable passed as a third function argument.
+					// This map's keys will hold the fully qualified tuple attribute names.
+					// This map's values will hold the SPL type names of the tuple attribute names.
+					get_tuple_schema_and_attribute_info(myTuple1, tupleSchema,
+						attributeInfo, error, $EVAL_PREDICATE_TRACING);
+
+					if(error == 0) {
+						printStringLn("Testcase 2.9: Get tuple schema function returned successfully. " +
+							", tupleSchema = " + tupleSchema + 
+							", attributeInfo = " + (rstring)attributeInfo);
+					} else {
+						printStringLn("Testcase 2.9: Get tuple schema function returned an error. Error=" + (rstring)error);
+					}					
 
 					// ============== TESTCASE GROUP 3 ============== 
 					mutable City_t myCity = {};

com.ibm.streamsx.eval_predicate/FunctionalTests.spl

@@ -1,14 +1,14 @@
 /*
 ==============================================
 # Licensed Materials - Property of IBM
-# Copyright IBM Corp. 2021
+# Copyright IBM Corp. 2021, 2023
 ==============================================
 */
 
 /*
 ==================================================================
 First created on: Mar/28/2021
-Last modified on: Oct/16/2021
+Last modified on: Jan/07/2023
 
 This application is meant for doing several hundred 
 functional tests to provide as much coverage as possible to 
@@ -47,6 +47,12 @@ attribute names that differ in their values. In this example,
 you can search for compare_tuple_attributes to see a few
 test cases on that topic.
 
+Another feature available in the eval_predicate toolkit is to
+get the schema literal string of a given tuple along with the 
+fully qualified attribute names and their SPL type names.
+In this example, you can search for get_tuple_schema_and_attribute_info
+to see a few test cases on that topic.
+
 How can you build this test application?
 ----------------------------------------
 1) If you are a command line person, you can use the
@@ -9146,6 +9152,30 @@ composite FunctionalTests {
 						printStringLn("Testcase C1.50: Compare tuple attributes function returned an error. Error=" + (rstring)error);
 					}
 
+					// C1.51
+					// Get tuple schema literal string along with its attribute information.
+					//
+					mutable rstring tupleSchema = "";
+					mutable map<rstring, rstring> attributeInfo = {};
+					
+					// Call the specific function that can do this for us.
+					// It will return the tuple schema literal string in the 
+					// mutable string variable passed as a second function argument.
+					// It will return the tuple attribute information in the
+					// mutable map variable passed as a third function argument.
+					// This map's keys will hold the fully qualified tuple attribute names.
+					// This map's values will hold the SPL type names of the tuple attribute names.
+					get_tuple_schema_and_attribute_info(myTuple1, tupleSchema,
+						attributeInfo, error, $EVAL_PREDICATE_TRACING);
+
+					if(error == 0) {
+						printStringLn("Testcase C1.51: Get tuple schema function returned successfully. " +
+							", tupleSchema = " + tupleSchema + 
+							", attributeInfo = " + (rstring)attributeInfo);
+					} else {
+						printStringLn("Testcase C1.51: Get tuple schema function returned an error. Error=" + (rstring)error);
+					}					
+										
 					// -------------------------
 
 					// Let us add below a few test cases for the

com.ibm.streamsx.eval_predicate/native.function/function.xml

@@ -42,6 +42,19 @@ It compares the attribute values of two tuples that are made of the same schema
 		</description>
         <prototype>&lt;tuple T1> public void compare_tuple_attributes(T1 myTuple1, T1 myTuple2, mutable list&lt;rstring&gt; matchingAttributes, mutable list&lt;rstring&gt; differingAttributes, mutable int32 error, boolean trace)</prototype>
       </function>
+      
+      <function>
+        <description>
+It fetches the schema literal string of a given tuple along with the information about all of its attributes.
+@param myTuple A user defined tuple for which schema and attribute information will be obtained. Type: Tuple
+@param schema A mutable variable in which the complete schema literal string of a given tuple will be returned. Type: rstring
+@param attributeInfo A mutable map variable in which information about the tuple attributes will be returned. Map key will carry the fully qualified name of a given tuple attribute and map value will carry the SPL type name of that attribute. Type: map&lt;rstring, rstring&gt;
+@param error A mutable variable that will contain a non-zero error code if an error occurs. Type: int32
+@param trace A boolean value to enable tracing inside this function. Type: boolean
+@return It returns nothing.  Type: void
+	  </description>
+	  <prototype>&lt;tuple T1> public void get_tuple_schema_and_attribute_info(T1 myTuple, mutable rstring schema, mutable map&lt;rstring, rstring&gt; attributeInfo, mutable int32 error, boolean trace)</prototype>
+	</function>
     </functions>
 
     <dependencies>

impl/include/eval_predicate.h

@@ -1,13 +1,14 @@
 /*
 ==============================================
 # Licensed Materials - Property of IBM
-# Copyright IBM Corp. 2021
+# Copyright IBM Corp. 2021, 2023
 ==============================================
 */
 /*
 ============================================================
 First created on: Mar/05/2021
-Last modified on: Oct/16/2021
+Last modified on: Jan/07/2023
+Author(s): Senthil Nathan (sen@us.ibm.com)
 
 This toolkit's public GitHub URL:
 https://github.com/IBMStreams/streamsx.eval_predicate
@@ -377,7 +378,7 @@ namespace eval_predicate_functions {
 			// subexpressions present in a fully validated expression.
 			// It is important to understand the structure of this map which
 			// is explained in great detail throughout this file.
-			// One such explanation is available around line 643 of this file.
+			// One such explanation is available around line 663 of this file.
 			SPL::map<rstring, SPL::list<rstring> > subexpressionsMap;
 
 			// This list provides the subexpression map keys in sorted order.
@@ -536,6 +537,13 @@ namespace eval_predicate_functions {
     	SPL::list<rstring> & matchingAttributes,
 		SPL::list<rstring> & differingAttributes,
 		int32 & error, boolean trace);
+    // This method fetches the tuple schema literal string and the
+    // tuple attribute information map with fully qualified tuple
+    // attribute names and values as key/value pairs.
+    template<class T1>
+    void get_tuple_schema_and_attribute_info(T1 const & myTuple,
+		rstring & schema, SPL::map<rstring, rstring> & attributeInfo,
+		int32 & error, boolean trace);
     // ====================================================================
 
 	// Evaluate a given expression.
@@ -562,7 +570,7 @@ namespace eval_predicate_functions {
     		return(false);
     	}
 
-    	// Get the string literal of a given tuple.
+    	// Get the schema literal string of a given tuple.
 		// Example of myTuple's schema:
 		// myTuple=tuple<rstring name,tuple<tuple<tuple<float32 latitude,float32 longitude> geo,tuple<rstring state,rstring zipCode,map<rstring,rstring> officials,list<rstring> businesses> info> location,tuple<float32 temperature,float32 humidity> weather> details,tuple<int32 population,int32 numberOfSchools,int32 numberOfHospitals> stats,int32 rank,list<int32> roadwayNumbers,map<rstring,int32> housingNumbers>
 		//
@@ -652,7 +660,6 @@ namespace eval_predicate_functions {
 			// user provided tuple and display its attribute names and values.
 			traceTupleAtttributeNamesAndValues(myTuple, tupleAttributesMap, trace);
 
-			// Note: The space below between > > is a must. Otherwise, compiler will give an error.
 			// This map's key is a subexpression id.
 			// Subexpression id will go something like this:
 			// 1.1, 1.2, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 4.1, 4.2, 4.3, 5.1
@@ -701,6 +708,7 @@ namespace eval_predicate_functions {
 			// Intra subexpression logical operator - When N/A, it will have an empty string.
 			// ...   - The sequence above repeats for this subexpression.
 			//
+			// Note: The space below between > > is a must. Otherwise, compiler will give an error.
 			SPL::map<rstring, SPL::list<rstring> > subexpressionsMap;
 			// Store the logical operators within the nested sub-expressions.
 			// Key for this map will be id of the nested subexpression that
@@ -798,7 +806,7 @@ namespace eval_predicate_functions {
     // ====================================================================
 
     // ====================================================================
-    // This function receives a Tuple as input and returns a tuple literal string.
+    // This function receives a Tuple as input and returns a tuple schema literal string.
     // We will later parse the tuple literal string to create a map of all the
     // attributes in a user given tuple.
 	// Example of myTuple's schema that will be returned by this function:
@@ -10674,6 +10682,50 @@ namespace eval_predicate_functions {
 			}
 		} // End of for loop.
 	} // End of compare_tuple_attributes
+
+    // This method fetches the tuple schema literal string and the
+    // tuple attribute information map with fully qualified tuple
+    // attribute names and their SPL type names as key/value
+    // pairs in that map.
+	//
+	// Get the tuple schema literal string along with the tuple attribute information.
+	// Arg1: Your tuple
+	// Arg2: A mutable variable of rstring type in which the
+	//       tuple schema literal string will be returned.
+	// Arg3: A mutable variable of map<string, rstring> type in which the
+	//       tuple attribute information will be returned. Map keys will
+	//       carry the fully qualified tuple attribute names and the
+	//       map values will carry the SPL type name of the attributes.
+	// Arg4: A mutable int32 variable to receive non-zero error code if any.
+	// Arg5: A boolean value to enable debug tracing inside this function.
+	// It is a void method that returns nothing.
+	//
+    template<class T1>
+    void get_tuple_schema_and_attribute_info(T1 const & myTuple,
+		rstring & schema, SPL::map<rstring, rstring> & attributeInfo,
+		int32 & error, boolean trace) {
+		error = ALL_CLEAR;
+
+		// Get the schema literal string of a given tuple.
+		// Example of myTuple's schema:
+		// myTuple=tuple<rstring name,tuple<tuple<tuple<float32 latitude,float32 longitude> geo,tuple<rstring state,rstring zipCode,map<rstring,rstring> officials,list<rstring> businesses> info> location,tuple<float32 temperature,float32 humidity> weather> details,tuple<int32 population,int32 numberOfSchools,int32 numberOfHospitals> stats,int32 rank,list<int32> roadwayNumbers,map<rstring,int32> housingNumbers>
+		//
+		schema = "";
+		schema = getSPLTypeName(myTuple, trace);
+
+		if(schema == "") {
+			// This should never occur. If it happens in
+			// extremely rare cases, we have to investigate the
+			// tuple literal schema generation function.
+			error = TUPLE_LITERAL_SCHEMA_GENERATION_ERROR;
+			return;
+		}
+
+		// Let us parse the individual attributes of the given tuple and
+		// store them in a user provided map.
+		Functions::Collections::clearM(attributeInfo);
+		parseTupleAttributes(schema, attributeInfo, error, trace);
+    } // End of get_tuple_schema_and_attribute_info
     // ====================================================================
 } // End of namespace eval_predicate_functions
 // ====================================================================
@@ -10694,8 +10746,8 @@ last hurrah in my technical contributions to the incomparable IBM Streams.
 I will be thrilled to get another chance to associate with this wonderful
 product if it finds a new home for further development either inside or
 outside of IBM. Until then, I will continue to reminisce this unforgettable
-journey made possible by the passionate researchers, engineers and managers
-who are all simply world class.
+journey made possible by the passionate researchers, engineers, managers and
+customers who are all simply world class.
 
 It will take many more years for some other company or an open-source group to
 roll out a full-featured product that can be a true match for IBM Streams.

info.xml

@@ -4,7 +4,7 @@
  <info:identity>
    <info:name>eval_predicate</info:name>
    <info:description>Toolkit for user defined rule (expression) processing</info:description>
-   <info:version>1.1.3</info:version>
+   <info:version>1.1.4</info:version>
    <info:requiredProductVersion>4.2.1.6</info:requiredProductVersion>
  </info:identity>
  <info:dependencies/>