Perl 5.42.0

https://perldoc.perl.org/5.42.0/
Admin
Perl is a practical, general-purpose programming language widely used for text processing, system...
Tokens:7,449,871
Snippets:54,452
Trust Score:9.9
Update:5 days ago
Show doc for...
Tokens:
Raw
### Install command examples for modules and distributions

Source: https://perldoc.perl.org/5.42.0/CPAN.txt

Examples of the install command: installing a module by name, installing a distribution by file name, and using a regexp to install a distribution when unambiguous. The install command checks if an install is needed for modules and prints 'module up to date' if not needed.

```shell
install Dummy::Perl                   # installs the module
install AUXXX/Dummy-Perl-3.14.tar.gz  # installs that distribution
install /Dummy-Perl-3.14/             # same if the regexp is unambiguous
```

--------------------------------

### Force install example with -f and -i

Source: https://perldoc.perl.org/5.42.0/App%3A%3ACpan.txt

Shows how to force an installation even if tests fail, using the -f option with -i.

```shell
% cpan -f -i Module::Foo
```

--------------------------------

### cpan command-line examples

Source: https://perldoc.perl.org/5.42.0/cpan.txt

Examples of common cpan commands: printing help, version, creating an autobundle, recompiling modules, upgrading all installed modules, installing modules, forcing installs, and installing without testing.

```shell
# print a help message
cpan -h
```

```shell
# print the version numbers
cpan -v
```

```shell
# create an autobundle
cpan -a
```

```shell
# recompile modules
cpan -r
```

```shell
# upgrade all installed modules
cpan -u
```

```shell
# install modules ( sole -i is optional )
cpan -i Netscape::Booksmarks Business::ISBN
```

```shell
# force install modules ( must use -i )
cpan -fi CGI::Minimal URI
```

```shell
# install modules but without testing them
cpan -Ti CGI::Minimal URI
```

--------------------------------

### App::Cpan synopsis usage examples

Source: https://perldoc.perl.org/5.42.0/App%3A%3ACpan.txt

The synopsis section shows various ways to invoke the cpan command, including installing modules, using local::lib, overriding mirrors, installing from the current directory, and starting the CPAN shell.

```shell
# with arguments and no switches, installs specified modules
cpan module_name [ module_name ... ]
```

```shell
# with switches, installs modules with extra behavior
cpan [-cfFimtTw] module_name [ module_name ... ]
```

```shell
# use local::lib
cpan -I module_name [ module_name ... ]
```

```shell
# one time mirror override for faster mirrors
cpan -p ...
```

```shell
# with just the dot, install from the distribution in the
# current directory
cpan .
```

```shell
# without arguments, starts CPAN.pm shell
cpan
```

```shell
# without arguments, but some switches
cpan [-ahpruvACDLOPX]
```

--------------------------------

### perl Makefile.PL with PREFIX

Source: https://perldoc.perl.org/5.42.0/ExtUtils%3A%3AMakeMaker.txt

Use PREFIX to set several INSTALL* attributes at once. Example installs into your home directory.

```shell
# Unix users, PREFIX=~ works fine
perl Makefile.PL PREFIX=/path/to/your/home/dir
```

--------------------------------

### config() set and get example

Source: https://perldoc.perl.org/5.42.0/Math%3A%3ABigRat.txt

Shows how to set and get configuration parameters using the config() method. Read-only parameters are marked RO, read-write are RW.

```perl
Math::BigRat->config("trap_nan" => 1);      # set
$accu = Math::BigRat->config("accuracy");   # get
```

--------------------------------

### Install a developer release by path

Source: https://perldoc.perl.org/5.42.0/CPAN.txt

Installs a specific developer release by specifying the partial path starting with the author id to the tarball. Use the 'ls' command to get the path.

```shell
cpan> install KWILLIAMS/Module-Build-0.27_07.tar.gz
```

--------------------------------

### o conf init examples

