=head1 The .NET Metadata To PIR Translator

Much data about .NET classes along with their fields and methods are stored in
tables, collectively known as metadata, outside of the instruction stream. A
number of PMCs (documented in L<pmcs.pod>) are used to access this metadata.

=head2 Interface

This subsystem represents itself as a single sub that takes a single parameter,
the filename of the EXE or DLL file with CLI metadata inside it that needs to
be translated. It returns the PIR of the translated file. The sub is simply
named "dotnet_to_pir".

  pir = dotnet_to_pir(filename)

This is contained in the file "src/translator.pir".

=head2 Guts

This section describes the internals of the metadata translator.

=head3 Flow

=head4 Assemblies, Classes, Fields and Methods

                   +----------------------------+
                   |        dotnet_to_pir       |
                   |       (translator.pir)     |
                   +------------||--------------+
                                ||
                               _||_
                               \  /
                   +------------\/--------------+
                   |         trans_class        |
                   |       (translator.pir)     |
                   +------------||--------------+
                                ||
                 ==================================
                ||                                ||
               _||_                              _||_
               \  /                              \  /
      +---------\/-----------+          +---------\/-----------+
      |     trans_field      |          |     trans_method     |
      |   (translator.pir)   |          |     (method.pir)     |
      +----------------------+          +---------||-----------+
                                                  ||
                                                 _||_
                                                 \  /
                                                  \/
                                               See below

=head4 Method Translation Details

                             See above
                                ||
                               _||_
                               \  /
                   +------------\/--------------+
                   |         trans_method       |---------|\ Instruction
                   |         (method.pir)       |---------|/ Translator
                   +------------||--------------+
                                ||
                 ==================================
                ||                                ||
               _||_                              _||_
               \  /                              \  /
      +---------\/-----------+          +---------\/-----------+
      | trans_method_params  |          | trans_method_locals  |
      |     (method.pir)     |          |     (method.pir)     |
      +---------||-----------+          +---------||-----------+
                ||                                ||
               _||_                              _||_
               \  /                              \  /
      +---------\/-----------+          +---------\/-----------+
      |    get_signature_    |          |    get_signature_    |
      |   RetType_or_Param   |          |        Local         |
      |    (signature.pir)   |          |    (signature.pir)   |
      +----------------------+          +----------------------+

=head3 Files

The translator source consists of a number of PIR files.

=head4 translator.pir

This contains the main dotnet_to_pir sub that initiates the translation process.
It also contains translate_class, which drives translation of a .NET class, and
translate_field, which translates a field.

=head4 method.pir

This contains routines related to translating methods along with their local
variables and parameters. The sub translate_method drives this, using a couple
of utility functions. It also makes use of signature translation routines in
signature.pir.

=head4 signature.pir

This contains routines that parse parts of signature blobs and build some simple
data structures out of them.