Merge pull request #7 from dime-worldbank/repado-schemes

Article for schemes when working with `repado`

src/tests/plus-ado/r/repado.ado

@@ -0,0 +1,124 @@
+*! version 1.0 05NOV2023 DIME Analytics [email protected]
+
+cap program drop   repado
+    program define repado
+
+qui {
+    syntax , adopath(string) mode(string) [lessverbose]
+
+    version 13.0
+
+    /***************************************************************************
+    ****************************************************************************
+      TEST INPUT
+    ****************************************************************************
+    ***************************************************************************/
+
+    * Test adopath input
+    mata : st_numscalar("r(dirExist)", direxists("`adopath'"))
+    if (`r(dirExist)' == 0) {
+      noi di as error `"{phang}The folder path [`adopath'] in adopath(`adopath') does not exist.{p_end}"'
+      error 99
+    }
+
+    * Test mode input
+    if !inlist("`mode'","strict","nostrict") {
+      noi di as error `"{phang}The mode {inp:`mode'} specified in {inp:mode(`mode')} is not valid. Only {inp:strict} and {inp:strict} is allowed. See helpfile {help repado} for more details.{p_end}"'
+      error 99
+    }
+
+    /***************************************************************************
+    ****************************************************************************
+      ADO PATH SECTION
+    ****************************************************************************
+    ***************************************************************************/
+
+    ****
+    * STRICT MODE
+
+    if ("`mode'" == "strict") {
+
+      * Set PLUS to adopath and list it first, then list BASE first.
+      * This means that BASE is first and PLUS is second.
+      sysdir set  PLUS `"`adopath'"'
+      adopath ++  PLUS
+      adopath ++  BASE
+
+      * Keep removing adopaths with rank 3 until only BASE and PLUS,
+      * that has rank 1 and 2, are left in the adopaths
+      local morepaths 1
+      while (`morepaths' == 1) {
+        capture adopath - 3
+        if _rc local morepaths 0
+      }
+
+      * Update the paths where mata search for commands to mirror adopath
+      mata: mata mlib index
+
+    }
+
+    ****
+    * NO STRICT MODE
+
+    else {
+      * Set PERSONAL path to ado path
+      sysdir set  PERSONAL `"`adopath'"'
+      adopath ++  PERSONAL
+      adopath ++  BASE
+    }
+
+    * Print user output
+    noi print_output, adopath("`adopath'") mode("`mode'") `lessverbose'
+
+}  //quietly
+end
+
+
+cap program drop   print_output
+    program define print_output
+
+    syntax , adopath(string) mode(string) [lessverbose]
+
+    ****
+    * Print Intro
+
+    * Strict intro
+    if ("`mode'" == "strict") {
+      noi di as text _n `"{pstd}{inp:repado} has set the PLUS adopath for this Stata session to {inp:`adopath'} and removed all other adopaths except for BASE. PLUS has second priority after BASE.{p_end}"'
+
+    }
+    * No strict intro
+    else {
+      noi di as text _n `"{pstd}{inp:repado} has set the PERSONAL adopath for this Stata session to {inp:`adopath'} and given it second priority after BASE. All other adopaths remain unchanged.{p_end}"'
+    }
+
+    ****
+    * Print details unless lessverbose is used
+    if missing("`lessverbose'") {
+
+      noi di as text _n "{pstd}This means that in this session (until you restart Stata), the following is true:{p_end}"
+
+      * Strict details
+      if ("`mode'" == "strict") {
+        noi di as text `"{phang}- Only Stata's built-in commands in BASE and user-written commands installed in the new PLUS folder {inp:`adopath'} are available to scripts run in this session.{p_end}"'
+        noi di as text `"{phang}- If a script runs without error in this session, it indicates that all user-written commands required by that script are in the new PLUS folder {inp:`adopath'}.{p_end}"'
+        noi di as text `"{phang}- Any other user who has access to the same folder {inp:`adopath'} (shared over Git, a syncing service, etc.) will use the exact same version of the commands installed at that location if they also use {inp:repado} to point to that folder..{p_end}"'
+        noi di as text `"{phang}- In this session, both {help ssc install} and {help net install} will install new commands in the new PLUS folder {inp:`adopath'} instead of the previous location where PLUS was pointing.{p_end}"'
+      }
+
+      * Nostrict details
+      else {
+        noi di as text `"{phang}- User-written commands installed in the new PERSONAL folder {inp:`adopath'} are available to scripts run in this session{p_end}"'
+        noi di as text `"{phang}- Stata's built-in commands in BASE and user-written commands installed in other adopaths, such as PLUS, are also available.{p_end}"'
+        noi di as text `"{phang}- The exact version of user-written commands installed in the new PERSONAL folder {inp:`adopath'} will be used instead of any other version of a user-written command installed with the same name in the PLUS folder.{p_end}"'
+        noi di as text `"{phang}- Any other user who has access to the same folder {inp:`adopath'} (shared over Git, a syncing service, etc.) will use the exact same version of the commands installed at that location if they also use {inp:repado} to point to that folder.{p_end}"'
+        noi di as text `"{phang}- If a script runs without error in this session, then all user-written commands required in the script are either installed in the new PERSONAL folder {inp:`adopath'}, or in any of the other adopaths specified on this user's machine.{p_end}"'
+        noi di as text `"{phang}- Both {help ssc install} and {help net install} will install commands in the PLUS folder as usual and not in the new PERSONAL folder {inp:`adopath'}.{p_end}"'
+      }
+
+      ****
+      * Print outro
+      noi di as text _n "{pstd}You can run {stata adopath} to see your current setting. These settings will be restored the next time you restart Stata.{p_end}"
+    }
+
+end

