ServerJS/API/file - Revision history

KrisKowal at 23:35, 17 May 2009

2009-05-17T23:35:57Z

← Older revision		Revision as of 23:35, 17 May 2009
Line 1:		Line 1:
	Moved to [[ServerJS/~~File~~]] and the original proposal at [[ServerJS/~~File~~/A]].		Moved to [[ServerJS/Filesystem_API]] and the original proposal at [[ServerJS/Filesystem_API/A]].

KrisKowal: Moved to ServerJS/File/A

2009-05-17T23:25:49Z

Moved to ServerJS/File/A

Show changes

Mob: /* Tier 1 */ Added some drive-path specific text. Removed ROOT.

2009-04-26T21:43:35Z

Tier 1: Added some drive-path specific text. Removed ROOT.

← Older revision		Revision as of 21:43, 26 April 2009
Line 9:		Line 9:

	* SEPARATOR "/" or system specific analog, like ":" or "\".		* SEPARATOR "/" or system specific analog, like ":" or "\".
	* PARENT ".." or system specific analog.
	* SELF "." or system specific analog.
	* ROOT "/" or system specific analog, like "C:\".


	The File System API would provide the following methods:		The File System API would provide the following methods:
Line 18:		Line 14:
	* join(...paths:Strings...): takes a variadic list of path Strings, joins them on the directory separator, and normalizes the result.		* join(...paths:Strings...): takes a variadic list of path Strings, joins them on the directory separator, and normalizes the result.

	* split(path:String): returns a string split on the file system's directory separator.		* split(path:String): returns a string split on the file system's directory separator. The split() method will return an empty string as the first element for absolute paths that do not contain drives. For file systems with drives (such as windows), the first element will be the drive with colon if the path contained a drive specification. The intent is so that join with the SEPARATOR will correctly join the elements to reconstitute the path.

	* resolve(...paths:Strings...): marches through a list of variadic absolute or relative path Strings, resolving the next path relative to the previous and returning the ultimate destination path. This is analogous to navigating to the fully qualified URL of a relative URL on a given page. Unlike "join", which presumes that the base path is always a directory, "resolve" considers a directory separator at the end of a path an indication that the path must be resolved off of the directory rather than the leaf "file". For example, resolve("a", "b") returns "b", but resolve("a/", "b") returns "a/b" on a system with "/" as its directory separator. Resolving a fully qualified path relative to any base path returns the fully qualified path, like resolve("a", "/") == "/". Resolve is purely a string manipulation routine and does not use information about the underlying file system.		* resolve(...paths:Strings...): marches through a list of variadic absolute or relative path Strings, resolving the next path relative to the previous and returning the ultimate destination path. This is analogous to navigating to the fully qualified URL of a relative URL on a given page. Unlike "join", which presumes that the base path is always a directory, "resolve" considers a directory separator at the end of a path an indication that the path must be resolved off of the directory rather than the leaf "file". For example, resolve("a", "b") returns "b", but resolve("a/", "b") returns "a/b" on a system with "/" as its directory separator. Resolving a fully qualified path relative to any base path returns the fully qualified path, like resolve("a", "/") == "/". Resolve is purely a string manipulation routine and does not use information about the underlying file system.
Line 58:		Line 54:

	* write(path, content, [mode, [options]]): opens, writes, flushes, and closes a file with the given content.		* write(path, content, [mode, [options]]): opens, writes, flushes, and closes a file with the given content.


	= Tier 2 =		= Tier 2 =

KrisKowal: Fixes pointed out by tlrobinson.

2009-04-25T08:19:59Z

Fixes pointed out by tlrobinson.

