robstoll#630 add Path.isRelative method

apis/fluent-en_GB/atrium-api-fluent-en_GB-jvm/src/main/kotlin/ch/tutteli/atrium/api/fluent/en_GB/pathAssertions.kt

@@ -286,6 +286,26 @@ fun <T : Path> Expect<T>.isRegularFile(): Expect<T> =
 fun <T : Path> Expect<T>.isDirectory(): Expect<T> =
     _logicAppend { isDirectory() }
 
+/**
+ * Expects that the subject of the assertion (a [Path]) is a relative path;
+ * meaning that the [Path] specified in this instance does not start at the file system root.
+ *
+ * This assertion _resolves_ symbolic links.
+ * Therefore, if a symbolic link exists at the location the subject points to, search will continue
+ * at the location the link points at.
+ *
+ * This assertion is not atomic with respect to concurrent file system operations on the paths the assertions works on.
+ * Its result, in particular its extended explanations, may be wrong if such concurrent file system operations
+ * take place.
+ *
+ * @return An [Expect] for the current subject of the assertion.
+ * @throws AssertionError Might throw an [AssertionError] if the assertion made is not correct.
+ *
+ * @since 0.14.0
+ */
+fun <T : Path> Expect<T>.isRelative(): Expect<T> =
+    _logicAppend { isRelative() }
+
 /**
  * Creates an [Expect] for the property [Path.extension][ch.tutteli.niok.extension]
  * (provided via [niok](https://github.com/robstoll/niok)) of the subject of the assertion,

apis/fluent-en_GB/atrium-api-fluent-en_GB-jvm/src/test/kotlin/ch/tutteli/atrium/api/fluent/en_GB/PathAssertionsSpec.kt

@@ -20,6 +20,7 @@ class PathAssertionsSpec : ch.tutteli.atrium.specs.integration.PathAssertionsSpe
     fun0(Expect<Path>::isExecutable),
     fun0(Expect<Path>::isRegularFile),
     fun0(Expect<Path>::isDirectory),
+    fun0(Expect<Path>::isRelative),
     fun1(Expect<Path>::hasSameBinaryContentAs),
     fun3(Expect<Path>::hasSameTextualContentAs),
     fun1(Companion::hasSameTextualContentAsDefaultArgs)

apis/infix-en_GB/atrium-api-infix-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/infix/en_GB/keywords.kt

@@ -22,6 +22,12 @@ object aRegularFile : Keyword
  */
 object aDirectory : Keyword
 