src/tests/plus-ado/r/repado.sthlp

@@ -0,0 +1,76 @@
+{smcl}
+{* 01 Jan 1960}{...}
+{hline}
+{pstd}help file for {hi:repado}{p_end}
+{hline}
+
+{title:Title}
+
+{phang}{bf:repado} - a command to handle ado-file dependencies
+{p_end}
+
+{title:Syntax}
+
+{phang}{bf:repado} , {bf:adopath}({it:string}) {bf:mode}({it:string}) [{bf:lessverbose}]
+{p_end}
+
+{synoptset 15}{...}
+{synopthdr:options}
+{synoptline}
+{synopt: adopath({it:string})}The file path to the ado-folder to use{p_end}
+{synopt: mode({it:string})}Indicate {it:strict} or {it:nostrict} mode{p_end}
+{synopt: lessverbose}Have less explanatory details in the output{p_end}
+{synoptline}
+
+{title:Description}
+
+{pstd}This command is used to make sure that all users in a project use the exact same version of the commands the project code requires. This is done by creating a folder that we will call the ado-folder. This folder should be shared with the rest of the code of the project. This will work no matter how the files are shared. It can be using a syncing service like DropBox, a Git repository, a network drive, an external hard drive, a .zip folder etc.
+{p_end}
+
+{pstd}Using {inp:repado} in the {it:strict} mode, means that no other commands can be used apart from Stata{c 39}s built in commands and the commands in the shared ado-folder.
+The commands that users have installed on their computers will not be available.
+These settings are restored next time Stata is restarted.
+{p_end}
+
+{pstd}Using {inp:repado} in the {it:nostrict} mode, means that built-commands and the commands ado-folder are available to the script in addition to any command any user has installed on their computer. However, if a command is installed on a user{c 39}s computer that has the same name as a command in the ado-folder, then the exact version of the command in the ado-folder will be used.
+These settings are restored next time Stata is restarted.
+{p_end}
+
+{pstd}While it might seem more convenient to use the {it:nostrict} as default as it makes more command available to the user, we strongly recommend that for all projects that are expected to be reproducible, you use the {it:strict} mode. This is because if you run a script without {c 34}{it:command ... is unrecognized}{c 34} errors in {it:strict} mode, then you are guaranteed that all commands that script requires are indeed in the ado-folder. If you share the ado-folder with the rest of your code, then you know anyone reproducing your code will run your code using the exact same version of your dependencies.
+{p_end}
+
+{title:Options}
+
+{pstd}{bf:adopath}({it:string}) is used to specify where the ado-folder is located within the project folder. To make this reproducible across computers we recommend using a reproducible way of setting the root paths.
+{p_end}
+
+{pstd}{bf:mode}({it:string}) is used to specify which mode is used. It must be specified and can either be {it:strict} or {it:nostrict}. See the Description section above for a description of the differences between the two modes.
+{p_end}
+
+{pstd}{bf:lessverbose} is used to reduce the output that this command produces. The default without this option is that this command outputs how the adopaths has been modified and how that makes running your code different.
+{p_end}
+
+{title:Examples}
+
+{dlgtab:Example 1}
+
+{pstd}In this example the ado-folder is a folder called {inp:ado} in the folder that the global {inp:myproj} is pointing to.
+{p_end}
+
+{input}{space 8}repado , adopath({c 34}{c S|}{c -(}myproj{c )-}/ado{c 34}) mode({c 34}strict{c 34})
+{text}
+{title:Feedback, bug reports and contributions}
+
+{pstd}Read more about the commands in this package at https://dime-worldbank.github.io/repkit.
+{p_end}
+
+{pstd}Please provide any feed back by opening and issue at https://github.com/dime-worldbank/repkit.
+{p_end}
+
+{pstd}PRs with suggestions for improvements are also greatly appreciated.
+{p_end}
+
+{title:Authors}
+
+{pstd}DIME Analytics, The World Bank [email protected]
+{p_end}