Source: https://perldoc.perl.org/5.42.0/CPAN.txt

Interactive configuration dialog examples. The first sets specific options, the second uses a MATCH pattern enclosed by slashes to match variables.

```shell
o conf init ftp_passive ftp_proxy
```

```shell
o conf init /color/
```

--------------------------------

### ExtUtils::Installed SYNOPSIS example

Source: https://perldoc.perl.org/5.42.0/ExtUtils%3A%3AInstalled.txt

Shows the basic usage of ExtUtils::Installed: creating an instance with new( skip_cwd => 1 ), then calling methods like modules(), validate(), files(), directories(), directory_tree(), and packlist().

```perl
   use ExtUtils::Installed;
   my ($inst) = ExtUtils::Installed->new( skip_cwd => 1 );
   my (@modules) = $inst->modules();
   my (@missing) = $inst->validate("DBI");
   my $all_files = $inst->files("DBI");
   my $files_below_usr_local = $inst->files("DBI", "all", "/usr/local");
   my $all_dirs = $inst->directories("DBI");
   my $dirs_below_usr_local = $inst->directory_tree("DBI", "prog");
   my $packlist = $inst->packlist("DBI");
```

--------------------------------

### Using @- and @+ to get match positions

Source: https://perldoc.perl.org/5.42.0/perlretut.txt

Shows how to iterate over capture groups using @- and @+ to print the start and end positions of each match. The example matches 'Mmm...donut' and prints the positions of the two capture groups.

```perl
$x = "Mmm...donut, thought Homer";
$x =~ /^(Mmm|Yech)\.\.\.(donut|peas)/; # matches
foreach $exp (1..$#-) {
    no strict 'refs';
    print "Match $exp: '$$exp' at position ($-[$exp],$+[$exp])\n";
}
```

```output
Match 1: 'Mmm' at position (0,3)
Match 2: 'donut' at position (6,11)
```

--------------------------------

### SYNOPSIS example

Source: https://perldoc.perl.org/5.42.0/TAP%3A%3AParser%3A%3ASourceHandler%3A%3APerl.txt

Shows how to use the module to create a source, check if it can be handled, and make an iterator.

```perl
  use TAP::Parser::Source;
  use TAP::Parser::SourceHandler::Perl;

  my $source = TAP::Parser::Source->new->raw( \'script.pl' );
  $source->assemble_meta;

  my $class = 'TAP::Parser::SourceHandler::Perl';
  my $vote  = $class->can_handle( $source );
  my $iter  = $class->make_iterator( $source );
```

--------------------------------

### Invoke CPAN shell with perl -MCPAN -e shell

Source: https://perldoc.perl.org/5.42.0/perlutil.txt

Use this command to start the interactive CPAN shell, similar to the command-line mode of the CPAN module. It is used to install modules or distributions from CPAN, get information about them, and more.

```bash
perl -MCPAN -e shell
```

--------------------------------

### Synopsis usage example

Source: https://perldoc.perl.org/5.42.0/Config%3A%3APerl%3A%3AV.txt

Shows how to use the module: load it and call myconfig to get a hash reference, then access the osname from the config section.

```perl
use Config::Perl::V;

my $local_config = Config::Perl::V::myconfig ();
print $local_config->{config}{osname};
```

--------------------------------

### prove --rules examples

Source: https://perldoc.perl.org/5.42.0/prove.txt

Control parallel execution with --rules. First example allows all tests in parallel except those starting with 'p'. Second example runs all tests in sequence except those starting with 'p' in parallel.

```bash
# All tests are allowed to run in parallel, except those starting with "p"
--rules='seq=t/p*.t' --rules='par=**'
```

```bash
# All tests must run in sequence except those starting with "p", which should be run parallel
--rules='par=t/p*.t'
```

--------------------------------

### SYNOPSIS: getopts and getopt usage examples

Source: https://perldoc.perl.org/5.42.0/Getopt%3A%3AStd.txt

