The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Log-Shiras-v0.48.0
River stage one • 1 direct dependent • 1 total dependent
/ Log::Shiras::Types

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

Definition: all integers equal to or greater than 0
Coercions: no coersion available

ElevenInt

Definition: any posInt less than 11
Coercions: no coersion available

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

Definition: a file name with a qr/(\.yml|\.yaml)/ extention that exists
Coercions: none

JsonFile

Definition: a file name with a qr/(\.jsn|\.json)/ extention that exists
Coercions: none

ArgsHash

Definition: a hashref that has at least one of the following keys
        name_space_bounds
        reports
        buffering
        ignored_caller_names
        will_cluck
        logging_levels

This 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

Github Log-Shiras/issues

AUTHOR

Jed Lund
jandrew@cpan.org

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

SEE ALSO

Type::Tiny