view release on metacpan or  search on metacpan

doc/modules/Utility.html  view on Meta::CPAN

  # Usage      : use Mail::Toaster::Utility;
  #            : my $util = Mail::Toaster::Utility->new;
  # Purpose    : create a new Mail::Toaster::Utility object
  # Returns    : a bona fide object
  # Parameters : none
  ############################################</code></pre>

</dd>
<dt id="ask">ask</dt>
<dd>

<p>Get a response from the user. If the user responds, their response is returned. If not, then the default response is returned. If no default was supplied, 0 is returned.</p>

<pre><code>  ############################################
  # Usage      :  my $ask = $util-&gt;ask( &quot;Would you like fries with that&quot;,
  #                        default  =&gt; &quot;SuperSized!&quot;,
  #                        timeout  =&gt; 30
  #               );
  # Purpose    : prompt the user for information
  #
  # Returns    : S - the users response (if not empty) or
  #            : S - the default ask or
  #            : S - an empty string
  #
  # Parameters
  #   Required : S - question - what to ask
  #   Optional : S - default  - a default answer
  #            : I - timeout  - how long to wait for a response
  # Throws     : no exceptions
  # See Also   : yes_or_no</code></pre>

</dd>
<dt id="extract_archive">extract_archive</dt>
<dd>

<p>Decompresses a variety of archive formats using your systems built in tools.</p>

<pre><code>  ############### extract_archive ##################
  # Usage      : $util-&gt;extract_archive( &#39;example.tar.bz2&#39; );
  # Purpose    : test the archiver, determine its contents, and then
  #              use the best available means to expand it.
  # Returns    : 0 - failure, 1 - success
  # Parameters : S - archive - a bz2, gz, or tgz file to decompress</code></pre>

</dd>
<dt id="cwd_source_dir">cwd_source_dir</dt>
<dd>

<p>Changes the current working directory to the supplied one. Creates it if it does not exist. Tries to create the directory using perl&#39;s builtin mkdir, then the system mkdir, and finally the system mkdir with sudo.</p>

<pre><code>  ############ cwd_source_dir ###################
  # Usage      : $util-&gt;cwd_source_dir( &quot;/usr/local/src&quot; );
  # Purpose    : prepare a location to build source files in
  # Returns    : 0 - failure,  1 - success
  # Parameters : S - dir - a directory to build programs in</code></pre>

</dd>
<dt id="check_homedir_ownership">check_homedir_ownership</dt>
<dd>

<p>Checks the ownership on all home directories to see if they are owned by their respective users in /etc/password. Offers to repair the permissions on incorrectly owned directories. This is useful when someone that knows better does something like ...

<pre><code>  ######### check_homedir_ownership ############
  # Usage      : $util-&gt;check_homedir_ownership();
  # Purpose    : repair user homedir ownership
  # Returns    : 0 - failure,  1 - success
  # Parameters :
  #   Optional : I - auto - no prompts, just fix everything
  # See Also   : sysadmin</code></pre>

<p>Comments: Auto mode should be run with great caution. Run it first to see the results and then, if everything looks good, run in auto mode to do the actual repairs.</p>

</dd>
<dt id="chown_system">chown_system</dt>
<dd>

<p>The advantage this sub has over a Pure Perl implementation is that it can utilize sudo to gain elevated permissions that we might not otherwise have.</p>

<pre><code>  ############### chown_system #################
  # Usage      : $util-&gt;chown_system( dir=&gt;&quot;/tmp/example&quot;, user=&gt;&#39;matt&#39; );
  # Purpose    : change the ownership of a file or directory
  # Returns    : 0 - failure,  1 - success
  # Parameters : S - dir    - the directory to chown
  #            : S - user   - a system username
  #   Optional : S - group  - a sytem group name
  #            : I - recurse - include all files/folders in directory?
  # Comments   : Uses the system chown binary
  # See Also   : n/a</code></pre>

