Subject: ANNOUNCE: Tie::Registry beta, new Win32API::Registry
From: [email-masked] (Tye McQueen)
Date: 2 Jan 1998 23:53:53 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.modules

WHAT

I'm proud to announce the first beta release of Tie::Registry,
a Perl module to provide easy and powerful access to a Registry
(Microsoft's configuration database thingy and the module is only
supported on Win32 systems at this time).  I've also released a
new version of Win32API::Registry which is required by this
release of Tie::Registry.

As the name suggests, Tie::Registry lets you use tied hashes
to use a Registry very easily.  Tie::Registry also provides an
object-oriented interface which meshes nicely with the tied hash
interface and the underlying Win32API::Registry "raw" interface.
Now 90% of what you want to do with a Registry can be done very
simply, and you can do anything in Perl that you could do in C
(at least as easily).

Imagine being able to copy an entire Registry tree with a single
Perl statement (okay, enough hype):
    $classes->{"gnatfile/"}= $classes->{"batfile/"};

Sorry, Tie::Registry cannot be used with the ActiveState version
of Perl because Tie::Registry requires Win32API::Registry which
uses the standard Perl tools for building extensions and these
are not supported with the ActiveState version of Perl.  The
ActiveState version and standard version of Perl are merging
so you _may_ want to switch to the standard version of Perl soon.

You probably need a C compiler to use Win32API::Registry which
is required by Tie::Registry, but see the next section for a
possible work-around.

WHERE

I have just uploaded to PAUSE:

    Tie-Registry-0.12.zip
    Win32API-Registry-0.12.zip

so they will be available soon at your local CPAN site in the
authors/id/TYEMQ directory.

For a limited time, these are also available under
http://www.metronet.com/~tye/alpha/ as

    Tie-Registry-0.12.zip
    Win32API/Registry-0.12.zip
    Win32API/Registry-0.12bin.zip
    perl5.004_04tm.patch

Win32API/Registry-0.12bin.zip _may_ be useful for those without a
C compiler and with Perl5.004_04 built similar enough to my copy. 
perl5.004_04tm.patch is a patch for the source code of Perl
version 5.004_04 that ties $^E to GetLastError() to make life
under Win32 nicer, especially when using these modules [it has
been submitted to the perl5-porters and I hope will be included
in future releases of Perl].

DETAILS (Tie::Registry)

See Tie/Registry.pm for full [pod] documentation [though some
sections are still under construction].

The Tie::Registry module lets you manipulate the Registry via
objects [as in "object oriented"] or via tied hashes.  But you
will probably mostly use objects which are also references to
tied hashes that allow you to mix both access methods.

By default, Tie::Registry exports one global variable, $Registry,
which is a combination of a Perl object and a reference to a
tied hash and represents the virtual "root" of the Registry.
Use $Registry as a reference to a tied hash [as in,
$Registry->{"KeyName/"}] to open Registry keys and you get more
objects/references-to-tied-hashes.  Use these or $Registry to make
Tie::Registry method calls [as in $key->Information("Class")]
and/or as references to tied hashes [as in $key->{"/ValueName"}]
to do just about anything with the Registry.

Summary of using tied hashes

For the impatient, this may be the only documentation you need
to read to get started.  For best results, always append one
delimeter to the end of each Registry key name and prepend one
delimeter to the front of each Registry value name.

The root keys for use with $Registry are:
    Classes             HKEY_CLASSES_ROOT
    CUser               HKEY_CURRENT_USER
    LMachine            HKEY_LOCAL_MACHINE
    Users               HKEY_USERS
    PerfData            HKEY_PERFORMANCE_DATA
    CConfig             HKEY_CURRENT_CONFIG
    DynData             HKEY_DYN_DATA
Note that upper vs. lower case letters matter for these (but not
for other subkey names nor value names).

Opening keys

    use Tie::Registry;				# Exports $Registry.
    $Registry->Delimeter("/");                  # Set delimeter to "/".

    $swKey= $Registry->{"LMachine/Software/"};
    $winKey= $swKey->{"Microsoft/Windows/CurrentVersion/"};
    $userKey= $Registry->
      {"CUser/Software/Microsoft/Windows/CurrentVersion/"};

    $remoteKey= $Registry->{"//HostName/LMachine/"};
    # Run ``net use \\HostName\ipc$ /user:UserName PassWord'' first, if needed.

