From 600b4adf8980168a45551537575b4656ba2e0f36 Mon Sep 17 00:00:00 2001 From: Alex Snezhko Date: Mon, 2 Sep 2024 14:18:10 -0700 Subject: [PATCH] Address review feedback --- compiler/test/stdlib/fs.test.gr | 23 ++++++------ stdlib/fs.gr | 65 +++++++++++++++++---------------- stdlib/fs.md | 44 +++++++++++----------- 3 files changed, 68 insertions(+), 64 deletions(-) diff --git a/compiler/test/stdlib/fs.test.gr b/compiler/test/stdlib/fs.test.gr index d7ff3e956..76c41dac8 100644 --- a/compiler/test/stdlib/fs.test.gr +++ b/compiler/test/stdlib/fs.test.gr @@ -114,16 +114,17 @@ assert Fs.readDir(baseDirPath=Some(testPath("test-dir")), path("dir")) == Ok([{ name: "nested.txt", fileType: Fs.File }]) assert Fs.readDir(path("test/nonexisting")) == Err(Fs.NoSuchFileOrDirectory) -// makeDir +// createDir assert !Fs.exists(testPath("dir2")) -assert Fs.makeDir(testPath("dir2")) == Ok(void) +assert Fs.createDir(testPath("dir2")) == Ok(void) assert Fs.readDir(testPath("dir2")) == Ok([]) -assert Fs.makeDir(baseDirPath=Some(testPath("dir2")), path("inner")) == Ok(void) +assert Fs.createDir(baseDirPath=Some(testPath("dir2")), path("inner")) == + Ok(void) assert Fs.readDir(testPath("dir2")) == Ok([{ name: "inner", fileType: Fs.Directory }]) -assert Fs.makeDir(testPath("dir2")) == Err(Fs.FileExists) +assert Fs.createDir(testPath("dir2")) == Err(Fs.FileExists) // readLink assert Fs.readLink(testPath("test-dir/link")) == Ok(path("file1.txt")) @@ -132,17 +133,17 @@ assert Fs.readLink(baseDirPath=Some(testPath("test-dir")), path("link")) == assert Fs.readLink(testPath("blahblah")) == Err(Fs.NoSuchFileOrDirectory) assert Fs.readLink(testPath("foo.txt")) == Err(Fs.InvalidArgument) -// makeSymlink +// createSymlink assert !Fs.exists(testPath("symlink")) -assert Fs.makeSymlink(path("foo.txt"), testPath("symlink")) == Ok(void) +assert Fs.createSymlink(path("foo.txt"), testPath("symlink")) == Ok(void) assert Fs.readLink(testPath("symlink")) == Ok(path("foo.txt")) assert Result.unwrap(Fs.stats(testPath("symlink"), followSymlink=false)).fileType == Fs.SymbolicLink assert Result.unwrap(Fs.stats(testPath("symlink"), followSymlink=true)).fileType == Fs.File -assert Fs.makeSymlink(path("bar.txt"), testPath("symlink")) == +assert Fs.createSymlink(path("bar.txt"), testPath("symlink")) == Err(Fs.FileExists) -assert Fs.makeSymlink( +assert Fs.createSymlink( path("bar.txt"), targetBaseDirPath=Some(testPath("test-dir")), path("symlink") @@ -199,7 +200,7 @@ assert Result.unwrap( ).fileType == Fs.File -assert Fs.makeSymlink(path("test-dir"), testPath("linktodir")) == Ok(void) +assert Fs.createSymlink(path("test-dir"), testPath("linktodir")) == Ok(void) assert Fs.copy( testPath("linktodir"), testPath("copied-link-to-dir"), @@ -255,7 +256,7 @@ assert Fs.Utf8.readFile(testPath("boofar.txt")) == // remove assert Fs.remove(testPath("baz.txt")) == Ok(void) assert Fs.remove(testPath("newdir")) == Err(Fs.IsADirectory) -assert Fs.makeDir(testPath("newdir/innerdir")) == Ok(void) +assert Fs.createDir(testPath("newdir/innerdir")) == Ok(void) assert Fs.remove(testPath("newdir"), removeMode=Fs.RemoveEmptyDirectory) == Err(Fs.DirectoryNotEmpty) assert Fs.remove( @@ -264,7 +265,7 @@ assert Fs.remove( removeMode=Fs.RemoveEmptyDirectory ) == Ok(void) -assert Fs.makeDir(testPath("newdir/innerdir")) == Ok(void) +assert Fs.createDir(testPath("newdir/innerdir")) == Ok(void) assert Fs.Utf8.writeFile(testPath("newdir/innerdir/file.txt"), "content") == Ok(void) assert Fs.remove(testPath("newdir"), removeMode=Fs.RemoveRecursive) == Ok(void) diff --git a/stdlib/fs.gr b/stdlib/fs.gr index c7f25bc65..a7b2d37af 100644 --- a/stdlib/fs.gr +++ b/stdlib/fs.gr @@ -6,7 +6,7 @@ * @example Fs.Utf8.writeFile(Path.fromString("baz.txt"), "Hello World\n") * @example Fs.copy(Path.fromString("foo.txt"), Path.fromString("foocopy.txt")) * - * @since v0.6.5 + * @since v0.6.7 */ module Fs @@ -215,7 +215,7 @@ provide record Stats { } /** - * Represents information about an item in a directory + * Represents information about an item in a directory. */ provide record DirectoryEntry { name: String, @@ -528,18 +528,18 @@ let rec removeRecursive = (parentFd, path) => { /** * Removes a file or directory. * + * @param removeMode: The type of removal to perform; `RemoveFile` by default * @param baseDirPath: The path to the directory in which path resolution starts * @param path: The path of the file or directory to remove - * @param removeMode: The type of removal to perform; `RemoveFile` by default * @returns `Ok(void)` if the operation succeeds, `Err(err)` if a file system error is encountered * * @example Fs.remove(Path.fromString("file.txt")) // removes a file - * @example Fs.remove(Path.fromString("dir"), removeMode=Fs.RemoveEmptyDirectory) // removes an empty directory - * @example Fs.remove(Path.fromString("dir"), removeMode=Fs.RemoveRecursive) // removes the directory and its contents + * @example Fs.remove(removeMode=Fs.RemoveEmptyDirectory, Path.fromString("dir")) // removes an empty directory + * @example Fs.remove(removeMode=Fs.RemoveRecursive, Path.fromString("dir")) // removes the directory and its contents * - * @since v0.6.5 + * @since v0.6.7 */ -provide let remove = (baseDirPath=None, path, removeMode=RemoveFile) => { +provide let remove = (removeMode=RemoveFile, baseDirPath=None, path) => { let (baseDirPath, path) = getBaseDirAndPath(baseDirPath, path) match (removeMode) { RemoveFile => @@ -570,7 +570,7 @@ provide let remove = (baseDirPath=None, path, removeMode=RemoveFile) => { * @param path: The path to the directory to read * @returns `Ok(contents)` containing the directory contents or `Err(err)` if a file system error is encountered * - * @since v0.6.5 + * @since v0.6.7 */ provide let readDir = (baseDirPath=None, path) => { let path = joinPathOnBaseDir(baseDirPath, path) @@ -592,9 +592,9 @@ provide let readDir = (baseDirPath=None, path) => { * @param path: The path to create the new directory, relative to the base directory * @returns `Ok(void)` if the operation succeeds, `Err(err)` if a file system error is encountered * - * @since v0.6.5 + * @since v0.6.7 */ -provide let makeDir = (baseDirPath=None, path) => { +provide let createDir = (baseDirPath=None, path) => { let (baseDirPath, path) = getBaseDirAndPath(baseDirPath, path) fileOp( baseDirPath, @@ -611,9 +611,9 @@ provide let makeDir = (baseDirPath=None, path) => { * @param targetPath: The path to the target of the link * @returns `Ok(void)` if the operation succeeds, `Err(err)` if a file system error or relativization error is encountered * - * @since v0.6.5 + * @since v0.6.7 */ -provide let makeSymlink = (linkContents, targetBaseDirPath=None, targetPath) => { +provide let createSymlink = (linkContents, targetBaseDirPath=None, targetPath) => { let (targetBaseDirPath, targetPath) = getBaseDirAndPath( targetBaseDirPath, targetPath @@ -633,14 +633,14 @@ provide let makeSymlink = (linkContents, targetBaseDirPath=None, targetPath) => /** * Queries information about a file. * + * @param followSymlink: Whether to follow symlinks or not; if `true` then the stats of a valid symlink's underlying file will be returned. `true` by default * @param baseDirPath: The path to the directory in which the path resolution starts * @param path: The path of the file to query - * @param followSymlink: Whether to follow symlinks or not; if `true` then the stats of a valid symlink's underlying file will be returned. `true` by default * @returns `Ok(stats)` containing metadata or `Err(err)` if a file system error is encountered * - * @since v0.6.5 + * @since v0.6.7 */ -provide let stats = (baseDirPath=None, path, followSymlink=true) => { +provide let stats = (followSymlink=true, baseDirPath=None, path) => { let (baseDirPath, path) = getBaseDirAndPath(baseDirPath, path) let statsResult = fileOp(baseDirPath, Stats, dirFd => { File.pathFilestats( @@ -669,7 +669,7 @@ provide let stats = (baseDirPath=None, path, followSymlink=true) => { * @param path: The path of the file to query * @returns `true` if a file or directory exists at the path or `false` otherwise * - * @since v0.6.5 + * @since v0.6.7 */ provide let exists = (baseDirPath=None, path) => { stats(baseDirPath=baseDirPath, path, followSymlink=false) != @@ -695,7 +695,7 @@ let readLinkHelper = (dirFd, path, stats: File.Filestats) => { * @param path: The path to the link to read * @returns `Ok(path)` containing the link contents or `Err(err)` if a file system error is encountered * - * @since v0.6.5 + * @since v0.6.7 */ provide let readLink = (baseDirPath=None, path) => { let (baseDirPath, path) = getBaseDirAndPath(baseDirPath, path) @@ -866,20 +866,21 @@ let rec copyRecursive = ( /** * Copies a file or directory. * + * @param copyMode: The type of copy to perform; `CopyFile` by default + * @param followSymlink: Whether to follow symlinks or not; if `true` then the stats of a valid symlink's underlying file will be returned. `true` by default * @param sourceBaseDirPath: The path to the directory in which the source path resolution starts * @param sourcePath: The path of the file or directory to copy * @param targetBaseDirPath: The path to the directory in which the target path resolution starts * @param targetPath: The path to copy the file or directory to - * @param copyMode: The type of copy to perform; `CopyFile` by default * @returns `Ok(void)` if the operation succeeds, `Err(err)` if a file system error is encountered */ provide let copy = ( + copyMode=CopyFile, + followSymlink=true, sourceBaseDirPath=None, sourcePath, targetBaseDirPath=None, targetPath, - copyMode=CopyFile, - followSymlink=true, ) => { let (sourceBaseDirPath, sourcePath) = getBaseDirAndPath( sourceBaseDirPath, @@ -913,7 +914,7 @@ provide let copy = ( * @param targetPath: The new path of the file * @returns `Ok(void)` if the operation succeeds, `Err(err)` if a file system error is encountered * - * @since v0.6.5 + * @since v0.6.7 */ provide let rename = ( sourceBaseDirPath=None, @@ -950,7 +951,7 @@ provide let rename = ( /** * Functionality for reading and writing `Bytes` to files. * - * @since v0.6.5 + * @since v0.6.7 */ provide module Binary { /** @@ -960,7 +961,7 @@ provide module Binary { * @param path: The file path to read from * @returns `Ok(contents)` containing the bytes read if successful or `Err(err)` if a file system error is encountered * - * @since v0.6.5 + * @since v0.6.7 */ provide let readFile = (baseDirPath=None, path) => { let path = joinPathOnBaseDir(baseDirPath, path) @@ -978,15 +979,15 @@ provide module Binary { /** * Write `Bytes` to a file. * + * @param writeMode: The type of write operation to perform; `Truncate` by default * @param baseDirPath: The path to the directory to begin path resolution * @param path: The file path to write to * @param data: The bytes to write to the file - * @param writeMode: The type of write operation to perform; `Truncate` by default * @returns `Ok(void)` if the operation is successful or `Err(err)` if a file system error is encountered * - * @since v0.6.5 + * @since v0.6.7 */ - provide let writeFile = (baseDirPath=None, path, data, writeMode=Truncate) => { + provide let writeFile = (writeMode=Truncate, baseDirPath=None, path, data) => { let path = joinPathOnBaseDir(baseDirPath, path) let openMode = match (writeMode) { Truncate => WriteFile, @@ -1013,7 +1014,7 @@ provide module Binary { /** * Functionality for reading and writing `String`s to files. * - * @since v0.6.5 + * @since v0.6.7 */ provide module Utf8 { /** @@ -1023,7 +1024,7 @@ provide module Utf8 { * @param path: The file path to read from * @returns `Ok(contents)` containing the string read if successful or `Err(err)` if a file system error is encountered * - * @since v0.6.5 + * @since v0.6.7 */ provide let readFile = (baseDirPath=None, path) => { let bytes = Binary.readFile(baseDirPath=baseDirPath, path) @@ -1033,16 +1034,16 @@ provide module Utf8 { /** * Write a `String` to a file. * + * @param writeMode: The type of write operation to perform; `Truncate` by default * @param baseDirPath: The path to the directory to begin path resolution * @param path: The file path to write to * @param data: The string to write to the file - * @param writeMode: The type of write operation to perform; `Truncate` by default * @returns `Ok(void)` if the operation is successful or `Err(err)` if a file system error is encountered * - * @since v0.6.5 + * @since v0.6.7 */ - provide let writeFile = (baseDirPath=None, path, data, writeMode=Truncate) => { + provide let writeFile = (writeMode=Truncate, baseDirPath=None, path, data) => { let bytes = String.encode(data, String.UTF8) - Binary.writeFile(baseDirPath=baseDirPath, path, bytes, writeMode=writeMode) + Binary.writeFile(writeMode=writeMode, baseDirPath=baseDirPath, path, bytes) } } diff --git a/stdlib/fs.md b/stdlib/fs.md index a5f4e2b2b..5e053edb2 100644 --- a/stdlib/fs.md +++ b/stdlib/fs.md @@ -171,7 +171,7 @@ record DirectoryEntry { } ``` -Represents information about an item in a directory +Represents information about an item in a directory. ### Fs.**RemoveMode** @@ -220,7 +220,7 @@ No other changes yet. ```grain remove : - (?baseDirPath: Option, path: Path.Path, ?removeMode: RemoveMode) => + (?removeMode: RemoveMode, ?baseDirPath: Option, path: Path.Path) => Result ``` @@ -230,9 +230,9 @@ Parameters: |param|type|description| |-----|----|-----------| +|`?removeMode`|`RemoveMode`|The type of removal to perform; `RemoveFile` by default| |`?baseDirPath`|`Option`|The path to the directory in which path resolution starts| |`path`|`Path.Path`|The path of the file or directory to remove| -|`?removeMode`|`RemoveMode`|The type of removal to perform; `RemoveFile` by default| Returns: @@ -247,11 +247,11 @@ Fs.remove(Path.fromString("file.txt")) // removes a file ``` ```grain -Fs.remove(Path.fromString("dir"), removeMode=Fs.RemoveEmptyDirectory) // removes an empty directory +Fs.remove(removeMode=Fs.RemoveEmptyDirectory, Path.fromString("dir")) // removes an empty directory ``` ```grain -Fs.remove(Path.fromString("dir"), removeMode=Fs.RemoveRecursive) // removes the directory and its contents +Fs.remove(removeMode=Fs.RemoveRecursive, Path.fromString("dir")) // removes the directory and its contents ``` ### Fs.**readDir** @@ -282,7 +282,7 @@ Returns: |----|-----------| |`Result, FileError>`|`Ok(contents)` containing the directory contents or `Err(err)` if a file system error is encountered| -### Fs.**makeDir** +### Fs.**createDir**
Added in next @@ -290,7 +290,7 @@ No other changes yet.
```grain -makeDir : +createDir : (?baseDirPath: Option, path: Path.Path) => Result ``` @@ -310,7 +310,7 @@ Returns: |----|-----------| |`Result`|`Ok(void)` if the operation succeeds, `Err(err)` if a file system error is encountered| -### Fs.**makeSymlink** +### Fs.**createSymlink**
Added in next @@ -318,7 +318,7 @@ No other changes yet.
```grain -makeSymlink : +createSymlink : (linkContents: Path.Path, ?targetBaseDirPath: Option, targetPath: Path.Path) => Result ``` @@ -348,7 +348,7 @@ No other changes yet. ```grain stats : - (?baseDirPath: Option, path: Path.Path, ?followSymlink: Bool) => + (?followSymlink: Bool, ?baseDirPath: Option, path: Path.Path) => Result ``` @@ -358,9 +358,9 @@ Parameters: |param|type|description| |-----|----|-----------| +|`?followSymlink`|`Bool`|Whether to follow symlinks or not; if `true` then the stats of a valid symlink's underlying file will be returned. `true` by default| |`?baseDirPath`|`Option`|The path to the directory in which the path resolution starts| |`path`|`Path.Path`|The path of the file to query| -|`?followSymlink`|`Bool`|Whether to follow symlinks or not; if `true` then the stats of a valid symlink's underlying file will be returned. `true` by default| Returns: @@ -426,9 +426,10 @@ Returns: ```grain copy : - (?sourceBaseDirPath: Option, sourcePath: Path.Path, - ?targetBaseDirPath: Option, targetPath: Path.Path, - ?copyMode: CopyMode, ?followSymlink: Bool) => Result + (?copyMode: CopyMode, ?followSymlink: Bool, + ?sourceBaseDirPath: Option, sourcePath: Path.Path, + ?targetBaseDirPath: Option, targetPath: Path.Path) => + Result ``` Copies a file or directory. @@ -437,11 +438,12 @@ Parameters: |param|type|description| |-----|----|-----------| +|`?copyMode`|`CopyMode`|The type of copy to perform; `CopyFile` by default| +|`?followSymlink`|`Bool`|Whether to follow symlinks or not; if `true` then the stats of a valid symlink's underlying file will be returned. `true` by default| |`?sourceBaseDirPath`|`Option`|The path to the directory in which the source path resolution starts| |`sourcePath`|`Path.Path`|The path of the file or directory to copy| |`?targetBaseDirPath`|`Option`|The path to the directory in which the target path resolution starts| |`targetPath`|`Path.Path`|The path to copy the file or directory to| -|`?copyMode`|`CopyMode`|The type of copy to perform; `CopyFile` by default| Returns: @@ -530,8 +532,8 @@ No other changes yet. ```grain writeFile : - (?baseDirPath: Option, path: Path.Path, data: Bytes, - ?writeMode: WriteMode) => Result + (?writeMode: WriteMode, ?baseDirPath: Option, path: Path.Path, + data: Bytes) => Result ``` Write `Bytes` to a file. @@ -540,10 +542,10 @@ Parameters: |param|type|description| |-----|----|-----------| +|`?writeMode`|`WriteMode`|The type of write operation to perform; `Truncate` by default| |`?baseDirPath`|`Option`|The path to the directory to begin path resolution| |`path`|`Path.Path`|The file path to write to| |`data`|`Bytes`|The bytes to write to the file| -|`?writeMode`|`WriteMode`|The type of write operation to perform; `Truncate` by default| Returns: @@ -601,8 +603,8 @@ No other changes yet. ```grain writeFile : - (?baseDirPath: Option, path: Path.Path, data: String, - ?writeMode: WriteMode) => Result + (?writeMode: WriteMode, ?baseDirPath: Option, path: Path.Path, + data: String) => Result ``` Write a `String` to a file. @@ -611,10 +613,10 @@ Parameters: |param|type|description| |-----|----|-----------| +|`?writeMode`|`WriteMode`|The type of write operation to perform; `Truncate` by default| |`?baseDirPath`|`Option`|The path to the directory to begin path resolution| |`path`|`Path.Path`|The file path to write to| |`data`|`String`|The string to write to the file| -|`?writeMode`|`WriteMode`|The type of write operation to perform; `Truncate` by default| Returns: