lib/Autom4te/C4che.pm

   1 # autoconf -- create 'configure' using m4 macros
   2 # Copyright (C) 2003, 2006, 2009-2017, 2020-2023 Free Software
   3 # Foundation, Inc.
   4
   5 # This program is free software: you can redistribute it and/or modify
   6 # it under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation, either version 3 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  17
  18 package Autom4te::C4che;
  19
  20 =head1 NAME
  21
  22 Autom4te::C4che - a single m4 run request
  23
  24 =head1 SYNOPSIS
  25
  26   use Autom4te::C4che;
  27
  28 =head1 DESCRIPTION
  29
  30 This Perl module handles the cache of M4 runs used by autom4te.
  31
  32 =cut
  33
  34 use 5.006;
  35 use strict;
  36 use warnings FATAL => 'all';
  37
  38 use Carp;
  39 use Data::Dumper;
  40
  41 use Autom4te::Request;
  42
  43 =over 4
  44
  45 =item @request
  46
  47 List of requests.
  48
  49 Must be a package global so it can be accessed by code evaluated via
  50 'eval', below.
  51
  52 =cut
  53
  54 our @request;
  55
  56 =item C<$req = Autom4te::C4che-E<gt>retrieve (%attr)>
  57
  58 Find a request with the same path and input.
  59
  60 =cut
  61
  62 sub retrieve($%)
  63 {
  64   my ($self, %attr) = @_;
  65
  66   foreach (@request)
  67     {
  68       # Same path.
  69       next
  70         if join ("\n", @{$_->path}) ne join ("\n", @{$attr{path}});
  71
  72       # Same inputs.
  73       next
  74         if join ("\n", @{$_->input}) ne join ("\n", @{$attr{input}});
  75
  76       # Found it.
  77       return $_;
  78     }
  79
  80   return undef;
  81 }
  82
  83 =item C<$req = Autom4te::C4che-E<gt>register (%attr)>
  84
  85 Create and register a request for these path and input.
  86
  87 =cut
  88
  89 # $REQUEST-OBJ
  90 # register ($SELF, %ATTR)
  91 # -----------------------
  92 # NEW should not be called directly.
  93 # Private.
  94 sub register ($%)
  95 {
  96   my ($self, %attr) = @_;
  97
  98   # path and input are the only ID for a request object.
  99   my $obj = new Autom4te::Request ('path'  => $attr{path},
 100                                    'input' => $attr{input});
 101   push @request, $obj;
 102
 103   # Assign an id for cache file.
 104   $obj->id ("$#request");
 105
 106   return $obj;
 107 }
 108
 109
 110 =item C<$req = Autom4te::C4che-E<gt>request (%request)>
 111
 112 Get (retrieve or create) a request for the path C<$request{path}> and
 113 the input C<$request{input}>.
 114
 115 =cut
 116
 117 # $REQUEST-OBJ
 118 # request($SELF, %REQUEST)
 119 # ------------------------
 120 sub request ($%)
 121 {
 122   my ($self, %request) = @_;
 123
 124   my $req =
 125     Autom4te::C4che->retrieve (%request)
 126     || Autom4te::C4che->register (%request);
 127
 128   # If there are new traces to produce, then we are not valid.
 129   foreach (@{$request{'macro'}})
 130     {
 131       if (! exists ${$req->macro}{$_})
 132         {
 133           ${$req->macro}{$_} = 1;
 134           $req->valid (0);
 135         }
 136     }
 137
 138   # It would be great to have $REQ check that it is up to date wrt
 139   # its dependencies, but that requires getting traces (to fetch the
 140   # included files), which is out of the scope of Request (currently?).
 141
 142   return $req;
 143 }
 144
 145
 146 =item C<$string = Autom4te::C4che-E<gt>marshall ()>
 147
 148 Serialize all the current requests.
 149
 150 =cut
 151
 152
 153 # marshall($SELF)
 154 # ---------------
 155 sub marshall ($)
 156 {
 157   my ($caller) = @_;
 158   my $res = '';
 159
 160   my $marshall = Data::Dumper->new ([\@request], [qw (*request)]);
 161   $marshall->Indent(2)->Terse(0)->Sortkeys(1);
 162   $res = $marshall->Dump . "\n";
 163
 164   return $res;
 165 }
 166
 167
 168 =item C<Autom4te::C4che-E<gt>save ($file, $version)>
 169
 170 Save the cache in the C<$file> file object.
 171
 172 =cut
 173
 174 # SAVE ($FILE, $VERSION)
 175 # ----------------------
 176 sub save ($$)
 177 {
 178   my ($self, $file, $version) = @_;
 179
 180   confess "cannot save a single request\n"
 181     if ref ($self);
 182
 183   $file->seek (0, 0);
 184   $file->truncate (0);
 185   print $file
 186     "# This file was generated by Autom4te $version.\n",
 187     "# It contains the lists of macros which have been traced.\n",
 188     "# It can be safely removed.\n",
 189     "\n",
 190     $self->marshall;
 191 }
 192
 193
 194 =item C<Autom4te::C4che-E<gt>good_version ($file, $version)>
 195
 196 Succeed if the cache from the C<$file> file object is of the given version.
 197
 198 =cut
 199
 200 # GOOD_VERSION ($FILE, $VERSION)
 201 # ------------------------------
 202 sub good_version ($$)
 203 {
 204   my ($self, $file, $version) = @_;
 205   my ($line) = $file->getline;
 206   return defined ($line) && $line eq "# This file was generated by Autom4te $version.\n";
 207 }
 208
 209 =item C<Autom4te::C4che-E<gt>load ($file)>
 210
 211 Load the cache from the C<$file> file object.
 212
 213 =cut
 214
 215 # LOAD ($FILE)
 216 # ------------
 217 sub load ($$)
 218 {
 219   my ($self, $file) = @_;
 220   my $fname = $file->name;
 221
 222   confess "cannot load a single request\n"
 223     if ref ($self);
 224
 225   my $contents = join "", $file->getlines;
 226
 227   eval $contents;
 228
 229   confess "cannot eval $fname: $@\n" if $@;
 230 }
 231
 232
 233 =head1 SEE ALSO
 234
 235 L<Autom4te::Request>
 236
 237 =head1 HISTORY
 238
 239 Written by Akim Demaille E<lt>F<akim@freefriends.org>E<gt>.
 240
 241 =cut
 242
 243 1; # for require
 244
 245 ### Setup "GNU" style for perl-mode and cperl-mode.
 246 ## Local Variables:
 247 ## perl-indent-level: 2
 248 ## perl-continued-statement-offset: 2
 249 ## perl-continued-brace-offset: 0
 250 ## perl-brace-offset: 0
 251 ## perl-brace-imaginary-offset: 0
 252 ## perl-label-offset: -2
 253 ## cperl-indent-level: 2
 254 ## cperl-brace-offset: 0
 255 ## cperl-continued-brace-offset: 0
 256 ## cperl-label-offset: -2
 257 ## cperl-extra-newline-before-brace: t
 258 ## cperl-merge-trailing-else: nil
 259 ## cperl-continued-statement-offset: 2
 260 ## End: