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.