MOJO::Guts

- NAME
- SYNOPSIS
- DESCRIPTION
- SUBROUTINES
- COPYRIGHT
- CONTACT INFO

# NAME

MOJO::Guts

# SYNOPSIS

            use MOJO::Guts;

This is the belly of the beast. Many functions of Mojo Mail are in here and they deal with all sorts of things that are above the breath of this synopsis.

# DESCRIPTION

This module will soon fade away and be cut up into a few other modules, hopefully sooner than later

All functions that delt with subscription/unsubscription from lists have been moved into the MOJO::List::* namespace

In the Future This module will be tentitively cut up into

            MOJO::CGI_Security
            MOJO::Settings or MOJO::List::Settings
            MOJO::Templates

plus a few other surprises

# SUBROUTINES

check_for_valid_email

              $e_test = check_for_valid_email($email_address);

  returns 1 if the email is invalid.

  But will return 0 if an email is invalid if you specify that addres in the @EMAIL_EXCEPTIONS array in the Config file. Good for testing.

strip

              my $str = strip($str);

      a simple subroutine to take off leading and trailing white spaces

pretty

              $str = pretty($str);

  a simple subroutine to turn underscores to whitespace

make_pin

              $pin = make_pin(-Email => $email);

  Returns a pin number to validate subscriptions

  You can change how the pin number is generated a few ways;

  There are two variables in the Config.pm file called the $PIN_WORD and the $PIN_NUM, they'll change the outcome of $pin, The algorithym to make a pin number isn't that sophisticated, I'm not trying to keep a nuclear submarine from launching its missles, although if you create your own $PIN_NUM and $PIN_WORD, it'll be pretty hard to decipher 6230 from justin@skazat.com

check_email_pin

              my $check = check_email_pin(-Email=>$email, -Pin=> $pin);

  checks a given e-mail with the given pin, returns 1 on success, 0 on failure.

available_archives

              my @archives = available_archives();

  s Pleae don't use this if you can help it

make_template

              make_template(-Path     => $path,
                            -List     => $list,
                            -Template => $template);

  takes where you want the template to be saved, the list that this template belongs to and the actual data to be saved in the template and saved this to a file. Usually, a template file is made when a list is created, using either the default Mojo Mail template, or if you specified a $DEFAULT_LIST in the Config.pm file, it'll use that template.

  Templates are stored in the $TEMPLATES directory (which is usually set the same as $FILES) under the name $listname.template, where $listname is the List's shortname.

delete_list_template

              delete_list_template(-Path => $path, -List => $list);

  deletes a template file for a list.

delete_list_archive

              delete_list_archive(-Path => $path, -List => $list);

      deletes the archive  file for a list.

delete_list_info

              delete_list_info(-Path => $path, -List => $list);

  deletes the db file for a list.

delete_email_list

              delete_email_list(-Path => $path, -List => $list);

  deletes the email list for a list.

check_if_list_exists

              check_if_list_exists(-List => $list, -Path => $path);

  checks to see if theres a filename called $list returns 1 for success, 0 for failure.

available_lists

              available_lists(-Path => $path);

  returns a @list of all Mojo lists available at $path

open_database

              my %list_info = open_database(-List => $list,
                                            -Path => $path,
                                            -Format=> $format);

  returns a hash that has all the saved list information, such as the list name, description, private policy statement, list administrator, list owner, various cusomizations

  the -Format flag is used to control how the information is given in the hash, you can set this to ``replaced'' and any psuendo tags that look like [this] will be changed to what the really are, example:

  [list_info] in the 'mailing_list_message' value will be changed to the description value. this is mostly for email message customization.

archive_message

              archive_message(
              -List    =>  $list,
              -Subject =>  $message_subject,
              -Body    =>  $message_body,
              -Id      =>  $message_id,
              -Format  =>  $archive_format
              );

  saves mass mailing messages in a db file the -Id flag should be made from the date, so when you go and make an index of all of em, they'll be in order.

  Again, don't use this, use Archive.pm, this is just hanging around for no real reason

setup_list

              setup_list(\%list_hash_ref);

  tTkes a hashref and changes information in the db file. this db file holds maost of the config information abut the list, such as the name of the list, the description, private policy, any mail messages cutomizations, email address, and even the password (in an encrypted form) returns 1 on sucess, 0 on failure, the failure could because the db file isn't writable, the directory is wrong, or who knows. Usually you just need to chmod 777 the directory your trying to write to or be sure its a directory that exists.

  the list_name is sent within the hashref, kinda like this:

              my %new_info = (
              list     => $list,
              password => $new_encrypt
              );

              my $status = setup_list(\%new_info);
              user_error("no_permissions_to_write") if $status == 0;

date_this

              my $readable_date =     date_this($packed_date)

  this takes a packed date, say, the key of an archive entry and transforms it into an html data. the date is packed as

  yyyymmdd

  where, yyyy is the year in this form: 2000 mm is the month in this form: 01 dd is the day in this for 31

  it returns something that looks like this:

              <i>Sent January 1st, 2001</i>

