Data-Validator-0.06 > Data::Validator
Data-Validator-0.06

名前

Data::Validator - Rule based validator on type constraint system

Data::Validator - ルールに基づいた型制約システム

VERSION

This document describes Data::Validator version 0.06.

このドキュメントは Data::Validatorバージョン 0.06について述べています.

概要

    use 5.10.0;
    use Data::Validator;

    # for functions
    sub get {
        state $rule = Data::Validator->new(
            uri        => { isa => 'Str', xor => [qw(schema host path_query)] },

            schema     => { isa => 'Str', default => 'http' },
            host       => { isa => 'Str' },
            path_query => { isa => 'Str', default => '/' },

            method     => { isa => 'Str', default => 'GET' },
        );

        my $args = $rule->validate(@_);
        # ...
    }
    get( uri => 'http://example.com/' );

    # for methods
    sub method {
        state $rule = Data::Validator->new(
            foo => 'Str',
        )->with('Method');

        my($self, $args) = $rule->validate(@_);
        # ...
    }
    Foo->method( foo => 'bar' );


    # using sequenced parameters
    sub seq {
        state $rule = Data::Validator->new(
            foo => 'Str',
        )->with('Sequenced');

        my $args = $rule->validate(@_);
        # ...
    }
    seq( 'bar' );          # seq() will get { foo => 'bar' }
    seq({ foo => 'bar' }); # named style are available!


    # using Method and Sequenced together
    sub seq_method {
        state $rule = Data::Validator->new(
            foo => 'Str',
        )->with( 'Method', 'Sequenced');

        my($self, $args) = $rule->validate(@_);
        # ...
    }
    Foo->seq_method( 'bar' ); # seq() will get { foo => 'bar' }
    use 5.10.0;
    use Data::Validator;

    # 関数の場合
    sub get {
        state $rule = Data::Validator->new(
            uri        => { isa => 'Str', xor => [qw(schema host path_query)] },

            schema     => { isa => 'Str', default => 'http' },
            host       => { isa => 'Str' },
            path_query => { isa => 'Str', default => '/' },

            method     => { isa => 'Str', default => 'GET' },
        );

        my $args = $rule->validate(@_);
        # ...
    }
    get( uri => 'http://example.com/' );

    # メソッドの場合
    sub method {
        state $rule = Data::Validator->new(
            foo => 'Str',
        )->with('Method');

        my($self, $args) = $rule->validate(@_);
        # ...
    }
    Foo->method( foo => 'bar' );


    # 引数をリストを使って渡す場合
    sub seq {
        state $rule = Data::Validator->new(
            foo => 'Str',
        )->with('Sequenced');

        my $args = $rule->validate(@_);
        # ...
    }
    seq( 'bar' );          # seq()は { foo => 'bar' }として受け取ることになります
    seq({ foo => 'bar' }); # 名前付きの方式も利用できます!


    # メソッドとリスト渡しを同時に使用する場合
    sub seq_method {
        state $rule = Data::Validator->new(
            foo => 'Str',
        )->with( 'Method', 'Sequenced');

        my($self, $args) = $rule->validate(@_);
        # ...
    }
    Foo->seq_method( 'bar' ); # seq() will get { foo => 'bar' }

説明

This is yet another validation library, based on Smart::Args but less smart.

This is under development. Any API will change without notice.

Concepts

Natural as Perl code

I love Smart::Args because it is really stylish, but it does not seem Perl-ish.

Thus, I have designed Data::Validator in more Perl-ish way with full of Smart::Args functionality.

Basics on type constraint system

Moose's type constraint system is awesome, and so is Mouse's. In fact, Mouse's type constraints are much faster than Moose's so that you need not hesitate to check types.

Thus, I have made Data::Validator on Mouse's type constraint system.

Pure Perl

Although I do not hesitate to depend on XS modules, some people think that XS modules are hard to install.

Thus, I have written Data::Validator in pure Perl and selected dependent modules which work in pure Perl.

Performance

Validators should be as fast as possible because they matter only for illegal inputs. Otherwise, one would want something like no validation option.

