Merge pull request #28 from SASPAC/dev

BasePlus package [ver. 1.34.0]

README.md

@@ -52,7 +52,7 @@ libname NEW "%workPath()/new";
 ```
 and more.
 
-SHA256 digest for the latest version of `BasePlus`: F*3407AD8068C7528E129034144F9A44CFDF14B7DC34334C64C2F1D67351D1E01E
+SHA256 digest for the latest version of `BasePlus`: F*D84CE41A550DC2D5C092C70C04A796E8329F34087A603BEF0CD366910C162E80
 
 [**Documentation for BasePlus**](./baseplus.md "Documentation for BasePlus")
 

baseplus.md

@@ -45,6 +45,8 @@
   * [`%RainCloudPlot()` macro](#raincloudplot-macro)
   * [`%zipLibrary()` macro](#ziplibrary-macro)
   * [`%unzipLibrary()` macro](#unziplibrary-macro)
+  * [`%zipArch()` macro](#ziparch-macro)
+  * [`%unzipArch()` macro](#unziparch-macro)
   * [`%LDSN()` macro](#ldsn-macro)
   * [`%LDsNm()` macro](#ldsnm-macro)
   * [`%LVarNm()` macro](#lvarnm-macro)
@@ -78,7 +80,7 @@
   
 ---
 
-# The BasePlus package [ver. 1.32.0] <a name="baseplus-package"></a> ###############################################
+# The BasePlus package [ver. 1.34.0] <a name="baseplus-package"></a> ###############################################
 
 The **BasePlus** package implements useful
 functions and functionalities I miss in the BASE SAS.
@@ -354,81 +356,128 @@ run;
 ;
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**EXAMPLE 25** Zipping and unzipping directories:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+options dlCreateDir;
+libname arch1 "%workPath()/testArch1";
+libname arch2 "%workPath()/testArch2";
+
+filename arch1 "%workPath()/testArch1";
+
+data _null_;
+  file arch1(test1.txt);
+  put "text for test file 1";
+data _null_;
+  file arch1(test2.txt);
+  put "text for test file 2";
+data _null_;
+  file arch1(test3.txt);
+  put "text for test file 3";
+run;
+
+data arch1.class(index=(name));
+  set sashelp.class;
+run;
+data arch1.cars(index=(model));
+  set sashelp.cars;
+run;
+
+%zipArch(
+  archName2.zip
+, pathRef = arch1
+, target = %workPath()/testArch2
+, list = 1 
+, overwrite = 1
+)
+
+%unzipArch(
+  archName2.zip 
+, path = %workPath()/testArch2
+, target = %workPath()/testArch2
+, clean=1
+, list=1
+);
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
 ---
 
 Package contains: 
-1.  macro     bppipe
+1.   macro      bppipe 
-2.  macro     deduplistc
+2.   macro      deduplistc 
-3.  macro     deduplistp
+3.   macro      deduplistp 
-4.  macro     deduplists
+4.   macro      deduplists 
-5.  macro     deduplistx
+5.   macro      deduplistx 
-6.  macro     dirsandfiles
+6.   macro      dirsandfiles 
-7.  macro     functionexists
+7.   macro      functionexists 
-8.  macro     getvars
+8.   macro      getvars 
-9.  macro     intslist
+9.   macro      intslist 
-10. macro     ldsn
+10.  macro      ldsn 
-11. macro     ldsnm
+11.  macro      ldsnm 
-12. macro     lvarnm
+12.  macro      lvarnm 
-13. macro     lvarnmlab
+13.  macro      lvarnmlab 
-14. macro     qdeduplistx
+14.  macro      qdeduplistx 
-15. macro     qgetvars
+15.  macro      qgetvars 
-16. macro     qzipevalf
+16.  macro      qzipevalf 
-17. macro     raincloudplot
+17.  macro      raincloudplot 
-18. macro     repeattxt
+18.  macro      repeattxt 
-19. macro     splitdsintoblocks
+19.  macro      splitdsintoblocks 
-20. macro     splitdsintoparts
+20.  macro      splitdsintoparts 
-21. macro     symdelglobal
+21.  macro      symdelglobal 
-22. macro     unziplibrary
+22.  macro      unziparch 
-23. macro     zipevalf
+23.  macro      unziplibrary 
-24. macro     ziplibrary
+24.  macro      ziparch 
-25. format    bool
+25.  macro      zipevalf 
-26. format    boolz
+26.  macro      ziplibrary 
-27. format    ceil
+27.  format     bool 
-28. format    floor
+28.  format     boolz 
-29. format    int
+29.  format     ceil 
-30. function  arrfill
+30.  format     floor 
-31. function  arrfillc
+31.  format     int 
-32. function  arrmissfill
+32.  functions  arrfill 
-33. function  arrmissfillc
+33.  functions  arrfillc 
-34. function  arrmisstoleft
+34.  functions  arrmissfill 
-35. function  arrmisstoleftc
+35.  functions  arrmissfillc 
-36. function  arrmisstoright
+36.  functions  arrmisstoleft 
-37. function  arrmisstorightc
+37.  functions  arrmisstoleftc 
-38. function  bracketsc
+38.  functions  arrmisstoright 
-39. function  bracketsn
+39.  functions  arrmisstorightc 
-40. function  catxfc
+40.  functions  bracketsc 
-41. function  catxfi
+41.  functions  bracketsn 
-42. function  catxfj
+42.  functions  catxfc 
-43. function  catxfn
+43.  functions  catxfi 
-44. function  deldataset
+44.  functions  catxfj 
-45. function  semicolonc
+45.  functions  catxfn 
-46. function  semicolonn
+46.  functions  deldataset 
-47. format    brackets
+47.  functions  semicolonc 
-48. format    semicolon
+48.  functions  semicolonn 
-49. proto     qsortincbyprocproto
+49.  format     brackets 
-50. function  frommissingtonumberbs
+50.  format     semicolon 
-51. function  fromnumbertomissing
+51.  proto      qsortincbyprocproto 
-52. function  quicksort4notmiss
+52.  functions  frommissingtonumberbs 
-53. function  quicksorthash
+53.  functions  fromnumbertomissing 
-54. function  quicksorthashsddv
+54.  functions  quicksort4notmiss 
-55. function  quicksortlight
+55.  functions  quicksorthash 
-56. macro     date
+56.  functions  quicksorthashsddv 
-57. macro     datetime
+57.  functions  quicksortlight 
-58. macro     filepath
+58.  macro      date 
-59. macro     finddswithvarval
+59.  macro      datetime 
-60. macro     fmt
+60.  macro      filepath 
-61. macro     gettitle
+61.  macro      finddswithvarval 
-62. macro     infmt
+62.  macro      fmt 
-63. macro     letters
+63.  macro      gettitle 
-64. macro     libpath
+64.  macro      infmt 
-65. macro     minclude
+65.  macro      letters 
-66. macro     monthshift
+66.  macro      libpath 
-67. macro     replist
+67.  macro      minclude 
-68. macro     time
+68.  macro      monthshift 
-69. macro     today
+69.  macro      replist 
-70. macro     translate
+70.  macro      time 
-71. macro     tranwrd
+71.  macro      today 
-72. macro     workpath
+72.  macro      translate 
+73.  macro      tranwrd 
+74.  macro      workpath 
 
 
 
@@ -436,10 +485,10 @@ Package contains additional content, run:  %loadPackageAddCnt(BasePlus)  to load
 or look for the baseplus_AdditionalContent directory in the Packages fileref
 localization (only if additional content was deployed during the installation process).
 
-* SAS package generated by generatePackage, version 20231024 *
+* SAS package generated by generatePackage, version 20231107 *
 
 The SHA256 hash digest for package BasePlus: 
-`F*3407AD8068C7528E129034144F9A44CFDF14B7DC34334C64C2F1D67351D1E01E` 
+`F*D84CE41A550DC2D5C092C70C04A796E8329F34087A603BEF0CD366910C162E80` 
 
 ---
 # Content description ############################################################################################
@@ -3771,6 +3820,237 @@ run;
 
 ---
 
+## >>> `%zipArch()` macro: <<< <a name="ziparch-macro"></a> #######################  
+
+The zipArch() macro allows to ZIP content of a directory. 
+Macro is OS independent, the `XCMD` option is not required.
+
+Content of zipped archive can be listed in the log.
+
+Errors of decompression and are reported. 
+
+Macro **does not** include hidden files.
+
+See examples below for the details.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%zipArch(
+    archName
+   ,path = 
+  <,pathRef=>
+  <,target=>
+  <,targetRef=>
+  <,list=>
+  <,overwrite=>
+  <,dropList=> 
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `archName`      - *Required*, name of the archive to be generated.
+                     Name should be full, i.e., with the extension!
+
+2. `path=`         - *Required/Optional*, location of a directory to ZIP.
+                     The path should be provided unquoted.
+                     Has priority over the `pathRef` parameter.
+
+* `pathRef=`       - *Required/Optional*, fileref to location of a directory to ZIP.
+                     The reference **has** to be pointing to single directory.
+                     If provided with `path` - the `path` takes 
+                     priority over the `pathRef` parameter.
+
+* `target=`        - *Optional*, a path pointing to target location where
+                     the archive will be generated.
+                     The path should be provided unquoted.
+                     Default value is `WORK` location.
+                     Has priority over the `targetRef` parameter.
+
+* `targetRef=`     - *Optional*, fileref to a path pointing to target location 
+                     where the archive will be generated.
+                     The reference **has** to be pointing to single directory.
+                     If provided with `target` - the `target` takes 
+                     priority over the `targetRef` parameter.
+
+* `list = 0`       - *Optional*, default value is `0`,
+                     indicates if zip content should be listed in the log. 
+                     `1` means *yes*, `0` means *no*. 
+
+* `overwrite = 0`  - *Optional*, default value is `0`,
+                     indicates if existing archive file should be overwritten. 
+                     `1` means *yes*, `0` means *no*. 
+
+* `overwrite = 1`  - *Technical*, default value is `1`,
+                     indicates if the "to-be-zipped-files-list" 
+                     data set should be deleted. 
+                     `1` means *yes*, `0` means *no*.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Zip a directory . Example requires the `basePlus` package.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+
+options dlCreateDir;
+libname arch1 "%workPath()/testArch1";
+libname arch2 "%workPath()/testArch2";
+
+filename arch1 "%workPath()/testArch1";
+
+data _null_;
+  file arch1(test1.txt);
+  put "text for test file 1";
+data _null_;
+  file arch1(test2.txt);
+  put "text for test file 2";
+data _null_;
+  file arch1(test3.txt);
+  put "text for test file 3";
+run;
+
+data arch1.class(index=(name));
+  set sashelp.class;
+run;
+data arch1.cars(index=(model));
+  set sashelp.cars;
+run;
+
+
+
+%zipArch(
+  archName1.zip
+, path = %workPath()/testArch1
+, list = 1 
+, overwrite = 1
+
+)
+
+%zipArch(
+  archName2.zip
+, pathRef = arch1
+, target = %workPath()/testArch2
+, list = 1 
+, overwrite = 1
+)
+
+
+%unzipArch(
+  archName2.zip 
+, path = %workPath()/testArch2
+, target = %workPath()/testArch2
+, clean=1
+, list=1
+);
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+## >>> `%unzipArch()` macro: <<< <a name="unziparch-macro"></a> #######################  
+
+The unzipArch() macro allows to unzip content of a ZIP archive. 
+Macro is OS independent, the `XCMD` option is not required.
+
+The `dlCreateDir` option is used under the hood.
+
+Content of unzipped archive can be listed in the log.
+
+Source files can be deleted after decompression.
+Errors of decompression and are reported. If any occur
+the deletion is suspended.
+
+See examples below for the details.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%unzipArch(
+    archName
+  <,path=>
+  <,pathRef=>
+  <,target=>
+  <,targetRef=>
+  <,list=> 
+  <,clean=>
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `archName`      - *Required*, name of the ZIP archive to be extracted.
+                     Name should be full, i.e., with the extension!
+
+* `path=`          - *Optional*, a path pointing to zipped file location.
+                     The path should be provided unquoted.
+                     Default value is `WORK` location.
+
+* `pathRef=`       - *Optional*, a fileref to path pointing to zipped file location.
+                     The `path`, if not null, has precedense over the `pathRef`.
+
+* `target=`        - *Optional*, a path pointing to target location where
+                     files will be extracted.
+                     The path should be provided unquoted.
+                     Default value is `WORK` location.
+
+* `target=`        - *Optional*, a fileref to path pointing to target location where
+                     files will be extracted.
+                     The `target`, if not null, has precedense over the `targetRef`.
+
+* `list = 0`       - *Optional*, default value is `0`,
+                     indicates if zip content should be listed in the log. 
+                     `1` means *yes*, `0` means *no*. 
+
+* `clean = 0`      - *Optional*, default value is `0`,
+                     indicates if zip file should be deleted after unzipping. 
+                     `1` means *yes*, `0` means *no*. 
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Unzip compressed archive. Example requires the `basePlus` package.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+
+filename arch ZIP "%workPath()/testArch.zip";
+
+data _null_;
+  file arch(abc/test1.txt);
+  put "text for test file 1";
+data _null_;
+  file arch(abc/subdir/test2.txt);
+  put "text for test file 2";
+data _null_;
+  file arch(abc/subdir/test3.txt);
+  put "text for test file 3";
+run;
+
+%unzipArch(
+  testArch.zip 
+, path = %workPath()
+, target = %workPath()
+, list=1
+);
+
+
+
+filename pR "%workPath()";
+
+%unzipArch(
+  testArch.zip 
+, pathRef = pR
+, targetRef = pR
+, clean=1
+);
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
 ## >>> `%LDSN()` macro: <<< <a name="ldsn-macro"></a> #######################  
 
 The LDSN (Long DataSet Names) macro function