Difference between revisions of "POD AN::Tools"

From AN!Wiki
Jump to: navigation, search
 
(4 intermediate revisions by one user not shown)
Line 1: Line 1:
 
{{mod_header}}
 
{{mod_header}}
 +
 +
'''[https://alteeve.ca/AN/Tools.pod Tools.pod]'''
  
 
==NAME==
 
==NAME==
Line 7: Line 9:
  
 
==SYNOPSIS==
 
==SYNOPSIS==
<code>
+
<source lang="perl">
 
   use AN::Tools;
 
   use AN::Tools;
 
   
 
   
Line 20: Line 22:
 
         },
 
         },
 
   });
 
   });
</code>
+
</source>
 
==DESCRIPTION==
 
==DESCRIPTION==
This module provides access to all the AN::Tools::* modules' methods. For details on what methods each module provides, please see their respective perldocs or visit the AN::Tools webite, https://alteeve.com.
+
This module provides access to all the AN::Tools::* modules' methods. For details on what methods each module provides, please see their respective perldocs or visit the AN::Tools webite, https://alteeve.ca.
  
Some modules can be passed load-time values to alter how the AN::Tools suite starts. Where this is the case, you can pass a hash reference where the key structure is '$hashref{module_name}{method_name}=arg' or, when a method takes several parameters, '$hashref{module_name}{method_name}{arg_name}=arg'.
+
Some modules can be passed load-time values to alter how the AN::Tools suite starts. Where this is the case, you can pass a hash reference where the key structure is '$hashref->{module_name}{method_name}=arg' or, when a method takes several parameters, '$hashref->{module_name}{method_name}{arg_name}=arg'.
  
 
Currently supported load-time arguments:
 
Currently supported load-time arguments:
Line 39: Line 41:
 
===new===
 
===new===
 
====Example====
 
====Example====
<code>
+
<source lang="perl">
 
   use AN::Tools;
 
   use AN::Tools;
 
   
 
   
Line 52: Line 54:
 
   # The format is always:
 
   # The format is always:
 
   #$an->Module->Method(<parameters>);
 
   #$an->Module->Method(<parameters>);
</code>
+
</source>
 
====Details====
 
====Details====
 
This is the constructor method used to access this object's handle on the various AN::Tools::* objects. It also provides access to the methods provided by these modules as seen in the example above. Access to each module's methods is formatted this way to make the resulting code clearer and somewhat self-documenting. This access method cannot be (safely) circumvented as AN::Tools does not use <tt>@ISA</tt> to access the child (sibling) module's methods nor do the other methods <tt>Export</tt> their methods. Attempting to directly access the child modules will fail as they require access to one another and expect to be able to do this via the <tt>AN::Tools</tt> module.
 
This is the constructor method used to access this object's handle on the various AN::Tools::* objects. It also provides access to the methods provided by these modules as seen in the example above. Access to each module's methods is formatted this way to make the resulting code clearer and somewhat self-documenting. This access method cannot be (safely) circumvented as AN::Tools does not use <tt>@ISA</tt> to access the child (sibling) module's methods nor do the other methods <tt>Export</tt> their methods. Attempting to directly access the child modules will fail as they require access to one another and expect to be able to do this via the <tt>AN::Tools</tt> module.
Line 64: Line 66:
 
===error===
 
===error===
 
====Example====
 
====Example====
<code>
+
<source lang="perl">
 
   # See if an error state exists.
 
   # See if an error state exists.
 
   die "AN::Tools failed on the last call. Error was: ".$an->error if $an->error;
 
   die "AN::Tools failed on the last call. Error was: ".$an->error if $an->error;
</code>
+
</source>
 
====Details====
 
====Details====
 
This method takes no arguments. It simply returns the last error if set, otherwise it returns undef. This method only has use if '$an->Alert->no_fatal_errors' has been set to '1'. Otherwise the method call with an error would have died before returning.
 
This method takes no arguments. It simply returns the last error if set, otherwise it returns undef. This method only has use if '$an->Alert->no_fatal_errors' has been set to '1'. Otherwise the method call with an error would have died before returning.
Line 76: Line 78:
 
===<tt>Alert</tt>===
 
===<tt>Alert</tt>===
 
