From 347834c5e6e05256a851b588594d72a62c6864bb Mon Sep 17 00:00:00 2001 From: Quarto GHA Workflow Runner Date: Fri, 10 Jan 2025 22:37:42 +0000 Subject: [PATCH] Built site for gh-pages --- .nojekyll | 2 +- configuration.html | 753 +++++++++++++++++++++++++++++++++++++++++++++ editors.html | 6 + formatter.html | 6 + index.html | 6 + installation.html | 6 + search.json | 70 ++++- sitemap.xml | 18 +- 8 files changed, 844 insertions(+), 23 deletions(-) create mode 100644 configuration.html diff --git a/.nojekyll b/.nojekyll index 2abac731..4f3b1922 100644 --- a/.nojekyll +++ b/.nojekyll @@ -1 +1 @@ -648646d7 \ No newline at end of file +f634b04b \ No newline at end of file diff --git a/configuration.html b/configuration.html new file mode 100644 index 00000000..f90febc5 --- /dev/null +++ b/configuration.html @@ -0,0 +1,753 @@ + + + + + + + + + +Configuration – Air + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+ +
+ + +
+ + + +
+ +
+
+

Configuration

+
+ + + +
+ + + + +
+ + + +
+ + +

Air can be configured using a TOML file named air.toml. Air is purposefully minimally configurable, with the main configuration points being related to line width and indent style. Our hope is that most projects never need an air.toml file!

+
+

Example configuration

+

Below is a complete air.toml file showing all available options set to their default values:

+
[format]
+line-width = 80
+indent-width = 2
+indent-style = "space"
+line-ending = "auto"   
+ignore-magic-line-break = false
+
+
+

Configuration discovery

+

The ideal place to put an air.toml file is at your project root. For example, note the placement of air.toml in this minimal dplyr project:

+
~/files/dplyr
+├── air.toml
+├── DESCRIPTION
+├── NAMESPACE
+├── R
+├── src
+├── tests
+└── vignettes
+

If you run air format with a working directory of ~/files/dplyr or open your IDE in the dplyr project, then Air will find and use that TOML file.

+

Air also supports walking up the directory tree from the project root. For example, if you ran air format from within ~/files/dplyr/R, then Air would look “up” one directory and would find and use ~/files/dplyr/air.toml.

+
+
+

Format options

+

All formatting options are specified under the [format] table.

+
+

line-width

+

The preferred maximum line length.

+

An integer value between 1 and 320, with a default of 80.

+

While the formatter will attempt to format lines such that they remain within the line-width, it isn’t a hard upper bound, and formatted lines may exceed the line-width.

+
+
+

indent-width

+

The number of spaces per indentation level.

+

An integer value between 1 and 24, with a default of 2.

+

This option changes the number of spaces the formatter inserts when using indent-style = "space". It also represents the width of a tab when indent-style = "tab" for the purposes of computing the line-width.

+
+
+

indent-style

+

Whether to use spaces or tabs for indentation.

+

One of the following values, with a default of "space":

+
    +

  • "space": Use spaces for indentation.

    • +

  • "tab": Use tabs for indentation.

    • +
+

Air defaults to spaces due to the overwhelming amount of existing R code written in this style, but consider using tabs for new projects to improve accessibility. See indent-width to configure the number of spaces per indentation and the tab width.

+
+
+

line-ending

+

The character air uses at the end of a line.

+

One of the following values, with a default of "auto":

+
    +

  • "auto": The newline style is detected automatically on a file per file basis. Files with mixed line endings will be converted to the first detected line ending. Defaults to \n for files that contain no line endings.

    • +

  • "lf": Line endings will be converted to \n. The typical line ending on Unix.

    • +

  • "crlf": Line endings will be converted to \r\n. The typical line ending on Windows.

    • +

  • "native": Line endings will be converted to \n on Unix and \r\n on Windows.

    • +
+
+
+

ignore-magic-line-break

+

Whether or not magic line breaks should be ignored.

