= Managing your files and applications =

== Adding files and directories ==

You can add files to the !RefactorErl database by calling the
add function with either a filename as a string or a module name as an atom.
Note that in the latter case, "ri" defaults to the current working directory
(which you may work around by including a path in your singe-quoted atom).
If you specify a directory instead of a regular filename, then it will be recursively
traversed. You may just as well give a list of atoms or strings to add more files
at once. All of the following example commands would add the same file:

{{{
#!erlang
 cd(dir), ri:add(modname).
 ri:add('dir/modname').
 ri:add(['dir/modname']).
 ri:add("dir/modname.erl").
 ri:add("/current/dir/modname.erl").
 ri:add("path_to_dir/dir").
}}}

Usually, Erlang source files (having the extension
.erl) are loaded into !RefactorErl. In addition, !RefactorErl is also capable of
loading compiled .beam files.

{{{
#!erlang
ri:add("compiled.beam").
}}}

Note that this feature is applicable only to those .beam files that were compiled
with the debug_info option. Also note that the resulting file will be pretty
printed by !RefactorErl.

== Dropping files and directories ==

The module displays the progression of loading.
Removing files from the database is similarly easy and also recursive. 
The following will equally work:

{{{
#!erlang
 ri:drop(modname).
 ri:drop([modname]).
 ri:drop("dir/modname.erl").
 ri:drop("/current/dir/modname.erl").
 ri:drop("path_to_dir/dir").
}}}

== Adding applications ==

Modules can be loaded as applications, but some configurations has to be made before.
The configurations can be done manually by setting the enviromental nodes, or can be done automatically by using the [http://www.erlang.org/doc/man/make.html Emakefile] handling functions (beta version) of the tool.

=== Adding applications by manual configuration ===

The manually configuration can be done by using the {{{ri}}} or the {{{ris}}} module.

Modules can be loaded as applications, but the base of your library has to
be set before:

{{{
#!erlang
ri:addenv(appbase, "path/to/my/applib").
}}}

If the application has additional include directories, then these directories has to be also set in advance:

{{{
#!erlang
ri:addenv(include, "path/to/my/incldir").
}}}

If the application build process contains compile-time macros, then these macros also can be set:

{{{
#!erlang
%if it is only used in ifdef forms.
ri:addenv(def, 'my_macro').

ri:addenv(def, {'my_macro', my_macro_value}).
}}}

If the include forms of the application contain OS based enviromental nodes, then these nodes can be set:

{{{
#!erlang
ri:addenv(env_var, {os_env_name, "os_env_path"}).
}}}

Let's see an example:

The Emakefile has the following contents:
{{{
#!erlang

{"/home/user/dev/lib/app1/src/*",
   [{i,"/home/user/dev/lib/"},
    {d,'MY_MACRO', "ITS_VALUE"},
    {outdir,"/home/user/dev/lib/app1/ebin"}]}.

{"/home/user/dev/lib/app2/src/*",
   [{i,"/home/user/dev/lib/"},
    {d,'MY_MACRO', "ITS_VALUE"},
    {outdir,"/home/user/dev/lib/app2/ebin"}]}.

{"/home/user/dev/lib/app3/src/*",
   [{i,"/home/user/dev/lib/share/include/"},
    {i,"/home/user/dev/lib/"},
    {outdir,"/home/user/dev/lib/app3/ebin"}]}.
}}}

To add {{{app1}}}, {{{app2}}}, {{{app3}}} to !RefactorErl you should do the followings:
{{{
#!erlang

% add app1, app2 with the same configuration
ri:addenv(appbase, "/home/user/dev/lib/"),
ri:addenv(def, {'MY_MACRO', "ITS_VALUE"}),

Apps = [app1, app2],
[ri:add(home, App) || App <- Apps].

% add app3 after the configuration has been modified
ri:delenv(def),
ri:addenv(include, "/home/user/dev/lib/share/include/"),

ri:add(home, app3).

}}}


You can check the already given application base directories by listing all of the enviromental nodes:

{{{
#!erlang
ri:envs().
}}}

It is possible to delete the defined environment variables:

{{{
#!erlang
ri:delenv(include).
}}}

Or you can set an environmental variable to another value:
{{{
#!erlang
ri:setenv(env_name, "path/to/new_value").
}}}


The following enviromental nodes can be set via the {{{ri}}} module:

{{{output}}}: Where does !RefactorErl write changes in?

{{{appbase}}}: The list of the used  application based directories.

{{{include}}}: The list of the used include directories.

{{{def}}}: The list of the compile-time macros.

{{{env_var}}}: The list of the OS based enviromental nodes.


===  Adding applications using the Emakefile handling functions ===
Applications with their proper configurations (such as include paths, macros), or only the configurations, which are defined 
in an Emakefile, can be added by executing only one command. 
The given Emakefile is parsed then the configurations and the  adding procedure are handled automatically by the tool. 
The functionality is available in the ri module and also available in the ris module.

By executing one of the following commands:

{{{
#!erlang
EmakeFilePath = "/absolute_path_to_the_emakefile",
ri:add_by_emakefile(EmakefilePath).

% whether a list of Emakefiles are present.
EmakeFiles = ["/absolute_path_to_the_emakefile1", "/absolute_path_to_the_emakefile2"],
ri:add_by_emakefile(EmakeFiles).

}}}

the applications which are defined in the given Emakefile(s) are loaded into the database. Please note, that 
 * the configurations, which are defined in the Emakefile, only stored temporary, while the adding procedure has not been finished;
 * if the Emakefile contains relative path, then it will be converted absolute by using the path of the Emakefile as base.

If your apllications have been loaded by using {{{ri:add_by_emakefile/1}}} and any of the applications uses irregular include path or compile-time macro, 
then these applications should be updated by using {{{ri:add_by_emakefile/1}}}, or by loading the configuration {{{ri:load_configuration/1}}} then by executing {{{ri:database_synchronization/0}}}.\\
If the loaded configuration is not needed further then it may be unloaded by executing {{{ri:unload_configuration/1}}}.

Applications can be dropped from the database in the same way as the normal files.

== Refreshing your database ==
If your files has been changed in the disk, since the last load, then these files may be re-added to the database to gather fresh information about the files from the tool. This can be easily done, by executing one of the following commands:
{{{
#!erlang
ri:database_synchronization().

ris:database_synchronization().
}}}

== Gathering information about your database ==

For convenience, both the filenames and the directory names can be given
as atoms as well as strings.
The list of loaded files can be obtained by calling

{{{
#!erlang
ri:ls().
}}}

This call also displays the status of the loaded files (error or no_error).
If the module m is loaded,

{{{
#!erlang
ri:ls(m).
}}}

will give information about the functions, records and macros in the file.
The contents of a file can be listed by

{{{
#!erlang
ri:cat(ModFile).
}}}

The content of a function can be listed by

{{{
#!erlang
ri:cat(ModFile, {FunName,Arity}).
}}}