# Example:
# Simple program called programming.pl
use strict;
use warnings;
use Data::Dumper qw(Dumper);

print Dumper \@ARGV;

# Run the program like this: perl programming.pl -a --machine remote /etc
# The output would be:
$VAR1 = [ '-a',
          '--machine',
          'remote',
          '/etc'
        ];

\!h # Extract command line arguments from @ARGV

# @ARGV is where the diamond operator looks when called, trying to determine what filenames it should use.
# Because of how it works, you have a chance to tinker with it and force specific files, regardless of what the user chose on the command line.
# Example:
@ARGV = qw(larry moe curly); # force these three files to be read
while (<>) {
  chomp;
  say "It was $_ that I saw in some stooge-like file!";
}

\!h use v5.22;

while (<<>>) {
  chomp;
  say "It was $_ that I saw!";
}

while (defined($line = <>)) {
  chomp($line);
  say "It was $line that I saw!";
}

# There's also a shortcut for this:
while (<>) {
  chomp; # acts on $_ by default
  say "It was $_ that I saw!";
}

# So, if your arguments are fred, barney and betty, the program will return something like:
# "It was [a line from file fred] that I saw!";
# "It was [another line from file fred] that I saw!";
# ...until it reaches the end of file fred.
# Then it moves onto files barney and betty, doing the same thing.
# The current file's name is stored in $ARGV, it could be '-' if its a standard input stream.
# Note: there's no break when you go from one file to another, 
# as if the input files merged into one big one.

while (defined($line = <STDIN>)) { # reading input into a variable and checking if it's defined.
  print "I saw $line"; # if it is, you're running the body of the while loop and printing each line.
}

# foreach alternative:
foreach(<STDIN>) {
  print "I saw $_";
}

# The differnence between the two is how they work through the input behind the scenes.
# The while loop, Perl reads a single line of input, puts it into a variable and runs the body of the loop.
# In a foreach loop, it reads all of the input before the loop can start running, this can become problematic with big web server logfiles.
# Therefore, it's usually better to use the while loop's shortcut.

sub marine {
  state $n = 0; # private, persistent variable $n
  $n += 1;
  say "Hello, sailor number $n!";
}
# state isn't just used for scalar variables. 
# However, you can't initialize arrays and hashes in list context with state:
state @numbers; # OK
state @numbers = qw(...); # WRONG, won't work

# Except for the main rules, your parameter list needs to be in parentheses, it's got to be a function call:
my @cards = shuffle(@deck_of_cards); # no ampersand needed on &shuffle

# However, if Perl's internal compiler has already seen the subroutine definition,
# you can even omit the parentheses around the argument list:
sub division {
  $_[0] / $_[1]; # divide first param by second
}

my $quotient = division 355, 113; # uses &division
# the sub declaration has to be placed before the invocation

\!h # Important - you cannot omit the ampersand if your sub has the same name as a Perl built-in:
sub chomp {
  say "Munch, munch!";
}

&chomp; # ampersand not optional here

my @names = qw/ fred barney betty dino wilma pebbles bamm-bamm/;
my $result = &which_element_is("dino", @names);

# Find the index of dino, in the array @names
sub which_element_is {
  my($what, @array) = @_; # $what = to look for, @array = to search in
  foreach (0..$#array) { # iterate all indices of @array
    if ($what eq $array[$_]) {
      return $_; # return early once found
    }
  }
  -1             # element not found - 'value not found' code (return not needed here)
}

$maximum = &max(3, 5, 10, 4, 6);

sub max {
  my($max_so_far) = shift @_; # takes first element from parameter array
  foreach (@_) { # iterate through remaining values in the array
    if ($_ > $max_so_far) { # if current number is bigger than current max,
      $max_so_far = $_; # set the current number to the current max instead
    }
  }
  $max_so_far; # return value
}

\!h # Empty Parameter Lists
# This comes into play with a line like this:
$maximum = &max(@numbers);
# @numbers might sometimes be an empty list
# Firstly, the subroutine sets $max_so_far by unshifting @_, making it undef.
# Then, the foreach loops tries to iterate over @_, executing the loop body zero times as @_ is empty.
# In the end, Perl returns the value of $max_so_far, undef, as the return value.

sub max {
  my($m, $n); # new, private variables for this block
  ($m, $n) = @_; # give names to parameters
  if ($m > $n) {$m} else {$n}
  
  # the second line can be omitted and merged with the first one like so:
  # my ($m, $n) = @_; 
}

# Note: without the parentheses, my only declares a single lexical variable:
my $fred, $barney; # failed to declare $barney
my ($fred, $barney); # correct, declared both

@rocks = qw( talc quartz jade obsidian);
print "How many rocks do you have?\n"; 
print "I have ", @rocks, " rocks!\n"; # WRONG, prints names of the rocks
print "I have ", scalar @rocks, " rocks!\n"; # correct, gives number of rocks