view release on metacpan or  search on metacpan

lib/Archive/SCS.pm  view on Meta::CPAN

  my @contents = sort $scs->list_dirs, $scs->list_files;

  say $scs->read_entry('def/env_data.sii');

=head1 DESCRIPTION

Handles the union file system used by SCS archive files.
Allows mounting of multiple files or extracted directories and
performs lookups in all of them using the SCS hash algorithm.

These modules exist primarily to support the F<scs_archive>
command-line tool included in this distribution.

=head1 METHODS

=head2 formats

  @formats = $scs->formats;

Returns the list of currently active formats.
See C<set_formats()>.

=head2 list_dirs

  @directories = $scs->list_dirs;

Returns an ordered list of all directory paths in currently
mounted archives. The root directory, represented by an empty
string, is currently omitted from the list.

Paths are returned without a leading C</> because that's the
way they are stored internally. This is subject to change,
but the output of C<list_dirs()> will always be good to use
as path for C<read_entry()>.

=head2 list_files

  @files = $scs->list_files;

Returns an ordered list of all file paths in currently mounted
archives.

Paths are returned without a leading C</> because that's the
way they are stored internally. This is subject to change,
but the output of C<list_files()> will always be good to use
as path for C<read_entry()>.

=head2 list_orphans

  @orphan_hashes = $scs->list_orphans;

Returns a list of hash values for
orphans in currently mounted archives.

Some file formats allow files (or subdirs) without a directory entry.
These files may be accessed directly using their hash value. This
software refers to such files as orphans. For example, the following
orphans are known to exist in 1.49.3.14:

  05c075dc23d8d177 # in core.scs, 'def/achievements.sii'
  0eeaffbe65995414 # in base.scs + core.scs, 'ui/desktop_demo.sii'
  0fb3a3294f8ac99c # in base_cfg.scs
  2a794836b65afe88 # in base.scs
  34f7048e2d3b04b6 # in core.scs, 'def/online_economy_data.sii'
  507dcc5fb3fb6443 # in core.scs, 'def/online_data.sii'
  83a9902d7733b94d # in core.scs, 'def/mod_manager_data.sii'
  88a1194cb25b253c # in core.scs, 'ui/desktop_standalone_demo.sii'
  c09356068ea66aac # in core.scs, 'def/world/building_scheme_core_scs.sii'
  d9d3d2a218c69f3d # in base.scs
  e773fb1407c8468d # in core.scs, 'def/world/building_model_core_scs.sii'

=head2 mount

  $archive = $scs->mount($pathname);
  $archive = $scs->mount($mountable);

Adds the given SCS archive to the currently mounted archives.
Returns an L<Archive::SCS::Mountable> object. If a file system
path is given as argument, the object will be created by
attempting to load the given archive with the currently active
formats. See C<set_formats()>.

=head2 new

  $scs = Archive::SCS->new;

Creates a new L<Archive::SCS> object.

=head2 read_entry

  $data = $scs->read_entry($pathname);
  $data = $scs->read_entry($hash);

Returns the contents of the given entry. Directories will be
returned as L<Archive::SCS::DirIndex> objects and S<HashFS v2>
texture objects as L<Archive::SCS::TObj>.

The argument may be the pathname within the archive or its hash
value, hex-encoded in network byte order as a 16-byte scalar PV.
Paths are expected without a leading C</> because that's the
way they are stored internally. This is subject to change,
but the output of C<list_files()> will always be good to use
as path for C<read_entry()>.

=head2 set_formats

  $scs = $scs->set_formats(qw[ HashFS Zip ]);

Sets the list of currently active formats. All formats must be
in the C<Archive::SCS> namespace. By default, the list includes
all formats implemented in this distribution, which currently
are the following:

=over

=item * L<Archive::SCS::Directory>

=item * L<Archive::SCS::HashFS>

=item * L<Archive::SCS::HashFS2>

=item * L<Archive::SCS::Zip>

=back

=head2 unmount