Added experimental annotation and updated checks in move

Author: ajaychandran

build.sc

@@ -72,6 +72,9 @@ trait MiMaChecks extends Mima {
     // this is fine, because ProcessLike is sealed (and its subclasses should be final)
     ProblemFilter.exclude[ReversedMissingMethodProblem]("os.ProcessLike.joinPumperThreadsHook")
   )
+  override def mimaExcludeAnnotations: T[Seq[String]] = Seq(
+    "os.experimental"
+  )
 }
 
 trait OsLibModule

os/src/FileOps.scala

@@ -22,10 +22,12 @@ import scala.util.Try
  * ignore the destination if it already exists, using [[os.makeDir.all]]
  */
 object makeDir extends Function1[Path, Unit] {
+  @experimental
   def apply(path: Path): Unit = {
     checker.value.onWrite(path)
     Files.createDirectory(path.wrapped)
   }
+  @experimental
   def apply(path: Path, perms: PermSet): Unit = {
     checker.value.onWrite(path)
     Files.createDirectory(
@@ -41,6 +43,7 @@ object makeDir extends Function1[Path, Unit] {
    */
   object all extends Function1[Path, Unit] {
     def apply(path: Path): Unit = apply(path, null, true)
+    @experimental
     def apply(path: Path, perms: PermSet = null, acceptLinkedDirectory: Boolean = true): Unit = {
       checker.value.onWrite(path)
       // We special case calling makeDir.all on a symlink to a directory;
@@ -82,15 +85,15 @@ object move {
   def matching(partialFunction: PartialFunction[Path, Path]): PartialFunction[Path, Unit] = {
     matching()(partialFunction)
   }
+  @experimental
   def apply(
       from: Path,
       to: Path,
       replaceExisting: Boolean = false,
       atomicMove: Boolean = false,
       createFolders: Boolean = false
   ): Unit = {
-    checker.value.onRead(from)
-    checker.value.onWrite(from / RelPath.up)
+    checker.value.onWrite(from)
     checker.value.onWrite(to)
     if (createFolders && to.segmentCount != 0) makeDir.all(to / up)
     val opts1 =
@@ -175,6 +178,7 @@ object copy {
     matching()(partialFunction)
   }
 
+  @experimental
   def apply(
       from: Path,
       to: Path,
@@ -319,6 +323,7 @@ object copy {
  */
 object remove extends Function1[Path, Boolean] {
   def apply(target: Path): Boolean = apply(target, false)
+  @experimental
   def apply(target: Path, checkExists: Boolean = false): Boolean = {
     checker.value.onWrite(target)
     if (checkExists) {
@@ -330,6 +335,7 @@ object remove extends Function1[Path, Boolean] {
   }
 
   object all extends Function1[Path, Unit] {
+    @experimental
     def apply(target: Path) = {
       require(target.segmentCount != 0, s"Cannot remove a root directory: $target")
       checker.value.onWrite(target)
@@ -360,6 +366,7 @@ object exists extends Function1[Path, Boolean] {
  * Creates a hardlink between two paths
  */
 object hardlink {
+  @experimental
   def apply(link: Path, dest: Path) = {
     checker.value.onWrite(link)
     checker.value.onRead(dest)
@@ -371,6 +378,7 @@ object hardlink {
  * Creates a symbolic link between two paths
  */
 object symlink {
+  @experimental
   def apply(link: Path, dest: FilePath, perms: PermSet = null): Unit = {
     checker.value.onWrite(link)
     checker.value.onRead(dest match {

os/src/Model.scala

@@ -288,9 +288,10 @@ object PosixStatInfo {
  * Defines hooks for path based operations.
  *
  * This, in conjunction with [[checker]], can be used to implement custom checks like
- *  - restricting operations to some path(s)
- *  - logging operations
+ *  - restricting an operation to some path(s)
+ *  - logging an operation
  */
+@experimental
 trait Checker {
 
   /** A hook for a read operation on `path`. */
@@ -300,6 +301,7 @@ trait Checker {
   def onWrite(path: Path): Unit
 }
 
+@experimental
 object Checker {
 
   /** A no-op [[Checker]]. */

os/src/PermsOps.scala

@@ -23,6 +23,7 @@ object perms extends Function1[Path, PermSet] {
    * default set of permissions and having `os.perms.set` over-write them later
    */
   object set {
+    @experimental
     def apply(p: Path, arg2: PermSet): Unit = {
       checker.value.onWrite(p)
       Files.setPosixFilePermissions(p.wrapped, arg2.toSet())
@@ -45,6 +46,7 @@ object owner extends Function1[Path, UserPrincipal] {
    * Set the owner of the file/folder at the given path
    */
   object set {
+    @experimental
     def apply(arg1: Path, arg2: UserPrincipal): Unit = {
       checker.value.onWrite(arg1)
       Files.setOwner(arg1.wrapped, arg2)
@@ -76,6 +78,7 @@ object group extends Function1[Path, GroupPrincipal] {
    * Set the owning group of the file/folder at the given path
    */
   object set {
+    @experimental
     def apply(arg1: Path, arg2: GroupPrincipal): Unit = {
       checker.value.onWrite(arg1)
       Files.getFileAttributeView(

os/src/ReadWriteOps.scala

@@ -21,6 +21,7 @@ object write {
   /**
    * Open a [[java.io.OutputStream]] to write to the given file
    */
+  @experimental
   def outputStream(
       target: Path,
       perms: PermSet = null,
@@ -47,6 +48,7 @@ object write {
    * from `java.nio.file.Files.write` so we could re-use it properly for
    * different combinations of flags and all sorts of [[Source]]s
    */
+  @experimental
   def write(
       target: Path,
       data: Source,
@@ -167,6 +169,7 @@ object write {
    * Opens a [[SeekableByteChannel]] to write to the given file.
    */
   object channel extends Function1[Path, SeekableByteChannel] {
+    @experimental
     def write(p: Path, options: Seq[StandardOpenOption]) = {
       checker.value.onWrite(p)
       java.nio.file.Files.newByteChannel(p.toNIO, options.toArray: _*)
@@ -214,6 +217,7 @@ object write {
  * given size, does nothing.
  */
 object truncate {
+  @experimental
   def apply(p: Path, size: Long): Unit = {
     checker.value.onWrite(p)
     val channel = FileChannel.open(p.toNIO, StandardOpenOption.WRITE)
@@ -246,6 +250,7 @@ object read extends Function1[ReadablePath, String] {
    * Opens a [[java.io.InputStream]] to read from the given file
    */
   object inputStream extends Function1[ReadablePath, java.io.InputStream] {
+    @experimental
     def apply(p: ReadablePath): java.io.InputStream = {
       checker.value.onRead(p)
       p.getInputStream
@@ -269,6 +274,7 @@ object read extends Function1[ReadablePath, String] {
    * Opens a [[SeekableByteChannel]] to read from the given file.
    */
   object channel extends Function1[Path, SeekableByteChannel] {
+    @experimental
     def apply(p: Path): SeekableByteChannel = {
       checker.value.onRead(p)
       p.toSource.getChannel()

os/src/StatOps.scala

@@ -73,6 +73,7 @@ object mtime extends Function1[Path, Long] {
    * https://stackoverflow.com/questions/17308363/symlink-lastmodifiedtime-in-java-1-7
    */
   object set {
+    @experimental
     def apply(p: Path, millis: Long) = {
       checker.value.onWrite(p)
       Files.setLastModifiedTime(p.wrapped, FileTime.fromMillis(millis))

os/src/TempOps.scala

@@ -20,6 +20,7 @@ object temp {
    * By default, temporary files are deleted on JVM exit. You can disable that
    * behavior by setting `deleteOnExit = false`
    */
+  @experimental
   def apply(
       contents: Source = null,
       dir: Path = null,
@@ -28,7 +29,6 @@ object temp {
       deleteOnExit: Boolean = true,
       perms: PermSet = null
   ): Path = {
-    import collection.JavaConverters._
     val permArray: Array[FileAttribute[_]] =
       if (perms == null) Array.empty
       else Array(PosixFilePermissions.asFileAttribute(perms.toSet()))
@@ -53,6 +53,7 @@ object temp {
    * By default, temporary directories are deleted on JVM exit. You can disable that
    * behavior by setting `deleteOnExit = false`
    */
+  @experimental
   def dir(
       dir: Path = null,
       prefix: String = null,

os/src/ZipOps.scala

@@ -36,6 +36,7 @@ object zip {
    * @param compressionLevel number from 0-9, where 0 is no compression and 9 is best compression. Defaults to -1 (default compression)
    * @return The path to the created ZIP archive.
    */
+  @experimental
   def apply(
       dest: os.Path,
       sources: Seq[ZipSource] = List(),
@@ -265,6 +266,7 @@ object unzip {
    * @param dest     The path to the destination directory for extracted files.
    * @param excludePatterns A list of regular expression patterns to exclude files during extraction. (Optional)
    */
+  @experimental
   def stream(
       source: geny.Readable,
       dest: os.Path,

os/src/experimental.scala

@@ -0,0 +1,8 @@
+package os
+
+import scala.annotation.StaticAnnotation
+
+/**
+ * Annotation to mark experimental API, which is not guaranteed to stay.
+ */
+class experimental extends StaticAnnotation {}

os/test/src/ManipulatingFilesFoldersTests.scala

@@ -39,7 +39,7 @@ object ManipulatingFilesFoldersTests extends TestSuite {
             |And I look good on the barbecue""".stripMargin
       }
       test("checker") - prepChecker { wd =>
-        intercept[ReadDenied] {
+        intercept[WriteDenied] {
           os.move(rd / "folder1/one.txt", wd / "folder1/File.txt")
         }
         os.list(wd / "folder1") ==> Seq(wd / "folder1/one.txt")