convert_to_ascii

              $string = convert_to_ascii($string);

  takes a string and dumbly strips out HTML tags,

uriescape

              $string = uriescape($string);

      use to escape strings to be used as url strings.

subscribe_form

              $form = subscribe_form($list);

  returns a html form for subscribin'

  Warning Will be moved into Widgets::* soon

make_safer

              $string = make_safer($string);

  This subroutine is used to make sure strings, such as list names, path to directories, critical stuff like that. This is in effort to make Mojo Mail able to run in 'Taint' Mode. If you need to run in taint mode, it may need still some tweakin.

urlify

              $string = urlify($string);

  This simple subbroutine wraps an <a href...> </a> around what it sees as links in a string. This is mostly to make links in plain text archived messages into live links.

interpolate_string

              $string = interpolate_string(-String => $string,
                                           -List_Db_Ref => \%list_info);

  This is used for psuedo tag interpolation, ie, changing [mojo_url] and friends into meaning full text.

check_list_setup
  `check_list_setup()` is used when creating and editing the core basic list information, like the list name, list password, list owner's email address and the list password. to check a new list, you'll want to do this:

       my ($list_errors,$flags) =
           check_list_setup(-fields => {list            => $list,
                                         mojo_email      => $mojo_email,
                                          password        => $password,
                                          retype_password => $retype_password,
                                          info            => $info,
                                          });

  Its a big boy. What's happening? this function returns two things, a reference to a hash with any errors it finds, and a scalar who's value is 1 or above if it finds any errors. here's a small reference to what $list_errors would return, all values in the hash ref will be one IF they are found to have something wrong in em:

  list - no list name was given list_exists - the list exists password - no password given retype_password - the second password was not given password_ne_retype_password - the first password didn't math the second slashes_in_name - slashes were found in the list name weird_characters - unprintable characters were found in the list name quotes - quotes were found in the list name invalid_mojo_email - the email address for the list owner is invlaid info - no list info was given.

  here's a better example on how to use this:

       my ($list_errors,$flags) =
       check_list_setup(-fields => {list            => $list,
                                      mojo_email      => $mojo_email,
                                      password        => $password,
                                      retype_password => $retype_password,
                                      info            => $info,
                                      });
              if($flags >= 1){
              print "your list name was never entered!" if $list_errors -> {list} == 1;
              }

  Now, if you want to check the setup of a list already created (editing a list) just set the -new_list flag to 'no', like this:

       my ($list_errors,$flags) =
       check_list_setup(-fields => {list            => $list,
                                      mojo_email      => $mojo_email,
                                      password        => $password,
                                      retype_password => $retype_password,
                                      info            => $info,
                                      },
                          -new_list => 'no'
                                      );

  This will stop checks on the list name (which is already set) and if the list exists (which, hopefully it does, since we're editing it)

check_admin_cgi_security

              my ($problems, $flags, $root_logged_in) =
               check_admin_cgi_security(-Admin_List     => $args{-Admin_List},
                                         -Admin_Password => $args{-Admin_Password},
                                         -Function       => $args{-Function},
                                         -IP_Address     => $ENV{REMOTE_ADDR});

  Checks the security for logins via the CGI interface to the list administration control panel

user_error
  deals with errors from a CGI interface

              user_error(-List => 'my_list',
                         -Error => 'some_error',
                         -Email => 'some@email.com');

check_admin_cgi_security
  sanity security check for the CGI interface

              my ($problems, $flags, $root_logged_in) =
                  check_admin_cgi_security(-Admin_List         => $args{-Admin_List},
                                       -Admin_Password => $args{-Admin_Password},
                                       -Function       => $args{-Function},
                                       -IP_Address     => $ENV{REMOTE_ADDR});

enforce_admin_cgi_security

              if($problems){
                      enforce_admin_cgi_security(-Admin_List     => $args{-Admin_List},
                                                 -Admin_Password => $args{-Admin_Password},
                                                 -Flags          => $flags);
              }

  shows the correct error message for list logins

make_all_list_files

              make_all_list_files(-List => $list);

  makes all the list files needed for a Mojo Mail list.

message_id
  returns an id, based on the date.

subscribe_link

              subscribe_link(
                      -url           => $MOJO_URL,
                      -email         => 'you@me.com',
                      -pin           => 1234,
                      -make_pin      => 0,
                      -list          => 'mylist',
                      -escape_list   => 1,
                      -escape_all    => 0);

      creates a subscription link

unsubscribe_link

              unsubscribe_link(
                      -url           => $MOJO_URL,
                      -email         => 'you@me.com',
                      -pin           => 1234,
                      -make_pin      => 0,
                      -list          => 'mylist',
                      -escape_list   => 1,
                      -escape_all    => 0);

  creates an unsubscription link

# COPYRIGHT

Copyright (c) 1999 - 2002 Justin Simoni (justin@skazat.com) http://skazat.com All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

# CONTACT INFO

Justin Simoni http://skazat.com justin\@skazat.com

A good place to start to get information is at:

http://mojo.skazat.com