NAME

File::Corresponding - Find corresponding files in the directory tree

PREAMBLE

In a source tree it is common to have files with the same name, but in different places in the directory tree. For a typical MVC application, an example could be:

Controller/Book.pm
Controller/Borrower.pm
Model/Schema/Book.pm
Model/Schema/Borrower.pm
root/templates/Book.t
root/templates/Borrower.t
t/controller-book.t
t/controller-borrower.t
t/model-schema-book.t
t/model-schema-borrower.t

Here Controller/Book.pm, Model/Schema/Book.pm, root/templates/Book.t, t/controller-book.t, and t/model-schema-book.t correspond to each other; they represent different aspects of the same Book entity.

Since the files belong to each other it is useful for the programmer to navigate between them, to deal with the various aspects of the Book.

SYNOPSIS

Config file

Given a config file .corresponding_file in the current directory or your $HOME directory:

---
file_groups:
  -
    name: All MyApp classes
    file_profiles:
      -
        name: Cat Controller
        regex: /Controller.(\w+)\.pm$/
        sprintf: Controller/%s.pm
      -
        name: DBIC Schema
        regex: /Model.Schema.(\w+)\.pm$/
        sprintf: Model/Schema/%s.pm
      -
        name: Template
        regex: /root.template.(\w+)\.pm$/
        sprintf: root/template/%s.pm

From the command line

$ corresponding_file Controller/Book.pm
Model/Schema/Book.pm
$ cd ..
$ corresponding_file lib/Controller/Book.pm
lib/Model/Schema/Book.pm

From your editor

Emacs

Devel::PerlySense has a feature "Go to Project's Other Files" for navigating to related files.

Actually, it doesn't yet. But it will.

From your program

By using File::Corresponding as a library, you can use the resulting File::Corresponding::File::Found objects to display more information than just the file name.

DESCRIPTION

File::Corresponding uses a configuration of groups of File Profiles to identify corresponding files.

Using a .corresponding_file config file, and the command line script corresponding_file, you can easily look up corresponding files.

It's obviously better if you let your editor do the tedious bits for you, like passing the file name to the script, letting you choose which of the corresponding files you meant, and opening the file in the editor.

That's left as an exercise for the reader (well you are a programmer, aren't you?).

THE CONFIG FORMAT

See the synopsis example.

A File Profile for e.g. "Controller" files includes a regex to match a Controller file name with e.g. "Book" in it, and a sprintf string template to render any found files with "Book" in them as a Controller file.

The regex should match the intended file. The first capturing parenthesis must contain the entity file fragmen that is common to all files in the group.

The sprintf string should contain a %s to fill in the captured file fragment from any other File Profile in the Group.

Only existing files are reported.

SEE ALSO

AUTHOR

Johan Lindström, <johanl[ÄT]DarSerMan.com>

BUGS AND CAVEATS

Currently File::Corresponding supports the simple case in the DESCRIPTION above, where the Controller/Book.pm can easily be translated to Model/Schema/Book.pm. It does not yet support the more complicated translation from Controller/Book.pm to t/controller-book.t and back.

BUG REPORTS

Please report any bugs or feature requests to bug-file-corresponding@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Corresponding. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

CAVEATS

KNOWN BUGS

COPYRIGHT & LICENSE

Copyright 2007 Johan Lindström, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

*** DEVELOPER API DOCS ***

ERROR HANDLING MODEL

Failures will result in a die.

ATTRIBUTES

profile_groups : ArrayRef[File::Corresponding::Group]

Group config objects.

METHODS

corresponding($file) : ArrayRef[File::Corresponding::File::Found]

Find files corresponding to $file (given the config in ->profile_groups) and return found @files.

If the same file is found via many Groups, it will be reported once per group (so if you only use this to display the file name, make sure to unique the file names).

load_config_file($config_file) : 1

Load yaml $config_file, or die with an error message.

cpanm File::Corresponding

perl -MCPAN -e shell
install File::Corresponding