From ed671e7d1d50a02e57875d3e325208fe1925590d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Sat, 14 Dec 2024 17:52:33 +0100 Subject: [PATCH] docs: Add `index.md` --- .Rbuildignore | 1 + README.Rmd | 41 ++++++++++-- README.md | 181 ++++++++++++++++++++++++++++---------------------- index.md | 116 ++++++++++++++++++++++++++++++++ 4 files changed, 256 insertions(+), 83 deletions(-) create mode 100644 index.md diff --git a/.Rbuildignore b/.Rbuildignore index 7f5fe3bff..21e9071b8 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -28,3 +28,4 @@ _cache$ ^vignettes/.*\.html$ ^CRAN-SUBMISSION$ ^\.aviator/config\.yml$ +^index\.md$ diff --git a/README.Rmd b/README.Rmd index 3cba16d3e..1660c19f6 100644 --- a/README.Rmd +++ b/README.Rmd @@ -1,17 +1,48 @@ --- -output: downlit::readme_document +output: + github_document: + html_preview: false --- - - - + ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", - fig.path = "README-" + fig.path = "man/figures/README-", + out.width = "100%" +) + +pkgload::load_all() + +set.seed(20230702) + +clean_output <- function(x, options) { + x <- gsub("0x[0-9a-f]+", "0xdeadbeef", x) + x <- gsub("dataframe_[0-9]*_[0-9]*", " dataframe_42_42 ", x) + x <- gsub("[0-9]*\\.___row_number ASC", "42.___row_number ASC", x) + + index <- x + index <- gsub("─", "-", index) + index <- strsplit(paste(index, collapse = "\n"), "\n---\n")[[1]][[2]] + writeLines(index, "index.md") + + x <- fansi::strip_sgr(x) + x +} + +options( + cli.num_colors = 256, + cli.width = 80, + width = 80, + pillar.bold = TRUE ) + +local({ + hook_source <- knitr::knit_hooks$get("document") + knitr::knit_hooks$set(document = clean_output) +}) ``` diff --git a/README.md b/README.md index f44f6702f..315bbc63b 100644 --- a/README.md +++ b/README.md @@ -1,103 +1,128 @@ - - + # pillar -[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable) [![R build status](https://github.com/r-lib/pillar/workflows/R-CMD-check/badge.svg)](https://github.com/r-lib/pillar/actions) [![Coverage status](https://codecov.io/gh/r-lib/pillar/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/pillar) [![CRAN status](https://www.r-pkg.org/badges/version/pillar)](https://cran.r-project.org/package=pillar) - +[![Lifecycle: +stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable) +[![R build +status](https://github.com/r-lib/pillar/workflows/R-CMD-check/badge.svg)](https://github.com/r-lib/pillar/actions) +[![Coverage +status](https://codecov.io/gh/r-lib/pillar/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/pillar) +[![CRAN +status](https://www.r-pkg.org/badges/version/pillar)](https://cran.r-project.org/package=pillar) -pillar provides tools for styling columns of data, artfully using colour and unicode characters to guide the eye. +pillar provides tools for styling columns of data, artfully using colour +and unicode characters to guide the eye. ## Installation -
-# pillar is installed if you install the tidyverse package:
-install.packages("tidyverse")
-
-# Alternatively, install just pillar:
-install.packages("pillar")
+``` r +# pillar is installed if you install the tidyverse package: +install.packages("tidyverse") + +# Alternatively, install just pillar: +install.packages("pillar") +``` ## Usage -pillar is a developer-facing package that is not designed for end-users. It powers the [`print()`](https://rdrr.io/r/base/print.html) and [`format()`](https://rdrr.io/r/base/format.html) methods for [tibble](https://tibble.tidyverse.org/)s. It also and defines generics and helpers that are useful for package authors who create custom vector classes (see for examples) or custom table classes (like [dbplyr](https://dbplyr.tidyverse.org/) or [sf](https://r-spatial.github.io/sf/)). - -
-library(pillar)
-
-x <- 123456789 * (10^c(-3, -5, NA, -8, -10))
-pillar(x)
-#> <pillar>
-#>       <dbl>
-#> 123457.    
-#>   1235.    
-#>     NA     
-#>      1.23  
-#>      0.0123
-
-tbl_format_setup(tibble::tibble(x))
-#> <pillar_tbl_format_setup>
-#> <tbl_format_header(setup)>
-#> # A tibble: 5 × 1
-#> <tbl_format_body(setup)>
-#>             x
-#>         <dbl>
-#> 1 123457.    
-#> 2   1235.    
-#> 3     NA     
-#> 4      1.23  
-#> 5      0.0123
-#> <tbl_format_footer(setup)>
+pillar is a developer-facing package that is not designed for end-users. +It powers the `print()` and `format()` methods for +[tibble](https://tibble.tidyverse.org/)s. It also and defines generics +and helpers that are useful for package authors who create custom vector +classes (see for +examples) or custom table classes (like +[dbplyr](https://dbplyr.tidyverse.org/) or +[sf](https://r-spatial.github.io/sf/)). + +``` r +library(pillar) + +x <- 123456789 * (10^c(-3, -5, NA, -8, -10)) +pillar(x) +#> +#> +#> 123457. +#> 1235. +#> NA +#> 1.23 +#> 0.0123 + +tbl_format_setup(tibble::tibble(x)) +#> +#> +#> # A tibble: 5 × 1 +#> +#> x +#> +#> 1 123457. +#> 2 1235. +#> 3 NA +#> 4 1.23 +#> 5 0.0123 +#> +``` ## Custom vector classes -The primary user of this package is [tibble](https://github.com/tidyverse/tibble), which lets pillar do all the formatting work. Packages that implement a data type to be used in a tibble column can customize the display by implementing a [`pillar_shaft()`](https://pillar.r-lib.org/reference/pillar_shaft.html) method. - -
-library(pillar)
-
-percent <- vctrs::new_vctr(9:11 * 0.01, class = "percent")
-
-pillar_shaft.percent <- function(x, ...) {
-  fmt <- format(vctrs::vec_data(x) * 100)
-  new_pillar_shaft_simple(paste0(fmt, " ", style_subtle("%")), align = "right")
-}
-
-pillar(percent)
-#> <pillar>
-#> <percent>
-#>       9 %
-#>      10 %
-#>      11 %
- -See [`vignette("pillar", package = "vctrs")`](https://vctrs.r-lib.org/articles/pillar.html) for details. +The primary user of this package is +[tibble](https://github.com/tidyverse/tibble), which lets pillar do all +the formatting work. Packages that implement a data type to be used in a +tibble column can customize the display by implementing a +`pillar_shaft()` method. + +``` r +library(pillar) + +percent <- vctrs::new_vctr(9:11 * 0.01, class = "percent") + +pillar_shaft.percent <- function(x, ...) { + fmt <- format(vctrs::vec_data(x) * 100) + new_pillar_shaft_simple(paste0(fmt, " ", style_subtle("%")), align = "right") +} + +pillar(percent) +#> +#> +#> 9 % +#> 10 % +#> 11 % +``` + +See `vignette("pillar", package = "vctrs")` for details. ## Custom table classes -pillar provides various extension points for customizing how a tibble-like class is printed. - -
-tbl <- vctrs::new_data_frame(list(a = 1:3), class = c("my_tbl", "tbl"))
-
-tbl_sum.my_tbl <- function(x, ...) {
-  c("Hello" = "world!")
-}
-
-tbl
-#> # Hello: world!
-#>       a
-#>   <int>
-#> 1     1
-#> 2     2
-#> 3     3
- -See [`vignette("extending", package = "pillar")`](https://pillar.r-lib.org/articles/extending.html) for a walkthrough of the options. +pillar provides various extension points for customizing how a +tibble-like class is printed. + +``` r +tbl <- vctrs::new_data_frame(list(a = 1:3), class = c("my_tbl", "tbl")) + +tbl_sum.my_tbl <- function(x, ...) { + c("Hello" = "world!") +} + +tbl +#> # Hello: world! +#> a +#> +#> 1 1 +#> 2 2 +#> 3 3 +``` + +See `vignette("extending", package = "pillar")` for a walkthrough of the +options. ------------------------------------------------------------------------ ## Code of Conduct -Please note that the pillar project is released with a [Contributor Code of Conduct](https://pillar.r-lib.org/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. +Please note that the pillar project is released with a [Contributor Code +of Conduct](https://pillar.r-lib.org/CODE_OF_CONDUCT.html). By +contributing to this project, you agree to abide by its terms. diff --git a/index.md b/index.md new file mode 100644 index 000000000..fef70cc48 --- /dev/null +++ b/index.md @@ -0,0 +1,116 @@ + + + + + + +# pillar + + +[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable) +[![R build status](https://github.com/r-lib/pillar/workflows/R-CMD-check/badge.svg)](https://github.com/r-lib/pillar/actions) +[![Coverage status](https://codecov.io/gh/r-lib/pillar/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/pillar) +[![CRAN status](https://www.r-pkg.org/badges/version/pillar)](https://cran.r-project.org/package=pillar) + + + +pillar provides tools for styling columns of data, artfully using colour and unicode characters to guide the eye. + + +## Installation + + +``` r +# pillar is installed if you install the tidyverse package: +install.packages("tidyverse") + +# Alternatively, install just pillar: +install.packages("pillar") +``` + + +## Usage + +pillar is a developer-facing package that is not designed for end-users. +It powers the `print()` and `format()` methods for [tibble](https://tibble.tidyverse.org/)s. +It also and defines generics and helpers that are useful for package authors who create custom vector classes (see https://github.com/krlmlr/awesome-vctrs#readme for examples) or custom table classes (like [dbplyr](https://dbplyr.tidyverse.org/) or [sf](https://r-spatial.github.io/sf/)). + + +``` r +library(pillar) + +x <- 123456789 * (10^c(-3, -5, NA, -8, -10)) +pillar(x) +#>  +#>  +#> 123457. +#> 1235. +#> NA +#> 1.23 +#> 0.0123 + +tbl_format_setup(tibble::tibble(x)) +#>  +#>  +#> # A tibble: 5 × 1 +#>  +#> x +#>  +#> 1 123457. +#> 2 1235. +#> 3 NA +#> 4 1.23 +#> 5 0.0123 +#>  +``` + +## Custom vector classes + +The primary user of this package is [tibble](https://github.com/tidyverse/tibble), which lets pillar do all the formatting work. +Packages that implement a data type to be used in a tibble column can customize the display by implementing a `pillar_shaft()` method. + + +``` r +library(pillar) + +percent <- vctrs::new_vctr(9:11 * 0.01, class = "percent") + +pillar_shaft.percent <- function(x, ...) { + fmt <- format(vctrs::vec_data(x) * 100) + new_pillar_shaft_simple(paste0(fmt, " ", style_subtle("%")), align = "right") +} + +pillar(percent) +#>  +#>  +#> 9 % +#> 10 % +#> 11 % +``` + +See `vignette("pillar", package = "vctrs")` for details. + + +## Custom table classes + +pillar provides various extension points for customizing how a tibble-like class is printed. + + +``` r +tbl <- vctrs::new_data_frame(list(a = 1:3), class = c("my_tbl", "tbl")) + +tbl_sum.my_tbl <- function(x, ...) { + c("Hello" = "world!") +} + +tbl +#> # Hello: world! +#> a +#>  +#> 1 1 +#> 2 2 +#> 3 3 +``` + +See `vignette("extending", package = "pillar")` for a walkthrough of the options. +