Reading values

    $progDir= $winKey->{"/ProgramFilesDir"};    # "C:\\Program Files"
    $tip21= $winKey->{"Explorer/Tips//21"};     # Text of tip #21.

    $winKey->ArrayValues(1);
    ( $devPath, $type )= $winKey->{"/DevicePath"};
    # $devPath eq "%SystemRoot%\\inf"
    # $type eq "REG_EXPAND_SZ"  [if you have SetDualVar.pm installed]
    # $type == REG_EXPAND_SZ  [if you did "use Win32API::Registry qw(REG_)"]

Setting values

    $winKey->{"Setup//SourcePath"}= "\\\\SwServer\\SwShare\\Windows";
    # Simple.  Assumes data type of REG_SZ.

    $winKey->{"Setup//Installation Sources"}=
      [ "D:\x00\\\\SwServer\\SwShare\\Windows\0\0", "REG_MULTI_SZ" ];
    # "\x00" and "\0" used to mark ends of each string and end of list.

    $userKey->{"Explorer/Tips//DisplayInitialTipWindow"}=
      [ pack("L",0), "REG_DWORD" ];
    $userKey->{"Explorer/Tips//Next"}= [ pack("S",3), "REG_BINARY" ];
    $userKey->{"Explorer/Tips//Show"}= [ pack("L",0), "REG_BINARY" ];

Adding keys

    $swKey->{"FooCorp/"}= {
        "FooWriter/" => {
            "/Version" => "4.032",
            "Startup/" => {
                "/Title" => "Foo Writer Deluxe ][",
                "/WindowSize" => [ pack("LL",$wid,$ht), REG_BINARY ],
                "/TaskBarIcon" => [ "0x0001", REG_DWORD ],
            },
            "Compatibility/" => {
                "/AutoConvert" => "Always",
                "/Default Palette" => "Windows Colors",
            },
        },
        "/License", => "0123-9C8EF1-09-FC",
    };

Listing all subkeys and values

    @members= keys( %{$swKey} );
    @subKeyNames= grep(  m#^/#,  keys( %{$swKey->{"Classes/batfile/"}} )  );
    # @subKeyNames= ( "/", "/EditFlags" );
    @valueNames= grep(  ! m#^/#,  keys( %{$swKey->{"Classes/batfile/"}} )  );
    # @valueNames= ( "DefaultIcon/", "shell/", "shellex/" );

Deleting values or keys with no subkeys

    $oldValue= delete $userKey->{"Explorer/Tips//Next"};

    $oldValues= delete $userKey->{"Explorer/Tips/"};
    # $oldValues will be reference to hash containing deleted keys values.

Closing keys

    undef $swKey;               # Explicit way to close a key.
    $winKey= "Anything else";   # Implicitly closes a key.
    exit 0;                     # Implicitly closes all keys.

Installation

Tie::Registry installs like any standard Perl module.  First, get and
install the Win32API::Registry module.  For best results, also get and
install the SetDualVar module and make sure your Perl distribution
included the Win32::WinError module.

Then you can use the following commands to install Tie::Registry:

    unzip Tie-Registry-0.12.zip
    cd Tie-Registry-0.12
    perl Makefile.PL
    make install        [or "nmake install"]

Or, if you don't have a "make" command [usually as part of a C
compiler], you can get away with simply copying the Registry.pm
file into theh "Tie" subdirectory of Perl's "lib" directory.

SEE ALSO

Win32API::Registry(3) [required] - Provides Reg*(), HKEY_*, KEY_*, REG_*.

Win32::WinError(3) [optional] - Defines ERROR_* values.

SetDualVar(3) [optional] - For returning REG_* values as combo string/integer.
--
Tye McQueen    Nothing is obvious unless you are overlooking something
         http://www.metronet.com/~tye/ (scripts, links, nothing fancy)
       Remove d's from address to reply (sorry for the inconvenience).