dakusui / pcond

pcond is a library that allows you to write a program in the "Design by Contract"[DbC] style. Not only that, it gives a very informative message when a check you defined fails.

A Library for Uniformed Value Checking: pcond

pcond is a library to build "printable" predicates to build conditions that generate informative messages on failures of value checks.

Check pcond documentation for more detail.

Build

Build steps

To build and install the jar in local maven repository. This also builds the documentation.

mvn clean compile test install site

Build-time dependencies

sudo apt install openjdk-8-jdk
sudo apt install maven
sudo apt install -y ruby
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 && export PATH=$JAVA_HOME/bin:$PATH

pcond's Issues

Improve documentation

Improve documentation (an umbrella ticket)

Stop summarizing a checked value

Stop summarizing a checked value.
It sometimes obscures the reason where a condition is violated.

`findSubstring` output improvement

Following is the "as-is" output.

.ASIS

    "Gallia est omnis divis...Bello Gallicco."->transform
                                                  findTokens                       ->"Gallia est omnis divis...Bello Gallicco."
                                                  identity                         ->"Gallia est omnis divis...Bello Gallicco."
                                                VERIFY
                                                  &&                               ->true
                                                    findTokenBy[substring[Gallia]] ->true
    " est omnis divisa in p...Bello Gallicco."->    findTokenBy[substring[quarum]] ->true
[0] " unum incolunt Belgae,...Bello Gallicco."->    findTokenBy[substring[Belgium]]->true
                                                    findTokenBy[substring[nostra]] ->true
    " Galli Appellantur. De Bello Gallicco."  ->    findTokenBy[substring[De]]     ->true
[1] " Bello Gallicco."                        ->    findTokenBy[substring[Bellum]] ->true
                                                    (end)                          ->true

.Detail of failure [0]
----
Gallia est omnis divisa in partes tres, quarum
<<NOTFOUND:substring[Belgium]>>
 unum incolunt Belgae, aliam Acquitanii, tertiam nostra Galli Appellantur. De Bello Gallicco.
----

.Detail of failure [1]
----
Gallia est omnis divisa in partes tres, quarum unum incolunt Belgae, aliam Acquitanii, tertiam nostra Galli Appellantur. De
<<NOTFOUND:substring[Bellum]>>
 Bello Gallicco.
----

I want to make it like following.

.TOBE

    "Gallia est omnis divis...Bello Gallicco."->transform
                                                  findTokens                       ->"Gallia est omnis divis...Bello Gallicco."
                                                  identity                         ->"Gallia est omnis divis...Bello Gallicco."
                                                VERIFY
                                                  &&                               ->false
                                                    findTokenBy[substring[Gallia]] ->true
    " est omnis divisa in p...Bello Gallicco."->    findTokenBy[substring[quarum]] ->true
[0] " unum incolunt Belgae,...Bello Gallicco."->    findTokenBy[substring[Belgium]]->false
                                                    findTokenBy[substring[nostra]] ->true
    " Galli Appellantur. De Bello Gallicco."  ->    findTokenBy[substring[De]]     ->true
[1] " Bello Gallicco."                        ->    findTokenBy[substring[Bellum]] ->false
[2]                                                   (end)                          ->false

.Detail of failure [0]
----
Gallia est omnis divisa in partes tres, quarum
<<NOTFOUND:substring[Belgium]>>
 ----

.Detail of failure [1]
----
...Galli Appellantur. De
<<NOTFOUND:substring[Bello]>>
----
.Detail of failure [2]
----
 Bello Gallicco.
----

Improve output of an exception thrown during exception.

Improve output of an exception thrown during exception.

• When an exception thrown during evaluation, the evaluation should go to the end.
• The exception's stacktrace should be printed in the detail section.

A public method overriding a public in a superclass cannot be accessed if the class is private

A public method overriding a public in a superclass cannot be accessed if the class is private.

