POD AN::Tools::Alert: Difference between revisions

From Alteeve Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{mod_header}}
{{mod_header}}
'''[https://alteeve.ca/AN/Tools/Alert.pod Alert.pod]'''


==NAME==
==NAME==
AN::Tools::Math
AN::Tools::Alert


This module provides access to the mathmatical and other number-type methods in the AN::Tools suite. Please see each method's sections below.
This module provides access to the mathmatical and other number-type methods in the AN::Tools suite. Please see each method's sections below.


==SYNOPSIS==
==SYNOPSIS==
<code>
<source lang="perl">
   use AN::Tools;
   use AN::Tools;
   
   
Line 13: Line 15:
   my $an=AN::Tools->new();
   my $an=AN::Tools->new();
    
    
   # Access this module's methods using '$an->Math->method()' syntax.
   # Trigger a fatal error.
   my $rounded=$an->Math->round({
   $an->Alert->error({
           number        =>      10.245,
        fatal           =>      1,
           places        =>      2
        title           =>      "Something went boom",
        message        =>      "Details on what went boom",
        code            =>      <some integer representing what went boom>,
        file            =>      "$THIS_FILE",
        line            =>      __LINE__
   });
   });
  print "Rounded: [$rounded]\n";        # Prints "Rounded: [10.25]"
</source>
</code>
==DESCRIPTION==
==DESCRIPTION==
This is the mathmatical (and general number-based methods) module in the AN::Tools suite. Please do not directly access it, but instead access it's methods via the parent AN::Tools module. The methods provided by this method are described below.
This is the error handling module. It provides support for all the possible ways that AN::Tools could fail.


==NOTES==
==NOTES==
Line 31: Line 36:
===no_fatal_errors===
===no_fatal_errors===
====Example====
====Example====
<code>
<source lang="perl">
   # Set otherwise fatal errors to not die but instead return the error to the
   # Set otherwise fatal errors to not die but instead return the error to the
   # caller.
   # caller.
Line 48: Line 53:
   # Make fatal errors actually fatal again (this is the default).
   # Make fatal errors actually fatal again (this is the default).
   $an->Alert->no_fatal_errors({set => 0});
   $an->Alert->no_fatal_errors({set => 0});
