From 75f712a3052fe3f8b9c05afb2a61ae0a99af309b Mon Sep 17 00:00:00 2001
From: munja <allnbwe@gmail.com>
Date: Wed, 19 Jan 2022 10:55:52 +0100
Subject: [PATCH] chore(docs): assertscope

---
 base/mp_assertscope.sas                    | 21 ++++++-----
 tests/crossplatform/mp_stackdiffs.test.sas | 41 ++++++++++++++++++++++
 2 files changed, 53 insertions(+), 9 deletions(-)
 create mode 100644 tests/crossplatform/mp_stackdiffs.test.sas

diff --git a/base/mp_assertscope.sas b/base/mp_assertscope.sas
index 38d6a54..dd03519 100644
--- a/base/mp_assertscope.sas
+++ b/base/mp_assertscope.sas
@@ -1,18 +1,18 @@
 /**
   @file
   @brief Used to capture scope leakage of macro variables
-  @details A common 'difficult to detect' bug in macros is where a nested
-    macro over-writes variables in a higher level macro.
+  @details
 
-    This assertion takes a snapshot of the macro variables before and after
-    a macro invocation.  This makes it easy to detect whether any macro
-    variables were modified or changed.
+  A common 'difficult to detect' bug in macros is where a nested macro
+  over-writes variables in a higher level macro.
 
-    Currently, the macro only checks for global scope variables.  In the future
-    it may be extended to work at multiple levels of nesting.
+  This assertion takes a snapshot of the macro variables before and after
+  a macro invocation.  Differences are captured in the `&outds` table. This
+  makes it easy to detect whether any macro variables were modified or
+  changed.
 
-    If you would like this feature, feel free to contribute / raise an issue /
-    engage the SASjs team directly.
+  If you would like this feature, feel free to contribute / raise an issue /
+  engage the SASjs team directly.
 
   Example usage:
 
@@ -24,6 +24,9 @@
         desc=Checking macro variables against previous snapshot
       )
 
+  This macro is designed to work alongside `sasjs test` - for more information
+  about this facility, visit [cli.sasjs.io/test](https://cli.sasjs.io/test).
+
   @param [in] action (SNAPSHOT) The action to take.  Valid values:
     @li SNAPSHOT - take a copy of the current macro variables
     @li COMPARE - compare the current macro variables against previous values
diff --git a/tests/crossplatform/mp_stackdiffs.test.sas b/tests/crossplatform/mp_stackdiffs.test.sas
new file mode 100644
index 0000000..37bbdbe
--- /dev/null
+++ b/tests/crossplatform/mp_stackdiffs.test.sas
@@ -0,0 +1,41 @@
+/**
+  @file
+  @brief Testing mp_storediffs macro
+
+  <h4> SAS Macros </h4>
+  @li mp_assert.sas
+  @li mp_assertcolvals.sas
+  @li mp_assertdsobs.sas
+  @li mp_stackdiffs.sas
+  @li mp_storediffs.sas
+
+**/
+
+/* first, make some data */
+
+data work.orig work.deleted work.changed work.appended;
+  set sashelp.electric;
+  if _n_ le 10 then do;
+    output work.orig work.deleted;
+  end;
+  else if _n_ le 20 then do;
+    output work.orig;
+    age=99;
+    output work.changed;
+  end;
+  else if _n_ le 30 then do;
+    year=_n_;
+    output work.appended;
+  end;
+  else stop;
+run;
+
+%mp_storediffs(sashelp.electric,work.orig,CUSTOMER YEAR
+  ,delds=work.deleted
+  ,modds=work.changed
+  ,appds=work.appended
+  ,outds=work.final
+  ,mdebug=1
+)
+
+/* now, stack it back */
\ No newline at end of file