Hello again!
Attached is the updated proposal, taking received user comments into
account and noting functions that have been implemented as of the
present day. Feel free to continue the conversation!
Thanks,
Lydia Duncan
On 09/05/2014 09:49 AM, Lydia Duncan wrote:
Hello Chapel users!
We're looking into implementing more file library functions in the
near future and are looking for some community feedback. Please take
some time in the coming weeks to look over the high level document
(fileProposal.txt) and the more detailed function description
(fileProposalDetails.chpl). We would like to know your thoughts on
the proposal, as well as a list of 10 functions you'd like to see take
priority over the others.
Thanks for your time, and your continued interest in Chapel!
Lydia Duncan
(Chapel team)
------------------------------------------------------------------------------
Slashdot TV.
Video for Nerds. Stuff that matters.
http://tv.slashdot.org/
_______________________________________________
Chapel-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/chapel-users
This proposal involves adding more file manipulation capabilities to Chapel.
Please review the full description of the proposed functions and provide
suggestions for alternate/additional functionality if desired, as well as a list
of the 6-12 functions you would want implemented first.
For context, a file record is currently defined as follows:
record file {
var home: locale = here;
var _file_internal:qio_file_ptr_t = QIO_FILE_PTR_NULL;
}
It has an init copy function, an assignment function, and a destructor,
as well as a check method which will halt if _file_internal is nil.
There are various methods to obtain the path of the file, a getter for
its style, a sync method (fsync) and a method to close the file. More details
on iostyles can be found in README.io within the release documentation.
Files can be created and opened using one of five methods: open, openfd (which
requires a C file descriptor), openfp (which requires a C file pointer),
opentmp, and openmem. opentmp creates a temporary file that is deleted upon
closing, and openmem does the same thing but using a buffer in memory. They
can only be written to and read from using a channel record, which are obtained
by calling <file>.writer and <file>.reader with the appropriate arguments.
Most of these functions have two versions: one which returns an error and one
which halts with an error message if one occurred.
It is considered an error to perform I/O operations on a file once it has been
closed, or to have channels open when the file is closed.
Through this proposal, we seek to expand both the file record capabilities and
the manipulation of files via string specifiers. Most of the current
functionality will remain unchanged, with the exception of the
file.path/getPath/tryGetPath methods which will be both expanded and subsumed
by the functions absPath, realPath, and relPath and their respective file
methods.
Where the operation(s) taken by a function can result in an error, two versions
of the function will be provided: one which could halt with an error message if
an error occurred that we or the system could detect, and one which will return
any such error code via a syserr object of out intent named error. We
recommend that you utilize the former function.
The following functions (in alphabetical order) are thought capable of being
added in Chapel's current state:
Both file and directory related
realPath
remove
sameFile
umask
File specific functions
chmod
chown
copy
copy2
copyFile
copyMode
exists
isFile
isLink
file.realPath
rename
sameOpenFile
symlink
viewMode
Directory specific functions
copyTree
isDir
isMount
mkdir
moveDir
rmTree
Environment related
chdir
curDir
cwd
parentDir
The following functions (in alphabetical order) are desired but will remain
unimplemented until our string capabilities have expanded:
Both file and directory related
absPath
commonPrefix
isAbsPath
join
normCase
normPath
relPath
split
File specific functions
file.absPath
basename
file.getParentName
file.relPath
Directory specific functions
dirname
listDir
Environment related
expandUser
expandVars
For descriptions of what these functions will entail, please see the other file
attached.
/* Change the current working directory of the current locale to the specified
name. May generate an error message (for instance, if the specified
directory does not exist).
name: a string indicating a new directory.
Note: this is not safe within a parallel context. A chdir call in one task
will affect the current working directory of all tasks for that locale.
IMPLEMENTED
*/
proc chdir(name: string);
/* The intention is to provide constant values of the form
S_I[R | W | X][USR | GRP | OTH], S_IRWX[U | G | O], S_ISUID, S_ISGID,
or S_ISVTX, where R corresponds to readable, W corresponds to writable,
X corresponds to executable, USR and U correspond to user, GRP and G
correspond to group, OTH and O correspond to other, directly tied to
the C idea of these constants. These would be capable of being used
with the chmod function, and capable of being checked against in the
general view function
*/
/* Set the permissions of the file or directory specified by name to that
indicated by settings, and may generate an error message
name: the name of the file/directory which should have its permissions
alterred.
mode: an integer representing the permissions desired for the file
in question. See description of the provided constants for potential
values.
*/
proc chmod(name: string, mode: int);
/* Changes one or both of the owner and group id of the named file to the
specified values. If uid or gid are -1, the value in question will remain
unchanged. May generate an error message.
name: the name of the file to be changed.
uid: user id to use as new owner, or -1 if it should remain the same.
gid: group id to use as the new group owner, or -1 if it should remain the
same.
IMPLEMENTED
*/
proc chown(name: string, uid: int, gid: int);
/* Copies the contents and permissions of the file indicated by src into
the file or directory dest. If dest is a directory, will create or
overwrite a file with the same basename as src in dest. If metadata is
set to true, will also copy the metadata of the file to be copied. May
generate an error message.
src: the source file whose contents and permissions are to be copied
dest: the destination directory or file of the contents and permissions.
metadata: a boolean indicating whether to copy metadata associated with the
source file.
*/
proc copy(src: string, dest: string, metadata: bool = false);
/* Copies the contents of the file indicated by src into the file indicated
by dest, replacing dest if it already exists (and is different than src).
If the dest is not writable or src and dest are the same file, generates
an error. Does not copy metadata. May generate an error message.
src: the source file whose contents are to be copied.
dest: the destination of the contents.
*/
proc copyFile(src: string, dest: string);
/* Copies the permissions of the file indicated by src to the file indicated
by dest, leaving contents, owner and group unaffected. May generate an error
message.
src: the source file whose permissions are to be copied.
dest: the destination of the permissions.
*/
proc copyMode(src: string, dest: string);
/* Will recursively copy the tree which starts at src into dst, including all
contents, permissions, and metadata. dst must not previously exist, this
function assumes it can create it and any missing parent directories.
If copySymbolically is true, symlinks will be copied as symlinks, otherwise
their contents and metadata will be copied. May generate an error message.
src: the root of the source tree to be copied.
dest: the root of the destination directory where the tree where the tree is
to be copied (must not exist prior to this function call).
copySymbolically: a boolean indicating how to handle symlinks in the
source directory.
*/
proc copyTree(src: string, dest: string, copySymbolically: bool=false);
/* Returns a constant string representing the current directory according to
the operating system. For Windows and POSIX, this is "."
*/
proc curDir(): string;
/* Returns the current working directory for the current locale, which is
equivalent to realPath(curDir()).
Note: another task on this locale can change the current working
directory from underneath this task, so use caution when making use
of this function in a parallel environment.
IMPLEMENTED
*/
proc cwd(): string;
/* Returns true if the provided filename corresponds to an existing file,
false otherwise.
name: a string used to attempt to find the file specified.
*/
proc exists(name: string): bool;
/* Returns true if the name corresponds to a file, false otherwise.
name: a string that could be the name of a file.
IMPLEMENTED
*/
proc isFile(name: string): bool;
/* Returns true if the name corresponds to a directory, false otherwise.
name: a string that could be the name of a directory.
IMPLEMENTED
*/
proc isDir(name: string): bool;
/* Returns true if the name corresponds to a symbolic link, false if not
or if symbolic links are not supported.
name: a string that could be the name of a symbolic link.
*/
proc isLink(name: string): bool;
/* Returns true if the name corresponds to a mount point, false otherwise.
name: a string that could be the name of a mount point.
*/
proc isMount(name: string): bool;
/* Attempt to create a directory with the given path. If parents is true,
will attempt to create any directory in the path that did not previously
exist. May generate an error message.
name: the name of the directory to be created, fully specified.
mode: an integer representing the permissions desired for the file
in question. See description of the provided constants for potential
values.
parents: a boolean indicating if parent directories should be created.
If set to false, any nonexistent parent will cause an error to
occur.
IMPLEMENTED
*/
proc mkdir(name: string, mode: int = 0o777, parents: bool=false);
/* Recursively moves the directory indicated by src and its contents to the
destination denoted by dest. If dest is a directory, src is moved inside
of it. May generate an error message.
src: the location of the directory to be moved
dest: the location to move it to.
*/
proc moveDir(src: string, dest: string);
/* Returns a constant string representing the parent directory according to
the operating system. In Windows and POSIX, this is ".."
*/
proc parentDir(): string;
/* Returns the canonical path specified, eliminating symbolic links. May
generate an error message.
name: a string representing a valid path.
*/
proc realPath(name: string): string;
// Note that the file record already has some path related methods, but
// that they do not specify the format in which the path is returned. This
// and other methods will expand/reuse the functionality previously provided.
/* Returns the canonical path referred to by the file record, eliminating
symbolic links.
*/
proc file.realPath(): string;
/* Renames the file specified by oldname to newname, and may generate an error
message. The file is not opened during this operation.
oldname: current name of the file
newname: name which should refer to the file in the future.
IMPLEMENTED
*/
proc rename(oldname: string, newname: string);
/* Removes the file or directory specified by name, and may generate an error
message while deleting the initial file/directory. If parents
is true, will remove all directories emptied as a result of removing
this file/directory.
name: the name of the file/directory to remove
parents: a boolean indicating whether to remove emptied parent
directories
IMPLEMENTED (except for the recursive portion)
*/
proc remove(name: string, parents: bool=false);
/* Delete the entire directory tree specified by root, and may generate an error
message.
root: path name representing a directory that should be deleted along with
its entire contents.
*/
proc rmTree(root: string);
/* Returns true if both pathnames refer to the same file or directory
(utilizing operating system operations rather than string ones), returns
false otherwise. May generate an error message.
file1, file2: string representations of paths to be compared.
*/
proc sameFile(file1: string, file2: string): bool;
/* Same as the above function, but taking file records instead of string
pathnames as arguments. May generate an error message.
*/
proc sameFile(file1: file, file2: file): bool;
/* Create a symbolic link pointing to actual named sym. May generate an error
message.
actual: the source file to be linked
symLink: the location the symbolic link should live
*/
proc symlink(actual: string, symLink: string);
/* Sets the file creation mask of the current process to mask, and returns
the previous value of the file creation mask. May generate an error message.
mask: the file creation mask to use now.
*/
proc umask(mask: int): int;
/* Returns an integer representing the current permissions of the file specified
by name. May generate an error message.
name: the name of the file that you want to know the permissions of.
*/
proc viewMode(name: string): int;
/*
These functions should wait until the string library has been fleshed out
*/
/* Return an absolute version of the path specified. Equivalent to the call
normPath(joinPath(cwd(), name)) when the path is not already absolute and
returns the original string otherwise.
name: the path whose absolute path is desired.
*/
proc absPath(name: string): string;
/* Return an absolute version of the path in this file. Equivalent to the call
normPath(joinPath(cwd(), file.path)) when the path is not already absolute
and returns the original file.path otherwise.
*/
proc file.absPath(): string;
/* Returns the basename of the file name provided. For instance, in the
name "/foo/bar/baz", this function would return "baz", while "/foo/bar/"
would yield the empty string. Note that this is different from the Unix
basename function.
name: a string file name. Note that this string does not have to be
a valid file name, as the file itself will not be affected.
*/
proc basename(name: string): string;
/* Returns the parent directory of the file name provided. For instance,
in the name "/foo/bar/baz", this function would return "/foo/bar", as
would a call with "/foo/bar/" as the argument.
name: a string file name. Note that this string does not have to be
a valid file name, as the file itself will not be affected.
*/
proc dirname(name: string): string;
/* Returns the parent directory of the file record. For instance, a file
with path "/foo/bar/baz" would return "/foo/bar"
*/
proc file.getParentName(): string;
/* Returns the longest common path prefix (taken character-by-character) of
all the string pathnames provided. If no arguments are specified, returns
the empty string.
*/
proc commonPrefix(paths: string ...?n): string;
// Should I add an array version of common prefix?
/* Returns the argument. If the argument begins with ~ or ~<user>, replace
that substring with that user's home directory, otherwise returns the
argument unchanged.
path: a string representation of a file or directory, which may or may
not include ~ or ~<user>
*/
proc expandUser(path: string): string;
/* Expands any environment variables in the path of the form $<name> or
${<name>} into their values. If <name> does not exist, they are left
in place. Returns the path which includes these expansions.
path: a string representation of a path, which may or may not include
$<name> or ${<name>}. */
proc expandVars(path: string): string;
/* Returns true if the path specified is an absolute path, false otherwise
name: the path to be checked.
*/
proc isAbsPath(name: string): bool;
/* Join and return one or more paths, putting precedent on the last absolute
path seen. Return value is the concatentation of the paths with one
directory separator following each non-empty argument except the last.
As an example: joinPath("/foo/bar", "/baz") yields "/baz", while
joinPath("/foo", "./baz") and joinPath("/foo/", "", "./baz") would yield
"/foo/./baz"
*/
proc joinPaths(paths: string ...?n): string;
/* Returns an array containing the names of the entries in the directory
specified by name. No particular ordering is guaranteed and "." and ".."
are not included in the entries listed. May generate an error message.
name: the directory to obtain entries from.
*/
proc listDir(name: string): [] string
// Under the covers, this should obtain a large string from the C code, then
// make use of string.split to obtain the array.
/* For case-insensitive file systems, alters path to lowercase. On Windows,
additionally converts forward slashes to back-slashes. For case-sensitive
file systems, this will return the path unaltered and generate a warning
to the user that the action could not be taken.
name: a potential path to convert to lowercase if that would not alter
the meaning of the path.
*/
proc normCase(name: string): string;
/* Collapse paths such as "foo//bar", "foo/bar/", "foo/./bar", and
"foo/baz/../bar" into "foo/bar". Warning: may alter meaning of paths
containing symbolic links. Similar to normCase, on Windows will replace
forward slashes.
name: a potential path to collapse, possibly destroying the meaning of the
path if symbolic links were included.
*/
proc normPath(name: string): string;
/* Returns a relative path to the named path from the current directory.
The filesystem is not accessed to verify the existence of the named path.
name: a path which the caller would like to access from the current
directory.
*/
proc relPath(name: string): string;
/* Returns a relative path to the named path from the specified start directory.
The filesystem is not accessed to verify the existence of the named path or
the specified starting location.
name: a path which the caller would like to access.
start: the location from which access to name is desired.
*/
proc relPath(name: string, start: string): string;
/* There should also be two methods on a file record with the same purpose
and which use the record's filename in place of the first argument in the
two versions of relpath listed above: */
proc file.relPath(): string;
proc file.relPath(start: string): string;
/* Split name into a tuple that is equivalent to (dirname(), basename()).
The second part of the tuple will never contain a slash. Examples:
splitPath("foo/bar") will yield ("foo", "bar")
splitPath("bar") will yield ("", "bar")
splitPath("foo/") will yield ("foo", "")
splitPath("") will yield ("", "")
splitPath("/") will yield ("/", "")
name: path to be split.
*/
proc splitPath(name: string): (string, string);
------------------------------------------------------------------------------
Slashdot TV. Videos for Nerds. Stuff that Matters.
http://pubads.g.doubleclick.net/gampad/clk?id=160591471&iu=/4140/ostg.clktrk
_______________________________________________
Chapel-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/chapel-users