com.github.dakusui.pcond.internals.InternalException: An exception(com.github.dakusui.pcond.internals.MethodAccessException: Method access to 'public java.util.Set com.github.dakusui.pcond.ut.bugfixes.issuexyz.IssueXyzUtils$PrivateExtendingPublic.keySet()' was failed) was thrown during evaluation of value: {}: <>.keySet() isEmpty
transform("{}")          
  <>.keySet()("{}")      com.github.dakusui.pcond.internals.MethodAccessException: Method access to 'public java.util.Set com.github.dakusui.pcond.ut.bugfixes.issuexyz.IssueXyzUtils$PrivateExtendingPublic.keySet()' was failed

	at com.github.dakusui.pcond.internals.InternalUtils.wrap(InternalUtils.java:94)
	at com.github.dakusui.pcond.provider.impls.DefaultAssertionProvider.checkValue(DefaultAssertionProvider.java:97)
	at com.github.dakusui.pcond.provider.AssertionProviderBase.require(AssertionProviderBase.java:32)
	at com.github.dakusui.pcond.provider.AssertionProviderBase.require(AssertionProviderBase.java:27)
	at com.github.dakusui.pcond.Preconditions.require(Preconditions.java:26)
	at com.github.dakusui.pcond.ut.bugfixes.IssueXyzTest.givenPrivateClassExtendingPublic$whenPublicMethodIsCalled$thenCallSucceeds(IssueXyzTest.java:20)
Caused by: com.github.dakusui.pcond.internals.MethodAccessException: Method access to 'public java.util.Set com.github.dakusui.pcond.ut.bugfixes.issuexyz.IssueXyzUtils$PrivateExtendingPublic.keySet()' was failed
	at com.github.dakusui.pcond.core.refl.ReflUtils.invokeMethod(ReflUtils.java:84)
	at com.github.dakusui.pcond.core.refl.ReflUtils.invokeMethod(ReflUtils.java:63)
	at com.github.dakusui.pcond.functions.Functions.lambda$call$2(Functions.java:175)

Enable opentest4j when junit4 seems not to be present.

Enable opentest4j when junit4 seems not to be present.

Make assertion provider more configurable

Make assertion provider more configurable.
Following features should be configured independently.

• Reporting
• Exception Creation
• Message Composition

Transforming should not use its name for equalness check

2024/06/10

Expose methods to create parameterized functions

Expose methods to create parameterized functions.

Release `pcond-3.0.0-alpha`.

Simplify "fluent" style entry points

Simplify "fluent" style entry points.
Existing "Fluent" style should be removed and the "MoreFluent" style should be called "Fluent".

Add type aware "stream" function to Functions

Add type aware "stream" function to Functions.
Such as:

Functions.stream(Class<E> elementClass)

to be able to handle a collection-to-stream transform without a manual cast.

Support a feature to convert a method into a function or predicate

Introduce a feature, where following example is possible.

  public void chainExample() {
    String var = "hello, world";

    requireArgument(
        var,
        transform(
            chain("substring", 7)
                .andThen(chain("toUpperCase")))
            .castAndCheck(chainp("equals", "WORLD"))
    );
  }

Instead of defining a printable function every time, directly create it from a method.

Move methods to create statements to Statement interface

Move methods to create statements to Statement interface to make it easy to use the pcond library.

Add unit tests

Add unit tests (an umbrella ticket)

Improve the `findElements`'s output

Currently, it's shown like below.

["Hello","world",""...;9]        ->transform
                                     toCursoredList                            ->["Hello","world",""...;9]
                                     identity                                  ->["Hello","world",""...;9]
                                   VERIFY
                                     &&                                        ->false
                                       findElementBy[isEqualTo["world"]]       ->true
["","everyone","quick"...;7]     ->    findElementBy[isEqualTo["cat"]]         ->false
                                       findElementBy[isEqualTo["organization"]]->false
                                       findElementBy[isNotNull]                ->true
["everyone","quick","brown"...;6]->    findElementBy[isEqualTo["fox"]]         ->true
["runs","forever"]               ->    findElementBy[isEqualTo["world"]]       ->false
                                       (end)                                   ->true

But it can be improved by using snapshotting and explain mechanism.

Improve IDEA setting

Improve IDEA setting (This is a place-holder ticket)

Make it possible to use pcond as a assertion library

Add procedure to deploy site

Add procedure to deploy site for reports and JavaDoc to somewhere (probably README.adoc).

mvn -Dmaven.site.deploy.skip=false compile test site

Predicates.isInstanceOf() should return Predicate<Object>

Predicates.isInstanceOf() should return Predicate instead of Predicate<? super T>.
Otherwise, users will need to give an explicit type parameter every time to composite predicate methods (allOf, anyOf, and, or).

Improve report output

Improve report output

• Squash "negate" predicate if target is a leaf
• Use and and allOf instead of &&
• Use or and anyOf instead of ||

Make exceptions more customizable

Make exceptions more customizable by completing Configuration interface.

Support nested loop

