EVOLUTION-MANAGER
Edit File: namespace.html
<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta name="generator" content="pandoc" /> <meta http-equiv="X-UA-Compatible" content="IE=EDGE" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Managing imports and exports</title> <script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to // be compatible with the behavior of Pandoc < 2.8). document.addEventListener('DOMContentLoaded', function(e) { var hs = document.querySelectorAll("div.section[class*='level'] > :first-child"); var i, h, a; for (i = 0; i < hs.length; i++) { h = hs[i]; if (!/^h[1-6]$/i.test(h.tagName)) continue; // it should be a header h1-h6 a = h.attributes; while (a.length > 0) h.removeAttribute(a[0].name); } }); </script> <style type="text/css"> code{white-space: pre-wrap;} span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} </style> <style type="text/css"> code { white-space: pre; } .sourceCode { overflow: visible; } </style> <style type="text/css" data-origin="pandoc"> pre > code.sourceCode { white-space: pre; position: relative; } pre > code.sourceCode > span { display: inline-block; line-height: 1.25; } pre > code.sourceCode > span:empty { height: 1.2em; } .sourceCode { overflow: visible; } code.sourceCode > span { color: inherit; text-decoration: inherit; } div.sourceCode { margin: 1em 0; } pre.sourceCode { margin: 0; } @media screen { div.sourceCode { overflow: auto; } } @media print { pre > code.sourceCode { white-space: pre-wrap; } pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; } } pre.numberSource code { counter-reset: source-line 0; } pre.numberSource code > span { position: relative; left: -4em; counter-increment: source-line; } pre.numberSource code > span > a:first-child::before { content: counter(source-line); position: relative; left: -1em; text-align: right; vertical-align: baseline; border: none; display: inline-block; -webkit-touch-callout: none; -webkit-user-select: none; -khtml-user-select: none; -moz-user-select: none; -ms-user-select: none; user-select: none; padding: 0 4px; width: 4em; color: #aaaaaa; } pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } div.sourceCode { } @media screen { pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } } code span.al { color: #ff0000; font-weight: bold; } /* Alert */ code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ code span.at { color: #7d9029; } /* Attribute */ code span.bn { color: #40a070; } /* BaseN */ code span.bu { } /* BuiltIn */ code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ code span.ch { color: #4070a0; } /* Char */ code span.cn { color: #880000; } /* Constant */ code span.co { color: #60a0b0; font-style: italic; } /* Comment */ code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ code span.do { color: #ba2121; font-style: italic; } /* Documentation */ code span.dt { color: #902000; } /* DataType */ code span.dv { color: #40a070; } /* DecVal */ code span.er { color: #ff0000; font-weight: bold; } /* Error */ code span.ex { } /* Extension */ code span.fl { color: #40a070; } /* Float */ code span.fu { color: #06287e; } /* Function */ code span.im { } /* Import */ code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ code span.kw { color: #007020; font-weight: bold; } /* Keyword */ code span.op { color: #666666; } /* Operator */ code span.ot { color: #007020; } /* Other */ code span.pp { color: #bc7a00; } /* Preprocessor */ code span.sc { color: #4070a0; } /* SpecialChar */ code span.ss { color: #bb6688; } /* SpecialString */ code span.st { color: #4070a0; } /* String */ code span.va { color: #19177c; } /* Variable */ code span.vs { color: #4070a0; } /* VerbatimString */ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ </style> <script> // apply pandoc div.sourceCode style to pre.sourceCode instead (function() { var sheets = document.styleSheets; for (var i = 0; i < sheets.length; i++) { if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue; try { var rules = sheets[i].cssRules; } catch (e) { continue; } for (var j = 0; j < rules.length; j++) { var rule = rules[j]; // check if there is a div.sourceCode rule if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") continue; var style = rule.style.cssText; // check if color or background-color is set if (rule.style.color === '' && rule.style.backgroundColor === '') continue; // replace div.sourceCode by a pre.sourceCode rule sheets[i].deleteRule(j); sheets[i].insertRule('pre.sourceCode{' + style + '}', j); } } })(); </script> <style type="text/css">body { background-color: #fff; margin: 1em auto; max-width: 700px; overflow: visible; padding-left: 2em; padding-right: 2em; font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; font-size: 14px; line-height: 1.35; } #TOC { clear: both; margin: 0 0 10px 10px; padding: 4px; width: 400px; border: 1px solid #CCCCCC; border-radius: 5px; background-color: #f6f6f6; font-size: 13px; line-height: 1.3; } #TOC .toctitle { font-weight: bold; font-size: 15px; margin-left: 5px; } #TOC ul { padding-left: 40px; margin-left: -1.5em; margin-top: 5px; margin-bottom: 5px; } #TOC ul ul { margin-left: -2em; } #TOC li { line-height: 16px; } table { margin: 1em auto; border-width: 1px; border-color: #DDDDDD; border-style: outset; border-collapse: collapse; } table th { border-width: 2px; padding: 5px; border-style: inset; } table td { border-width: 1px; border-style: inset; line-height: 18px; padding: 5px 5px; } table, table th, table td { border-left-style: none; border-right-style: none; } table thead, table tr.even { background-color: #f7f7f7; } p { margin: 0.5em 0; } blockquote { background-color: #f6f6f6; padding: 0.25em 0.75em; } hr { border-style: solid; border: none; border-top: 1px solid #777; margin: 28px 0; } dl { margin-left: 0; } dl dd { margin-bottom: 13px; margin-left: 13px; } dl dt { font-weight: bold; } ul { margin-top: 0; } ul li { list-style: circle outside; } ul ul { margin-bottom: 0; } pre, code { background-color: #f7f7f7; border-radius: 3px; color: #333; white-space: pre-wrap; } pre { border-radius: 3px; margin: 5px 0px 10px 0px; padding: 10px; } pre:not([class]) { background-color: #f7f7f7; } code { font-family: Consolas, Monaco, 'Courier New', monospace; font-size: 85%; } p > code, li > code { padding: 2px 0px; } div.figure { text-align: center; } img { background-color: #FFFFFF; padding: 2px; border: 1px solid #DDDDDD; border-radius: 3px; border: 1px solid #CCCCCC; margin: 0 5px; } h1 { margin-top: 0; font-size: 35px; line-height: 40px; } h2 { border-bottom: 4px solid #f7f7f7; padding-top: 10px; padding-bottom: 2px; font-size: 145%; } h3 { border-bottom: 2px solid #f7f7f7; padding-top: 10px; font-size: 120%; } h4 { border-bottom: 1px solid #f7f7f7; margin-left: 8px; font-size: 105%; } h5, h6 { border-bottom: 1px solid #ccc; font-size: 105%; } a { color: #0033dd; text-decoration: none; } a:hover { color: #6666ff; } a:visited { color: #800080; } a:visited:hover { color: #BB00BB; } a[href^="http:"] { text-decoration: underline; } a[href^="https:"] { text-decoration: underline; } code > span.kw { color: #555; font-weight: bold; } code > span.dt { color: #902000; } code > span.dv { color: #40a070; } code > span.bn { color: #d14; } code > span.fl { color: #d14; } code > span.ch { color: #d14; } code > span.st { color: #d14; } code > span.co { color: #888888; font-style: italic; } code > span.ot { color: #007020; } code > span.al { color: #ff0000; font-weight: bold; } code > span.fu { color: #900; font-weight: bold; } code > span.er { color: #a61717; background-color: #e3d2d2; } </style> </head> <body> <h1 class="title toc-ignore">Managing imports and exports</h1> <p>The package <code>NAMESPACE</code> is one of the most confusing parts of building a package. roxygen2 aims to make it as easy as possible to build a package that is a well-behaved member of the R ecosystem. This is a little frustrating at first, but soon becomes second-nature.</p> <div id="exports" class="section level2"> <h2>Exports</h2> <p>For a function to be usable outside your package, you must <strong>export</strong> it. By default roxygen2 doesn’t export anything from your package. If you want an object to be publicly available, you must explicitly tag it with <code>@export</code>.</p> <p>Use the following guidelines to decide what to export:</p> <ul> <li><p><strong>Functions</strong>: export functions that you want to make available. Exported functions must be documented, and you must be cautious when changing their interface.</p></li> <li><p><strong>Datasets</strong>: all datasets are publicly available. They exist outside of the package namespace and must not be exported.</p></li> <li><p><strong>S3 classes</strong>: if you want others to be able to create instances of the class <code>@export</code> the constructor function.</p></li> <li><p><strong>S3 generics</strong>: the generic is a function, so <code>@export</code> if you want it to be usable outside the package.</p></li> <li><p><strong>S3 methods</strong>: every S3 method <em>must</em> be exported, even if the generic is not. Otherwise, the S3 method table will not be generated correctly and internal generics will not find the correct method. See below for instructions on how to export a method for a generic in a suggested package.</p></li> <li><p><strong>S4 classes</strong>: export S4 classes if you want others to be able to extend them.</p></li> <li><p><strong>S4 generics:</strong> <code>@export</code> if you want the generic to be publicly usable.</p></li> <li><p><strong>S4 methods</strong>: you only need to <code>@export</code> methods for generics in other packages.</p></li> </ul> <div id="s3-methods-for-generics-in-suggested-packages" class="section level3"> <h3>S3 methods for generics in suggested packages</h3> <p><code>@exportS3Method</code> tag allows you to generate <code>S3method()</code> namespace directives. Its primary use is for “delayed” method registration, which allows you to define methods for generics found in suggested packages (R >= 3.6). For example,</p> <div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="co">#' @exportS3Method pkg::generic</span></span> <span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a>generic.foo <span class="ot"><-</span> <span class="cf">function</span>(x, ...) {</span> <span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a>}</span></code></pre></div> <p>will generate</p> <pre><code>S3method(pkg::generic, foo)</code></pre> <p>Which will cause the method to be registered only when pkg is loaded.</p> </div> <div id="manual-exports" class="section level3"> <h3>Manual exports</h3> <p>If <code>@export</code> does not automatically generate the correct directive when, you can use one of the tags below to exercise greater control:</p> <ul> <li><code>@export foo</code> generates <code>export(foo)</code></li> <li><code>@exportS3Method generic method</code> generates <code>S3method(generic, method)</code></li> <li><code>@exportClass foo</code> generates <code>exportClasses(foo)</code></li> <li><code>@exportMethod foo</code> generates <code>exportMethods(foo)</code></li> <li><code>@exportPattern foo</code> generates <code>exportPattern(foo)</code></li> </ul> <p>For even more specialised cases you can use <code>@rawNamespace code</code> which inserts <code>code</code> literally into the <code>NAMESPACE</code>. If you need to automate this, <code>@evalNamespace fun()</code> will evaluate <code>fun()</code> in the package environment and insert the results into <code>NAMESPACE</code>. Because <code>evalNamespace()</code> is run in the package environment, it can only generate exports, not imports.</p> </div> </div> <div id="imports" class="section level2"> <h2>Imports</h2> <p>The <code>NAMESPACE</code> also controls which functions from other packages are made available to your package.</p> <div id="functions" class="section level3"> <h3>Functions</h3> <p>If you are using just a few functions from another package, we recommending adding the package to the <code>Imports:</code> field of the <code>DESCRIPTION</code> file and calling the functions explicitly using <code>::</code>, e.g., <code>pkg::fun()</code>.</p> <div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a>my_function <span class="ot"><-</span> <span class="cf">function</span>(x, y) {</span> <span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a> pkg<span class="sc">::</span><span class="fu">fun</span>(x) <span class="sc">*</span> y</span> <span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a>}</span></code></pre></div> <p>If the repetition of the package name becomes annoying you can <code>@importFrom</code> and drop the <code>::</code>:</p> <div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="co">#' @importFrom pkg fun </span></span> <span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a>my_function <span class="ot"><-</span> <span class="cf">function</span>(x, y) {</span> <span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a> <span class="fu">fun</span>(x) <span class="sc">*</span> y</span> <span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a>}</span></code></pre></div> <p>Imports affect every function in a package, so it’s common to collect them in a central place, like <code>{packagename}-package.R</code>. This is automated by <code>usethis::use_import_from()</code>.</p> <div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="co">#' @importFrom pkg fun1 fun2</span></span> <span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="co">#' @importFrom pkg2 fun3</span></span> <span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="co">#' @importFrom pkg3 fun4</span></span> <span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a><span class="cn">NULL</span></span> <span id="cb5-5"><a href="#cb5-5" aria-hidden="true" tabindex="-1"></a><span class="co">#> NULL</span></span></code></pre></div> <p>Note the use of <code>NULL</code> here: you must provide something for roxygen2 to document, so we use <code>NULL</code> as place holder.</p> <p>It is possible, but not generally recommended to import all functions from a package with <code>@import package</code>. This is risky if you import functions from more than one package, because while it might be ok today, in the future the packages might end up with a function having the same name, and your users will get a warning every time your package is loaded.</p> </div> <div id="s3" class="section level3"> <h3>S3</h3> <p>S3 generics are just functions, so the same rules for functions apply. S3 methods always accompany the generic, so as long as you can access the generic (either implicitly or explicitly), the methods will also be available. In other words, you don’t need to do anything special for S3 methods. As long as you’ve imported the generic, all the methods will also be available.</p> </div> <div id="s4" class="section level3"> <h3>S4</h3> <ul> <li>To use classes defined in another package, place <code>@importClassesFrom package ClassA ClassB ...</code> next to the classes that inherit from the imported classes, or next to the methods that implement a generic for the imported classes.</li> <li>To use generics defined in another package, place <code>@importMethodsFrom package GenericA GenericB ...</code> next to the methods that use the imported generics.</li> </ul> </div> <div id="compiled-code" class="section level3"> <h3>Compiled code</h3> <p>To import compiled code from another package, use <code>@useDynLib</code></p> <ul> <li><p><code>@useDynLib package</code> imports all compiled functions.</p></li> <li><p><code>@useDynLib package routinea routineb</code> imports selected compiled functions.</p></li> <li><p>Any <code>@useDynLib</code> specification containing a comma, e.g. <code>@useDynLib mypackage, .registration = TRUE</code> will be inserted as is into the the NAMESPACE, e.g. <code>useDynLib(mypackage, .registration = TRUE)</code></p></li> </ul> </div> </div> <!-- code folding --> <!-- dynamically load mathjax for compatibility with self-contained --> <script> (function () { var script = document.createElement("script"); script.type = "text/javascript"; script.src = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"; document.getElementsByTagName("head")[0].appendChild(script); })(); </script> </body> </html>