+/**
+ * A helper construct to allow expressing assertions about a path being relative.
+ * It can be used for a parameterless function so that it has one parameter and thus can be used as infix function.
+ */
+object relative : Keyword
+
 /**
  * Represents a helper construct which allows to express blankness.
  * It can be used for a parameterless function so that it has one parameter and thus can be used as infix function.

apis/infix-en_GB/atrium-api-infix-en_GB-jvm/src/main/kotlin/ch/tutteli/atrium/api/infix/en_GB/pathAssertions.kt

@@ -296,6 +296,27 @@ infix fun <T : Path> Expect<T>.toBe(@Suppress("UNUSED_PARAMETER") aRegularFile:
 infix fun <T : Path> Expect<T>.toBe(@Suppress("UNUSED_PARAMETER") aDirectory: aDirectory): Expect<T> =
     _logicAppend { isDirectory() }
 
+/**
+ * Expects that the subject of the assertion (a [Path]) is a relative path;
+ * meaning that the [Path] specified in this instance does not start at system root.
+ *
+ * This assertion _resolves_ symbolic links.
+ * Therefore, if a symbolic link exists at the location the subject points to, search will continue
+ * at the location the link points at.
+ *
+ * This assertion is not atomic with respect to concurrent file system operations on the paths the assertions works on.
+ * Its result, in particular its extended explanations, may be wrong if such concurrent file system operations
+ * take place.
+ *
+ * @return An [Expect] for the current subject of the assertion.
+ * @throws AssertionError Might throw an [AssertionError] if the assertion made is not correct.
+ *
+ * @since 0.14.0
+ */
+infix fun <T : Path> Expect<T>.toBe(@Suppress("UNUSED_PARAMETER") relative: relative): Expect<T> =
+    _logicAppend { isRelative() }
+
+
 /**
  * Creates an [Expect] for the property [Path.extension][ch.tutteli.niok.extension]
  * (provided via [niok](https://github.com/robstoll/niok)) of the subject of the assertion,

apis/infix-en_GB/atrium-api-infix-en_GB-jvm/src/test/kotlin/ch/tutteli/atrium/api/infix/en_GB/PathAssertionsSpec.kt

@@ -21,6 +21,7 @@ class PathAssertionsSpec : ch.tutteli.atrium.specs.integration.PathAssertionsSpe
     "toBe ${executable::class.simpleName}" to Companion::isExecutable,
     "toBe ${aRegularFile::class.simpleName}" to Companion::isRegularFile,
     "toBe ${aDirectory::class.simpleName}" to Companion::isDirectory,
+    "toBe ${relative::class.simpleName}" to Companion::isRelative,
     fun1(Expect<Path>::hasSameBinaryContentAs),
     fun3(Companion::hasSameTextualContentAs),
     fun1(Companion::hasSameTextualContentAsDefaultArgs)
@@ -34,6 +35,7 @@ class PathAssertionsSpec : ch.tutteli.atrium.specs.integration.PathAssertionsSpe
         private fun isExecutable(expect: Expect<Path>) = expect toBe executable
         private fun isRegularFile(expect: Expect<Path>) = expect toBe aRegularFile
         private fun isDirectory(expect: Expect<Path>) = expect toBe aDirectory
+        private fun isRelative(expect: Expect<Path>) = expect toBe relative
 
         private fun hasSameTextualContentAs(
             expect: Expect<Path>,
@@ -62,6 +64,7 @@ class PathAssertionsSpec : ch.tutteli.atrium.specs.integration.PathAssertionsSpe
         a1 toBe writable
         a1 toBe aRegularFile
         a1 toBe aDirectory
+        a1 toBe relative
         a1 hasSameTextualContentAs withEncoding(Paths.get("a"))
         a1 hasSameTextualContentAs Paths.get("a")
     }

logic/atrium-logic-jvm/src/generated/kotlin/ch/tutteli/atrium/logic/path.kt

@@ -32,6 +32,7 @@ fun <T : Path> AssertionContainer<T>.isWritable(): Assertion = impl.isWritable(t
 fun <T : Path> AssertionContainer<T>.isExecutable(): Assertion = impl.isExecutable(this)
 fun <T : Path> AssertionContainer<T>.isRegularFile(): Assertion = impl.isRegularFile(this)
 fun <T : Path> AssertionContainer<T>.isDirectory(): Assertion = impl.isDirectory(this)
+fun <T : Path> AssertionContainer<T>.isRelative(): Assertion = impl.isRelative(this)
 
 fun <T : Path> AssertionContainer<T>.hasSameTextualContentAs(targetPath: Path, sourceCharset: Charset, targetCharset: Charset): Assertion =
     impl.hasSameTextualContentAs(this, targetPath, sourceCharset, targetCharset)

logic/atrium-logic-jvm/src/main/kotlin/ch/tutteli/atrium/logic/PathAssertions.kt

@@ -28,6 +28,7 @@ interface PathAssertions {
     fun <T : Path> isExecutable(container: AssertionContainer<T>): Assertion
     fun <T : Path> isRegularFile(container: AssertionContainer<T>): Assertion
     fun <T : Path> isDirectory(container: AssertionContainer<T>): Assertion
+    fun <T : Path> isRelative(container: AssertionContainer<T>): Assertion
 
     fun <T : Path> hasSameTextualContentAs(
         container: AssertionContainer<T>,

logic/atrium-logic-jvm/src/main/kotlin/ch/tutteli/atrium/logic/creating/filesystem/hints/hints.kt

@@ -11,6 +11,7 @@ import ch.tutteli.atrium.logic.creating.filesystem.IoResult
 import ch.tutteli.atrium.logic.creating.filesystem.Success
 import ch.tutteli.atrium.reporting.translating.Translatable
 import ch.tutteli.atrium.translations.DescriptionBasic
+import ch.tutteli.atrium.translations.DescriptionPathAssertion
 import ch.tutteli.atrium.translations.DescriptionPathAssertion.*
 import ch.tutteli.niok.followSymbolicLink
 import ch.tutteli.niok.getFileAttributeView
@@ -35,16 +36,30 @@ inline fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withIOExcept
 
 fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withFileAttributesFailureHint(
     expect: Expect<IoResult<BasicFileAttributes>>
+): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> =
+    withAttributeFailureHint(expect) { it.value.fileType }
+
+fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withPathAttributesFailureHint(
+    expect: Expect<IoResult<BasicFileAttributes>>
+): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> =
+    withAttributeFailureHint(expect) { it.path.type }
+
+private inline fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withAttributeFailureHint(
+    expect: Expect<IoResult<BasicFileAttributes>>,
+    actualTypeProvider: (Success<BasicFileAttributes>) -> Translatable
 ): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> =
     withFailureHintBasedOnDefinedSubject(expect) { result ->
         explainForResolvedLink(result.path) { realPath ->
             when (result) {
-                is Success -> describeWas(result.value.fileType)
+                is Success -> describeWas(actualTypeProvider(result))
                 is Failure -> hintForIoException(realPath, result.exception)
             }
         }
     }
 
+private val Path.type: DescriptionPathAssertion
+    get() = if (isAbsolute) ABSOLUTE_PATH else RELATIVE_PATH
+
 /**
  * Internal for testing purposes only
  */

