Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Tazinho/snakecase
🐍🐍🐍 A systematic approach to parse strings and automate the conversion to snake_case, UpperCamelCase or any other case.
https://github.com/Tazinho/snakecase
camelcase case conversion package pascalcase r snake-case
Last synced: about 2 months ago
JSON representation
🐍🐍🐍 A systematic approach to parse strings and automate the conversion to snake_case, UpperCamelCase or any other case.
- Host: GitHub
- URL: https://github.com/Tazinho/snakecase
- Owner: Tazinho
- License: gpl-3.0
- Created: 2017-03-12T17:13:23.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-01-22T19:55:37.000Z (8 months ago)
- Last Synced: 2024-07-05T22:08:08.744Z (3 months ago)
- Topics: camelcase, case, conversion, package, pascalcase, r, snake-case
- Language: R
- Homepage: https://tazinho.github.io/snakecase/
- Size: 28.8 MB
- Stars: 144
- Watchers: 3
- Forks: 8
- Open Issues: 24
-
Metadata Files:
- Readme: README.Rmd
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/security.html
Awesome Lists containing this project
- jimsghstars - Tazinho/snakecase - 🐍🐍🐍 A systematic approach to parse strings and automate the conversion to snake_case, UpperCamelCase or any other case. (R)
README
---
output: rmarkdown::github_document
---
# snakecase 
[](https://ci.appveyor.com/project/Tazinho/snakecase) [](https://travis-ci.org/Tazinho/snakecase) [](https://cran.r-project.org/package=snakecase) [](https://codecov.io/github/Tazinho/snakecase?branch=master) [](http://cranlogs.r-pkg.org/) [](http://cranlogs.r-pkg.org/) [](https://www.tidyverse.org/lifecycle/#stable) [](https://bestpractices.coreinfrastructure.org/projects/2475)
## Overview
The snakecase package introduces a fresh and straightforward approach on case conversion, based upon a consistent design philosophy.
For a short intro regarding typical use cases, see the blog article [Introducing the snakecase package](http://www.malte-grosser.com/post/introducing-the-snakecase-package/).
### Install and load
```{r, results='hide', message=FALSE, warning=FALSE, eval = TRUE}
# install snakecase from cran
# install.packages("snakecase")
# or the (stable) development version hosted on github
# install.packages("remotes")
remotes::install_github("Tazinho/snakecase")
# load snakecase
library(snakecase)
```
### Basic usage
The workhorse function of this package is `to_any_case()`. It converts strings (by default) into snake case:
```{r, collapse = TRUE}
string <- c("lowerCamelCase", "ALL_CAPS", "I-DontKNOWWhat_thisCASE_is")
to_any_case(string)
```
However, one can choose between many other cases like `"lower_camel"`, `"upper_camel"`, `"all_caps"`, `"lower_upper"`, `"upper_lower"`, `"sentence"` and `"mixed"`, which are based on `"parsed"` case:
```{r, collapse = TRUE}
to_any_case(string, case = "parsed")
```
Also shortcuts (wrappers around `to_any_case()`) are provided:
```{r, collapse = TRUE}
to_upper_camel_case(string)
```
Be aware that automatic case conversion depends on the input string and it is therefore recommended to verify the results. You might want to pipe these into `dput()` and hardcode name changes instead of blindly trusting the output:
```{r, collapse = TRUE}
library(magrittr)
to_snake_case(c("SomeBAdInput", "someGoodInput")) %>% dput()
```
## Big picture (a parameterized workflow)
The `to_any_case()` function basically enables you to convert any string into any case. This is achieved via a well thought process of __parsing__ (`abbreviations`, `sep_in`, `parsing_option`), __conversion__ (`transliterations`, `case`) and __postprocessing__ (`numerals`, `sep_out`). The specific arguments allow you to customize the pipeline.
On this example, you can see the whole pipeline including some implementation details.
```{r echo=FALSE, out.width='100%'}
# knitr::include_graphics('./man/figures/Workflow01.PNG')
knitr::include_graphics('./man/figures/Workflow02.PNG')
```
Some further **cosmetics** (`unique_sep`, `empty_fill`, `prefix`, `postfix`) can be applied to the output, see arguments.
## Arguments
**string**: A character vector, containing the input strings.
### Parsing
**abbreviations**: One challenge in case conversion are odd looking "mixed cases". These might be introduced due to country codes or other abbreviations, which are usually written in upper case. Before you consider a different `parsing_option` (see below), you might just want to use the `abbreviations` argument:
```{r, collapse = TRUE}
to_snake_case(c("HHcity", "IDTable1", "KEYtable2", "newUSElections"),
abbreviations = c("HH", "ID", "KEY", "US"))
```
Abbreviations are consistently formatted regarding the supplied `case`. However, for title-, mixed-, lower-camel- and upper-camel-case the formatting is specified by the formatting of the input:
```{r, collapse = TRUE}
to_upper_camel_case(c("user_id", "finals_mvp"), abbreviations = c("Id", "MVP"))
```
**sep_in**: By default non-alphanumeric characters are treated as separators:
```{r, collapse = TRUE}
to_snake_case("[email protected]")
```
To suppress this behaviour, just set `sep_in = NULL`:
```{r, collapse = TRUE}
to_snake_case("[email protected]", sep_in = NULL)
```
Since `sep_in` takes regular expressions as input, `to_any_case()` becomes very flexible. We can for example express that dots behind digits should not be treated as separators, since they might be intended as decimal marks:
```{r, collapse = TRUE}
to_snake_case("Pi.Value:3.14", sep_in = ":|(? 1`, its last element gets recycled and the output separators are incorporated per string according the order in `sep_in`. This might come in handy when e.g. formatting file names:
```{r, collapse = TRUE}
to_any_case(
string = c("YYYY_MM.DD_bla_bla_bla",
"2019_01-09_bla_bla_bla"),
sep_out = c("", "", "-", "_"),
postfix = ".txt")
```
### Cosmetics
**unique_sep**: (character): When not `NULL` non unique output strings will get an integer suffix separated with the supplied string.
**empty_fill**: (character): Empty output (`""`) will be replaced by this string.
**prefix**: (character): simple prefix.
**postfix**: (character): simple post-/suffix.
## Design decisions
### Scope
`to_any_case()` is an attempt to provide good low level control, while still being high level enough for daily usage. For another example of case conversion with good default settings, you can look into the `clean_names()` function from the [janitor](https://github.com/sfirke/janitor) package, which works directly on data frames. You can also look into the [sjPlot](https://github.com/strengejacke/sjPlot) package, where automatic case conversion is used to provide nice default labels within graphics.
For daily usage (especially when preparing fixed scripts) I recommend to combine `to_any_case()` with `dput()`. In this way, you can quickly inspect, if the output is as intended and hardcode the results (which is basically safer and good practice in my opinion). In very complex cases you might just want to manually fix the output from `dput()` instead of tweeking with the arguments too much.
### Dependencies, vectorisation, speed and special input handling
The package is internally build up on the [stringr](https://github.com/tidyverse/stringr) package, which means that many powerful features are provided "by default":
* `to_any_case()` is vectorised over most of its arguments like `string`, `sep_in`, `sep_out`, `empty_fill`, `prefix` and `postfix`.
* internal character operations are super fast c++. However, some speed is lost due to a more systematic and maintainable implementation.
* special input like `character(0)`, `NA` etc. is handled in exactly the same consistent and convenient manner as in the stringr package.
### Known limitations
* In general combinations of one letter words or abbreviations are hard to convert back from cases with `""` as default separator:
```{r, collapse=TRUE}
to_any_case("a_b_c_d", case = "upper_camel")
```
However, it it not impossible:
```{r, collapse= TRUE}
to_snake_case("ABCD", sep_out = ".",
transliterations = c("^ABCD$" = "A_B_C_D"))
to_snake_case("BVBFCB:5-2", sep_in = ":",
transliterations = c("^BVBFCB" = "BVB_FCB"))
```
* Sometimes further pre- or postprocessing might be needed. For example you can easily write your own parsing via a sequence of calls like `str_replace_all(string, (some_pattern), "_\\1_")`.
* You can decide yourself: Open an issue [here](https://github.com/Tazinho/snakecase/issues) or build sth. quickly yourself via packages like base, [stringr](https://github.com/tidyverse/stringr), [stringi](https://github.com/gagolews/stringi) etc.
## Design Philosophy
### Practical influences
Conversion to a specific target case is not always obvious or unique. In general a clean conversion
can only be guaranteed, when the input-string is meaningful.
Take for example a situation where you have IDs for some customers. Instead of calling the column "CustomerID" you abbreviate it to "CID". Without further knowledge about the meaning of CID it will be impossible to know that it should be converted to "c_id", when using `to_snake_case()`. Instead it will be converted to:
```{r, collapse=TRUE}
to_snake_case("CID")
```
We could have also converted to "c_i_d" and if we don't know the meaning of "CID", we can't decide which one is the better solution. However, it is easy to exclude specific approaches by counterexamples. So in practice it might be nicer to convert "SCREAMING_SNAKE_CASE" to "screaming_snake_case" instead of "s_c_r_e_a_m_i_n_g_s_n_a_k_e_c_a_s_e" (or "screamin_g_snak_e_cas_e" or "s_creaming_s_nake_c_ase"), which means that also "cid" is preferable to "c_i_d" (or "c_id" or "ci_d") without further knowledge.
Since the computer can't know, that we want "c_id" by himself. It is easiest, if we provide him with the right information (here in form of a valid PascalCase syntax):
```{r, collapse=TRUE}
to_snake_case("CId")
```
In this way it is guaranteed to get the correct conversion and the only chance of an error lies in an accidentally wrong provided input string or a bug in the converter function `to_snake_case()` (or a sequence of (one letter) abbreviations, see known limitations).
### Consistent behaviour
In many scenarios the analyst doesn't have a big influence on naming conventions and sometimes there might occur situations where it is not possible to find out the exact meaning of a variable name, even if we ask the original author. In some cases data might also have been named by a machine and the results can be relatively technically. So in general it is a good idea to compare the input of the case converter functions with their output, to see if the intended meanings at least seem to be preserved.
To make this as painless as possible, it is best to provide a logic that is robust and can handle also relatively complex cases. Note for example the string "RStudio". How should one convert it to snake case? We have seen a similar example with "CId", but for now we focus on sth. different. In case of "RStudio", we could convert to:
1. "r_s_tudio",
1. "rs_tudio" or
1. "r_studio".
If we are conservative about any assumptions on the meaning of "RStudio", we can't decide which is the correct conversion. It is also not valid to assume that "RStudio" was intentionally written in PascalCase. Of course we know that "r_studio" is the correct solution, but we can get there also via different considerations. Let us try to convert our three possible translations (back) to PascalCase and from there back to snake case. What should the output look like?
1. r_s_tudio -> RSTudio -> r_s_t_udio
1. rs_tudio -> RsTudio -> rs_tudio
1. r_studio -> RStudio -> r_studio
Both of the first two alternatives can't be consistently converted back to a valid Pascal case input ("RStudio") and with the first logic the further snake case conversion seems to be complete nonsense. Only the latter case is consistent, when converting back to PascalCase, which is the case of the input "RStudio". It is also consistent to itself, when converting from PascalCase back to snake_case.
In this way, we can get a good starting point on how to convert specific strings to valid snake_case. Once we have a clean snake_case conversion, we can easily convert further to smallCamelCase, BigCamelCase, SCREAMING_SNAKE_CASE or anything else.
### Three rules of consistency
In the last sections we have seen, that it is reasonable to bring a specific conversion from an input string to some standardized case into question. We have also seen, that it is helpful to introduce some tests on the behavior of a specific conversion pattern in related cases. The latter can help to detect inappropriate conversions and also establishes a consistent behavior when converting exotic cases or switching between standardized cases. Maybe we can generalize some of these tests and introduce some kind of consistency patterns. This would enable us that whenever inappropriate or non-unique possibilities for conversions appear, we have rules that help us to deal with this situation and help to exclude some inconsistent conversion alternatives.
During the development of this package I recognized three specific rules that seem reasonable to be valid whenever cases are converted. To be more general we just use `to_x()` and `to_y()` to refer to any two differing converter functions from the set of functions including `to_snake_case()`, `to_screaming_snake_case()`, `to_lower_camel_case` and `to_upper_camel_case()`. (Other cases like "lower_upper" or "upper_lower" could be included, if we consider `parsing_option = 2` within the equations.)
1. When we have converted to a standardized case, a new conversion to the case should not change the output:
`to_x(to_x(string)) = to_x(string)`
1. When converting to a specific case, it should not matter if a conversion to another case happened already:
`to_y(to_x(string)) = to_y(string)`
1. It should always be possible to switch between different cases, without any loss of information:
`to_x(to_y(to_x(string))) = to_x(string)`
Note that it can easily be shown, that rule three follows from the second rule. However, it seems reasonable to express each by its own, since they all have an interpretation and together they give a really good intuition about the properties of the converter functions.
## Testing
To give a meaningful conversion for different cases, we systematically designed test-cases for conversion to snake, small- and big camel case among others.
To be consistent regarding the conversion between different cases, we also test the rules above on all test-cases.
```{r, echo = FALSE, include = FALSE}
cases <- c(NA, "snake_case", "snakeCase",
"SnakeCase", "_", "snake_Case",
"_", "SNake", "Snake",
"s_nake", "sn_ake", "_",
"SNaKE", "SNaKEr", "s_na_k_er",
"_", "SNAKE SNAKE CASE", "_",
"snakeSnakECase", "SNAKE snakE_case", "_",
"ssRRss", "ssRRRR")
# cases <- c(NA,
# "snake_case", "snakeCase",
# "SnakeCase", "_", "snake_Case",
# "_", "SNake", "Snake",
# "s_nake", "sn_ake", "_",
# "SNaKE", "SNaKEr", "s_na_k_er", "_",
# "SNAKE SNAKE CASE", "_",
# "snakeSnakECase", "SNAKE snakE_case", "_",
# "bangBooMBang",
# "upPER", "CId", "_",
# "___", ".", "...",
# "Sepal.Width", "Var 1", "Var-2",
# "Var.3", "Var4",
# "SnakeCase",
# "Snake-Case",
# "Snake Case",
# "Snake - Case")
#
# `As intended?` = c("yes", "yes", "yes",
# "yes", "", "yes",
# "", "yes", "yes",
# "yes", "yes", "",
# "yes", "yes", "yes",
# "", "yes", "yes",
# "yes", "", "yes",
# "_ ?", "",
# "_ X",
# "_ X", "_ ? (maybe c_id)", "_ ?",
# "_ ?", "_ ?", "_ ?",
# "_ X", "_ ? (maybe var1)", "_ ?",
# "_ ? (maybe var3)", "_ X",
# "","")
knitr::kable(tibble::tibble(nr = seq_along(cases),
examples = cases,
snake_case = snakecase::to_snake_case(cases),
#snake_case_dev = snakecase::to_snake_case_dev(cases),
smallCamelCase = snakecase::to_lower_camel_case(cases),
BigCamelCase = snakecase::to_upper_camel_case(cases)
)
)
```
## Related Resources
* If you are interested on (the history of) this package, you can watch this [(older) talk](https://www.youtube.com/watch?v=T6p0l8XzP64).
* [The state of naming conventions in R, Bååth 2012, R Journal](https://lup.lub.lu.se/search/publication/e324f252-1d1c-4416-ad1f-284d4ba84bf9) [Download article](journal.r-project.org/archive/2012-2/RJournal_2012-2_Baaaath.pdf)
* [Consistent naming conventions in R, Lovelace 2014, RBloggers](https://www.r-bloggers.com/consistent-naming-conventions-in-r/)
* [What is your preferred style for naming variables in R?, Stackoverflowquestion 2009](http://stackoverflow.com/questions/1944910/what-is-your-preferred-style-for-naming-variables-in-r)
* [Are there any official naming conventions in R?, stackoverflowquestion 2012](http://stackoverflow.com/questions/10013545/are-there-any-official-naming-conventions-for-r)
* [`clean_names()` function](https://github.com/sfirke/janitor/blob/master/R/clean_names.R) from the [janitor package](https://github.com/sfirke/janitor)
* [`to_camel()` function](https://github.com/Rapporter/rapportools/blob/master/R/utils.R) from the [rapporttools package](https://github.com/Rapporter/rapportools)
* [lettercase-pkg](https://cran.r-project.org/web/packages/lettercase/index.html)
---
Please note that the _snakecase_ package is released with a [Contributor Code of Conduct](.github/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.