This is much faster than Params::Validate, which has an XS backend, though.

このモジュールは Smart::Argsに基づくバリデーションライブラリです. ただし少しばかり機能が劣っています.

このモジュールは開発段階です. <APIは予告なしに変更されるかもしれません>

Concepts

Perlらしいコード

私は洗練された Smart::Argsが大好きですが, Perlらしくないと思います.

そこで私は Smart::Argsの全機能を, より Perlらしく使える Data::Validatorを設計しました.

型制約システムの基本

Mooseの型制約システムは見事なものです. Mouseも同様です. 実のところ Mouseの型制約システムは Mooseのものより高速であるため, 型チェックを 行うことを躊躇する必要はありません.

そこで Data::Validatorは Mouse'sの型制約システムが利用するようにしました.

Pure Perl

私は XSモジュールの依存についてを遠慮しませんが, XSモジュールのインストールが 困難と考える人もいるでしょう.

そこで Data::Validatorを Pure Perlとしてコーディングし, Pure Purlとして 動作する場合の依存モジュールを選び出しました.

性能

バリデータは不正な入力を検出するだけなので, 可能な限り高速で高速であるべきです. そうでなければ, no validationオプションのようなものが欲しくなってしまうことでしょう.

このモジュールは XSバックエンドを持つ Params::Validateよりも高速です.

INTERFACE

Data::Validator->new( $arg_name => $rule [, ...]) :Validator

Creates a validation rule. You should cache the rules for performance.

Attributes for $rule are as follows:

isa => $type : Str|Object

The type of the rule, which can be a Mouse type constraint name, a class name, or a type constraint object of either Mouse or Moose (i.e. it's duck-typed).

does => $role : Str|Object

The type of the rule, which can be a Mouse type constraint name, a role name, or a type constraint object of either Mouse or Moose (i.e. it's duck-typed).

Note that you cannot use it with the isa attribute.

coerce => $should_coercion : Bool

If false, the rule does not try to coerce when the validation fails. Default to true.

default=> $value : Any | CodeRef

The default value for the argument. If it is a CODE reference, it is called in scalar context as $default->($validator, $rule, $args) and its return value is used as a default value.

Because arguments are validated in the order of definitions, default callbacks can rely on the previously-filled values:

    my $v = Data::Validator->new(
        foo => { default => 99 },
        bar => { default => sub {
            my($validator, $this_rule, $args) = @_;
            return $args->{foo} + 1;
        } },
    );
    $v->validate();          # bar is 100
    $v->validate(foo => 42); # bar is 43

Unlike Moose/Mouse's default, any references are allowed, but note that they are statically allocated.

optional => $value : Bool

If true, users can omit the argument. Default to false.

xor => $exclusives : ArrayRef

Exclusive arguments, which users cannot pass together.

documentation => $doc : Str

Descriptions of the argument.

This is not yet used anywhere.

$validator->find_rule($name :Str)

Finds the rule named $name. Provided for error handling.

$validator->with(@extentions) :Validator

Applies @extentions to $validator and returns itself.

See "EXTENTIONS" for details.

$validator->validate(@args) :HashRef

Validates @args and returns a restricted HASH reference.

Restricted hashes are hashes which do not allow to access non-existing keys, so you must check a key exists in the hash before fetching its values.

Data::Validator->new( $arg_name => $rule [, ...]) :Validator

バリデーションルールの生成. パフォーマンスを気にするのであればルールはキャッシュすべきです.

$ruleの属性は以下に示すとおりです.

isa => $type : Str|Object

ルールの型. Mouseの型制約名, クラス名, Mouseか Mooseいずれかの型制約オブジェクト (すなわちダックタイピング)を指定できます.

does => $role : Str|Object

ルールの型. Mouseの型制約名, ロール名, Mouseか Mooseいずれかの型制約オブジェクト (すなわちダックタイピング)を指定できます.

注意 isa属性と同時に使用することはできません.

coerce => $should_coercion : Bool

この属性に偽を指定した場合, バリデーションが失敗した場合に型変換を行いません. デフォルトは真です.

default=> $value : Any | CodeRef

引数のデフォルト値. コードリファレンスを指定した場合, $default->($validator, $rule, $args)を スカラコンテキストで呼び出し, その戻り値をデフォルト値として使用します.

なぜなら引数は定義された順番でバリデートされるので, defaultコールバックは 前で定義される値に依存します.

    my $v = Data::Validator->new(
        foo => { default => 99 },
        bar => { default => sub {
            my($validator, $this_rule, $args) = @_;
            return $args->{foo} + 1;
        } },
    );
    $v->validate();          # bar is 100
    $v->validate(foo => 42); # bar is 43

任意のリファレンスを許可する Moose/Mouseの defaultと異なります. それらは静的に割り当てられます.

optional => $value : Bool

真が設定された場合, ユーザはその引数を省略することができます. デフォルトは偽です.

xor => $exclusives : ArrayRef

同時に引き渡すことのできない, 排他的な引数を指定します.

documentation => $doc : Str

引数の説明.

どこでも使われていません.

$validator->find_rule($name :Str)

$nameと名付けられたルールを探します. エラー処理のために提供されます.

$validator->with(@extentions) :Validator

@extentions$validatorに適用し, 自分自身を返します.

"EXTENTIONS"の詳細を参照してください.

$validator->validate(@args) :HashRef

@argsをバリデートし, 制限されたハッシュリファレンスを返します.

制限されたハッシュは存在していないキーにアクセスすることが許可されていないので, 値を使う前に必ず existsでキーの存在を確認する必要があります.

EXTENTIONS

There are extentions which changes behaviours of validate().

Method

Takes the first argument as an invocant (i.e. class or object instance), and returns it as the first value:

    my($invocant, $args) = $rule->validate(@_);

Sequenced

Deals with arguments in sequenced style, where users should pass arguments by the order of argument rules, instead of by-name.

Note that if the last argument is a HASH reference, it is regarded as named-style arguments.

AllowExtra

Regards unknown arguments as extra arguments, and returns them as a list of name-value pairs:

    my($args, %extra) = $rule->validate(@_);

NoThrow

Does not throw errors. Instead, it provides validators with the errors attribute:

    my $args = $v->validate(@_); # it never throws errors
    if($v->has_errors) {
        my $errors = $v->clear_errors;
        foreach my $e(@{$errors}) {
            # $e has 'type', 'message' and 'name'
            print $e->{message}, "\n";
        }
    }

Croak

Does not report stack backtraces on errors, i.e. uses croak() instead of confess() to throw errors.

これらの拡張は validate()の挙動を変更します.

Method

第一引数にインボカントを渡し(すなわちクラスかインスタンス), 第一要素としてそれを返します.

    my($invocant, $args) = $rule->validate(@_);

Sequenced

ユーザに名前ではなく順序づいた引数を渡して欲しい場合に, 引数をリスト渡しスタイルとして扱います.

注記 最後の引数がハッシュリファレンスであれば, それは名前付き引数と して扱います.

AllowExtra

不明な引数を別の引数として扱い, 名前と値のペアのリストとしてそれらを 返します.

    my($args, %extra) = $rule->validate(@_);

NoThrow

例外を報告しません. 代わりに, バリデータに errors属性を提供しています.

    my $args = $v->validate(@_); # エラーが通知されることはありません
    if($v->has_errors) {
        my $errors = $v->clear_errors;
        foreach my $e(@{$errors}) {
            # $e has 'type', 'message' and 'name'
            print $e->{message}, "\n";
        }
    }

Croak

例外発生時 confess()の代わりに croak()を使い, エラー時にスタックのバックトレースをレポートしません.

DEPENDENCIES

Perl 5.8.1 or later.

バグ

All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT.

複雑なソフトウェアにはバグが潜んでおり, このモジュールも例外ではありません. バグを見つけた場合は, メールをしていただくか, CPAN-RTにバグを追加してください.

SEE ALSO

Smart::Args

Params::Validate

MooseX::Params::Validate

Mouse

作者

Fuji, Goro (gfx) <gfuji@cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2010, Fuji Goro (gfx). All rights reserved.

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