NAME
Log::Shiras::Types - The Type::Tiny library for Log::Shiras
SYNOPSIS
#!perl
package Log::Shiras::Report::MyRole;
use Modern::Perl;#suggested
use Moose::Role;
use Log::Shiras::Types v0.013 qw(
ShirasFormat
JsonFile
);
has 'someattribute' =>(
isa => ShirasFormat,#Note the lack of quotes
);
sub valuetestmethod{
return is_JsonFile( 'my_file.jsn' );
}
no Moose::Role;
1;DESCRIPTION
This is the custom type class that ships with the Log::Shiras package.
There are only subtypes in this package! WARNING These types should be considered in a beta state. Future type fixing will be done with a set of tests in the test suit of this package. (currently few are implemented)
See MooseX::Types for general re-use of this module.
Types
PosInt
ElevenInt
ElevenArray
- Definition: an array with up to 12 total positions [0..11] This one goes to eleven
- Coercions: no coersion available
ShirasFormat
- Definition: this is the core of the Log::Shiras::Report::ShirasFormat module. When prepared the final 'ShirasFormat' definition is a hashref that contains three keys;
-
- final - a sprintf compliant format string
- alt_input - an arrayref of input definitions and positions for all the additional 'ShirasFormat' modifications allowed
- bump_list - a record of where and how many new inputs will be inserted in the passed data for formatting the sprintf compliant string
In order to simplify sprintf formatting I approached the sprintf definition as having the following sequence;
- Optional - Pre-string, any pre-string that would be printed as it stands (not interpolated)
- Required - %, this indicates the start of a formating definition
- Optional - Flags, any one or two of the following optional flag [\s\-\+0#] as defined in the sprintf documentation.
- Optional - Order of arguments, indicate some other position to obtain the formatted value.
- Optional - Vector flag, to treat each input character as a value in a vector then you use the vector flag with it's optional vector separator definition.
- Optional - Minimum field width, This defines the space taken for presenting the value
- Optional - Maximum field width, This defines the maximum length of the presented value. If maximum width is smaller than the minimum width then the value is truncatd to the maximum width and presented in the mimimum width space as defined by the flags.
- Required - Data type definition, This is done with an upper or lower case letter as described in the sprintf documentation. Only the letters defined in the sprintf documentation are supported. These letters close the sprintf documentation segment started with '%'.
The specific combination of these values is defined in the perldoc sprintf.
The module ShirasFormat expands on this definitions as follows;
- Word in braces {}, just prior to the "Data type definition" you can begin a sequence that starts with a word (no spaces) enclosed in braces. This word will be the name of the source data used in this format sequence.
- Source indicator qr/[MP]/, just after the "Word in braces {}" you must indicate where the code should look for this information. There are only two choices;
-
- P - a passed value in the message hash reference. The word in braces should be an exact match to a key in the message hashref. The core value used for this ShirasFormat segemnt will be the value assigned to that key.
- M - a method name to be discovered by the class. This method must exist at the time the format is set! When the Shiras format string is set the code will attempt to locate the method and save the location for calling this method to speed up implementation of ongoing formatting operations. If the method does not exist when the format string is set even if it will exist before data is passed for formatting then this call will fail. if you want to pass a closure (subroutine reference) then pass it as the value in the mesage hash part of the message ref and call it with 'P'.
- Code pairs in (), following the source indicator often the passed information is a code reference and for that code to be useful it needs to accept input. These code pairs are a way of implementing the code. The code pairs must be in intended use sequence. The convention is to write these in a fat comma list. There is no limit to code pairs quatities. There are three possible keys for these pairs;
-
- m this indicates a method call. If the code passed is actually an object with methods then this will call the value of this pair as a method on the code.
- i this indicates regular input to the method and input will be provided to a method using the value as follows;
-
$method( 'value' ) - l this indicates lvalue input to the method and input will be provided to a method using the value as follows;
-
$method->( 'value' ) - [value] Values to the methods can be provided in one of three ways. A string that will be sent to the method directly. An * to indicate that the method will consume the next value in the passed message array ref. Or an integer indicating how many of the elements of the passed messay array should be consumed. When elements of the passed message array are consumed they are consumed in order just like other sprintf elements.
When a special ShirasFormat segment is called the braces and the Source indicator are manditory. The code pairs are optional.
- Coercions: from a modified sprintf format string
TextFile
- Definition: a file name with a \.txt or \.csv extention that exists
- Coercions: no coersion available
HeaderString
- Definition: a string without any newlines
- Coercions: if coercions are turned on, newlines will be stripped (\n\r)
YamlFile
JsonFile
ArgsHash
- Definition: a hashref that has at least one of the following keys
-
name_space_bounds reports buffering ignored_caller_names will_cluck logging_levelsThis are the primary switchboard settings.
- Coersion from a "JsonFile" or "YamlFile" it will attempt to open the file and turn the file into a hashref that will pass the ArgsHash criteria
ReportObject
- Definition: an object that passes $object->can( 'add_line' )
- Coersion 1: from a hashref it will use MooseX::ShortCut::BuildInstance to build a report object if the necessary hashref is passed instead of an object
- Coersion 2: from a "JsonFile" or "YamlFile" it will attempt to open the file and turn the file into a hashref that can be used in "Coersion 1".
GLOBAL VARIABLES
- $ENV{hide_warn}
-
The module will warn when debug lines are 'Unhide'n. In the case where the you don't want these notifications set this environmental variable to true.
TODO
write a test suit for the types to fix behavior!
write a set of tests for combinations of %n and {string}M
SUPPORT
AUTHOR
COPYRIGHT
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
DEPENDANCIES
- Carp - confess
- version
- YAML::Any - ( Dump LoadFile )
- JSON::XS
- MooseX::Types
- MooseX::Types::Moose
- MooseX::ShortCut::BuildInstance - 1.044