├── LICENSE ├── README.md ├── here.ado ├── here.hlp ├── here.pkg └── stata.toc /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Miklós Koren 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # here 2 | `here` is a Stata package roughly replicating the behavior of the R library with the same name. 3 | 4 | ## Installation 5 | 6 | Install with `net install`: 7 | 8 | ``` 9 | net install here, from("https://raw.githubusercontent.com/korenmiklos/here/master/") 10 | ``` 11 | 12 | ## Usage 13 | 14 | Type the command `here` anywhere inside a project folder and it will put the *root* of the project folder into a global macro called `here`. 15 | 16 | ``` 17 | . pwd 18 | /Users/koren/projects/social-distancing/analysis/counterfactual 19 | 20 | . here 21 | /Users/koren/projects/social-distancing 22 | 23 | . display "${here}" 24 | /Users/koren/projects/social-distancing 25 | 26 | . import delimited "${here}/data/raw/bls/employment.csv" 27 | ``` 28 | 29 | To fix the root folder, use `here, set`. 30 | 31 | ``` 32 | . cd "/Users/koren/projects/social-distancing/analysis" 33 | /Users/koren/projects/social-distancing/analysis 34 | 35 | . here, set 36 | /Users/koren/projects/social-distancing/analysis 37 | 38 | . display ${here} 39 | /Users/koren/projects/social-distancing/analysis 40 | ``` 41 | 42 | ## Under the hood 43 | 44 | With the basic usage, `here` looks for a parent folder with the (empty) file `.here` in it. Suppose you have the following folder structure. 45 | 46 | ``` 47 | . 48 | ├── .here 49 | ├── analysis 50 | │   ├── counterfactual 51 | │   │   └── simulate.do 52 | │   └── regress.do 53 | └── data 54 | └── raw 55 | └── employment.csv 56 | ``` 57 | 58 | Whether you call `here` from `analysis/regress.do` or from `analysis/counterfactual/simulate.do`, the value of `${here}` will be absolute path of the folder containing the file `.here`. Whevener you issue 59 | ``` 60 | here, set 61 | ``` 62 | here will put a file called `.here` in your current folder. 63 | 64 | `here` will also stop if it finds a `.git` folder, with the understanding that git repositories are typically in the root of a project folder. But if this is not case for your project, you can turn off this behavior with the otion 65 | 66 | ``` 67 | here, nogit 68 | ``` 69 | -------------------------------------------------------------------------------- /here.ado: -------------------------------------------------------------------------------- 1 | program define here, rclass 2 | syntax [, nogit set] 3 | 4 | tempname here 5 | 6 | if ("`set'"=="set") { 7 | tempname myfile 8 | file open `myfile' using ".here", write replace 9 | 10 | local `here' = c(pwd) 11 | } 12 | else { 13 | tempname current previous 14 | local `current' = c(pwd) 15 | 16 | * are we there yet? 17 | are_we_there_yet, `git' 18 | while (_rc) { 19 | * if not, go up one level 20 | 21 | local `previous' = c(pwd) 22 | capture quietly cd ".." 23 | 24 | * if at root folder, cd .. might fail or keep pwd the same 25 | * in either case, we have not found .here so stop with an error 26 | if (_rc) | ("`c(pwd)'" == "``previous''") { 27 | break_with_error, directory(``current'') 28 | } 29 | are_we_there_yet, `git' 30 | } 31 | 32 | local `here' = c(pwd) 33 | quietly cd "``current''/" 34 | } 35 | return local here "``here''/" 36 | global here "``here''/" 37 | display "``here''/" 38 | end 39 | 40 | program define are_we_there_yet 41 | syntax [, nogit] 42 | 43 | capture confirm file ".here" 44 | if (_rc != 0) & ("`git'" != "nogit") { 45 | capture confirm file ".git/config" 46 | } 47 | end 48 | 49 | program define break_with_error 50 | syntax , directory(string) 51 | 52 | display in red "Project folder not found." 53 | quietly cd "`directory'/" 54 | error 170 55 | end 56 | -------------------------------------------------------------------------------- /here.hlp: -------------------------------------------------------------------------------- 1 | .- 2 | help for ^here^ 3 | .- 4 | 5 | A Simpler Way to Find Your Files 6 | -------------------------------- 7 | 8 | ^here^ [, ^set^ ^nogit^ ] 9 | 10 | Installation 11 | ------------ 12 | 13 | ^net install here, from("https://raw.githubusercontent.com/korenmiklos/here/master/")^ 14 | 15 | Usage 16 | ----- 17 | 18 | Type the command ^here^ anywhere inside a project folder and it will put the *root* of the project folder into a global macro called ^here^. 19 | 20 | . pwd 21 | /Users/koren/projects/social-distancing/analysis/counterfactual 22 | 23 | . here 24 | /Users/koren/projects/social-distancing/ 25 | 26 | . display "${here}" 27 | /Users/koren/projects/social-distancing/ 28 | 29 | . import delimited "${here}/data/raw/bls/employment.csv" 30 | 31 | To fix the root folder, use ^here, set^. 32 | 33 | . cd "/Users/koren/projects/social-distancing/analysis" 34 | /Users/koren/projects/social-distancing/analysis 35 | 36 | . here, set 37 | /Users/koren/projects/social-distancing/analysis/ 38 | 39 | . display ${here} 40 | /Users/koren/projects/social-distancing/analysis/ 41 | 42 | Under the hood 43 | -------------- 44 | 45 | With the basic usage, ^here^ looks for a parent folder with the (empty) file ".here" in it. Suppose you have the following folder structure. 46 | 47 | . 48 | ├── .here 49 | ├── analysis 50 | │   ├── counterfactual 51 | │   │   └── simulate.do 52 | │   └── regress.do 53 | └── data 54 | └── raw 55 | └── employment.csv 56 | 57 | Whether you call ^here^ from "analysis/regress.do" or from "analysis/counterfactual/simulate.do", the value of ^${here}^ will be absolute path of the folder containing the file ".here". Whevener you issue 58 | 59 | ^here, set^ 60 | 61 | here will put a file called ".here" in your current folder. 62 | 63 | ^here^ will also stop if it finds a ".git" folder, with the understanding that git repositories are typically in the root of a project folder. But if this is not case for your project, you can turn off this behavior with the otion 64 | 65 | ^here, nogit^ 66 | 67 | Options 68 | ------- 69 | 70 | ^set^ sets the root folder of the project. 71 | 72 | ^nogit^ ignores .git folders when finding the root folder. -------------------------------------------------------------------------------- /here.pkg: -------------------------------------------------------------------------------- 1 | v 3 2 | d 'here': a simpler way to find your files 3 | d 4 | d save the absolute path of the root of your project folder in a global macro. 5 | d 'here' roughly implements the behavior of the CRAN library with the same name. 6 | d 7 | d Author: Miklós Koren 8 | d License: MIT 9 | d Distribution-Date: 20200731 10 | f here.ado 11 | f here.hlp -------------------------------------------------------------------------------- /stata.toc: -------------------------------------------------------------------------------- 1 | v 5.0.0 2 | d Author Miklós Koren 3 | d korenm@ceu.edu 4 | d https://github.com/korenmiklos/here 5 | 6 | d 'here': a simpler way to find your files 7 | 8 | p here --------------------------------------------------------------------------------