</code>
</source>
====Details====
====Details====
This either checks if AN::Tools errors are fatal (will terminate the running program) or instead set their internal error strings (see below). By default, errors are fatal.
This either checks if AN::Tools errors are fatal (will terminate the running program) or instead set their internal error strings (see below). By default, errors are fatal.
Line 58: Line 63:
===error===
===error===
====Example====
====Example====
<code>
<source lang="perl">
   # Calling this method triggers an error event.
   # Calling this method triggers an error event.
   $an->Alert->error({
   $an->Alert->error({
Line 71: Line 76:
   # The alternative, short-form of calling this method is:
   # The alternative, short-form of calling this method is:
   $an->Alert->error(1, "Something went boom", "Details on what went boom", <some integer representing what went boom>, "$THIS_FILE", __LINE__);
   $an->Alert->error(1, "Something went boom", "Details on what went boom", <some integer representing what went boom>, "$THIS_FILE", __LINE__);
</code>
</source>
====Details====
====Details====
This method handles errors via the module. It actually expects the 'title' and 'message' to be word keys, but that isn't built yet (Madi!). When it does, it will also accept the usual 'title_var' and 'message_var' array references.
This method handles errors via the module. It actually expects the 'title' and 'message' to be word keys, but that isn't built yet (Madi!). When it does, it will also accept the usual 'title_var' and 'message_var' array references.

Latest revision as of 03:59, 5 May 2013

 AN!Tools :: AN::Tools :: POD AN::Tools::Alert

Alert.pod

NAME

AN::Tools::Alert

This module provides access to the mathmatical and other number-type methods in the AN::Tools suite. Please see each method's sections below.

SYNOPSIS

  use AN::Tools;
 
  # Get a common object handle on all AN::Tools::* modules.
  my $an=AN::Tools->new();
  
  # Trigger a fatal error.
  $an->Alert->error({
        fatal           =>      1,
        title           =>      "Something went boom",
        message         =>      "Details on what went boom",
        code            =>      <some integer representing what went boom>,
        file            =>      "$THIS_FILE",
        line            =>      __LINE__
  });

DESCRIPTION

This is the error handling module. It provides support for all the possible ways that AN::Tools could fail.

NOTES

All AN::Tools::* modules expects the data they receive to be in UTF-8 encoded format. Likewise, they return UTF-8 encoded strings. If you are getting weird output or are seeing a "wide character in print" error, check that you are not getting double-encoded UTF-8 strings by casting your data as UTF-8 in the first place.

METHODS

Below are the detailed usage instructions for the methods provided by this module.

no_fatal_errors

Example

  # Set otherwise fatal errors to not die but instead return the error to the
  # caller.
  $an->Alert->no_fatal_errors({set => 1});
  
  # Check if fatal errors are actually fatal.
  if ($an->Alert->no_fatal_errors)
  {
          print "AN::Tools errors are fatal.\n";
  }
  else
  {
          print "AN::Tools errors are no longer fatal.\n";
  }
  
  # Make fatal errors actually fatal again (this is the default).
  $an->Alert->no_fatal_errors({set => 0});

Details

This either checks if AN::Tools errors are fatal (will terminate the running program) or instead set their internal error strings (see below). By default, errors are fatal.

When called with no arguments, this method will return 1 or 0 depending on whether errors are fatal or not, respectively. The only parameter this method takes is 'set' with a value or '1' or '0'. Any other value is simply ignored.

If set to 1, modules that would have died will set '$an->error' in much the same way that you can check for an error in 'eval' by seeing if the special variable '$@' is set.

error

Example

  # Calling this method triggers an error event.
  $an->Alert->error({
        fatal           =>      1,
        title           =>      "Something went boom",
        message         =>      "Details on what went boom",
        code            =>      <some integer representing what went boom>,
        file            =>      "$THIS_FILE",
        line            =>      __LINE__
  });
  
  # The alternative, short-form of calling this method is:
  $an->Alert->error(1, "Something went boom", "Details on what went boom", <some integer representing what went boom>, "$THIS_FILE", __LINE__);

Details

This method handles errors via the module. It actually expects the 'title' and 'message' to be word keys, but that isn't built yet (Madi!). When it does, it will also accept the usual 'title_var' and 'message_var' array references.

This method takes several parameters.

Parameters

fatal

default: 1

if 'no_fatal_errors' was set, this parameter is ignored, the error that would have been printed is set in '$an->error' and the method returns undef.

If set to 1, an error string will be built using the other parameters and then be printed to STDOUT and the method terminate the calling program.

If set to 0, the error will simply print to the error message to STDOUT and return undef.

AN::Tools ERROR CODES

Below are the list of AN::Tools numeric error codes and their English description.

0

No Error, successful exit.

1

Generic or unknown error.

2

Non-integer value passed to the 'AN::Tools::Math->round' method. Only digits and one decimal are allowed in the string to be rounded. Commas may be passed but they will be stripped out in the returned string.

3

A value other that 0 or 1 was passed into the 'AN::Readable::Readable' module's 'base2' method.

4

Invalid argument passed into the 'AN::Tools::Readable' module's 'comma' method. Specifically, the argument contained a non-digit character or too many decimals.

5

Invalid argument passed into the 'AN::Tools::Readable' module's 'time' method. Specifically, the argument contained a non-digit character or too many decimals. Commas may have been in the string and they would not trigger this error as they are removed prior to calculation.

6

Invalid argument passed into the 'AN::Tools::Readable' module's 'bytes_to_hr' method. Specifically, the byte size was not a signed integer. Commas are allowed and are removed by the method prior to calculations. Any other non-digit character will trigger this error.

7

Invalid argument passed into the 'AN::Tools::Readable' module's 'hr_to_bytes' method. Specifically, the byte size was not a signed integer or real number. Commas are allowed and are removed by the method prior to calculations. Any other non-digit character will trigger this error.

8

Invalid argument passed into the 'AN::Tools::Readable' module's 'hr_to_bytes' method. Specifically, the size appears to already be in bytes but the size was not a signed integer. Commas are allowed and are removed by the method prior to calculations. Any other non-digit character will trigger this error.

9

The 'AN::Tools' module tried to load the 'Math::BigInt' module but it failed to load or was not found. This module is needed when dealing with very large number and is only loaded when needed. Please install this module using your operating system's package manager or via CPAN.

10

The 'AN::Tools::Readable' module's 'hr_to_bytes' method was not able to parse a valid size type. Either an invalid size type was passed or the method failed to properly parse the size type. Valid size types are: 'b', 'k', 'm', 'g', 't', 'p', 'e', 'z' or 'y'.

11

The 'AN::Tools::String' module's 'read_words' method was not able to find the specified words file. This was either the passed words file or the default words file 'tools.xml' in the root directory of the module if none was specified.

12

The 'AN::Tools::String' module's 'read_words' method was not able to read the specified words file. Please check the permissions on the words file.

13

The 'AN::Tools' module tried to load the 'IO::Handle' module but it failed to load or was not found. This module is needed when reading from or writing to files on disk. Please install this module using your operating system's package manager or via CPAN.

14

The 'AN::Tools::String' module's 'force_utf8' method was passed an invalid argument. Only 1 and 0 are valid arguments.

15

The 'AN::Tools::String' module's 'get_string' method was passed an invalid 'hash' argument. This must be a hash reference containing data read in from an XML words file by the 'read_words()' method.

16

The 'AN::Tools::String' module's 'get_string' method was passed an invalid 'vars' argument. This must be an array reference containing elements intended to replace corresponding #!var!x!# replacement keys in the requested string.

17

The 'AN::Tools::String' module's 'get_string' method was passed an invalid 'language' argument. This must match one of the languages in the words file's <langs>...</langs> block.

18

The 'AN::Tools::String' module's 'get_string' method was passed a 'key' argument not found in the active language. This key must be defined in one of the read in words files.

SEE ALSO

Other modules in the AN::Tools suite:

AN::Tools; AN::Tools::Math; AN::Tools::Readable; AN::Tools::String

LICENSE

Copyright (c) 2009 Alteeve's Niche!. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

 

Any questions, feedback, advice, complaints or meanderings are welcome.
Alteeve's Niche! Enterprise Support:
Alteeve Support
Community Support
© Alteeve's Niche! Inc. 1997-2024   Anvil! "Intelligent Availability®" Platform
legal stuff: All info is provided "As-Is". Do not use anything here unless you are willing and able to take responsibility for your own actions.