Understanding Unqualified Names in R

In this article, we will explore the concept of unqualified names and how to retrieve a list of all such names that are currently in scope within an R environment.

Introduction to Unqualified Names

Unqualified names refer to identifiers used in R without specifying their namespace or package. For example, c, class(), and backSpline are all unqualified names because they can be accessed directly without qualifying them with a package name or namespace prefix.

In contrast, qualified names require the use of the namespace prefix, such as splines::backSpline.

Evaluating Expressions to Find Unqualified Names

To find unqualified names in R, we need to evaluate expressions that will return all identifiers defined in the current scope. We can start by evaluating simple expressions like class(c) and class(backSpline), which do not include qualified names.

> class(c)
[1] "function"

> class(backSpline)
Error: object 'backSpline' not found

> library(splines)

> class(backSpline)
[1] "function"

After loading the splines package, we can see that class(backSpline) returns no error and includes backSpline in its output. However, before loading the package, class(backSpline) reports an object not found error.

Using Apropos to Retrieve Unqualified Names

The R function apropos() is designed specifically for finding unqualified names within a given search path. By default, it searches all packages attached to the current environment.

To retrieve a list of all unqualified names in the current scope, we can use the following expression:

> apropos("")

[1] "backSpline"     "class"          "c"

As shown, apropos() returns a vector containing all unqualified names found within the search path.

Understanding Apropos Internals

The internal workings of apropos() can be explored using the following code:

> apropos(search())
[1] "backSpline"     "class"          "c"

By calling apropos() with no arguments, it searches all attached packages. However, by passing a character vector containing package names to apropos(), we can restrict the search path.

> apropos(c("splines", "stats"))
[1] "backSpline"     "class"

In this example, apropos() searches only within the splines and stats packages.

Understanding Unlist(sapply(search(), ls, all.names = T))

The internal implementation of apropos() relies on the following code:

> unlist(sapply(search(), ls, all.names = TRUE))
[1] "backSpline"     "class"          "c"

This expression uses sapply() to apply the ls() function across all packages found in the search path. The all.names = TRUE argument tells ls() to return a vector of all names, not just those within the current environment.

The resulting output is then passed to unlist() to remove any other unnecessary elements and produce a flat list of unqualified names.

Conclusion

In this article, we explored how to retrieve a list of all unqualified names currently in scope within an R environment. We used apropos(), which relies on the internal implementation using sapply(), ls() and unlist(). By understanding these concepts and using them effectively, you can create your own functions to find unqualified names in specific search paths.

Example Use Cases

• Searching all packages for a given function name:

> apropos("function")
[1] "backSpline"     "class"

• Restricting the search path to specific packages:

> apropos(c("splines", "stats"))
[1] "backSpline"     "class"

• Using unlist(sapply(search(), ls, all.names = T)) to get a flat list of unqualified names in the current environment:

> unlist(sapply(search(), ls, all.names = TRUE))
[1] "backSpline"     "class"          "c"

• Using apropos() with no arguments to search all attached packages for a given function name:

Last modified on 2024-10-22