← Older revision		Revision as of 08:19, 25 April 2009
Line 79:		Line 79:
	* BinaryReadStream		* BinaryReadStream
	** read() -> all:ByteString		** read() -> all:ByteString
	** read(max:Number) -> actual:~~Number~~		** read(max:Number) -> actual:ByteString
	** readInto(buffer:Array\|ByteArray, [begin:Number, [end:Number]]) -> actual:Number		** readInto(buffer:Array\|ByteArray, [begin:Number, [end:Number]]) -> actual:Number
	** available() -> Number -- how many bytes are ready to be read (buffered) without blocking.		** available() -> Number -- how many bytes are ready to be read (buffered) without blocking.
Line 90:		Line 90:
	** tell() -> position:Number)		** tell() -> position:Number)
	** seek(position:Number, whence:enumerated)		** seek(position:Number, whence:enumerated)
			** rewind() -- returns the read/write head to the beginning of the file
			** truncate([size:Number]) -- sets the length of the file. size defaults to the current position as reported by tell(). If a size is explicated, truncate also seeks to the new end.
	* TextReadStream		* TextReadStream
	** raw -> a BinaryReadStream		** raw -> a BinaryReadStream
			** read() -> String -- returns all remaining characters
			** read(max:Number) -> String -- returns up to max characters, with the length of the returned string reflecting the actual number read.
	** readLine() -> String -- returns "" if no data is available before EOF. Otherwise, includes the "recordSeparator".		** readLine() -> String -- returns "" if no data is available before EOF. Otherwise, includes the "recordSeparator".
	** readLines() -> Array * String		** readLines() -> Array * String

KrisKowal at 06:27, 25 April 2009

2009-04-25T06:27:12Z

← Older revision		Revision as of 06:27, 25 April 2009
Line 66:		Line 66:
	* open(path, mode, {options}) or open({options})		* open(path, mode, {options}) or open({options})
	*# options may include {path, mode, charset, recordSeparator, fieldSeparator} and more in a later, more detailed specification.		*# options may include {path, mode, charset, recordSeparator, fieldSeparator} and more in a later, more detailed specification.
	*# The mode is a String and may contain:		*# The mode is a String and may additionally contain:
	*## "b" for ByteArray and ByteString streams.		*## "b" for ByteArray and ByteString streams.
	*## "t" for String and Array streams (default)		*## "t" for String and Array streams (default)
Line 81:		Line 81:
	** read(max:Number) -> actual:Number		** read(max:Number) -> actual:Number
	** readInto(buffer:Array\|ByteArray, [begin:Number, [end:Number]]) -> actual:Number		** readInto(buffer:Array\|ByteArray, [begin:Number, [end:Number]]) -> actual:Number
			** available() -> Number -- how many bytes are ready to be read (buffered) without blocking.
			** skip(n:Number) -> advance the read head past these bytes.
	* BinaryWriteStream		* BinaryWriteStream
	** write(buffer:Array\|ByteArray\|ByteString)		** write(buffer:Array\|ByteArray\|ByteString)
			** truncate(length:Number=0)
	** flush()		** flush()
	* BinaryRandomStream < BinaryReadStream < BinaryWriteStream		* BinaryRandomStream < BinaryReadStream < BinaryWriteStream
Line 93:		Line 96:
	** next() -> String -- throws a StopIteration if no data is available before EOF.		** next() -> String -- throws a StopIteration if no data is available before EOF.
	** input() -> returns "readLine" without the "recordSeparator".		** input() -> returns "readLine" without the "recordSeparator".
			** available() -> Number -- how many characters are ready to be read (buffered) without blocking.
			** skip(n:Number) -> advance the read head past these characters.
	* TextWriteStream		* TextWriteStream
	** raw -> a BinaryWriteStream		** raw -> a BinaryWriteStream
Line 159:		Line 164:
	*# stat() -> stat:Object {mtime:Date, size:Number}		*# stat() -> stat:Object {mtime:Date, size:Number}
	*# to(path:String\|Path) -> path:Path -- an alias for "relative" that finds the relative path from this path to the given one.		*# to(path:String\|Path) -> path:Path -- an alias for "relative" that finds the relative path from this path to the given one.
			*# toString() -> String
	*# touch([mtime:Date])		*# touch([mtime:Date])
	*# write(data:ByteString\|ByteArray\|Array\|String, [mode, [options]])		*# write(data:ByteString\|ByteArray\|Array\|String, [mode, [options]])

