Merge pull request #51 from SASPAC/dev

The BasePlus package [ver. 3.0.0]

README.md

@@ -53,10 +53,12 @@ libname NEW "%workPath()/new";
 %put %monthShift(2023,1,-5);
 
 %put #%expandDataSetsList(lib=sashelp,datasets=_all_)#;
+
+%workLib(ABC)
 ```
 and more.
 
-SHA256 digest for the latest version of `BasePlus`: F*FB102C9B12E870666C15A651017D48E0141E47D64C11437350D0EC75A7E9E609
+SHA256 digest for the latest version of `BasePlus`: F*B9F6D8F1EDD1ECDA89F4BE327C4F4202649475D1D9DFB476279B633D9F14125D
 
 [**Documentation for BasePlus**](./baseplus.md "Documentation for BasePlus")
 

baseplus.md

@@ -9,22 +9,22 @@
 ### Version information:
   
 - Package: BasePlus
-- Version: 2.0.1
+- Version: 3.0.0
-- Generated: 2024-07-24T07:58:59
+- Generated: 2025-10-15T10:13:04
-- Author(s): Bartosz Jablonski (yabwon@gmail.com), Quentin McMullen (qmcmullen@gmail.com)
+- Author(s): Bartosz Jablonski (yabwon@gmail.com), Quentin McMullen (qmcmullen@gmail.com), Ryo Nakaya (nakaya.ryou@gmail.com)
 - Maintainer(s): Bartosz Jablonski (yabwon@gmail.com)
 - License: MIT
-- File SHA256: `F*FB102C9B12E870666C15A651017D48E0141E47D64C11437350D0EC75A7E9E609` for this version
+- File SHA256: `F*B9F6D8F1EDD1ECDA89F4BE327C4F4202649475D1D9DFB476279B633D9F14125D` for this version
-- Content SHA256: `C*0444AC5B54150AE5424D335FF89A03D831F00F60898C99250CD59E0C5C5B0398` for this version
+- Content SHA256: `C*680412F6B403870A3A8975FC17300F7C92AEDECA48D3F242B5BC4E545DC6D313` for this version
   
 ---
  
-# The `BasePlus` package, version: `2.0.1`;
+# The `BasePlus` package, version: `3.0.0`;
   
 ---
  
 
-# The BasePlus package [ver. 2.0.1] <a name="baseplus-package"></a> ###############################################
+# The BasePlus package [ver. 3.0.0] <a name="baseplus-package"></a> ###############################################
 
 The **BasePlus** package implements useful
 functions and functionalities I miss in the BASE SAS.
@@ -47,7 +47,8 @@ Kudos to all who inspired me to generate this package:
 *Quentin McMullen*,
 *Kurt Bremser*,
 *Leonid Batkhan*,
-*Louise Hadden*.
+*Louise Hadden*,
+*Ryo Nakaya*.
 
 ---
 
@@ -387,6 +388,11 @@ proc print data=b_x;
 run;
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**EXAMPLE 29** Create library ABC assigned to `<WORK>/ABC` directory:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %workLib(abc)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ---
   
 ---
@@ -403,7 +409,7 @@ localization (only if additional content was deployed during the installation pr
  
 --------------------------------------------------------------------
  
-*SAS package generated by SAS Package Framework, version `20240711`*
+*SAS package generated by SAS Package Framework, version `20250729`*
  
 --------------------------------------------------------------------
  
@@ -490,10 +496,11 @@ The `BasePlus` package consists of the following content:
 78. [`%translate()` macro ](#translate-macro-78 )
 79. [`%tranwrd()` macro ](#tranwrd-macro-79 )
 80. [`%unifyvarscasesize()` macro ](#unifyvarscasesize-macro-80 )
-81. [`%workpath()` macro ](#workpath-macro-81 )
+81. [`%worklib()` macro ](#worklib-macro-81 )
+82. [`%workpath()` macro ](#workpath-macro-82 )
   
  
-82. [License note](#license)
+83. [License note](#license)
   
 ---
  
@@ -838,6 +845,7 @@ The basic syntax is the following, the `<...>` means optional parameters:
   <,longFormat=>
   <,fileExt=>
   <,maxDepth=>
+  <,backslashSens=>
 )
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -868,6 +876,11 @@ The basic syntax is the following, the `<...>` means optional parameters:
 * `maxDepth=0`                - *Optional*, if not zero then indicates
                                 maximum depth of search in the root path.
 
+* `backslashSens=0`           - *Optional*, if not zero then it indicates 
+                                that backslash(`\`) symbol in files and dirs 
+                                names is detectable under Linux. Accepted 
+                                values: `0` and `1`. Ignored under Windows. 
+
 
 ### EXAMPLES AND USECASES: ####################################################
 
@@ -989,7 +1002,12 @@ The QgetVars() returns quoted value [by %superq()].
 
 See examples below for the details.
 
-The `%getVars()` macro executes like a pure macro code.
+When `mcArray=` is not used the `%getVars()` macro executes like 
+a pure macro code. When `mcArray=` is not null (creation of a
+macro variable array is requested) them a single semicolon is returned.
+
+When `validvarname=ANY` in set special care should be kept.
+See dedicated examples below.
 
 ### SYNTAX: ###################################################################
 
@@ -1003,6 +1021,7 @@ The basic syntax is the following, the `<...>` means optional parameters:
  <,quote=>
  <,mcArray=> 
  <,ignoreCases>
+ <,nlit=>
 )
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1025,23 +1044,32 @@ The basic syntax is the following, the `<...>` means optional parameters:
 
 * `mcArray=`         - *Optional*, default value is blank.
                        1) When *null* - the macro behaves like a macro function 
-                          and returns a text string with variables list.
+                          and ban be used in the `%put` or `%let=` statements.
-                       2) When *not null* - behaviour of the macro is altered.
+                          The returned text is a string with variables list.
+                       2) When *not null* - behavior of the macro is altered.
                           In such case a macro array of selected variables, named 
                           with `mcArray` value as a prefix, is created.
                           Furthermore a macro named as `mcArray` value is generated.
                           (see the macroArray package for the details).
                           When `mcArray=` parameter is active the `getVars` macro 
-                          cannot be called within the `%put` statement. Execution like: 
+                          should not be called within the `%put` or `%let=` statements. 
-                           `%put %getVars(..., mcArray=XXX);` will result with  
+                          A single semicolon is produced as the macro result, hence
-                          an Explicit & Radical Refuse Of Run (aka ERROR).
+                          execution like: `%put %getVars(..., mcArray=XXX) some text;` 
+                          will result with an Explicit & Radical Refuse Of Run (aka ERROR).
 
-* `ignoreCases=`     - *Optional*, default value is 1.  
+* `ignoreCases=`     - *Optional*, default value is 1.
                         Indicates if search should be case insensitive.
 
+* `nlit=`            - *Optional*, default value is 0.
+                        Introduced to improve `validvarname=ANY` handling.
+                        Indicates if the `NLITERAL()` function should be 
+                        executed to cover spacial characters.
+
  
 ### EXAMPLES AND USECASES: ####################################################
 
+**When `validvarname=` option is _not_ `ANY`.** 
+
 **EXAMPLE 1.** A list of all variables from the 
                sashelp.class dataset:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
@@ -1267,6 +1295,44 @@ run;
   %put %do_over(XYZ);
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**When the `validvarname=ANY` option is set.** 
+
+**EXAMPLE 12.** Get all variables and handle special characters.
+                Without `nlit=1` the code will fail.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  options validvarname = any;
+  data varnameANY;
+    set sashelp.class(obs=3);
+
+    'A&B'n=42;
+    'space name'n=101;
+    '2025-08'n=234;
+    '2025%09'n=235;
+    "2025'10"n=236;
+    '2025"11'n=237;
+  run; 
+
+  %put %getVars(varnameANY, nlit=1);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**EXAMPLE 13.** Create macro variable array ABC for all variables.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %getVars(varnameANY, mcArray=ABC, nlit=1);
+  %put %ABC(1) %ABC(6) %ABC(7) %ABC(11);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**EXAMPLE 14.** Get only variables with illegal characters in names.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %let notV7compliant = %getVars(varnameANY, pattern=[^a-z0-9_], nlit=1);
+  %put &notV7compliant.;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 14.** Print variables starting with a digit.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %getVars(varnameANY, pattern=^\d, nlit=1);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ---
 
   
@@ -1929,6 +1995,11 @@ The basic syntax is the following, the `<...>` means optional parameters:
 * `ignoreCases=`     - *Optional*, default value is 1.  
                         Indicates if search should be case insensitive.
 
+* `nlit=`            - *Optional*, default value is 0.
+                        Introduced to improve `validvarname=ANY` handling.
+                        Indicates if the `NLITERAL()` function should be 
+                        executed to cover spacial characters.
+
  
 ### EXAMPLES AND USECASES: ####################################################
 
@@ -2035,6 +2106,9 @@ plots of kernel density estimates, jitter data values, and box-and-whiskers plot
 
 See examples below for the details.
 
+The "Here Comes the Rain (Cloud Plot) Again" (B. Jablonski, 2024) article
+describing the macro is attached as an additional content to the package.
+
 ### SYNTAX: ###################################################################
 
 The basic syntax is the following, the `<...>` means optional parameters:
@@ -2052,6 +2126,7 @@ The basic syntax is the following, the `<...>` means optional parameters:
  <,boxPlotSymbolSize=>
  <,boxPlotLineSize=>
  <,boxPlotFill=>
+ <,whiskerScale=>
  <,meanShiftLine=>
  <,meanShiftStep=>
  <,meanShiftColors=>
@@ -2147,6 +2222,12 @@ The basic syntax is the following, the `<...>` means optional parameters:
                          Transparency of the box plot.
                          Ranges from 0.0 (opaque) to 1.0 (full translucent).
 
+* `whiskerScale=`      - *Optional*, default value `1.5`.                         
+                         It provides `WS` parameter in the `Q1 - WS*IQR`
+                         formula and the `Q3 + WS*IQR` formula.
+                         Provided value should be a positive number. 
+                         Otherwise it is set to 0.
+
 * `meanShiftLine`      - *Optional*, default value `0`.
                          Indicates if a line connecting mean symbol 
                          on the Box Plot should be added.
@@ -2366,12 +2447,14 @@ The basic syntax is the following, the `<...>` means optional parameters:
 
 The box-and-whiskers plot has the following interpretation: 
 - left vertical bar indicates the *minimum*,
-- left whisker line starts at `max(Q1 - 1.5IQR, minimum)` and ends at lower quartile (Q1),
+- left whisker line starts at `max(Q1 - WS*IQR, minimum)` and ends at lower quartile (Q1),
 - diamond indicates mean,
 - vertical bar inside of the box indicates median,
-- right whisker line starts at upper quartile (Q3) and ends at `min(Q3 + 1.5IQR, maximum)`,
+- right whisker line starts at upper quartile (Q3) and ends at `min(Q3 + WS*IQR, maximum)`,
 - right vertical bar indicates the *maximum*.
 
+The `WS` value is provided through `whiskerScale=` parameter. Default value is `1.5`.
+
 With above setup it may happen that 
 there is a gap between the minimum marker and the beginning of the left whisker 
 or 
@@ -2533,6 +2616,7 @@ The output can be seen in the `md` file.
   , vertical = 1
   , title = %nrstr(title1 J=C HEIGHT=3 "The VERTICAL plotting is cool, ...";)
   , footnote = %nrstr(footnote1 J=L HEIGHT=2 "... isn't it?";)
+  , whiskerScale = 1.5
   )
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -6382,7 +6466,7 @@ The basic syntax is the following, the `<...>` means optional parameters:
 
 3. `false` - *Required*, value returned when condition is false.
 
-4 `v=`     - *Optional*, v for verbose. If set to `1` extra notes
+* `v=`     - *Optional*, v for verbose. If set to `1` extra notes
               are printed.
 ---
 
@@ -7542,7 +7626,71 @@ run;
   
 ---
  
-## `%workpath()` macro <a name="workpath-macro-81"></a> ######
+## `%worklib()` macro <a name="worklib-macro-81"></a> ######
+
+## >>> `%workLib()` macro: <<< <a name="worklib-macro"></a> ####################### 
+
+The `%workLib()` macro creates and assigns a WORK-scoped sub-library.
+
+Purpose:
+
+The macro creates (if needed) and assigns a SAS library as a sub-directory 
+under the current `WORK` location. This is useful for isolating temporary 
+outputs per task while ensuring automatic cleanup at the end of the SAS session.
+Basic engines libraries, like `BASE`, `V*`, and simple `SPDE`, can be set.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%workLib(lib,<engine>)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+ 
+- `lib`    - *Required*: Name of a library (and sub-folder) 
+             to create under WORK. The value must be a valid 
+             nonempty SAS libref (8 characters max, starting 
+             with a letter or underscore).
+
+- `engine` - *Optional*, Name of a basic, directory level, 
+             SAS engine, e.g. `BASE`. When empty the default
+             engine is used.
+---
+
+### Details  
+
+- Builds a target path: `<WORK>/<lib>`.
+- All data written to this libref are temporary and will be removed 
+  when the WORK library is cleared at session end.
+- If a directory with the same name already exists under WORK, 
+  the macro prints a note and simply assigns the LIBNAME to 
+  that location.
+- The `dcreate()` function is used to create sub-directory.
+
+ 
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Create basic library ABC:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %workLib(abc)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**EXAMPLE 2.** Create libraries with different engines:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %workLib(b,BASE)
+
+  %workLib(v,V6) %* for Windows only.;
+
+  %workLib(s,SPDE)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+  
+---
+ 
+## `%workpath()` macro <a name="workpath-macro-82"></a> ######
  
 ## >>> `%workPath()` macro: <<< <a name="workpath-macro"></a> #######################  
 
@@ -7585,7 +7733,7 @@ The basic syntax is the following, the `<...>` means optional parameters:
  
 # License <a name="license"></a> ######
  
-Copyright (c) 2020 - 2023 Bartosz Jablonski
+Copyright (c) 2020 - 2025 Bartosz Jablonski
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal