{"id":20596918,"url":"https://github.com/petdance/carp-assert-more","last_synced_at":"2025-07-14T02:33:08.275Z","repository":{"id":5294087,"uuid":"6474854","full_name":"petdance/carp-assert-more","owner":"petdance","description":"Carp::Assert::More, handy assertion functions for Perl","archived":false,"fork":false,"pushed_at":"2025-03-06T04:33:18.000Z","size":111,"stargazers_count":2,"open_issues_count":3,"forks_count":4,"subscribers_count":2,"default_branch":"dev","last_synced_at":"2025-04-14T23:52:21.086Z","etag":null,"topics":["assertions","hacktoberfest","perl","perl5"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/petdance.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-10-31T14:05:08.000Z","updated_at":"2025-03-06T04:32:52.000Z","dependencies_parsed_at":"2024-03-10T05:21:00.461Z","dependency_job_id":"d38e96f2-fdfd-4e3b-b42c-1a3f8d420ab6","html_url":"https://github.com/petdance/carp-assert-more","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/petdance/carp-assert-more","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petdance%2Fcarp-assert-more","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petdance%2Fcarp-assert-more/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petdance%2Fcarp-assert-more/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petdance%2Fcarp-assert-more/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/petdance","download_url":"https://codeload.github.com/petdance/carp-assert-more/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petdance%2Fcarp-assert-more/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265233753,"owners_count":23731825,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assertions","hacktoberfest","perl","perl5"],"created_at":"2024-11-16T08:19:27.082Z","updated_at":"2025-07-14T02:33:08.253Z","avatar_url":"https://github.com/petdance.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Carp::Assert::More\n\n[![Build Status](https://github.com/petdance/carp-assert-more/workflows/testsuite/badge.svg?branch=dev)](https://github.com/petdance/carp-assert-more/actions?query=workflow%3Atestsuite+branch%3Adev)\n\n# NAME\n\nCarp::Assert::More - Convenience assertions for common situations\n\n# VERSION\n\nVersion 2.8.0\n\n# SYNOPSIS\n\nA set of convenience functions for common assertions.\n\n    use Carp::Assert::More;\n\n    my $obj = My::Object;\n    assert_isa( $obj, 'My::Object', 'Got back a correct object' );\n\n# DESCRIPTION\n\nCarp::Assert::More is a convenient set of assertions to make the habit\nof writing assertions even easier.\n\nEverything in here is effectively syntactic sugar.  There's no technical\ndifference between calling one of these functions:\n\n    assert_datetime( $foo );\n    assert_isa( $foo, 'DateTime' );\n\nthat are provided by Carp::Assert::More and calling these assertions\nfrom Carp::Assert\n\n    assert( defined $foo );\n    assert( ref($foo) eq 'DateTime' );\n\nMy intent here is to make common assertions easy so that we as programmers\nhave no excuse to not use them.\n\n# SIMPLE ASSERTIONS\n\n## assert( $condition \\[, $name\\] )\n\nAsserts that `$condition` is a true value.  This is the same as `assert`\nin `Carp::Assert`, provided as a convenience.\n\n## assert\\_is( $string, $match \\[,$name\\] )\n\nAsserts that _$string_ is the same string value as _$match_.\n\n`undef` is not converted to an empty string. If both strings are\n`undef`, they match. If only one string is `undef`, they don't match.\n\n## assert\\_isnt( $string, $unmatch \\[,$name\\] )\n\nAsserts that _$string_ does NOT have the same string value as _$unmatch_.\n\n`undef` is not converted to an empty string.\n\n## assert\\_cmp( $x, $op, $y \\[,$name\\] )\n\nAsserts that the relation `$x $op $y` is true. It lets you know why\nthe comparsison failed, rather than simply that it did fail, by giving\nbetter diagnostics than a plain `assert()`, as well as showing the\noperands in the stacktrace.\n\nPlain `assert()`:\n\n    assert( $nitems \u003c= 10, 'Ten items or fewer in the express lane' );\n\n    Assertion (Ten items or fewer in the express lane) failed!\n    Carp::Assert::assert(\"\", \"Ten items or fewer in the express lane\") called at foo.pl line 12\n\nWith `assert_cmp()`:\n\n    assert_cmp( $nitems, '\u003c=', 10, 'Ten items or fewer in the express lane' );\n\n    Assertion (Ten items or fewer in the express lane) failed!\n    Failed: 14 \u003c= 10\n    Carp::Assert::More::assert_cmp(14, \"\u003c=\", 10, \"Ten items or fewer in the express lane\") called at foo.pl line 11\n\nThe following operators are supported:\n\n- == numeric equal\n- != numeric not equal\n- \u003e numeric greater than\n- \u003e= numeric greater than or equal\n- \u003c numeric less than\n- \u003c= numeric less than or equal\n- lt string less than\n- le string less than or equal\n- gt string less than\n- ge string less than or equal\n\nThere is no support for `eq` or `ne` because those already have\n`assert_is` and `assert_isnt`, respectively.\n\nIf either `$x` or `$y` is undef, the assertion will fail.\n\nIf the operator is numeric, and `$x` or `$y` are not numbers, the assertion will fail.\n\n## assert\\_like( $string, qr/regex/ \\[,$name\\] )\n\nAsserts that _$string_ matches _qr/regex/_.\n\nThe assertion fails either the string or the regex are undef.\n\n## assert\\_unlike( $string, qr/regex/ \\[,$name\\] )\n\nAsserts that _$string_ matches _qr/regex/_.\n\nThe assertion fails if the regex is undef.\n\n## assert\\_defined( $this \\[, $name\\] )\n\nAsserts that _$this_ is defined.\n\n## assert\\_undefined( $this \\[, $name\\] )\n\nAsserts that _$this_ is not defined.\n\n## assert\\_nonblank( $this \\[, $name\\] )\n\nAsserts that _$this_ is not a reference and is not an empty string.\n\n# BOOLEAN ASSERTIONS\n\nThese boolean assertions help make diagnostics more useful.\n\nIf you use `assert` with a boolean condition:\n\n    assert( $x \u0026\u0026 $y, 'Both X and Y should be true' );\n\nyou can't tell why it failed:\n\n    Assertion (Both X and Y should be true) failed!\n     at .../Carp/Assert/More.pm line 123\n            Carp::Assert::More::assert(undef, 'Both X and Y should be true') called at foo.pl line 16\n\nBut if you use `assert_and`:\n\n    assert_and( $x, $y, 'Both X and Y should be true' );\n\nthe stacktrace tells you which half of the expression failed.\n\n    Assertion (Both X and Y should be true) failed!\n     at .../Carp/Assert/More.pm line 123\n            Carp::Assert::More::assert_and('thing', undef, 'Both X and Y should be true') called at foo.pl line 16\n\n## assert\\_and( $x, $y \\[, $name\\] )\n\nAsserts that both `$x` and `$y` are true.\n\n## assert\\_or( $x, $y \\[, $name\\] )\n\nAsserts that at least one of `$x` or `$y` are true.\n\n## assert\\_xor( $x, $y \\[, $name\\] )\n\nAsserts that `$x` is true, or `$y` is true, but not both.\n\n# NUMERIC ASSERTIONS\n\n## assert\\_numeric( $n \\[, $name\\] )\n\nAsserts that `$n` looks like a number, according to `Scalar::Util::looks_like_number`.\n`undef` will always fail.\n\n## assert\\_integer( $this \\[, $name \\] )\n\nAsserts that _$this_ is an integer, which may be zero or negative.\n\n    assert_integer( 0 );      # pass\n    assert_integer( 14 );     # pass\n    assert_integer( -14 );    # pass\n    assert_integer( '14.' );  # FAIL\n\n## assert\\_nonzero( $this \\[, $name \\] )\n\nAsserts that the numeric value of _$this_ is defined and is not zero.\n\n    assert_nonzero( 0 );    # FAIL\n    assert_nonzero( -14 );  # pass\n    assert_nonzero( '14.' );  # pass\n\n## assert\\_positive( $this \\[, $name \\] )\n\nAsserts that _$this_ is defined, numeric and greater than zero.\n\n    assert_positive( 0 );    # FAIL\n    assert_positive( -14 );  # FAIL\n    assert_positive( '14.' );  # pass\n\n## assert\\_nonnegative( $this \\[, $name \\] )\n\nAsserts that _$this_ is defined, numeric and greater than or equal\nto zero.\n\n    assert_nonnegative( 0 );      # pass\n    assert_nonnegative( -14 );    # FAIL\n    assert_nonnegative( '14.' );  # pass\n    assert_nonnegative( 'dog' );  # pass\n\n## assert\\_negative( $this \\[, $name \\] )\n\nAsserts that the numeric value of _$this_ is defined and less than zero.\n\n    assert_negative( 0 );       # FAIL\n    assert_negative( -14 );     # pass\n    assert_negative( '14.' );   # FAIL\n\n## assert\\_nonzero\\_integer( $this \\[, $name \\] )\n\nAsserts that the numeric value of _$this_ is defined, an integer, and not zero.\n\n    assert_nonzero_integer( 0 );      # FAIL\n    assert_nonzero_integer( -14 );    # pass\n    assert_nonzero_integer( '14.' );  # FAIL\n\n## assert\\_positive\\_integer( $this \\[, $name \\] )\n\nAsserts that the numeric value of _$this_ is defined, an integer and greater than zero.\n\n    assert_positive_integer( 0 );     # FAIL\n    assert_positive_integer( -14 );   # FAIL\n    assert_positive_integer( '14.' ); # FAIL\n    assert_positive_integer( '14' );  # pass\n\n## assert\\_nonnegative\\_integer( $this \\[, $name \\] )\n\nAsserts that the numeric value of _$this_ is defined, an integer, and not less than zero.\n\n    assert_nonnegative_integer( 0 );      # pass\n    assert_nonnegative_integer( -14 );    # FAIL\n    assert_nonnegative_integer( '14.' );  # FAIL\n\n## assert\\_negative\\_integer( $this \\[, $name \\] )\n\nAsserts that the numeric value of _$this_ is defined, an integer, and less than zero.\n\n    assert_negative_integer( 0 );      # FAIL\n    assert_negative_integer( -14 );    # pass\n    assert_negative_integer( '14.' );  # FAIL\n\n## assert\\_numeric\\_between( $n, $lo, $hi \\[, $name \\] )\n\nAsserts that the value of _$this_ is defined, numeric and between `$lo`\nand `$hi`, inclusive.\n\n    assert_numeric_between( 15, 10, 100 );  # pass\n    assert_numeric_between( 10, 15, 100 );  # FAIL\n    assert_numeric_between( 3.14, 1, 10 );  # pass\n\n## assert\\_integer\\_between( $n, $lo, $hi \\[, $name \\] )\n\nAsserts that the value of _$this_ is defined, an integer, and between `$lo`\nand `$hi`, inclusive.\n\n    assert_integer_between( 15, 10, 100 );  # pass\n    assert_integer_between( 10, 15, 100 );  # FAIL\n    assert_integer_between( 3.14, 1, 10 );  # FAIL\n\n# REFERENCE ASSERTIONS\n\n## assert\\_isa( $this, $type \\[, $name \\] )\n\nAsserts that _$this_ is an object of type _$type_.\n\n## assert\\_isa\\_in( $obj, \\\\@types \\[, $description\\] )\n\nAssert that the blessed `$obj` isa one of the types in `\\@types`.\n\n    assert_isa_in( $obj, [ 'My::Foo', 'My::Bar' ], 'Must pass either a Foo or Bar object' );\n\n## assert\\_empty( $this \\[, $name \\] )\n\n_$this_ must be a ref to either a hash or an array.  Asserts that that\ncollection contains no elements.  Will assert (with its own message,\nnot _$name_) unless given a hash or array ref.   It is OK if _$this_ has\nbeen blessed into objecthood, but the semantics of checking an object to see\nif it does not have keys (for a hashref) or returns 0 in scalar context (for\nan array ref) may not be what you want.\n\n    assert_empty( 0 );       # FAIL\n    assert_empty( 'foo' );   # FAIL\n    assert_empty( undef );   # FAIL\n    assert_empty( {} );      # pass\n    assert_empty( [] );      # pass\n    assert_empty( {foo=\u003e1} );# FAIL\n    assert_empty( [1,2,3] ); # FAIL\n\n## assert\\_nonempty( $this \\[, $name \\] )\n\n_$this_ must be a ref to either a hash or an array.  Asserts that that\ncollection contains at least 1 element.  Will assert (with its own message,\nnot _$name_) unless given a hash or array ref.   It is OK if _$this_ has\nbeen blessed into objecthood, but the semantics of checking an object to see\nif it has keys (for a hashref) or returns \u003e0 in scalar context (for an array\nref) may not be what you want.\n\n    assert_nonempty( 0 );       # FAIL\n    assert_nonempty( 'foo' );   # FAIL\n    assert_nonempty( undef );   # FAIL\n    assert_nonempty( {} );      # FAIL\n    assert_nonempty( [] );      # FAIL\n    assert_nonempty( {foo=\u003e1} );# pass\n    assert_nonempty( [1,2,3] ); # pass\n\n## assert\\_nonref( $this \\[, $name \\] )\n\nAsserts that _$this_ is not undef and not a reference.\n\n## assert\\_hashref( $ref \\[,$name\\] )\n\nAsserts that _$ref_ is defined, and is a reference to a (possibly empty) hash.\n\n**NB:** This method returns _false_ for objects, even those whose underlying\ndata is a hashref. This is as it should be, under the assumptions that:\n\n- (a)\n\n    you shouldn't rely on the underlying data structure of a particular class, and\n\n- (b)\n\n    you should use `assert_isa` instead.\n\n## assert\\_hashref\\_nonempty( $ref \\[,$name\\] )\n\nAsserts that _$ref_ is defined and is a reference to a hash with at\nleast one key/value pair.\n\n## assert\\_arrayref( $ref \\[, $name\\] )\n\n## assert\\_listref( $ref \\[,$name\\] )\n\nAsserts that _$ref_ is defined, and is a reference to an array, which\nmay or may not be empty.\n\n**NB:** The same caveat about objects whose underlying structure is a\nhash (see `assert_hashref`) applies here; this method returns false\neven for objects whose underlying structure is an array.\n\n`assert_listref` is an alias for `assert_arrayref` and may go away in\nthe future.  Use `assert_arrayref` instead.\n\n## assert\\_arrayref\\_nonempty( $ref \\[, $name\\] )\n\nAsserts that _$ref_ is reference to an array that has at least one element in it.\n\n## assert\\_arrayref\\_of( $ref, $type \\[, $name\\] )\n\nAsserts that _$ref_ is reference to an array that has at least one\nelement in it, and every one of those elements is of type _$type_.\n\nFor example:\n\n    my @users = get_users();\n    assert_arrayref_of( \\@users, 'My::User' );\n\n## assert\\_arrayref\\_all( $aref, $sub \\[, $name\\] )\n\nAsserts that _$aref_ is reference to an array that has at least one\nelement in it. Each element of the array is passed to subroutine _$sub_\nwhich is assumed to be an assertion.\n\nFor example:\n\n    my $aref_of_counts = get_counts();\n    assert_arrayref_all( $aref, \\\u0026assert_positive_integer, 'Counts are positive' );\n\nWhatever is passed as _$name_, a string saying \"Element #N\" will be\nappended, where N is the zero-based index of the array.\n\n## assert\\_aoh( $ref \\[, $name \\] )\n\nVerifies that `$array` is an arrayref, and that every element is a hashref.\n\nThe array `$array` can be an empty arraref and the assertion will pass.\n\n## assert\\_coderef( $ref \\[,$name\\] )\n\nAsserts that _$ref_ is defined, and is a reference to a closure.\n\n## assert\\_regex( $ref \\[,$name\\] )\n\nAsserts that _$ref_ is defined, and is a reference to a regex.\n\nIt is functionally the same as `assert_isa( $ref, 'Regexp' )`.\n\n# TYPE-SPECIFIC ASSERTIONS\n\n## assert\\_datetime( $date )\n\nAsserts that `$date` is a DateTime object.\n\n# SET AND HASH MEMBERSHIP\n\n## assert\\_in( $string, \\\\@inlist \\[,$name\\] );\n\nAsserts that _$string_ matches one of the elements of _\\\\@inlist_.\n_$string_ may be undef.\n\n_\\\\@inlist_ must be an array reference of non-ref strings.  If any\nelement is a reference, the assertion fails.\n\n## assert\\_exists( \\\\%hash, $key \\[,$name\\] )\n\n## assert\\_exists( \\\\%hash, \\\\@keylist \\[,$name\\] )\n\nAsserts that _%hash_ is indeed a hash, and that _$key_ exists in\n_%hash_, or that all of the keys in _@keylist_ exist in _%hash_.\n\n    assert_exists( \\%custinfo, 'name', 'Customer has a name field' );\n\n    assert_exists( \\%custinfo, [qw( name addr phone )],\n                            'Customer has name, address and phone' );\n\n## assert\\_lacks( \\\\%hash, $key \\[,$name\\] )\n\n## assert\\_lacks( \\\\%hash, \\\\@keylist \\[,$name\\] )\n\nAsserts that _%hash_ is indeed a hash, and that _$key_ does NOT exist\nin _%hash_, or that none of the keys in _@keylist_ exist in _%hash_.\nThe list `@keylist` cannot be empty.\n\n    assert_lacks( \\%users, 'root', 'Root is not in the user table' );\n\n    assert_lacks( \\%users, [qw( root admin nobody )], 'No bad usernames found' );\n\n## assert\\_all\\_keys\\_in( \\\\%hash, \\\\@names \\[, $name \\] )\n\nAsserts that each key in `%hash` is in the list of `@names`.\n\nThis is used to ensure that there are no extra keys in a given hash.\n\n    assert_all_keys_in( $obj, [qw( height width depth )], '$obj can only contain height, width and depth keys' );\n\nYou can pass an empty list of `@names`.\n\n## assert\\_keys\\_are( \\\\%hash, \\\\@keys \\[, $name \\] )\n\nAsserts that the keys for `%hash` are exactly `@keys`, no more and no less.\n\n# CONTEXT ASSERTIONS\n\n## assert\\_context\\_nonvoid( \\[$name\\] )\n\nVerifies that the function currently being executed has not been called\nin void context.  This is to ensure the calling function is not ignoring\nthe return value of the executing function.\n\nGiven this function:\n\n    sub something {\n        ...\n\n        assert_context_nonvoid();\n\n        return $important_value;\n    }\n\nThese calls to `something` will pass:\n\n    my $val = something();\n    my @things = something();\n\nbut this will fail:\n\n    something();\n\nIf the `$name` argument is not passed, a default message of \"\u0026lt;funcname\u003e\nmust not be called in void context\" is provided.\n\n## assert\\_context\\_void( \\[$name\\] )\n\nVerifies that the function currently being executed has been called\nin void context.  This is for functions that do not return anything\nmeaningful.\n\nGiven this function:\n\n    sub something {\n        ...\n\n        assert_context_void();\n\n        return; # No meaningful value.\n    }\n\nThese calls to `something` will fail:\n\n    my $val = something();\n    my @things = something();\n\nbut this will pass:\n\n    something();\n\nIf the `$name` argument is not passed, a default message of \"\u0026lt;funcname\u003e\nmust be called in void context\" is provided.\n\n## assert\\_context\\_scalar( \\[$name\\] )\n\nVerifies that the function currently being executed has been called in\nscalar context.  This is to ensure the calling function is not ignoring\nthe return value of the executing function.\n\nGiven this function:\n\n    sub something {\n        ...\n\n        assert_context_scalar();\n\n        return $important_value;\n    }\n\nThis call to `something` will pass:\n\n    my $val = something();\n\nbut these will fail:\n\n    something();\n    my @things = something();\n\nIf the `$name` argument is not passed, a default message of \"\u0026lt;funcname\u003e\nmust be called in scalar context\" is provided.\n\n## assert\\_context\\_list( \\[$name\\] )\n\nVerifies that the function currently being executed has been called in\nlist context.\n\nGiven this function:\n\n    sub something {\n        ...\n\n        assert_context_scalar();\n\n        return @values;\n    }\n\nThis call to `something` will pass:\n\n    my @vals = something();\n\nbut these will fail:\n\n    something();\n    my $thing = something();\n\nIf the `$name` argument is not passed, a default message of \"\u0026lt;funcname\u003e\nmust be called in list context\" is provided.\n\n# UTILITY ASSERTIONS\n\n## assert\\_fail( \\[$name\\] )\n\nAssertion that always fails.  `assert_fail($msg)` is exactly the same\nas calling `assert(0,$msg)`, but it eliminates that case where you\naccidentally use `assert($msg)`, which of course never fires.\n\n# COPYRIGHT \u0026 LICENSE\n\nCopyright 2005-2025 Andy Lester\n\nThis program is free software; you can redistribute it and/or modify\nit under the terms of the Artistic License version 2.0.\n\n# ACKNOWLEDGEMENTS\n\nThanks to\nEric A. Zarko,\nBob Diss,\nPete Krawczyk,\nDavid Storrs,\nDan Friedman,\nAllard Hoeve,\nThomas L. Shinnick,\nand Leland Johnson\nfor code and fixes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetdance%2Fcarp-assert-more","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpetdance%2Fcarp-assert-more","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetdance%2Fcarp-assert-more/lists"}