####
Main
####


****
NAME
****


Kernel::System::Main - main object


***********
DESCRIPTION
***********


All main functions to load modules, die, and handle files.


****************
PUBLIC INTERFACE
****************


new()
=====


create new object. Do not use it directly, instead use:


.. code-block:: perl

     my $MainObject = $Kernel::OM->Get('Kernel::System::Main');



Require()
=========


require/load a module


.. code-block:: perl

     my $Loaded = $MainObject->Require(
         'Kernel::System::Example',
         Silent => 1,                # optional, no log entry if module was not found
     );



RequireBaseClass()
==================


require/load a module and add it as a base class to the
calling package, if not already present (this check is needed
for persistent environments).


.. code-block:: perl

     my $Loaded = $MainObject->RequireBaseClass(
         'Kernel::System::Example',
     );



Die()
=====


to die


.. code-block:: perl

     $MainObject->Die('some message to die');



FilenameCleanUp()
=================


to clean up filenames which can be used in any case (also quoting is done)


.. code-block:: perl

     my $Filename = $MainObject->FilenameCleanUp(
         Filename => 'me_to/alal.xml',
         Type     => 'Local',            # Local|Attachment|MD5
     );
 
     my $Filename = $MainObject->FilenameCleanUp(
         Filename => 'some:file.xml',
         Type     => 'MD5',              # Local|Attachment|MD5
     );



FileRead()
==========


to read files from file system


.. code-block:: perl

     my $ContentSCALARRef = $MainObject->FileRead(
         Directory => 'c:\some\location',
         Filename  => 'file2read.txt',
         # or Location
         Location  => 'c:\some\location\file2read.txt',
     );
 
     my $ContentARRAYRef = $MainObject->FileRead(
         Directory => 'c:\some\location',
         Filename  => 'file2read.txt',
         # or Location
         Location  => 'c:\some\location\file2read.txt',
 
         Result    => 'ARRAY', # optional - SCALAR|ARRAY
     );
 
     my $ContentSCALARRef = $MainObject->FileRead(
         Directory       => 'c:\some\location',
         Filename        => 'file2read.txt',
         # or Location
         Location        => 'c:\some\location\file2read.txt',
 
         Mode            => 'binmode', # optional - binmode|utf8
         Type            => 'Local',   # optional - Local|Attachment|MD5
         Result          => 'SCALAR',  # optional - SCALAR|ARRAY
         DisableWarnings => 1,         # optional
     );



FileWrite()
===========


to write data to file system


.. code-block:: perl

     my $FileLocation = $MainObject->FileWrite(
         Directory => 'c:\some\location',
         Filename  => 'file2write.txt',
         # or Location
         Location  => 'c:\some\location\file2write.txt',
 
         Content   => \$Content,
     );
 
     my $FileLocation = $MainObject->FileWrite(
         Directory  => 'c:\some\location',
         Filename   => 'file2write.txt',
         # or Location
         Location   => 'c:\some\location\file2write.txt',
 
         Content    => \$Content,
         Mode       => 'binmode', # binmode|utf8
         Type       => 'Local',   # optional - Local|Attachment|MD5
         Permission => '644',     # optional - unix file permissions
     );


Platform note: MacOS (HFS+) stores filenames as Unicode \ ``NFD``\  internally,
and DirectoryRead() will also report them as \ ``NFD``\ .


FileDelete()
============


to delete a file from file system


.. code-block:: perl

     my $Success = $MainObject->FileDelete(
         Directory       => 'c:\some\location',
         Filename        => 'me_to/alal.xml',
         # or Location
         Location        => 'c:\some\location\me_to\alal.xml',
 
         Type            => 'Local',     # optional - Local|Attachment|MD5
         DisableWarnings => 1,           # optional
     );



FileGetMTime()
==============


get timestamp of file change time


.. code-block:: perl

     my $FileMTime = $MainObject->FileGetMTime(
         Directory => 'c:\some\location',
         Filename  => 'me_to/alal.xml',
         # or Location
         Location  => 'c:\some\location\me_to\alal.xml',
     );



MD5sum()
========


get an \ ``MD5``\  sum of a file or a string


.. code-block:: perl

     my $MD5Sum = $MainObject->MD5sum(
         Filename => '/path/to/me_to_alal.xml',
     );
 
     my $MD5Sum = $MainObject->MD5sum(
         String => \$SomeString,
     );
 
     # note: needs more memory!
     my $MD5Sum = $MainObject->MD5sum(
         String => $SomeString,
     );



Dump()
======


dump variable to an string


.. code-block:: perl

     my $Dump = $MainObject->Dump(
         $SomeVariable,
     );
 
     my $Dump = $MainObject->Dump(
         {
             Key1 => $SomeVariable,
         },
     );
 
     dump only in ascii characters (> 128 will be marked as \x{..})
 
     my $Dump = $MainObject->Dump(
         $SomeVariable,
         'ascii',        # ascii|binary - default is binary
     );



DirectoryRead()
===============


reads a directory and returns an array with results.


.. code-block:: perl

     my @FilesInDirectory = $MainObject->DirectoryRead(
         Directory => '/tmp',
         Filter    => 'Filenam*',
     );
 
     my @FilesInDirectory = $MainObject->DirectoryRead(
         Directory => $Path,
         Filter    => '*',
     );


read all files in subdirectories as well (recursive):


.. code-block:: perl

     my @FilesInDirectory = $MainObject->DirectoryRead(
         Directory => $Path,
         Filter    => '*',
         Recursive => 1,
     );


You can pass several additional filters at once:


.. code-block:: perl

     my @FilesInDirectory = $MainObject->DirectoryRead(
         Directory => '/tmp',
         Filter    => \@MyFilters,
     );


The result strings are absolute paths, and they are converted to utf8.

Use the 'Silent' parameter to suppress log messages when a directory
does not have to exist:


.. code-block:: perl

     my @FilesInDirectory = $MainObject->DirectoryRead(
         Directory => '/special/optional/directory/',
         Filter    => '*',
         Silent    => 1,     # will not log errors if the directory does not exist
     );


Platform note: MacOS (HFS+) stores filenames as Unicode \ ``NFD``\  internally,
and DirectoryRead() will also report them as \ ``NFD``\ .


GenerateRandomString()
======================


generate a random string of defined length, and of a defined alphabet.
defaults to a length of 16 and alphanumerics ( 0..9, A-Z and a-z).


.. code-block:: perl

     my $String = $MainObject->GenerateRandomString();


returns


.. code-block:: perl

     $String = 'mHLOx7psWjMe5Pj7';


with specific length:


.. code-block:: perl

     my $String = $MainObject->GenerateRandomString(
         Length => 32,
     );


returns


.. code-block:: perl

     $String = 'azzHab72wIlAXDrxHexsI5aENsESxAO7';


with specific length and alphabet:


.. code-block:: perl

     my $String = $MainObject->GenerateRandomString(
         Length     => 32,
         Dictionary => [ 0..9, 'a'..'f' ], # hexadecimal
         );


returns


.. code-block:: perl

     $String = '9fec63d37078fe72f5798d2084fea8ad';