=pod

=encoding utf8

=head1 NAME

AN::Tut::Tools::Say

This module provides access to the translation methods.

=head1 SYNOPSIS

  use AN::Tut::Tools;

  # Get a common object handle on all AN::Tut::Tools::* modules.
  my $an=AN::Tut::Tools->new();

=head1 DESCRIPTION

This module provides methods that take arguments and variables from other module's methods and generates a string in a given language suitable for reading by the user.

=head1 NOTES

All AN::Tut::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.

=head1 METHODS

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

=head2 math

=head3 Example

  # Do a simple addition using '$an->Math->add()' so that there is something to
  # talk about.
  my $num1=10;
  my $num2=12;
  my $result=$an->Math->add($num1, $num2);
  
  # Now generate and print a string to show the user using the default
  # language.
  print $an->Say->math("add", $num1, $num2, $result), "\n";
  
  # This time, generate a French string.
  print $an->Say->math("add", $num1, $num2, $result, "fr"), "\n";
  
  # Now, generate a French string using a hash to pass in arguments.
  print $an->Say->math({
  	task	=>	"add",
  	num1	=>	$num1, 
  	num2	=>	$num2, 
  	result	=>	$result, 
  	lang	=>	"fr"
  }), "\n";

=head3 Details

This method takes arguments passed into and the resulting output from calls to C<AN::Tut::Tools::Math>'s C<add> and C<subtract> methods. It then produces a string suitable for reading by the user in either English (default) or French.

=head3 Arguments

This method can either take arguments as an array or via a hash reference. The former being shorter and easier to type, the latter allowing for a more self-documenting format.

When call as an array, arguments must be passed in the order: C<task>, C<num1>, C<num2>, C<result> and, optionally, C<lang>. When C<lang> is not specified, C<en> (English) is used.

When call using a hash reference the arguments need not be in any particular order. The arguments below are to be used:

=head4 C<task>

This is either C<add> or C<sub> with no default being set. This is used as a key to tell this method what string type to generate; "Addition" or "Subtraction".

=head4 C<num1>

This is the first number used in the equation being discussed.

=head4 C<num2>

This is the second number used in the equation being discussed.

=head4 C<result>

This is the resulting number generated by the equation.

=head4 C<lang>

Default: C<en>

This is the language code used to tell this method what language string to create. Valid arguments are:

=over

=item C<en>

English

=item C<fr>

French

=back

=head1 SEE ALSO

Other modules in the AN::Tut::Tools suite:

=over

=item AN::Tut::Tools

=item AN::Tut::Tools::Math

=back

=head1 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.

=cut