The macroArray package [ver. 1.2.0]

## The macroArray package [ver. 1.2.0]

- New parameters added to the [`%mcDictionary()`](https://github.com/SASPAC/macroarray/blob/main/macroarray.md#mcdictionary-macro) macro which allows to populate dictionary directly from a data set (see the last example in the documentation).
- Documentation updated.

README.md

@@ -22,7 +22,7 @@ The **macroArray** package implements an array, a hash table, and a dictionary c
   );
 ```
 
-SHA256 digest for the latest version of `macroArray`: F*85E3BE4D163AC5223B6EC9D3C25C46564A656E3830998B4555A963180D767160
+SHA256 digest for the latest version of `macroArray`: F*8689194590698F9A00B57FB37BE3CA8D7330F16B3E591CEAF49E6BE0B70D61D0
 
 [**Documentation for macroArray**](./macroarray.md "Documentation for macroArray")
 

macroarray.md

@@ -19,7 +19,7 @@
 
 ---
 
-# The macroArray package [ver. 1.0.5] <a name="macroarray-package"></a> ###############################################
+# The macroArray package [ver. 1.2.0] <a name="macroarray-package"></a> ###############################################
 
 The **macroArray** package implements a macro array facility:
 - `%array()`,
@@ -75,10 +75,10 @@ Package contains:
 Required SAS Components: 
   *Base SAS Software*
 
-*SAS package generated by generatePackage, version 20230411*
+*SAS package generated by generatePackage, version 20231107*
 
 The SHA256 hash digest for package macroArray: 
-`F*85E3BE4D163AC5223B6EC9D3C25C46564A656E3830998B4555A963180D767160`
+`F*8689194590698F9A00B57FB37BE3CA8D7330F16B3E591CEAF49E6BE0B70D61D0`
 
 ---
 # Content description ############################################################################################
@@ -278,6 +278,7 @@ The basic syntax is the following, the `<...>` means optional parameters:
   <,macarray=N>
   <,ds=>
   <,vars=>
+  <,q=>
 )
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -312,8 +313,8 @@ The basic syntax is the following, the `<...>` means optional parameters:
                     `%array(myArr[*] x1-x3 (4:6), vnames=Y)`
                   will use `x1`, `x2`, and `x3` as values instead `4`, `5`, and `6`.
 
-* `macarray=N` -  *Optional*, default value `N`, if set to `Y`/`YES` then macro named with array 
-                  name is compiled to create convenient envelope for multiple ampersands, e.g. 
+* `macarray=N` -  *Optional*, default value `N`, if set to `Y`/`YES` then a macro, named with the array 
+                  name, is compiled to create convenient envelope for multiple ampersands, e.g. 
                     `%array(myArr[*] x1-x3 (4:6), macarray=Y)` 
                   will create `%myArr(J)` macro which will allow to extract "data" 
                   from macroarray like: 
@@ -325,7 +326,7 @@ The basic syntax is the following, the `<...>` means optional parameters:
                   macrovariables with prefix like the array name and numeric suffixes, 
                   then the minimum and the maximum index is determined
                   and all not existing global macrovariables are created and
-                  a macro is generated in the same way as for the `Y` value
+                  a macro is generated in the same way as for the `Y` value.
 
 * `ds=` -        *Optional*, use a dataset as a basis for a macroarray data, 
                  if used by default overwrites use of the `array` parameter, honors `macarray=` 
@@ -343,23 +344,27 @@ The basic syntax is the following, the `<...>` means optional parameters:
                   2) macroarray "WEIGHT" with ALL(no separator is equivalent to #) 
                      values of variable "weight" <br>
                   3) macroarray "W" with UNIQUE(|) values of variable "weight" and <br>
-                  4) macroarray "AGE" with UNIQUE(|) values of variable "age",
-
+                  4) macroarray "AGE" with UNIQUE(|) values of variable "age".
+
+* `q=` -        *Optional*, indicates (when set to `1`) if the value be surrounded by quotes.
+                It uses `quote(cats(...))` combo under the hood. Default value is `0`.
+                Ignored for `macarray=M`.
 
 
+---
  
 ### EXAMPLES AND USECASES: ####################################################
 
 
 **EXAMPLE 1.** Basic use-case. 
-    Creating macroarray like in the array statement;
-    values are used by default;
-    different types of brackets are allowed;
+    Creating macroarray like in the array statement.
+    Values not variables names are used by default.
+    Different types of brackets are allowed.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
   %array(a[*] x1-x5 (1:5))
 
-  %array(b{5} (5*17))
+  %array(b{5} (5*17), q=1)
 
   %* Mind the $ since it is a character array!;
   %array(c(3) $ 10 ("a A" "b,B" "c;C"))
@@ -405,7 +410,7 @@ The basic syntax is the following, the `<...>` means optional parameters:
   %put &=g0. &=g1. &=g2.; 
 
   %* Or something more complex;
-  %array(gg[0:11] $ 11, function = put(intnx("MONTH", '1jun2018'd, _I_, "E"), yymmn.))
+  %array(gg[0:11] $ 11, function = put(intnx("MONTH", '1jun2018'd, _I_, "E"), yymmn.), q=1)
   %put &=ggLBOUND. &=ggHBOUND. &=ggN.;
   %put &=gg0 &=gg1 &=gg2 ... &=gg11;
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -433,10 +438,10 @@ The basic syntax is the following, the `<...>` means optional parameters:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
-**EXAMPLE 6a.** "Uppercas Letters"
+**EXAMPLE 6a.** Quoted "Uppercas Letters"
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
-  %array(UL[26] $, function = byte(rank("A")+_I_-1) )
+  %array(UL[26] $, function = byte(rank("A")+_I_-1) , q=1)
   %put &=UL1 &=UL2 ... &=UL25 &=UL26;
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -576,10 +581,10 @@ The basic syntax is the following, the `<...>` means optional parameters:
     Currently the only separator in VARS is a space.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
-  %array(ds = sashelp.class, vars = height#h weight weight|w age|)
+  %array(ds = sashelp.class, vars = height#h weight weight|w age|, q=1)
   %put _user_;
 
-  %array(ds = sashelp.class, vars = height#hght weight weight|wght age|, macarray=Y)
+  %array(ds = sashelp.class, vars = height#hght weight weight|wght age|, macarray=Y, q=1)
   %put *%hght(&hghtLBOUND.)**%weight(2)**%wght(&wghtHBOUND.)**%age(3)*;
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -599,7 +604,7 @@ The basic syntax is the following, the `<...>` means optional parameters:
   %let myTest6 = 16;
   %let myTest9 = 19;
   
-  %array(myTest, macarray=M)
+  %array(myTest, macarray=M, q=1)
   %do_over(myTest, phrase = %nrstr(%put *&_I_.*%myTest(&_I_.)*;))
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1551,6 +1556,9 @@ The basic syntax is the following, the `<...>` means optional parameters:
 %mcDictionary(
    H
   <,METHOD>
+  <,DS=>
+  <,K=Key>
+  <,D=Data>
 )
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1566,6 +1574,18 @@ The basic syntax is the following, the `<...>` means optional parameters:
               If `DELETE` then the macro dictionary named by `H` and all 
               macrovariables named like "`&H._`" are deleted.
 
+* `DS=`     - *Optional*, if NOT empty then the `&DS.` dataset is used to 
+              populate dictionary with keys from variable `&K.` and data
+              from variable `&D.` Works only during declaration.
+
+* `K=`      - *Optional*, if the `&DS.` is NOT empty then `&K.` holds a name of
+              a variable which keeps or an expression which generates keys values. 
+              Default is `Key`.
+
+* `D=`      - *Optional*, if the `&DS.` is NOT empty then `&D.` holds a name of
+              a variable which keeps or an expression which generates data values. 
+              Default is `Data`.
+
 ---
 
 ### THE CREATED MACRO `%&H.()`: ####################################################
@@ -1699,7 +1719,7 @@ See examples below to see use cases.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
-**EXAMPLE 2.** Populate macro dictionary from a dataset.
+**EXAMPLE 2A.** Populate macro dictionary from a dataset "by hand".
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
 %mcDictionary(CLASS)
@@ -1709,6 +1729,7 @@ data _null_;
   call execute('%CLASS(ADD,key=' !! name !! ',data=' !! age !! ')');
 run;
 %put t = %sysevalf(%sysfunc(datetime()) - &t.);
+%put &=Class_KEYSNUM.;
 %put _user_;
 %CLASS(CLEAR)
 
@@ -1716,25 +1737,52 @@ run;
 %mcDictionary(CARS)
 %let t = %sysfunc(datetime());
 data _null_;
-  set sashelp.cars;
-  call execute('%CARS(ADD,key=' !! catx("|",make,model,type)  !! ',data=' !! MPG_CITY !! ')');
+  set sashelp.cars(obs=42);
+  call execute('%CARS(ADD,key=' !! catx("|",make,model,type)  !! ',data=' !! put(MPG_CITY*10,dollar10.2) !! ')');
 run;
 %put t = %sysevalf(%sysfunc(datetime()) - &t.);
 %put &=CARS_KEYSNUM.;
 %CARS(LIST);
+
+%put %CARS(F,key=Audi|TT 3.2 coupe 2dr (convertible)|Sports);
+
 %CARS(CLEAR)
 %put &=CARS_KEYSNUM.;
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
-**EXAMPLE 3.** Data portion may require quoting and un-quoting..
+**EXAMPLE 2B.** Populate macro dictionary from a dataset "automatically".
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%let t = %sysfunc(datetime());
+%mcDictionary(CLASS,DCL,DS=sashelp.class,k=name,d=_N_)
+%put t = %sysevalf(%sysfunc(datetime()) - &t.);
+%put &=CLASS_KEYSNUM.;
+%put _user_;
+%CLASS(CLEAR)
+
+
+%let t = %sysfunc(datetime());
+%mcDictionary(CARS,DCL,DS=sashelp.cars(obs=42),k=catx("|",make,model,type),d=put(MPG_CITY*10,dollar10.2))
+%put t = %sysevalf(%sysfunc(datetime()) - &t.);
+%put &=CARS_KEYSNUM.;
+%CARS(LIST);
+
+%put %CARS(F,key=Audi|TT 3.2 coupe 2dr (convertible)|Sports);
+
+%CARS(CLEAR)
+%put &=CARS_KEYSNUM.;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 3.** Data portion may require quoting and un-quoting.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
 %mcDictionary(CODE)
 %CODE(CLEAR)
 %CODE(ADD,key=data, data=%str(data test; x = 42; run;))
 %CODE(ADD,key=proc, data=%str(proc print; run;))
-%CODE(ADD,key=macro,data=%nrstr(%put *****;))
+%CODE(ADD,key=macro,data=%nrstr(%put *1*2*3*4*;))
 
 %CODE(FIND,key=data)
 %CODE(FIND,key=proc) 
@@ -1760,6 +1808,7 @@ data _null_;
   end;
 run;
 %put t = %sysevalf(%sysfunc(datetime()) - &t.);
+%put %AAA(F,key=A555) %AAA(CHECK,key=A555);
 %put &=AAA_KEYSNUM;
 %AAA(CLEAR)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1775,6 +1824,43 @@ run;
 %mcDictionary(ABCDEFGHIJKLMNOP)  %* good;
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+
+**EXAMPLE 6.** More fun with datasets.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+
+data work.metadata;
+  input key :$16. data :$128.;
+cards;
+ID ABC-123-XYZ
+path /path/to/study/data
+cutoffDT 2023-01-01
+startDT 2020-01-01
+endDT 2024-12-31
+MedDRA v26.0
+;
+run;
+proc print;
+run;
+
+%mcDictionary(Study,dcl,DS=work.metadata)
+
+%put _user_;
+
+%put *%Study(F,key=ID)**%Study(C,key=ID)*;
+
+title1 "Study %Study(F,key=ID) is located at %Study(F,key=path)";
+title2 "it starts %Study(F,key=startDT) and ends %Study(F,key=endDT)";
+footnote "MedDRA version: %Study(F,key=MedDRA)";
+
+proc print data=sashelp.class(obs=7);
+run;
+
+title; 
+footnote;
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ---
 
 ## >>> `%QzipArrays()` macro: <<< <a name="qziparrays-macro"></a> #######################