gitpan / class-value Goto Github PK

NAME
    Class::Value - Implements the Value Object Design Pattern

VERSION
    version 1.100840

SYNOPSIS
        Class::Value::Boolean->new("Y");      # ok
        Class::Value::Boolean->new("hoge");   # fails

DESCRIPTION
    This class, and other classes in its namespace, implement the Value
    Object Design Pattern. A value object encapsulates its value and adds
    semantic information. For example, an IPv4 address is not just a string
    of arbitrary characters. You can detect whether a given string is a
    well-formed IPv4 address and perform certain operations on it. Value
    objects provide a consistent interface to do this for all kinds of
    semantically-enhanced values.

METHODS
  value
    This is the method to use when getting or setting values. It includes
    the checks for well-formedness and validity. The values of $SkipChecks
    and $SkipNormalizations are respected.

    When skipping checks, we still try to normalize the value, unless told
    not to by $SkipNormalizations. If we can't normalize it, that is,
    "normalize_value()" returns "undef", we use the value we were given. We
    don't try to normalize an undefined value lest some overridden
    "normalize_value()" method checks via "assert_defined()".

    Skipping even normalization is useful if you want to purposefully set an
    denormalized value and later check whether "run_checks()" properly
    normalizes it.

    If you absolutely need to set an value that will not be validated, use
    "set_value()" for that. The value stored by "set_value()" could be
    anything - a scalar, array, hash, coderef, another object etc. Specific
    value objects could also accept various input and decode it into the
    underlying components.

    Consider, for example, a date value class that internally stores year,
    month and day components, for example using accessors generated by
    Class::Accessor::Complex. The public interface for the value object
    would still be "value()"; outside code never needs to know what's
    happening behind the scenes. However, outside code could call "year()",
    "month()" and "day()" on the value object and get at the components.

    The date value class would override "set_value()" to parse the input and
    split it into the components. It would also override
    "is_well_formed_value()" and/or "is_valid_value()" to do some checking.
    And it would override get_value to return the components joined up into
    a date string. Thus, "stringify()" would continue to work as expected.

  MUNGE_CONSTRUCTOR_ARGS
    This is called by the constructor before setting attributes with the
    constructor's arguments. If the number of arguments is an odd value, it
    prepends the word "value". This allows you to write:

        My::Class::Value->new('my_value');

    instead of having to write

        My::Class::Value->new(value => 'my_value');

  add
    This method is used as the overload handler for the "+" operation. It
    can be overridden in subclasses. In this base class it throws an
    Class::Value::Exception::UnsupportedOperation exception.

  atan2
    Like "add()" but affects the "atan2" operation.

  bit_and
    Like "add()" but affects the "&" operation.

  bit_not
    Like "add()" but affects the "~" operation.

  bit_or
    Like "add()" but affects the "|" operation.

  bit_shift_left
    Like "add()" but affects the "<<" operation.

  bit_shift_right
    Like "add()" but affects the ">>" operation.

  bit_xor
    Like "add()" but affects the "^" operation.

  check
    Takes the argument value, if given, or the object's currently set value
    and checks whether it is well-formed and valid.

  comparable
    As support for Data::Comparable, this method stringifies the value
    object. If no value is set, it returns the empty string.

  cos
    Like "add()" but affects the "cos" operation.

  divide
    Like "add()" but affects the "/" operation.

  exp
    Like "add()" but affects the "exp" operation.

  get_value
    Returns the value object's currently stored value.

  int
    Like "add()" but affects the "int" operation.

  is_defined
    Returns whether the currently stored value is defined. If there is no
    value set on the value object, it will return "undef".

  is_valid
    Takes the argument value, if given, or the object's currently set value
    and checks whether it is valid.

  is_valid_normalized_value
    Takes a normalized value as an argument and checks whether it is
    well-formed.

  is_valid_value
    Takes a value as an argument, normalizes it and checks whether the
    normalized value is valid. If normalization fails, that is, if it
    returns "undef", then this method will return 0. If the argument value -
    before normalization - is not defined, this method returns 1, because
    when no value has been set on the value object yet we don't want it to
    report an invalid value. If you need a different behaviour, subclass and
    override this method.

  is_well_formed
    Takes the argument value, if given, or the object's currently set value
    and checks whether it is well-formed.

  is_well_formed_value
    Takes an argument value and checks whether it is well-formed. In this
    base class, this method always returns 1.

  iterate
    Like "add()" but affects the "<>" operation.

  log
    Like "add()" but affects the "log" operation.

  modulo
    Like "add()" but affects the "%" operation.

  multiply
    Like "add()" but affects the "*" operation.

  normalize
    Takes an argument value and tries to normalize it. If the normalized
    value is different from the argument value, it sends out a notification
    by calling "send_notify_value_normalized()" - this will most likely be
    just informational. If normalization failed because "normalize_value()"
    returned "undef", a different notification is being sent using
    "send_notify_value_invalid()".

  normalize_value
    Takes an argument value and normalizes it. In this base class, the value
    is returned as is, but in subclasses you could customize this behaviour.
    For example, in a date-related value object you might accept various
    date input formats but normalize it to one specific format. Also see
    Class::Value::Boolean and its superclass Class::Value::Enum as an
    example.

    This method should just normalize the value and return "undef" if it
    can't do so. It should not send any notifications; they are handled by
    "normalize()".

  num_cmp
    Like "add()" but affects the "<=>" operation.

  power
    Like "add()" but affects the "**" operation.

  run_checks
    Takes the argument value, if given, or the object's currently set value
    and checks whether it is valid and well-formed. The value object's
    exception container is cleared before those checks so notification
    delegates can store exceptions in this container.

    If only one exception has been recorded and $ThrowSingleException is
    true then this individual exception will be thrown. Otherwise the whole
    exception container will be thrown.

  run_checks_with_exception_container
    Like "run_checks()", except that it takes as an additional first
    argument an exception container object. The exceptions accumulated
    during the checks are stored in this container. The container will not
    be thrown. This is useful if you have various value objects and you want
    to accumulate all exceptions in one big exception container.

    The value object's own exception container will be modified during the
    checks and cleared afterwards.

  send_notify_value_invalid
    Calls "notify_value_invalid()" on the notification delegate.

  send_notify_value_normalized
    Calls "notify_value_normalized()" on the notification delegate.

  send_notify_value_not_wellformed
    Calls "notify_value_not_wellformed()" on the notification delegate.

  set_value
    Directly sets the argument value on the value object without any checks.

  sin
    Like "add()" but affects the "sin" operation.

  skip_checks
    You can tell the value object to omit all checks that would be run
    during "value()". If this method is given an argument value, it will set
    the package-global $SkipChecks. If no argument is given, it will return
    the current value of $SkipChecks. Note that this is not a per-object
    setting.

    Temporarily skipping checks is useful if you want to set a series of
    value objects to values that might be invalid, for example when reading
    them from a data source such as a database or a configuration file, and
    later call "run_checks_with_exception_container()" on all of them.

    You can use

        Class::Value->skip_checks(1);

    to temporarily skip checks, but you have to remember to call

        Class::Value->skip_checks(0);

    afterwards. An alternative way would be to bypass this method:

        {
            local $Class::Value::SkipChecks = 1;
            ...
        }

  skip_normalizations
    Like "skip_checks()", but it affects the normalizations that would be
    done during "value()".

  sqrt
    Like "add()" but affects the "sqrt" operation.

  str_cmp
    Like "add()" but affects the "cmp" operation.

  stringify
    Like "add()" but affects the "" operation.

  subtract
    Like "add()" but affects the "-" operation.

  throw_single_exception
    Like "skip_checks()", but affects $ThrowSingleException.

INSTALLATION
    See perlmodinstall for information and options on installing Perl
    modules.

BUGS AND LIMITATIONS
    No bugs have been reported.

    Please report any bugs or feature requests through the web interface at
    <http://rt.cpan.org/Public/Dist/Display.html?Name=Class-Value>.

AVAILABILITY
    The latest version of this module is available from the Comprehensive
    Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a
    CPAN site near you, or see <http://search.cpan.org/dist/Class-Value/>.

    The development version lives at
    <http://github.com/hanekomu/Class-Value/>. Instead of sending patches,
    please fork this project using the standard git and github
    infrastructure.

AUTHOR
      Marcel Gruenauer <[email protected]>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2004 by Marcel Gruenauer.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.