Author image Francisco Zarabozo

NAME

Parse::Lnk - A cross-platform, depencency free, Windows shortcut (.lnk) meta data parser.

VERSION

Version 0.06

SYNOPSIS

This module reads Win32 shortcuts (*.lnk files) to obtain the meta data in them.

Its goal is to be able to resolve the path they point to (along with other data), from any platform/OS, without the need for extra dependencies.

Some examples of usage:

    use Parse::Lnk;

    my $data = Parse::Lnk->from($filename);
    
    # $data is now a hashref if the file was parsed successfully.
    # undef if not.
    
    ##########
    # Or ... #
    ##########
    
    use Parse::Lnk qw(parse_lnk);
    
    my $data = parse_lnk $filename;
    
    # $data is now a hashref if the file was parsed successfully.
    # undef if not.
    
    ##########
    # Or ... #
    ##########
    
    use Parse::Lnk qw(resolve_lnk);
    
    my $path = resolve_lnk $filename;
    
    # $path is now a string with the path the lnk file points to.
    # undef if the lnk file was not parsed successfully.
    
    ###############################################################
    # Or, if you want a little more information/control on errors #
    ###############################################################
    
    use Parse::Lnk;
    
    my $lnk = Parse::Lnk->new;
    
    $lnk->parse($filename) or die $lnk->{error};
    
    # Or:
    
    $lnk->parse($filename);
    
    if ($lnk->{error}) {
        # ... do your own error handling;
    }
    

EXPORT

Nothing is exported by default. You can explicitly import this functions:

parse_lnk($filename)

This will return a Parse::Lnk instance, which is a hashref. The keys in that hashref depend on the data that was parsed from the .lnk file.

It will return undef on error.

    use Parse::Lnk qw(parse_lnk);
    
    my $lnk = parse_lnk $filename;
    
    if ($lnk) {
        print "$filename points to path $lnk->{base_path}\n";
        
        my $create_date = localtime $lnk->{create_time};
        print "$filename was created on $create_date";
    } else {
        print "Could not parse $filename";
    }

resolve_lnk($filename)

This will return the path the .lnk file is pointing to.

It will return undef on error.

    use Parse::Lnk qw(resolve_lnk);
    
    my $path = resolve_lnk $filename;
    
    if ($path) {
        print "$filename points to path $path";
    } else {
        print "Could not parse $filename";
    }

METHODS

You can create a Parse::Lnk instance and call a few methods on it. This may give you more control/information when something goes wrong while parsing the file.

new

This creates a new instance. You can pass the filename value as argument, or you can set/change it later.

    use Parse::Lnk;
    
    my $lnk = Parse::Lnk->new(filename => $filename);
    
    # or
    
    my $lnk = Parse::Lnk->new;
    $lnk->{filename} = $filename;

parse

This method will parse the current filename in the instance. You can change the value of filename and parse again at any point.

    use Parse::Lnk;
    
    my $lnk = Parse::Lnk->new(filename => $filename);
    
    $lnk->parse;
    
    if ($lnk->{error}) {
        # handle the error
    } else {
        print "$filename points to $lnk->{base_path}";
    }
    
    for my $other_filename (@filenames) {
        $lnk->{filename} = $other_filename;
        $lnk->parse;
        
        if ($lnk->{error}) {
            # handle the error
            next;
        }
        
        print "$other_filename points to $lnk->{base_path}";
    }

from

It will return a Parse::Lnk instance, or undef on error. This method was written with plain package name calling in mind:

    use Parse::Lnk;
    
    my $lnk = Parse::Lnk->from($filename);
    
    if ($lnk) {
        print "$filename points to path $lnk->{base_path}\n";
        
        my $create_date = localtime $lnk->{create_time};
        print "$filename was created on $create_date";
    } else {
        print "Could not parse $filename";
    }

AUTHOR

Francisco Zarabozo, <zarabozo at cpan.org>

BUGS

I'm sure there are many. I haven't found bugs with the lnk files I've tested it. If you find a bug or you have a problem reading a shortcut/lnk file, please don't hesitate to report it and don't forget to include the file in question. If you are on Windows, you will have to zip the file in a way that is the lnk file the one being zipped and not the actual directory/file it is pointing to. I promise to look at any report and work on a solution as fast as I can.

Please report any bugs or feature requests to bug-parse-lnk at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Parse-Lnk. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Parse::Lnk

You can also look for information at:

ACKNOWLEDGEMENTS

Many sections of the code were adapted from Jacob Cunningham's Windows LNK File Parser, licensed under the GNU General Public License Version 2.

LICENSE AND COPYRIGHT

This software is copyright (c) 2021 by Francisco Zarabozo.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.