lib/Mac/NSGetExecutablePath.pm

   1 package Mac::NSGetExecutablePath;
   2
   3 use 5.006;
   4
   5 use strict;
   6 use warnings;
   7
   8 =head1 NAME
   9
  10 Mac::NSGetExecutablePath - Perl interface to the _NSGetExecutablePath darwin (OS X) system call.
  11
  12 =head1 VERSION
  13
  14 Version 0.02
  15
  16 =cut
  17
  18 our $VERSION;
  19 BEGIN {
  20  $VERSION = '0.02';
  21 }
  22
  23 =head1 SYNOPSIS
  24
  25     sub get_perl_path {
  26      if ($^O eq 'darwin') {
  27       require Cwd;
  28       require Mac::NSGetExecutablePath;
  29       return Cwd::abs_path(Mac::NSGetExecutablePath::NSGetExecutablePath());
  30      } else {
  31       return $^X;
  32      }
  33     }
  34
  35 =head1 DESCRIPTION
  36
  37 This module provides a Perl interface to the C<_NSGetExecutablePath> darwin system call.
  38 It will only build on darwin systems.
  39
  40 Note that if you are using L<perl> 5.16 or greater, then the value of C<$^X> is already computed from the return value of C<_NSGetExecutablePath>, making this module mostly irrelevant.
  41
  42 =cut
  43
  44 BEGIN {
  45  require XSLoader;
  46  XSLoader::load(__PACKAGE__, $VERSION);
  47 }
  48
  49 =head1 FUNCTIONS
  50
  51 =head2 C<NSGetExecutablePath>
  52
  53     my $path = NSGetExecutablePath();
  54
  55 Returns a string representing the path to the current executable.
  56 This path may rightfully point to a symlink.
  57
  58 This function may throw exceptions, see L</DIAGNOSTICS> for details.
  59
  60 =head1 DIAGNOSTICS
  61
  62 =head2 C<NSGetExecutablePath() wants to return a path too large>
  63
  64 This exception is thrown when C<_NSGetExecutablePath> requires an outrageously large buffer to return the path to the current executable.
  65
  66 =head1 EXPORT
  67
  68 The function L</NSGetExecutablePath> is only exported on request, either individually or by the tags C<':funcs'> and C<':all'>.
  69
  70 =cut
  71
  72 use base qw<Exporter>;
  73
  74 our @EXPORT         = ();
  75 our %EXPORT_TAGS    = (
  76  'funcs' => [ qw<NSGetExecutablePath> ],
  77 );
  78 our @EXPORT_OK      = map { @$_ } values %EXPORT_TAGS;
  79 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
  80
  81 =head1 DEPENDENCIES
  82
  83 L<perl> 5.6.
  84
  85 A C compiler.
  86 This module may happen to build with a C++ compiler as well, but don't rely on it, as no guarantee is made in this regard.
  87
  88 L<Exporter> (core since perl 5), L<XSLoader> (since 5.6.0), L<base> (since 5.004_05).
  89
  90 =head1 SEE ALSO
  91
  92 C<dyld(3)>.
  93
  94 =head1 AUTHOR
  95
  96 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
  97
  98 You can contact me by mail or on C<irc.perl.org> (vincent).
  99
 100 =head1 BUGS
 101
 102 Please report any bugs or feature requests to C<bug-mac-nsgetexecutablepath at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Mac-NSGetExecutablePath>.
 103 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
 104
 105 =head1 SUPPORT
 106
 107 You can find documentation for this module with the perldoc command.
 108
 109     perldoc Mac::NSGetExecutablePath
 110
 111 =head1 ACKNOWLEDGEMENTS
 112
 113 The implementation of this module is inspired by Nicholas Clark's work of adding this feature to perl 5.16.
 114
 115 =head1 COPYRIGHT & LICENSE
 116
 117 Copyright 2012 Vincent Pit, all rights reserved.
 118
 119 This program is free software; you can redistribute it and/or modify it
 120 under the same terms as Perl itself.
 121
 122 =cut
 123
 124 1; # End of Mac::NSGetExecutablePath