Examples from the SYNOPSIS section showing how to use getopts() and getopt() with boolean flags, argument-taking switches, and optional hash references to store options.

```perl
use Getopt::Std;

getopts('oif:');  # -o & -i are boolean flags, -f takes an argument
		      # Sets $opt_* global variables as a side effect
getopts('oif:', \my %opts);  # Options as above, values in %opts
getopt('oDI');    # -o, -D & -I take arguments
                      # Sets $opt_* global variables as a side effect
getopt('oDI', \my %opts);    # -o, -D & -I take arg, values in %opts
```

--------------------------------

### HTTP::Tiny basic GET request example

Source: https://perldoc.perl.org/5.42.0/HTTP%3A%3ATiny.txt

Shows a simple GET request using HTTP::Tiny, checking success, printing status, reason, headers, and content. This is the canonical usage example from the SYNOPSIS.

```perl
    use HTTP::Tiny;

    my $response = HTTP::Tiny->new->get('http://example.com/');

    die "Failed!\n" unless $response->{success};

    print "$response->{status} $response->{reason}\n";

    while (my ($k, $v) = each %{$response->{headers}}) {
        for (ref $v eq 'ARRAY' ? @$v : $v) {
            print "$k: $_\n";
        }
    }

    print $response->{content} if length $response->{content};
```

--------------------------------

### INSTALL_BASE installation pattern

Source: https://perldoc.perl.org/5.42.0/ExtUtils%3A%3AMakeMaker.txt

Shows the installation pattern for INSTALL_BASE, setting several INSTALL* attributes at once.

```text
INSTALLARCHLIB     INSTALL_BASE/lib/perl5/$Config{archname}
INSTALLPRIVLIB     INSTALL_BASE/lib/perl5
INSTALLBIN         INSTALL_BASE/bin
INSTALLSCRIPT      INSTALL_BASE/bin
INSTALLMAN1DIR     INSTALL_BASE/man/man1
INSTALLMAN3DIR     INSTALL_BASE/man/man3
```

--------------------------------

### cpan command examples for module management

Source: https://perldoc.perl.org/5.42.0/App%3A%3ACpan.txt

Common cpan commands: upgrade all installed modules, install modules (with optional -i), force install with -fi, and install without testing with -Ti.

```shell
# upgrade all installed modules
cpan -u

# install modules ( sole -i is optional )
cpan -i Netscape::Booksmarks Business::ISBN

# force install modules ( must use -i )
cpan -fi CGI::Minimal URI

# install modules but without testing them
cpan -Ti CGI::Minimal URI
```

--------------------------------

### Example_qr_package implementation

Source: https://perldoc.perl.org/5.42.0/perlreapi.txt

Example implementation of the qr_package callback that returns the package name 're::engine::Example'.

```C
    SV*
    Example_qr_package(pTHX_ REGEXP * const rx)
    {
    	PERL_UNUSED_ARG(rx);
    	return newSVpvs("re::engine::Example");
    }
```

--------------------------------

### Plugin configuration example

Source: https://perldoc.perl.org/5.42.0/CPAN.txt

Example of a plugin_list entry: CPAN::Plugin::Flurb=dir,/opt/pkgs/flurb/raw,verbose,1

```plaintext
CPAN::Plugin::Flurb=dir,/opt/pkgs/flurb/raw,verbose,1
```

--------------------------------

### install()

Source: https://perldoc.perl.org/5.42.0/ExtUtils%3A%3AInstall.txt

Installs files from source to target directories. The recommended interface accepts a single hashref with a mandatory 'from_to' option. Returns a hashref of results on success, or dies on failure.