====Example====
 
====Example====
<code>
+
<source lang="perl">
 
   # Access the example 'foo' method.
 
   # Access the example 'foo' method.
 
   $an->Alert->foo.
 
   $an->Alert->foo.
 
    
 
    
</code>
+
</source>
 
====Details====
 
====Details====
 
The <tt>AN::Tools::Alert</tt> module handles warnings and errors.
 
The <tt>AN::Tools::Alert</tt> module handles warnings and errors.
Line 90: Line 92:
 
===<tt>Math</tt>===
 
===<tt>Math</tt>===
 
====Example====
 
====Example====
<code>
+
<source lang="perl">
 
   # Access the example 'foo' method.
 
   # Access the example 'foo' method.
 
   $an->Math->foo.
 
   $an->Math->foo.
 
    
 
    
</code>
+
</source>
 
====Details====
 
====Details====
 
The <tt>AN::Tools::Math</tt> method handles mathmatical operations.
 
The <tt>AN::Tools::Math</tt> method handles mathmatical operations.
Line 104: Line 106:
 
===<tt>Readable</tt>===
 
===<tt>Readable</tt>===
 
====Example====
 
====Example====
<code>
+
<source lang="perl">
 
   # Access the example 'foo' method.
 
   # Access the example 'foo' method.
 
   $an->Readable->foo.
 
   $an->Readable->foo.
 
    
 
    
</code>
+
</source>
 
====Details====
 
====Details====
 
The <tt>AN::Tools::Readable</tt> method handles converting large bits of data, generally numbers, sizes and UNIX timestamps, between more human readable formats and back
 
The <tt>AN::Tools::Readable</tt> method handles converting large bits of data, generally numbers, sizes and UNIX timestamps, between more human readable formats and back
Line 118: Line 120:
 
===<tt>data</tt>===
 
===<tt>data</tt>===
 
====Example====
 
====Example====
<code>
+
<source lang="perl">
 
   # Get a handle on AN::Tool's internal data store.
 
   # Get a handle on AN::Tool's internal data store.
 
   my $data=$an->data;
 
   my $data=$an->data;
</code>
+
</source>
 
====Details====
 
====Details====
 
All AN::Tools modules store their data in a common, user-accessible hash reference. This allows easy access to variables read in from configuration files, a given language's word strings and so forth.
 
All AN::Tools modules store their data in a common, user-accessible hash reference. This allows easy access to variables read in from configuration files, a given language's word strings and so forth.
Line 142: Line 144:
 
Other modules in the AN::Tools suite:
 
Other modules in the AN::Tools suite:
  
; AN&#58;&#58;Tools&#58;&#58;Alert; AN&#58;&#58;Tools&#58;&#58;Math; AN&#58;&#58;Tools&#58;&#58;Readable; AN&#58;&#58;Tools&#58;&#58;String
+
AN&#58;&#58;Tools&#58;&#58;Alert
 +
AN&#58;&#58;Tools&#58;&#58;Math
 +
AN&#58;&#58;Tools&#58;&#58;Readable
 +
AN&#58;&#58;Tools&#58;&#58;String
 +
 
 
==LICENSE==
 
==LICENSE==
 
<code>
 
<code>

Latest revision as of 03:20, 5 May 2013

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

Tools.pod

Contents

[edit] NAME

AN::Tools

Serves only to load all other AN::Tools::* modules in a common object and provide shortcuts to their methods.

[edit] SYNOPSIS

  use AN::Tools;
 
  # Get a common object handle on all AN::Tools::* modules.
  my $an=AN::Tools->new();
 
  # Again, but this time tell the AN::Tools::String module to force the use of
  # UTF-8 mode when reading it's built-in XML words file.
  my $an=AN::Tools->new({
        String  =>      {
                force_utf8      =>      1,
        },
  });

[edit] DESCRIPTION

This module provides access to all the AN::Tools::* modules' methods. For details on what methods each module provides, please see their respective perldocs or visit the AN::Tools webite, https://alteeve.ca.

Some modules can be passed load-time values to alter how the AN::Tools suite starts. Where this is the case, you can pass a hash reference where the key structure is '$hashref->{module_name}{method_name}=arg' or, when a method takes several parameters, '$hashref->{module_name}{method_name}{arg_name}=arg'.