src/tests/plus-ado/r/repkit.ado

@@ -0,0 +1,29 @@
+*! version 1.0 05NOV2023 DIME Analytics [email protected]
+
+cap program drop   repkit
+    program define repkit, rclass
+
+    version 13.0
+
+    * UPDATE THESE LOCALS FOR EACH NEW VERSION PUBLISHED
+  	local version "1.0"
+  	local versionDate "05NOV2023"
+
+  	syntax [anything]
+
+  	version 12
+
+    * Prepare returned locals
+    return local versiondate     "`versionDate'"
+    return local version		      = `version'
+
+    * Display output
+    noi di ""
+    local cmd    "repkit"
+    local vtitle "This version of {inp:`cmd'} installed is version:"
+    local btitle "This version of {inp:`cmd'} was released on:"
+    local col2 = max(strlen("`vtitle'"),strlen("`btitle'"))
+    noi di as text _col(4) "`vtitle'" _col(`col2')"`version'"
+    noi di as text _col(4) "`btitle'" _col(`col2')"`versionDate'"
+
+end

src/tests/plus-ado/r/repkit.sthlp

@@ -0,0 +1,45 @@
+{smcl}
+{* 01 Jan 1960}{...}
+{hline}
+{pstd}help file for {hi:repkit}{p_end}
+{hline}
+
+{title:Title}
+
+{phang}{bf:repkit} - Package command with utilities for the rest of the package
+{p_end}
+
+{title:Syntax}
+
+{phang}{bf:repkit}
+{p_end}
+
+{title:Description}
+
+{pstd}This command only returns the version number and version data to the user.
+This command has little application for the user.
+For packages installed on SSC it is important that a there is a command
+in the package that has the same name as the package.
+That is the main purpose of this command.
+{p_end}
+
+{title:Options}
+
+{pstd}This command has no options.
+{p_end}
+
+{title:Feedback, bug reports and contributions}
+
+{pstd}Read more about the commands in this package at https://dime-worldbank.github.io/repkit.
+{p_end}
+
+{pstd}Please provide any feed back by opening and issue at https://github.com/dime-worldbank/repkit.
+{p_end}
+
+{pstd}PRs with suggestions for improvements are also greatly appreciated.
+{p_end}
+
+{title:Authors}
+
+{pstd}DIME Analytics, The World Bank [email protected]
+{p_end}