```APIDOC
## install()

### Description
Installs files from source to target directories. The recommended interface accepts a single hashref with a mandatory 'from_to' option. Returns a hashref of results on success, or dies on failure.

### Method
install

### Parameters
#### Options (hashref)
- **from_to** (hashref) - Required - A hashref mapping source directories to target directories.
- **verbose** (integer) - Optional - Verbosity level.
- **dry_run** (boolean) - Optional - If true, perform a dry run without actually installing.
- **uninstall_shadows** (boolean) - Optional - If true, uninstall shadow files.
- **skip** (arrayref) - Optional - List of patterns to skip.
- **always_copy** (boolean) - Optional - If true, always copy files even if unchanged.
- **result** (hashref) - Optional - A hashref to store results.

### Return Value
- On success, returns a hashref of results. If a result parameter is provided, the returned hashref is the same as the passed-in hashref.
- On failure, dies (throws an exception).

### Example
```perl
my $result = install({
    from_to => { 'blib/lib' => '/usr/lib/perl5' },
    verbose => 1,
});
```
```

--------------------------------

### Manually install a failed module

Source: https://perldoc.perl.org/5.42.0/perlos2.txt

Manually installs a module whose installation failed, for example because DLLs were already loaded by CPAN.pm. Change to the module's build directory and run 'make install'.

```shell
cd $CPANHOME/.cpan/build/Digest-MD5-2.31
make install
```

--------------------------------

### Load a different math library with lib options

Source: https://perldoc.perl.org/5.42.0/bigfloat.txt

Command-line examples showing how to load the GMP math library using the l, lib, try, and only options.

```shell
perl -Mbigfloat=l,GMP -e 'print 2 ** 512'
```

```shell
perl -Mbigfloat=lib,GMP -e 'print 2 ** 512'
```

```shell
perl -Mbigfloat=try,GMP -e 'print 2 ** 512'
```

```shell
perl -Mbigfloat=only,GMP -e 'print 2 ** 512'
```

--------------------------------

### index function with offset example

Source: https://perldoc.perl.org/5.42.0/functions/index.txt

Shows how to use the optional POSITION argument to start searching from a specific offset, allowing you to find the second occurrence of a substring. The example finds 'e' starting at position 5, returning 10.

```perl
index("Perl is great", "e", 5);  # Returns 10
```

--------------------------------

### Installation instructions for Module::Build

Source: https://perldoc.perl.org/5.42.0/perlmodstyle.txt

Standard installation steps for modules using Module::Build: perl Build.PL, perl Build, perl Build test, perl Build install.

```shell
perl Build.PL
perl Build
perl Build test
perl Build install
```

--------------------------------

### perl Makefile.PL with INSTALL_BASE

Source: https://perldoc.perl.org/5.42.0/ExtUtils%3A%3AMakeMaker.txt

Pass INSTALL_BASE to Makefile.PL to change where the module will be installed. Example installs everything in your home directory.

```shell
# Unix users, INSTALL_BASE=~ works fine
perl Makefile.PL INSTALL_BASE=/path/to/your/home/dir
```

--------------------------------

### config() Method

Source: https://perldoc.perl.org/5.42.0/Math%3A%3ABigInt.txt

Demonstrates setting and getting class variables using config(). The example sets trap_nan and gets accuracy.

```perl
Math::BigInt->config("trap_nan" => 1);      # set
$accu = Math::BigInt->config("accuracy");   # get
```

--------------------------------

### new

Source: https://perldoc.perl.org/5.42.0/ExtUtils%3A%3AInstalled.txt

Creates a new ExtUtils::Installed object. The constructor accepts optional parameters such as skip_cwd.

```APIDOC
## new

### Description
Creates a new ExtUtils::Installed object. The constructor accepts optional parameters such as skip_cwd.

### Method
new

### Parameters
- **skip_cwd** (boolean) - Optional - If true, skips the current working directory when scanning for installed modules.

### Returns
- **ExtUtils::Installed** - A new ExtUtils::Installed object.
```

--------------------------------

### Get default include path (incomplete)

Source: https://perldoc.perl.org/5.42.0/App%3A%3ACpan.txt