Currently supported load-time arguments:

String
To tell AN::Tools to force the use of UTF-8 mode when reading it's internal XML words file. The format is: {String}{force_utf8}=[0|1].

[edit] 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.

[edit] METHODS

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

[edit] new

[edit] Example

  use AN::Tools;
 
  # Get a handle on the MB::Tools object.
  my $an=AN::Tools->new;
 
  # With the handle to this module's object, you access the rest of the
  # AN::Tools::* suite of modules by calling them by their method name. For
  # example, to access AN::Tools::Math's 'round' method, call it like this:
  $an->Math->round({number=>30.33754, places=>2});
 
  # The format is always:
  #$an->Module->Method(<parameters>);

[edit] Details

This is the constructor method used to access this object's handle on the various AN::Tools::* objects. It also provides access to the methods provided by these modules as seen in the example above. Access to each module's methods is formatted this way to make the resulting code clearer and somewhat self-documenting. This access method cannot be (safely) circumvented as AN::Tools does not use @ISA to access the child (sibling) module's methods nor do the other methods Export their methods. Attempting to directly access the child modules will fail as they require access to one another and expect to be able to do this via the AN::Tools module.

The current supported modules are:

  • AN::Tools::Alert
  • AN::Tools::Math
  • AN::Tools::Readable

[edit] error

[edit] Example

  # See if an error state exists.
  die "AN::Tools failed on the last call. Error was: ".$an->error if $an->error;

[edit] Details

This method takes no arguments. It simply returns the last error if set, otherwise it returns undef. This method only has use if '$an->Alert->no_fatal_errors' has been set to '1'. Otherwise the method call with an error would have died before returning.

[edit] Child Module Access

In traditional perl parlance, these modules are siblings of this module. However, it makes a bit more sense to think of them as child objects because of how access is structured.

[edit] Alert

[edit] Example

  # Access the example 'foo' method.
  $an->Alert->foo.

[edit] Details

The AN::Tools::Alert module handles warnings and errors.

Please read this modules POD documentation using your favourite POD reader. The most common one at the command shell being perldoc.

perldoc AN::Tools::Alert

[edit] Math

[edit] Example

  # Access the example 'foo' method.
  $an->Math->foo.

[edit] Details

The AN::Tools::Math method handles mathmatical operations.

Please read this modules POD documentation using your favourite POD reader. The most common one at the command shell being perldoc.

perldoc AN::Tools::Math

[edit] Readable

[edit] Example

  # Access the example 'foo' method.
  $an->Readable->foo.

[edit] Details

The AN::Tools::Readable method handles converting large bits of data, generally numbers, sizes and UNIX timestamps, between more human readable formats and back

Please read this modules POD documentation using your favourite POD reader. The most common one at the command shell being perldoc.

perldoc AN::Tools::Readable

[edit] data

[edit] Example

  # Get a handle on AN::Tool's internal data store.
  my $data=$an->data;

[edit] Details

All AN::Tools modules store their data in a common, user-accessible hash reference. This allows easy access to variables read in from configuration files, a given language's word strings and so forth.

For example, say that your configuration file had the variable-value pair:

foo::bar = baz

You could see the value read for foo::bar by:

print "The value of 'foo::bar' is: [$data->{foo}{bar}]\n"; # prints "The value of 'foo::bar' is: [baz]";

Another example, though not realistic, would be to access the word string 'an_0000' in the language 'en_CA':

my $word=$an->data()->{words}{lang}{en_CA}{key}{an_0000}{content}; print "Word: [$word].\n"; # prints "Word: [AN::Tools rapid development suite.]."

Realistically though, you'll probably want to access strings via 'AN::Tools::String's 'get_word()' method.

[edit] SEE ALSO

Other modules in the AN::Tools suite:

AN::Tools::Alert
AN::Tools::Math
AN::Tools::Readable
AN::Tools::String

[edit] 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.
Us: Alteeve's Niche! Support: Mailing List IRC: #clusterlabs on Freenode   © Alteeve's Niche! Inc. 1997-2019
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.
Personal tools
Namespaces

Variants
Actions
Navigation
projects
Toolbox