如何为自定义R包编写可被demo()调用的演示程序？

我来帮你梳理清楚怎么给自定义R包写demo()能运行的演示程序——这个过程完全手动可控，而且完全支持在纯R控制台使用，和RStudio没有依赖关系。

1. 先搭好基础文件结构 #

首先，在你的R包根目录下创建一个小写的demo文件夹，所有演示脚本都要放在这里。

• 演示脚本可以用.R后缀命名（比如scoping_demo.R），也可以不带后缀，但推荐带.R，方便识别。
• 脚本里如果需要调用包内的函数，保险起见可以在开头加上library(yourpackage)或者用yourpackage::your_function()的形式——虽然用户运行demo()时你的包大概率已经加载了，但这样能避免意外报错。

2. 编写演示脚本的小技巧 #

演示脚本就是普通的R代码，demo()会按顺序执行，默认每段会暂停（等用户按回车继续）。举个简单的示例，假设你的包叫mypkg，demo/scoping_demo.R可以这么写：

# 这是自定义作用域功能的演示
cat("=== 开始演示包内的作用域函数 ===\n")

# 调用包内的自定义函数
mypkg::my_scoped_func()

# 演示变量作用域差异
x <- 10
cat("\n原始x的值：", x, "\n")
mypkg::modify_x(x)
cat("调用modify_x后的x值：", x, "\n")

# 用注释分段，demo运行时会自动显示这些注释

如果想让demo全程自动运行不暂停，可以在脚本开头加options(demo.ask = FALSE)，或者用户运行时用demo("scoping_demo", ask = FALSE)。

3. 让R识别到你的demo #

必须在包的DESCRIPTION文件里添加一行配置，告诉R你的包有哪些demo：

Demo: scoping_demo, another_demo

这里的名字对应demo文件夹里的脚本名（如果脚本是.R后缀，可以省略后缀），多个demo用逗号分隔就行。

4. 测试你的demo #

开发阶段可以用devtools::load_all()加载包，然后运行demo("scoping_demo", package = "mypkg")测试；正式构建安装后，直接在R控制台输入demo("scoping_demo")就能运行了。

额外提示 #

• 用cat()打印说明文字能让demo的输出更清晰，比纯注释更醒目
• 尽量避免在demo里修改用户的全局环境，比如可以用局部环境包裹代码，或者运行完清理临时变量
• 其实R官方的包编写手册里有关于demo的详细说明，之前你可能没留意到，核心就是demo文件夹+DESCRIPTION配置这两步

内容的提问来源于stack exchange，提问作者Tan Jason