I am reworking the source code and docs for Resources so that both take use of newer features of Perl/pod and so that the source does not create compiler warnings. I am doing so because the author's email bounces and the module was last updated in '97.

Not in any hurry, I applied the microscope to the new method and docs today. Here are his docs for the method:

new Resources ($resfile);

Creates a new resource database, initialized with the defaults for class Resources (see below for a list of them).

If a nonempty file name is specified in $resfile, it initializes the object with the content of the so named resource file. For safe (non overwriting) loading, see the load method below.

If the special file name "_RES_NODEFAULTS" is specified, the object is created completely empty, with not even the Resources class defaults in it.

Returns the new object, or undef in case of error.

To me, these docs were fraught with confusion. After looking at the source code, I have created the following docs:

Resources->new ( [ $resfile ] ) ;

This method is called to create a new resource database object, heretofore referred to as $res

The method behavior is based on:

  1. The method was called with $resfile
    1. The method was called with $resfile eq _RES_NODEFAULTS
    2. The method was called with $resfile ne _RES_NODEFAULTS
  2. The method was called without $resfile

In case 1.1, the object is created completely empty, with NO resources whatsoever.

In both case 1.2 and case 2, the "CORE" resources from Resources.pm are bound to the object. In case 1.2, the object is further initialized via a call to $res->load($resfile)

I am including the source code for his new method for your reference: 

sub new {
   my $type = shift;
   my $resfile = shift;
   my ($name, $valdoc, $app);
   my $res = bless {};
   
   $res->{Load}    = 0;    # 1 if loading
   $res->{Merge}   = 0;    # 1 if merging
   $res->{Wilds}   = {};   # Wildcarded resources.
   $res->{Res}     = {};   # Named resources.
   $res->{Owned}   = {};   # Inverted index of member clases.
   $res->{Isa}     = {};   # Inverted index of base classes.

   # Safe environment for the evaluation of constructors.
   $res->{Safe} = new Safe or 
      ($res->_error("new", "can't get a Safe object."), return undef);

   # Hack hack - the special filename "_RES_NODEFAULTS" is
   # used to prevent resource initialization (e.g. when called by the
   # "bypattern" method
   unless ($resfile and $resfile eq "_RES_NODEFAULTS") {
      # Must make sure this is not overridden by a wildcard
      $res->{Wilds}->{'.*resources\.updates'} = [0];
      $res->{Res}->{'resources.updates'}->[$Value] = 0;
      
      # Get appclass without extensions
      if (($app = $Resources{'resources.appclass'}->[$Value]) =~ /\./)
+ {
     $Resources{'resources.appclass'}->[$Value] = (split(/\./, $app))[
+0];
      }

      # Bootstrap defaults. We don't want any subclassing here 
      while (($name, $valdoc) = CORE::each(%Resources)) {
     $res->{Res}->{$name} = $valdoc;
      }
   }

   if ($resfile and $resfile ne "_RES_NODEFAULTS") {
      $res->load($resfile) || 
     ($res->_error("new", "can't load"), return undef); 
   }

   $res;
}

[download]

DBSchema::Sample

Replies are listed 'Best First'.
Re: Rewording the Resources docs
by graff (Chancellor) on Oct 26, 2003 at 01:12 UTC
    I'd try to simplify the "unless" clause, just to make it easier to comprehend: 
    ...
    unless ( $resfile eq "_RES_NODEFAULTS" ) {
       # do the normal (default) resource inits...
    }
    if ( $resfile and $resfile ne "_RES_NODEFAULTS" ) {
       # read resources from $resfile...
    }
...

    [download]
    As for the documentation, the hierarchy (1.1 vs. 1.2 vs. 2) doesn't really help. There are just three different possible invocations for "new()", involving the single argument that it can take:
    • the literal string "_RES_NODEFAULTS" -- returns a completely empty object, with no resource values set
    • no argument at all (or empty string) -- assigns default values to a core set of resources
    • the name of a resource file -- can assign non-default values to core resources, and/or define additional resources

    I haven't looked at the rest of the module, so I'm guessing that those descriptions are appropriate. In any case, I hope the docs will clarify what the "core" resources are, how the default values make sense, what a resource file should look like, and what constraints, if any, apply to defining additional resources.

[reply]
[d/l]
Re: Rewording the Resources docs
by Anonymous Monk on Oct 26, 2003 at 05:46 UTC
    I hate to tell you this princepawn, but the existing docs were far clearer to me. In fact, I had to refer back to them to make sure I was getting your new docs. I am not joking.
[reply]
Re: Rewording the Resources docs
by princepawn (Parson) on Oct 26, 2003 at 07:50 UTC
[reply]
[d/l]
[select]
      For what it's worth, I find the expression subheaders a bit confusing, and think that a few straight code examples would help.

      Might I suggest the following?

      Constructor: Resources->new( ... )

      Creates a new resource database object $res, initializes it, and returns the new object, or undef in case of error. 

        my $res = Resources->new( $filename ); # Load file data

  my $res = Resources->new(); # New with core defaults only

  my $res = Resources->new('_RES_NODEFAULTS'); # totally empty

      [download]

      The resource is initialized in one of three possible ways based on the single argument, $resfile, that it can take:

      No argument or false value
      In this case core resource values (The Resources of Resources) are bound and the object is returned.
      A resource file name
      First the object is created and initialized as above. Then $res->load($resfile) is called, overwriting and adding any new resources found in that file.
      The string '_RES_NODEFAULTS'
      This creates a completely empty object, with no bound resources.

[reply]
[d/l]
[reply]

Back to Meditations