cdfind               package:mvbutils               R Documentation

_H_i_e_r_a_r_c_h_y-_c_r_a_w_l_i_n_g _f_u_n_c_t_i_o_n_s _f_o_r _c_d-_o_r_g_a_n_i_z_e_d _w_o_r_k_s_p_a_c_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     These functions work through part or all of a workspace (task)
     hierarchy set up via 'cd'. 'cdfind' searches for objects through
     the (attached and unattached) task hierarchy. 'cdtree' displays
     the hierarchy structure. 'cd.change.all.paths' is useful for
     moving or migrating all or part of the hierarchy to new disk
     directories. 'cd.write.mvb.tasks' sets up sourceable text
     representations of the hierarchy, as a safeguard. 'cditerate' is
     the engine that crawls through the hierarchy, underpinning the
     others; you can write your own functions to be called by
     'cditerate'.

_U_s_a_g_e:

     cdfind( pattern, from = ., from.text)
     cdtree( from = ., from.text = substitute(from), charlim = 90)
     cd.change.all.paths( from.text = "0", old.path, new.path)
     cd.write.mvb.tasks( from = ., from.text = substitute(from))
     cditerate( from.text, what.to.do, so.far = vector("NULL", 0), ...)

_A_r_g_u_m_e_n_t_s:

 pattern: regexpr to be checked against object names.

    from: unquoted path specifier (see 'cd'); make this 0 to operate on
          the entire hierarchy.

 from.text: use this in place of 'from' if you want to use a character
          string instead

 charlim: maximum characters per line allowed in graphical display of
          'cdtree'; reduce if unreadable, or change par( 'cex')

 old.path: regexpr showing portion of directory names to be replaced

 new.path: replacement portion of directory names

 what.to.do: function to be called on each task (see DETAILS)

  so.far: starting value for accumulated list of function results

     ...: further fixed arguments to be passed to 'what.to.do'

_D_e_t_a_i_l_s:

     All these functions start by default from the task that is
     currently top of the search list, and only look further down the
     hiearchy (i.e. to unattached descendents). To make them work
     through the whole hierarchy, supply '0' as the 'from' argument.

     If you want to automatically crawl through the task hierarchy to
     do something else, you can write a wrapper function which calls
     'cditerate', and an inner function to be passed as the
     'what.to.do' argument to 'cditerate'. The wrapper function will
     typically be very short; see the code of 'cdfind' for an example.

     The inner function (typically called 'cdsomething.guts') must have
     arguments 'found', 'task.dir', 'task.name', and 'env', and may
     have any other arguments, which will be set according as the '...'
     argument of 'cditerate'. 'found' accumulates the results of
     previous calls to 'what.to.do'. Your inner function can augment
     'found', and should return the (possibly augmented) 'found'. As
     for the other parameters: 'task.dir' is obvious; 'task.name' is a
     character(1) giving the full path specifier, e.g. '"ROOT/mytask"';
     and 'env' holds the environment into which the task has been
     (temporarily) loaded. 'env' allows you to examine the task; for
     instance, you can check objects in the task by calling
     'ls(env=env)' inside your 'what.to.do' function. See the code of
     'cdfind.guts' for an example.

_V_a_l_u_e:

     'cdfind' returns a list with one element for each object that is
     found somewhere; each such element is a character vector showing
     the tasks where the object was found. 'cdtree' returns an object
     of class 'cdtree', which is normally printed with indentations to
     show the hierarchy. You can also 'plot(cdtree(...))' to see a
     graphical display. 'cd.change.all.paths' and 'cd.write.mvb.tasks'
     do not return anything useful.

_A_u_t_h_o_r(_s):

     Mark Bravington

_E_x_a_m_p_l_e_s:

     cdfind( ".First", 0) # probably returns list( .First="ROOT")

