attach                 package:base                 R Documentation

_A_t_t_a_c_h _S_e_t _o_f _R _O_b_j_e_c_t_s _t_o _S_e_a_r_c_h _P_a_t_h

_D_e_s_c_r_i_p_t_i_o_n:

     The database is attached to the R search path.  This means that
     the database is searched by R when evaluating a variable, so
     objects in the database can be accessed by simply giving their
     names.

_U_s_a_g_e:

     attach(what, pos = 2, name = deparse(substitute(what)),
            warn.conflicts = TRUE)

_A_r_g_u_m_e_n_t_s:

    what: 'database'.  This can be a 'data.frame' or a 'list' or a R
          data file created with 'save' or 'NULL' or an environment. 
          See also 'Details'.

     pos: integer specifying position in 'search()' where to attach.

    name: name to use for the attached database.

warn.conflicts: logical.  If 'TRUE', warnings are printed about
          'conflicts' from attaching the database, unless that database
          contains an object '.conflicts.OK'.  A conflict is a function
          masking a function, or a non-function masking a non-function. 

_D_e_t_a_i_l_s:

     When evaluating a variable or function name R searches for that
     name in the databases listed by 'search'.  The first name of the
     appropriate type is used.

     By attaching a data frame (or list) to the search path it is
     possible to refer to the variables in the data frame by their
     names alone, rather than as components of the data frame (e.g. in
     the example below, 'height' rather than 'women$height').

     By default the database is attached in position 2 in the search
     path, immediately after the user's workspace and before all
     previously loaded packages and previously attached databases. 
     This can be altered to attach later in the search path with the
     'pos' option, but you cannot attach at 'pos=1'.

     The database is not actually attached.  Rather, a new environment
     is created on the search path and the elements of a list
     (including columns of a data frame) or objects in a save file or
     an environment are _copied_ into the new environment.  If you use
     '<<-' or 'assign' to assign to an attached database, you only
     alter the attached copy, not the original object. (Normal
     assignment will place a modified version in the user's workspace:
     see the examples.) For this reason 'attach' can lead to confusion.

     One useful 'trick' is to use 'what = NULL' (or equivalently a
     length-zero list) to create a new environment on the search path
     into which objects can be assigned by 'assign' or 'load' or
     'sys.source'.

     Names starting '"package:"' are reserved for 'library' and should
     not be used by end users.  The name given for the attached
     environment will be used by 'search' and can be used as the
     argument to 'as.environment'.

     There are hooks to attach user-defined table objects of class
     '"UserDefinedDatabase"', supported by the Omegahat package
     'RObjectTables'.  See <URL:
     http://www.omegahat.org/RObjectTables/>.

_V_a_l_u_e:

     The 'environment' is returned invisibly with a '"name"' attribute.

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

_S_e_e _A_l_s_o:

     'library', 'detach', 'search', 'objects', 'environment', 'with'.

_E_x_a_m_p_l_e_s:

     require(utils)

     summary(women$height)   # refers to variable 'height' in the data frame
     attach(women)
     summary(height)         # The same variable now available by name
     height <- height*2.54   # Don't do this. It creates a new variable
                             # in the user's workspace
     find("height")
     summary(height)         # The new variable in the workspace
     rm(height)
     summary(height)         # The original variable.
     height <<- height*25.4  # Change the copy in the attached environment
     find("height")
     summary(height)         # The changed copy
     detach("women")
     summary(women$height)   # unchanged

     ## Not run: 
     ## create an environment on the search path and populate it
     sys.source("myfuns.R", envir=attach(NULL, name="myfuns"))
     ## End(Not run)