logic/atrium-logic-jvm/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultPathAssertions.kt

@@ -109,6 +109,9 @@ class DefaultPathAssertions : PathAssertions {
     override fun <T : Path> isDirectory(container: AssertionContainer<T>): Assertion =
         fileTypeAssertion(container, A_DIRECTORY) { it.isDirectory }
 
+    override fun <T : Path> isRelative(container: AssertionContainer<T>): Assertion =
+        pathTypeAssertion(container, RELATIVE_PATH) { !it.isAbsolute }
+
     private fun <T : Path> filePermissionAssertion(
         container: AssertionContainer<T>,
         permissionName: Translatable,
@@ -147,6 +150,17 @@ class DefaultPathAssertions : PathAssertions {
             .build()
     }
 
+    private inline fun <T : Path> pathTypeAssertion(
+        container: AssertionContainer<T>,
+        typeName: Translatable,
+        crossinline typeTest: (Path) -> Boolean
+    ) = changeSubjectToFileAttributes(container) { fileAttributesExpect ->
+        assertionBuilder.descriptive
+            .withTest(fileAttributesExpect) { it is Success && typeTest(it.path) }
+            .withPathAttributesFailureHint(fileAttributesExpect)
+            .withDescriptionAndRepresentation(DescriptionBasic.IS, typeName)
+            .build()
+    }
 
     override fun <T : Path> fileName(container: AssertionContainer<T>): FeatureExtractorBuilder.ExecutionStep<T, String> =
         container.manualFeature(FILE_NAME) { fileName.toString() }

misc/specs/atrium-specs-jvm/src/main/kotlin/ch/tutteli/atrium/specs/integration/PathAssertionsSpec.kt

@@ -19,6 +19,7 @@ import org.spekframework.spek2.dsl.Skip.No
 import org.spekframework.spek2.dsl.Skip.Yes
 import org.spekframework.spek2.dsl.TestBody
 import org.spekframework.spek2.style.specification.Suite
+import java.io.File
 import java.io.IOException
 import java.nio.charset.Charset
 import java.nio.file.Files
@@ -43,6 +44,7 @@ abstract class PathAssertionsSpec(
     isExecutable: Fun0<Path>,
     isRegularFile: Fun0<Path>,
     isDirectory: Fun0<Path>,
+    isRelative: Fun0<Path>,
     hasSameBinaryContentAs: Fun1<Path, Path>,
     hasSameTextualContentAs: Fun3<Path, Path, Charset, Charset>,
     hasSameTextualContentAsDefaultArgs: Fun1<Path, Path>,
@@ -62,6 +64,7 @@ abstract class PathAssertionsSpec(
         isExecutable.forSubjectLess(),
         isRegularFile.forSubjectLess(),
         isDirectory.forSubjectLess(),
+        isRelative.forSubjectLess(),
         hasSameBinaryContentAs.forSubjectLess(Paths.get("a")),
         hasSameTextualContentAs.forSubjectLess(Paths.get("a"), Charsets.ISO_8859_1, Charsets.ISO_8859_1),
         hasSameTextualContentAsDefaultArgs.forSubjectLess(Paths.get("a"))
@@ -828,6 +831,48 @@ abstract class PathAssertionsSpec(
         }
     }
 
+    describeFun(isRelative) {
+        val isRelativeFun = isRelative.lambda
+        val expectedMessage = "$isDescr: ${RELATIVE_PATH.getDefault()}"
+
+        context("not accessible") {
+            it("throws an AssertionError for a non-existent path") withAndWithoutSymlink { maybeLink ->
+                val file = maybeLink.create(tempFolder.tmpDir.resolve("nonExistent"))
+                expect {
+                    expect(file).isRelativeFun()
+                }.toThrow<AssertionError>().message {
+                    contains(expectedMessage, FAILURE_DUE_TO_NO_SUCH_FILE.getDefault())
+                    containsExplanationFor(maybeLink)
+                }
+            }
+
+            itPrintsFileAccessProblemDetails { testFile ->
+                expect(testFile).isRelativeFun()
+            }
+        }
+
+        it("throws an AssertionError for absolute path") withAndWithoutSymlink { maybeLink ->
+            val path = maybeLink.create(tempFolder.newFile("test"))
+                .absolutePathAsString
+                .let { File(it) }
+                .toPath()
+
+            expect {
+                expect(path).isRelativeFun()
+            }.toThrow<AssertionError>().message {
+                contains(expectedMessage, "${WAS.getDefault()}: ${ABSOLUTE_PATH.getDefault()}")
+                containsExplanationFor(maybeLink)
+            }
+        }
+
+        it("does not throw for relative path") withAndWithoutSymlink { maybeLink ->
+            val path = maybeLink.create(tempFolder.newFile("test"))
+                .relativize(tempFolder.tmpDir)
+
+            expect(path).isRelativeFun()
+        }
+    }
+
     describeFun(hasSameBinaryContentAs, hasSameTextualContentAs, hasSameTextualContentAsDefaultArgs) {
         val hasSameBinaryContentAsFun = hasSameBinaryContentAs.lambda
         val hasSameTextualContentAsFun = hasSameTextualContentAs.lambda

translations/en_GB/atrium-translations-en_GB-jvm/src/main/kotlin/ch/tutteli/atrium/translations/DescriptionPathAssertion.kt

@@ -8,6 +8,7 @@ package ch.tutteli.atrium.translations
 import ch.tutteli.atrium.reporting.translating.StringBasedTranslatable
 
 enum class DescriptionPathAssertion(override val value: String) : StringBasedTranslatable {
+    ABSOLUTE_PATH("absolute path"),
     DOES_NOT_HAVE_PARENT("!! does not have a parent"),
     ENDS_NOT_WITH("does not end with"),
     ENDS_WITH("ends with"),
@@ -40,4 +41,5 @@ enum class DescriptionPathAssertion(override val value: String) : StringBasedTra
     HINT_FOLLOWED_SYMBOLIC_LINK("followed the symbolic link %s to %s"),
     HAS_SAME_TEXTUAL_CONTENT("has same textual content with encoding %s, %s"),
     HAS_SAME_BINARY_CONTENT("has same binary content"),
+    RELATIVE_PATH("relative path"),
 }