I'd like to be able write a following requirement.

  public void hello() {
    require(
        asList("hello", "world"),
        when(stream().andThen(nest(asList("1", "2", "o")))).then(anyMatch(test(String::endsWith(), 0, 1))));
  }

where, 0,1 represents the order of variables in the context passed to the endsWith function.

asListOf(Class elementType) method is missing.

asListOf(Class elementType) method is missing in ObjectTransformer (or AbstractObjectTransformer).

Improve output of assertWhen.

For the following test code:

  @Test
  public void givenKnownLastName_whenFindMembersByFullName_thenLastNastIsNotNullAndContainedInFullName() {
    MemberDatabase database = new MemberDatabase();
    String lastName = database.lookUp("0001")
        .orElseThrow(NoSuchElementException::new)
        .lastName();
    List<String> fullName = database.findMembersByLastName(lastName).get(0).toFullName();
    assertWhen(
        valueOf(lastName)
            .then()
            .verifyWith(allOf(
                isNotNull(),
                not(isEmptyString()))),
        valueOf(fullName).asListOfClass(String.class)
            .then()
            .contains(lastName + "_"));
  }

pcond currently gives following output:

["Doe",["John","Doe","PhD"]]->&&                    ->false
                                transform
                                  at[0]             ->"Doe"
"Doe"                       ->  check
                                  WHEN
                                    treatAs[NOUT]   ->"Doe"
                                  THEN
                                    &&              ->true
                                      isNotNull     ->true
                                      !             ->true
                                        isEmpty     ->false
["Doe",["John","Doe","PhD"]]->  transform
                                  at[1]             ->["John","Doe","PhD"]
["John","Doe","PhD"]        ->  check
                                  WHEN
                                    treatAsList     ->["John","Doe","PhD"]
                                  THEN
                                    contains["Doe_"]->false

This is redundant and it should be like the following.

"Doe"                       ->  check
                                  WHEN
                                    treatAs[NOUT]   ->"Doe"
                                  THEN
                                    &&              ->true
                                      isNotNull     ->true
                                      !             ->true
                                        isEmpty     ->false
["John","Doe","PhD"]        ->  check
                                  WHEN
                                    treatAsList     ->["John","Doe","PhD"]
                                  THEN
                                    contains["Doe_"]->false

If this can be

"Doe"                       ->  WHEN
                                    treatAs[NOUT]   ->"Doe"
                                  THEN
                                    &&              ->true
                                      isNotNull     ->true
                                      !             ->true
                                        isEmpty     ->false
["John","Doe","PhD"]        ->  WHEN
                                    treatAsList     ->["John","Doe","PhD"]
                                  THEN
                                    contains["Doe_"]->false

it will be even better.

Clean up object identification mechanism

Clean up object identification mechanism

Improve output message of "MoreFluent" style

In case, we use "WHEN" phrase but no transformation is given, we see the following output.

"Doe"               ->WHEN:treatAs[NOUT]    ->"Doe"
                      THEN:&&              ->true
                          isNotNull        ->true
                          !                ->true
                            isEmpty        ->false
["John","Doe","PhD"]->WHEN:treatAsList     ->["John","Doe","PhD"]
                      THEN:contains["Doe_"]->true

The part treatAs[NOUT] is an internal term and if it is treatAsIs, the output will be more readable.

Add $() method to Checker interface

Add $(): ObjectChecker method to Checker interface.
This will be necessary for valid8j's all(Statement<T>... statements): boolean method.
Without having it, you cannot use all(...) method for checking multiple values of different types.

Support special forms

Support special forms to make the pcond Turing complete.

IDEA reports a warning that uses methods in Assertions class

IDEA reports a warning that uses methods in Assertions class because they always true, if a condition given to a method in the class becomes true always, as long as the condition is met, even if an exception is thrown in case the condition is violated.

Add "allOf" method to a predicate factory returned by "Predicates.transfotm(...)"

Add allOf method to a predicate factory returned by Predicates.transfotm(...).

It is so often to do transform(...).check(allOf(...)).
Let's create a short hand method for it.

Print failure detail for leaf predicate

Print failure detail for leaf predicate so that full expectation and full actual values are seen in the report.

Doesn't print intended error meesage

		requireArgument(asList(args),
				and(when(size()).then(isEqualTo(1)),
						when(elementAt(0)).then(and(isNotNull(), isInstanceOf(String.class)))));

In case args[0] = (int)0,
This results in a java's native lambda printed message.