EVOLUTION-MANAGER
Edit File: on_load.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: Run expressions on load</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 on_load {rlang}"><tr><td>on_load {rlang}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Run expressions on load</h2> <h3>Description</h3> <ul> <li> <p><code>on_load()</code> registers expressions to be run on the user's machine each time the package is loaded in memory. This is by contrast to normal R package code which is run once at build time on the packager's machine (e.g. CRAN). </p> <p><code>on_load()</code> expressions require <code>run_on_load()</code> to be called inside <code><a href="../../base/html/ns-hooks.html">.onLoad()</a></code>. </p> </li> <li> <p><code>on_package_load()</code> registers expressions to be run each time another package is loaded. </p> </li></ul> <p><code>on_load()</code> is for your own package and runs expressions when the namespace is not <em>sealed</em> yet. This means you can modify existing binding or create new ones. This is not the case with <code>on_package_load()</code> which runs expressions after a foreign package has finished loading, at which point its namespace is sealed. </p> <h3>Usage</h3> <pre> on_load(expr, env = parent.frame(), ns = topenv(env)) run_on_load(ns = topenv(parent.frame())) on_package_load(pkg, expr, env = parent.frame()) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>expr</code></td> <td> <p>An expression to run on load.</p> </td></tr> <tr valign="top"><td><code>env</code></td> <td> <p>The environment in which to evaluate <code>expr</code>. Defaults to the current environment, which is your package namespace if you run <code>on_load()</code> at top level.</p> </td></tr> <tr valign="top"><td><code>ns</code></td> <td> <p>The namespace in which to hook <code>expr</code>.</p> </td></tr> <tr valign="top"><td><code>pkg</code></td> <td> <p>Package to hook expression into.</p> </td></tr> </table> <h3>When should I run expressions on load?</h3> <p>There are two main use cases for running expressions on load: </p> <ol> <li><p> When a side effect, such as registering a method with <code>s3_register()</code>, must occur in the user session rather than the package builder session. </p> </li> <li><p> To avoid hard-coding objects from other packages in your namespace. If you assign <code>foo::bar</code> or the result of <code>foo::baz()</code> in your package, they become constants. Any upstream changes in the <code>foo</code> package will not be reflected in the objects you've assigned in your namespace. This often breaks assumptions made by the authors of <code>foo</code> and causes all sorts of issues. </p> <p>Recreating the foreign objects each time your package is loaded makes sure that any such changes will be taken into account. In technical terms, running an expression on load introduces <em>indirection</em>. </p> </li></ol> <h3>Comparison with <code>.onLoad()</code></h3> <p><code>on_load()</code> has the advantage that hooked expressions can appear in any file, in context. This is unlike <code>.onLoad()</code> which gathers disparate expressions in a single block. </p> <p><code>on_load()</code> is implemented via <code>.onLoad()</code> and requires <code>run_on_load()</code> to be called from that hook. </p> <h3>Examples</h3> <pre> quote({ # Not run # First add `run_on_load()` to your `.onLoad()` hook, # then use `on_load()` anywhere in your package .onLoad <- function(lib, pkg) { run_on_load() } # Register a method on load on_load(s3_register("foo::bar", "my_class")) # Assign an object on load var <- NULL on_load( var <- foo() ) # To use `on_package_load()` at top level, wrap it in `on_load()` on_load(on_package_load("foo", message("foo is loaded"))) # In functions it can be called directly f <- function() on_package_load("foo", message("foo is loaded")) }) </pre> <hr /><div style="text-align: center;">[Package <em>rlang</em> version 1.0.6 <a href="00Index.html">Index</a>]</div> </body></html>