KrisKowal: New draft.

2009-04-25T05:44:18Z

New draft.

Show changes

KrisKowal: /* Tier 1 */ added another open syntax option

2009-04-07T23:51:28Z

Tier 1: added another open syntax option

← Older revision		Revision as of 23:51, 7 April 2009
Line 27:		Line 27:
	*# Throws an error if the directory does not exist or is inaccessible.		*# Throws an error if the directory does not exist or is inaccessible.

	* open(path, mode, permissions, encoding) or open(path, {keywords}) or open({keywords}): returns an IO stream object that supports the requested mode and encoding.		* open(path, mode, permissions, encoding) or open(path, mode, {keywords}) or open(path, {keywords}) or open({keywords}): returns an IO stream object that supports the requested mode and encoding.
	*# The encoding must be undefined, "utf-8", or "utf-16". Other encodings may be specified in the future.		*# The encoding must be undefined, "utf-8", or "utf-16". Other encodings may be specified in the future.
	*## An undefined encoding means "binary", and implies that read and write methods will operate on byte array objects (not yet specified) instead of strings. The "cookie" returned by "tell" and accepted by "seek" can only be an integer for binary encoding (although this tier does not specify those methods).		*## An undefined encoding means "binary", and implies that read and write methods will operate on byte array objects (not yet specified) instead of strings. The "cookie" returned by "tell" and accepted by "seek" can only be an integer for binary encoding (although this tier does not specify those methods).

MrN: /* Tier 1 */ add keyword open thingie

2009-04-07T23:36:33Z

Tier 1: add keyword open thingie

← Older revision		Revision as of 23:36, 7 April 2009
Line 27:		Line 27:
	*# Throws an error if the directory does not exist or is inaccessible.		*# Throws an error if the directory does not exist or is inaccessible.

	* open(path, mode, permissions, encoding): returns an IO stream object that supports the requested mode and encoding.		* open(path, mode, permissions, encoding) or open(path, {keywords}) or open({keywords}): returns an IO stream object that supports the requested mode and encoding.
	*# The encoding must be undefined, "utf-8", or "utf-16". Other encodings may be specified in the future.		*# The encoding must be undefined, "utf-8", or "utf-16". Other encodings may be specified in the future.
	*## An undefined encoding means "binary", and implies that read and write methods will operate on byte array objects (not yet specified) instead of strings. The "cookie" returned by "tell" and accepted by "seek" can only be an integer for binary encoding (although this tier does not specify those methods).		*## An undefined encoding means "binary", and implies that read and write methods will operate on byte array objects (not yet specified) instead of strings. The "cookie" returned by "tell" and accepted by "seek" can only be an integer for binary encoding (although this tier does not specify those methods).

KrisKowal: /* Tier 2 */ fixed a link.

2009-04-07T21:04:37Z

Tier 2: fixed a link.

← Older revision		Revision as of 21:04, 7 April 2009
Line 44:		Line 44:
	= Tier 2 =		= Tier 2 =

	In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names\|proposed names].		In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names proposed names].

KrisKowal: Moved close under open.

2009-04-04T17:29:14Z

Moved close under open.

← Older revision		Revision as of 17:29, 4 April 2009
Line 40:		Line 40:
	*# The path is resolved relative to the current working directory.		*# The path is resolved relative to the current working directory.
	*# Throws an error if the specified stream cannot be created.		*# Throws an error if the specified stream cannot be created.
	* close(): Closes the ~~file~~. Should be called automatically when the mode is changed, and when the garbage collector collects its last reference.		*# close(): Closes the stream. Should be called automatically when the mode is changed, and when the garbage collector collects its last reference.

	= Tier 2 =		= Tier 2 =

	In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names\|proposed names].		In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names\|proposed names].