Starts a subroutine to get the default include path, but the code is incomplete as shown.

```perl
sub _get_default_inc
	{
	require Config;
```

--------------------------------

### Example variables for /some/path/foo.ext

Source: https://perldoc.perl.org/5.42.0/File%3A%3AFind.txt

Shows the values of $File::Find::dir, $_, and $File::Find::name when examining the file /some/path/foo.ext.

```text
$File::Find::dir  = /some/path/
$_                = foo.ext
$File::Find::name = /some/path/foo.ext
```

--------------------------------

### phase_name usage example

Source: https://perldoc.perl.org/5.42.0/perlapi.txt

Example showing how to use phase_name to get the current interpreter phase and include it in a warning message.

```c
const char* phase_name = phase_name(PL_phase);
    mess("This is weird. (Perl phase: %s)", phase_name);
```

--------------------------------

### Plugin invocation examples

Source: https://perldoc.perl.org/5.42.0/App%3A%3AProve.txt

Shows how to load a plugin with -P and pass arguments using commas.

```shell
prove -PMyPlugin
```

```shell
prove -PMyPlugin=foo,bar,baz
```

--------------------------------

### Subroutine signature parameter must start with sigil

Source: https://perldoc.perl.org/5.42.0/perldiag.txt

Shows a valid subroutine signature with parameters starting with $, @, or %. The example is from the error message 'A signature parameter must start with '$', '@' or '%''.

```perl
sub foo ($x, $, $y = 1, @z) {}
```

--------------------------------

### PM_FILTER example to remove comments

Source: https://perldoc.perl.org/5.42.0/ExtUtils%3A%3AMakeMaker.txt

PM_FILTER is a filter program applied to each .pm file during the build. This example removes lines starting with '#'.

```perl
PM_FILTER => 'perl -ne "print unless /^#/"',
```

--------------------------------

### After action requirements table

Source: https://perldoc.perl.org/5.42.0/CPAN%3A%3AMeta%3A%3ASpec.txt

Table showing which phases must be satisfied after installation actions. For example, 'make install' requires 'runtime'.

```text
  after action        requirements that must be met
  ----------------    --------------------------------
  make install        runtime
  Build install
```

--------------------------------

### config method example

Source: https://perldoc.perl.org/5.42.0/TAP%3A%3AParser%3A%3ASource.txt

Shows getter and setter usage for configuration.

```perl
my $config = $source->config;
$source->config({ %some_value });
```

--------------------------------

### Get PI with bigrat

Source: https://perldoc.perl.org/5.42.0/bigrat.txt

Command-line example to print PI.

```perl
# perl -Mbigrat=PI -wle 'print PI'
```

--------------------------------

### plan - Set up test plan

Source: https://perldoc.perl.org/5.42.0/Test%3A%3ABuilder.txt

Convenient way to set up tests. Prints appropriate headers and takes actions. Do not call other setup methods if you call plan().

```perl
$Test->plan('no_plan');
$Test->plan( skip_all => $reason );
$Test->plan( tests => $num_tests );
```

--------------------------------

### Print version information

Source: https://perldoc.perl.org/5.42.0/bigfloat.txt

Command-line example using the 'v' option to print module name and version.

```shell
perl -Mbigfloat=v
```

--------------------------------

### Set PATH for Perl installation

Source: https://perldoc.perl.org/5.42.0/perlwin32.txt

Add the Perl bin directory to your PATH to use the installed Perl. Example uses c:\perl\bin.

```shell
set PATH=c:\perl\bin;%PATH%
```

--------------------------------

### PM hashref example

Source: https://perldoc.perl.org/5.42.0/ExtUtils%3A%3AMakeMaker.txt

PM is a hashref of .pm files and *.pl files to be installed. The key is the source file and the value is the installation path.

```perl
{'name_of_file.pm' => '$(INST_LIB)/install_as.pm'}
```
Tokens:
Raw