EVOLUTION-MANAGER
Edit File: pluralization.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: About cli pluralization</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for pluralization {cli}"><tr><td>pluralization {cli}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>About cli pluralization</h2> <h3>Description</h3> <p>About cli pluralization </p> <h3>Introduction</h3> <p>cli has tools to create messages that are printed correctly in singular and plural forms. This usually requires minimal extra work, and increases the quality of the messages greatly. In this document we first show some pluralization examples that you can use as guidelines. Hopefully these are intuitive enough, so that they can be used without knowing the exact cli pluralization rules. </p> <p>If you need pluralization without the semantic cli functions, see the <code>pluralize()</code> function. </p> <h3>Examples</h3> <h4>Pluralization markup</h4> <p>In the simplest case the message contains a single <code>{}</code> glue substitution, which specifies the quantity that is used to select between the singular and plural forms. Pluralization uses markup that is similar to glue, but uses the <code style="white-space: pre;">{?</code> and <code style="white-space: pre;">}</code> delimiters: </p> <div class="sourceCode r"><pre>library(cli) nfile <- 0; cli_text("Found {nfile} file{?s}.") </pre></div> <div class="sourceCode"><pre>#> Found 0 files. </pre></div> <div class="sourceCode r"><pre>nfile <- 1; cli_text("Found {nfile} file{?s}.") </pre></div> <div class="sourceCode"><pre>#> Found 1 file. </pre></div> <div class="sourceCode r"><pre>nfile <- 2; cli_text("Found {nfile} file{?s}.") </pre></div> <div class="sourceCode"><pre>#> Found 2 files. </pre></div> <p>Here the value of <code>nfile</code> is used to decide whether the singular or plural form of <code>file</code> is used. This is the most common case for English messages. </p> <h4>Irregular plurals</h4> <p>If the plural form is more difficult than a simple <code>s</code> suffix, then the singular and plural forms can be given, separated with a forward slash: </p> <div class="sourceCode r"><pre>ndir <- 1; cli_text("Found {ndir} director{?y/ies}.") </pre></div> <div class="sourceCode"><pre>#> Found 1 directory. </pre></div> <div class="sourceCode r"><pre>ndir <- 5; cli_text("Found {ndir} director{?y/ies}.") </pre></div> <div class="sourceCode"><pre>#> Found 5 directories. </pre></div> <h4>Use <code>"no"</code> instead of zero</h4> <p>For readability, it is better to use the <code>no()</code> helper function to include a count in a message. <code>no()</code> prints the word <code>"no"</code> if the count is zero, and prints the numeric count otherwise: </p> <div class="sourceCode r"><pre>nfile <- 0; cli_text("Found {no(nfile)} file{?s}.") </pre></div> <div class="sourceCode"><pre>#> Found no files. </pre></div> <div class="sourceCode r"><pre>nfile <- 1; cli_text("Found {no(nfile)} file{?s}.") </pre></div> <div class="sourceCode"><pre>#> Found 1 file. </pre></div> <div class="sourceCode r"><pre>nfile <- 2; cli_text("Found {no(nfile)} file{?s}.") </pre></div> <div class="sourceCode"><pre>#> Found 2 files. </pre></div> <h4>Use the length of character vectors</h4> <p>With the auto-collapsing feature of cli it is easy to include a list of objects in a message. When cli interprets a character vector as a pluralization quantity, it takes the length of the vector: </p> <div class="sourceCode r"><pre>pkgs <- "pkg1" cli_text("Will remove the {.pkg {pkgs}} package{?s}.") </pre></div> <div class="sourceCode"><pre>#> Will remove the pkg1 package. </pre></div> <div class="sourceCode r"><pre>pkgs <- c("pkg1", "pkg2", "pkg3") cli_text("Will remove the {.pkg {pkgs}} package{?s}.") </pre></div> <div class="sourceCode"><pre>#> Will remove the pkg1, pkg2, and pkg3 packages. </pre></div> <p>Note that the length is only used for non-numeric vectors (when <code>is.numeric(x)</code> return <code>FALSE</code>). If you want to use the length of a numeric vector, convert it to character via <code>as.character()</code>. </p> <p>You can combine collapsed vectors with <code>"no"</code>, like this: </p> <div class="sourceCode r"><pre>pkgs <- character() cli_text("Will remove {?no/the/the} {.pkg {pkgs}} package{?s}.") </pre></div> <div class="sourceCode"><pre>#> Will remove no packages. </pre></div> <div class="sourceCode r"><pre>pkgs <- c("pkg1", "pkg2", "pkg3") cli_text("Will remove {?no/the/the} {.pkg {pkgs}} package{?s}.") </pre></div> <div class="sourceCode"><pre>#> Will remove the pkg1, pkg2, and pkg3 packages. </pre></div> <p>When the pluralization markup contains three alternatives, like above, the first one is used for zero, the second for one, and the third one for larger quantities. </p> <h4>Choosing the right quantity</h4> <p>When the text contains multiple glue <code>{}</code> substitutions, the one right before the pluralization markup is used. For example: </p> <div class="sourceCode r"><pre>nfiles <- 3; ndirs <- 1 cli_text("Found {nfiles} file{?s} and {ndirs} director{?y/ies}") </pre></div> <div class="sourceCode"><pre>#> Found 3 files and 1 directory </pre></div> <p>This is sometimes not the the correct one. You can explicitly specify the correct quantity using the <code>qty()</code> function. This sets that quantity without printing anything: </p> <div class="sourceCode r"><pre>nupd <- 3; ntotal <- 10 cli_text("{nupd}/{ntotal} {qty(nupd)} file{?s} {?needs/need} updates") </pre></div> <div class="sourceCode"><pre>#> 3/10 files need updates </pre></div> <p>Note that if the message only contains a single <code>{}</code> substitution, then this may appear before or after the pluralization markup. If the message contains multiple <code>{}</code> substitutions <em>after</em> pluralization markup, an error is thrown. </p> <p>Similarly, if the message contains no <code>{}</code> substitutions at all, but has pluralization markup, an error is thrown. </p> <h3>Rules</h3> <p>The exact rules of cli pluralization. There are two sets of rules. The first set specifies how a quantity is associated with a <code style="white-space: pre;">{?}</code> pluralization markup. The second set describes how the <code style="white-space: pre;">{?}</code> is parsed and interpreted. </p> <h4>Quantities</h4> <ol> <li> <p><code>{}</code> substitutions define quantities. If the value of a <code>{}</code> substitution is numeric (when <code>is.numeric(x)</code> holds), then it has to have length one to define a quantity. This is only enforced if the <code>{}</code> substitution is used for pluralization. The quantity is defined as the value of <code>{}</code> then, rounded with <code>as.integer()</code>. If the value of <code>{}</code> is not numeric, then its quantity is defined as its length. </p> </li> <li><p> If a message has <code style="white-space: pre;">{?}</code> markup but no <code>{}</code> substitution, an error is thrown. </p> </li> <li><p> If a message has exactly one <code>{}</code> substitution, its value is used as the pluralization quantity for all <code style="white-space: pre;">{?}</code> markup in the message. </p> </li> <li><p> If a message has multiple <code>{}</code> substitutions, then for each <code style="white-space: pre;">{?}</code> markup cli uses the quantity of the <code>{}</code> substitution that precedes it. </p> </li> <li><p> If a message has multiple <code>{}</code> substitutions and has pluralization markup without a preceding <code>{}</code> substitution, an error is thrown. </p> </li></ol> <h4>Pluralization markup</h4> <ol> <li><p> Pluralization markup starts with <code style="white-space: pre;">{?</code> and ends with <code style="white-space: pre;">}</code>. It may not contain <code style="white-space: pre;">{</code> and <code style="white-space: pre;">}</code> characters, so it may not contain <code>{}</code> substitutions either. </p> </li> <li><p> Alternative words or suffixes are separated by <code>/</code>. </p> </li> <li><p> If there is a single alternative, then <em>nothing</em> is used if <code>quantity == 1</code> and this single alternative is used if <code>quantity != 1</code>. </p> </li> <li><p> If there are two alternatives, the first one is used for <code>quantity == 1</code>, the second one for <code>quantity != 1</code> (including '<code>quantity == 0</code>). </p> </li> <li><p> If there are three alternatives, the first one is used for <code>quantity == 0</code>, the second one for <code>quantity == 1</code>, and the third one otherwise. </p> </li></ol> <h3>See Also</h3> <p>Other pluralization: <code><a href="pluralization-helpers.html">no</a>()</code>, <code><a href="pluralize.html">pluralize</a>()</code> </p> <hr /><div style="text-align: center;">[Package <em>cli</em> version 3.4.1 <a href="00Index.html">Index</a>]</div> </body></html>