+

Either true to ignore magic line breaks, or false to respect them, with a default of false.

+

Air respects a small set of magic line breaks as an indication that certain function calls or function signatures should be left expanded. For example, the following list could be flattened to one line and would still fit within a line-width of 80, however, it remains expanded due to the magic line break between the opening ( and the first argument, apple.

+
dictionary <- list(
+  apple = 0.75,
+  banana = 0.25,
+  cherry = 0.50
+)
+

Similarly, this function signature could also be flattened, but is not, due to the magic line break between the opening ( and the first parameter, ....

+
case_when <- function(
+  ..., 
+  .default = NULL, 
+  .ptype = NULL, 
+  .size = NULL
+) {
+  body
+}
+

To request flattening in these cases, just remove the magic line break. For example:

+
# If you started here,
+dictionary <- list(
+  apple = 0.75,
+  banana = 0.25,
+  cherry = 0.50
+)
+
+# then do this, and run air,
+dictionary <- list(apple = 0.75,
+  banana = 0.25,
+  cherry = 0.50
+)
+
+# to get this.
+dictionary <- list(apple = 0.75, banana = 0.25, cherry = 0.50)
+

Alternatively, use a tool such as codegrip bound to a keyboard shortcut to flatten the code, and air will keep it flattened as long as it fits within the line-width.

+

It may be preferable to ignore magic line breaks if you prefer that line-width should be the only value that influences line breaks.

+ + +
+
+ +
+ +
+ + + + + \ No newline at end of file diff --git a/editors.html b/editors.html index 430d4ceb..62f35d02 100644 --- a/editors.html +++ b/editors.html @@ -163,6 +163,12 @@ Editors + +
  • +
    + + Configuration +
  • diff --git a/formatter.html b/formatter.html index c5ce46d4..441ea699 100644 --- a/formatter.html +++ b/formatter.html @@ -129,6 +129,12 @@ Editors
    +
    • +
  • +
    + + Configuration +
  • diff --git a/index.html b/index.html index f474100e..cf23165a 100644 --- a/index.html +++ b/index.html @@ -129,6 +129,12 @@ Editors
    +
    • +
  • +
    + + Configuration +
  • diff --git a/installation.html b/installation.html index 231b57c9..3b8ca74d 100644 --- a/installation.html +++ b/installation.html @@ -163,6 +163,12 @@ Editors
    +
    • +
  • +
    + + Configuration +
  • diff --git a/search.json b/search.json index 49959570..09e0025b 100644 --- a/search.json +++ b/search.json @@ -1,22 +1,52 @@ [ { - "objectID": "installation.html", - "href": "installation.html", - "title": "Installing Air", + "objectID": "configuration.html", + "href": "configuration.html", + "title": "Configuration", "section": "", - "text": "If you’d like to use Air at the command line, you can use one of our standalone installers.\n\nTo install Air as a command line tool:\nOn macOS and Linux:\ncurl -LsSf https://github.com/posit-dev/air/releases/latest/download/air-installer.sh | sh\nOn Windows:\npowershell -c \"irm https://github.com/posit-dev/air/releases/latest/download/air-installer.ps1 | iex\"\nFor a specific version:\ncurl -LsSf https://github.com/posit-dev/air/releases/download/0.1.1/air-installer.sh | sh\npowershell -c \"irm https://github.com/posit-dev/air/releases/download/0.1.1/air-installer.ps1 | iex\"\nThe installer scripts will automatically add Air to your PATH. The very first time you install Air, for the PATH modifications to be applied you’ll need to restart your terminal.\nOn Windows, the first time you install Air it requires a full system restart for the PATH modification to take effect. We are working on improving this.", + "text": "Air can be configured using a TOML file named air.toml. Air is purposefully minimally configurable, with the main configuration points being related to line width and indent style. Our hope is that most projects never need an air.toml file!", "crumbs": [ - "Installation" + "Configuration" ] }, { - "objectID": "index.html", - "href": "index.html", - "title": "Overview", + "objectID": "configuration.html#example-configuration", + "href": "configuration.html#example-configuration", + "title": "Configuration", + "section": "Example configuration", + "text": "Example configuration\nBelow is a complete air.toml file showing all available options set to their default values:\n[format]\nline-width = 80\nindent-width = 2\nindent-style = \"space\"\nline-ending = \"auto\" \nignore-magic-line-break = false", + "crumbs": [ + "Configuration" + ] + }, + { + "objectID": "configuration.html#configuration-discovery", + "href": "configuration.html#configuration-discovery", + "title": "Configuration", + "section": "Configuration discovery", + "text": "Configuration discovery\nThe ideal place to put an air.toml file is at your project root. For example, note the placement of air.toml in this minimal dplyr project:\n~/files/dplyr\n├── air.toml\n├── DESCRIPTION\n├── NAMESPACE\n├── R\n├── src\n├── tests\n└── vignettes\nIf you run air format with a working directory of ~/files/dplyr or open your IDE in the dplyr project, then Air will find and use that TOML file.\nAir also supports walking up the directory tree from the project root. For example, if you ran air format from within ~/files/dplyr/R, then Air would look “up” one directory and would find and use ~/files/dplyr/air.toml.", + "crumbs": [ + "Configuration" + ] + }, + { + "objectID": "configuration.html#format-options", + "href": "configuration.html#format-options", + "title": "Configuration", + "section": "Format options", + "text": "Format options\nAll formatting options are specified under the [format] table.\n\nline-width\nThe preferred maximum line length.\nAn integer value between 1 and 320, with a default of 80.\nWhile the formatter will attempt to format lines such that they remain within the line-width, it isn’t a hard upper bound, and formatted lines may exceed the line-width.\n\n\nindent-width\nThe number of spaces per indentation level.\nAn integer value between 1 and 24, with a default of 2.\nThis option changes the number of spaces the formatter inserts when using indent-style = \"space\". It also represents the width of a tab when indent-style = \"tab\" for the purposes of computing the line-width.\n\n\nindent-style\nWhether to use spaces or tabs for indentation.\nOne of the following values, with a default of \"space\":\n\n\"space\": Use spaces for indentation.\n\"tab\": Use tabs for indentation.\n\nAir defaults to spaces due to the overwhelming amount of existing R code written in this style, but consider using tabs for new projects to improve accessibility. See indent-width to configure the number of spaces per indentation and the tab width.\n\n\nline-ending\nThe character air uses at the end of a line.\nOne of the following values, with a default of \"auto\":\n\n\"auto\": The newline style is detected automatically on a file per file basis. Files with mixed line endings will be converted to the first detected line ending. Defaults to \\n for files that contain no line endings.\n\"lf\": Line endings will be converted to \\n. The typical line ending on Unix.\n\"crlf\": Line endings will be converted to \\r\\n. The typical line ending on Windows.\n\"native\": Line endings will be converted to \\n on Unix and \\r\\n on Windows.\n\n\n\nignore-magic-line-break\nWhether or not magic line breaks should be ignored.\nEither true to ignore magic line breaks, or false to respect them, with a default of false.\nAir respects a small set of magic line breaks as an indication that certain function calls or function signatures should be left expanded. For example, the following list could be flattened to one line and would still fit within a line-width of 80, however, it remains expanded due to the magic line break between the opening ( and the first argument, apple.\ndictionary <- list(\n apple = 0.75,\n banana = 0.25,\n cherry = 0.50\n)\nSimilarly, this function signature could also be flattened, but is not, due to the magic line break between the opening ( and the first parameter, ....\ncase_when <- function(\n ..., \n .default = NULL, \n .ptype = NULL, \n .size = NULL\n) {\n body\n}\nTo request flattening in these cases, just remove the magic line break. For example:\n# If you started here,\ndictionary <- list(\n apple = 0.75,\n banana = 0.25,\n cherry = 0.50\n)\n\n# then do this, and run air,\ndictionary <- list(apple = 0.75,\n banana = 0.25,\n cherry = 0.50\n)\n\n# to get this.\ndictionary <- list(apple = 0.75, banana = 0.25, cherry = 0.50)\nAlternatively, use a tool such as codegrip bound to a keyboard shortcut to flatten the code, and air will keep it flattened as long as it fits within the line-width.\nIt may be preferable to ignore magic line breaks if you prefer that line-width should be the only value that influences line breaks.", + "crumbs": [ + "Configuration" + ] + }, + { + "objectID": "formatter.html", + "href": "formatter.html", + "title": "Formatter", "section": "", - "text": "Air is an R formatter and language server, written in Rust.\n\nIntegrates with your favorite editor with support for\n\nFormat on save\nFormat selection\n\nUsable from the command line with support for\n\nFormatting individual files\nRecursively formatting entire directories\n--check mode, suitable for a git pre-commit hook or a GitHub Actions workflow\n\n\nIf you’d like to use Air from the command line, read our installation guide. If you’d like to use Air inside a code editor, read our editors guide.", + "text": "TODO", "crumbs": [ - "Overview" + "Formatter" ] }, { @@ -80,13 +110,23 @@ ] }, { - "objectID": "formatter.html", - "href": "formatter.html", - "title": "Formatter", + "objectID": "index.html", + "href": "index.html", + "title": "Overview", "section": "", - "text": "TODO", + "text": "Air is an R formatter and language server, written in Rust.\n\nIntegrates with your favorite editor with support for\n\nFormat on save\nFormat selection\n\nUsable from the command line with support for\n\nFormatting individual files\nRecursively formatting entire directories\n--check mode, suitable for a git pre-commit hook or a GitHub Actions workflow\n\n\nIf you’d like to use Air from the command line, read our installation guide. If you’d like to use Air inside a code editor, read our editors guide.", "crumbs": [ - "Formatter" + "Overview" + ] + }, + { + "objectID": "installation.html", + "href": "installation.html", + "title": "Installing Air", + "section": "", + "text": "If you’d like to use Air at the command line, you can use one of our standalone installers.\n\nTo install Air as a command line tool:\nOn macOS and Linux:\ncurl -LsSf https://github.com/posit-dev/air/releases/latest/download/air-installer.sh | sh\nOn Windows:\npowershell -c \"irm https://github.com/posit-dev/air/releases/latest/download/air-installer.ps1 | iex\"\nFor a specific version:\ncurl -LsSf https://github.com/posit-dev/air/releases/download/0.1.1/air-installer.sh | sh\npowershell -c \"irm https://github.com/posit-dev/air/releases/download/0.1.1/air-installer.ps1 | iex\"\nThe installer scripts will automatically add Air to your PATH. The very first time you install Air, for the PATH modifications to be applied you’ll need to restart your terminal.\nOn Windows, the first time you install Air it requires a full system restart for the PATH modification to take effect. We are working on improving this.", + "crumbs": [ + "Installation" ] } ] \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml index 3af7f07a..bb9ae80f 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -1,19 +1,23 @@ - https://posit-dev.github.io/air/installation.html - 2025-01-10T16:47:50.107Z + https://posit-dev.github.io/air/configuration.html + 2025-01-10T22:37:22.162Z - https://posit-dev.github.io/air/index.html - 2025-01-10T16:47:50.107Z + https://posit-dev.github.io/air/formatter.html + 2025-01-10T22:37:22.162Z https://posit-dev.github.io/air/editors.html - 2025-01-10T16:47:50.104Z + 2025-01-10T22:37:22.162Z - https://posit-dev.github.io/air/formatter.html - 2025-01-10T16:47:50.104Z + https://posit-dev.github.io/air/index.html + 2025-01-10T22:37:22.165Z + + + https://posit-dev.github.io/air/installation.html + 2025-01-10T22:37:22.165Z