Merge pull request #19 from SASPAC/dev

The BasePlus package [ver. 1.26.1]

README.md

@@ -29,14 +29,26 @@ format x bool.;
 %put %repeatTxt(#,15,s=$) HELLO SAS! %repeatTxt(#,15,s=$);
 
 %put %intsList(42);
+%put %letters(1:26:1);
 
 %splitDSIntoBlocks(5, sashelp.class, classBlock)
 
 %splitDSIntoParts(7, sashelp.cars, carsPart)
+
+filename f temp;
+%put %filePath(f);
+
+%put %libPath(WORK);
+
+libname NEW "%workPath()/new";
+
+%put %translate(%str("A", "B", "C"),%str(%",),%str(%' ));
+
+%put %tranwrd(Miss Joan Smith,Miss,Ms.);
 ```
 and more.
 
-SHA256 digest for the latest version of `BasePlus`: F*625E56B017C4AA8D436959C0A03C8503773A9A3823D43FA9E0326276E52DA6F2
+SHA256 digest for the latest version of `BasePlus`: F*D6DC5AD1B60A92AD300B639B3C361C1F7846EB01E5AB35BF4FDDA6E783408172
 
 [**Documentation for BasePlus**](./baseplus.md "Documentation for BasePlus")
 

baseplus.md

@@ -53,14 +53,24 @@
   * [`%dirsAndFiles()` macro](#dirsandfiles-macro)
   * [`%repeatTxt()` macro](#repeattxt-macro)
   * [`%intsList()` macro](#intslist-macro)
+  * [`%letters()` macro](#letters-macro)
   * [`%splitDSIntoBlocks()` macro](#splitdsintoblocks-macro)
   * [`%splitDSIntoParts()` macro](#splitdsintoparts-macro)
+  * [`%filePath()` macro](#filepath-macro)
+  * [`%libPath()` macro](#libpath-macro)
+  * [`%workPath()` macro](#workpath-macro)
+  * [`%translate()` macro](#translate-macro)
+  * [`%tranwrd()` macro](#tranwrd-macro)
+  * [`%findDSwithVarVal()` macro](#finddswithvarval-macro)
+  * [`%getTitle()` macro](#gettitle-macro) 
+
+  
   
   * [License](#license)
   
 ---
 
-# The BasePlus package [ver. 1.20.0] <a name="baseplus-package"></a> ###############################################
+# The BasePlus package [ver. 1.26.1] <a name="baseplus-package"></a> ###############################################
 
 The **BasePlus** package implements useful
 functions and functionalities I miss in the BASE SAS.
@@ -202,7 +212,6 @@ Recording from the SAS Explore 2022 conference: [A BasePlus Package for SAS](htt
 %rainCloudPlot(sashelp.cars,DriveTrain,Invoice)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-
 **Example 10**: Zip SAS library.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
 %zipLibrary(sashelp, libOut=work)
@@ -212,7 +221,7 @@ Recording from the SAS Explore 2022 conference: [A BasePlus Package for SAS](htt
 
 **Example 11**: Long dataset names.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
-data %LDSN(  work. peanut butter & jelly time with a "Hot-Dog" in [a box], popcorn, and s*t*a*r*s (drop = sex rename=(name=first_name) where = (age in (12,13,14)))  );
+data %LDSN(  work. peanut butter & jelly with a "Hot-Dog" in [a box], popcorn, and s*t*a*r*s (drop = sex rename=(name=first_name) where = (age in (12,13,14)))  );
   set sashelp.class;
 run;
 
@@ -240,75 +249,114 @@ run;
 %put %repeatTxt(#,15,s=$) HELLO SAS! %repeatTxt(#,15,s=$);
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**EXAMPLE 15** Integer list:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%put %intsList(42);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**EXAMPLE 16** Split dataset into blocks of 5 observations:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%splitDSIntoBlocks(5, sashelp.class, classBlock)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**EXAMPLE 17** Split dataset into 7 parts:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%splitDSIntoParts(7, sashelp.cars, carsPart)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**EXAMPLE 18** Return path to temporary file:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  filename f temp;
+  %put %filePath(f);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**EXAMPLE 19** Get titles:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  title1 j=c "Hi Roger" ;
+  title2 j=l "Good Morning" ;
+  title3 "How are you?" ;
+  title4 ;
+  title5 "Bye bye!" ;
+
+  %put %GetTitle(1 2 3 5, dlm=s, qt='') ;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ---
 
 Package contains: 
-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        intslist
-10. macro        ldsn
-11. macro        ldsnm
-12. macro        lvarnm
-13. macro        lvarnmlab
-14. macro        qdeduplistx
-15. macro        qgetvars
-16. macro        qzipevalf
-17. macro        raincloudplot
-18. macro        repeattxt
-19. macro        splitdsintoblocks
-20. macro        splitdsintoparts
-21. macro        symdelglobal
-22. macro        unziplibrary
-23. macro        zipevalf
-24. macro        ziplibrary
-25. format       bool
-26. format       boolz
-27. format       ceil
-28. format       floor
-29. format       int
-30. functions    arrfill
-31. functions    arrfillc
-32. functions    arrmissfill
-33. functions    arrmissfillc
-34. functions    arrmisstoleft
-35. functions    arrmisstoleftc
-36. functions    arrmisstoright
-37. functions    arrmisstorightc
-38. functions    bracketsc
-39. functions    bracketsn
-40. functions    catxfc
-41. functions    catxfi
-42. functions    catxfj
-43. functions    catxfn
-44. functions    deldataset
-45. functions    semicolonc
-46. functions    semicolonn
-47. format       brackets
-48. format       semicolon
-49. proto        qsortincbyprocproto
-50. functions    frommissingtonumberbs
-51. functions    fromnumbertomissing
-52. functions    quicksort4notmiss
-53. functions    quicksorthash
-54. functions    quicksorthashsddv
-55. 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      intslist
+10. macro      ldsn
+11. macro      ldsnm
+12. macro      lvarnm
+13. macro      lvarnmlab
+14. macro      qdeduplistx
+15. macro      qgetvars
+16. macro      qzipevalf
+17. macro      raincloudplot
+18. macro      repeattxt
+19. macro      splitdsintoblocks
+20. macro      splitdsintoparts
+21. macro      symdelglobal
+22. macro      unziplibrary
+23. macro      zipevalf
+24. macro      ziplibrary
+25. format     bool
+26. format     boolz
+27. format     ceil
+28. format     floor
+29. format     int
+30. functions  arrfill
+31. functions  arrfillc
+32. functions  arrmissfill
+33. functions  arrmissfillc
+34. functions  arrmisstoleft
+35. functions  arrmisstoleftc
+36. functions  arrmisstoright
+37. functions  arrmisstorightc
+38. functions  bracketsc
+39. functions  bracketsn
+40. functions  catxfc
+41. functions  catxfi
+42. functions  catxfj
+43. functions  catxfn
+44. functions  deldataset
+45. functions  semicolonc
+46. functions  semicolonn
+47. format     brackets
+48. format     semicolon
+49. proto      qsortincbyprocproto
+50. functions  frommissingtonumberbs
+51. functions  fromnumbertomissing
+52. functions  quicksort4notmiss
+53. functions  quicksorthash
+54. functions  quicksorthashsddv
+55. functions  quicksortlight
+56. macro      filepath
+57. macro      finddswithvarval
+58. macro      gettitle
+59. macro      letters
+60. macro      libpath
+61. macro      translate
+62. macro      tranwrd
+63. macro      workpath
 
 
 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 *
+* SAS package generated by generatePackage, version 20230520 *
 
 The SHA256 hash digest for package BasePlus: 
-`F*625E56B017C4AA8D436959C0A03C8503773A9A3823D43FA9E0326276E52DA6F2` 
+`F*D6DC5AD1B60A92AD300B639B3C361C1F7846EB01E5AB35BF4FDDA6E783408172` 
 
 ---
 # Content description ############################################################################################
@@ -3081,13 +3129,18 @@ The basic syntax is the following, the `<...>` means optional parameters:
  <,xLabels=>
  <,catLabelPos=> 
  <,xLabelPos=>
+ <,catLabelAttrs=>
+ <,xLabelAttrs=>
  <,formated=>
  <,y2axis=>
  <,y2axisLevels=>
  <,y2axisValueAttrs=>
+ <,catAxisValueAttrs=>
  <,xaxisValueAttrs=>
  <,xaxisTickstyle=>
-
+ <,sganno=>
+ <,odsGraphicsOptions=>
+ <,sgPlotOptions=>
 
  <,VSCALE=>
  <,KERNEL_K=>
@@ -3129,7 +3182,7 @@ The basic syntax is the following, the `<...>` means optional parameters:
                          granularity level, e.g. for data with value 
                          around `1e-8` should be decreased. 
 
-* `rainDropSiz`        - *Optional*, default value `5px`.
+* `rainDropSize`       - *Optional*, default value `5px`.
                          Size of data points in the "rain" plot.
 
 * `boxPlotSymbolSize`  - *Optional*, default value `8px`.
@@ -3172,11 +3225,19 @@ The basic syntax is the following, the `<...>` means optional parameters:
                          Indicates position of the label on data axix (horizontal).
                          Allowed values are `LEFT`, `CENTER`, `DATACENTER`, and `RIGHT`.
 
+* `catLabelAttrs`      - *Optional*, default value is empty. 
+                         List of attributes for group axix labels (vertical).
+                         For details see notes below.
+
+* `xLabelAttrs`        - *Optional*, default value is empty. 
+                         List of attributes for data variable axix labels (horizontal).
+                         For details see notes below.
+
 * `formated`           - *Optional*, default value `0`.
                          Indicates if values of the grouping variable should be formated.
 
 * `y2axis`             - *Optional*, default value `1`.
-                         Indicates if the righ vertical axix should be displayed.
+                         Indicates if the right vertical axix should be displayed.
 
 * `y2axisLevels`       - *Optional*, default value `4`.
                          Indicates if the number of expected levels of values printed 
@@ -3185,6 +3246,9 @@ The basic syntax is the following, the `<...>` means optional parameters:
 * `y2axisValueAttrs`   - *Optional*, default value `Color=Grey`.
                          Allows to modify Y2 axis values attributes.
 
+* `catAxisValueAttrs`  - *Optional*, default value `Color=Black`.
+                         Allows to modify category (Y) axis values attributes.
+
 * `xaxisValueAttrs`    - *Optional*, default value `Color=Grey`.
                          Allows to modify X axis values attributes.
 
@@ -3193,6 +3257,19 @@ The basic syntax is the following, the `<...>` means optional parameters:
                          Allowed values are `OUTSIDE`, `INSIDE`, `ACROSS`, and `INBETWEEN`. 
                          *For SAS previous to* **9.4M5** *set to missing!*
 
+* `sganno`             - *Optional*, default value is empty.
+                         keeps name of a data set for the `sganno=` option
+                         of the SGPLOT procedure.
+
+* `sgPlotOptions`      - *Optional*, default value is `noautolegend noborder`.
+                         List of additional options values for SGPLOT procedure.
+
+* `odsGraphicsOptions` - *Optional*, default value is empty.
+                         List of additional options values for `ODS Graphics` statement.
+                         By default only the: `width=`, `height=`, and `antialiasmax=`
+                         are modified.
+
+
 ***Stat related options***:
 
 * `VSCALE`             - *Optional*, default value `Proportion`.
@@ -3233,6 +3310,9 @@ The basic syntax is the following, the `<...>` means optional parameters:
 * The `catLabels` and `xLabels` should be quoted comma separated lists enclosed with brackets, 
   e.g. `catLabels=("Continent of Origin", "Car Type")`, see Example below.
 
+* The `catLabelAttrs` and `xLabelAttrs` should be space separated lists of `key=value` pairs,
+  e.g. `xLabelAttrs=size=12 color=Pink weight=bold`, see Example below.
+
 * Kernel density estimates and basic statistics are calculated with `PROC UNIVARIATE`.
 
 * Plot is generated by `PROC SGPLOT` with `BAND`, `SCATTE`, and `POLYGON` plots.
@@ -3314,6 +3394,7 @@ The output:
   , y2axisLevels=3
   , catLabels=("Continent of Origin", "Car Type")
   , xLabels="Invoice, [$]"
+  , xLabelAttrs=size=12 color=Pink weight=bold
   )
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3323,6 +3404,61 @@ The output:
 ![Example 2b](./baseplus_RainCloudPlot_Ex2b.png)
 
 
+
+**EXAMPLE 3.** Rain Cloud plot with formatted groups
+               and annotations.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+
+  data annotation; 
+    function="text";
+    label="This graph is full(*ESC*){sup '2'} of annotations!";
+    drawspace="graphpercent";
+    rotate=30;
+    anchor="center";
+    textsize=32;
+    x1=50;
+    y1=50;
+    textcolor="red"; 
+    justify="center";
+    textweight="bold";
+    width=100;
+    widthunit="percent";
+  run; 
+
+  proc format;
+    value system
+    1="Windows"
+    2="MacOS"
+    3="Linux"
+    ;
+  run;
+
+  data test;
+    do system = 1 to 3;
+      do i = 1 to 50;
+        x = rannor(123)/system;
+        output;
+      end;
+    end;
+    format system system.;
+  run;
+
+
+  %RainCloudPlot(test, system, x
+  , colorslist=CX88CCEE CX44AA99 CX117733
+  , formated=1
+  , sganno=annotation
+  , sgPlotOptions=noborder
+  , WidthPX=1000
+  , HeightPX=320
+  , catAxisValueAttrs=Color=Green weight=bold
+  )
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The output:
+![Example 3](./baseplus_RainCloudPlot_Ex3.png)
+
 ---
 
 ## >>> `%zipLibrary()` macro: <<< <a name="ziplibrary-macro"></a> #######################  
@@ -4303,6 +4439,118 @@ The basic syntax is the following, the `<...>` means optional parameters:
 
 ---
 
+## >>> `%letters()` macro: <<< <a name="letters-macro"></a> #######################  
+
+The letters() macro function allows to print a list of Roman
+letters starting from `start` up to `end` incremented by `by`.
+The letters list can be uppercases or lowercase (parameter `c=U` or `c=L`), 
+can be quoted (e.g. `q=""` or `q=[]`), and can be separated by `s=`.
+
+Values of `start`, `end`, and `by` have to be integers in range between 1 ad 26.
+
+See examples below for the details.
+
+The `%letters()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%letters(
+    range
+  <,c=>
+  <,q=>
+  <,s=>
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `range`       - *Required*, letters selector in form `start:end:by`.
+                   Lists letters from `start` to `end` by `by`. 
+                   Values of `start`, `end`, and `by` are separated by 
+                   colon and must be between 1 ad 26.
+                   If value is outside range it is set to 
+                   `start=1`, `en=26`, and `by=1`. If `end` is missing
+                   then is set to value of `start`.
+                   If `end` is smaller than `start` list is reversed
+
+* `c = U`        - *Optional*, it is a lowercase letters indicator. 
+                   Select `L` or `l`. Default value is `U` for upcase.
+
+* `q = `         - *Optional*, it is a quite around elements of the list. 
+                   Default value is empty. Use `%str()` for one quote symbol.
+                   If there are multiple symbols, only the first and the 
+                   second are selected as a preceding and trailing one, 
+                   e.g. `q=[]` gives `[A] [B] ... [Z]`.
+
+* `s = %str( )`  - *Optional*, it is a separator between 
+                   elements of the list. Default value is space.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Space separated list of capital letters from A to Z:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %letters(1:26:1);
+
+  %put %letters();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.** First, thirteenth, and last letter:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %letters(1) %letters(13) %letters(26);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 3.** Every third lowercase letter, i.e. `a d g j m p s v y`:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %letters(1:26:3,c=L);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 4.** Lists with separators:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %letters(1:26:2,s=#);
+  %put %letters(1:26:3,s=%str(;));
+  %put %letters(1:26:4,s=%str(,));
+  %put %letters(1:26,s=);
+  %put %letters(1:26,s==);
+  %put %letters(1:26,s=/);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 5.** Every second letter with quotes:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %letters(1:26:2,q=%str(%'));
+  %put %letters(2:26:2,q=%str(%"));
+
+  %put %letters(1:26:2,q='');
+  %put %letters(2:26:2,q="");
+
+  %put %letters(1:26:2,q=<>);
+  %put %letters(2:26:2,q=\/);
+
+  %put %letters(1:26:2,q=());
+  %put %letters(2:26:2,q=][);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 6.** Mix of examples 4, 5, and 6:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %letters(1:26,c=L,q='',s=%str(, ));
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 7.** If `end` is smaller than `start` list is reversed:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %letters(26:1:2,q='');
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
 ## >>> `%splitDSIntoBlocks()` macro: <<< <a name="splitdsintoblocks-macro"></a> #######################  
 
 The splitDSIntoBlocks() macro allows to split the `set` dataset into blocks 
@@ -4441,6 +4689,434 @@ The basic syntax is the following, the `<...>` means optional parameters:
   %splitDSIntoParts(3,test.test,work.spde)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+---
+
+## >>> `%filePath()` macro: <<< <a name="filepath-macro"></a> #######################  
+
+The filePath() macro function returns path to a file,
+it is a wrapper to `pathname()` function for files.
+
+See examples below for the details.
+
+The `%filePath()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%filePath(
+    fileref
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `fileref` - *Required*, a fileref from the `filename` statement.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Return path to temporary file:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  filename f temp;
+  %put %filePath(f);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+## >>> `%libPath()` macro: <<< <a name="libpath-macro"></a> #######################  
+
+The libPath() macro function returns path to a library,
+it is a wrapper to `pathname()` function for libraries.
+
+See examples below for the details.
+
+The `%libPath()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%libPath(
+    libref
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `libref` - *Required*, a libref from the `libname` statement.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Return path to `WORK` library:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %libPath(WORK);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.** Return path to `SASHELP` library:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %libPath(SASHELP);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+## >>> `%workPath()` macro: <<< <a name="workpath-macro"></a> #######################  
+
+The workPath() macro function returns path to the `WORK` library,
+it is a wrapper to `pathname("work", "L")` function.
+
+See examples below for the details.
+
+The `%workPath()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%workPath()
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+*) No arguments.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Create new library inside `WORK` library:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  options dlCreateDir;
+  libname NEW "%workPath()/new";
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+## >>> `%translate()` macro: <<< <a name="translate-macro"></a> #######################  
+
+The translate() macro function allows to replace bytes with bytes in text string.
+
+See examples below for the details.
+
+The `%translate()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%translate(
+    string
+   ,from
+   ,to
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `string`       - *Required*, string to modify.
+
+2. `from`         - *Required*, list of bytes to be replaced with 
+                    corresponding bytes from `to`.
+
+3. `to`           - *Required*, list of bytes replacing
+                    corresponding bytes from `from`. 
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Replace quotes and commas with apostrophes and spaces:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %translate(%str("A", "B", "C"),%str(%",),%str(%' ));
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.** Unify all brackets;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %translate(%str([A] {B} (C) <D>),{[(<>)]},(((()))));
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 3.** Replace all digits with `*`:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+    %put %translate(QAZ1WSSX2EDC3RFV4TGB5YHN6UJM7IK8OL9P0,1234567890,**********);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 4.** Letters change:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+    %put %translate(%str(A=B),AB,BA);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+## >>> `%tranwrd()` macro: <<< <a name="tranwrd-macro"></a> #######################  
+
+The tranwrd() macro function allows to replace substrings 
+with other substrings in text string.
+
+Returned string is unquoted by `%unquote()`.
+
+See examples below for the details.
+
+The `%tranwrd()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%tranwrd(
+    string
+   ,from
+   ,to
+  <,repeat>
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `string`       - *Required*, string to modify.
+
+2. `from`         - *Required*, substring replaced with 
+                    corresponding string from `to`.
+
+3. `to`           - *Required*, substring replacing
+                    corresponding substring from `from`. 
+
+4. `repeat`       - *Optional*, number of times the replacing
+                    should be repeated, default is 1.
+                    Useful while removing multiple adjacent 
+                    characters, e.g. compress all multiple 
+                    spaces (see example 2).
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Simple text replacement:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %tranwrd(Miss Joan Smith,Miss,Ms.);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.** Delete multiple spaces;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %tranwrd(%str(A      B   C),%str(  ),%str( ),5);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 3.** Remove substring:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+    %put %tranwrd(ABCxyzABCABCxyzABC,ABC);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+## >>> `%findDSwithVarVal()` macro: <<< <a name="finddswithvarval-macro"></a> #######################  
+
+The findDSwithVarVal() macro searches for all 
+datasets (available for a given session) containing 
+a variable of a given value.
+
+The value search is case sensitive - but can be altered with `IC=` parameter.
+The value search keeps leading blanks - but can be altered with `TB=` parameter.
+The value search compares full value - but can be altered with `CTS=` parameter.
+
+The default variable type is `char`, the `type=` parameter allows 
+to change it (possible values are `char` and `num`), the parameter is case sensitive.
+
+Only datasets are searched, views are not included.
+
+During the process two temporary datasets named: 
+`WORK._` (single underscore) and `WORK.__` (double underscore) 
+are generated. The datasets are deleted at the end of the process.
+
+By default search results are stored in the `WORK.RESULT` dataset.
+Name of the dataset can be altered with `result=` parameter.
+The dataset with result contains two variables:
+`datasetName` - names of datasets,
+`firstObservation` - the firs occurrence of the value.
+
+See examples below for the details.
+
+The `%findDSwithVarVal()` macro does not execute as a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%findDSwithVarVal(
+    variable
+   ,value
+  <,type=>
+  <,ic=>
+  <,tb=>
+  <,cts=>
+  <,lib=>
+  <,result=>
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `variable`     - *Required*, name of variable to be searched.
+
+2. `value`        - *Required*, the value to be searched.
+
+*. `type`         - *Optional*, default value is `char`.
+                    Indicates which type is the searched value.
+                    Possible values are `char` and `num`, 
+                    the parameter is case sensitive. 
+
+*. `ic`           - *Optional*, "Ignore Cases", default value is `0`.
+                    Indicates should the search ignore cases of the text values.
+                    Possible values are `0` and `1`.
+
+*. `tb`           - *Optional*, "Trim Blanks", default value is `0`.
+                    Indicates should the search trim leading and trailing
+                    blanks of the text values.
+                    Possible values are `0` and `1`.
+
+*. `cts`          - *Optional*, "Compare To Shorter", default value is `0`.
+                    IF set to `1` execute value comparison as `=:` for the text value.
+                    Possible values are `0` and `1`.
+                    See examples.
+
+*. `lib`          - *Optional*, default value is missing.
+                    If not empty narrows the search to a particular library.
+
+*. `result`       - *Optional*, default value is `WORK.RESULT`.
+                    Is the name of the dataset with results.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Search variable `NAME` containing value `John`:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %findDSwithVarVal(name, John)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.** Search numeric variable `AGE` containing value `14`:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %findDSwithVarVal(age, 14, type=num)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 3.** Search numeric variable `SCORE` with missing value:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+    data TEST;
+      score=17; output;
+      score=42; output;
+      score=. ; output;
+    run;
+    
+    %findDSwithVarVal(score, ., type=num, result=WORK.MissingScore)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 4.** Search library `WORK` for variable `NAME` starting with value `Jo` 
+               ignoring cases and trimming blanks from value:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  data A;
+    name="Joanna";
+  data B;
+    name="john";
+  data C;
+    name="  Joseph";
+  data D;
+    name="  joe";
+  run;
+
+  %findDSwithVarVal(name, Jo, ic=1, tb=1, cts=1, lib=WORK)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+## >>> `%getTitle()` macro: <<< <a name="gettitle-macro"></a> #######################  
+
+The getTitle() macro extract text of titles or footnotes
+into a delimited list.
+
+Titles/footnotes numbers can be selected with the `number` argument.
+Only the text of a title or footnote is extracted.
+
+Author of the original code is: Quentin McMullen (`qmcmullen.sas@gmail.com`).
+
+See examples below for the details.
+
+The `%getTitle()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%getTitle(
+  < number>
+  <,type=> 
+  <,dlm=>
+  <,qt=>
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `number`       - *Optional*, default value is empty,
+                    indicates numbers of titles to be extracted.
+                    Space separated list is expected.
+                    If empty or `_ALL_` extract all non-missing.
+
+*. `type`         - *Optional*, default value is `T`.
+                    Indicates which type is the searched.
+                    `T` fro title, `F` for footnote.
+
+*. `dlm`          - *Optional*, "DeLiMiter", default value is `|` (pipe).
+                    Possible values are: `| \ / , . ~ * # @ ! + - _ : ?`
+                    or `s` for space, `c` for comma, `d` for semicolon.
+
+*. `qt`           - *Optional*, "QuoTes", default value is empty.
+                    Use `%str()` for single quote symbol (e.g. `%str(%")`).
+                    If there are multiple symbols, only the first and the 
+                    second are selected as a leading and trailing one, 
+                    e.g. `qt=""` gives `"title1 text" "title2 text" ... `.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Get titles in different forms:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  title1 j=c "Hi Roger" ;
+  title2 j=l "Good Morning" ;
+  title3 "How are you?" ;
+  title4 ;
+  title5 "Bye bye!" ;
+
+  %put %GetTitle() ;
+
+  %put %GetTitle(1 3,dlm=c, qt=[]) ;
+
+  %put %GetTitle(2:4,dlm=s, qt='') ;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.**  Get footnotes in different forms:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  footnote1 "First little footnote";
+  footnote2 "Second little footnote";
+  footnote3 "Third little footnote";
+
+  %put %GetTitle(1 2,type=f,dlm=s, qt="") ;
+  %put %GetTitle(2 3,type=f,dlm=c, qt='') ;
+  %put %GetTitle(1 3,type=f,dlm=d, qt=[]) ;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+
+
 ---
 
 ---