Merge pull request #32 from SASPAC/dev

The BasePlus package [ver. 1.35.1]

README.md

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

baseplus.md

@@ -47,6 +47,7 @@
   * [`%unzipLibrary()` macro](#unziplibrary-macro)
   * [`%zipArch()` macro](#ziparch-macro)
   * [`%unzipArch()` macro](#unziparch-macro)
+  * [`%downloadFilesTo()` macro](#downloadfilesto-macro)
   * [`%LDSN()` macro](#ldsn-macro)
   * [`%LDsNm()` macro](#ldsnm-macro)
   * [`%LVarNm()` macro](#lvarnm-macro)
@@ -80,7 +81,7 @@
   
 ---
 
-# The BasePlus package [ver. 1.34.0] <a name="baseplus-package"></a> ###############################################
+# The BasePlus package [ver. 1.35.1] <a name="baseplus-package"></a> ###############################################
 
 The **BasePlus** package implements useful
 functions and functionalities I miss in the BASE SAS.
@@ -102,7 +103,8 @@ Kudos to all who inspired me to generate this package:
 *Michal Ludwicki*,
 *Quentin McMullen*,
 *Kurt Bremser*,
-*Leonid Batkhan*.
+*Leonid Batkhan*,
+*Louise Hadden*.
 
 ---
 
@@ -400,6 +402,16 @@ run;
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**EXAMPLE 26** Downloading data from the internet to a local dirrectory:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%downloadFilesTo(~/directoryA)
+datalines4;
+https://www.lexjansen.com/wuss/2023/WUSS-2023-Paper-189.pdf
+https://www.lexjansen.com/wuss/2023/WUSS-2023-Paper-189.zip
+;;;;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 
 ---
 
@@ -463,21 +475,22 @@ Package contains:
 57.  functions  quicksortlight 
 58.  macro      date 
 59.  macro      datetime 
-60.  macro      filepath 
+60.  macro      downloadfilesto 
-61.  macro      finddswithvarval 
+61.  macro      filepath 
-62.  macro      fmt 
+62.  macro      finddswithvarval 
-63.  macro      gettitle 
+63.  macro      fmt 
-64.  macro      infmt 
+64.  macro      gettitle 
-65.  macro      letters 
+65.  macro      infmt 
-66.  macro      libpath 
+66.  macro      letters 
-67.  macro      minclude 
+67.  macro      libpath 
-68.  macro      monthshift 
+68.  macro      minclude 
-69.  macro      replist 
+69.  macro      monthshift 
-70.  macro      time 
+70.  macro      replist 
-71.  macro      today 
+71.  macro      time 
-72.  macro      translate 
+72.  macro      today 
-73.  macro      tranwrd 
+73.  macro      translate 
-74.  macro      workpath 
+74.  macro      tranwrd 
+75.  macro      workpath
 
 
 
@@ -488,7 +501,7 @@ localization (only if additional content was deployed during the installation pr
 * SAS package generated by generatePackage, version 20231107 *
 
 The SHA256 hash digest for package BasePlus: 
-`F*D84CE41A550DC2D5C092C70C04A796E8329F34087A603BEF0CD366910C162E80` 
+`F*BCD89EDF856762EB8E441BC53933774483258453D1F7D74185F8A1861E414B0E` 
 
 ---
 # Content description ############################################################################################
@@ -4051,6 +4064,125 @@ filename pR "%workPath()";
 
 ---
 
+## >>> `%downloadFilesTo()` macro: <<< <a name="downloadfilesto-macro"></a> #######################  
+
+The downloadFilesTo() macro copy files (in binary mode
+using `filename()` function with options `lrecl=1 recfm=n`) 
+from list provided by user to a directory indicated 
+in the macro call.
+
+Macro can be executed in two possible ways:
+1) by providing list of files to download in a `datalines4`(`cards4`) list 
+   directly after macro call:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %downloadFilesTo(</path/to/target/directory>)
+  datalines4;
+  <link to file1>
+  <link to file2>
+   ...
+  <link to fileN>
+  ;;;;
+  run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+2) by create a dataset with a list of links and use of `DS=` and `DSvar=` parameters.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %downloadFilesTo(</path/to/target/directory>
+  , DS=<dataset with list>
+  , DSvar=<variable with list>
+  )
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See examples below for the details.
+
+The `%downloadFilesTo()` macro **does not** execute as a pure macro code.
+
+Temporary dataset `work.______locationInfoData` is generated during processing.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%downloadFilesTo(
+    target
+  <,DS=>
+  <,DSvar=link>
+  <,inDev=URL>
+  <,outDev=DISK>
+  <,inOptions=>
+  <,outOptions=>
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `target  `     - *Required*, a path to target directory.
+                    If empty the `WORK` location is used.
+
+*. `DS= `         - *Optional*, name of data set with list 
+                    of files to download. 
+
+*. `DSvar= `      - *Optional*, name of variable in data set 
+                    with list of files to download. 
+
+
+*. `inDev=`       - *Optional*, type of device used by the 
+                    `filename()` function to access incoming files.
+                    Default value is `URL`.
+
+*. `outDev=`      - *Optional*, type of device used by the 
+                    `filename()` function to access outgoing files.
+                    Default value is `DISK`.
+
+*. `inOptions=`   - *Optional*, list of additional options for the 
+                    `filename()` function to access incoming files.
+                    Default value is empty.
+
+*. `outOptions=`  - *Optional*, list of additional options for the 
+                    `filename()` function to access outgoing files.
+                    Default value is empty.
+
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Download data from web with diect list and then copy between directories:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+resetline;
+%downloadFilesTo(~/directoryA)
+datalines4;
+https://www.lexjansen.com/wuss/2023/WUSS-2023-Paper-189.pdf
+https://www.lexjansen.com/wuss/2023/WUSS-2023-Paper-189.zip
+;;;;
+run;
+
+%downloadFilesTo(~/directoryB,inDev=DISK)
+datalines4;
+~/directoryA/WUSS-2023-Paper-189.pdf
+~/directoryA/WUSS-2023-Paper-189.zip
+;;;;
+run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.** Download data from web using data set with list:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+resetline;
+data listOfFiles;
+infile cards;
+input files :$1024.;
+cards4;
+https://www.lexjansen.com/wuss/2023/WUSS-2023-Paper-201.pdf
+https://www.lexjansen.com/wuss/2023/WUSS-2023-Paper-109.pdf
+;;;;
+run;
+
+%downloadFilesTo(R:\directoryC, DS=listOfFiles, DSvar=files)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
 ## >>> `%LDSN()` macro: <<< <a name="ldsn-macro"></a> #######################  
 
 The LDSN (Long DataSet Names) macro function