docs: Add index.md

r-lib · Dec 14, 2024 · ed671e7 · ed671e7
1 parent fd2ada4
commit ed671e7
Show file tree

Hide file tree

Showing 4 changed files with 256 additions and 83 deletions.
diff --git 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
@@ -1,17 +1,48 @@
 ---
-output: downlit::readme_document
+output:
+  github_document:
+    html_preview: false
 ---
-<!-- README.md is generated from README.Rmd on GitHub Actions: do not edit by hand -->
 
-
-<!-- .github/README.md is copied manually from README.md and adapted -->
+<!-- README.md and index.md are generated from README.Rmd. Please edit that file. -->
 
 ```{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
@@ -1,103 +1,128 @@
-<!-- README.md is generated from README.Rmd on GitHub Actions: do not edit by hand -->
 
-<!-- .github/README.md is copied manually from README.md and adapted -->
+<!-- README.md and index.md are generated from README.Rmd. Please edit that file. -->
 
 # pillar
 
 <!-- badges: start -->
 
-[![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)
 <!-- badges: end -->
 
-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
 
-<pre class='chroma'>
-<span><span class='c'># pillar is installed if you install the tidyverse package:</span></span>
-<span><span class='nf'><a href='https://rdrr.io/r/utils/install.packages.html'>install.packages</a></span><span class='o'>(</span><span class='s'>"tidyverse"</span><span class='o'>)</span></span>
-<span></span>
-<span><span class='c'># Alternatively, install just pillar:</span></span>
-<span><span class='nf'><a href='https://rdrr.io/r/utils/install.packages.html'>install.packages</a></span><span class='o'>(</span><span class='s'>"pillar"</span><span class='o'>)</span></span></pre>
+``` 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 <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/)).
-
-<pre class='chroma'>
-<span><span class='kr'><a href='https://rdrr.io/r/base/library.html'>library</a></span><span class='o'>(</span><span class='nv'><a href='https://pillar.r-lib.org/'>pillar</a></span><span class='o'>)</span></span>
-<span></span>
-<span><span class='nv'>x</span> <span class='o'>&lt;-</span> <span class='m'>123456789</span> <span class='o'>*</span> <span class='o'>(</span><span class='m'>10</span><span class='o'>^</span><span class='nf'><a href='https://rdrr.io/r/base/c.html'>c</a></span><span class='o'>(</span><span class='o'>-</span><span class='m'>3</span>, <span class='o'>-</span><span class='m'>5</span>, <span class='kc'>NA</span>, <span class='o'>-</span><span class='m'>8</span>, <span class='o'>-</span><span class='m'>10</span><span class='o'>)</span><span class='o'>)</span></span>
-<span><span class='nf'><a href='https://pillar.r-lib.org/reference/pillar.html'>pillar</a></span><span class='o'>(</span><span class='nv'>x</span><span class='o'>)</span></span>
-<span><span class='c'>#&gt; <span style='font-weight: bold;'>&lt;pillar&gt;</span></span></span>
-<span><span class='c'>#&gt;       <span style='color: #555555; font-style: italic;'>&lt;dbl&gt;</span></span></span>
-<span><span class='c'>#&gt; <span style='text-decoration: underline;'>123</span>457.    </span></span>
-<span><span class='c'>#&gt;   <span style='text-decoration: underline;'>1</span>235.    </span></span>
-<span><span class='c'>#&gt;     <span style='color: #BB0000;'>NA</span>     </span></span>
-<span><span class='c'>#&gt;      1.23  </span></span>
-<span><span class='c'>#&gt;      0.012<span style='text-decoration: underline;'>3</span></span></span>
-<span></span>
-<span><span class='nf'><a href='https://pillar.r-lib.org/reference/tbl_format_setup.html'>tbl_format_setup</a></span><span class='o'>(</span><span class='nf'>tibble</span><span class='nf'>::</span><span class='nf'><a href='https://tibble.tidyverse.org/reference/tibble.html'>tibble</a></span><span class='o'>(</span><span class='nv'>x</span><span class='o'>)</span><span class='o'>)</span></span>
-<span><span class='c'>#&gt; <span style='font-weight: bold;'>&lt;pillar_tbl_format_setup&gt;</span></span></span>
-<span><span class='c'>#&gt; <span style='font-weight: bold;'>&lt;tbl_format_header(setup)&gt;</span></span></span>
-<span><span class='c'>#&gt; <span style='color: #555555;'># A tibble: 5 × 1</span></span></span>
-<span><span class='c'>#&gt; <span style='font-weight: bold;'>&lt;tbl_format_body(setup)&gt;</span></span></span>
-<span><span class='c'>#&gt;             <span style='font-weight: bold;'>x</span></span></span>
-<span><span class='c'>#&gt;         <span style='color: #555555; font-style: italic;'>&lt;dbl&gt;</span></span></span>
-<span><span class='c'>#&gt; <span style='color: #555555;'>1</span> <span style='text-decoration: underline;'>123</span>457.    </span></span>
-<span><span class='c'>#&gt; <span style='color: #555555;'>2</span>   <span style='text-decoration: underline;'>1</span>235.    </span></span>
-<span><span class='c'>#&gt; <span style='color: #555555;'>3</span>     <span style='color: #BB0000;'>NA</span>     </span></span>
-<span><span class='c'>#&gt; <span style='color: #555555;'>4</span>      1.23  </span></span>
-<span><span class='c'>#&gt; <span style='color: #555555;'>5</span>      0.012<span style='text-decoration: underline;'>3</span></span></span>
-<span><span class='c'>#&gt; <span style='font-weight: bold;'>&lt;tbl_format_footer(setup)&gt;</span></span></span></pre>
+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)
+#> <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)>
+```
 
 ## 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.
-
-<pre class='chroma'>
-<span><span class='kr'><a href='https://rdrr.io/r/base/library.html'>library</a></span><span class='o'>(</span><span class='nv'><a href='https://pillar.r-lib.org/'>pillar</a></span><span class='o'>)</span></span>
-<span></span>
-<span><span class='nv'>percent</span> <span class='o'>&lt;-</span> <span class='nf'>vctrs</span><span class='nf'>::</span><span class='nf'><a href='https://vctrs.r-lib.org/reference/new_vctr.html'>new_vctr</a></span><span class='o'>(</span><span class='m'>9</span><span class='o'>:</span><span class='m'>11</span> <span class='o'>*</span> <span class='m'>0.01</span>, class <span class='o'>=</span> <span class='s'>"percent"</span><span class='o'>)</span></span>
-<span></span>
-<span><span class='nv'>pillar_shaft.percent</span> <span class='o'>&lt;-</span> <span class='kr'>function</span><span class='o'>(</span><span class='nv'>x</span>, <span class='nv'>...</span><span class='o'>)</span> <span class='o'>{</span></span>
-<span>  <span class='nv'>fmt</span> <span class='o'>&lt;-</span> <span class='nf'><a href='https://rdrr.io/r/base/format.html'>format</a></span><span class='o'>(</span><span class='nf'>vctrs</span><span class='nf'>::</span><span class='nf'><a href='https://vctrs.r-lib.org/reference/vec_data.html'>vec_data</a></span><span class='o'>(</span><span class='nv'>x</span><span class='o'>)</span> <span class='o'>*</span> <span class='m'>100</span><span class='o'>)</span></span>
-<span>  <span class='nf'><a href='https://pillar.r-lib.org/reference/new_pillar_shaft.html'>new_pillar_shaft_simple</a></span><span class='o'>(</span><span class='nf'><a href='https://rdrr.io/r/base/paste.html'>paste0</a></span><span class='o'>(</span><span class='nv'>fmt</span>, <span class='s'>" "</span>, <span class='nf'><a href='https://pillar.r-lib.org/reference/style_subtle.html'>style_subtle</a></span><span class='o'>(</span><span class='s'>"%"</span><span class='o'>)</span><span class='o'>)</span>, align <span class='o'>=</span> <span class='s'>"right"</span><span class='o'>)</span></span>
-<span><span class='o'>}</span></span>
-<span></span>
-<span><span class='nf'><a href='https://pillar.r-lib.org/reference/pillar.html'>pillar</a></span><span class='o'>(</span><span class='nv'>percent</span><span class='o'>)</span></span>
-<span><span class='c'>#&gt; <span style='font-weight: bold;'>&lt;pillar&gt;</span></span></span>
-<span><span class='c'>#&gt; <span style='color: #555555; font-style: italic;'>&lt;percent&gt;</span></span></span>
-<span><span class='c'>#&gt;       9 <span style='color: #555555;'>%</span></span></span>
-<span><span class='c'>#&gt;      10 <span style='color: #555555;'>%</span></span></span>
-<span><span class='c'>#&gt;      11 <span style='color: #555555;'>%</span></span></span></pre>
-
-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)
+#> <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.
-
-<pre class='chroma'>
-<span><span class='nv'>tbl</span> <span class='o'>&lt;-</span> <span class='nf'>vctrs</span><span class='nf'>::</span><span class='nf'><a href='https://vctrs.r-lib.org/reference/new_data_frame.html'>new_data_frame</a></span><span class='o'>(</span><span class='nf'><a href='https://rdrr.io/r/base/list.html'>list</a></span><span class='o'>(</span>a <span class='o'>=</span> <span class='m'>1</span><span class='o'>:</span><span class='m'>3</span><span class='o'>)</span>, class <span class='o'>=</span> <span class='nf'><a href='https://rdrr.io/r/base/c.html'>c</a></span><span class='o'>(</span><span class='s'>"my_tbl"</span>, <span class='s'>"tbl"</span><span class='o'>)</span><span class='o'>)</span></span>
-<span></span>
-<span><span class='nv'>tbl_sum.my_tbl</span> <span class='o'>&lt;-</span> <span class='kr'>function</span><span class='o'>(</span><span class='nv'>x</span>, <span class='nv'>...</span><span class='o'>)</span> <span class='o'>{</span></span>
-<span>  <span class='nf'><a href='https://rdrr.io/r/base/c.html'>c</a></span><span class='o'>(</span><span class='s'>"Hello"</span> <span class='o'>=</span> <span class='s'>"world!"</span><span class='o'>)</span></span>
-<span><span class='o'>}</span></span>
-<span></span>
-<span><span class='nv'>tbl</span></span>
-<span><span class='c'>#&gt; <span style='color: #555555;'># Hello: world!</span></span></span>
-<span><span class='c'>#&gt;       <span style='font-weight: bold;'>a</span></span></span>
-<span><span class='c'>#&gt;   <span style='color: #555555; font-style: italic;'>&lt;int&gt;</span></span></span>
-<span><span class='c'>#&gt; <span style='color: #555555;'>1</span>     1</span></span>
-<span><span class='c'>#&gt; <span style='color: #555555;'>2</span>     2</span></span>
-<span><span class='c'>#&gt; <span style='color: #555555;'>3</span>     3</span></span></pre>
-
-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
+#>   <int>
+#> 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
@@ -0,0 +1,116 @@
+
+<!-- README.md and index.md are generated from README.Rmd. Please edit that file. -->
+
+
+
+
+# pillar
+
+<!-- badges: start -->
+[![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)
+<!-- badges: end -->
+
+
+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)
+#> [1m<pillar>[22m
+#>       [3m[38;5;246m<dbl>[39m[23m
+#> [4m1[24m[4m2[24m[4m3[24m457.    
+#>   [4m1[24m235.    
+#>     [31mNA[39m     
+#>      1.23  
+#>      0.012[4m3[24m
+
+tbl_format_setup(tibble::tibble(x))
+#> [1m<pillar_tbl_format_setup>[22m
+#> [1m<tbl_format_header(setup)>[22m
+#> [38;5;246m# A tibble: 5 × 1[39m
+#> [1m<tbl_format_body(setup)>[22m
+#>             [1mx[22m
+#>         [3m[38;5;246m<dbl>[39m[23m
+#> [38;5;250m1[39m [4m1[24m[4m2[24m[4m3[24m457.    
+#> [38;5;250m2[39m   [4m1[24m235.    
+#> [38;5;250m3[39m     [31mNA[39m     
+#> [38;5;250m4[39m      1.23  
+#> [38;5;250m5[39m      0.012[4m3[24m
+#> [1m<tbl_format_footer(setup)>[22m
+```
+
+## 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)
+#> [1m<pillar>[22m
+#> [3m[38;5;246m<percent>[39m[23m
+#>       9 [38;5;246m%[39m
+#>      10 [38;5;246m%[39m
+#>      11 [38;5;246m%[39m
+```
+
+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
+#> [38;5;246m# Hello: world![39m
+#>       [1ma[22m
+#>   [3m[38;5;246m<int>[39m[23m
+#> [38;5;250m1[39m     1
+#> [38;5;250m2[39m     2
+#> [38;5;250m3[39m     3
+```
+
+See `vignette("extending", package = "pillar")` for a walkthrough of the options.
+