Merge pull request #12 from SASPAC/dev

The BasePlus package [ver. 1.20.0]

README.md

@@ -21,9 +21,17 @@ format x bool.;
 %rainCloudPlot(sashelp.cars,DriveTrain,Invoice)
 
 %zipLibrary(sashelp,libOut=work)
+
+%bpPIPE(ls -la ~/)
+
+%dirsAndFiles(C:\SAS_WORK\,ODS=work.result)
+
+%put %repeatTxt(#,15,s=$) HELLO SAS! %repeatTxt(#,15,s=$);
 ```
 and more.
 
-SHA256 digest for the latest version of `BasePlus`: EBA9EDB3D50D854288970CC0E965DA6AD5B057F6E6433EEBEC4A02B9A25CF6E2
+SHA256 digest for the latest version of `BasePlus`: F*F39F38CE80A5D8EED3BC9F2413CD6DEF38E8657E5DCF427CBA8938EB8C4350B6
 
 [**Documentation for BasePlus**](./baseplus.md "Documentation for BasePlus")
+
+To work with a package use the [**SAS Packages Framework**](https://github.com/yabwon/SAS_PACKAGES/blob/main/README.md "SPFinit").

baseplus.md

@@ -49,14 +49,15 @@
   * [`%LDsNm()` macro](#ldsnm-macro)
   * [`%LVarNm()` macro](#lvarnm-macro)
   * [`%LVarNmLab()` macro](#lvarnmlab-macro)
-
-  
+  * [`%bpPIPE()` macro](#bppipe-macro)
+  * [`%dirsAndFiles()` macro](#dirsandfiles-macro)
+  * [`%repeatTxt()` macro](#repeattxt-macro)
   
   * [License](#license)
   
 ---
 
-# The BasePlus package [ver. 1.17.2] <a name="baseplus-package"></a> ###############################################
+# The BasePlus package [ver. 1.20.0] <a name="baseplus-package"></a> ###############################################
 
 The **BasePlus** package implements useful
 functions and functionalities I miss in the BASE SAS.
@@ -75,7 +76,8 @@ Kudos to all who inspired me to generate this package:
 *Allan Bowe*,
 *Anamaria Calai*,
 *Michal Ludwicki*,
-*Quentin McMullen*.
+*Quentin McMullen*,
+*Kurt Bremser*.
 
 Recording from the SAS Explore 2022 conference: [A BasePlus Package for SAS](https://communities.sas.com/t5/SAS-Explore-Presentations/A-BasePlus-Package-for-SAS/ta-p/838246 "A BasePlus Package for SAS") (September 27th-29th, 2022).
 
@@ -220,63 +222,86 @@ data MyNextDataset;
 run;
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**Example 12**: List, to the log, content of `home` directory.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%bpPIPE(ls -la ~/)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**EXAMPLE 13** Get list of all files and directories from `C:\SAS_WORK\`:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%dirsAndFiles(C:\SAS_WORK\,ODS=work.result)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**EXAMPLE 14** Text repetition:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%put %repeatTxt(#,15,s=$) HELLO SAS! %repeatTxt(#,15,s=$);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ---
 
 Package contains: 
-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 
+1.  macro        bppipe
+2.  macro        deduplistc
+3.  macro        deduplistp
+4.  macro        deduplists
+5.  macro        deduplistx
+6.  macro        dirsandfiles
+7.  macro        functionexists
+8.  macro        getvars
+9.  macro        ldsn
+10. macro        ldsnm
+11. macro        lvarnm
+12. macro        lvarnmlab
+13. macro        qdeduplistx
+14. macro        qgetvars
+15. macro        qzipevalf
+16. macro        raincloudplot
+17. macro        repeattxt
+18. macro        symdelglobal
+19. macro        unziplibrary
+20. macro        zipevalf
+21. macro        ziplibrary
+22. format       bool
+23. format       boolz
+24. format       ceil
+25. format       floor
+26. format       int
+27. functions    arrfill
+28. functions    arrfillc
+29. functions    arrmissfill
+30. functions    arrmissfillc
+31. functions    arrmisstoleft
+32. functions    arrmisstoleftc
+33. functions    arrmisstoright
+34. functions    arrmisstorightc
+35. functions    bracketsc
+36. functions    bracketsn
+37. functions    catxfc
+38. functions    catxfi
+39. functions    catxfj
+40. functions    catxfn
+41. functions    deldataset
+42. functions    semicolonc
+43. functions    semicolonn
+44. format       brackets
+45. format       semicolon
+46. proto        qsortincbyprocproto
+47. functions    frommissingtonumberbs
+48. functions    fromnumbertomissing
+49. functions    quicksort4notmiss
+50. functions    quicksorthash
+51. functions    quicksorthashsddv
+52. functions    quicksortlight
 
-*SAS package generated by generatePackage, version 20221121*
+
+Package contains additional content, run:  %loadPackageAddCnt(BasePlus)  to load it
+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 20230411 *
 
 The SHA256 hash digest for package BasePlus: 
-`EBA9EDB3D50D854288970CC0E965DA6AD5B057F6E6433EEBEC4A02B9A25CF6E2` 
+`F*F39F38CE80A5D8EED3BC9F2413CD6DEF38E8657E5DCF427CBA8938EB8C4350B6` 
 
 ---
 # Content description ############################################################################################
@@ -3934,6 +3959,271 @@ The basic syntax is the following, the `<...>` means optional parameters:
 
 ---
 
+## >>> `%bpPIPE()` macro: <<< <a name="bppipe-macro"></a> #######################  
+
+The bpPIPE() [Base Plus PIPE] macro executes OS command
+and print to the log output of the execution.
+
+Under the hood it uses `_` filename reference to PIPE device.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%bpPIPE( <OS command goes here> )
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+* **NO Arguments**    - Everything inside brackets is treated as an OS command.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** List, to the log, content of D and C drives:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %bpPIPE(D: & dir & dir "C:\")
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.** List, to the log, content of `home` directory:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %bpPIPE(ls -halt ~/)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+## >>> `%dirsAndFiles()` macro: <<< <a name="dirsandfiles-macro"></a> #######################  
+
+The `%dirsAndFiles()` macro allows to extract info about all files 
+and subdirectories of a given `root` directory. 
+
+The extracted info may be just a list of files and subdirectories or, if 
+the `details=` parameter is set to 1, additional operating system information 
+is extracted (information is OSS dependent and gives different results for Linux 
+and for Windows)
+
+The extracted info can be narrowed down to files (`keepFiles=1`) or to 
+directories (`keepDirs=1`) if need be.
+
+The extracted info can be presented in wide or long format (`longFormat=1`).
+
+The extracted info for files can be narrowed down to only files with particular
+extension, for example: `fileExt=sas7bdat`.
+
+The extracted info can be narrowed down maximal path depth 
+by setting up the `maxDepth=` parameter.
+
+See examples below for the details.
+
+### REFERENCES: ###################################################################
+
+The macro is based on Kurt Bremser's "*Talking to Your Host*" article 
+presented at WUSS 2022 conference.
+
+The article is available [here](https://communities.sas.com/t5/SAS-User-Groups-Library/WUSS-Presentation-Talking-to-Your-Host/ta-p/838344)
+and also as an additional content of this package.
+The paper was awarded the "Best Paper Award - Programming".
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%dirsAndFiles(
+    root
+  <,ODS=>
+  <,details=>
+  <,keepDirs=>
+  <,keepFiles=>
+  <,longFormat=>
+  <,fileExt=>
+  <,maxDepth=>
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `root`                     - *Required*, path to be searched
+                                for information.
+
+* `ODS=work.dirsAndFilesInfo` - *Optional*, output data set, 
+                                name of a dataset to store information.
+
+* `details=0`                 - *Optional*, indicates if detailed info 
+                                 will be collected, `1` = yes, `0` = no.
+
+* `keepDirs=1`                - *Optional*, indicates if directories info 
+                                will be collected, `1` = yes, `0` = no.
+
+* `keepFiles=1`               - *Optional*, indicates if files info 
+                                will be collected, `1` = yes, `0` = no.
+
+* `longFormat=0`              - *Optional*, indicates if output be 
+                                in long format, `1` = yes, `0` = no.
+
+* `fileExt=`                  - *Optional*, if not missing then indicates 
+                                file extension to filter out results.
+                                
+* `maxDepth=0`                - *Optional*, if not zero then indicates
+                                maximum depth of search in the root path.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Get list of files and directories:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%dirsAndFiles(C:\SAS_WORK\,ODS=work.result1)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.** Get detailed info:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%dirsAndFiles(C:\SAS_WORK\,ODS=work.result2,details=1)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 3.** Get only files info:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%dirsAndFiles(C:\SAS_WORK\,ODS=work.result3,keepDirs=0)
+
+%dirsAndFiles(C:\SAS_WORK\,ODS=work.result5,keepDirs=0,details=1)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 4.** Get only directories info:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%dirsAndFiles(C:\SAS_WORK\,ODS=work.result4,keepFiles=0)
+
+%dirsAndFiles(C:\SAS_WORK\,ODS=work.result6,keepFiles=0,details=1)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 5.** Filter out by `sas` extension:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%dirsAndFiles(~/,ODS=work.result7,fileExt=sas)
+
+%dirsAndFiles(~/,ODS=work.result8,fileExt=sas,details=1)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 6.** Keep result in the long format:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%dirsAndFiles(~/,ODS=work.result9,details=1,longFormat=1)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 7.** Get info for maximum depth of 2:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%dirsAndFiles(C:\SAS_WORK\,ODS=work.result10,details=1,maxDepth=2)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 8.** How locked/unavailable files are handled:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%dirsAndFiles(%sysfunc(pathname(WORK)),ODS=work.result11,details=1)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 9.** Not existing directory:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%dirsAndFiles(%sysfunc(pathname(WORK))/noSuchDir,ODS=work.result12,details=1)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+## >>> `%repeatTxt()` macro: <<< <a name="repeattxt-macro"></a> #######################  
+
+The repeatTxt() macro function allows to repeat `n` 
+times a `text` string separated by string `s=`.
+
+The repeatTxt() returns unquoted value [by %unquote()].
+
+See examples below for the details.
+
+The `%repeatTxt()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%repeatTxt(
+    text
+  <,n>
+  <,s=>
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `text`       - *Required*, a text to be repeated.
+
+2. `n`          - *Required/Optional*, the number of repetitions.
+                  If missing then set to `1`;
+
+* `s = %str( )` - *Optional*, it is a separator between 
+                  repeated elements. Default value is space.
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Simple repetition of dataset name:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+options mprint;
+data work.test5;
+  set 
+   %repeatTxt(sashelp.cars, 5) 
+    ;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.** Simple repetition of data step:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+options mprint;
+%repeatTxt(data _null_; set sashelp.cars; run;, 3)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 3.** "Nice" output:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%put %repeatTxt(#,15,s=$) HELLO SAS! %repeatTxt(#,15,s=$);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ 
+**EXAMPLE 4.** Macroquote a text with commas:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%repeatTxt( 
+  %str(proc sql; create table wh as select weight,height from sashelp.class; quit;)
+  ,3
+) 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**EXAMPLE 5.** Empty `n` repeats `text` one time:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+options mprint;
+data work.test1;
+  set 
+   %repeatTxt(sashelp.cars) 
+    ;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**EXAMPLE 6.** Dynamic "formatting":
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%macro printWork();
+ %let work=%sysfunc(pathname(work));
+ %put +%repeatTxt(~,%length(&work.)+5,s=)+; 
+ %put {&=work.}; 
+ %put +%repeatTxt(~,%length(&work.)+5,s=)+;
+%mend printWork;
+
+%printWork()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
 ## License ####################################################################
 
 Copyright (c) since 2020 Bartosz Jablonski