</dd>
<dt id="clean_tmp_dir">clean_tmp_dir</dt>
<dd>

<pre><code>  ############## clean_tmp_dir ################
  # Usage      : $util-&gt;clean_tmp_dir( $dir );
  # Purpose    : clean up old build stuff before rebuilding
  # Returns    : 0 - failure,  1 - success
  # Parameters : S - $dir - a directory or file.
  # Throws     : die on failure
  # Comments   : Running this will delete its contents. Be careful!</code></pre>

</dd>
<dt id="get_mounted_drives">get_mounted_drives</dt>
<dd>

<pre><code>  ############# get_mounted_drives ############
  # Usage      : my $mounts = $util-&gt;get_mounted_drives();
  # Purpose    : Uses mount to fetch a list of mounted drive/partitions
  # Returns    : a hashref of mounted slices and their mount points.</code></pre>

</dd>
<dt id="archive_file">archive_file</dt>
<dd>

<pre><code>  ############### archive_file #################
  # Purpose    : Make a backup copy of a file by copying the file to $file.timestamp.
  # Usage      : my $archived_file = $util-&gt;archive_file( $file );
  # Returns    : the filename of the backup file, or 0 on failure.
  # Parameters : S - file - the filname to be backed up
  # Comments   : none</code></pre>

</dd>
<dt id="chmod">chmod</dt>
<dd>

<p>Set the permissions (ugo-rwx) of a file. Will use the native perl methods (by default) but can also use system calls and prepend sudo if additional permissions are needed.</p>

<pre><code>  $util-&gt;chmod(
                file_or_dir =&gt; &#39;/etc/resolv.conf&#39;,
                mode =&gt; &#39;0755&#39;,
                sudo =&gt; $sudo
  )

 arguments required:
   file_or_dir - a file or directory to alter permission on
   mode   - the permissions (numeric)

 arguments optional:
   sudo  - the output of $util-&gt;sudo

 result:
   0 - failure
   1 - success</code></pre>

</dd>
<dt id="chown">chown</dt>
<dd>

<p>Set the ownership (user and group) of a file. Will use the native perl methods (by default) but can also use system calls and prepend sudo if additional permissions are needed.</p>

<pre><code>  $util-&gt;chown(
                file_or_dir =&gt; &#39;/etc/resolv.conf&#39;,
                uid =&gt; &#39;root&#39;,
                gid =&gt; &#39;wheel&#39;,
                sudo =&gt; 1
  );

 arguments required:
   file_or_dir - a file or directory to alter permission on
   uid   - the uid or user name
   gid   - the gid or group name

 arguments optional:
   file  - alias for file_or_dir
   dir   - alias for file_or_dir
   sudo  - the output of $util-&gt;sudo

 result:
   0 - failure
   1 - success</code></pre>

</dd>
<dt id="file_delete">file_delete</dt>
<dd>

<pre><code>  ############################################
  # Usage      : $util-&gt;file_delete( $file );
  # Purpose    : Deletes a file.
  # Returns    : 0 - failure, 1 - success
  # Parameters
  #   Required : file - a file path
  # Comments   : none
  # See Also   :

 Uses unlink if we have appropriate permissions, otherwise uses a system rm call, using sudo if it is not being run as root. This sub will try very hard to delete the file!</code></pre>

</dd>
<dt id="get_url">get_url</dt>
<dd>

<pre><code>   $util-&gt;get_url( $url, verbose=&gt;1 );</code></pre>

<p>Use the standard URL fetching utility (fetch, curl, wget) for your OS to download a file from the $url handed to us.</p>

<pre><code> arguments required:
   url - the fully qualified URL

 arguments optional:
   timeout - the maximum amount of time to try

 result:
   1 - success
   0 - failure</code></pre>

</dd>
<dt id="file_is_newer">file_is_newer</dt>
<dd>

<p>compares the mtime on two files to determine if one is newer than another.</p>

</dd>