The BasePlus package [ver. 1.17]

The BasePlus package [ver. 1.17]

- new macro `%LDSNM()`, which extends functionality of the `%LDSN()` was added.
- documentation updated

hash: 619D4B2562F1D9E42C9C5DCB326E8F4D6A020B5D0CEE29A6174F65F8E1B0E7BD

README.md

@@ -93,7 +93,7 @@ This is a list of locations where the SAS Packages Framework is used:
 
 If you want to share that you are using the SPF let me know and I'll update the list.
 
-If you find the SPF usefull **share info** about it or **give it a [star](https://github.com/yabwon/SAS_PACKAGES/stargazers)** so more people will know.
+If you find the SPF useful **share info** about it or **give it a [star](https://github.com/yabwon/SAS_PACKAGES/stargazers)** so more people will know.
 
 ---
 
@@ -146,7 +146,7 @@ SHA256 digest for macroArray: DF63B0E027827A82038F1C8422787A0BC569BA93104BA1778D
 [Documentation for macroArray](https://github.com/yabwon/SAS_PACKAGES/blob/main/packages/macroarray.md "Documentation for macroArray")
 
 
-- **BasePlus**\[1.14\] adds a bunch of functionalities I am missing in BASE SAS, such as:
+- **BasePlus**\[1.17\] adds a bunch of functionalities I am missing in BASE SAS, such as:
 ```sas
 call arrMissToRight(myArray); 
 call arrFillMiss(17, myArray); 
@@ -164,7 +164,7 @@ format x bool.;
 
 %zipLibrary(sashelp,libOut=work)
 ```
-SHA256 digest for BasePlus: 12A9A2155D9C6F969DF0A66E3A18D0938B8194FA3AA9D70EDDE1CB71DEF9691E
+SHA256 digest for BasePlus: 619D4B2562F1D9E42C9C5DCB326E8F4D6A020B5D0CEE29A6174F65F8E1B0E7BD
 
 [Documentation for BasePlus](https://github.com/yabwon/SAS_PACKAGES/blob/main/packages/baseplus.md "Documentation for BasePlus")
 

packages/README.md

@@ -90,7 +90,7 @@ SHA256 digest for macroArray: DF63B0E027827A82038F1C8422787A0BC569BA93104BA1778D
 
 ---
 
-- **BasePlus**\[1.14\] adds a bunch of functionalities I am missing in BASE SAS, such as: 
+- **BasePlus**\[1.17\] adds a bunch of functionalities I am missing in BASE SAS, such as: 
 ```sas
 call arrMissToRight(myArray); 
 call arrFillMiss(17, myArray); 
@@ -108,7 +108,7 @@ format x bool.;
 
 %zipLibrary(sashelp,libOut=work)
 ```
-SHA256 digest for BasePlus: 12A9A2155D9C6F969DF0A66E3A18D0938B8194FA3AA9D70EDDE1CB71DEF9691E
+SHA256 digest for BasePlus: 619D4B2562F1D9E42C9C5DCB326E8F4D6A020B5D0CEE29A6174F65F8E1B0E7BD
 
 [Documentation for BasePlus](https://github.com/yabwon/SAS_PACKAGES/blob/main/packages/baseplus.md "Documentation for BasePlus")
 

packages/SHA256_for_packages.txt

@@ -1,3 +1,12 @@
+/* 20220511 */
+BasePlus: 619D4B2562F1D9E42C9C5DCB326E8F4D6A020B5D0CEE29A6174F65F8E1B0E7BD
+
+/* 20220509 */
+BasePlus: 4CD3926B9842925C86B80B5B47B47BEA1FB9707826B545B9B4D52AE97BC3617E
+
+/* 20220508 */
+BasePlus: 0331C673052D5221DA98C5CC93295634D8A0BC62C7D2FEF9D0D85B0B2DEDE4E9
+
 /* 20220420 */
 BasePlus: 12A9A2155D9C6F969DF0A66E3A18D0938B8194FA3AA9D70EDDE1CB71DEF9691E
 DFA: 6B3FB0B06B47A7EF1BB004B483B0F39B8F553F7F16D02A7E24CDE388BBA704EA

packages/baseplus.md

@@ -45,12 +45,18 @@
   * [`%RainCloudPlot()` macro](#raincloudplot-macro)
   * [`%zipLibrary()` macro](#ziplibrary-macro)
   * [`%unzipLibrary()` macro](#unziplibrary-macro)
+  * [`%LDSN()` macro](#ldsn-macro)
+  * [`%LDsNm()` macro](#ldsnm-macro)
+  * [`%LVarNm()` macro](#lvarnm-macro)
+  * [`%LVarNmLab()` macro](#lvarnmlab-macro)
+
+  
   
   * [License](#license)
   
 ---
 
-# The BasePlus package [ver. 1.14] <a name="baseplus-package"></a> ###############################################
+# The BasePlus package [ver. 1.17] <a name="baseplus-package"></a> ###############################################
 
 The **BasePlus** package implements useful
 functions and functionalities I miss in the BASE SAS.
@@ -67,7 +73,9 @@ Kudos to all who inspired me to generate this package:
 *Richard DeVenezia*, 
 *Christian Graffeuille*,
 *Allan Bowe*,
-*Anamaria Calai*.
+*Anamaria Calai*,
+*Michal Ludwicki*,
+*Quentin McMullen*.
 
 ---
 
@@ -187,7 +195,6 @@ Kudos to all who inspired me to generate this package:
 %rainCloudPlot(sashelp.cars,DriveTrain,Invoice)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-![Rain Cloud Plot](./baseplus_RainCloudPlot_Ex0_9.png)
 
 **Example 10**: Zip SAS library.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
@@ -196,64 +203,78 @@ Kudos to all who inspired me to generate this package:
 %unzipLibrary(%sysfunc(pathname(work)), zip=sashelp, mode=S, clean=1)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**Example 11**: Long dataset names.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+data %LDSN(  work. peanut butter & jelly time with a "Hot-Dog" in [a box], popcorn, and s*t*a*r*s (drop = sex rename=(name=first_name) where = (age in (12,13,14)))  );
+  set sashelp.class;
+run;
 
+proc print data  = %LDSN(  work. peanut butter & jelly with a "Hot-Dog" in [a box], popcorn, and s*t*a*r*s  );
+run;
 
+data MyNextDataset;
+  set %LDSN(  work. peanut butter & jelly with a "Hot-Dog" in [a box], popcorn, and s*t*a*r*s  );
+  where age > 12;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ---
 
 Package contains: 
-1.  macro deduplistc 
-2.  macro deduplistp 
-3.  macro deduplists 
-4.  macro deduplistx 
-5.  macro functionexists 
-6.  macro getvars 
-7.  macro qdeduplistx 
-8.  macro qgetvars 
-9.  macro qzipevalf 
-10. macro raincloudplot 
-11. macro symdelglobal 
-12. macro unziplibrary 
-13. macro zipevalf 
-14. macro ziplibrary 
-15. format bool 
-16. format boolz 
-17. format ceil 
-18. format floor 
-19. format int 
-20. function arrfill 
-21. function arrfillc 
-22. function arrmissfill 
-23. function arrmissfillc 
-24. function arrmisstoleft 
-25. function arrmisstoleftc 
-26. function arrmisstoright 
-27. function arrmisstorightc 
-28. function bracketsc 
-29. function bracketsn 
-30. function catxfc 
-31. function catxfi 
-32. function catxfj 
-33. function catxfn 
-34. function deldataset 
-35. function semicolonc 
-36. function semicolonn 
-37. format brackets 
-38. format semicolon 
-39. proto qsortincbyprocproto 
-40. function frommissingtonumberbs 
-41. function fromnumbertomissing 
-42. function quicksort4notmiss 
-43. function quicksorthash 
-44. function quicksorthashsddv 
-45. function quicksortlight 
-
-
+1.   macro      deduplistc 
+2.   macro      deduplistp 
+3.   macro      deduplists 
+4.   macro      deduplistx 
+5.   macro      functionexists 
+6.   macro      getvars 
+7.   macro      ldsn 
+8.   macro      ldsnm 
+9.   macro      lvarnm 
+10.  macro      lvarnmlab 
+11.  macro      qdeduplistx 
+12.  macro      qgetvars 
+13.  macro      qzipevalf 
+14.  macro      raincloudplot 
+15.  macro      symdelglobal 
+16.  macro      unziplibrary 
+17.  macro      zipevalf 
+18.  macro      ziplibrary 
+19.  format     bool 
+20.  format     boolz 
+21.  format     ceil 
+22.  format     floor 
+23.  format     int 
+24.  functions  arrfill 
+25.  functions  arrfillc 
+26.  functions  arrmissfill 
+27.  functions  arrmissfillc 
+28.  functions  arrmisstoleft 
+29.  functions  arrmisstoleftc 
+30.  functions  arrmisstoright 
+31.  functions  arrmisstorightc 
+32.  functions  bracketsc 
+33.  functions  bracketsn 
+34.  functions  catxfc 
+35.  functions  catxfi 
+36.  functions  catxfj 
+37.  functions  catxfn 
+38.  functions  deldataset 
+39.  functions  semicolonc 
+40.  functions  semicolonn 
+41.  format     brackets 
+42.  format     semicolon 
+43.  proto      qsortincbyprocproto 
+44.  functions  frommissingtonumberbs 
+45.  functions  fromnumbertomissing 
+46.  functions  quicksort4notmiss 
+47.  functions  quicksorthash 
+48.  functions  quicksorthashsddv 
+49.  functions  quicksortlight 
 
 *SAS package generated by generatePackage, version 20220420*
 
 The SHA256 hash digest for package BasePlus: 
-`12A9A2155D9C6F969DF0A66E3A18D0938B8194FA3AA9D70EDDE1CB71DEF9691E` 
+`619D4B2562F1D9E42C9C5DCB326E8F4D6A020B5D0CEE29A6174F65F8E1B0E7BD` 
 
 ---
 # Content description ############################################################################################
@@ -3497,6 +3518,419 @@ run;
 
 ---
 
+## >>> `%LDSN()` macro: <<< <a name="ldsn-macro"></a> #######################  
+
+The LDSN (Long DataSet Names) macro function 
+allows to use an "arbitrary" text string to name a dataset.
+
+The LDSN macro has some limitation described below, to overcome them 
+another macro, with different name: LDSNM (Long DataSet Names Modified) 
+was created. See its description to learn how to use it.
+
+---
+
+The idea for the macro came from the following story: 
+
+Good friend of mine, who didn't use SAS for quite some time, 
+told me that he lost a few hours for debugging because 
+he forgot that the SAS dataset name limitation is 32 bytes.
+ 
+I replied that it shouldn't be a problem to do a workaround 
+for this inconvenience with a macro and the `MD5()` hashing function. 
+
+I said: *The macro should take an "arbitrary string" for a dataset 
+name, convert it, with help of `MD5()`, to a hash digest, and 
+create a dataset with an "artificial" `hex16.` formated name.*
+
+Starting with something like this:
+
+~~~~~~~~~~~~~~~~~~~~~~~sas
+data %LDSN(work. peanut butter & jelly with a hot-dog in [a box] and s*t*a*r*s (drop = sex rename=(name=first_name) where = (age in (12,13,14))) );
+  set sashelp.class;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~
+
+the macro would do:
+
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%sysfunc(MD5(peanut butter & jelly with a hot-dog in [a box] and s*t*a*r*s), hex16.)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+and (under the hood) return and execute the following code: 
+
+~~~~~~~~~~~~~~~~~~~~~~~sas
+data work.DSN_41D599EF51FBA58_(drop = sex rename=(name=first_name) where = (age in (12,13,14))) ;
+  set sashelp.class;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Also in the next data step user should be able to do:
+
+~~~~~~~~~~~~~~~~~~~~~~~sas
+data my_next_data_step;
+  set %DSN(work. peanut butter & jelly with a hot-dog in [a box] and s*t*a*r*s);
+run;
+~~~~~~~~~~~~~~~~~~~~~~~
+
+and work without the "dataset-name-length-limitation" issue.
+
+---
+
+See examples below for the details.
+
+The `%LDSN()` macro executes like a pure macro code.
+
+**Known "Limitations":**
+
+- dataset name _cannot_ contain dots (`.`) since they are used as separators!
+
+- dataset name _cannot_ contain round brackets(`(` and `)`) since they are used as separators
+  (but `[]` and `{}` are allowed)!
+
+- dataset name _cannot_ contain unpaired quotes (`'` and `"`), 
+  text: `a "hot-dog"` is ok, but `John's dog` is not!
+
+**Behaviour:**
+
+- dataset name text is *converted to upcase*
+
+- dataset name text *leading and trailing spaces are ignored*, 
+  e.g. the following will give the same hash digest:
+  `%ldsn(work.test)`, `%ldsn( work.test)`, `%ldsn(work.test )`,
+  `%ldsn(work .test)`, `%ldsn(work. test)`, `%ldsn(work . test)`.
+
+- macro calls of the form:
+  `data %LDSN(); run;`, `data %LDSN(    ); run;`, `data %LDSN( . ); run;` or even
+  `data %LDSN( . (keep=x)); run;` are resolved to empty string, so the result is
+  equivalent to `data; run;`
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%LDSN(
+   arbitrary text string (in line with limitations)
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The text string is concider as *"fully qualified dataset name"*, i.e. macro
+assumes it may contain library as prefix and data set options as sufix.
+See the `%LDsNm()` macro for comparison.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+options nomprint source nomlogic nosymbolgen ls = max ps = max;
+
+data %LDSN(  work. peanut butter & jelly with a "Hot-Dog" in [a box], popcorn, and s*t*a*r*s (drop = sex rename=(name=first_name) where = (age in (12,13,14)))  );
+  set sashelp.class;
+run;
+
+proc print data  = %LDSN(  work. peanut butter & jelly with a "Hot-Dog" in [a box], popcorn, and s*t*a*r*s  );
+run;
+
+data MyNextDataset;
+  set %LDSN(  work. peanut butter & jelly with a "Hot-Dog" in [a box], popcorn, and s*t*a*r*s  );
+  where age > 12;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+## >>> `%LDSNM()` macro: <<< <a name="ldsnm-macro"></a> #######################  
+
+The LDSNM (Long DataSet Names Modified) macro function 
+allows to use an "arbitrary" text string to name a dataset.
+
+The LDSN macro had some limitation (see its documentation), to overcome them 
+another `%LDSNM()` (Long DataSet Names Modified) macro was created.
+
+The main idea behind the `%LDSNM()` is the same as for `%LDSN()` - see the description there.
+
+---
+
+The `%LDSNM()` works differently then the `%LDSN()`.
+
+The `%LDSN()` assumed that *both* libname and dataset options *could*
+be passed as elements in macro argument, e.g.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+data %LDSN( WORK.peanut butter & jelly with a hot-dog in [a box] and s*t*a*r*s (drop = sex) );
+  set sashelp.class;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `%LDSNM()`, in contrary, assumes that both libname and dataset options are
+passed **outside** the macro, i.e.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+data WORK.%LDSNM( peanut butter & jelly with a hot-dog in [a box] and s*t*a*r*s ) (drop = sex);
+  set sashelp.class;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This approach reduces some limitations the LDSN has.
+
+The **additional** feature of the `%LDSNM()` is that when the macro is called 
+a global macrovariable, which name is the same as hashed dataset name, is created.
+The macrovariable value is the text of the argument of the macro. For example 
+the following macro call:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+data %LDSNM(John "x" 'y' dog);
+  set sashelp.class;
+  where name = 'John';
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+creates `DSN_BF1F8C4D6495B34A_` macrovariable with value:  `JOHN "X" 'Y' DOG`.
+
+The macrovariable is useful when combined with `symget()` function and 
+the `indsname=` option to get the original text string value back, 
+like in this example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+data test;
+  set %LDSNM(John "x" 'y' dog) indsname = i;
+  
+  indsname = symget(scan(i,-1,"."));
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See examples below for the details.
+
+---
+
+The `%LDSN()` macro executes like a pure macro code.
+
+**Known "Limitations":**
+
+- dataset name _cannot_ contain _unpaired_ round brackets(`(` and `)`) 
+  (but unmatched `[]` and `{}` are allowed)!
+
+- dataset name _cannot_ contain _unpaired_ quotes (`'` and `"`), 
+  text: `a "hot-dog"` is ok, but `John's dog` is not!
+
+**Behaviour:**
+
+- dataset name text is *converted to upcase*
+
+- dataset name text *leading and trailing spaces are ignored*, 
+  e.g. the following will give the same hash digest:
+  `%ldsn(test)`, `%ldsn( test)`, `%ldsn(test )`.
+
+- macro calls of the form:
+  `data %LDSN(); run;` or `data %LDSN(    ); run;` are resolved 
+  to empty string, so the result is equivalent to `data; run;`
+
+- created macrovariable is _global_ in scope.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%LDSNM(
+   arbitrary text string (in line with limitations)
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The text string is concider as *"only dataset name"*, i.e. macro does not 
+assume it contain library as prefix or data set options as sufix.
+See the `%LDSN()` macro for comparison.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+data %LDSNM(John "x" 'y' & dog);
+  set sashelp.class;
+  where name = 'John';
+run;
+
+data %LDSNM(John "x"[ 'y' & dog);
+  set sashelp.class;
+  where name = 'John';
+run;
+
+data %LDSNM(John "x" 'y'} & dog);
+  set sashelp.class;
+  where name = 'John';
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.** 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+data work.%LDsNm(  peanut butter & jelly, a hot-dog in [a box], and s(*)t(*)a(*)r(*)s!!   ) (drop = sex rename=(name=first_name) where = (age in (12,13,14)))
+;
+  set sashelp.class;
+run;
+
+data test;
+  set work.%LDsNm(  peanut butter & jelly, a hot-dog in [a box], and s(*)t(*)a(*)r(*)s!!   ) indsname=i;
+
+  indsname=symget(scan(i,-1,"."));
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 3.** 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+data work.%LDsNm(  . );
+  set sashelp.class;
+run;
+
+data %LDsNm(  );
+  set sashelp.class;
+run;
+
+
+data %LDsNm();
+  set sashelp.class;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+## >>> `%LVarNm()` macro: <<< <a name="lvarnm-macro"></a> #######################  
+
+The LVarNm() macro function works like the LDSN() macro function, but for variables.
+Supported by LVarNmLab() macro function which allows to remember "user names" in labels.
+
+The motivation for the macro was similar one as for the LDSN() macro. 
+
+---
+
+See examples below for the details.
+
+The `%LVarNm()` macro executes like a pure macro code.
+
+**Known "Limitations":**
+
+- variable name _cannot_ contain unpaired quotes (`'` and `"`), 
+  text: `a "hot-dog"` is ok, but `John's dog` is not!
+
+**Behaviour:**
+
+- variable name text is *converted to upcase*
+
+- variable name text *leading and trailing spaces are ignored*, 
+  e.g. the following will give the same hash digest:
+  `%LVarNm(test)`, `%LVarNm( test)`, `%LVarNm(test )`.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%LVarNm(
+   arbitrary text string (in line with limitations)
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+options ls=max;
+data test;
+  %LVarNmLab( peanut butter & jelly with a "Hot-Dog" in [a box], popcorn, and s*t*a*r*s  )
+
+  do %LVarNm( peanut butter & jelly with a "Hot-Dog" in [a box], popcorn, and s*t*a*r*s  ) = 1 to 10;
+
+    y = 5 + %LVarNm( peanut butter & jelly with a "Hot-Dog" in [a box], popcorn, and s*t*a*r*s  ) * 17; 
+    output;
+  end;
+run;
+
+data test2;
+  set test;
+  where %LVarNm( peanut butter & jelly with a "Hot-Dog" in [a box], popcorn, and s*t*a*r*s  ) < 5;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.** 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+data test3;
+  %LVarNmLab() = 17;
+  
+  %LVarNm() = 17;
+
+  %LVarNm( ) = 42;
+
+  %LVarNm(  ) = 303;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 3.** 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+data test3;
+  %LVarNm(test) = 1;
+
+  %LVarNm( test) = 2;
+
+  %LVarNm(test ) = 3;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 4.** 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+data test4;
+  array X[*] %LVarNm(some strange! name)_0 - %LVarNm(some strange! name)_10;
+
+  do i = lbound(X) to hbound(X);
+    X[i] = 2**(i-1);    
+    put X[i]=;
+  end;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+## >>> `%LVarNmLab()` macro: <<< <a name="lvarnmlab-macro"></a> #######################  
+
+The LVarNmLab() macro function supports LVarNm() and allows to remember "user names" in labels.
+
+The motivation for the macro was similar one as for the LDSN() macro. 
+
+---
+
+See examples in LVarNm() documentation for the details.
+
+The `%LVarNmLab()` macro executes like a pure macro code.
+
+**Known "Limitations":**
+
+- variable name _cannot_ contain unpaired quotes (`'` and `"`), 
+  text: `a "hot-dog"` is ok, but `John's dog` is not!
+
+**Behaviour:**
+
+- variable name text is *converted to upcase*
+
+- variable name text *leading and trailing spaces are ignored*, 
+  e.g. the following will give the same hash digest:
+  `%LVarNmLab(test)`, `%LVarNmLab( test)`, `%LVarNmLab(test )`.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%LVarNmLab(
+   arbitrary text string (in line with limitations)
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
 ## License ####################################################################
 
 Copyright (c) 2020 Bartosz Jablonski