===== Perl =====

=== IDE ===
| Notepad++ | NppExec can execute perl in Editor <code>cmd /c perl "$(FULL_CURRENT_PATH)"</code> |
| EPIC is a Perl Plugin for Eclipse | [[http://www.epic-ide.org/index.php|EPIC]] **ACHTUNG:** \\ autocomplete is supported just on dereferencing from packages! |


===Howtos===

| 1. What does the header in perl files mean?| [[http://perldoc.perl.org/perlrun.html|perldoc.perl.org]] |
| 2. A syntax summary  | [[http://en.wikipedia.org/wiki/Perl_language_structure|Wikipedia]]|
| 3. A huge tutorial collection here | [[http://perl-tutorial.org/|perl-tutorial.org]]|
| 4. Howto compare values in perl | [[http://perlmeme.org/howtos/syntax/comparing_values.html|perlmeme.org]]|
| 5. References in Perl | [[http://www.perl.com/pub/1999/09/refererents.html|www.perl.com]] |
| 6. All Perl Operators | [[http://de.wikibooks.org/wiki/Perl-Programmierung:_Operatoren|de.wikibooks.org]] |
| 7. Objects in Perl | [[http://www.perl.com/pub/1999/09/refererents.html|www.perl.com]] |
| 8. Packages and Modules in Perl | [[http://www.tutorialspoint.com/perl/perl_modules.htm|www.tutorialspoint.com]], [[Perl#creating_modules|creating_modules]] |
| 9. External Modules | [[http://search.cpan.org/|CPAN]] |
|10. Passing Arguments to subs | {{http://perldoc.perl.org/perlfaq7.html#How-can-I-pass%2freturn-a-%7bFunction%2c-FileHandle%2c-Array%2c-Hash%2c-Method%2c-Regex%7d%3f|perldoc.perl.org}} |
|11. Perl regular expressions| {{http://perldoc.perl.org/perlrequick.html|perldoc.perl.org}} {{http://perldoc.perl.org/perlre.html|perldoc.perl.org Detailed}}|

=== Documentation ===
| All Perl Functions | [[http://www.tutorialspoint.com/perl/perl_function_references.htm|tutorialspoint.com]] |


=== Install Modules ===
The modules are located on [[http://search.cpan.org/|http://search.cpan.org/]]

The modules can be installed per //ppm// command.
<sxh perl>
ppm install File-Slurp
ppm install Mojolicious
ppm install DBD-mysql
</sxh>


===Stolperfallen===
<sxh perl>
#ACHTUNG: Notations
# my	- variable definition
# %		- hash
# @ 	- array
# $		- scalar, hash value
# ()	- create functions, array, hashes
# {}	- access hashes
# []	- access arrays
# =>	- create hashes
# ->{}	- dereference hash-reference and access value in hash
# ->[]	- dereference array-reference and access value in array
# ->()	-  dereference sub-reference and execute it  
# $$ref	 -  OR dereference object-reference and execute its method $$ref::method()  equals to $ref->method()


#ACHTUNG: comparison
# ==	- for numeric values AND String which start with a number
# eg	- for Strings


# ACHTUNG - available magic vars
# @_   - an array with sub-arguments, available in every sub. 
# $_[] - accesses a particular argument, like $_[0], $_[1] ...

# ACHTUNG - to access a concrete hashvalue use $$. To access the whole hashblock (e.g. in foreach) use %.
%hash = ('joe', "red", 'sam', "blue");
$hash{sam}="blue"; 

#ACHTUNG do declare a subroutine you don't need parenthesis like myfunc()
sub myfunc{  
 ...
}

#ACHTUNG: use $ or -> to dereference a Hash in order to ACCESS single hashvalues.
print "$hashkey belongs to ".$$mhash_ref{$hashkey};
print "$hashkey belongs to ".$mhash_ref->$hashkey; 


#ACHTUNG when accessing a Variable inside of a Namespace - prepend the $ to whole expression, not to the variable name
print $Foo::var;

#ACHTUNG - calling object's method as Object::method and Object->method is not the same. When using -> the source instance is passed as argument 0
MyObject::sayArgs(1,2,3); # here the @_[0] is 1
MyObject->sayArgs(1,2,3); # here the @_[0] is a REFERENCE to the source Instance

</sxh>
==== Syntax ====
Here the perl Syntax is listed as a Demo script.


=== Introduction ===
<sxh perl>
#!usr/bin/perl -w
#HTML

#comment: perl need a semicolon at the end of the line. Dont forget it!

#ACHTUNG: Notations
# my	- variable definition
# %		- hash
# @ 	- array
# $		- scalar, hash value
# &		- sub (function)
# ()	- create functions, array, hashes
# {}	- access hashes
# []	- access arrays
# =>	- create hashes
# ->{}	- dereference hash-reference and access value in hash
# ->[]	- dereference array-reference and access value in array
# ->(Argument)	-  dereference sub-reference and execute it  
# $$ref	-    OR dereference object-reference and execute its method $$ref::method()  equals to $ref->method()


#ACHTUNG: comparison
# ==	- for numeric values AND String which start with a number
# eg	- for Strings



# reference types are get by "ref"
# If $slr_ref contains...	then ref($slr_ref) returns...
# a scalar value undef
# a reference to a scalar	"SCALAR"
# a reference to an array	"ARRAY"
# a reference to a hash	"HASH"
# a reference to a subroutine	"CODE"
# a reference to a filehandle	"IO" or "IO::Handle"
# a reference to a typeglob	"GLOB"
# a reference to a precompiled pattern	"Regexp"
# a reference to another reference	"REF"


# ACHTUNG - available magic vars
# @_   - an array with sub-arguments, available in every sub. 
# $_[] - accesses a particular argument, like $_[0], $_[1] ...


# ACHTUNG - anonymous data stuctures
# {'key' => 'val1', ..} - creates an nonymous REFERENCE to a HASH
# ['val1', 'val2', ..]  - creates an nonymous REFERENCE to an ARRAY

# NOTATIONS
# saves the first argument to $firstargs and others to #saves the first argument to $firstargs and others to @restArgs
# ($firstarg, @restArgs) = @_;  




print "Hello, world!\n";

#the newline wont be understood
$mystring = 'Hello String';
print " $mystring ";

#multiline string
$multilined_string = <<EOF;
This is my multilined string
note that I am terminating it with the word "EOF".
EOF
print $multilined_string;




# perl converts strings to numbers by taking the prefix
$n = '3 apples';
$m = '2 oranges';
print $n + $m;


#false collection
$false = 0; # the number zero
$false = 0.0; # the number zero as a float
$false = 0b0; # the number zero in binary
$false = 0x0; # the number zero in hexadecimal
$false = '0'; # the string zero
$false = ""; # the empty string
$false = undef; # the return value from undef
$false = 2-3+1;  # computes to 0 which is converted to "0" so it is false


#datatypes
$scalar = "1";
$scalar = 'string';
$scalar = 'c:\filehandle.txt';
@array = ('Billy', 'Joe', 'Jim-Bob');
@array = qw(Billy Joe Jim-Bob); #qw inserts quotes and commas
%hash = ('joe', "red", 'sam', "blue");
%hash = (joe => 'red', sam => 'blue');
$hash{joe}="red";
$hash{sam}="blue"; # ACHTUNG - to access a concrete hashvalue use $. To access the whole hashblock (e.g. in foreach) use %.





#Filehandle is written in capital case
open(MYFILE,">test.txt") ||
  die("Programmabbruch: Konnte die Datei test.txt nicht offnen");
close(MYFILE);


#boolean structure
$real_result = 0 ? 0 : 1;
print $real_result;


#subroutine define and call
sub mysubroutine
{
	print "\n\n";
	print "Not a very interesting routine\n";
	print "This does the same thing every time\n";
}
&mysubroutine;


#subroutine with arguments
sub subWithArgs
{
	# (my %$arg0) = @_;
	my $aaRef = shift;
	# %mhash = {'ger_name' => 'Sasa'};
	# @mlist = ('one','two','three');
	# print keys %mhash  . "\n";

	
	foreach (keys %{$aaRef}){
		print $_ .' ';
	}
}
%mhash = {'ger_name' => 'Sasa'};
subWithArgs(\%mhash);


%mhash = (one => 'bang', two => 'bang', three => 'boom');
foreach $hashkey (sort keys %mhash){  # % - dereferencing respects the type of reference object
	print $hashkey;
}




#typoglob are pointers
$firstval = "firstval";
*pointertofirst = *firstval;
print $pointertofirst;


#control structures
# initialize a hash structure (name, age)
#VORSICHT: runde Klammern!
@myarray = ("one","two","three");
foreach $arrayitem (@myarray){
	print "\n$arrayitem";
}
#printing an array
print @myarray; 				# prints: onetwothree
print "\nArrayprint: @myarray"; # prints: one two three
print "\nArrayprint with join: ".join("___", @myarray);

%persons = (John => 25, Anne =>32, Paul =>22, Smith => 29);
foreach $name (sort keys %persons) {
  print "$name is $persons{$name} years old.\n";
}continue{
	print "Continue block is called every time, when the condition is evaluated again \n";
}

for($i=0; $i<5; $i++){
	print $i;
	last; # this is break. This ends the loop.
	next; # this will jump to the next iteration, its like continue statement
	redo; # this will repeat the loop
}

$alter=18;
unless($alter>18){
	print "\nZugriff Verweigert!\n";
}


# implicit loopings
@myarray = (1,2,3,4,5,6);
@result = grep{$_>3;} @myarray;
print join(" ",@result). "\n";



#map is like walk
@myarray = (1,2,3,4,5,6);
@selected = map $_** 2,  @myarray;
print "@selected";

my @myarray = (1,2,3,4,5,6);
@selected = map {$_-7; $_**3;}  @myarray;
print "\n@selected";


#subroutine alias function
# @_ is the array with the parameters.
# parameters are passed by reference
@arg = ('a','b','c');
myfunc('one', (joe => 'neulowimij', bill => 'odnorukij' ) , 'two', 99, @arg );
sub myfunc{  #ACHTUNG do declare a subroutine you don't need parenthesis like myfunc()
	print "\n";
	print "All arguments: @_ \n";
	print "first argument is $_[0] \n";
	print "second argument is $_[1] \n";
	print "second argument is $_[2] \n";
	print "second argument is $_[3] \n";
	
	#implicitly return 5. result is the last thing evaluated.
	#5;
	# may explicitely return 
	return 5;
}

print countParams(1,2,3);
sub countParams{
	scalar @_; #counts the array length
}



#pass by reference
$var = 1;

print "Var is $var \n"; #prints 1
settotwo($var);
print "Var is $var \n"; #prints 2

sub settotwo{
	$_[0]=2; #parameters are passed by reference. change the parameter.
}


# to pass parameters by value - save the parameter to temporary  vars
$var = 1;

print "Var is $var \n";
setpars($var);
print "Var is $var \n";
sub setpars{
	($first, $second, $third)=@_; #now you can use the parameters in the list
	$first=1;
	$second=2;
	$third=3;
}



#REFERENCES
# references are set by \ 
# dereferenced by $$ or by ->
$str = "hello";  ## original string
$ref = \$str;    ## compute $ref that points to $str
print "$$ref\n"; ## prints "hello" -- identical to "$str\n"; 

#reference types
$ref = \$ref;
print ref $ref . "\n";
if((ref $ref) eq "SCALAR"){ print "SCALAR \n";}
if((ref $ref) eq "ARRAY"){ print "ARRAY \n";}
if((ref $ref) eq "xuj"){ print "xj \n";}

@marr = ('bang','bang','boom');
$marr_ref = \@marr; 			#reference is made by unary operator \
print $marr_ref->[2];
foreach $arritem (@$marr_ref){	# @ - dereferencing respects the type of reference object
	print $arritem;
}continue{
	print "\n";
}

%mhash = (one => 'bang', two => 'bang', three => 'boom');
$mhash_ref = \%mhash; 						#reference is made by unary operator \
foreach $hashkey (sort keys %$mhash_ref){  # % - dereferencing respects the type of reference object
	print "$hashkey belongs to ".$$mhash_ref{$hashkey}; #ACHTUNG: use $ or -> to dereference a Hash in order to ACCESS single hashvalues.
	print "$hashkey belongs to ".$mhash_ref->{$hashkey}; 
	print $mhash_ref->{$hashkey}
}continue{
	print "\n";
}

#anonymous hash-REFERENCE is created by using {}
my $hashref = {'myhashkey1' => 'myvalue1','myhashkey2' => 'myvalue2'};
foreach ( keys %$hashref ){
		print $_ ;
		print " : ";
		print $hashref -> {$_};
		print "\n";
}

#anonymous array-REFERENCE is created by using []
my $arrayref = ['anonymarrayval0', 'anonymarrayval1', 'anonymarrayval2','anonymarrayval3', 'anonymarrayval4'];
foreach ( @$arrayref ){
		print $_ ;
		print "\n";
}

#replace single value by reference
$hashref->{'myhashkey1'} = 'newvalue';
$arrayref->[0] = 'newArrValue0';

#replace the whole referenced structure
%$hashref = ('key' => 'value');
@$arrayref = ('arrayval1', 'arrayval2');





#NAMESPACES
#package <NAME> defines a new Namespace. "package main" gets back to default namespace
# In the Namespace there can be Variables or subs
# Namespace is accessed by NAMESPACE::subName or NAMESPACE::varName

package Foo;
sub mySub{
	print "mySub says blang \n";
}
$var = 47;
package main;

Foo::mySub();
print $Foo::var;	#ACHTUNG when accessing a Variable inside of a Namespace - prepend the $ to WHOLE expression, not to the variable name

#or you can paste a function directly into the Namespace.
sub Foo::myNewSub{
	print "this is a  new sub\n";
}
Foo::myNewSub();






#OBJECTS
# Objects are simulated by Namespaces 
sub MyObject::sayArgs{
	print "\n List of passed to this method: \n";
	foreach $arg (@_){
		print "$arg has type ". ref(\$arg). "\n";
	}
}
#ACHTUNG - calling object's method as Object::method and Object->method is not the same. When using -> then the source instance is passed as argument 0
MyObject::sayArgs(1,2,3); # here the @_[0] is 1
MyObject->sayArgs(1,2,3); # here the @_[0] is a REFERENCE to the source Instance

my $mPoint1 = Point->new(1,2);
my $mPoint2 = Point->new(3,4);
print $mPoint1->distance($mPoint2) ."\n";

sub Point::new {
  my ($class, $x, $y) = @_; # class (here Point) is implicetly passed to the 
  # Bless defines a structure, which will perform as an object instance
  # Here the Object will have the type Point, which will be an array
  # Implicit return of a REFERENCE to the new object
  bless [$x, $y], $class;   
}
 
sub Point::distance {
  my ($self, $from) = @_; # self is the reference to the instance of the current class, which is passed as 1 argument, when using -> to get arguments.
  print ref($from);
  my ($dx, $dy) = ($$self[0] - $$from[0], $$self[1] - $$from[1]);
  sqrt($dx * $dx + $dy * $dy);
}

#destructors - are called, before letting the memory free
sub Point::DESTROY{
	# shift pops the first argument from the @_ array
	# the first argument - is the imlicit reference to the this object-instance
	my ($self) = shift; 
	print "\n\n\n\n\n";
	print "Destorying the Object of type ".ref($self) . "\n";
}




# CREATING AN OBJECT WITH GETTER AND SETTER
# create a new Object using "ObjectStory" package
# constructor
sub ObjectStory::new{
	my($class, $title, $story, $answer) = @_;
	# make the 
	%hash = (title=>$title, story=>$story, answer=>$answer);
	bless \%hash, $class; #ACHTUNG: bless can only take references to objects, to use them as "self"
}

# getter and setter all together
sub ObjectStory::title{
	my ($self, $title) = @_;
	if(defined $title){
		$self->{title} = $title;
	}
	return $self->{title};
}

# ObjectStory usage.
my $myObject = ObjectStory->new("DerTitel", "Die Geschichte", "DIe Antwort"); 
print "\n Der ObjectStory Titel ist: ". $myObject->title();
$myObject->title("Titel2");
print "\n Der neue ObjectStory Titel ist: ". $myObject->title();




#BLOCKS
#Following blocks will be executed on different Stages of the script
# print               "    PRINT: main running		\n";
# die                 "    DIE:   main dying			\n";
# die                 "DIE XXX /* NOTREACHED */";
# END         { print "1st END:   done running		\n";    }
# CHECK       { print "1st CHECK: done compiling		\n";    }
# INIT        { print "1st INIT:  started running		\n";    }
# END         { print "2nd END:   done running		\n";    }
# BEGIN       { print "1st BEGIN: still compiling		\n";    }
# INIT        { print "2nd INIT:  started running		\n";    }
# BEGIN       { print "2nd BEGIN: still compiling		\n";    }
# CHECK       { print "2nd CHECK: done compiling		\n";    }
# END         { print "3rd END:   done running		\n";    }





#OWN Module
use CGI;
use Cwd 'abs_path'; #the module to get the current directory, to import my own modules
use File::Basename;	#the module to parse the full path to this script
use File::Spec::Functions qw(rel2abs);

#block is executed on start. This block will make the script search for required modules in the same folder. User require inside of the block to import pm files.
BEGIN{
	# editing the @INC Variable to put the current script's directory into it
	my $scriptdir = dirname(rel2abs($0));
	push @INC,"$scriptdir"; 	#add current scripts dir to module sources
	
	# use ZvgEntry;	# wont work because evaluated at compiletime	
	require MyModule;	# require is evaluated at runtime. Here the the name of the *.pl file should be.
}

my $myModule = new MyModule();
$myModule->Bar();
$myModule->Foo();





#REGEXP
my $string = "betestesda";
  
#operator "m" checks if a String matches the regexp
# =~ m/regex/
if ($string =~ m/test/) {
	print "match!!! \n";
}else{
	print "no match!!! \n";
}


#Error handling

#printing Errors is done by redirecting the output to STDERR file
print STDERR "My Error";

#you can let perl do somehting on error
print "xoxo" or die("Error on printing xoxo");

#or you can do multiple things
print "xoxo" or do{
	print STDERR "Error on printing xoxo";
	print "Peng!";
};





</sxh>


==== Starting Blocks ====
There are several Blocks in Perl, where some code can be inserted, which will influence the running sequence.
<sxh perl>
% cat sto-INIT-eg
#!/usr/bin/perl -l
print               "    PRINT: main running		\n";
die                 "    DIE:   main dying		\n";
die                 "DIE XXX /* NOTREACHED */";
END         { print "1st END:   done running		\n";    }
CHECK       { print "1st CHECK: done compiling		\n";    }
INIT        { print "1st INIT:  started running		\n";    }
END         { print "2nd END:   done running		\n";    }
BEGIN       { print "1st BEGIN: still compiling		\n";    }
INIT        { print "2nd INIT:  started running		\n";    }
BEGIN       { print "2nd BEGIN: still compiling		\n";    }
CHECK       { print "2nd CHECK: done compiling		\n";    }
END         { print "3rd END:   done running		\n";    }
</sxh>

Will be executed as:
<sxh perl>
1st BEGIN: still compiling
2nd BEGIN: still compiling
2nd CHECK: done compiling
1st CHECK: done compiling
1st INIT:  started running
2nd INIT:  started running
    PRINT: main running
    DIE:   main dying
3rd END:   done running
2nd END:   done running
1st END:   done running
</sxh>

==== Creating Modules ====
The Modules are created in ***.pm** files by using the **package** command.

To import a module you can use the following commands
<sxh perl>
use ModuleName; # evaluated at compiletime. Expecially you can't add new path sources previously to a "use"
require ModuleName; # evaluated at runtime.
</sxh>

To import own module from the same directory as the current script - add teh current dir to the var @INC, inside of the **BEGIN** block. \\
ACHTUNG: Only use **require** to import Modules from newly added directory, because only require is evaluated at runtime.

<sxh perl>
use Cwd 'abs_path'; #the module to get the current directory, to import my own modules
use File::Basename; #the module to parse the full path to this script

BEGIN{
	# editing the @INC Variable to put the current script's directory into it
	my $fullscriptpath = abs_path($0);							# getting the full path to this script incl. filename
	my($filename, $directories) = fileparse($fullscriptpath);	#directories now contains

	push @INC,"$directories"; 	#add current scripts dir to module sources
	
	# use ModuleFromScriptDir;	# wont work because use is evaluated at compiletime	
	require ModuleFromScriptDir;	# require  is evaluated at runtime
}
</sxh>


==== Error handling ====
Use function **eval** to catch **die** signals. 

<sxh perl>
eval {
	 #code you want to catch errors from
	 die($!);
};
#errors are in @_
if ($@) {
    print "ERROR: $@ \n";
}

print "code after die will be executed";
</sxh>


==== Parse HTML ====
[[http://search.cpan.org/~sri/Mojolicious-3.36/lib/Mojo/DOM.pm|Mojo::DOM search.cpan.org]] \\
[[http://mojolicio.us/perldoc/Mojo/DOM|Mojo::DOM mojolicio.us]]

<sxh perl>

$dom = Mojo::DOM->new('<div><p id="a">A</p><p id="b">B</p></div>');

#id
print ($dom->at('#a')->text);

# get all text
print ($dom->all_text);

# get text at the first occurence of <p>
print ($dom->at('p')->all_text);

#find all tags
my @trobjects = $dom->find('tr')->each;
for my $trobject (@trobjects){	
	print ($trobject->all_text); 
}
</sxh>


==== Regular Expressions ====
The regular Expression is explained the best by example.
==Basics==
Regeular Expressions in Perl are written like that:
<sxh perl>"cat in the castle with a dog" =~ /(ca|do)(?:stle|g)/ </sxh>

<code>
// - marks the beginning and the End of the regexp
() - marks the part, which should be returned, if the exression is configured to return the match and not only to tell true/false when it matchen/not matches.
(?: content_here) - is called "not matching parenthesis". They can group content, but won't return the enclose content, if it matches. Can be used for grouping.
=~ is used with a string. Without further parameters the expression returns true, when the given string matches.
!~ inverse of above
[^o] - match everything except of "o"
</code>

==Making the expression return something ==
The expression can be configured to return something by using the /g **modifier** which are written **AFTER** the expression.

|/g|<sxh perl>my @matches = ( $str =~ /pa(tt)ern/g ) # /g makes it return all matches to an array</sxh>|

==Modifiers==
**Modifier** are written **AFTER** the expression.
<code>
i 	Makes the match case insensitive  - "pATTERn" =~ /(paTtErN)/i
m 	Specifies that if the string has newline or carriage
	return characters, the ^ and $ operators will now
	match against a newline boundary, instead of a
	string boundary
o 	Evaluates the expression only once
s 	Allows use of . to match a newline character
x 	Allows you to use white space in the expression for clarity
g 	Globally finds all matches
cg 	Allows the search to continue even after a global match fails
</code>

==Operators==
**Operators** are written **BEFORE** the expression. More about it [[http://www.tutorialspoint.com/perl/perl_regular_expression.htm|here]]
<sxh perl>
#Substitute Regular Expression - s///
"my dog" =~ s/dog/cat/; # my cat

#Match Regular Expression - m// 
"dog" =~ m/(d.g)/ #true. /m can be omitted
</sxh>

==Character classes==
<code>
\r \n \s ...
</code>

What means what is listed here: http://refcards.com/docs/trusketti/perl-regexp/perl-regexp-refcard-a4.pdf