CommonJS Spec Wiki http://wiki.commonjs.org/wiki/CommonJS MediaWiki 1.15.3 first-letter Media Special Talk User User talk CommonJS CommonJS talk File File talk MediaWiki MediaWiki talk Template Template talk Help Help talk Category Category talk Property Property talk Type Type talk Form Form talk Concept Concept talk Filter Filter talk Website Website talk 3 25 2009-04-14T05:39:14Z KrisKowal Added an index of module proposals. Here are sections for proposed standard modules. * [[ServerJS/API/console]] * [[ServerJS/API/system]] * [[ServerJS/API/binary]] * [[ServerJS/API/file]] * [[ServerJS/API/io]] * [[ServerJS/API/ioString]] 26 2009-09-09T22:13:48Z Dantman 1 1 revision:&#32;Import from https://wiki.mozilla.org/ServerJS Here are sections for proposed standard modules. * [[ServerJS/API/console]] * [[ServerJS/API/system]] * [[ServerJS/API/binary]] * [[ServerJS/API/file]] * [[ServerJS/API/io]] * [[ServerJS/API/ioString]] 617 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API]] to [[CommonJS/API]]:&#32;Subpages needed to be enabled Here are sections for proposed standard modules. * [[ServerJS/API/console]] * [[ServerJS/API/system]] * [[ServerJS/API/binary]] * [[ServerJS/API/file]] * [[ServerJS/API/io]] * [[ServerJS/API/ioString]] 784 2009-09-09T22:39:58Z Dantman 1 Robot: Automated text replacement (-ServerJS +CommonJS) Here are sections for proposed standard modules. * [[CommonJS/API/console]] * [[CommonJS/API/system]] * [[CommonJS/API/binary]] * [[CommonJS/API/file]] * [[CommonJS/API/io]] * [[CommonJS/API/ioString]] 965 2009-09-10T03:11:55Z Dantman 1 {{Old}} Here are sections for proposed standard modules. * [[CommonJS/API/console]] * [[CommonJS/API/system]] * [[CommonJS/API/binary]] * [[CommonJS/API/file]] * [[CommonJS/API/io]] * [[CommonJS/API/ioString]] 967 2009-09-10T03:13:56Z Dantman 1 moved [[CommonJS/API]] to [[OldAPI]] {{Old}} Here are sections for proposed standard modules. * [[CommonJS/API/console]] * [[CommonJS/API/system]] * [[CommonJS/API/binary]] * [[CommonJS/API/file]] * [[CommonJS/API/io]] * [[CommonJS/API/ioString]] 999 2009-09-10T03:15:35Z Dantman 1 Robot: Automated text replacement (-CommonJS/API +OldAPI) {{Old}} Here are sections for proposed standard modules. * [[OldAPI/console]] * [[OldAPI/system]] * [[OldAPI/binary]] * [[OldAPI/file]] * [[OldAPI/io]] * [[OldAPI/ioString]] 4 27 2009-02-18T08:10:51Z KrisKowal New page: * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] * Iterations Module API [[ServerJS/API/iter/ProposalK]] * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] * Iterations Module API [[ServerJS/API/iter/ProposalK]] 28 2009-02-18T08:14:18Z KrisKowal Added a reference to the posix module API proposal * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] * Iterations Module API [[ServerJS/API/iter/ProposalK]] * Posix Module API [[ServerJS/API/posix/ProposalK]] 29 2009-02-18T21:38:17Z KrisKowal Added a link to the sets proposal for ServerJS * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] * Posix Module API [[ServerJS/API/posix/ProposalK]] * Iterations Module API [[ServerJS/API/iter/ProposalK]] * Sets Module API [[ServerJS/API/set/ProposalK]] 30 2009-02-18T22:01:10Z KrisKowal Added a link to the dictionary proposal for ServerJS * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] * Posix Module API [[ServerJS/API/posix/ProposalK]] * Iterations Module API [[ServerJS/API/iter/ProposalK]] * Sets Module API [[ServerJS/API/set/ProposalK]] * Dictionaries Module API [[ServerJS/API/dict/ProposalK]] 31 2009-02-18T22:15:40Z KrisKowal Added a link to the list proposal for ServerJS * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] * Posix Module API [[ServerJS/API/posix/ProposalK]] * Iterations Module API [[ServerJS/API/iter/ProposalK]] * Sets Module API [[ServerJS/API/set/ProposalK]] * Dictionaries Module API [[ServerJS/API/dict/ProposalK]] * Lists Module API [[ServerJS/API/list/ProposalK]] 32 2009-02-18T22:50:17Z KrisKowal Added some story behind the ProposalK for ServerJS API. == Synopsis == In JavaScript there are both "rhinocerous", native patterns for collection types embodied by the usage and generic methods of <tt>Array</tt> and <tt>Object</tt>. However these objects and their patterns have several disadvantages which give rise to the need for "best practices" in user-defined collections. * <tt>.length</tt> assignment is not observable in pure-JS interoperably * <tt>[index]</tt> assignment is only special for <tt>Array</tt> and inheriting <tt>Array does not imbue types with their specialness. * <tt>[name]</tt> assignment can have name collisions between names in an object's prototype chain and those that it ought to contain. Assigning arbitrary strings in this domain can potentially mask builtins. * The <tt>in</tt> operator cannot be safely used on <tt>Object</tt> instances to check for containment or iteration. You have to use the <tt>Object.prototype.hasOwnProperty.call</tt> method instead. * Proxies for native objects cannot observe indexing or length assignment. * <tt>Array</tt>'s constructor is not strictly variadic. That is, creating an Array with a single value that is a number must be done with Array literals. <tt>Array</tt> and <tt>Object</tt> do not support copy construction. * <tt>Object</tt> can only be used for mappings from a domain of strings. However, there are distinct advantages of playing nicely with these types, like being able to use the <tt>Array.prototype</tt> generic methods. For this reason, there need to be two layers of collection types: those that play well with natives ("rhinocerous types", if you will), and those that can be manipulated in pure JavaScript using a new set of conventional names. With these user-defined types, it's necessary to use methods for all interaction with the underlying collection. We can create a system of base types that support mutual copy construction and mutual interface implementation. That is, all collections should be constructable by passing an iterable as their argument, and in turn all collections should be iterable. Python does this well, but we can do one step better by making the default iteration on dictionary mappings to render an iterable of (key, value) pairs instead of simply the keys. We can also define orthogonal interfaces intrinsic to each of the three main collection types and cross implement those interfaces in each other type to the extent it make sense. That is, a List is a duck-type for a Dict where the keys are offsets. A Dict is a Set of pairs. A Set is an unordered List. Methods intrinsic to: * Set (unordered values): insert, remove, retrieve, discard * Dict (unordered pairs): get, set, del, has, put, cut * List (ordered values, (index value pairs)): push, pop, shift, unshift But List implements all of these Dict interface, and Dict can inherit Set. This is a proposal for modules to be included in the standard library. Since there's some coupling between iteration and stream IO, I've begun layout out those modules as well. My recommendation is to implement the IO, file, and socket modules in the standard library. That would leave each platform to implement a "posix" module with all the routines that these other libraries would need. This is very rough draft status. I imagine there's a lot of room for discussion on nomenclature and intended scope for the ServerJS standard library. == API == * Iterations Module API [[ServerJS/API/iter/ProposalK]] * Sets Module API [[ServerJS/API/set/ProposalK]] * Dictionaries Module API [[ServerJS/API/dict/ProposalK]] * Lists Module API [[ServerJS/API/list/ProposalK]] * Posix Module API [[ServerJS/API/posix/ProposalK]] * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] 33 2009-02-18T22:53:45Z KrisKowal /* Synopsis */ == Synopsis == In JavaScript there are both "rhinocerous", native patterns for collection types embodied by the usage and generic methods of <tt>Array</tt> and <tt>Object</tt>. However these objects and their patterns have several disadvantages which give rise to the need for "best practices" in user-defined collections. * <tt>.length</tt> assignment is not observable in pure-JS interoperably * <tt>[index]</tt> assignment is only special for <tt>Array</tt> and inheriting <tt>Array does not imbue types with their specialness. * [name] assignment can have name collisions between names in an object's prototype chain and those that it ought to contain. Assigning arbitrary strings in this domain can potentially mask builtins. * The <tt>in</tt> operator cannot be safely used on <tt>Object</tt> instances to check for containment or iteration. You have to use the <tt>Object.prototype.hasOwnProperty.call</tt> method instead. * Proxies for native objects cannot observe indexing or length assignment. * <tt>Array</tt>'s constructor is not strictly variadic. That is, creating an Array with a single value that is a number must be done with Array literals. <tt>Array</tt> and <tt>Object</tt> do not support copy construction. * <tt>Object</tt> can only be used for mappings from a domain of strings. However, there are distinct advantages of playing nicely with these types, like being able to use the <tt>Array.prototype</tt> generic methods. For this reason, there need to be two layers of collection types: those that play well with natives ("rhinocerous types", if you will), and those that can be manipulated in pure JavaScript using a new set of conventional names. With these user-defined types, it's necessary to use methods for all interaction with the underlying collection. We can create a system of base types that support mutual copy construction and mutual interface implementation. That is, all collections should be constructable by passing an iterable as their argument, and in turn all collections should be iterable. Python does this well, but we can do one step better by making the default iteration on dictionary mappings to render an iterable of (key, value) pairs instead of simply the keys. We can also define orthogonal interfaces intrinsic to each of the three main collection types and cross implement those interfaces in each other type to the extent it make sense. That is, a List is a duck-type for a Dict where the keys are offsets. A Dict is a Set of pairs. A Set is an unordered List. Methods intrinsic to: * Set (unordered values): insert, remove, retrieve, discard * Dict (unordered pairs): get, set, del, has, put, cut * List (ordered values, (index value pairs)): push, pop, shift, unshift But List implements all of these Dict interface, and Dict can inherit Set. This is a proposal for modules to be included in the standard library. Since there's some coupling between iteration and stream IO, I've begun layout out those modules as well. My recommendation is to implement the IO, file, and socket modules in the standard library. That would leave each platform to implement a "posix" module with all the routines that these other libraries would need. This is very rough draft status. I imagine there's a lot of room for discussion on nomenclature and intended scope for the ServerJS standard library. == API == * Iterations Module API [[ServerJS/API/iter/ProposalK]] * Sets Module API [[ServerJS/API/set/ProposalK]] * Dictionaries Module API [[ServerJS/API/dict/ProposalK]] * Lists Module API [[ServerJS/API/list/ProposalK]] * Posix Module API [[ServerJS/API/posix/ProposalK]] * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] 34 2009-02-18T23:07:41Z KrisKowal == Synopsis == In JavaScript there are both "rhinocerous", native patterns for collection types embodied by the usage and generic methods of <tt>Array</tt> and <tt>Object</tt>. However these objects and their patterns have several disadvantages which give rise to the need for "best practices" in user-defined collections. * <tt>.length</tt> assignment is not observable in pure-JS interoperably * <tt>[index]</tt> assignment is only special for <tt>Array</tt> and inheriting <tt>Array</tt> does not imbue types with their specialness. * <tt>[name]</tt> assignment can have name collisions between names in an object's prototype chain and those that it ought to contain. Assigning arbitrary strings in this domain can potentially mask builtins. * The <tt>in</tt> operator cannot be safely used on <tt>Object</tt> instances to check for containment or iteration. You have to use the <tt>Object.prototype.hasOwnProperty.call</tt> method instead. * Proxies for native objects cannot observe indexing or length assignment. * <tt>Array</tt>'s constructor is not strictly variadic. That is, creating an Array with a single value that is a number must be done with Array literals. <tt>Array</tt> and <tt>Object</tt> do not support copy construction. * <tt>Object</tt> can only be used for mappings from a domain of strings. However, there are distinct advantages of playing nicely with these types, like being able to use the <tt>Array.prototype</tt> generic methods. For this reason, there need to be two layers of collection types: those that play well with natives ("rhinocerous types", if you will), and those that can be manipulated in pure JavaScript using a new set of conventional names. With these user-defined types, it's necessary to use methods for all interaction with the underlying collection. We can create a system of base types that support mutual copy construction and mutual interface implementation. That is, all collections should be constructable by passing an iterable as their argument, and in turn all collections should be iterable. Python does this well, but we can do one step better by making the default iteration on dictionary mappings to render an iterable of (key, value) pairs instead of simply the keys. We can also define orthogonal interfaces intrinsic to each of the three main collection types and cross implement those interfaces in each other type to the extent it make sense. That is, a List is a duck-type for a Dict where the keys are offsets. A Dict is a Set of pairs. A Set is an unordered List. Methods intrinsic to: * Set (unordered values): insert, remove, retrieve, discard * Dict (unordered pairs): get, set, del, has, put, cut * List (ordered values, (index value pairs)): push, pop, shift, unshift But List implements all of these Dict interface, and Dict can inherit Set. This is a proposal for modules to be included in the standard library. Since there's some coupling between iteration and stream IO, I've begun layout out those modules as well. My recommendation is to implement the IO, file, and socket modules in the standard library. That would leave each platform to implement a "posix" module with all the routines that these other libraries would need. This is very rough draft status. I imagine there's a lot of room for discussion on nomenclature and intended scope for the ServerJS standard library. == API == * Iterations Module API [[ServerJS/API/iter/ProposalK]] * Sets Module API [[ServerJS/API/set/ProposalK]] * Dictionaries Module API [[ServerJS/API/dict/ProposalK]] * Lists Module API [[ServerJS/API/list/ProposalK]] * Posix Module API [[ServerJS/API/posix/ProposalK]] * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] 35 2009-02-20T00:04:52Z KrisKowal /* API */ == Synopsis == In JavaScript there are both "rhinocerous", native patterns for collection types embodied by the usage and generic methods of <tt>Array</tt> and <tt>Object</tt>. However these objects and their patterns have several disadvantages which give rise to the need for "best practices" in user-defined collections. * <tt>.length</tt> assignment is not observable in pure-JS interoperably * <tt>[index]</tt> assignment is only special for <tt>Array</tt> and inheriting <tt>Array</tt> does not imbue types with their specialness. * <tt>[name]</tt> assignment can have name collisions between names in an object's prototype chain and those that it ought to contain. Assigning arbitrary strings in this domain can potentially mask builtins. * The <tt>in</tt> operator cannot be safely used on <tt>Object</tt> instances to check for containment or iteration. You have to use the <tt>Object.prototype.hasOwnProperty.call</tt> method instead. * Proxies for native objects cannot observe indexing or length assignment. * <tt>Array</tt>'s constructor is not strictly variadic. That is, creating an Array with a single value that is a number must be done with Array literals. <tt>Array</tt> and <tt>Object</tt> do not support copy construction. * <tt>Object</tt> can only be used for mappings from a domain of strings. However, there are distinct advantages of playing nicely with these types, like being able to use the <tt>Array.prototype</tt> generic methods. For this reason, there need to be two layers of collection types: those that play well with natives ("rhinocerous types", if you will), and those that can be manipulated in pure JavaScript using a new set of conventional names. With these user-defined types, it's necessary to use methods for all interaction with the underlying collection. We can create a system of base types that support mutual copy construction and mutual interface implementation. That is, all collections should be constructable by passing an iterable as their argument, and in turn all collections should be iterable. Python does this well, but we can do one step better by making the default iteration on dictionary mappings to render an iterable of (key, value) pairs instead of simply the keys. We can also define orthogonal interfaces intrinsic to each of the three main collection types and cross implement those interfaces in each other type to the extent it make sense. That is, a List is a duck-type for a Dict where the keys are offsets. A Dict is a Set of pairs. A Set is an unordered List. Methods intrinsic to: * Set (unordered values): insert, remove, retrieve, discard * Dict (unordered pairs): get, set, del, has, put, cut * List (ordered values, (index value pairs)): push, pop, shift, unshift But List implements all of these Dict interface, and Dict can inherit Set. This is a proposal for modules to be included in the standard library. Since there's some coupling between iteration and stream IO, I've begun layout out those modules as well. My recommendation is to implement the IO, file, and socket modules in the standard library. That would leave each platform to implement a "posix" module with all the routines that these other libraries would need. This is very rough draft status. I imagine there's a lot of room for discussion on nomenclature and intended scope for the ServerJS standard library. == API == * Iterations Module API [[ServerJS/API/iter/ProposalK]] * Sets Module API [[ServerJS/API/set/ProposalK]] * Dictionaries Module API [[ServerJS/API/dict/ProposalK]] * Lists Module API [[ServerJS/API/list/ProposalK]] * Binary Module API [[ServerJS/API/binary/ProposalK]] * Posix Module API [[ServerJS/API/posix/ProposalK]] * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] 36 2009-02-20T00:05:26Z KrisKowal /* Synopsis */ == Synopsis == In JavaScript there are both "javascriptish/rhinocerous", native patterns for collection types embodied by the usage and generic methods of <tt>Array</tt> and <tt>Object</tt>. However these objects and their patterns have several disadvantages which give rise to the need for "best practices" in user-defined collections. * <tt>.length</tt> assignment is not observable in pure-JS interoperably * <tt>[index]</tt> assignment is only special for <tt>Array</tt> and inheriting <tt>Array</tt> does not imbue types with their specialness. * <tt>[name]</tt> assignment can have name collisions between names in an object's prototype chain and those that it ought to contain. Assigning arbitrary strings in this domain can potentially mask builtins. * The <tt>in</tt> operator cannot be safely used on <tt>Object</tt> instances to check for containment or iteration. You have to use the <tt>Object.prototype.hasOwnProperty.call</tt> method instead. * Proxies for native objects cannot observe indexing or length assignment. * <tt>Array</tt>'s constructor is not strictly variadic. That is, creating an Array with a single value that is a number must be done with Array literals. <tt>Array</tt> and <tt>Object</tt> do not support copy construction. * <tt>Object</tt> can only be used for mappings from a domain of strings. However, there are distinct advantages of playing nicely with these types, like being able to use the <tt>Array.prototype</tt> generic methods. For this reason, there need to be two layers of collection types: those that play well with natives ("rhinocerous types", if you will), and those that can be manipulated in pure JavaScript using a new set of conventional names. With these user-defined types, it's necessary to use methods for all interaction with the underlying collection. We can create a system of base types that support mutual copy construction and mutual interface implementation. That is, all collections should be constructable by passing an iterable as their argument, and in turn all collections should be iterable. Python does this well, but we can do one step better by making the default iteration on dictionary mappings to render an iterable of (key, value) pairs instead of simply the keys. We can also define orthogonal interfaces intrinsic to each of the three main collection types and cross implement those interfaces in each other type to the extent it make sense. That is, a List is a duck-type for a Dict where the keys are offsets. A Dict is a Set of pairs. A Set is an unordered List. Methods intrinsic to: * Set (unordered values): insert, remove, retrieve, discard * Dict (unordered pairs): get, set, del, has, put, cut * List (ordered values, (index value pairs)): push, pop, shift, unshift But List implements all of these Dict interface, and Dict can inherit Set. This is a proposal for modules to be included in the standard library. Since there's some coupling between iteration and stream IO, I've begun layout out those modules as well. My recommendation is to implement the IO, file, and socket modules in the standard library. That would leave each platform to implement a "posix" module with all the routines that these other libraries would need. This is very rough draft status. I imagine there's a lot of room for discussion on nomenclature and intended scope for the ServerJS standard library. == API == * Iterations Module API [[ServerJS/API/iter/ProposalK]] * Sets Module API [[ServerJS/API/set/ProposalK]] * Dictionaries Module API [[ServerJS/API/dict/ProposalK]] * Lists Module API [[ServerJS/API/list/ProposalK]] * Binary Module API [[ServerJS/API/binary/ProposalK]] * Posix Module API [[ServerJS/API/posix/ProposalK]] * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] 37 2009-09-09T22:13:49Z Dantman 1 10 revisions:&#32;Import from https://wiki.mozilla.org/ServerJS == Synopsis == In JavaScript there are both "javascriptish/rhinocerous", native patterns for collection types embodied by the usage and generic methods of <tt>Array</tt> and <tt>Object</tt>. However these objects and their patterns have several disadvantages which give rise to the need for "best practices" in user-defined collections. * <tt>.length</tt> assignment is not observable in pure-JS interoperably * <tt>[index]</tt> assignment is only special for <tt>Array</tt> and inheriting <tt>Array</tt> does not imbue types with their specialness. * <tt>[name]</tt> assignment can have name collisions between names in an object's prototype chain and those that it ought to contain. Assigning arbitrary strings in this domain can potentially mask builtins. * The <tt>in</tt> operator cannot be safely used on <tt>Object</tt> instances to check for containment or iteration. You have to use the <tt>Object.prototype.hasOwnProperty.call</tt> method instead. * Proxies for native objects cannot observe indexing or length assignment. * <tt>Array</tt>'s constructor is not strictly variadic. That is, creating an Array with a single value that is a number must be done with Array literals. <tt>Array</tt> and <tt>Object</tt> do not support copy construction. * <tt>Object</tt> can only be used for mappings from a domain of strings. However, there are distinct advantages of playing nicely with these types, like being able to use the <tt>Array.prototype</tt> generic methods. For this reason, there need to be two layers of collection types: those that play well with natives ("rhinocerous types", if you will), and those that can be manipulated in pure JavaScript using a new set of conventional names. With these user-defined types, it's necessary to use methods for all interaction with the underlying collection. We can create a system of base types that support mutual copy construction and mutual interface implementation. That is, all collections should be constructable by passing an iterable as their argument, and in turn all collections should be iterable. Python does this well, but we can do one step better by making the default iteration on dictionary mappings to render an iterable of (key, value) pairs instead of simply the keys. We can also define orthogonal interfaces intrinsic to each of the three main collection types and cross implement those interfaces in each other type to the extent it make sense. That is, a List is a duck-type for a Dict where the keys are offsets. A Dict is a Set of pairs. A Set is an unordered List. Methods intrinsic to: * Set (unordered values): insert, remove, retrieve, discard * Dict (unordered pairs): get, set, del, has, put, cut * List (ordered values, (index value pairs)): push, pop, shift, unshift But List implements all of these Dict interface, and Dict can inherit Set. This is a proposal for modules to be included in the standard library. Since there's some coupling between iteration and stream IO, I've begun layout out those modules as well. My recommendation is to implement the IO, file, and socket modules in the standard library. That would leave each platform to implement a "posix" module with all the routines that these other libraries would need. This is very rough draft status. I imagine there's a lot of room for discussion on nomenclature and intended scope for the ServerJS standard library. == API == * Iterations Module API [[ServerJS/API/iter/ProposalK]] * Sets Module API [[ServerJS/API/set/ProposalK]] * Dictionaries Module API [[ServerJS/API/dict/ProposalK]] * Lists Module API [[ServerJS/API/list/ProposalK]] * Binary Module API [[ServerJS/API/binary/ProposalK]] * Posix Module API [[ServerJS/API/posix/ProposalK]] * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] 619 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API/ProposalK]] to [[CommonJS/API/ProposalK]]:&#32;Subpages needed to be enabled == Synopsis == In JavaScript there are both "javascriptish/rhinocerous", native patterns for collection types embodied by the usage and generic methods of <tt>Array</tt> and <tt>Object</tt>. However these objects and their patterns have several disadvantages which give rise to the need for "best practices" in user-defined collections. * <tt>.length</tt> assignment is not observable in pure-JS interoperably * <tt>[index]</tt> assignment is only special for <tt>Array</tt> and inheriting <tt>Array</tt> does not imbue types with their specialness. * <tt>[name]</tt> assignment can have name collisions between names in an object's prototype chain and those that it ought to contain. Assigning arbitrary strings in this domain can potentially mask builtins. * The <tt>in</tt> operator cannot be safely used on <tt>Object</tt> instances to check for containment or iteration. You have to use the <tt>Object.prototype.hasOwnProperty.call</tt> method instead. * Proxies for native objects cannot observe indexing or length assignment. * <tt>Array</tt>'s constructor is not strictly variadic. That is, creating an Array with a single value that is a number must be done with Array literals. <tt>Array</tt> and <tt>Object</tt> do not support copy construction. * <tt>Object</tt> can only be used for mappings from a domain of strings. However, there are distinct advantages of playing nicely with these types, like being able to use the <tt>Array.prototype</tt> generic methods. For this reason, there need to be two layers of collection types: those that play well with natives ("rhinocerous types", if you will), and those that can be manipulated in pure JavaScript using a new set of conventional names. With these user-defined types, it's necessary to use methods for all interaction with the underlying collection. We can create a system of base types that support mutual copy construction and mutual interface implementation. That is, all collections should be constructable by passing an iterable as their argument, and in turn all collections should be iterable. Python does this well, but we can do one step better by making the default iteration on dictionary mappings to render an iterable of (key, value) pairs instead of simply the keys. We can also define orthogonal interfaces intrinsic to each of the three main collection types and cross implement those interfaces in each other type to the extent it make sense. That is, a List is a duck-type for a Dict where the keys are offsets. A Dict is a Set of pairs. A Set is an unordered List. Methods intrinsic to: * Set (unordered values): insert, remove, retrieve, discard * Dict (unordered pairs): get, set, del, has, put, cut * List (ordered values, (index value pairs)): push, pop, shift, unshift But List implements all of these Dict interface, and Dict can inherit Set. This is a proposal for modules to be included in the standard library. Since there's some coupling between iteration and stream IO, I've begun layout out those modules as well. My recommendation is to implement the IO, file, and socket modules in the standard library. That would leave each platform to implement a "posix" module with all the routines that these other libraries would need. This is very rough draft status. I imagine there's a lot of room for discussion on nomenclature and intended scope for the ServerJS standard library. == API == * Iterations Module API [[ServerJS/API/iter/ProposalK]] * Sets Module API [[ServerJS/API/set/ProposalK]] * Dictionaries Module API [[ServerJS/API/dict/ProposalK]] * Lists Module API [[ServerJS/API/list/ProposalK]] * Binary Module API [[ServerJS/API/binary/ProposalK]] * Posix Module API [[ServerJS/API/posix/ProposalK]] * File Module API [[ServerJS/API/file/ProposalK]] * IO Module API [[ServerJS/API/io/ProposalK]] 785 2009-09-09T22:40:09Z Dantman 1 Robot: Automated text replacement (-ServerJS +CommonJS) == Synopsis == In JavaScript there are both "javascriptish/rhinocerous", native patterns for collection types embodied by the usage and generic methods of <tt>Array</tt> and <tt>Object</tt>. However these objects and their patterns have several disadvantages which give rise to the need for "best practices" in user-defined collections. * <tt>.length</tt> assignment is not observable in pure-JS interoperably * <tt>[index]</tt> assignment is only special for <tt>Array</tt> and inheriting <tt>Array</tt> does not imbue types with their specialness. * <tt>[name]</tt> assignment can have name collisions between names in an object's prototype chain and those that it ought to contain. Assigning arbitrary strings in this domain can potentially mask builtins. * The <tt>in</tt> operator cannot be safely used on <tt>Object</tt> instances to check for containment or iteration. You have to use the <tt>Object.prototype.hasOwnProperty.call</tt> method instead. * Proxies for native objects cannot observe indexing or length assignment. * <tt>Array</tt>'s constructor is not strictly variadic. That is, creating an Array with a single value that is a number must be done with Array literals. <tt>Array</tt> and <tt>Object</tt> do not support copy construction. * <tt>Object</tt> can only be used for mappings from a domain of strings. However, there are distinct advantages of playing nicely with these types, like being able to use the <tt>Array.prototype</tt> generic methods. For this reason, there need to be two layers of collection types: those that play well with natives ("rhinocerous types", if you will), and those that can be manipulated in pure JavaScript using a new set of conventional names. With these user-defined types, it's necessary to use methods for all interaction with the underlying collection. We can create a system of base types that support mutual copy construction and mutual interface implementation. That is, all collections should be constructable by passing an iterable as their argument, and in turn all collections should be iterable. Python does this well, but we can do one step better by making the default iteration on dictionary mappings to render an iterable of (key, value) pairs instead of simply the keys. We can also define orthogonal interfaces intrinsic to each of the three main collection types and cross implement those interfaces in each other type to the extent it make sense. That is, a List is a duck-type for a Dict where the keys are offsets. A Dict is a Set of pairs. A Set is an unordered List. Methods intrinsic to: * Set (unordered values): insert, remove, retrieve, discard * Dict (unordered pairs): get, set, del, has, put, cut * List (ordered values, (index value pairs)): push, pop, shift, unshift But List implements all of these Dict interface, and Dict can inherit Set. This is a proposal for modules to be included in the standard library. Since there's some coupling between iteration and stream IO, I've begun layout out those modules as well. My recommendation is to implement the IO, file, and socket modules in the standard library. That would leave each platform to implement a "posix" module with all the routines that these other libraries would need. This is very rough draft status. I imagine there's a lot of room for discussion on nomenclature and intended scope for the CommonJS standard library. == API == * Iterations Module API [[CommonJS/API/iter/ProposalK]] * Sets Module API [[CommonJS/API/set/ProposalK]] * Dictionaries Module API [[CommonJS/API/dict/ProposalK]] * Lists Module API [[CommonJS/API/list/ProposalK]] * Binary Module API [[CommonJS/API/binary/ProposalK]] * Posix Module API [[CommonJS/API/posix/ProposalK]] * File Module API [[CommonJS/API/file/ProposalK]] * IO Module API [[CommonJS/API/io/ProposalK]] 969 2009-09-10T03:13:56Z Dantman 1 moved [[CommonJS/API/ProposalK]] to [[OldAPI/ProposalK]] == Synopsis == In JavaScript there are both "javascriptish/rhinocerous", native patterns for collection types embodied by the usage and generic methods of <tt>Array</tt> and <tt>Object</tt>. However these objects and their patterns have several disadvantages which give rise to the need for "best practices" in user-defined collections. * <tt>.length</tt> assignment is not observable in pure-JS interoperably * <tt>[index]</tt> assignment is only special for <tt>Array</tt> and inheriting <tt>Array</tt> does not imbue types with their specialness. * <tt>[name]</tt> assignment can have name collisions between names in an object's prototype chain and those that it ought to contain. Assigning arbitrary strings in this domain can potentially mask builtins. * The <tt>in</tt> operator cannot be safely used on <tt>Object</tt> instances to check for containment or iteration. You have to use the <tt>Object.prototype.hasOwnProperty.call</tt> method instead. * Proxies for native objects cannot observe indexing or length assignment. * <tt>Array</tt>'s constructor is not strictly variadic. That is, creating an Array with a single value that is a number must be done with Array literals. <tt>Array</tt> and <tt>Object</tt> do not support copy construction. * <tt>Object</tt> can only be used for mappings from a domain of strings. However, there are distinct advantages of playing nicely with these types, like being able to use the <tt>Array.prototype</tt> generic methods. For this reason, there need to be two layers of collection types: those that play well with natives ("rhinocerous types", if you will), and those that can be manipulated in pure JavaScript using a new set of conventional names. With these user-defined types, it's necessary to use methods for all interaction with the underlying collection. We can create a system of base types that support mutual copy construction and mutual interface implementation. That is, all collections should be constructable by passing an iterable as their argument, and in turn all collections should be iterable. Python does this well, but we can do one step better by making the default iteration on dictionary mappings to render an iterable of (key, value) pairs instead of simply the keys. We can also define orthogonal interfaces intrinsic to each of the three main collection types and cross implement those interfaces in each other type to the extent it make sense. That is, a List is a duck-type for a Dict where the keys are offsets. A Dict is a Set of pairs. A Set is an unordered List. Methods intrinsic to: * Set (unordered values): insert, remove, retrieve, discard * Dict (unordered pairs): get, set, del, has, put, cut * List (ordered values, (index value pairs)): push, pop, shift, unshift But List implements all of these Dict interface, and Dict can inherit Set. This is a proposal for modules to be included in the standard library. Since there's some coupling between iteration and stream IO, I've begun layout out those modules as well. My recommendation is to implement the IO, file, and socket modules in the standard library. That would leave each platform to implement a "posix" module with all the routines that these other libraries would need. This is very rough draft status. I imagine there's a lot of room for discussion on nomenclature and intended scope for the CommonJS standard library. == API == * Iterations Module API [[CommonJS/API/iter/ProposalK]] * Sets Module API [[CommonJS/API/set/ProposalK]] * Dictionaries Module API [[CommonJS/API/dict/ProposalK]] * Lists Module API [[CommonJS/API/list/ProposalK]] * Binary Module API [[CommonJS/API/binary/ProposalK]] * Posix Module API [[CommonJS/API/posix/ProposalK]] * File Module API [[CommonJS/API/file/ProposalK]] * IO Module API [[CommonJS/API/io/ProposalK]] 1000 2009-09-10T03:15:45Z Dantman 1 Robot: Automated text replacement (-CommonJS/API +OldAPI) == Synopsis == In JavaScript there are both "javascriptish/rhinocerous", native patterns for collection types embodied by the usage and generic methods of <tt>Array</tt> and <tt>Object</tt>. However these objects and their patterns have several disadvantages which give rise to the need for "best practices" in user-defined collections. * <tt>.length</tt> assignment is not observable in pure-JS interoperably * <tt>[index]</tt> assignment is only special for <tt>Array</tt> and inheriting <tt>Array</tt> does not imbue types with their specialness. * <tt>[name]</tt> assignment can have name collisions between names in an object's prototype chain and those that it ought to contain. Assigning arbitrary strings in this domain can potentially mask builtins. * The <tt>in</tt> operator cannot be safely used on <tt>Object</tt> instances to check for containment or iteration. You have to use the <tt>Object.prototype.hasOwnProperty.call</tt> method instead. * Proxies for native objects cannot observe indexing or length assignment. * <tt>Array</tt>'s constructor is not strictly variadic. That is, creating an Array with a single value that is a number must be done with Array literals. <tt>Array</tt> and <tt>Object</tt> do not support copy construction. * <tt>Object</tt> can only be used for mappings from a domain of strings. However, there are distinct advantages of playing nicely with these types, like being able to use the <tt>Array.prototype</tt> generic methods. For this reason, there need to be two layers of collection types: those that play well with natives ("rhinocerous types", if you will), and those that can be manipulated in pure JavaScript using a new set of conventional names. With these user-defined types, it's necessary to use methods for all interaction with the underlying collection. We can create a system of base types that support mutual copy construction and mutual interface implementation. That is, all collections should be constructable by passing an iterable as their argument, and in turn all collections should be iterable. Python does this well, but we can do one step better by making the default iteration on dictionary mappings to render an iterable of (key, value) pairs instead of simply the keys. We can also define orthogonal interfaces intrinsic to each of the three main collection types and cross implement those interfaces in each other type to the extent it make sense. That is, a List is a duck-type for a Dict where the keys are offsets. A Dict is a Set of pairs. A Set is an unordered List. Methods intrinsic to: * Set (unordered values): insert, remove, retrieve, discard * Dict (unordered pairs): get, set, del, has, put, cut * List (ordered values, (index value pairs)): push, pop, shift, unshift But List implements all of these Dict interface, and Dict can inherit Set. This is a proposal for modules to be included in the standard library. Since there's some coupling between iteration and stream IO, I've begun layout out those modules as well. My recommendation is to implement the IO, file, and socket modules in the standard library. That would leave each platform to implement a "posix" module with all the routines that these other libraries would need. This is very rough draft status. I imagine there's a lot of room for discussion on nomenclature and intended scope for the CommonJS standard library. == API == * Iterations Module API [[OldAPI/iter/ProposalK]] * Sets Module API [[OldAPI/set/ProposalK]] * Dictionaries Module API [[OldAPI/dict/ProposalK]] * Lists Module API [[OldAPI/list/ProposalK]] * Binary Module API [[OldAPI/binary/ProposalK]] * Posix Module API [[OldAPI/posix/ProposalK]] * File Module API [[OldAPI/file/ProposalK]] * IO Module API [[OldAPI/io/ProposalK]] 5 38 2009-04-14T05:03:47Z KrisKowal Created page with 'Please see the [[ServerJS/Binary|Binary]] proposal for details about the contents of the "binary" module.' Please see the [[ServerJS/Binary|Binary]] proposal for details about the contents of the "binary" module. 39 2009-09-09T22:13:49Z Dantman 1 1 revision:&#32;Import from https://wiki.mozilla.org/ServerJS Please see the [[ServerJS/Binary|Binary]] proposal for details about the contents of the "binary" module. 621 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API/binary]] to [[CommonJS/API/binary]]:&#32;Subpages needed to be enabled Please see the [[ServerJS/Binary|Binary]] proposal for details about the contents of the "binary" module. 786 2009-09-09T22:40:18Z Dantman 1 Robot: Automated text replacement (-ServerJS +CommonJS) Please see the [[CommonJS/Binary|Binary]] proposal for details about the contents of the "binary" module. 971 2009-09-10T03:13:56Z Dantman 1 moved [[CommonJS/API/binary]] to [[OldAPI/binary]] Please see the [[CommonJS/Binary|Binary]] proposal for details about the contents of the "binary" module. 1212 2009-09-12T02:31:12Z Dantman 1 Robot: Automated text replacement (-CommonJS/ +) Please see the [[Binary|Binary]] proposal for details about the contents of the "binary" module. 1247 2009-09-12T04:40:59Z Dantman 1 Robot: Automated text replacement (-\[\[(.+?)\|\1\]\] +[[\1]]) Please see the [[Binary]] proposal for details about the contents of the "binary" module. 6 40 2009-02-20T00:03:30Z KrisKowal Added a preliminary API for Binary types in ServerJS. /*** Binary Returns a representation of an array of bytes. Accepts a Binary, or an Array of Numbers. Throws an error if any Number is greater than or equal to 256, less than 0, or of sub-integer precision. */ /**** length */ /**** get */ /**** set */ /**** slice */ /**** concat */ /**** indexOf */ /**** replace */ /**** toSource */ /**** toString */ /**** toSource */ 41 2009-09-09T22:13:49Z Dantman 1 1 revision:&#32;Import from https://wiki.mozilla.org/ServerJS /*** Binary Returns a representation of an array of bytes. Accepts a Binary, or an Array of Numbers. Throws an error if any Number is greater than or equal to 256, less than 0, or of sub-integer precision. */ /**** length */ /**** get */ /**** set */ /**** slice */ /**** concat */ /**** indexOf */ /**** replace */ /**** toSource */ /**** toString */ /**** toSource */ 623 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API/binary/ProposalK]] to [[CommonJS/API/binary/ProposalK]]:&#32;Subpages needed to be enabled /*** Binary Returns a representation of an array of bytes. Accepts a Binary, or an Array of Numbers. Throws an error if any Number is greater than or equal to 256, less than 0, or of sub-integer precision. */ /**** length */ /**** get */ /**** set */ /**** slice */ /**** concat */ /**** indexOf */ /**** replace */ /**** toSource */ /**** toString */ /**** toSource */ 973 2009-09-10T03:13:56Z Dantman 1 moved [[CommonJS/API/binary/ProposalK]] to [[OldAPI/binary/ProposalK]] /*** Binary Returns a representation of an array of bytes. Accepts a Binary, or an Array of Numbers. Throws an error if any Number is greater than or equal to 256, less than 0, or of sub-integer precision. */ /**** length */ /**** get */ /**** set */ /**** slice */ /**** concat */ /**** indexOf */ /**** replace */ /**** toSource */ /**** toString */ /**** toSource */ 7 42 2009-04-14T05:20:53Z KrisKowal Added a preliminary proposal for the console module API. The "console" top-level module must be available in all platforms. The module must provide the following exports: ; log(message, [level]): logs a message. The level may be any of "log", "info", "warn", "error", "debug", "pass", "fail", null, or undefined. Other labels beginning with "x" and a platform-specific identifier are reserved for the corresponding platform. ; info(message) : logs an informational message ; warn(message) : logs a warning message ; error(message) : logs an error message ; debug(message) : logs a debug message ; pass(name) : logs the success of a test ; fail(name) : logs the failure of a test Message may be any object reference. = Prior Art = * [http://getfirebug.com/logging.html Firebug] * [http://developer.apple.com/internet/safari/faq.html#anchor14 Safari 1.3 Console] * [http://operawiki.info/OperaJSConsole Opera JavaScript Console] * Internet Explorer 8 JavaScript Console = Relevant Discussions = = Show of Hands = = Implementations = 43 2009-04-14T05:22:13Z KrisKowal The "console" top-level module must be available in all platforms. The module must provide the following exports: ; log(message) : logs a message ; info(message) : logs an informational message ; warn(message) : logs a warning message ; error(message) : logs an error message ; debug(message) : logs a debug message ; pass(name) : logs the success of a test ; fail(name) : logs the failure of a test ; print(message, [level]): logs a message. The level may be any of "log", "info", "warn", "error", "debug", "pass", "fail", null, or undefined. Other labels beginning with "x" and a platform-specific identifier are reserved for the corresponding platform. Messages may be any reference. Names must be strings. = Prior Art = * [http://getfirebug.com/logging.html Firebug] * [http://developer.apple.com/internet/safari/faq.html#anchor14 Safari 1.3 Console] * [http://operawiki.info/OperaJSConsole Opera JavaScript Console] * Internet Explorer 8 JavaScript Console = Relevant Discussions = = Show of Hands = = Implementations = 44 2009-04-14T05:38:09Z KrisKowal Added a summary. Many client-side libraries already support a JavaScript console object. Since this functionality is useful on the server, and to ease migration of client-side JavaScript to the server, server-side JavaScript platforms need to provide a "console" object suitable for use with minimal modification to existing scripts. Rather than provide a "console" free variable like web browsers, interoperable JavaScript modules may explicitly import the "console" module and bind it to a module local "console" variable. = Specification = The "console" top-level module must be available in all platforms. The module must provide the following exports: ; log(message) : logs a message ; info(message) : logs an informational message ; warn(message) : logs a warning message ; error(message) : logs an error message ; debug(message) : logs a debug message ; pass(name) : logs the success of a test ; fail(name) : logs the failure of a test ; print(message, [level]): logs a message. The level may be any of "log", "info", "warn", "error", "debug", "pass", "fail", null, or undefined. Other labels beginning with "x" and a platform-specific identifier are reserved for the corresponding platform. Messages may be any reference. Names must be strings. = Prior Art = * [http://getfirebug.com/logging.html Firebug] * [http://developer.apple.com/internet/safari/faq.html#anchor14 Safari 1.3 Console] * [http://operawiki.info/OperaJSConsole Opera JavaScript Console] * Internet Explorer 8 JavaScript Console = Relevant Discussions = = Show of Hands = = Implementations = 45 2009-04-14T18:34:58Z KrisKowal Redacted print, pass, and fail. Many client-side libraries already support a JavaScript console object. Since this functionality is useful on the server, and to ease migration of client-side JavaScript to the server, server-side JavaScript platforms need to provide a "console" object suitable for use with minimal modification to existing scripts. Rather than provide a "console" free variable like web browsers, interoperable JavaScript modules may explicitly import the "console" module and bind it to a module local "console" variable. = Specification = The "console" top-level module must be available in all platforms. The module must provide the following exports: ; log(message) : logs a message ; info(message) : logs an informational message ; warn(message) : logs a warning message ; error(message) : logs an error message Messages may be any reference. Names must be strings. = Prior Art = * [http://getfirebug.com/logging.html Firebug] * [http://developer.apple.com/internet/safari/faq.html#anchor14 Safari 1.3 Console] * [http://operawiki.info/OperaJSConsole Opera JavaScript Console] * Internet Explorer 8 JavaScript Console = Relevant Discussions = = Show of Hands = = Implementations = 46 2009-09-09T22:13:50Z Dantman 1 4 revisions:&#32;Import from https://wiki.mozilla.org/ServerJS Many client-side libraries already support a JavaScript console object. Since this functionality is useful on the server, and to ease migration of client-side JavaScript to the server, server-side JavaScript platforms need to provide a "console" object suitable for use with minimal modification to existing scripts. Rather than provide a "console" free variable like web browsers, interoperable JavaScript modules may explicitly import the "console" module and bind it to a module local "console" variable. = Specification = The "console" top-level module must be available in all platforms. The module must provide the following exports: ; log(message) : logs a message ; info(message) : logs an informational message ; warn(message) : logs a warning message ; error(message) : logs an error message Messages may be any reference. Names must be strings. = Prior Art = * [http://getfirebug.com/logging.html Firebug] * [http://developer.apple.com/internet/safari/faq.html#anchor14 Safari 1.3 Console] * [http://operawiki.info/OperaJSConsole Opera JavaScript Console] * Internet Explorer 8 JavaScript Console = Relevant Discussions = = Show of Hands = = Implementations = 625 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API/console]] to [[CommonJS/API/console]]:&#32;Subpages needed to be enabled Many client-side libraries already support a JavaScript console object. Since this functionality is useful on the server, and to ease migration of client-side JavaScript to the server, server-side JavaScript platforms need to provide a "console" object suitable for use with minimal modification to existing scripts. Rather than provide a "console" free variable like web browsers, interoperable JavaScript modules may explicitly import the "console" module and bind it to a module local "console" variable. = Specification = The "console" top-level module must be available in all platforms. The module must provide the following exports: ; log(message) : logs a message ; info(message) : logs an informational message ; warn(message) : logs a warning message ; error(message) : logs an error message Messages may be any reference. Names must be strings. = Prior Art = * [http://getfirebug.com/logging.html Firebug] * [http://developer.apple.com/internet/safari/faq.html#anchor14 Safari 1.3 Console] * [http://operawiki.info/OperaJSConsole Opera JavaScript Console] * Internet Explorer 8 JavaScript Console = Relevant Discussions = = Show of Hands = = Implementations = 975 2009-09-10T03:13:56Z Dantman 1 moved [[CommonJS/API/console]] to [[OldAPI/console]] Many client-side libraries already support a JavaScript console object. Since this functionality is useful on the server, and to ease migration of client-side JavaScript to the server, server-side JavaScript platforms need to provide a "console" object suitable for use with minimal modification to existing scripts. Rather than provide a "console" free variable like web browsers, interoperable JavaScript modules may explicitly import the "console" module and bind it to a module local "console" variable. = Specification = The "console" top-level module must be available in all platforms. The module must provide the following exports: ; log(message) : logs a message ; info(message) : logs an informational message ; warn(message) : logs a warning message ; error(message) : logs an error message Messages may be any reference. Names must be strings. = Prior Art = * [http://getfirebug.com/logging.html Firebug] * [http://developer.apple.com/internet/safari/faq.html#anchor14 Safari 1.3 Console] * [http://operawiki.info/OperaJSConsole Opera JavaScript Console] * Internet Explorer 8 JavaScript Console = Relevant Discussions = = Show of Hands = = Implementations = 8 47 2009-02-18T22:00:48Z KrisKowal Added a proposal for a dictionary module for ServerJS /*** Dict an unordered collection of key to value mappings. Unlike `Object`, a `Dict` object's key domain includes any object, with better performance when the `hash` of each key does not collide. That is, the `Number` ``1`` and the `String` ``"1"`` are distinct objects. `Dict` inherits from `Iterable` and `Set`, overriding the `eq` and `hash` of the underlying `Set` to use versions that hash and compare equivalence based on the pair component of key value pairs. Different than Python ``dict``: - ``update``: `add` - ``has_key``: `hasKey` - ``iteritems``: `itemsIter` - ``iterkeys``: `keysIter` - ``itervalues``: `valuesIter` - ``fromkeys(S, v)``: ``Dict(each(S.keys(), function (k) {return [k, v]}))`` - ``setdefault``: use `set` and `get` - ``__del__`` -> `remove` - ``__contains__`` -> `has` Same as Python: - `get` - `clear` - `copy` - `items` - `keys` - `values` - `pop` */ /**** keysIter returns an `Iter` of keys from the key and value pairs (items) in the dictionary. Uses `itemsIter`. - `stateless` */ /**** keys returns a `Set` of keys from the key and value pairs (items) in the dictionary. Uses `keysIter` and `itemsIter`. - `stateless` */ /**** valuesIter returns an `Iter` of values from the key and value pairs (items) in the dictinoary. Uses `itemsiter`. - `stateless` */ /**** values returns a `List` of values from the key and value pairs (items) in the dictionary. Uses `valuesIter` and `itemsIter`. - `stateless` */ /**** itemsIter returns an iteration, `Iter`, of the key and value pairs (items) in the dictionary. Items are represented as native JavaScript `Array` objects. Uses `iter`, which is defined for the `Set` base-type. - `stateless` */ /**** items returns a `List` of the key and value pairs (items) in the dictionary. Items are represnted as native JavaScript `Array` objects. Uses `itemsIter`. - `stateless` */ /**** get returns the value of an item in the dictionary that has a given key. If there is item for the key, attempts to return a default value, checking whether you've specified a default value to return as a second argument, or deferring to `getDefault`. If no acceptable default exists, throws a `KeyError`. accepts: - a key (any object) - an optional default value, which can be `undefined` or `null` if you wish to avoid throwing a `KeyError`. - `stateless` */ /**** set stores a key and corresponding value (an item) in the dictionary. If an item already exists in the dictionary that has the same key, it is overwritten. - stateful - chainable */ /**** put an alias for `set` */ /**** has returns whether a dictionary contains a given key. */ /**** cut returns the value for a given key and removes the corresponding key, value pair from the dictionary. - `stateful` */ /**** del deletes the key and value pair (item) in the dictionary that has a given key. - `stateful` - `chainable` */ /**** getDefault an overridable function that returns a value or throws a KeyError if you attempt to `get` an item for a key that the dictionary does not contain. - `stateless`, but overrides may be stateful. */ /**** hasValue returns whether the dictionary contains an item with the given value. - `stateless` */ /**** hasKey an alias of `has` - `stateless` */ /**** update Sets the given iterable of key value pairs on this dictionary, overriding any existing keys. - `stateful` - `chainable` */ /**** updated Returns a new copy of this dictionary that has been updated with the pairs in a given iterable. - `stateless` - `chainable` */ /**** complete Sets the given iterable of key value pairs on this dictionary, except for those with existing keys. - `stateful` - `chainable` */ /**** completed Returns a new copy of this dictionary that has been completed with the pairs in a given iterable. - `stateless` - `chainable` */ /**** find - `stateless` */ /**** findReverse since dictionary keys are not ordered, `findReverse` is an alias of `find`. - `stateless` */ /**** add - `stateful` - `chainable` */ /**** added - `stateless` - `chainable` */ /**** eq - `stateless` */ /**** repr - `stateless` */ /**** string - `stateless` */ /**** hash - `stateless` */ /**** invoke an alias of `get` that permits a dictionary to be used as a unary relation on its domain of keys to its range of values. */ /*** toDict */ /*** toObject Creates a new native JavaScript `Object` from any instance. Defers to any user defined `toObject` method of the given object. Failing that, defers to `dict` to convert the given object to a `Dict` and then creates an `Object` from that dictionary's key value pairs. */ /*** hasKey - `polymorphic` */ /*** hasValue - `polymorphic` */ /*** update - `polymoprhic` - `stateful` - `chainable` */ /*** updated - `polymorphic` - `stateless` - `chainable` */ /*** complete - `polymoprhic` - `stateful` - `chainable` */ /*** completed - `polymorphic` - `stateless` - `chainable` */ /*** clear removes all key value pairs from list and dict-like objects including native Arrays, Objects, and types that override the `clear` function like `Dict` and `List`. - `polymorphic` - `stateful` - `chainable` */ /*** keys - `polymorphic` - `stateless` */ /*** keysIter - `polymorphic` - `stateless` */ /*** values - `polymorphic` - `stateless` */ /*** valuesIter - `polymorphic` - `stateless` */ /*** items - `polymorphic` - `stateless` */ /*** itemsIter - `polymorphic` - `stateless` */ 48 2009-02-18T22:02:34Z KrisKowal s/itemsiter/itemsIter /*** Dict an unordered collection of key to value mappings. Unlike `Object`, a `Dict` object's key domain includes any object, with better performance when the `hash` of each key does not collide. That is, the `Number` ``1`` and the `String` ``"1"`` are distinct objects. `Dict` inherits from `Iterable` and `Set`, overriding the `eq` and `hash` of the underlying `Set` to use versions that hash and compare equivalence based on the pair component of key value pairs. Different than Python ``dict``: - ``update``: `add` - ``has_key``: `hasKey` - ``iteritems``: `itemsIter` - ``iterkeys``: `keysIter` - ``itervalues``: `valuesIter` - ``fromkeys(S, v)``: ``Dict(each(S.keys(), function (k) {return [k, v]}))`` - ``setdefault``: use `set` and `get` - ``__del__`` -> `remove` - ``__contains__`` -> `has` Same as Python: - `get` - `clear` - `copy` - `items` - `keys` - `values` - `pop` */ /**** keysIter returns an `Iter` of keys from the key and value pairs (items) in the dictionary. Uses `itemsIter`. - `stateless` */ /**** keys returns a `Set` of keys from the key and value pairs (items) in the dictionary. Uses `keysIter` and `itemsIter`. - `stateless` */ /**** valuesIter returns an `Iter` of values from the key and value pairs (items) in the dictinoary. Uses `itemsIter`. - `stateless` */ /**** values returns a `List` of values from the key and value pairs (items) in the dictionary. Uses `valuesIter` and `itemsIter`. - `stateless` */ /**** itemsIter returns an iteration, `Iter`, of the key and value pairs (items) in the dictionary. Items are represented as native JavaScript `Array` objects. Uses `iter`, which is defined for the `Set` base-type. - `stateless` */ /**** items returns a `List` of the key and value pairs (items) in the dictionary. Items are represnted as native JavaScript `Array` objects. Uses `itemsIter`. - `stateless` */ /**** get returns the value of an item in the dictionary that has a given key. If there is item for the key, attempts to return a default value, checking whether you've specified a default value to return as a second argument, or deferring to `getDefault`. If no acceptable default exists, throws a `KeyError`. accepts: - a key (any object) - an optional default value, which can be `undefined` or `null` if you wish to avoid throwing a `KeyError`. - `stateless` */ /**** set stores a key and corresponding value (an item) in the dictionary. If an item already exists in the dictionary that has the same key, it is overwritten. - stateful - chainable */ /**** put an alias for `set` */ /**** has returns whether a dictionary contains a given key. */ /**** cut returns the value for a given key and removes the corresponding key, value pair from the dictionary. - `stateful` */ /**** del deletes the key and value pair (item) in the dictionary that has a given key. - `stateful` - `chainable` */ /**** getDefault an overridable function that returns a value or throws a KeyError if you attempt to `get` an item for a key that the dictionary does not contain. - `stateless`, but overrides may be stateful. */ /**** hasValue returns whether the dictionary contains an item with the given value. - `stateless` */ /**** hasKey an alias of `has` - `stateless` */ /**** update Sets the given iterable of key value pairs on this dictionary, overriding any existing keys. - `stateful` - `chainable` */ /**** updated Returns a new copy of this dictionary that has been updated with the pairs in a given iterable. - `stateless` - `chainable` */ /**** complete Sets the given iterable of key value pairs on this dictionary, except for those with existing keys. - `stateful` - `chainable` */ /**** completed Returns a new copy of this dictionary that has been completed with the pairs in a given iterable. - `stateless` - `chainable` */ /**** find - `stateless` */ /**** findReverse since dictionary keys are not ordered, `findReverse` is an alias of `find`. - `stateless` */ /**** add - `stateful` - `chainable` */ /**** added - `stateless` - `chainable` */ /**** eq - `stateless` */ /**** repr - `stateless` */ /**** string - `stateless` */ /**** hash - `stateless` */ /**** invoke an alias of `get` that permits a dictionary to be used as a unary relation on its domain of keys to its range of values. */ /*** toDict */ /*** toObject Creates a new native JavaScript `Object` from any instance. Defers to any user defined `toObject` method of the given object. Failing that, defers to `dict` to convert the given object to a `Dict` and then creates an `Object` from that dictionary's key value pairs. */ /*** hasKey - `polymorphic` */ /*** hasValue - `polymorphic` */ /*** update - `polymoprhic` - `stateful` - `chainable` */ /*** updated - `polymorphic` - `stateless` - `chainable` */ /*** complete - `polymoprhic` - `stateful` - `chainable` */ /*** completed - `polymorphic` - `stateless` - `chainable` */ /*** clear removes all key value pairs from list and dict-like objects including native Arrays, Objects, and types that override the `clear` function like `Dict` and `List`. - `polymorphic` - `stateful` - `chainable` */ /*** keys - `polymorphic` - `stateless` */ /*** keysIter - `polymorphic` - `stateless` */ /*** values - `polymorphic` - `stateless` */ /*** valuesIter - `polymorphic` - `stateless` */ /*** items - `polymorphic` - `stateless` */ /*** itemsIter - `polymorphic` - `stateless` */ 49 2009-09-09T22:13:50Z Dantman 1 2 revisions:&#32;Import from https://wiki.mozilla.org/ServerJS /*** Dict an unordered collection of key to value mappings. Unlike `Object`, a `Dict` object's key domain includes any object, with better performance when the `hash` of each key does not collide. That is, the `Number` ``1`` and the `String` ``"1"`` are distinct objects. `Dict` inherits from `Iterable` and `Set`, overriding the `eq` and `hash` of the underlying `Set` to use versions that hash and compare equivalence based on the pair component of key value pairs. Different than Python ``dict``: - ``update``: `add` - ``has_key``: `hasKey` - ``iteritems``: `itemsIter` - ``iterkeys``: `keysIter` - ``itervalues``: `valuesIter` - ``fromkeys(S, v)``: ``Dict(each(S.keys(), function (k) {return [k, v]}))`` - ``setdefault``: use `set` and `get` - ``__del__`` -> `remove` - ``__contains__`` -> `has` Same as Python: - `get` - `clear` - `copy` - `items` - `keys` - `values` - `pop` */ /**** keysIter returns an `Iter` of keys from the key and value pairs (items) in the dictionary. Uses `itemsIter`. - `stateless` */ /**** keys returns a `Set` of keys from the key and value pairs (items) in the dictionary. Uses `keysIter` and `itemsIter`. - `stateless` */ /**** valuesIter returns an `Iter` of values from the key and value pairs (items) in the dictinoary. Uses `itemsIter`. - `stateless` */ /**** values returns a `List` of values from the key and value pairs (items) in the dictionary. Uses `valuesIter` and `itemsIter`. - `stateless` */ /**** itemsIter returns an iteration, `Iter`, of the key and value pairs (items) in the dictionary. Items are represented as native JavaScript `Array` objects. Uses `iter`, which is defined for the `Set` base-type. - `stateless` */ /**** items returns a `List` of the key and value pairs (items) in the dictionary. Items are represnted as native JavaScript `Array` objects. Uses `itemsIter`. - `stateless` */ /**** get returns the value of an item in the dictionary that has a given key. If there is item for the key, attempts to return a default value, checking whether you've specified a default value to return as a second argument, or deferring to `getDefault`. If no acceptable default exists, throws a `KeyError`. accepts: - a key (any object) - an optional default value, which can be `undefined` or `null` if you wish to avoid throwing a `KeyError`. - `stateless` */ /**** set stores a key and corresponding value (an item) in the dictionary. If an item already exists in the dictionary that has the same key, it is overwritten. - stateful - chainable */ /**** put an alias for `set` */ /**** has returns whether a dictionary contains a given key. */ /**** cut returns the value for a given key and removes the corresponding key, value pair from the dictionary. - `stateful` */ /**** del deletes the key and value pair (item) in the dictionary that has a given key. - `stateful` - `chainable` */ /**** getDefault an overridable function that returns a value or throws a KeyError if you attempt to `get` an item for a key that the dictionary does not contain. - `stateless`, but overrides may be stateful. */ /**** hasValue returns whether the dictionary contains an item with the given value. - `stateless` */ /**** hasKey an alias of `has` - `stateless` */ /**** update Sets the given iterable of key value pairs on this dictionary, overriding any existing keys. - `stateful` - `chainable` */ /**** updated Returns a new copy of this dictionary that has been updated with the pairs in a given iterable. - `stateless` - `chainable` */ /**** complete Sets the given iterable of key value pairs on this dictionary, except for those with existing keys. - `stateful` - `chainable` */ /**** completed Returns a new copy of this dictionary that has been completed with the pairs in a given iterable. - `stateless` - `chainable` */ /**** find - `stateless` */ /**** findReverse since dictionary keys are not ordered, `findReverse` is an alias of `find`. - `stateless` */ /**** add - `stateful` - `chainable` */ /**** added - `stateless` - `chainable` */ /**** eq - `stateless` */ /**** repr - `stateless` */ /**** string - `stateless` */ /**** hash - `stateless` */ /**** invoke an alias of `get` that permits a dictionary to be used as a unary relation on its domain of keys to its range of values. */ /*** toDict */ /*** toObject Creates a new native JavaScript `Object` from any instance. Defers to any user defined `toObject` method of the given object. Failing that, defers to `dict` to convert the given object to a `Dict` and then creates an `Object` from that dictionary's key value pairs. */ /*** hasKey - `polymorphic` */ /*** hasValue - `polymorphic` */ /*** update - `polymoprhic` - `stateful` - `chainable` */ /*** updated - `polymorphic` - `stateless` - `chainable` */ /*** complete - `polymoprhic` - `stateful` - `chainable` */ /*** completed - `polymorphic` - `stateless` - `chainable` */ /*** clear removes all key value pairs from list and dict-like objects including native Arrays, Objects, and types that override the `clear` function like `Dict` and `List`. - `polymorphic` - `stateful` - `chainable` */ /*** keys - `polymorphic` - `stateless` */ /*** keysIter - `polymorphic` - `stateless` */ /*** values - `polymorphic` - `stateless` */ /*** valuesIter - `polymorphic` - `stateless` */ /*** items - `polymorphic` - `stateless` */ /*** itemsIter - `polymorphic` - `stateless` */ 627 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API/dict/ProposalK]] to [[CommonJS/API/dict/ProposalK]]:&#32;Subpages needed to be enabled /*** Dict an unordered collection of key to value mappings. Unlike `Object`, a `Dict` object's key domain includes any object, with better performance when the `hash` of each key does not collide. That is, the `Number` ``1`` and the `String` ``"1"`` are distinct objects. `Dict` inherits from `Iterable` and `Set`, overriding the `eq` and `hash` of the underlying `Set` to use versions that hash and compare equivalence based on the pair component of key value pairs. Different than Python ``dict``: - ``update``: `add` - ``has_key``: `hasKey` - ``iteritems``: `itemsIter` - ``iterkeys``: `keysIter` - ``itervalues``: `valuesIter` - ``fromkeys(S, v)``: ``Dict(each(S.keys(), function (k) {return [k, v]}))`` - ``setdefault``: use `set` and `get` - ``__del__`` -> `remove` - ``__contains__`` -> `has` Same as Python: - `get` - `clear` - `copy` - `items` - `keys` - `values` - `pop` */ /**** keysIter returns an `Iter` of keys from the key and value pairs (items) in the dictionary. Uses `itemsIter`. - `stateless` */ /**** keys returns a `Set` of keys from the key and value pairs (items) in the dictionary. Uses `keysIter` and `itemsIter`. - `stateless` */ /**** valuesIter returns an `Iter` of values from the key and value pairs (items) in the dictinoary. Uses `itemsIter`. - `stateless` */ /**** values returns a `List` of values from the key and value pairs (items) in the dictionary. Uses `valuesIter` and `itemsIter`. - `stateless` */ /**** itemsIter returns an iteration, `Iter`, of the key and value pairs (items) in the dictionary. Items are represented as native JavaScript `Array` objects. Uses `iter`, which is defined for the `Set` base-type. - `stateless` */ /**** items returns a `List` of the key and value pairs (items) in the dictionary. Items are represnted as native JavaScript `Array` objects. Uses `itemsIter`. - `stateless` */ /**** get returns the value of an item in the dictionary that has a given key. If there is item for the key, attempts to return a default value, checking whether you've specified a default value to return as a second argument, or deferring to `getDefault`. If no acceptable default exists, throws a `KeyError`. accepts: - a key (any object) - an optional default value, which can be `undefined` or `null` if you wish to avoid throwing a `KeyError`. - `stateless` */ /**** set stores a key and corresponding value (an item) in the dictionary. If an item already exists in the dictionary that has the same key, it is overwritten. - stateful - chainable */ /**** put an alias for `set` */ /**** has returns whether a dictionary contains a given key. */ /**** cut returns the value for a given key and removes the corresponding key, value pair from the dictionary. - `stateful` */ /**** del deletes the key and value pair (item) in the dictionary that has a given key. - `stateful` - `chainable` */ /**** getDefault an overridable function that returns a value or throws a KeyError if you attempt to `get` an item for a key that the dictionary does not contain. - `stateless`, but overrides may be stateful. */ /**** hasValue returns whether the dictionary contains an item with the given value. - `stateless` */ /**** hasKey an alias of `has` - `stateless` */ /**** update Sets the given iterable of key value pairs on this dictionary, overriding any existing keys. - `stateful` - `chainable` */ /**** updated Returns a new copy of this dictionary that has been updated with the pairs in a given iterable. - `stateless` - `chainable` */ /**** complete Sets the given iterable of key value pairs on this dictionary, except for those with existing keys. - `stateful` - `chainable` */ /**** completed Returns a new copy of this dictionary that has been completed with the pairs in a given iterable. - `stateless` - `chainable` */ /**** find - `stateless` */ /**** findReverse since dictionary keys are not ordered, `findReverse` is an alias of `find`. - `stateless` */ /**** add - `stateful` - `chainable` */ /**** added - `stateless` - `chainable` */ /**** eq - `stateless` */ /**** repr - `stateless` */ /**** string - `stateless` */ /**** hash - `stateless` */ /**** invoke an alias of `get` that permits a dictionary to be used as a unary relation on its domain of keys to its range of values. */ /*** toDict */ /*** toObject Creates a new native JavaScript `Object` from any instance. Defers to any user defined `toObject` method of the given object. Failing that, defers to `dict` to convert the given object to a `Dict` and then creates an `Object` from that dictionary's key value pairs. */ /*** hasKey - `polymorphic` */ /*** hasValue - `polymorphic` */ /*** update - `polymoprhic` - `stateful` - `chainable` */ /*** updated - `polymorphic` - `stateless` - `chainable` */ /*** complete - `polymoprhic` - `stateful` - `chainable` */ /*** completed - `polymorphic` - `stateless` - `chainable` */ /*** clear removes all key value pairs from list and dict-like objects including native Arrays, Objects, and types that override the `clear` function like `Dict` and `List`. - `polymorphic` - `stateful` - `chainable` */ /*** keys - `polymorphic` - `stateless` */ /*** keysIter - `polymorphic` - `stateless` */ /*** values - `polymorphic` - `stateless` */ /*** valuesIter - `polymorphic` - `stateless` */ /*** items - `polymorphic` - `stateless` */ /*** itemsIter - `polymorphic` - `stateless` */ 977 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/dict/ProposalK]] to [[OldAPI/dict/ProposalK]] /*** Dict an unordered collection of key to value mappings. Unlike `Object`, a `Dict` object's key domain includes any object, with better performance when the `hash` of each key does not collide. That is, the `Number` ``1`` and the `String` ``"1"`` are distinct objects. `Dict` inherits from `Iterable` and `Set`, overriding the `eq` and `hash` of the underlying `Set` to use versions that hash and compare equivalence based on the pair component of key value pairs. Different than Python ``dict``: - ``update``: `add` - ``has_key``: `hasKey` - ``iteritems``: `itemsIter` - ``iterkeys``: `keysIter` - ``itervalues``: `valuesIter` - ``fromkeys(S, v)``: ``Dict(each(S.keys(), function (k) {return [k, v]}))`` - ``setdefault``: use `set` and `get` - ``__del__`` -> `remove` - ``__contains__`` -> `has` Same as Python: - `get` - `clear` - `copy` - `items` - `keys` - `values` - `pop` */ /**** keysIter returns an `Iter` of keys from the key and value pairs (items) in the dictionary. Uses `itemsIter`. - `stateless` */ /**** keys returns a `Set` of keys from the key and value pairs (items) in the dictionary. Uses `keysIter` and `itemsIter`. - `stateless` */ /**** valuesIter returns an `Iter` of values from the key and value pairs (items) in the dictinoary. Uses `itemsIter`. - `stateless` */ /**** values returns a `List` of values from the key and value pairs (items) in the dictionary. Uses `valuesIter` and `itemsIter`. - `stateless` */ /**** itemsIter returns an iteration, `Iter`, of the key and value pairs (items) in the dictionary. Items are represented as native JavaScript `Array` objects. Uses `iter`, which is defined for the `Set` base-type. - `stateless` */ /**** items returns a `List` of the key and value pairs (items) in the dictionary. Items are represnted as native JavaScript `Array` objects. Uses `itemsIter`. - `stateless` */ /**** get returns the value of an item in the dictionary that has a given key. If there is item for the key, attempts to return a default value, checking whether you've specified a default value to return as a second argument, or deferring to `getDefault`. If no acceptable default exists, throws a `KeyError`. accepts: - a key (any object) - an optional default value, which can be `undefined` or `null` if you wish to avoid throwing a `KeyError`. - `stateless` */ /**** set stores a key and corresponding value (an item) in the dictionary. If an item already exists in the dictionary that has the same key, it is overwritten. - stateful - chainable */ /**** put an alias for `set` */ /**** has returns whether a dictionary contains a given key. */ /**** cut returns the value for a given key and removes the corresponding key, value pair from the dictionary. - `stateful` */ /**** del deletes the key and value pair (item) in the dictionary that has a given key. - `stateful` - `chainable` */ /**** getDefault an overridable function that returns a value or throws a KeyError if you attempt to `get` an item for a key that the dictionary does not contain. - `stateless`, but overrides may be stateful. */ /**** hasValue returns whether the dictionary contains an item with the given value. - `stateless` */ /**** hasKey an alias of `has` - `stateless` */ /**** update Sets the given iterable of key value pairs on this dictionary, overriding any existing keys. - `stateful` - `chainable` */ /**** updated Returns a new copy of this dictionary that has been updated with the pairs in a given iterable. - `stateless` - `chainable` */ /**** complete Sets the given iterable of key value pairs on this dictionary, except for those with existing keys. - `stateful` - `chainable` */ /**** completed Returns a new copy of this dictionary that has been completed with the pairs in a given iterable. - `stateless` - `chainable` */ /**** find - `stateless` */ /**** findReverse since dictionary keys are not ordered, `findReverse` is an alias of `find`. - `stateless` */ /**** add - `stateful` - `chainable` */ /**** added - `stateless` - `chainable` */ /**** eq - `stateless` */ /**** repr - `stateless` */ /**** string - `stateless` */ /**** hash - `stateless` */ /**** invoke an alias of `get` that permits a dictionary to be used as a unary relation on its domain of keys to its range of values. */ /*** toDict */ /*** toObject Creates a new native JavaScript `Object` from any instance. Defers to any user defined `toObject` method of the given object. Failing that, defers to `dict` to convert the given object to a `Dict` and then creates an `Object` from that dictionary's key value pairs. */ /*** hasKey - `polymorphic` */ /*** hasValue - `polymorphic` */ /*** update - `polymoprhic` - `stateful` - `chainable` */ /*** updated - `polymorphic` - `stateless` - `chainable` */ /*** complete - `polymoprhic` - `stateful` - `chainable` */ /*** completed - `polymorphic` - `stateless` - `chainable` */ /*** clear removes all key value pairs from list and dict-like objects including native Arrays, Objects, and types that override the `clear` function like `Dict` and `List`. - `polymorphic` - `stateful` - `chainable` */ /*** keys - `polymorphic` - `stateless` */ /*** keysIter - `polymorphic` - `stateless` */ /*** values - `polymorphic` - `stateless` */ /*** valuesIter - `polymorphic` - `stateless` */ /*** items - `polymorphic` - `stateless` */ /*** itemsIter - `polymorphic` - `stateless` */ 9 50 2009-03-13T07:02:34Z KrisKowal Posted current notes for the file module API Alright. The task of the month is to ratify a File API. There's been relatively little discussion on this topic. There's not much opportunity to advance the state of the art with yet another file API, which means that this will inevitably degenerate into shed painting, but it must be done! Let's just slog through this shall we? I've composed all of the functions from Ruby, Python, and Java into a very long list here. Please note which names you prefer, whether you feel a particular function ought to not be part of the standard API, any functions that are missing, and of course comment and discuss semantics. I will attempt to reserve my opinions for a follow up post. Let's begin with some high level preferences. There are a few naming choices that can be applied throughout the following document with rigor. Rather than note every occurrence of the offending word, please state your general preference: 1. make vs create make: Wes Garland (for dirs) create: George Mosochovitis, Wes Garland (for file mode) 2. dir vs directory dir: directory: Tom Robinson, Kevin Dangoor, George Mosochovitis, Wes Garland 3. cur vs current cur: current: Tom Robinson, Kevin Dangoor, Wes Garland, Kris Kowal 4. canonize, realize, normalize, qualify, canon, real, normal, qualified, absolute, canonicalize remove . and ..: normalize: Tom Robinson, Kevin Dangoor, Kris Kowal, George Mosochovitis qualify: Wes Garland remove . and .., start at /: absolute: Tom Robinson, Kevin Dangoor, Kris Kowal remove . and .., start at /, follow symlinks: canonical: Tom Robinson, Kevin Dangoor, Kris Kowal real: Tom Robinson, Kevin Dangoor Could apply for either of the two latter: absolute: George Moscochovitis, Wes Garland qualified: Wes Garland 5. constantCase vs CONSTANT_CASE vs kConstantCase There's a lot of legacy Netscape code with the pseudo Hungarian kConstantCase. CONSTANT_CASE: Tom Robinson, Kevin Dangoor constantCase: Kris Kowal, Wes Garland 6. Should "static" File methods be placed in require('file').File or : Tom Robinson, George Mosochovitis require('file') : Kris Kowal, Wes Garland e.g., var files = require('file'); files.move(a, b) vs. var File = require('file').File; File.move(a, b); Tom Robinson: should we use encoding here? Wes Garland: "b" should be stricken Wes Garland: encoding should actually be an encode function Kris Kowal: encoding should be the name of an encoding module 7. Choose: a.) setX/getX vs a.) For all functions for which it would make sense to have a setter and a getter. (It would not make sense to have a setSize, so size() would be permissible) b.) For all functions that get things (getSize, getMtime, setMtime, getBaseName) b.) setX/X Kris Kowal c.) pick and choose; no overarching convention d.) X property with getters and setters for: Davey Waterson Wes Garland Daniel Friesen against: Tom Robinson Kris Kowal exists(path) - Wes Garland Python: exists (uses stat(path) and checks for exception) Ruby: exist? exists? linkExists(path) Python: lexists Returns whether a file exists, even if it ultimately refers to a broken symbolic link. Java: not provided Wes Garland: exists(path, true) Kris Kowal: linkExists(path) move(source, target) Ruby: move rename(source, target) Ruby: rename copy(source, target) Ruby: copy systemCopy(source, target): Ruby: syscopy Copies a file from to to. If to is a directory, copies from to to/from. unnecessary - Wes Garland makeDirectory(path) Unix: mkdir createDirectory makePath(path) Ruby: makedirs Unix: mkdir -p mkpath, mkdirs, createPath, createDirectories Wes Garland: makeDirectory(path, true) Kris Kowal: makePath(path) makeTempFile(prefix, suffix) Java: createTempFile Python: mktemp mktemp(prefix, suffix), makeTemporary, makeTemp Wes Garland: this should be ommitted in favor of an alternate File constructor remove(path) Ruby: unlink, delete Python: unlink, remove Java: delete Posix: unlink Unix: rm (remove) Tom Robinson, Kevin Dangoor: remove, definitely not delete Wes Garland: unlink, but remove and delete are fine symlink(source, target) Ruby: symlink(old, new) link(source, target) Creates a hard link Ruby: File.link(old_name, new_name) => 0 Creates a new name for an existing file using a hard link. Will not overwrite new_name if it already exists (raising a subclass of SystemCallError). Not available on all platforms. Wes Garland: link(source, target, hard:Boolean) Kris Kowal: symlink, link truncate(file_name, length) create(path) Java: create Posix: creat lock(path, "shared|exculsive") - Wes Garland writeLock(path), readLock(path) tryLock(path, "shared|exclusive") - Wes Garland unlock(path) - Wes Garland opens a lock dup(fileno) - unnecessary Wes Garland dup2(fileno, fileno) - unnecessary Wes Garland Weights and Measures ==================== [new] Stat(path) returns a Stat object (more later) stat(path) returns an Array Posix: stat Java: omitted updateStat(:Stat) - Wes Garland setStat(:Stat) linkStat(path): Python: lstat Wes Garland: stat(path, true) Kris Kowal: linkStat(path) atime(path) - Tom Robinson, Kevin Dangoor Java: omitted Python: getatime Ruby: atime lastAccessed mtime(path) - Tom Robinson, Kevin Dangoor Java: lastModified Python: getmtime Ruby: mtime stat(path).st_mtime lastModified touch(path) - Kris Kowal setLastModified(path, date) setMtime(path, date) ctime(path) - Tom Robinson, Kevin Dangoor Unix: touch Java: omitted Python: getctime Ruby: ctime lastNodeModified size(path) - Tom Robinson, Kevin Dangoor Ruby: size? Java: length Python: getsize Posix: size: stat(path).st_size getLength, length, getSize, size Ownership ========= getOwner(path) getGroupOwner(path) setOwner(path, user, [group]) chown setGroupOwner(path, group) chown setLinkOwner(path, owner, [group]) Ruby: file.lchown(owner_int, group_int, file_name,..) => integer Equivalent to File::chown, but does not follow symbolic links (so it will change the owner associated with the link, not the file referenced by the link). Often not available. Returns number of files in the argument list. Wes Garland: use SetOwner(path, owner, group, true) setLinkGroupOwner(path, group) isOwned() Ruby: owned? Returns true if the named file exists and the effective used id of the calling process is the owner of the file. isGroupOwned() Ruby: grpowned? Returns true if the named file exists and the effective group id of the calling process is the owner of the file. Returns false on Windows. Please Sir, Can I Have Some More ================================ isReadable(path) Java: canRead Ruby: readable isReallyReadable(path) Ruby: readable_real? returns whether the file is readable by the current process owner. isWritable(path) Java: canWrite Ruby: writable isReallyWritable(path) Ruby: writable_real? isExecutable(path) Ruby: executable? Python: omitted isReallyExecutable(path) Ruby: executable_real? isSticky(path) returns whether the sticky bit is set, which is to say that anyone can create a file in the directory but cannot delete those created by other users. executesAsOwner(path) returns whether the file has the SID bit set. executesAsGroupOwner(path) returns whether the file has the GID bit set. setMode(path, mode) Posix: chmod Unix: chmod Ruby: chmod getMode(path) setLinkMode(path, mode) Ruby: File.lchmod(mode_int, file_name, ...) => integer Equivalent to File::chmod, but does not follow symbolic links (so it will change the permissions associated with the link, not the file referenced by the link). Often not available. setReadOnly(true|false) getModeMask() Ruby: umask() setModeMask(umask) Ruby: umask(umask) What is My Name =============== dirName(path) Python: dirname Returns the directory that contains the given path Ruby: File.dirname(file_name) Wes Garland: dirname Kris Kowal: dirName baseName(path) Java: File(fileName).getName() Python: basename(file_name) Ruby: basename(file_name, [suffix]) Unix: basename name [suffix] Wes Garland: basename Kris Kowal: baseName extension(path) Ruby: extname extensionName extension: George Mosochovitis, Wes Garland, Kris Kowal split Ruby: split Python: split Split a path in head (everything up to the last '/') and tail (the rest). If the path ends in '/', tail will be empty. If there is no '/' in the path, head will be empty. Trailing '/'es are stripped from head unless it is the root. pathComponents(path) Wes Garland splitExtension Python: splitext Split a path in root and extension. The extension is everything starting at the last dot in the last pathname component; the root is everything before that. It is always true that root + ext == p. splitDrive Python: splitDrive Split a pathname into a drive specification and the rest of the path. Useful on DOS/Windows/NT; on Unix, the drive is always empty. Where Did I Come From ===================== getType(fileName) Ruby: ftype(file_name) Identifies the type of the named file; the return string is one of ``file‚Äô‚Äô, ``directory‚Äô‚Äô, ``characterSpecial‚Äô‚Äô, ``blockSpecial‚Äô‚Äô, ``fifo‚Äô‚Äô, ``link‚Äô‚Äô, ``socket‚Äô‚Äô, or ``unknown‚Äô‚Äô. Wes Garland: type or osType isFile Python: isfile Java: isFile Ruby: file? isDirectory Java: isDirectory Python: isdir Ruby: directory? isLink Java: omitted Python: islink Ruby: symlink? isSymlink would be more accurate since it doesn't test hard links, but everything's a hard link so it's not like the name "isLink" will ever be needed for that purpose. isMount Python: ismount with some question of inter-unix compatibility undesirable - Wes Garland isSocket Ruby: socket? isPipe Ruby: pipe? isBlockDevice Ruby: blockdev?(file_name) Where Am I ========== cwd Python: os.getcwd Unix: pwd getCwd, workingDir, presentWorkingDir, currentWorkingDir Projection ---------- join(base, path) Python: join(base, rel) Java: File(parent, child) resolve(path, [base=cwd]) the path to a given path from another Python: resolve(rel, abs = '.') -> join(abs, rel) Python: abspath(path) -> normpath(join(cwd(), path)) unnecessary - Wes Garland relative(source, target) the relative path from source to target parent(path) Java: getParent Wes Garland: needs to be clear whether it's the lexical parent on the path or the parent link in the file system concatName(base, rel) Ruby: catname(from, to) If to is a valid directory, from will be appended to to, adding and escaping backslashes as necessary. Otherwise, to will be returned. Useful for appending from to to only if the filename was not specified in to. unnecessary - Wes Garland Identification -------------- absolute(path) follows symlinks from the root and produces a canonical, normal form of a path Python: realpath Unix: realpath realize, realPath, canon, canonize, canonical, getCanonical, normalize isAbsolute(path) Java: isAbsolute Python: isabs normalize(path) Python: normpath Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B. It should be understood that this may change the meaning of the path if it contains symbolic links! Jack: canonicalize canon, canonize, canonical, normal, getCanonical, getNormal normalizeCase(path) Python: normcase Normalize the case of a pathname. Trivial in Posix, string.lower on Mac. On MS-DOS this may also turn slashes into backslashes; however, other normalizations (such as optimizing '../' away) are not allowed (another function should be defined to do that). unnecessary - Wes Garland samePath(a, b) Python: samefile Ruby: identical? sameFile(a, b) Python: sameopenfile sameStat(a, b) Python: sameStat Returns whether the inode and dev are the same Platform Constants ------------------ selfDirectory ('.') Python: curdir parentDirectory ('..') Python: pardir parDir extensionSeparator Java: separator Python: extsep extsep, extSep, extensionSeparator, EXTENSION_SEPARATOR separator Java: pathSeparator Python: sep sep, separator, SEPARATOR alternateSeparator Python: altsep altsep alternateSeparator ALTERNATE_SEPARATOR deviceNull Python: devnull devNull DEV_NULL: unnecessary - Wes Garland path Python: defpath = ':/bin:/usr/bin' PATH unnecessary - Wes Garland supportsUnicodeFileName Python: supports_unicode_filenames What is a "Phone Book" ====================== match(pattern, fileName) Ruby: fnmatch(pattern, file_name, [flags]) glob(pattern) - Wes Garland, Kris Kowal Ruby: Dir[pattern] list(path) Python: os.listdir Ruby: Dir[path_glob] listdir, Dir listFiles, listDirs listIter next prev listRoots List the available filesystem roots. expand Python: expandUser -> expandVars -> normalize -> real Ruby: expand_path expandUser Python: expanduser expands '~user' expandVars Python: expandvars expands shell variables like $var and ${var} unnecessary - Wes Garland Is That Really Necessary ======================== isHidden Java: isHidden no - Wes Garland isZero(fileName) Ruby: zero? Perl: -z returns whether the file exists and is of zero length no - Wes Garland compare(source, target) Ruby: compare no - Wes Garland install(from, to, [mode], [verbose = false]) Ruby: install If src is not the same as dest, copies it and changes the permission mode to mode. If dest is a directory, destination is dest/src. If mode is not set, default is used. If verbose is set to true, the name of each file copied will be printed. no - Wes Garland url(path) Java: toURL no - Wes Garland uri(path) Java: toURI no - Wes Garland walk Python: Walk a directory tree. no - Kris Kowal commonPrefix return the longest common prefix of a list of paths. no - Kris Kowal File Type =========== [new] File(path, "+rwab", encoding) File(fileNo:Number) File(path:String, mode, encoding) File({path, mode, buffering, encoding, newLine}) File({directory, prefix}) - temp file File({command}) Mode: +, update a, append r, read w, write x, exclusive (lock) c, canon (nonblocking) construction implicitly opens does the javascript GC call a destructor function? needs to. - Kris Kowal, Wes Garland Java: FileStream Python: open is also file. file is generally preferred read() actual:Number reads to eof and returns binary read(length) actual:Number Tom Robinson, Kevin Dangoor, Wes Garland, Kris Kowal: should return Binary and Binary should have .toString(encoding=default) readLine() :String next() readInto(buffer:Binary) actual:Number write(:Binary) actual:Number seek(pos:Number, whence:Number code) tell() pos:Cookie truncate([pos:Cookie]) close() undefined readable() whether it was opened for reading writable() whether it was opened for writing seekable() whether there is random access fileNo undefined if the underlying implementation does not use file descriptors raw() raw is undefined if there is no underlying unbuffered file object readLine() :String returns "" if EOF hit immediately alternately input() to distinguish from read next() next line throws if EOF hit immediately iter() returns self (since it implements next()) forEach(relation) each(relation) readLines() writeLine() writeln, print writeLines(lines) isEOF isEof - Kris Kowal atEOF - Wes Garland, maybe fcntl - not recommended , use ioctl - Wes Garland getFileNo - not recommended, - Wes Garland toNumber an alias for `getFileNo` - not recommeded - Wes Garland getLineNo - encoding dependent, not recommended - Wes Garland isTty isTTY - Wes Garland rewind flush seek stat select fsync ioctl truncate writeLock readLock unlock dup() stat lastAccessed lastModified setLastModified lastNodeModified getSize setPos Posix/Python: seek getPos Posix/Python: tell isReadable isReallyReadable isWritable isReallyWritable isExecutable isReallyExecutable executesAsOwner executesAsGroupOwner setMode getMode setReadOnly pathComponents - Wes Garland drive extensions baseName dirName absolute fullPath - Wes Garland Directory Type ============== list forEach each iter isSticky remove match glob Stat Type ========= permissions Permissions inode Number // optional linkCount Number // optional owner String group String // optional size Number atime Date mtime Date ctime Date Permissions Type ================ owner ["read", "write"] group ["read"] world [] sticky setuid setgid Binary Type =========== Binary(:Array, [width, endian]) Binary(:String, [ecoding]) Binary.fromArray(:Array, [width, endian]) Binary.fromString(:String, [encoding]) Binary.createBuffer(length, [fill = 0]) Binary.prototype.toString(encoding) Array.prototype.toBinary([width, endian]) Todo ==== Split File into File and IO base (Tom Robinson, Kevin Dangoor) Clarify difference between canRead, isReadable, and select Resolve the default encoding for Binary.toString() Note distinction between read():Binary and input():String, as well as write(:Binary) and print(String) getEncoding setEncoding George Mosochovitis: divide among FileSystem, Path, and File References ========== http://www.python.org/dev/peps/pep-3116/ http://www.erights.org/javadoc/java/io/File.html http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html http://docs.python.org/library/os.path.html http://www.ruby-doc.org/core/classes/File.html http://www.ruby-doc.org/core/classes/IO.html 51 2009-03-24T23:16:45Z KrisKowal Draft 2 of File API discussion = High Level = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = API and Proposed Names = == File System Object == * the location of the file system type. ** environment.fs ** The file module would not expose a FileSystem constructor, since that implies "ambient authority" to get wholesale access to the file system, although platform specific modules that depend on ambient authority in a permissive environment might be used to construct this FileSystem object, and it could be then safely chrooted or passed directly to a sandbox in its environment with the same name. The "fs" object would conform to the following API. * the location of the file system object provided to your environment. ** is provided as "environment.fs" in all modules and has all of the properties and methods defined for the FileSystem type: *** Kris Kowal * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) * moves a file from a source to a target path. both paths are joined on the current working directory. ** move(source, target): *** uncontested * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): *** uncontested * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente * makes any directories that are missing on a given path. Does not throw an exception if any of the base paths are missing, and does not throw an exception if all of the path already exists. Only throws an exception if it can't make the path exist. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): *** uncontested * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. ** update(path, stat): *** Wes Garland * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal * locks the file at a given path with either an exclusive or shared lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal * attempts to lock a file at a given path. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. ** tryLock(path, "shared|exclusive"): *** Wes Garland * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) * returns the size of the corresponding file. ** size(path) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. ** open(path, "+arwxc", encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) * returns whether a given path matches a glob pattern. ** match(pattern, path) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem. * a string directing a path up to the parent of the current directory, usually '..'. ** parent ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) * a string directing a path back to itself, usually '.'. ** self * a string that contains the path separator, usually '/', '\', or ':'. ** separator * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** alternateSeparator * a string that contains the extension separator, usually '.'. ** extensionSeparator * whether the file system supports unicode file names ** supportsUnicodeFileNames * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. ** absolute(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) * returns the intrinsic path to a given file. Resolves the path relative to the current working directory. This involves tracing the hard parent links of it and its ancestors until reaching the root of the file system. If the file system was returned by chroot, returns undefined if the parent links traverse to a path that's inaccessible from the chroot, if the file system is chrooted. ** canonical(path) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** lastAccessed: *** Kris Kowal ** atime: *** Tom Robinson *** Kevin Dangoor * the Date that the file was last modified. ** lastModified: *** Kris Kowal *** Mario Valente ** mtime: *** Tom Robinson *** Kevin Dangoor * the Date that the file's stat/metadata was last modified. ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** ctime: *** Tom Robinson *** Kevin Dangoor * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** ommit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** ommit entirely: *** Wes Garland * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) * returns whether the cursor is at the end of the IO stream. ** isEof(): *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** eof() * flushes buffers for an IO stream ** flush() * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = File Module = The file module would export a copy of every property on "environment.fs", for convenience. Thus:: require('file').open(foo) Would be equivalent to: environment.fs.open(foo) = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = References = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API : http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 52 2009-03-24T23:20:27Z KrisKowal fixed the last reference formatting = High Level = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = API and Proposed Names = == File System Object == * the location of the file system type. ** environment.fs ** The file module would not expose a FileSystem constructor, since that implies "ambient authority" to get wholesale access to the file system, although platform specific modules that depend on ambient authority in a permissive environment might be used to construct this FileSystem object, and it could be then safely chrooted or passed directly to a sandbox in its environment with the same name. The "fs" object would conform to the following API. * the location of the file system object provided to your environment. ** is provided as "environment.fs" in all modules and has all of the properties and methods defined for the FileSystem type: *** Kris Kowal * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) * moves a file from a source to a target path. both paths are joined on the current working directory. ** move(source, target): *** uncontested * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): *** uncontested * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente * makes any directories that are missing on a given path. Does not throw an exception if any of the base paths are missing, and does not throw an exception if all of the path already exists. Only throws an exception if it can't make the path exist. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): *** uncontested * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. ** update(path, stat): *** Wes Garland * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal * locks the file at a given path with either an exclusive or shared lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal * attempts to lock a file at a given path. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. ** tryLock(path, "shared|exclusive"): *** Wes Garland * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) * returns the size of the corresponding file. ** size(path) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. ** open(path, "+arwxc", encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) * returns whether a given path matches a glob pattern. ** match(pattern, path) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem. * a string directing a path up to the parent of the current directory, usually '..'. ** parent ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) * a string directing a path back to itself, usually '.'. ** self * a string that contains the path separator, usually '/', '\', or ':'. ** separator * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** alternateSeparator * a string that contains the extension separator, usually '.'. ** extensionSeparator * whether the file system supports unicode file names ** supportsUnicodeFileNames * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. ** absolute(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) * returns the intrinsic path to a given file. Resolves the path relative to the current working directory. This involves tracing the hard parent links of it and its ancestors until reaching the root of the file system. If the file system was returned by chroot, returns undefined if the parent links traverse to a path that's inaccessible from the chroot, if the file system is chrooted. ** canonical(path) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** lastAccessed: *** Kris Kowal ** atime: *** Tom Robinson *** Kevin Dangoor * the Date that the file was last modified. ** lastModified: *** Kris Kowal *** Mario Valente ** mtime: *** Tom Robinson *** Kevin Dangoor * the Date that the file's stat/metadata was last modified. ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** ctime: *** Tom Robinson *** Kevin Dangoor * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** ommit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** ommit entirely: *** Wes Garland * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) * returns whether the cursor is at the end of the IO stream. ** isEof(): *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** eof() * flushes buffers for an IO stream ** flush() * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = File Module = The file module would export a copy of every property on "environment.fs", for convenience. Thus:: require('file').open(foo) Would be equivalent to: environment.fs.open(foo) = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = References = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 53 2009-03-24T23:36:13Z KrisKowal /* References */ = High Level = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = API and Proposed Names = == File System Object == * the location of the file system type. ** environment.fs ** The file module would not expose a FileSystem constructor, since that implies "ambient authority" to get wholesale access to the file system, although platform specific modules that depend on ambient authority in a permissive environment might be used to construct this FileSystem object, and it could be then safely chrooted or passed directly to a sandbox in its environment with the same name. The "fs" object would conform to the following API. * the location of the file system object provided to your environment. ** is provided as "environment.fs" in all modules and has all of the properties and methods defined for the FileSystem type: *** Kris Kowal * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) * moves a file from a source to a target path. both paths are joined on the current working directory. ** move(source, target): *** uncontested * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): *** uncontested * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente * makes any directories that are missing on a given path. Does not throw an exception if any of the base paths are missing, and does not throw an exception if all of the path already exists. Only throws an exception if it can't make the path exist. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): *** uncontested * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. ** update(path, stat): *** Wes Garland * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal * locks the file at a given path with either an exclusive or shared lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal * attempts to lock a file at a given path. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. ** tryLock(path, "shared|exclusive"): *** Wes Garland * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) * returns the size of the corresponding file. ** size(path) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. ** open(path, "+arwxc", encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) * returns whether a given path matches a glob pattern. ** match(pattern, path) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem. * a string directing a path up to the parent of the current directory, usually '..'. ** parent ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) * a string directing a path back to itself, usually '.'. ** self * a string that contains the path separator, usually '/', '\', or ':'. ** separator * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** alternateSeparator * a string that contains the extension separator, usually '.'. ** extensionSeparator * whether the file system supports unicode file names ** supportsUnicodeFileNames * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. ** absolute(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) * returns the intrinsic path to a given file. Resolves the path relative to the current working directory. This involves tracing the hard parent links of it and its ancestors until reaching the root of the file system. If the file system was returned by chroot, returns undefined if the parent links traverse to a path that's inaccessible from the chroot, if the file system is chrooted. ** canonical(path) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** lastAccessed: *** Kris Kowal ** atime: *** Tom Robinson *** Kevin Dangoor * the Date that the file was last modified. ** lastModified: *** Kris Kowal *** Mario Valente ** mtime: *** Tom Robinson *** Kevin Dangoor * the Date that the file's stat/metadata was last modified. ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** ctime: *** Tom Robinson *** Kevin Dangoor * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** ommit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** ommit entirely: *** Wes Garland * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) * returns whether the cursor is at the end of the IO stream. ** isEof(): *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** eof() * flushes buffers for an IO stream ** flush() * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = File Module = The file module would export a copy of every property on "environment.fs", for convenience. Thus:: require('file').open(foo) Would be equivalent to: environment.fs.open(foo) = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = Inspiration = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 54 2009-03-25T07:58:13Z Ondras /* High Level */ = High Level = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) #** Ondrej Zara # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #** Ondrej Zara #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #** Ondrej Zara #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #** expand: #*** Ondrej Zara #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #** normalize: #*** Ondrej Zara #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor #** Ondrej Zara # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #** Ondrej Zara #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = API and Proposed Names = == File System Object == * the location of the file system type. ** environment.fs ** The file module would not expose a FileSystem constructor, since that implies "ambient authority" to get wholesale access to the file system, although platform specific modules that depend on ambient authority in a permissive environment might be used to construct this FileSystem object, and it could be then safely chrooted or passed directly to a sandbox in its environment with the same name. The "fs" object would conform to the following API. * the location of the file system object provided to your environment. ** is provided as "environment.fs" in all modules and has all of the properties and methods defined for the FileSystem type: *** Kris Kowal * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) * moves a file from a source to a target path. both paths are joined on the current working directory. ** move(source, target): *** uncontested * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): *** uncontested * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente * makes any directories that are missing on a given path. Does not throw an exception if any of the base paths are missing, and does not throw an exception if all of the path already exists. Only throws an exception if it can't make the path exist. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): *** uncontested * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. ** update(path, stat): *** Wes Garland * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal * locks the file at a given path with either an exclusive or shared lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal * attempts to lock a file at a given path. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. ** tryLock(path, "shared|exclusive"): *** Wes Garland * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) * returns the size of the corresponding file. ** size(path) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. ** open(path, "+arwxc", encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) * returns whether a given path matches a glob pattern. ** match(pattern, path) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem. * a string directing a path up to the parent of the current directory, usually '..'. ** parent ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) * a string directing a path back to itself, usually '.'. ** self * a string that contains the path separator, usually '/', '\', or ':'. ** separator * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** alternateSeparator * a string that contains the extension separator, usually '.'. ** extensionSeparator * whether the file system supports unicode file names ** supportsUnicodeFileNames * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. ** absolute(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) * returns the intrinsic path to a given file. Resolves the path relative to the current working directory. This involves tracing the hard parent links of it and its ancestors until reaching the root of the file system. If the file system was returned by chroot, returns undefined if the parent links traverse to a path that's inaccessible from the chroot, if the file system is chrooted. ** canonical(path) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** lastAccessed: *** Kris Kowal ** atime: *** Tom Robinson *** Kevin Dangoor * the Date that the file was last modified. ** lastModified: *** Kris Kowal *** Mario Valente ** mtime: *** Tom Robinson *** Kevin Dangoor * the Date that the file's stat/metadata was last modified. ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** ctime: *** Tom Robinson *** Kevin Dangoor * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** ommit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** ommit entirely: *** Wes Garland * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) * returns whether the cursor is at the end of the IO stream. ** isEof(): *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** eof() * flushes buffers for an IO stream ** flush() * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = File Module = The file module would export a copy of every property on "environment.fs", for convenience. Thus:: require('file').open(foo) Would be equivalent to: environment.fs.open(foo) = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = Inspiration = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 55 2009-03-25T08:03:52Z Ondras /* Stat Object */ = High Level = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) #** Ondrej Zara # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #** Ondrej Zara #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #** Ondrej Zara #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #** expand: #*** Ondrej Zara #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #** normalize: #*** Ondrej Zara #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor #** Ondrej Zara # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #** Ondrej Zara #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = API and Proposed Names = == File System Object == * the location of the file system type. ** environment.fs ** The file module would not expose a FileSystem constructor, since that implies "ambient authority" to get wholesale access to the file system, although platform specific modules that depend on ambient authority in a permissive environment might be used to construct this FileSystem object, and it could be then safely chrooted or passed directly to a sandbox in its environment with the same name. The "fs" object would conform to the following API. * the location of the file system object provided to your environment. ** is provided as "environment.fs" in all modules and has all of the properties and methods defined for the FileSystem type: *** Kris Kowal * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) * moves a file from a source to a target path. both paths are joined on the current working directory. ** move(source, target): *** uncontested * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): *** uncontested * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente * makes any directories that are missing on a given path. Does not throw an exception if any of the base paths are missing, and does not throw an exception if all of the path already exists. Only throws an exception if it can't make the path exist. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): *** uncontested * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. ** update(path, stat): *** Wes Garland * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal * locks the file at a given path with either an exclusive or shared lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal * attempts to lock a file at a given path. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. ** tryLock(path, "shared|exclusive"): *** Wes Garland * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) * returns the size of the corresponding file. ** size(path) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. ** open(path, "+arwxc", encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) * returns whether a given path matches a glob pattern. ** match(pattern, path) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem. * a string directing a path up to the parent of the current directory, usually '..'. ** parent ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) * a string directing a path back to itself, usually '.'. ** self * a string that contains the path separator, usually '/', '\', or ':'. ** separator * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** alternateSeparator * a string that contains the extension separator, usually '.'. ** extensionSeparator * whether the file system supports unicode file names ** supportsUnicodeFileNames * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. ** absolute(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) * returns the intrinsic path to a given file. Resolves the path relative to the current working directory. This involves tracing the hard parent links of it and its ancestors until reaching the root of the file system. If the file system was returned by chroot, returns undefined if the parent links traverse to a path that's inaccessible from the chroot, if the file system is chrooted. ** canonical(path) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** lastAccessed: *** Kris Kowal ** atime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara * the Date that the file was last modified. ** lastModified: *** Kris Kowal *** Mario Valente ** mtime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara * the Date that the file's stat/metadata was last modified. ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** ctime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** ommit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** ommit entirely: *** Wes Garland *** Ondrej Zara * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size *** Ondrej Zara * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) * returns whether the cursor is at the end of the IO stream. ** isEof(): *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** eof() * flushes buffers for an IO stream ** flush() * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = File Module = The file module would export a copy of every property on "environment.fs", for convenience. Thus:: require('file').open(foo) Would be equivalent to: environment.fs.open(foo) = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = Inspiration = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 56 2009-03-25T22:14:02Z Gmosx /* High Level */ = High Level = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) #** Ondrej Zara # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #** Ondrej Zara #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #** Ondrej Zara #** George Moschovitis #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #** expand: #*** Ondrej Zara #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #** normalize: #*** Ondrej Zara #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor #** Ondrej Zara #** George Moschovitis # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #** Ondrej Zara #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = API and Proposed Names = == File System Object == * the location of the file system type. ** environment.fs ** The file module would not expose a FileSystem constructor, since that implies "ambient authority" to get wholesale access to the file system, although platform specific modules that depend on ambient authority in a permissive environment might be used to construct this FileSystem object, and it could be then safely chrooted or passed directly to a sandbox in its environment with the same name. The "fs" object would conform to the following API. * the location of the file system object provided to your environment. ** is provided as "environment.fs" in all modules and has all of the properties and methods defined for the FileSystem type: *** Kris Kowal * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) * moves a file from a source to a target path. both paths are joined on the current working directory. ** move(source, target): *** uncontested * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): *** uncontested * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente * makes any directories that are missing on a given path. Does not throw an exception if any of the base paths are missing, and does not throw an exception if all of the path already exists. Only throws an exception if it can't make the path exist. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): *** uncontested * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. ** update(path, stat): *** Wes Garland * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal * locks the file at a given path with either an exclusive or shared lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal * attempts to lock a file at a given path. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. ** tryLock(path, "shared|exclusive"): *** Wes Garland * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) * returns the size of the corresponding file. ** size(path) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. ** open(path, "+arwxc", encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) * returns whether a given path matches a glob pattern. ** match(pattern, path) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem. * a string directing a path up to the parent of the current directory, usually '..'. ** parent ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) * a string directing a path back to itself, usually '.'. ** self * a string that contains the path separator, usually '/', '\', or ':'. ** separator * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** alternateSeparator * a string that contains the extension separator, usually '.'. ** extensionSeparator * whether the file system supports unicode file names ** supportsUnicodeFileNames * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. ** absolute(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) * returns the intrinsic path to a given file. Resolves the path relative to the current working directory. This involves tracing the hard parent links of it and its ancestors until reaching the root of the file system. If the file system was returned by chroot, returns undefined if the parent links traverse to a path that's inaccessible from the chroot, if the file system is chrooted. ** canonical(path) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** lastAccessed: *** Kris Kowal ** atime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara * the Date that the file was last modified. ** lastModified: *** Kris Kowal *** Mario Valente ** mtime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara * the Date that the file's stat/metadata was last modified. ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** ctime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** ommit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** ommit entirely: *** Wes Garland *** Ondrej Zara * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size *** Ondrej Zara * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) * returns whether the cursor is at the end of the IO stream. ** isEof(): *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** eof() * flushes buffers for an IO stream ** flush() * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = File Module = The file module would export a copy of every property on "environment.fs", for convenience. Thus:: require('file').open(foo) Would be equivalent to: environment.fs.open(foo) = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = Inspiration = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 57 2009-03-26T06:38:53Z KrisKowal Reinserted etymologies. = API and Proposed Names = The following sections are organized with a bullet point per function. Each point includes a specification for the behavior of a given method, intended to be suitable for documentation. Under each definition is a list of potential names for that function, and in bullets beneath that, everyone is encouraged to write their name under their preference. Please feel to leave comments as well. In the next section, "General Preferences", there are several broad sweeping points about whether to use certain conventions in a consistent fashion. All of the name options are intended to conform to the prevalent opinion among those elections. For example, "make" and "create" and "dir" and "directory" are both general preference elections, so if you would prefer "makeDir" over "createDirectory", please vote independently for "make" and "dir" in the general preferences. == File System Object == The "file" module would conform to the File System API, as well as objects returned by "chroot". There is no definitive implementation of a FileSystem class, so "chroot" is the only way to construct new objects that conform to the FileSystem API. In permissive environments, the "file" module may have direct access to ambient authority through a foreign function interface, or may itself be a dynamically loaded module. In secured environments, the "file" module must copy the properties of "environment.fs" onto its exports. In a secure sandbox, the following statements would be equivalent. require('file').open(foo) environment.fs.open(foo) Since "fs" must be frozen to be secure, there is no need for the "file" module to assemble aparatus for late binding to "fs" methods. * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland *** (Python: os.path.exists, Ruby: exist?, exists?, Java: exists, JSExt: access, Spidermonkey: Helma: v8cgi: JSExt: EJScript: Synchronet: exists, jslibs: exist) * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.path.lexists) * moves a file from a source to a target path. Both paths are joined on the current working directory. ** move(source, target): ** (Ruby: move, Python: shutil.move, Java: File.renameTo) * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal ** (Ruby: rename) * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): ** (Ruby: copy, systemCopy, Python: copy, Unix: cp) * copies a file and its recursive contents to a target path. Both paths are joined on the current working directory. If "synbolicLinks" is truthy, symbolic links in the source tree are represented as symbolic links in the new tree; if falsy, the contents of the linked files are copied to the new tree. If ignore is given, it must be a relation that will receive as its arguments the directory being visited by copytree(), and a list of its contents. Since this is called recursively (or walking an equivalent iteration), the ignore relation will be called once for each directory that is copied. The relation must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. ** copyTree(source, target, symbolicLinks = false, ignore = undefined) ** copy(source, target, "recursive") ** copy(source, target, true) ** (Python: copytree) * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente ** (Unix: mkdir) * creates recursive directories. Makes all intermediate-level directories needed to contain the leaf directory. Throws an exception if the leaf directory already exists or cannot be created. The default mode is 0777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "recursive"): ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) ** makeTree(path) ** (Unix: mkdir -p, Ruby: makedirs, mkpath, Python: os.makedirs) * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland ** (Ruby: unlink, delete, Python: unlink, remove, Java: delete, Posix: unlink, Unix: rm, Spidermonkey: Helma: EJScript: Synchronet: remove, jslibs: Delete) * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) ** removeTree(path, ignoreErrors = false, onError = undefined) ** (Unix: rm -r, Python: rmtree) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested ** (Python: link, Ruby: link, Unix: ln) * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) ** (Ruby: symlink, Python: symlink, Unix: ln -s) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland ** (Java: createNewFile, Posix: creat, Unix: touch) * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): ** omit entirely: *** Kris Kowal ** (Ruby: truncate, Python: ftruncate applies to open files only) * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. *** Wes Garland ** update(path, stat): ** chstat(path, stat): ** setStat(path, stat): ** restat(path, stat): ** (a low-level alternative to Python's copy2 and copyStat) * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal ** (Unix: touch) * locks the file at a given path with either an exclusive or shared advisory lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal ** lock(path, "rw|") ** (Posix: lock, Python: lock) * attempts to acquire an advisory lock a file at a given path but does not block. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. *** Wes Garland ** tryLock(path, "shared|exclusive"): ** lock(path, "rw") ** (Python: lock) * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") ** lock(path, "u") ** (Python: lock) * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente ** (Python: os.stat, Ruby: File.stat, Posix: stat) * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.lstat, Ruby: File.lstat) * returns the size of the corresponding file. ** size(path) ** (Python: size, Ruby: size?: Java: length, Posix: st_size) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. The given permissions object may be a Unix numeric representation of permissions, a Stat object, or any object that provides the members of Stat regarding permissions. ** open(path, "+arwxc", permissions, encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) ** (Java: FileStream classes, Python: open, file, Ruby: File.new, universal precedent among SSJS frameworks) * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) ** (Python: os.listdir, Ruby: Dir) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) ** (Ruby: Dir[]) * returns whether a given path matches a glob pattern. ** match(pattern, path) ** (Ruby: fnmatch) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem object. * a string directing a path up to the parent of the current directory, usually '..'. ** PARENT ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) ** (Python: pardir) * a string directing a path back to itself, usually '.'. ** SELF ** (Python: curdir) * a string that contains the path separator, usually '/', '\', or ':'. ** SEPARATOR ** (Python: sep, Spidermonkey: separator, Ruby: SEPARATOR, Separator) * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** ALTERNATE_SEPARATOR ** (Python: altsep, Ruby: ALT_SEPARATOR) * a string that contains the extension separator, usually '.'. ** EXTENSION_SEPRATOR ** (Python: extsep) * whether the file system supports unicode file names ** SUPPORTS_UNICODE_FILE_NAMES * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) ** (not precedented) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland ** (Python: Unix: dirname) * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland ** (Python: Unix: basename) * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland ** (Ruby: extname) * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) ** (Python: normpath) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to epxanding any user directory alias, joining the path to the current working directory, and normalizing the result. ** absolute(path) ** (Python: abspath) * returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding an user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. ** canonical(path) ** (Python: realpath) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) ** (Python: isabs) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** atime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastAccessed: *** Kris Kowal ** (Python: getatime, Ruby: atime) * the Date that the file was last modified. ** mtime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastModified: *** Kris Kowal *** Mario Valente ** (Python: getmtime, Ruby: mtime, Java: Spidermonkey: Helma: lastModified, jslibs: modifyTime, EJScript: modified, Synchronet: date) * the Date that the file's stat/metadata was last modified. ** ctime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** (Ruby: ctime, Python: getctime) * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: ** omit entirely: *** Kris Kowal ** (Spidermonkey: jslibs: creationTime, EJScript: create) * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** omit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory ** (Spidermonkey: isDir, Helma: isDir, JSExt: isdir) * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** omit entirely: *** Wes Garland *** Ondrej Zara * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size *** Ondrej Zara ** (jslibs: size, Helma: getLength, Spidermonkey: wxJS: EJScript: Synchronet: length) * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner ** setuid * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner ** setgid * whether the corresponding directory will permit anyone to create files in it, but only let the owner of a file delete it. ** sticky * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() ** (Python: JSExt: readline, Spidermonkey: Helma: Synchronet: readln) * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() ** (Python: readlines, JSExt: readlines, EJScript: getLines) * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) ** (universal precedent) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() ** (wxJS: JSExt: Python: Ruby: tell) * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) ** (Ruby: truncate, Python: ftruncate) * returns whether the cursor is at the end of the IO stream. ** eof() *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** (Helma: wxJS: JSExt: Synchronet: eof) * flushes buffers for an IO stream ** flush() ** (universal precedent) * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") ** (related to isOpen in many existing SSJS frameworks, but without a race condition hazard) * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = General Preferences = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) #** Ondrej Zara # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #** Ondrej Zara #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #** Ondrej Zara #** George Moschovitis #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #** expand: #*** Ondrej Zara #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #** normalize: #*** Ondrej Zara #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor #** Ondrej Zara #** George Moschovitis #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #** Ondrej Zara #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = References = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 58 2009-03-26T06:42:47Z KrisKowal Reinserted etymologies. = API and Proposed Names = The following sections are organized with a bullet point per function. Each point includes a specification for the behavior of a given method, intended to be suitable for documentation. Under each definition is a list of potential names for that function, and in bullets beneath that, everyone is encouraged to write their name under their preference. Please feel to leave comments as well. In the next section, "General Preferences", there are several broad sweeping points about whether to use certain conventions in a consistent fashion. All of the name options are intended to conform to the prevalent opinion among those elections. For example, "make" and "create" and "dir" and "directory" are both general preference elections, so if you would prefer "makeDir" over "createDirectory", please vote independently for "make" and "dir" in the general preferences. == File System Object == The "file" module would conform to the File System API, as well as objects returned by "chroot". There is no definitive implementation of a FileSystem class, so "chroot" is the only way to construct new objects that conform to the FileSystem API. In permissive environments, the "file" module may have direct access to ambient authority through a foreign function interface, or may itself be a dynamically loaded module. In secured environments, the "file" module must copy the properties of "environment.fs" onto its exports. In a secure sandbox, the following statements would be equivalent. require('file').open(foo) environment.fs.open(foo) Since "fs" must be frozen to be secure, there is no need for the "file" module to assemble aparatus for late binding to "fs" methods. * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland *** (Python: os.path.exists, Ruby: exist?, exists?, Java: exists, JSExt: access, Spidermonkey: Helma: v8cgi: JSExt: EJScript: Synchronet: exists, jslibs: exist) * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.path.lexists) * moves a file from a source to a target path. Both paths are joined on the current working directory. ** move(source, target): ** (Ruby: move, Python: shutil.move, Java: File.renameTo) * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal ** (Ruby: rename) * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): ** (Ruby: copy, systemCopy, Python: copy, Unix: cp) * copies a file and its recursive contents to a target path. Both paths are joined on the current working directory. If "synbolicLinks" is truthy, symbolic links in the source tree are represented as symbolic links in the new tree; if falsy, the contents of the linked files are copied to the new tree. If ignore is given, it must be a relation that will receive as its arguments the directory being visited by copytree(), and a list of its contents. Since this is called recursively (or walking an equivalent iteration), the ignore relation will be called once for each directory that is copied. The relation must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. ** copyTree(source, target, symbolicLinks = false, ignore = undefined) ** copy(source, target, "recursive") ** copy(source, target, true) ** (Python: copytree) * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente ** (Unix: mkdir) * creates recursive directories. Makes all intermediate-level directories needed to contain the leaf directory. Throws an exception if the leaf directory already exists or cannot be created. The default mode is 0777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "recursive"): ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) ** makeTree(path) ** (Unix: mkdir -p, Ruby: makedirs, mkpath, Python: os.makedirs) * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland ** (Ruby: unlink, delete, Python: unlink, remove, Java: delete, Posix: unlink, Unix: rm, Spidermonkey: Helma: EJScript: Synchronet: remove, jslibs: Delete) * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) ** removeTree(path, ignoreErrors = false, onError = undefined) ** (Unix: rm -r, Python: rmtree) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested ** (Python: link, Ruby: link, Unix: ln) * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) ** (Ruby: symlink, Python: symlink, Unix: ln -s) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland ** (Java: createNewFile, Posix: creat, Unix: touch) * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): ** omit entirely: *** Kris Kowal ** (Ruby: truncate, Python: ftruncate applies to open files only) * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. *** Wes Garland ** update(path, stat): ** chstat(path, stat): ** setStat(path, stat): ** restat(path, stat): ** (a low-level alternative to Python's copy2 and copyStat) * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal ** (Unix: touch) * locks the file at a given path with either an exclusive or shared advisory lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal ** lock(path, "rw|") ** (Posix: lock, Python: lock) * attempts to acquire an advisory lock a file at a given path but does not block. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. *** Wes Garland ** tryLock(path, "shared|exclusive"): ** lock(path, "rw") ** (Python: lock) * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") ** lock(path, "u") ** (Python: lock) * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente ** (Python: os.stat, Ruby: File.stat, Posix: stat) * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.lstat, Ruby: File.lstat) * returns the size of the corresponding file. ** size(path) ** (Python: size, Ruby: size?: Java: length, Posix: st_size) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. The given permissions object may be a Unix numeric representation of permissions, a Stat object, or any object that provides the members of Stat regarding permissions. ** open(path, "+arwxc", permissions, encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) ** (Java: FileStream classes, Python: open, file, Ruby: File.new, universal precedent among SSJS frameworks) * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) ** (Python: os.listdir, Ruby: Dir) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) ** (Ruby: Dir[]) * returns whether a given path matches a glob pattern. ** match(pattern, path) ** (Ruby: fnmatch) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem object. * a string directing a path up to the parent of the current directory, usually '..'. ** PARENT ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) ** (Python: pardir) * a string directing a path back to itself, usually '.'. ** SELF ** (Python: curdir) * a string that contains the path separator, usually '/', '\', or ':'. ** SEPARATOR ** (Python: sep, Spidermonkey: separator, Ruby: SEPARATOR, Separator) * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** ALTERNATE_SEPARATOR ** (Python: altsep, Ruby: ALT_SEPARATOR) * a string that contains the extension separator, usually '.'. ** EXTENSION_SEPRATOR ** (Python: extsep) * whether the file system supports unicode file names ** SUPPORTS_UNICODE_FILE_NAMES * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) ** (not precedented) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland ** (Python: Unix: dirname) * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland ** (Python: Unix: basename) * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland ** (Ruby: extname) * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) ** (Python: normpath) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to epxanding any user directory alias, joining the path to the current working directory, and normalizing the result. ** absolute(path) ** (Python: abspath) * returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding an user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. ** canonical(path) ** (Python: realpath) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) ** (Python: isabs) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** atime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastAccessed: *** Kris Kowal ** (Python: getatime, Ruby: atime) * the Date that the file was last modified. ** mtime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastModified: *** Kris Kowal *** Mario Valente ** (Python: getmtime, Ruby: mtime, Java: Spidermonkey: Helma: lastModified, jslibs: modifyTime, EJScript: modified, Synchronet: date) * the Date that the file's stat/metadata was last modified. ** ctime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** (Ruby: ctime, Python: getctime) * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: ** omit entirely: *** Kris Kowal ** (Spidermonkey: jslibs: creationTime, EJScript: create) * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** omit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory ** (Spidermonkey: isDir, Helma: isDir, JSExt: isdir) * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** omit entirely: *** Wes Garland *** Ondrej Zara * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size *** Ondrej Zara ** (jslibs: size, Helma: getLength, Spidermonkey: wxJS: EJScript: Synchronet: length) * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner ** setuid * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner ** setgid * whether the corresponding directory will permit anyone to create files in it, but only let the owner of a file delete it. ** sticky * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() ** (Python: JSExt: readline, Spidermonkey: Helma: Synchronet: readln) * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() ** (Python: readlines, JSExt: readlines, EJScript: getLines) * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) ** (universal precedent) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() ** (wxJS: JSExt: Python: Ruby: tell) * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) ** (Ruby: truncate, Python: ftruncate) * returns whether the cursor is at the end of the IO stream. ** eof() *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** (Helma: wxJS: JSExt: Synchronet: eof) * flushes buffers for an IO stream ** flush() ** (universal precedent) * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") ** (related to isOpen in many existing SSJS frameworks, but without a race condition hazard) * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = General Preferences = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) #** Ondrej Zara # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #** Ondrej Zara #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #** Ondrej Zara #** George Moschovitis #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #** expand: #*** Ondrej Zara #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #** normalize: #*** Ondrej Zara #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor #** Ondrej Zara #** George Moschovitis #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #** Ondrej Zara #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = References = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 59 2009-03-29T03:50:37Z KrisKowal Added a proposal for a tier1 specification of the File API = Tier 1 = The require('file') module would provide support the File System API. In turn, the File System API would provide all methods that deal with path strings. File System API functions would return file stream objects, directory objects, and file stat objects. File stream objects would, for securability, be unaware of their corresponding path, and keep their underlying file system connection, albeit a file descriptor or FILE*, and their parent directory link, secret. The File System API would provide the following methods: * normal: removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. * absolute: returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result. * canonical: returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. * exists(path): whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. * existsLink(path): whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. * stat(path): returns an object that represents a snapshot of the information about given file. *# The stat file must contain the following properties: *## mtime: the time that the file was last modified *## other properties will be specified in a future specification, including other times, ownership, permissions, and size. *# The path is resolved relative to the current working directory. *# Throws an error if the corresponding file does not exist or is inaccessible. * statLink(path): returns the same object as stat, except for the symbolic link at the end of the path, if it is a symbolic link. * list(path): returns a traversable, indexable representation of the names of files in a particular directory. *# The returned object implements the Array API for indexing, and may in fact be an Array if the underlying implementation is not sophhisticated enough to do lazy indexing. The prototype of the returned object contains all of the Array generics like "push", "pop", and such. *# The returned object may be immutable. *# The returned object must implement "next" and "prev", which walk backward and forward among the file names in the directory. Both throw an exception when they are beyond the bounds of the directory. *# The path is resolved relative to the current working directory. *# 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. *# 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). *# The mode is a String and may contain: *## "r" that means that the stream may be read, and implies that the "read", "readLine", "readLines", "next", and "iter" methods must be supported by the returned stream object. "readLine" returns "" on EOF, and "next" throws an error instead. "iter" returns the stream object itself. "readLine" returns a string excluding the newline character. *## "w" that means that the stream may be written to, and implies that the "write", "writeLine", and "writeLines" methods must be supported by the stream object. Also implies that the file will be created or truncated if necessary, if not overridden by the "a" or "+" flags. *## "a" that means that the stream's position will begin at the end of the stream, and that the file will be created but not truncated. *## "+" that means that the stream will not be truncated. *## other options may be added in the future for advisory locks. *## the "b" option known in other languages will not be implemented since it is really an encoding argument. *# The permissions must be an integer of Unix style permissions. Other objects may be permitted in a later specification, like a Stat object or duck-type thereof. *# The path is resolved relative to the current working directory. *# Throws an error if the specified stream cannot be created. = Tier 2 = In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names|proposed names]. 60 2009-03-29T03:55:53Z KrisKowal /* Tier 1 */ removed symlink variants for tier 1 = Tier 1 = The require('file') module would provide support the File System API. In turn, the File System API would provide all methods that deal with path strings. File System API functions would return file stream objects, directory objects, and file stat objects. File stream objects would, for securability, be unaware of their corresponding path, and keep their underlying file system connection, albeit a file descriptor or FILE*, and their parent directory link, secret. The File System API would provide the following methods: * normal: removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. * absolute: returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result. * canonical: returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. * exists(path): whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. * stat(path): returns an object that represents a snapshot of the information about given file. *# The stat file must contain the following properties: *## mtime: the time that the file was last modified *## other properties will be specified in a future specification, including other times, ownership, permissions, and size. *# The path is resolved relative to the current working directory. *# Throws an error if the corresponding file does not exist or is inaccessible. * list(path): returns a traversable, indexable representation of the names of files in a particular directory. *# The returned object implements the Array API for indexing, and may in fact be an Array if the underlying implementation is not sophhisticated enough to do lazy indexing. The prototype of the returned object contains all of the Array generics like "push", "pop", and such. *# The returned object may be immutable. *# The returned object must implement "next" and "prev", which walk backward and forward among the file names in the directory. Both throw an exception when they are beyond the bounds of the directory. *# The path is resolved relative to the current working directory. *# 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. *# 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). *# The mode is a String and may contain: *## "r" that means that the stream may be read, and implies that the "read", "readLine", "readLines", "next", and "iter" methods must be supported by the returned stream object. "readLine" returns "" on EOF, and "next" throws an error instead. "iter" returns the stream object itself. "readLine" returns a string excluding the newline character. *## "w" that means that the stream may be written to, and implies that the "write", "writeLine", and "writeLines" methods must be supported by the stream object. Also implies that the file will be created or truncated if necessary, if not overridden by the "a" or "+" flags. *## "a" that means that the stream's position will begin at the end of the stream, and that the file will be created but not truncated. *## "+" that means that the stream will not be truncated. *## other options may be added in the future for advisory locks. *## the "b" option known in other languages will not be implemented since it is really an encoding argument. *# The permissions must be an integer of Unix style permissions. Other objects may be permitted in a later specification, like a Stat object or duck-type thereof. *# The path is resolved relative to the current working directory. *# Throws an error if the specified stream cannot be created. = Tier 2 = In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names|proposed names]. 61 2009-04-02T13:46:38Z Jake123 /* Tier 1 */ = Tier 1 = The require('file') module would provide support the File System API. In turn, the File System API would provide all methods that deal with path strings. File System API functions would return file stream objects, directory objects, and file stat objects. File stream objects would, for securability, be unaware of their corresponding path, and keep their underlying file system connection, albeit a file descriptor or FILE*, and their parent directory link, secret. The File System API would provide the following methods: * normal: removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. * absolute: returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result. * canonical: returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. * exists(path): whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. * stat(path): returns an object that represents a snapshot of the information about given file. *# The stat file must contain the following properties: *## mtime: the time that the file was last modified *## other properties will be specified in a future specification, including other times, ownership, permissions, and size. *# The path is resolved relative to the current working directory. *# Throws an error if the corresponding file does not exist or is inaccessible. * list(path): returns a traversable, indexable representation of the names of files in a particular directory. *# The returned object implements the Array API for indexing, and may in fact be an Array if the underlying implementation is not sophhisticated enough to do lazy indexing. The prototype of the returned object contains all of the Array generics like "push", "pop", and such. *# The returned object may be immutable. *# The returned object must implement "next" and "prev", which walk backward and forward among the file names in the directory. Both throw an exception when they are beyond the bounds of the directory. *# The path is resolved relative to the current working directory. *# 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. *# 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). *# The mode is a String and may contain: *## "r" that means that the stream may be read, and implies that the "read", "readLine", "readLines", "next", and "iter" methods must be supported by the returned stream object. "readLine" returns "" on EOF, and "next" throws an error instead. "iter" returns the stream object itself. "readLine" returns a string excluding the newline character. *## "w" that means that the stream may be written to, and implies that the "write", "writeLine", and "writeLines" methods must be supported by the stream object. Also implies that the file will be created or truncated if necessary, if not overridden by the "a" or "+" flags. *## "a" that means that the stream's position will begin at the end of the stream, and that the file will be created but not truncated. *## "+" that means that the stream will not be truncated. *## other options may be added in the future for advisory locks. *## the "b" option known in other languages will not be implemented since it is really an encoding argument. *# The permissions must be an integer of Unix style permissions. Other objects may be permitted in a later specification, like a Stat object or duck-type thereof. *# The path is resolved relative to the current working directory. *# 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. = Tier 2 = In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names|proposed names]. 62 2009-04-04T17:29:14Z KrisKowal Moved close under open. = Tier 1 = The require('file') module would provide support the File System API. In turn, the File System API would provide all methods that deal with path strings. File System API functions would return file stream objects, directory objects, and file stat objects. File stream objects would, for securability, be unaware of their corresponding path, and keep their underlying file system connection, albeit a file descriptor or FILE*, and their parent directory link, secret. The File System API would provide the following methods: * normal: removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. * absolute: returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result. * canonical: returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. * exists(path): whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. * stat(path): returns an object that represents a snapshot of the information about given file. *# The stat file must contain the following properties: *## mtime: the time that the file was last modified *## other properties will be specified in a future specification, including other times, ownership, permissions, and size. *# The path is resolved relative to the current working directory. *# Throws an error if the corresponding file does not exist or is inaccessible. * list(path): returns a traversable, indexable representation of the names of files in a particular directory. *# The returned object implements the Array API for indexing, and may in fact be an Array if the underlying implementation is not sophhisticated enough to do lazy indexing. The prototype of the returned object contains all of the Array generics like "push", "pop", and such. *# The returned object may be immutable. *# The returned object must implement "next" and "prev", which walk backward and forward among the file names in the directory. Both throw an exception when they are beyond the bounds of the directory. *# The path is resolved relative to the current working directory. *# 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. *# 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). *# The mode is a String and may contain: *## "r" that means that the stream may be read, and implies that the "read", "readLine", "readLines", "next", and "iter" methods must be supported by the returned stream object. "readLine" returns "" on EOF, and "next" throws an error instead. "iter" returns the stream object itself. "readLine" returns a string excluding the newline character. *## "w" that means that the stream may be written to, and implies that the "write", "writeLine", and "writeLines" methods must be supported by the stream object. Also implies that the file will be created or truncated if necessary, if not overridden by the "a" or "+" flags. *## "a" that means that the stream's position will begin at the end of the stream, and that the file will be created but not truncated. *## "+" that means that the stream will not be truncated. *## other options may be added in the future for advisory locks. *## the "b" option known in other languages will not be implemented since it is really an encoding argument. *# The permissions must be an integer of Unix style permissions. Other objects may be permitted in a later specification, like a Stat object or duck-type thereof. *# The path is resolved relative to the current working directory. *# Throws an error if the specified stream cannot be created. *# close(): Closes the stream. Should be called automatically when the mode is changed, and when the garbage collector collects its last reference. = Tier 2 = In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names|proposed names]. 63 2009-04-07T21:04:37Z KrisKowal /* Tier 2 */ fixed a link. = Tier 1 = The require('file') module would provide support the File System API. In turn, the File System API would provide all methods that deal with path strings. File System API functions would return file stream objects, directory objects, and file stat objects. File stream objects would, for securability, be unaware of their corresponding path, and keep their underlying file system connection, albeit a file descriptor or FILE*, and their parent directory link, secret. The File System API would provide the following methods: * normal: removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. * absolute: returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result. * canonical: returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. * exists(path): whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. * stat(path): returns an object that represents a snapshot of the information about given file. *# The stat file must contain the following properties: *## mtime: the time that the file was last modified *## other properties will be specified in a future specification, including other times, ownership, permissions, and size. *# The path is resolved relative to the current working directory. *# Throws an error if the corresponding file does not exist or is inaccessible. * list(path): returns a traversable, indexable representation of the names of files in a particular directory. *# The returned object implements the Array API for indexing, and may in fact be an Array if the underlying implementation is not sophhisticated enough to do lazy indexing. The prototype of the returned object contains all of the Array generics like "push", "pop", and such. *# The returned object may be immutable. *# The returned object must implement "next" and "prev", which walk backward and forward among the file names in the directory. Both throw an exception when they are beyond the bounds of the directory. *# The path is resolved relative to the current working directory. *# 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. *# 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). *# The mode is a String and may contain: *## "r" that means that the stream may be read, and implies that the "read", "readLine", "readLines", "next", and "iter" methods must be supported by the returned stream object. "readLine" returns "" on EOF, and "next" throws an error instead. "iter" returns the stream object itself. "readLine" returns a string excluding the newline character. *## "w" that means that the stream may be written to, and implies that the "write", "writeLine", and "writeLines" methods must be supported by the stream object. Also implies that the file will be created or truncated if necessary, if not overridden by the "a" or "+" flags. *## "a" that means that the stream's position will begin at the end of the stream, and that the file will be created but not truncated. *## "+" that means that the stream will not be truncated. *## other options may be added in the future for advisory locks. *## the "b" option known in other languages will not be implemented since it is really an encoding argument. *# The permissions must be an integer of Unix style permissions. Other objects may be permitted in a later specification, like a Stat object or duck-type thereof. *# The path is resolved relative to the current working directory. *# Throws an error if the specified stream cannot be created. *# close(): Closes the stream. Should be called automatically when the mode is changed, and when the garbage collector collects its last reference. = Tier 2 = In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names proposed names]. 64 2009-04-07T23:36:33Z MrN /* Tier 1 */ add keyword open thingie = Tier 1 = The require('file') module would provide support the File System API. In turn, the File System API would provide all methods that deal with path strings. File System API functions would return file stream objects, directory objects, and file stat objects. File stream objects would, for securability, be unaware of their corresponding path, and keep their underlying file system connection, albeit a file descriptor or FILE*, and their parent directory link, secret. The File System API would provide the following methods: * normal: removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. * absolute: returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result. * canonical: returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. * exists(path): whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. * stat(path): returns an object that represents a snapshot of the information about given file. *# The stat file must contain the following properties: *## mtime: the time that the file was last modified *## other properties will be specified in a future specification, including other times, ownership, permissions, and size. *# The path is resolved relative to the current working directory. *# Throws an error if the corresponding file does not exist or is inaccessible. * list(path): returns a traversable, indexable representation of the names of files in a particular directory. *# The returned object implements the Array API for indexing, and may in fact be an Array if the underlying implementation is not sophhisticated enough to do lazy indexing. The prototype of the returned object contains all of the Array generics like "push", "pop", and such. *# The returned object may be immutable. *# The returned object must implement "next" and "prev", which walk backward and forward among the file names in the directory. Both throw an exception when they are beyond the bounds of the directory. *# The path is resolved relative to the current working directory. *# 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. *# 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). *# The mode is a String and may contain: *## "r" that means that the stream may be read, and implies that the "read", "readLine", "readLines", "next", and "iter" methods must be supported by the returned stream object. "readLine" returns "" on EOF, and "next" throws an error instead. "iter" returns the stream object itself. "readLine" returns a string excluding the newline character. *## "w" that means that the stream may be written to, and implies that the "write", "writeLine", and "writeLines" methods must be supported by the stream object. Also implies that the file will be created or truncated if necessary, if not overridden by the "a" or "+" flags. *## "a" that means that the stream's position will begin at the end of the stream, and that the file will be created but not truncated. *## "+" that means that the stream will not be truncated. *## other options may be added in the future for advisory locks. *## the "b" option known in other languages will not be implemented since it is really an encoding argument. *# The permissions must be an integer of Unix style permissions. Other objects may be permitted in a later specification, like a Stat object or duck-type thereof. *# The path is resolved relative to the current working directory. *# Throws an error if the specified stream cannot be created. *# close(): Closes the stream. Should be called automatically when the mode is changed, and when the garbage collector collects its last reference. = Tier 2 = In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names proposed names]. 65 2009-04-07T23:51:28Z KrisKowal /* Tier 1 */ added another open syntax option = Tier 1 = The require('file') module would provide support the File System API. In turn, the File System API would provide all methods that deal with path strings. File System API functions would return file stream objects, directory objects, and file stat objects. File stream objects would, for securability, be unaware of their corresponding path, and keep their underlying file system connection, albeit a file descriptor or FILE*, and their parent directory link, secret. The File System API would provide the following methods: * normal: removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. * absolute: returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result. * canonical: returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. * exists(path): whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. * stat(path): returns an object that represents a snapshot of the information about given file. *# The stat file must contain the following properties: *## mtime: the time that the file was last modified *## other properties will be specified in a future specification, including other times, ownership, permissions, and size. *# The path is resolved relative to the current working directory. *# Throws an error if the corresponding file does not exist or is inaccessible. * list(path): returns a traversable, indexable representation of the names of files in a particular directory. *# The returned object implements the Array API for indexing, and may in fact be an Array if the underlying implementation is not sophhisticated enough to do lazy indexing. The prototype of the returned object contains all of the Array generics like "push", "pop", and such. *# The returned object may be immutable. *# The returned object must implement "next" and "prev", which walk backward and forward among the file names in the directory. Both throw an exception when they are beyond the bounds of the directory. *# The path is resolved relative to the current working directory. *# Throws an error if the directory does not exist or is inaccessible. * 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. *## 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). *# The mode is a String and may contain: *## "r" that means that the stream may be read, and implies that the "read", "readLine", "readLines", "next", and "iter" methods must be supported by the returned stream object. "readLine" returns "" on EOF, and "next" throws an error instead. "iter" returns the stream object itself. "readLine" returns a string excluding the newline character. *## "w" that means that the stream may be written to, and implies that the "write", "writeLine", and "writeLines" methods must be supported by the stream object. Also implies that the file will be created or truncated if necessary, if not overridden by the "a" or "+" flags. *## "a" that means that the stream's position will begin at the end of the stream, and that the file will be created but not truncated. *## "+" that means that the stream will not be truncated. *## other options may be added in the future for advisory locks. *## the "b" option known in other languages will not be implemented since it is really an encoding argument. *# The permissions must be an integer of Unix style permissions. Other objects may be permitted in a later specification, like a Stat object or duck-type thereof. *# The path is resolved relative to the current working directory. *# Throws an error if the specified stream cannot be created. *# close(): Closes the stream. Should be called automatically when the mode is changed, and when the garbage collector collects its last reference. = Tier 2 = In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names proposed names]. 66 2009-04-25T05:44:18Z KrisKowal New draft. = Tier 1 = This tier establishes a basis with binary IO and basic string manipulation for paths. The require('file') module would provide support the File System API. In turn, the File System API would provide all methods that deal with path strings. File System API functions would return file stream objects, directory objects, and file stat objects. File stream objects would, for securability, be unaware of their corresponding path, and keep their underlying file system connection, albeit a file descriptor or FILE*, and their parent directory link, secret. The File System API would provide the following constants: * 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: * 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. * 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. * relative(from, to): returns the relative path from one path to another using only ".." to traverse up to the two paths' common ancestor. * normal(path:String): removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. "normal" may be implemented in terms of "resolve". * absolute(path:String): returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result. "absolute" can be implemented in terms of "resolve" and "cwd". * canonical(path:String): returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. "canonical" can be implemented in terms of "cwd", "resolve", and "readlink". * exists(path): whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. * stat(path): returns an object that represents a snapshot of the information about given file. *# The stat file must contain the following properties: *## mtime: the time that the file was last modified *## other properties will be specified in a future specification, including other times, ownership, permissions, and size. *# The path is resolved relative to the current working directory. *# Throws an error if the corresponding file does not exist or is inaccessible. * list(path): returns an Array of file name strings. *# The returned object may be immutable. *# The path is resolved relative to the current working directory. *# Throws an error if the directory does not exist or is inaccessible. * open(path, mode) or open({options}) *# options may include {path, mode} and more in a later, more detailed specification. *# The mode is a String and may contain: *## "r" that means that the stream may be read, and implies that the "read", "readLine", "readLines", "next", and "iter" methods must be supported by the returned stream object. "readLine" returns "" on EOF, and "next" throws an error instead. "iter" returns the stream object itself. "readLine" returns a string excluding the newline character. *## "w" that means that the stream may be written to, and implies that the "write", "writeLine", and "writeLines" methods must be supported by the stream object. Also implies that the file will be created or truncated if necessary, if not overridden by the "a" or "+" flags. *## "a" that means that the stream's position will begin at the end of the stream, and that the file will be created but not truncated. *## "+" that means that the stream will not be truncated. *# The path is resolved relative to the current working directory. *# Throws an error if the specified stream cannot be created. *# close(): Closes the stream. Should be called automatically when the mode is changed, and when the garbage collector collects its last reference. * read(path, [mode, [options]]): opens, reads, and closes a file, returning its content. * write(path, content, [mode, [options]]): opens, writes, flushes, and closes a file with the given content. = Tier 2 = This tier adds support for encoded and buffered text IO and a chainable Path type. * open(path, mode, {options}) or open({options}) *# options may include {path, mode, charset, recordSeparator, fieldSeparator} and more in a later, more detailed specification. *# The mode is a String and may contain: *## "b" for ByteArray and ByteString streams. *## "t" for String and Array streams (default) *# "charset" may be any IANA charset identifier, case-insensitive. "open" may throw an error if the charset is not supported. "charset" defaults to a system-specific encoding if the stream is in text mode with no charset provided. *# returns a stream type. While the type names need not correspond to these name, these are used as an interal reference in this document for what the minimum interface of those streams must contain. *## Returns a BinaryReadStream for "b" and "r" modes. *## Returns a BinaryWriteStream for "b" and "w" or "a" modes. *## Returns a BinaryRandomStream for "b" and "+" modes. *## Returns a TextReadStream wrapper for "t" and "r" modes. *## Returns a TextWriteStream wrapper for "t" and "w" modes. * BinaryReadStream ** read() -> all:ByteString ** read(max:Number) -> actual:Number ** readInto(buffer:Array|ByteArray, [begin:Number, [end:Number]]) -> actual:Number * BinaryWriteStream ** write(buffer:Array|ByteArray|ByteString) ** flush() * BinaryRandomStream < BinaryReadStream < BinaryWriteStream ** tell() -> position:Number) ** seek(position:Number, whence:enumerated) * TextReadStream ** raw -> a BinaryReadStream ** readLine() -> String -- returns "" if no data is available before EOF. Otherwise, includes the "recordSeparator". ** readLines() -> Array * String ** next() -> String -- throws a StopIteration if no data is available before EOF. ** input() -> returns "readLine" without the "recordSeparator". * TextWriteStream ** raw -> a BinaryWriteStream ** write(buffer:String) ** writeLine(buffer:String) ** print(...String...) -- writes a "fieldSeparator" delimited and "recordSeparator" terminated line. ** flush() The File System API would provide the following additional methods: * basename(path:String) -> String * copy(from:String, to:String) -> copies a file by reading one and writing the other in binary modes. * dirname(path:String) -> String * extname(path:String) -> String * isDirectory(path:String) -> Boolean * isFile(path:String) -> Boolean * isLink(path:String) -> Boolean * isReadable(path:String) -> Boolean * isWritable(path:String) -> Boolean * mkdir(path:String) * mkdirs(path:String) * move(from:String, to:String) * mtime() -> lastModification:Date|null * remove(path:String) * rename(path:String, name:String) * rmdir(path:String) * rmtree(path:String) * same(from:String, to:String) -> Boolean -- whether the two files are identical, in that they come from the same file system, same device, and have the same node and corresponding storage, such that modifying one would modify the other. * size(path:String) -> bytes:Number * touch(path:String, [mtime:Date]) The Path object closes on both a file system and a path String. The file system mediates all interaction with the underlying storage, so a Path only provides a convenient interface for chaining operations that manipulate a path string. All of the methods of path are polymorphic (meaning late-bound) and curried (meaning the enclosed path String is passed to the corresponding file system method). * path(path:String) -> path:Path * new Path(path:String, [fs:FileSystem]) -> path:Path *# absolute() -> path:Path *# basename() -> path:Path *# canonical() -> path:Path *# copy(to:Path) *# dirname() -> path:Path *# exists() -> Boolean *# extname() -> String *# from(path:String|Path) -> path:Path -- an alias for "relative" that finds the relative path from the given path to this one. *# isDirectory() -> Boolean *# isFile() -> Boolean *# isLink() -> Boolean *# isReadable() -> Boolean *# isWritable() -> Boolean *# join(...paths...) -> path:Path *# list() -> Array * Path *# mkdir() *# mkdirs() *# move(to:String) *# mtime() -> Date *# normal() -> path:Path *# open(mode, [options]) -> stream:{Text,Binary}{Read,Write,RW,Random}Stream *# read([mode, [options]]) -> {Byte,}String *# remove() *# rename(name:String) -- rename is distinct from move only in that the new name is resolved relative to the former path, rather than the current working directory. *# resolve(...paths...) -> path:Path *# rmdir() *# rmtree() *# same(as:Path|String) -> Boolean *# size() -> Number *# split() -> parts:(Array * String) *# 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. *# touch([mtime:Date]) *# write(data:ByteString|ByteArray|Array|String, [mode, [options]]) = Tier 3 = This tier adds support for random access IO, locks, canonical IO (non-blocking), more comprehensive stat access and mutation, and temporary files and directories, and symbolic links. * open(path, mode, {options}) or open({options}) *# options may include {path, mode, charset, permissions, owner, groupOwner} and more in a later, more detailed specification. *# The permissions must be an integer of Unix style permissions. Other objects may be permitted in a later specification, like a Stat object or duck-type thereof. * copyStat(from:String, to:String) Path: * copyStat(to:String|Path) In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names proposed names]. 67 2009-04-25T06:27:12Z KrisKowal = Tier 1 = This tier establishes a basis with binary IO and basic string manipulation for paths. The require('file') module would provide support the File System API. In turn, the File System API would provide all methods that deal with path strings. File System API functions would return file stream objects, directory objects, and file stat objects. File stream objects would, for securability, be unaware of their corresponding path, and keep their underlying file system connection, albeit a file descriptor or FILE*, and their parent directory link, secret. The File System API would provide the following constants: * 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: * 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. * 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. * relative(from, to): returns the relative path from one path to another using only ".." to traverse up to the two paths' common ancestor. * normal(path:String): removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. "normal" may be implemented in terms of "resolve". * absolute(path:String): returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result. "absolute" can be implemented in terms of "resolve" and "cwd". * canonical(path:String): returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. "canonical" can be implemented in terms of "cwd", "resolve", and "readlink". * exists(path): whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. * stat(path): returns an object that represents a snapshot of the information about given file. *# The stat file must contain the following properties: *## mtime: the time that the file was last modified *## other properties will be specified in a future specification, including other times, ownership, permissions, and size. *# The path is resolved relative to the current working directory. *# Throws an error if the corresponding file does not exist or is inaccessible. * list(path): returns an Array of file name strings. *# The returned object may be immutable. *# The path is resolved relative to the current working directory. *# Throws an error if the directory does not exist or is inaccessible. * open(path, mode) or open({options}) *# options may include {path, mode} and more in a later, more detailed specification. *# The mode is a String and may contain: *## "r" that means that the stream may be read, and implies that the "read", "readLine", "readLines", "next", and "iter" methods must be supported by the returned stream object. "readLine" returns "" on EOF, and "next" throws an error instead. "iter" returns the stream object itself. "readLine" returns a string excluding the newline character. *## "w" that means that the stream may be written to, and implies that the "write", "writeLine", and "writeLines" methods must be supported by the stream object. Also implies that the file will be created or truncated if necessary, if not overridden by the "a" or "+" flags. *## "a" that means that the stream's position will begin at the end of the stream, and that the file will be created but not truncated. *## "+" that means that the stream will not be truncated. *# The path is resolved relative to the current working directory. *# Throws an error if the specified stream cannot be created. *# close(): Closes the stream. Should be called automatically when the mode is changed, and when the garbage collector collects its last reference. * read(path, [mode, [options]]): opens, reads, and closes a file, returning its content. * write(path, content, [mode, [options]]): opens, writes, flushes, and closes a file with the given content. = Tier 2 = This tier adds support for encoded and buffered text IO and a chainable Path type. * open(path, mode, {options}) or open({options}) *# options may include {path, mode, charset, recordSeparator, fieldSeparator} and more in a later, more detailed specification. *# The mode is a String and may additionally contain: *## "b" for ByteArray and ByteString streams. *## "t" for String and Array streams (default) *# "charset" may be any IANA charset identifier, case-insensitive. "open" may throw an error if the charset is not supported. "charset" defaults to a system-specific encoding if the stream is in text mode with no charset provided. *# returns a stream type. While the type names need not correspond to these name, these are used as an interal reference in this document for what the minimum interface of those streams must contain. *## Returns a BinaryReadStream for "b" and "r" modes. *## Returns a BinaryWriteStream for "b" and "w" or "a" modes. *## Returns a BinaryRandomStream for "b" and "+" modes. *## Returns a TextReadStream wrapper for "t" and "r" modes. *## Returns a TextWriteStream wrapper for "t" and "w" modes. * BinaryReadStream ** read() -> all:ByteString ** read(max: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 ** write(buffer:Array|ByteArray|ByteString) ** truncate(length:Number=0) ** flush() * BinaryRandomStream < BinaryReadStream < BinaryWriteStream ** tell() -> position:Number) ** seek(position:Number, whence:enumerated) * TextReadStream ** raw -> a BinaryReadStream ** readLine() -> String -- returns "" if no data is available before EOF. Otherwise, includes the "recordSeparator". ** readLines() -> Array * String ** next() -> String -- throws a StopIteration if no data is available before EOF. ** 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 ** raw -> a BinaryWriteStream ** write(buffer:String) ** writeLine(buffer:String) ** print(...String...) -- writes a "fieldSeparator" delimited and "recordSeparator" terminated line. ** flush() The File System API would provide the following additional methods: * basename(path:String) -> String * copy(from:String, to:String) -> copies a file by reading one and writing the other in binary modes. * dirname(path:String) -> String * extname(path:String) -> String * isDirectory(path:String) -> Boolean * isFile(path:String) -> Boolean * isLink(path:String) -> Boolean * isReadable(path:String) -> Boolean * isWritable(path:String) -> Boolean * mkdir(path:String) * mkdirs(path:String) * move(from:String, to:String) * mtime() -> lastModification:Date|null * remove(path:String) * rename(path:String, name:String) * rmdir(path:String) * rmtree(path:String) * same(from:String, to:String) -> Boolean -- whether the two files are identical, in that they come from the same file system, same device, and have the same node and corresponding storage, such that modifying one would modify the other. * size(path:String) -> bytes:Number * touch(path:String, [mtime:Date]) The Path object closes on both a file system and a path String. The file system mediates all interaction with the underlying storage, so a Path only provides a convenient interface for chaining operations that manipulate a path string. All of the methods of path are polymorphic (meaning late-bound) and curried (meaning the enclosed path String is passed to the corresponding file system method). * path(path:String) -> path:Path * new Path(path:String, [fs:FileSystem]) -> path:Path *# absolute() -> path:Path *# basename() -> path:Path *# canonical() -> path:Path *# copy(to:Path) *# dirname() -> path:Path *# exists() -> Boolean *# extname() -> String *# from(path:String|Path) -> path:Path -- an alias for "relative" that finds the relative path from the given path to this one. *# isDirectory() -> Boolean *# isFile() -> Boolean *# isLink() -> Boolean *# isReadable() -> Boolean *# isWritable() -> Boolean *# join(...paths...) -> path:Path *# list() -> Array * Path *# mkdir() *# mkdirs() *# move(to:String) *# mtime() -> Date *# normal() -> path:Path *# open(mode, [options]) -> stream:{Text,Binary}{Read,Write,RW,Random}Stream *# read([mode, [options]]) -> {Byte,}String *# remove() *# rename(name:String) -- rename is distinct from move only in that the new name is resolved relative to the former path, rather than the current working directory. *# resolve(...paths...) -> path:Path *# rmdir() *# rmtree() *# same(as:Path|String) -> Boolean *# size() -> Number *# split() -> parts:(Array * String) *# 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. *# toString() -> String *# touch([mtime:Date]) *# write(data:ByteString|ByteArray|Array|String, [mode, [options]]) = Tier 3 = This tier adds support for random access IO, locks, canonical IO (non-blocking), more comprehensive stat access and mutation, and temporary files and directories, and symbolic links. * open(path, mode, {options}) or open({options}) *# options may include {path, mode, charset, permissions, owner, groupOwner} and more in a later, more detailed specification. *# The permissions must be an integer of Unix style permissions. Other objects may be permitted in a later specification, like a Stat object or duck-type thereof. * copyStat(from:String, to:String) Path: * copyStat(to:String|Path) In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names proposed names]. 68 2009-04-25T08:19:59Z KrisKowal Fixes pointed out by tlrobinson. = Tier 1 = This tier establishes a basis with binary IO and basic string manipulation for paths. The require('file') module would provide support the File System API. In turn, the File System API would provide all methods that deal with path strings. File System API functions would return file stream objects, directory objects, and file stat objects. File stream objects would, for securability, be unaware of their corresponding path, and keep their underlying file system connection, albeit a file descriptor or FILE*, and their parent directory link, secret. The File System API would provide the following constants: * 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: * 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. * 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. * relative(from, to): returns the relative path from one path to another using only ".." to traverse up to the two paths' common ancestor. * normal(path:String): removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. "normal" may be implemented in terms of "resolve". * absolute(path:String): returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result. "absolute" can be implemented in terms of "resolve" and "cwd". * canonical(path:String): returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. "canonical" can be implemented in terms of "cwd", "resolve", and "readlink". * exists(path): whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. * stat(path): returns an object that represents a snapshot of the information about given file. *# The stat file must contain the following properties: *## mtime: the time that the file was last modified *## other properties will be specified in a future specification, including other times, ownership, permissions, and size. *# The path is resolved relative to the current working directory. *# Throws an error if the corresponding file does not exist or is inaccessible. * list(path): returns an Array of file name strings. *# The returned object may be immutable. *# The path is resolved relative to the current working directory. *# Throws an error if the directory does not exist or is inaccessible. * open(path, mode) or open({options}) *# options may include {path, mode} and more in a later, more detailed specification. *# The mode is a String and may contain: *## "r" that means that the stream may be read, and implies that the "read", "readLine", "readLines", "next", and "iter" methods must be supported by the returned stream object. "readLine" returns "" on EOF, and "next" throws an error instead. "iter" returns the stream object itself. "readLine" returns a string excluding the newline character. *## "w" that means that the stream may be written to, and implies that the "write", "writeLine", and "writeLines" methods must be supported by the stream object. Also implies that the file will be created or truncated if necessary, if not overridden by the "a" or "+" flags. *## "a" that means that the stream's position will begin at the end of the stream, and that the file will be created but not truncated. *## "+" that means that the stream will not be truncated. *# The path is resolved relative to the current working directory. *# Throws an error if the specified stream cannot be created. *# close(): Closes the stream. Should be called automatically when the mode is changed, and when the garbage collector collects its last reference. * read(path, [mode, [options]]): opens, reads, and closes a file, returning its content. * write(path, content, [mode, [options]]): opens, writes, flushes, and closes a file with the given content. = Tier 2 = This tier adds support for encoded and buffered text IO and a chainable Path type. * open(path, mode, {options}) or open({options}) *# options may include {path, mode, charset, recordSeparator, fieldSeparator} and more in a later, more detailed specification. *# The mode is a String and may additionally contain: *## "b" for ByteArray and ByteString streams. *## "t" for String and Array streams (default) *# "charset" may be any IANA charset identifier, case-insensitive. "open" may throw an error if the charset is not supported. "charset" defaults to a system-specific encoding if the stream is in text mode with no charset provided. *# returns a stream type. While the type names need not correspond to these name, these are used as an interal reference in this document for what the minimum interface of those streams must contain. *## Returns a BinaryReadStream for "b" and "r" modes. *## Returns a BinaryWriteStream for "b" and "w" or "a" modes. *## Returns a BinaryRandomStream for "b" and "+" modes. *## Returns a TextReadStream wrapper for "t" and "r" modes. *## Returns a TextWriteStream wrapper for "t" and "w" modes. * BinaryReadStream ** read() -> all:ByteString ** read(max:Number) -> actual:ByteString ** 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 ** write(buffer:Array|ByteArray|ByteString) ** truncate(length:Number=0) ** flush() * BinaryRandomStream < BinaryReadStream < BinaryWriteStream ** tell() -> position:Number) ** 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 ** 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". ** readLines() -> Array * String ** next() -> String -- throws a StopIteration if no data is available before EOF. ** 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 ** raw -> a BinaryWriteStream ** write(buffer:String) ** writeLine(buffer:String) ** print(...String...) -- writes a "fieldSeparator" delimited and "recordSeparator" terminated line. ** flush() The File System API would provide the following additional methods: * basename(path:String) -> String * copy(from:String, to:String) -> copies a file by reading one and writing the other in binary modes. * dirname(path:String) -> String * extname(path:String) -> String * isDirectory(path:String) -> Boolean * isFile(path:String) -> Boolean * isLink(path:String) -> Boolean * isReadable(path:String) -> Boolean * isWritable(path:String) -> Boolean * mkdir(path:String) * mkdirs(path:String) * move(from:String, to:String) * mtime() -> lastModification:Date|null * remove(path:String) * rename(path:String, name:String) * rmdir(path:String) * rmtree(path:String) * same(from:String, to:String) -> Boolean -- whether the two files are identical, in that they come from the same file system, same device, and have the same node and corresponding storage, such that modifying one would modify the other. * size(path:String) -> bytes:Number * touch(path:String, [mtime:Date]) The Path object closes on both a file system and a path String. The file system mediates all interaction with the underlying storage, so a Path only provides a convenient interface for chaining operations that manipulate a path string. All of the methods of path are polymorphic (meaning late-bound) and curried (meaning the enclosed path String is passed to the corresponding file system method). * path(path:String) -> path:Path * new Path(path:String, [fs:FileSystem]) -> path:Path *# absolute() -> path:Path *# basename() -> path:Path *# canonical() -> path:Path *# copy(to:Path) *# dirname() -> path:Path *# exists() -> Boolean *# extname() -> String *# from(path:String|Path) -> path:Path -- an alias for "relative" that finds the relative path from the given path to this one. *# isDirectory() -> Boolean *# isFile() -> Boolean *# isLink() -> Boolean *# isReadable() -> Boolean *# isWritable() -> Boolean *# join(...paths...) -> path:Path *# list() -> Array * Path *# mkdir() *# mkdirs() *# move(to:String) *# mtime() -> Date *# normal() -> path:Path *# open(mode, [options]) -> stream:{Text,Binary}{Read,Write,RW,Random}Stream *# read([mode, [options]]) -> {Byte,}String *# remove() *# rename(name:String) -- rename is distinct from move only in that the new name is resolved relative to the former path, rather than the current working directory. *# resolve(...paths...) -> path:Path *# rmdir() *# rmtree() *# same(as:Path|String) -> Boolean *# size() -> Number *# split() -> parts:(Array * String) *# 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. *# toString() -> String *# touch([mtime:Date]) *# write(data:ByteString|ByteArray|Array|String, [mode, [options]]) = Tier 3 = This tier adds support for random access IO, locks, canonical IO (non-blocking), more comprehensive stat access and mutation, and temporary files and directories, and symbolic links. * open(path, mode, {options}) or open({options}) *# options may include {path, mode, charset, permissions, owner, groupOwner} and more in a later, more detailed specification. *# The permissions must be an integer of Unix style permissions. Other objects may be permitted in a later specification, like a Stat object or duck-type thereof. * copyStat(from:String, to:String) Path: * copyStat(to:String|Path) In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names proposed names]. 69 2009-04-26T21:43:35Z Mob /* Tier 1 */ Added some drive-path specific text. Removed ROOT. = Tier 1 = This tier establishes a basis with binary IO and basic string manipulation for paths. The require('file') module would provide support the File System API. In turn, the File System API would provide all methods that deal with path strings. File System API functions would return file stream objects, directory objects, and file stat objects. File stream objects would, for securability, be unaware of their corresponding path, and keep their underlying file system connection, albeit a file descriptor or FILE*, and their parent directory link, secret. The File System API would provide the following constants: * SEPARATOR "/" or system specific analog, like ":" or "\". The File System API would provide the following methods: * 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. 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. * relative(from, to): returns the relative path from one path to another using only ".." to traverse up to the two paths' common ancestor. * normal(path:String): removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. "normal" may be implemented in terms of "resolve". * absolute(path:String): returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result. "absolute" can be implemented in terms of "resolve" and "cwd". * canonical(path:String): returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. "canonical" can be implemented in terms of "cwd", "resolve", and "readlink". * exists(path): whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. * stat(path): returns an object that represents a snapshot of the information about given file. *# The stat file must contain the following properties: *## mtime: the time that the file was last modified *## other properties will be specified in a future specification, including other times, ownership, permissions, and size. *# The path is resolved relative to the current working directory. *# Throws an error if the corresponding file does not exist or is inaccessible. * list(path): returns an Array of file name strings. *# The returned object may be immutable. *# The path is resolved relative to the current working directory. *# Throws an error if the directory does not exist or is inaccessible. * open(path, mode) or open({options}) *# options may include {path, mode} and more in a later, more detailed specification. *# The mode is a String and may contain: *## "r" that means that the stream may be read, and implies that the "read", "readLine", "readLines", "next", and "iter" methods must be supported by the returned stream object. "readLine" returns "" on EOF, and "next" throws an error instead. "iter" returns the stream object itself. "readLine" returns a string excluding the newline character. *## "w" that means that the stream may be written to, and implies that the "write", "writeLine", and "writeLines" methods must be supported by the stream object. Also implies that the file will be created or truncated if necessary, if not overridden by the "a" or "+" flags. *## "a" that means that the stream's position will begin at the end of the stream, and that the file will be created but not truncated. *## "+" that means that the stream will not be truncated. *# The path is resolved relative to the current working directory. *# Throws an error if the specified stream cannot be created. *# close(): Closes the stream. Should be called automatically when the mode is changed, and when the garbage collector collects its last reference. * read(path, [mode, [options]]): opens, reads, and closes a file, returning its content. * write(path, content, [mode, [options]]): opens, writes, flushes, and closes a file with the given content. = Tier 2 = This tier adds support for encoded and buffered text IO and a chainable Path type. * open(path, mode, {options}) or open({options}) *# options may include {path, mode, charset, recordSeparator, fieldSeparator} and more in a later, more detailed specification. *# The mode is a String and may additionally contain: *## "b" for ByteArray and ByteString streams. *## "t" for String and Array streams (default) *# "charset" may be any IANA charset identifier, case-insensitive. "open" may throw an error if the charset is not supported. "charset" defaults to a system-specific encoding if the stream is in text mode with no charset provided. *# returns a stream type. While the type names need not correspond to these name, these are used as an interal reference in this document for what the minimum interface of those streams must contain. *## Returns a BinaryReadStream for "b" and "r" modes. *## Returns a BinaryWriteStream for "b" and "w" or "a" modes. *## Returns a BinaryRandomStream for "b" and "+" modes. *## Returns a TextReadStream wrapper for "t" and "r" modes. *## Returns a TextWriteStream wrapper for "t" and "w" modes. * BinaryReadStream ** read() -> all:ByteString ** read(max:Number) -> actual:ByteString ** 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 ** write(buffer:Array|ByteArray|ByteString) ** truncate(length:Number=0) ** flush() * BinaryRandomStream < BinaryReadStream < BinaryWriteStream ** tell() -> position:Number) ** 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 ** 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". ** readLines() -> Array * String ** next() -> String -- throws a StopIteration if no data is available before EOF. ** 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 ** raw -> a BinaryWriteStream ** write(buffer:String) ** writeLine(buffer:String) ** print(...String...) -- writes a "fieldSeparator" delimited and "recordSeparator" terminated line. ** flush() The File System API would provide the following additional methods: * basename(path:String) -> String * copy(from:String, to:String) -> copies a file by reading one and writing the other in binary modes. * dirname(path:String) -> String * extname(path:String) -> String * isDirectory(path:String) -> Boolean * isFile(path:String) -> Boolean * isLink(path:String) -> Boolean * isReadable(path:String) -> Boolean * isWritable(path:String) -> Boolean * mkdir(path:String) * mkdirs(path:String) * move(from:String, to:String) * mtime() -> lastModification:Date|null * remove(path:String) * rename(path:String, name:String) * rmdir(path:String) * rmtree(path:String) * same(from:String, to:String) -> Boolean -- whether the two files are identical, in that they come from the same file system, same device, and have the same node and corresponding storage, such that modifying one would modify the other. * size(path:String) -> bytes:Number * touch(path:String, [mtime:Date]) The Path object closes on both a file system and a path String. The file system mediates all interaction with the underlying storage, so a Path only provides a convenient interface for chaining operations that manipulate a path string. All of the methods of path are polymorphic (meaning late-bound) and curried (meaning the enclosed path String is passed to the corresponding file system method). * path(path:String) -> path:Path * new Path(path:String, [fs:FileSystem]) -> path:Path *# absolute() -> path:Path *# basename() -> path:Path *# canonical() -> path:Path *# copy(to:Path) *# dirname() -> path:Path *# exists() -> Boolean *# extname() -> String *# from(path:String|Path) -> path:Path -- an alias for "relative" that finds the relative path from the given path to this one. *# isDirectory() -> Boolean *# isFile() -> Boolean *# isLink() -> Boolean *# isReadable() -> Boolean *# isWritable() -> Boolean *# join(...paths...) -> path:Path *# list() -> Array * Path *# mkdir() *# mkdirs() *# move(to:String) *# mtime() -> Date *# normal() -> path:Path *# open(mode, [options]) -> stream:{Text,Binary}{Read,Write,RW,Random}Stream *# read([mode, [options]]) -> {Byte,}String *# remove() *# rename(name:String) -- rename is distinct from move only in that the new name is resolved relative to the former path, rather than the current working directory. *# resolve(...paths...) -> path:Path *# rmdir() *# rmtree() *# same(as:Path|String) -> Boolean *# size() -> Number *# split() -> parts:(Array * String) *# 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. *# toString() -> String *# touch([mtime:Date]) *# write(data:ByteString|ByteArray|Array|String, [mode, [options]]) = Tier 3 = This tier adds support for random access IO, locks, canonical IO (non-blocking), more comprehensive stat access and mutation, and temporary files and directories, and symbolic links. * open(path, mode, {options}) or open({options}) *# options may include {path, mode, charset, permissions, owner, groupOwner} and more in a later, more detailed specification. *# The permissions must be an integer of Unix style permissions. Other objects may be permitted in a later specification, like a Stat object or duck-type thereof. * copyStat(from:String, to:String) Path: * copyStat(to:String|Path) In progress. More information about other potential additions, please refer to the [https://wiki.mozilla.org/ServerJS/API/file/Names proposed names]. 70 2009-05-17T23:25:49Z KrisKowal Moved to ServerJS/File/A Moved to [[ServerJS/File]] and the original proposal at [[ServerJS/File/A]]. 71 2009-05-17T23:35:57Z KrisKowal Moved to [[ServerJS/Filesystem_API]] and the original proposal at [[ServerJS/Filesystem_API/A]]. 72 2009-09-09T22:13:55Z Dantman 1 22 revisions:&#32;Import from https://wiki.mozilla.org/ServerJS Moved to [[ServerJS/Filesystem_API]] and the original proposal at [[ServerJS/Filesystem_API/A]]. 629 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API/file]] to [[CommonJS/API/file]]:&#32;Subpages needed to be enabled Moved to [[ServerJS/Filesystem_API]] and the original proposal at [[ServerJS/Filesystem_API/A]]. 787 2009-09-09T22:40:28Z Dantman 1 Robot: Automated text replacement (-ServerJS +CommonJS) Moved to [[CommonJS/Filesystem_API]] and the original proposal at [[CommonJS/Filesystem_API/A]]. 979 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/file]] to [[OldAPI/file]] Moved to [[CommonJS/Filesystem_API]] and the original proposal at [[CommonJS/Filesystem_API/A]]. 1214 2009-09-12T02:31:22Z Dantman 1 Robot: Automated text replacement (-CommonJS/ +) Moved to [[Filesystem_API]] and the original proposal at [[Filesystem_API/A]]. 1231 2009-09-12T04:31:35Z Dantman 1 Robot: Automated text replacement (-\[\[([^\]]*)_+([^\]]*)\]\] +[[\1 \2]]) Moved to [[Filesystem API]] and the original proposal at [[Filesystem API/A]]. 1239 2009-09-12T04:35:20Z Dantman 1 Robot: Automated text replacement (-Filesystem API +Filesystem) Moved to [[Filesystem]] and the original proposal at [[Filesystem/A]]. 10 73 2009-03-29T03:41:11Z KrisKowal Moved the function name discussion for the File API into a subpage. = API and Proposed Names = The following sections are organized with a bullet point per function. Each point includes a specification for the behavior of a given method, intended to be suitable for documentation. Under each definition is a list of potential names for that function, and in bullets beneath that, everyone is encouraged to write their name under their preference. Please feel to leave comments as well. In the next section, "General Preferences", there are several broad sweeping points about whether to use certain conventions in a consistent fashion. All of the name options are intended to conform to the prevalent opinion among those elections. For example, "make" and "create" and "dir" and "directory" are both general preference elections, so if you would prefer "makeDir" over "createDirectory", please vote independently for "make" and "dir" in the general preferences. == File System Object == The "file" module would conform to the File System API, as well as objects returned by "chroot". There is no definitive implementation of a FileSystem class, so "chroot" is the only way to construct new objects that conform to the FileSystem API. In permissive environments, the "file" module may have direct access to ambient authority through a foreign function interface, or may itself be a dynamically loaded module. In secured environments, the "file" module must copy the properties of "environment.fs" onto its exports. In a secure sandbox, the following statements would be equivalent. require('file').open(foo) environment.fs.open(foo) Since "fs" must be frozen to be secure, there is no need for the "file" module to assemble aparatus for late binding to "fs" methods. * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland *** (Python: os.path.exists, Ruby: exist?, exists?, Java: exists, JSExt: access, Spidermonkey: Helma: v8cgi: JSExt: EJScript: Synchronet: exists, jslibs: exist) * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.path.lexists) * moves a file from a source to a target path. Both paths are joined on the current working directory. ** move(source, target): ** (Ruby: move, Python: shutil.move, Java: File.renameTo) * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal ** (Ruby: rename) * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): ** (Ruby: copy, systemCopy, Python: copy, Unix: cp) * copies a file and its recursive contents to a target path. Both paths are joined on the current working directory. If "synbolicLinks" is truthy, symbolic links in the source tree are represented as symbolic links in the new tree; if falsy, the contents of the linked files are copied to the new tree. If ignore is given, it must be a relation that will receive as its arguments the directory being visited by copytree(), and a list of its contents. Since this is called recursively (or walking an equivalent iteration), the ignore relation will be called once for each directory that is copied. The relation must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. ** copyTree(source, target, symbolicLinks = false, ignore = undefined) ** copy(source, target, "recursive") ** copy(source, target, true) ** (Python: copytree) * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente ** (Unix: mkdir) * creates recursive directories. Makes all intermediate-level directories needed to contain the leaf directory. Throws an exception if the leaf directory already exists or cannot be created. The default mode is 0777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "recursive"): ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) ** makeTree(path) ** (Unix: mkdir -p, Ruby: makedirs, mkpath, Python: os.makedirs) * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland ** (Ruby: unlink, delete, Python: unlink, remove, Java: delete, Posix: unlink, Unix: rm, Spidermonkey: Helma: EJScript: Synchronet: remove, jslibs: Delete) * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) ** removeTree(path, ignoreErrors = false, onError = undefined) ** (Unix: rm -r, Python: rmtree) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested ** (Python: link, Ruby: link, Unix: ln) * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) ** (Ruby: symlink, Python: symlink, Unix: ln -s) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland ** (Java: createNewFile, Posix: creat, Unix: touch) * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): ** omit entirely: *** Kris Kowal ** (Ruby: truncate, Python: ftruncate applies to open files only) * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. *** Wes Garland ** update(path, stat): ** chstat(path, stat): ** setStat(path, stat): ** restat(path, stat): ** (a low-level alternative to Python's copy2 and copyStat) * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal ** (Unix: touch) * locks the file at a given path with either an exclusive or shared advisory lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal ** lock(path, "rw|") ** (Posix: lock, Python: lock) * attempts to acquire an advisory lock a file at a given path but does not block. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. *** Wes Garland ** tryLock(path, "shared|exclusive"): ** lock(path, "rw") ** (Python: lock) * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") ** lock(path, "u") ** (Python: lock) * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente ** (Python: os.stat, Ruby: File.stat, Posix: stat) * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.lstat, Ruby: File.lstat) * returns the size of the corresponding file. ** size(path) ** (Python: size, Ruby: size?: Java: length, Posix: st_size) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. The given permissions object may be a Unix numeric representation of permissions, a Stat object, or any object that provides the members of Stat regarding permissions. ** open(path, "+arwxc", permissions, encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) ** (Java: FileStream classes, Python: open, file, Ruby: File.new, universal precedent among SSJS frameworks) * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) ** (Python: os.listdir, Ruby: Dir) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) ** (Ruby: Dir[]) * returns whether a given path matches a glob pattern. ** match(pattern, path) ** (Ruby: fnmatch) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem object. * a string directing a path up to the parent of the current directory, usually '..'. ** PARENT ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) ** (Python: pardir) * a string directing a path back to itself, usually '.'. ** SELF ** (Python: curdir) * a string that contains the path separator, usually '/', '\', or ':'. ** SEPARATOR ** (Python: sep, Spidermonkey: separator, Ruby: SEPARATOR, Separator) * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** ALTERNATE_SEPARATOR ** (Python: altsep, Ruby: ALT_SEPARATOR) * a string that contains the extension separator, usually '.'. ** EXTENSION_SEPRATOR ** (Python: extsep) * whether the file system supports unicode file names ** SUPPORTS_UNICODE_FILE_NAMES * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) ** (not precedented) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland ** (Python: Unix: dirname) * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland ** (Python: Unix: basename) * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland ** (Ruby: extname) * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) ** (Python: normpath) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to epxanding any user directory alias, joining the path to the current working directory, and normalizing the result. ** absolute(path) ** (Python: abspath) * returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding an user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. ** canonical(path) ** (Python: realpath) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) ** (Python: isabs) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** atime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastAccessed: *** Kris Kowal ** (Python: getatime, Ruby: atime) * the Date that the file was last modified. ** mtime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastModified: *** Kris Kowal *** Mario Valente ** (Python: getmtime, Ruby: mtime, Java: Spidermonkey: Helma: lastModified, jslibs: modifyTime, EJScript: modified, Synchronet: date) * the Date that the file's stat/metadata was last modified. ** ctime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** (Ruby: ctime, Python: getctime) * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: ** omit entirely: *** Kris Kowal ** (Spidermonkey: jslibs: creationTime, EJScript: create) * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** omit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory ** (Spidermonkey: isDir, Helma: isDir, JSExt: isdir) * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** omit entirely: *** Wes Garland *** Ondrej Zara * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size *** Ondrej Zara ** (jslibs: size, Helma: getLength, Spidermonkey: wxJS: EJScript: Synchronet: length) * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner ** setuid * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner ** setgid * whether the corresponding directory will permit anyone to create files in it, but only let the owner of a file delete it. ** sticky * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() ** (Python: JSExt: readline, Spidermonkey: Helma: Synchronet: readln) * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() ** (Python: readlines, JSExt: readlines, EJScript: getLines) * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) ** (universal precedent) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() ** (wxJS: JSExt: Python: Ruby: tell) * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) ** (Ruby: truncate, Python: ftruncate) * returns whether the cursor is at the end of the IO stream. ** eof() *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** (Helma: wxJS: JSExt: Synchronet: eof) * flushes buffers for an IO stream ** flush() ** (universal precedent) * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") ** (related to isOpen in many existing SSJS frameworks, but without a race condition hazard) * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = General Preferences = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) #** Ondrej Zara # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #** Ondrej Zara #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #** Ondrej Zara #** George Moschovitis #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #** expand: #*** Ondrej Zara #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #** normalize: #*** Ondrej Zara #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor #** Ondrej Zara #** George Moschovitis #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #** Ondrej Zara #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = References = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 74 2009-04-07T23:34:25Z MrN add keyword-style open proposal = API and Proposed Names = The following sections are organized with a bullet point per function. Each point includes a specification for the behavior of a given method, intended to be suitable for documentation. Under each definition is a list of potential names for that function, and in bullets beneath that, everyone is encouraged to write their name under their preference. Please feel to leave comments as well. In the next section, "General Preferences", there are several broad sweeping points about whether to use certain conventions in a consistent fashion. All of the name options are intended to conform to the prevalent opinion among those elections. For example, "make" and "create" and "dir" and "directory" are both general preference elections, so if you would prefer "makeDir" over "createDirectory", please vote independently for "make" and "dir" in the general preferences. == File System Object == The "file" module would conform to the File System API, as well as objects returned by "chroot". There is no definitive implementation of a FileSystem class, so "chroot" is the only way to construct new objects that conform to the FileSystem API. In permissive environments, the "file" module may have direct access to ambient authority through a foreign function interface, or may itself be a dynamically loaded module. In secured environments, the "file" module must copy the properties of "environment.fs" onto its exports. In a secure sandbox, the following statements would be equivalent. require('file').open(foo) environment.fs.open(foo) Since "fs" must be frozen to be secure, there is no need for the "file" module to assemble aparatus for late binding to "fs" methods. * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland *** (Python: os.path.exists, Ruby: exist?, exists?, Java: exists, JSExt: access, Spidermonkey: Helma: v8cgi: JSExt: EJScript: Synchronet: exists, jslibs: exist) * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.path.lexists) * moves a file from a source to a target path. Both paths are joined on the current working directory. ** move(source, target): ** (Ruby: move, Python: shutil.move, Java: File.renameTo) * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal ** (Ruby: rename) * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): ** (Ruby: copy, systemCopy, Python: copy, Unix: cp) * copies a file and its recursive contents to a target path. Both paths are joined on the current working directory. If "synbolicLinks" is truthy, symbolic links in the source tree are represented as symbolic links in the new tree; if falsy, the contents of the linked files are copied to the new tree. If ignore is given, it must be a relation that will receive as its arguments the directory being visited by copytree(), and a list of its contents. Since this is called recursively (or walking an equivalent iteration), the ignore relation will be called once for each directory that is copied. The relation must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. ** copyTree(source, target, symbolicLinks = false, ignore = undefined) ** copy(source, target, "recursive") ** copy(source, target, true) ** (Python: copytree) * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente ** (Unix: mkdir) * creates recursive directories. Makes all intermediate-level directories needed to contain the leaf directory. Throws an exception if the leaf directory already exists or cannot be created. The default mode is 0777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "recursive"): ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) ** makeTree(path) ** (Unix: mkdir -p, Ruby: makedirs, mkpath, Python: os.makedirs) * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland ** (Ruby: unlink, delete, Python: unlink, remove, Java: delete, Posix: unlink, Unix: rm, Spidermonkey: Helma: EJScript: Synchronet: remove, jslibs: Delete) * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) ** removeTree(path, ignoreErrors = false, onError = undefined) ** (Unix: rm -r, Python: rmtree) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested ** (Python: link, Ruby: link, Unix: ln) * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) ** (Ruby: symlink, Python: symlink, Unix: ln -s) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland ** (Java: createNewFile, Posix: creat, Unix: touch) * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): ** omit entirely: *** Kris Kowal ** (Ruby: truncate, Python: ftruncate applies to open files only) * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. *** Wes Garland ** update(path, stat): ** chstat(path, stat): ** setStat(path, stat): ** restat(path, stat): ** (a low-level alternative to Python's copy2 and copyStat) * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal ** (Unix: touch) * locks the file at a given path with either an exclusive or shared advisory lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal ** lock(path, "rw|") ** (Posix: lock, Python: lock) * attempts to acquire an advisory lock a file at a given path but does not block. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. *** Wes Garland ** tryLock(path, "shared|exclusive"): ** lock(path, "rw") ** (Python: lock) * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") ** lock(path, "u") ** (Python: lock) * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente ** (Python: os.stat, Ruby: File.stat, Posix: stat) * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.lstat, Ruby: File.lstat) * returns the size of the corresponding file. ** size(path) ** (Python: size, Ruby: size?: Java: length, Posix: st_size) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. The given permissions object may be a Unix numeric representation of permissions, a Stat object, or any object that provides the members of Stat regarding permissions. ** open(path, "+arwxc", permissions, encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) ** (Java: FileStream classes, Python: open, file, Ruby: File.new, universal precedent among SSJS frameworks) ** open([path,] {[path: path,] mode: "+arxwc", permissions: permissions, encoding: encoding})<br>(keyword-style parameters, first parameter is path or keyword object containing path) *** Aristid Breitkreuz * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) ** (Python: os.listdir, Ruby: Dir) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) ** (Ruby: Dir[]) * returns whether a given path matches a glob pattern. ** match(pattern, path) ** (Ruby: fnmatch) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem object. * a string directing a path up to the parent of the current directory, usually '..'. ** PARENT ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) ** (Python: pardir) * a string directing a path back to itself, usually '.'. ** SELF ** (Python: curdir) * a string that contains the path separator, usually '/', '\', or ':'. ** SEPARATOR ** (Python: sep, Spidermonkey: separator, Ruby: SEPARATOR, Separator) * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** ALTERNATE_SEPARATOR ** (Python: altsep, Ruby: ALT_SEPARATOR) * a string that contains the extension separator, usually '.'. ** EXTENSION_SEPRATOR ** (Python: extsep) * whether the file system supports unicode file names ** SUPPORTS_UNICODE_FILE_NAMES * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) ** (not precedented) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland ** (Python: Unix: dirname) * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland ** (Python: Unix: basename) * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland ** (Ruby: extname) * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) ** (Python: normpath) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to epxanding any user directory alias, joining the path to the current working directory, and normalizing the result. ** absolute(path) ** (Python: abspath) * returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding an user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. ** canonical(path) ** (Python: realpath) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) ** (Python: isabs) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** atime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastAccessed: *** Kris Kowal ** (Python: getatime, Ruby: atime) * the Date that the file was last modified. ** mtime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastModified: *** Kris Kowal *** Mario Valente ** (Python: getmtime, Ruby: mtime, Java: Spidermonkey: Helma: lastModified, jslibs: modifyTime, EJScript: modified, Synchronet: date) * the Date that the file's stat/metadata was last modified. ** ctime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** (Ruby: ctime, Python: getctime) * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: ** omit entirely: *** Kris Kowal ** (Spidermonkey: jslibs: creationTime, EJScript: create) * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** omit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory ** (Spidermonkey: isDir, Helma: isDir, JSExt: isdir) * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** omit entirely: *** Wes Garland *** Ondrej Zara * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size *** Ondrej Zara ** (jslibs: size, Helma: getLength, Spidermonkey: wxJS: EJScript: Synchronet: length) * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner ** setuid * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner ** setgid * whether the corresponding directory will permit anyone to create files in it, but only let the owner of a file delete it. ** sticky * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() ** (Python: JSExt: readline, Spidermonkey: Helma: Synchronet: readln) * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() ** (Python: readlines, JSExt: readlines, EJScript: getLines) * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) ** (universal precedent) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() ** (wxJS: JSExt: Python: Ruby: tell) * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) ** (Ruby: truncate, Python: ftruncate) * returns whether the cursor is at the end of the IO stream. ** eof() *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** (Helma: wxJS: JSExt: Synchronet: eof) * flushes buffers for an IO stream ** flush() ** (universal precedent) * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") ** (related to isOpen in many existing SSJS frameworks, but without a race condition hazard) * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = General Preferences = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) #** Ondrej Zara # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #** Ondrej Zara #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #** Ondrej Zara #** George Moschovitis #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #** expand: #*** Ondrej Zara #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #** normalize: #*** Ondrej Zara #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor #** Ondrej Zara #** George Moschovitis #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #** Ondrej Zara #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = References = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 75 2009-04-07T23:39:08Z KrisKowal Supported open with options = API and Proposed Names = The following sections are organized with a bullet point per function. Each point includes a specification for the behavior of a given method, intended to be suitable for documentation. Under each definition is a list of potential names for that function, and in bullets beneath that, everyone is encouraged to write their name under their preference. Please feel to leave comments as well. In the next section, "General Preferences", there are several broad sweeping points about whether to use certain conventions in a consistent fashion. All of the name options are intended to conform to the prevalent opinion among those elections. For example, "make" and "create" and "dir" and "directory" are both general preference elections, so if you would prefer "makeDir" over "createDirectory", please vote independently for "make" and "dir" in the general preferences. == File System Object == The "file" module would conform to the File System API, as well as objects returned by "chroot". There is no definitive implementation of a FileSystem class, so "chroot" is the only way to construct new objects that conform to the FileSystem API. In permissive environments, the "file" module may have direct access to ambient authority through a foreign function interface, or may itself be a dynamically loaded module. In secured environments, the "file" module must copy the properties of "environment.fs" onto its exports. In a secure sandbox, the following statements would be equivalent. require('file').open(foo) environment.fs.open(foo) Since "fs" must be frozen to be secure, there is no need for the "file" module to assemble aparatus for late binding to "fs" methods. * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland *** (Python: os.path.exists, Ruby: exist?, exists?, Java: exists, JSExt: access, Spidermonkey: Helma: v8cgi: JSExt: EJScript: Synchronet: exists, jslibs: exist) * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.path.lexists) * moves a file from a source to a target path. Both paths are joined on the current working directory. ** move(source, target): ** (Ruby: move, Python: shutil.move, Java: File.renameTo) * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal ** (Ruby: rename) * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): ** (Ruby: copy, systemCopy, Python: copy, Unix: cp) * copies a file and its recursive contents to a target path. Both paths are joined on the current working directory. If "synbolicLinks" is truthy, symbolic links in the source tree are represented as symbolic links in the new tree; if falsy, the contents of the linked files are copied to the new tree. If ignore is given, it must be a relation that will receive as its arguments the directory being visited by copytree(), and a list of its contents. Since this is called recursively (or walking an equivalent iteration), the ignore relation will be called once for each directory that is copied. The relation must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. ** copyTree(source, target, symbolicLinks = false, ignore = undefined) ** copy(source, target, "recursive") ** copy(source, target, true) ** (Python: copytree) * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente ** (Unix: mkdir) * creates recursive directories. Makes all intermediate-level directories needed to contain the leaf directory. Throws an exception if the leaf directory already exists or cannot be created. The default mode is 0777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "recursive"): ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) ** makeTree(path) ** (Unix: mkdir -p, Ruby: makedirs, mkpath, Python: os.makedirs) * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland ** (Ruby: unlink, delete, Python: unlink, remove, Java: delete, Posix: unlink, Unix: rm, Spidermonkey: Helma: EJScript: Synchronet: remove, jslibs: Delete) * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) ** removeTree(path, ignoreErrors = false, onError = undefined) ** (Unix: rm -r, Python: rmtree) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested ** (Python: link, Ruby: link, Unix: ln) * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) ** (Ruby: symlink, Python: symlink, Unix: ln -s) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland ** (Java: createNewFile, Posix: creat, Unix: touch) * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): ** omit entirely: *** Kris Kowal ** (Ruby: truncate, Python: ftruncate applies to open files only) * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. *** Wes Garland ** update(path, stat): ** chstat(path, stat): ** setStat(path, stat): ** restat(path, stat): ** (a low-level alternative to Python's copy2 and copyStat) * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal ** (Unix: touch) * locks the file at a given path with either an exclusive or shared advisory lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal ** lock(path, "rw|") ** (Posix: lock, Python: lock) * attempts to acquire an advisory lock a file at a given path but does not block. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. *** Wes Garland ** tryLock(path, "shared|exclusive"): ** lock(path, "rw") ** (Python: lock) * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") ** lock(path, "u") ** (Python: lock) * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente ** (Python: os.stat, Ruby: File.stat, Posix: stat) * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.lstat, Ruby: File.lstat) * returns the size of the corresponding file. ** size(path) ** (Python: size, Ruby: size?: Java: length, Posix: st_size) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. The given permissions object may be a Unix numeric representation of permissions, a Stat object, or any object that provides the members of Stat regarding permissions. ** open(path, "+arwxc", permissions, encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) ** (Java: FileStream classes, Python: open, file, Ruby: File.new, universal precedent among SSJS frameworks) ** open([path,] [mode,] {[path: path,] mode: "+arxwc", permissions: permissions, encoding: encoding})<br>(keyword-style parameters, first parameter is path or keyword object containing path) *** Aristid Breitkreuz *** Kris Kowal * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) ** (Python: os.listdir, Ruby: Dir) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) ** (Ruby: Dir[]) * returns whether a given path matches a glob pattern. ** match(pattern, path) ** (Ruby: fnmatch) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem object. * a string directing a path up to the parent of the current directory, usually '..'. ** PARENT ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) ** (Python: pardir) * a string directing a path back to itself, usually '.'. ** SELF ** (Python: curdir) * a string that contains the path separator, usually '/', '\', or ':'. ** SEPARATOR ** (Python: sep, Spidermonkey: separator, Ruby: SEPARATOR, Separator) * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** ALTERNATE_SEPARATOR ** (Python: altsep, Ruby: ALT_SEPARATOR) * a string that contains the extension separator, usually '.'. ** EXTENSION_SEPRATOR ** (Python: extsep) * whether the file system supports unicode file names ** SUPPORTS_UNICODE_FILE_NAMES * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) ** (not precedented) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland ** (Python: Unix: dirname) * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland ** (Python: Unix: basename) * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland ** (Ruby: extname) * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) ** (Python: normpath) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to epxanding any user directory alias, joining the path to the current working directory, and normalizing the result. ** absolute(path) ** (Python: abspath) * returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding an user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. ** canonical(path) ** (Python: realpath) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) ** (Python: isabs) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** atime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastAccessed: *** Kris Kowal ** (Python: getatime, Ruby: atime) * the Date that the file was last modified. ** mtime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastModified: *** Kris Kowal *** Mario Valente ** (Python: getmtime, Ruby: mtime, Java: Spidermonkey: Helma: lastModified, jslibs: modifyTime, EJScript: modified, Synchronet: date) * the Date that the file's stat/metadata was last modified. ** ctime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** (Ruby: ctime, Python: getctime) * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: ** omit entirely: *** Kris Kowal ** (Spidermonkey: jslibs: creationTime, EJScript: create) * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** omit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory ** (Spidermonkey: isDir, Helma: isDir, JSExt: isdir) * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** omit entirely: *** Wes Garland *** Ondrej Zara * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size *** Ondrej Zara ** (jslibs: size, Helma: getLength, Spidermonkey: wxJS: EJScript: Synchronet: length) * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner ** setuid * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner ** setgid * whether the corresponding directory will permit anyone to create files in it, but only let the owner of a file delete it. ** sticky * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() ** (Python: JSExt: readline, Spidermonkey: Helma: Synchronet: readln) * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() ** (Python: readlines, JSExt: readlines, EJScript: getLines) * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) ** (universal precedent) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() ** (wxJS: JSExt: Python: Ruby: tell) * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) ** (Ruby: truncate, Python: ftruncate) * returns whether the cursor is at the end of the IO stream. ** eof() *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** (Helma: wxJS: JSExt: Synchronet: eof) * flushes buffers for an IO stream ** flush() ** (universal precedent) * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") ** (related to isOpen in many existing SSJS frameworks, but without a race condition hazard) * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = General Preferences = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) #** Ondrej Zara # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #** Ondrej Zara #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #** Ondrej Zara #** George Moschovitis #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #** expand: #*** Ondrej Zara #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #** normalize: #*** Ondrej Zara #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor #** Ondrej Zara #** George Moschovitis #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #** Ondrej Zara #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = References = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 76 2009-04-16T07:08:38Z KrisKowal Noted Kevin's elections for mkdir and mkdirs (by way of him having implemented them in Narwhal by those names) = API and Proposed Names = The following sections are organized with a bullet point per function. Each point includes a specification for the behavior of a given method, intended to be suitable for documentation. Under each definition is a list of potential names for that function, and in bullets beneath that, everyone is encouraged to write their name under their preference. Please feel to leave comments as well. In the next section, "General Preferences", there are several broad sweeping points about whether to use certain conventions in a consistent fashion. All of the name options are intended to conform to the prevalent opinion among those elections. For example, "make" and "create" and "dir" and "directory" are both general preference elections, so if you would prefer "makeDir" over "createDirectory", please vote independently for "make" and "dir" in the general preferences. == File System Object == The "file" module would conform to the File System API, as well as objects returned by "chroot". There is no definitive implementation of a FileSystem class, so "chroot" is the only way to construct new objects that conform to the FileSystem API. In permissive environments, the "file" module may have direct access to ambient authority through a foreign function interface, or may itself be a dynamically loaded module. In secured environments, the "file" module must copy the properties of "environment.fs" onto its exports. In a secure sandbox, the following statements would be equivalent. require('file').open(foo) environment.fs.open(foo) Since "fs" must be frozen to be secure, there is no need for the "file" module to assemble aparatus for late binding to "fs" methods. * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland *** (Python: os.path.exists, Ruby: exist?, exists?, Java: exists, JSExt: access, Spidermonkey: Helma: v8cgi: JSExt: EJScript: Synchronet: exists, jslibs: exist) * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.path.lexists) * moves a file from a source to a target path. Both paths are joined on the current working directory. ** move(source, target): ** (Ruby: move, Python: shutil.move, Java: File.renameTo) * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal ** (Ruby: rename) * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): ** (Ruby: copy, systemCopy, Python: copy, Unix: cp) * copies a file and its recursive contents to a target path. Both paths are joined on the current working directory. If "synbolicLinks" is truthy, symbolic links in the source tree are represented as symbolic links in the new tree; if falsy, the contents of the linked files are copied to the new tree. If ignore is given, it must be a relation that will receive as its arguments the directory being visited by copytree(), and a list of its contents. Since this is called recursively (or walking an equivalent iteration), the ignore relation will be called once for each directory that is copied. The relation must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. ** copyTree(source, target, symbolicLinks = false, ignore = undefined) ** copy(source, target, "recursive") ** copy(source, target, true) ** (Python: copytree) * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente ** mkdir(path) *** Kevin Dangoor ** (Unix: mkdir) * creates recursive directories. Makes all intermediate-level directories needed to contain the leaf directory. Throws an exception if the leaf directory already exists or cannot be created. The default mode is 0777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "recursive"): ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) ** makeTree(path) ** (Unix: mkdir -p, Ruby: makedirs, mkpath, Python: os.makedirs) ** mkdirs(path) *** Kevin Dangoor * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland ** (Ruby: unlink, delete, Python: unlink, remove, Java: delete, Posix: unlink, Unix: rm, Spidermonkey: Helma: EJScript: Synchronet: remove, jslibs: Delete) * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) ** removeTree(path, ignoreErrors = false, onError = undefined) ** (Unix: rm -r, Python: rmtree) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested ** (Python: link, Ruby: link, Unix: ln) * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) ** (Ruby: symlink, Python: symlink, Unix: ln -s) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland ** (Java: createNewFile, Posix: creat, Unix: touch) * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): ** omit entirely: *** Kris Kowal ** (Ruby: truncate, Python: ftruncate applies to open files only) * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. *** Wes Garland ** update(path, stat): ** chstat(path, stat): ** setStat(path, stat): ** restat(path, stat): ** (a low-level alternative to Python's copy2 and copyStat) * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal ** (Unix: touch) * locks the file at a given path with either an exclusive or shared advisory lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal ** lock(path, "rw|") ** (Posix: lock, Python: lock) * attempts to acquire an advisory lock a file at a given path but does not block. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. *** Wes Garland ** tryLock(path, "shared|exclusive"): ** lock(path, "rw") ** (Python: lock) * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") ** lock(path, "u") ** (Python: lock) * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente ** (Python: os.stat, Ruby: File.stat, Posix: stat) * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.lstat, Ruby: File.lstat) * returns the size of the corresponding file. ** size(path) ** (Python: size, Ruby: size?: Java: length, Posix: st_size) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. The given permissions object may be a Unix numeric representation of permissions, a Stat object, or any object that provides the members of Stat regarding permissions. ** open(path, "+arwxc", permissions, encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) ** (Java: FileStream classes, Python: open, file, Ruby: File.new, universal precedent among SSJS frameworks) ** open([path,] [mode,] {[path: path,] mode: "+arxwc", permissions: permissions, encoding: encoding})<br>(keyword-style parameters, first parameter is path or keyword object containing path) *** Aristid Breitkreuz *** Kris Kowal * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) ** (Python: os.listdir, Ruby: Dir) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) ** (Ruby: Dir[]) * returns whether a given path matches a glob pattern. ** match(pattern, path) ** (Ruby: fnmatch) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem object. * a string directing a path up to the parent of the current directory, usually '..'. ** PARENT ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) ** (Python: pardir) * a string directing a path back to itself, usually '.'. ** SELF ** (Python: curdir) * a string that contains the path separator, usually '/', '\', or ':'. ** SEPARATOR ** (Python: sep, Spidermonkey: separator, Ruby: SEPARATOR, Separator) * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** ALTERNATE_SEPARATOR ** (Python: altsep, Ruby: ALT_SEPARATOR) * a string that contains the extension separator, usually '.'. ** EXTENSION_SEPRATOR ** (Python: extsep) * whether the file system supports unicode file names ** SUPPORTS_UNICODE_FILE_NAMES * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) ** (not precedented) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland ** (Python: Unix: dirname) * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland ** (Python: Unix: basename) * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland ** (Ruby: extname) * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) ** (Python: normpath) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to epxanding any user directory alias, joining the path to the current working directory, and normalizing the result. ** absolute(path) ** (Python: abspath) * returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding an user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. ** canonical(path) ** (Python: realpath) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) ** (Python: isabs) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** atime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastAccessed: *** Kris Kowal ** (Python: getatime, Ruby: atime) * the Date that the file was last modified. ** mtime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastModified: *** Kris Kowal *** Mario Valente ** (Python: getmtime, Ruby: mtime, Java: Spidermonkey: Helma: lastModified, jslibs: modifyTime, EJScript: modified, Synchronet: date) * the Date that the file's stat/metadata was last modified. ** ctime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** (Ruby: ctime, Python: getctime) * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: ** omit entirely: *** Kris Kowal ** (Spidermonkey: jslibs: creationTime, EJScript: create) * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** omit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory ** (Spidermonkey: isDir, Helma: isDir, JSExt: isdir) * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** omit entirely: *** Wes Garland *** Ondrej Zara * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size *** Ondrej Zara ** (jslibs: size, Helma: getLength, Spidermonkey: wxJS: EJScript: Synchronet: length) * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner ** setuid * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner ** setgid * whether the corresponding directory will permit anyone to create files in it, but only let the owner of a file delete it. ** sticky * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() ** (Python: JSExt: readline, Spidermonkey: Helma: Synchronet: readln) * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() ** (Python: readlines, JSExt: readlines, EJScript: getLines) * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) ** (universal precedent) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() ** (wxJS: JSExt: Python: Ruby: tell) * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) ** (Ruby: truncate, Python: ftruncate) * returns whether the cursor is at the end of the IO stream. ** eof() *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** (Helma: wxJS: JSExt: Synchronet: eof) * flushes buffers for an IO stream ** flush() ** (universal precedent) * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") ** (related to isOpen in many existing SSJS frameworks, but without a race condition hazard) * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = General Preferences = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) #** Ondrej Zara # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #** Ondrej Zara #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #** Ondrej Zara #** George Moschovitis #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #** expand: #*** Ondrej Zara #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #** normalize: #*** Ondrej Zara #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor #** Ondrej Zara #** George Moschovitis #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #** Ondrej Zara #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = References = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 77 2009-04-24T19:52:58Z KrisKowal /* File System Object */ purged use of "environment" name. = API and Proposed Names = The following sections are organized with a bullet point per function. Each point includes a specification for the behavior of a given method, intended to be suitable for documentation. Under each definition is a list of potential names for that function, and in bullets beneath that, everyone is encouraged to write their name under their preference. Please feel to leave comments as well. In the next section, "General Preferences", there are several broad sweeping points about whether to use certain conventions in a consistent fashion. All of the name options are intended to conform to the prevalent opinion among those elections. For example, "make" and "create" and "dir" and "directory" are both general preference elections, so if you would prefer "makeDir" over "createDirectory", please vote independently for "make" and "dir" in the general preferences. == File System Object == The "file" module would conform to the File System API, as well as objects returned by "chroot". There is no definitive implementation of a FileSystem class, so "chroot" is the only way to construct new objects that conform to the FileSystem API. In permissive platforms, the "file" module may have direct access to ambient authority through a foreign function interface, or may itself be a dynamically loaded module. In secured platform, the "file" module must copy the properties of "system.fs" onto its exports. In a secure sandbox, the following statements would be equivalent. require('file').open(foo) system.fs.open(foo) Since "fs" must be frozen to be secure, there is no need for the "file" module to assemble aparatus for late binding to "fs" methods. * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland *** (Python: os.path.exists, Ruby: exist?, exists?, Java: exists, JSExt: access, Spidermonkey: Helma: v8cgi: JSExt: EJScript: Synchronet: exists, jslibs: exist) * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.path.lexists) * moves a file from a source to a target path. Both paths are joined on the current working directory. ** move(source, target): ** (Ruby: move, Python: shutil.move, Java: File.renameTo) * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal ** (Ruby: rename) * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): ** (Ruby: copy, systemCopy, Python: copy, Unix: cp) * copies a file and its recursive contents to a target path. Both paths are joined on the current working directory. If "synbolicLinks" is truthy, symbolic links in the source tree are represented as symbolic links in the new tree; if falsy, the contents of the linked files are copied to the new tree. If ignore is given, it must be a relation that will receive as its arguments the directory being visited by copytree(), and a list of its contents. Since this is called recursively (or walking an equivalent iteration), the ignore relation will be called once for each directory that is copied. The relation must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. ** copyTree(source, target, symbolicLinks = false, ignore = undefined) ** copy(source, target, "recursive") ** copy(source, target, true) ** (Python: copytree) * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente ** mkdir(path) *** Kevin Dangoor ** (Unix: mkdir) * creates recursive directories. Makes all intermediate-level directories needed to contain the leaf directory. Throws an exception if the leaf directory already exists or cannot be created. The default mode is 0777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "recursive"): ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) ** makeTree(path) ** (Unix: mkdir -p, Ruby: makedirs, mkpath, Python: os.makedirs) ** mkdirs(path) *** Kevin Dangoor * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland ** (Ruby: unlink, delete, Python: unlink, remove, Java: delete, Posix: unlink, Unix: rm, Spidermonkey: Helma: EJScript: Synchronet: remove, jslibs: Delete) * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) ** removeTree(path, ignoreErrors = false, onError = undefined) ** (Unix: rm -r, Python: rmtree) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested ** (Python: link, Ruby: link, Unix: ln) * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) ** (Ruby: symlink, Python: symlink, Unix: ln -s) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland ** (Java: createNewFile, Posix: creat, Unix: touch) * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): ** omit entirely: *** Kris Kowal ** (Ruby: truncate, Python: ftruncate applies to open files only) * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. *** Wes Garland ** update(path, stat): ** chstat(path, stat): ** setStat(path, stat): ** restat(path, stat): ** (a low-level alternative to Python's copy2 and copyStat) * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal ** (Unix: touch) * locks the file at a given path with either an exclusive or shared advisory lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal ** lock(path, "rw|") ** (Posix: lock, Python: lock) * attempts to acquire an advisory lock a file at a given path but does not block. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. *** Wes Garland ** tryLock(path, "shared|exclusive"): ** lock(path, "rw") ** (Python: lock) * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") ** lock(path, "u") ** (Python: lock) * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente ** (Python: os.stat, Ruby: File.stat, Posix: stat) * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.lstat, Ruby: File.lstat) * returns the size of the corresponding file. ** size(path) ** (Python: size, Ruby: size?: Java: length, Posix: st_size) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. The given permissions object may be a Unix numeric representation of permissions, a Stat object, or any object that provides the members of Stat regarding permissions. ** open(path, "+arwxc", permissions, encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) ** (Java: FileStream classes, Python: open, file, Ruby: File.new, universal precedent among SSJS frameworks) ** open([path,] [mode,] {[path: path,] mode: "+arxwc", permissions: permissions, encoding: encoding})<br>(keyword-style parameters, first parameter is path or keyword object containing path) *** Aristid Breitkreuz *** Kris Kowal * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) ** (Python: os.listdir, Ruby: Dir) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) ** (Ruby: Dir[]) * returns whether a given path matches a glob pattern. ** match(pattern, path) ** (Ruby: fnmatch) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem object. * a string directing a path up to the parent of the current directory, usually '..'. ** PARENT ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) ** (Python: pardir) * a string directing a path back to itself, usually '.'. ** SELF ** (Python: curdir) * a string that contains the path separator, usually '/', '\', or ':'. ** SEPARATOR ** (Python: sep, Spidermonkey: separator, Ruby: SEPARATOR, Separator) * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** ALTERNATE_SEPARATOR ** (Python: altsep, Ruby: ALT_SEPARATOR) * a string that contains the extension separator, usually '.'. ** EXTENSION_SEPRATOR ** (Python: extsep) * whether the file system supports unicode file names ** SUPPORTS_UNICODE_FILE_NAMES * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) ** (not precedented) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland ** (Python: Unix: dirname) * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland ** (Python: Unix: basename) * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland ** (Ruby: extname) * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) ** (Python: normpath) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to epxanding any user directory alias, joining the path to the current working directory, and normalizing the result. ** absolute(path) ** (Python: abspath) * returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding an user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. ** canonical(path) ** (Python: realpath) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) ** (Python: isabs) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** atime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastAccessed: *** Kris Kowal ** (Python: getatime, Ruby: atime) * the Date that the file was last modified. ** mtime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastModified: *** Kris Kowal *** Mario Valente ** (Python: getmtime, Ruby: mtime, Java: Spidermonkey: Helma: lastModified, jslibs: modifyTime, EJScript: modified, Synchronet: date) * the Date that the file's stat/metadata was last modified. ** ctime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastChanged: *** Wes Garland ** lastStatModified: *** Kris Kowal ** (Ruby: ctime, Python: getctime) * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: ** omit entirely: *** Kris Kowal ** (Spidermonkey: jslibs: creationTime, EJScript: create) * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** omit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory ** (Spidermonkey: isDir, Helma: isDir, JSExt: isdir) * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** omit entirely: *** Wes Garland *** Ondrej Zara * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size *** Ondrej Zara ** (jslibs: size, Helma: getLength, Spidermonkey: wxJS: EJScript: Synchronet: length) * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner ** setuid * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner ** setgid * whether the corresponding directory will permit anyone to create files in it, but only let the owner of a file delete it. ** sticky * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() ** (Python: JSExt: readline, Spidermonkey: Helma: Synchronet: readln) * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() ** (Python: readlines, JSExt: readlines, EJScript: getLines) * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) ** (universal precedent) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() ** (wxJS: JSExt: Python: Ruby: tell) * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) ** (Ruby: truncate, Python: ftruncate) * returns whether the cursor is at the end of the IO stream. ** eof() *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** (Helma: wxJS: JSExt: Synchronet: eof) * flushes buffers for an IO stream ** flush() ** (universal precedent) * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") ** (related to isOpen in many existing SSJS frameworks, but without a race condition hazard) * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = General Preferences = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) #** Ondrej Zara # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #** Ondrej Zara #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #** Ondrej Zara #** George Moschovitis #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #** expand: #*** Ondrej Zara #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #** normalize: #*** Ondrej Zara #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor #** Ondrej Zara #** George Moschovitis #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #** Ondrej Zara #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = References = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 78 2009-04-28T18:57:15Z KrisKowal Noted Daniel Friessen's election of lastModified. = API and Proposed Names = The following sections are organized with a bullet point per function. Each point includes a specification for the behavior of a given method, intended to be suitable for documentation. Under each definition is a list of potential names for that function, and in bullets beneath that, everyone is encouraged to write their name under their preference. Please feel to leave comments as well. In the next section, "General Preferences", there are several broad sweeping points about whether to use certain conventions in a consistent fashion. All of the name options are intended to conform to the prevalent opinion among those elections. For example, "make" and "create" and "dir" and "directory" are both general preference elections, so if you would prefer "makeDir" over "createDirectory", please vote independently for "make" and "dir" in the general preferences. == File System Object == The "file" module would conform to the File System API, as well as objects returned by "chroot". There is no definitive implementation of a FileSystem class, so "chroot" is the only way to construct new objects that conform to the FileSystem API. In permissive platforms, the "file" module may have direct access to ambient authority through a foreign function interface, or may itself be a dynamically loaded module. In secured platform, the "file" module must copy the properties of "system.fs" onto its exports. In a secure sandbox, the following statements would be equivalent. require('file').open(foo) system.fs.open(foo) Since "fs" must be frozen to be secure, there is no need for the "file" module to assemble aparatus for late binding to "fs" methods. * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland *** (Python: os.path.exists, Ruby: exist?, exists?, Java: exists, JSExt: access, Spidermonkey: Helma: v8cgi: JSExt: EJScript: Synchronet: exists, jslibs: exist) * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.path.lexists) * moves a file from a source to a target path. Both paths are joined on the current working directory. ** move(source, target): ** (Ruby: move, Python: shutil.move, Java: File.renameTo) * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal ** (Ruby: rename) * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): ** (Ruby: copy, systemCopy, Python: copy, Unix: cp) * copies a file and its recursive contents to a target path. Both paths are joined on the current working directory. If "synbolicLinks" is truthy, symbolic links in the source tree are represented as symbolic links in the new tree; if falsy, the contents of the linked files are copied to the new tree. If ignore is given, it must be a relation that will receive as its arguments the directory being visited by copytree(), and a list of its contents. Since this is called recursively (or walking an equivalent iteration), the ignore relation will be called once for each directory that is copied. The relation must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. ** copyTree(source, target, symbolicLinks = false, ignore = undefined) ** copy(source, target, "recursive") ** copy(source, target, true) ** (Python: copytree) * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente ** mkdir(path) *** Kevin Dangoor ** (Unix: mkdir) * creates recursive directories. Makes all intermediate-level directories needed to contain the leaf directory. Throws an exception if the leaf directory already exists or cannot be created. The default mode is 0777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "recursive"): ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) ** makeTree(path) ** (Unix: mkdir -p, Ruby: makedirs, mkpath, Python: os.makedirs) ** mkdirs(path) *** Kevin Dangoor * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland ** (Ruby: unlink, delete, Python: unlink, remove, Java: delete, Posix: unlink, Unix: rm, Spidermonkey: Helma: EJScript: Synchronet: remove, jslibs: Delete) * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) ** removeTree(path, ignoreErrors = false, onError = undefined) ** (Unix: rm -r, Python: rmtree) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested ** (Python: link, Ruby: link, Unix: ln) * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) ** (Ruby: symlink, Python: symlink, Unix: ln -s) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland ** (Java: createNewFile, Posix: creat, Unix: touch) * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): ** omit entirely: *** Kris Kowal ** (Ruby: truncate, Python: ftruncate applies to open files only) * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. *** Wes Garland ** update(path, stat): ** chstat(path, stat): ** setStat(path, stat): ** restat(path, stat): ** (a low-level alternative to Python's copy2 and copyStat) * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal ** (Unix: touch) * locks the file at a given path with either an exclusive or shared advisory lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal ** lock(path, "rw|") ** (Posix: lock, Python: lock) * attempts to acquire an advisory lock a file at a given path but does not block. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. *** Wes Garland ** tryLock(path, "shared|exclusive"): ** lock(path, "rw") ** (Python: lock) * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") ** lock(path, "u") ** (Python: lock) * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente ** (Python: os.stat, Ruby: File.stat, Posix: stat) * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.lstat, Ruby: File.lstat) * returns the size of the corresponding file. ** size(path) ** (Python: size, Ruby: size?: Java: length, Posix: st_size) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. The given permissions object may be a Unix numeric representation of permissions, a Stat object, or any object that provides the members of Stat regarding permissions. ** open(path, "+arwxc", permissions, encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) ** (Java: FileStream classes, Python: open, file, Ruby: File.new, universal precedent among SSJS frameworks) ** open([path,] [mode,] {[path: path,] mode: "+arxwc", permissions: permissions, encoding: encoding})<br>(keyword-style parameters, first parameter is path or keyword object containing path) *** Aristid Breitkreuz *** Kris Kowal * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) ** (Python: os.listdir, Ruby: Dir) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) ** (Ruby: Dir[]) * returns whether a given path matches a glob pattern. ** match(pattern, path) ** (Ruby: fnmatch) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem object. * a string directing a path up to the parent of the current directory, usually '..'. ** PARENT ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) ** (Python: pardir) * a string directing a path back to itself, usually '.'. ** SELF ** (Python: curdir) * a string that contains the path separator, usually '/', '\', or ':'. ** SEPARATOR ** (Python: sep, Spidermonkey: separator, Ruby: SEPARATOR, Separator) * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** ALTERNATE_SEPARATOR ** (Python: altsep, Ruby: ALT_SEPARATOR) * a string that contains the extension separator, usually '.'. ** EXTENSION_SEPRATOR ** (Python: extsep) * whether the file system supports unicode file names ** SUPPORTS_UNICODE_FILE_NAMES * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) ** (not precedented) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland ** (Python: Unix: dirname) * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland ** (Python: Unix: basename) * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland ** (Ruby: extname) * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) ** (Python: normpath) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to epxanding any user directory alias, joining the path to the current working directory, and normalizing the result. ** absolute(path) ** (Python: abspath) * returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding an user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. ** canonical(path) ** (Python: realpath) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) ** (Python: isabs) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** atime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastAccessed: *** Kris Kowal ** (Python: getatime, Ruby: atime) * the Date that the file was last modified. ** mtime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastModified: *** Kris Kowal *** Mario Valente *** Daniel Friessen ** (Python: getmtime, Ruby: mtime, Java: Spidermonkey: Helma: lastModified, jslibs: modifyTime, EJScript: modified, Synchronet: date) * the Date that the file's stat/metadata was last modified. ** ctime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastChanged: *** Wes Garland *** Kris Kowal ** (Ruby: ctime, Python: getctime) * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: ** omit entirely: *** Kris Kowal ** (Spidermonkey: jslibs: creationTime, EJScript: create) * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** omit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory ** (Spidermonkey: isDir, Helma: isDir, JSExt: isdir) * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** omit entirely: *** Wes Garland *** Ondrej Zara * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size *** Ondrej Zara ** (jslibs: size, Helma: getLength, Spidermonkey: wxJS: EJScript: Synchronet: length) * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner ** setuid * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner ** setgid * whether the corresponding directory will permit anyone to create files in it, but only let the owner of a file delete it. ** sticky * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() ** (Python: JSExt: readline, Spidermonkey: Helma: Synchronet: readln) * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() ** (Python: readlines, JSExt: readlines, EJScript: getLines) * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) ** (universal precedent) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() ** (wxJS: JSExt: Python: Ruby: tell) * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) ** (Ruby: truncate, Python: ftruncate) * returns whether the cursor is at the end of the IO stream. ** eof() *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** (Helma: wxJS: JSExt: Synchronet: eof) * flushes buffers for an IO stream ** flush() ** (universal precedent) * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") ** (related to isOpen in many existing SSJS frameworks, but without a race condition hazard) * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = General Preferences = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) #** Ondrej Zara # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #** Ondrej Zara #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #** Ondrej Zara #** George Moschovitis #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #** expand: #*** Ondrej Zara #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #** normalize: #*** Ondrej Zara #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor #** Ondrej Zara #** George Moschovitis #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #** Ondrej Zara #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = References = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing ServerJS File API nomenclature and support 79 2009-05-17T23:35:44Z KrisKowal Moved to ServerJS/Filesystem_API/Names Moved to [[ServerJS/Filesystem_API/Names]]. 80 2009-09-09T22:13:57Z Dantman 1 7 revisions:&#32;Import from https://wiki.mozilla.org/ServerJS Moved to [[ServerJS/Filesystem_API/Names]]. 631 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API/file/Names]] to [[CommonJS/API/file/Names]]:&#32;Subpages needed to be enabled Moved to [[ServerJS/Filesystem_API/Names]]. 788 2009-09-09T22:40:39Z Dantman 1 Robot: Automated text replacement (-ServerJS +CommonJS) Moved to [[CommonJS/Filesystem_API/Names]]. 929 2009-09-10T03:04:06Z Dantman 1 Redirected page to [[CommonJS/Filesystem API/Names]] #REDIRECT [[CommonJS/Filesystem_API/Names]]. 930 2009-09-10T03:04:16Z Dantman 1 ` #REDIRECT [[Filesystem/Names]]. 981 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/file/Names]] to [[OldAPI/file/Names]] #REDIRECT [[Filesystem/Names]]. 11 81 2009-02-18T07:44:12Z KrisKowal An rough initial proposal for a file module for ServerJS. /** */ /*** File - :isa:`io#Io` */ /*** Stat - :isa:`Object` a representation of a file's metadata including permissions, ownership, time stamps, and other traits. */ /*** Dir */ /**** iter */ /*** glob returns a `List` of file names for a given "glob" expression that may contain patterns: === ====================================================== ? matches any single character * matches any pattern of characters ** matches any pattern of characters in the file names of a depth first traversal starting with the file names and directories that start with the file name characters before ``**`` and ending with the file name characters after ``**`` === ====================================================== */ /*** globIter returns an iteration of file names for a given "glob" expression that may contain patterns according to those documented in `glob` */ /*** separator The path separator for the platform's file systems. */ /*** resolve returns the real, absolute, fully-qualified path arrived at from a ``base`` path following an relative ``rel`` path. When no ``base`` is provided, resolves the ``rel`` path relative to the current working directory. - accepts ``rel`` - accepts an optional ``base`` */ /*** relative returns the relative path between two fully-qualifed paths. */ /*** baseName */ /*** dirName */ 82 2009-09-09T22:13:57Z Dantman 1 1 revision:&#32;Import from https://wiki.mozilla.org/ServerJS /** */ /*** File - :isa:`io#Io` */ /*** Stat - :isa:`Object` a representation of a file's metadata including permissions, ownership, time stamps, and other traits. */ /*** Dir */ /**** iter */ /*** glob returns a `List` of file names for a given "glob" expression that may contain patterns: === ====================================================== ? matches any single character * matches any pattern of characters ** matches any pattern of characters in the file names of a depth first traversal starting with the file names and directories that start with the file name characters before ``**`` and ending with the file name characters after ``**`` === ====================================================== */ /*** globIter returns an iteration of file names for a given "glob" expression that may contain patterns according to those documented in `glob` */ /*** separator The path separator for the platform's file systems. */ /*** resolve returns the real, absolute, fully-qualified path arrived at from a ``base`` path following an relative ``rel`` path. When no ``base`` is provided, resolves the ``rel`` path relative to the current working directory. - accepts ``rel`` - accepts an optional ``base`` */ /*** relative returns the relative path between two fully-qualifed paths. */ /*** baseName */ /*** dirName */ 633 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API/file/ProposalK]] to [[CommonJS/API/file/ProposalK]]:&#32;Subpages needed to be enabled /** */ /*** File - :isa:`io#Io` */ /*** Stat - :isa:`Object` a representation of a file's metadata including permissions, ownership, time stamps, and other traits. */ /*** Dir */ /**** iter */ /*** glob returns a `List` of file names for a given "glob" expression that may contain patterns: === ====================================================== ? matches any single character * matches any pattern of characters ** matches any pattern of characters in the file names of a depth first traversal starting with the file names and directories that start with the file name characters before ``**`` and ending with the file name characters after ``**`` === ====================================================== */ /*** globIter returns an iteration of file names for a given "glob" expression that may contain patterns according to those documented in `glob` */ /*** separator The path separator for the platform's file systems. */ /*** resolve returns the real, absolute, fully-qualified path arrived at from a ``base`` path following an relative ``rel`` path. When no ``base`` is provided, resolves the ``rel`` path relative to the current working directory. - accepts ``rel`` - accepts an optional ``base`` */ /*** relative returns the relative path between two fully-qualifed paths. */ /*** baseName */ /*** dirName */ 983 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/file/ProposalK]] to [[OldAPI/file/ProposalK]] /** */ /*** File - :isa:`io#Io` */ /*** Stat - :isa:`Object` a representation of a file's metadata including permissions, ownership, time stamps, and other traits. */ /*** Dir */ /**** iter */ /*** glob returns a `List` of file names for a given "glob" expression that may contain patterns: === ====================================================== ? matches any single character * matches any pattern of characters ** matches any pattern of characters in the file names of a depth first traversal starting with the file names and directories that start with the file name characters before ``**`` and ending with the file name characters after ``**`` === ====================================================== */ /*** globIter returns an iteration of file names for a given "glob" expression that may contain patterns according to those documented in `glob` */ /*** separator The path separator for the platform's file systems. */ /*** resolve returns the real, absolute, fully-qualified path arrived at from a ``base`` path following an relative ``rel`` path. When no ``base`` is provided, resolves the ``rel`` path relative to the current working directory. - accepts ``rel`` - accepts an optional ``base`` */ /*** relative returns the relative path between two fully-qualifed paths. */ /*** baseName */ /*** dirName */ 12 83 2009-02-18T07:13:27Z KrisKowal An initial proposal for an IO module for ServerJS. /** */ /*** Io - :is:`iter#Iterable` */ /**** input - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier - returns a `String` decoded from reading */ /**** print - accepts a `String` to encode and write - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier */ /**** read - accepts a maximum `Number` of bytes to read. - returns a `Binary` of however many bytes were actually read. */ /**** write - returns a `Number` of however many bytes were actually written. */ /**** readNonblock - accepts a maximum `Number` of bytes to read. - returns a `Binary` of however many bytes were read without blocking. */ /**** writeNonblock - accepts a `Binary` of bytes to write. - returns a `Number` of however many bytes were actually written without blocking. */ /**** isEof returns whether the read/write head is at or beyond the end of the stream. */ /**** iter an alias for `linesIter` */ /**** linesIter - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier returns an iteration on lines (`String`) of the stream. */ /**** charsIter - accepts an optional `String` encoding module identifier returns an iteration of characters (`String`) of the stream. */ /**** bytesIter returns an iteration on bytes (`Binary`) of the stream. */ /**** fcntl */ /**** getFileNo returns an integer `Number` for the process stream number that the IO object is attached to. */ /**** toNumber an alias for `getFileNo` */ /**** getLineNo returns the current "line" number from the file. updated on read. */ /**** isTty returns whether the stream is attached to a terminal device, a teletype, ``tty``. */ /**** getPos get the current byte offset of the read/write head in the stream. */ /**** setPos set the current byte offset of the read/write head in the stream. */ /**** rewind Equivalent to ``setPos(0)`` */ /**** seek Seeks to a given integer `Number` offset in the stream relative to a given position: Accepts: - ``offset``, an integer `Number` - ``whence``, an enumerated integer `Number` supplied by one of the following constants. Whence: ======== ================================== SEEK_CUR Seeks to current position plus ``offset`` SEEK_END Seeks to the end of the stream plus ``offset``, usually negative. SEEK_SET Seeks to the beginning of the stream plus ``offset`` ======== ================================== Example:: var file = require('file'); var io = require('io'); var f = file.File("testfile", "utf-8"); f.seek(-13, io.SEEK_END); var line = f.input() */ /**** stat */ /**** select */ /**** fsync */ /**** ioctl */ 84 2009-02-18T23:00:36Z KrisKowal This module and the file module in this proposal are a hybrid of mostly the Ruby API melded with Pythonic/Rhinocerous iteration, and liberated of the notion that certain things should be static methods as opposed to simply hosted by the module. /** */ /*** Io - :is:`iter#Iterable` */ /**** input - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier - returns a `String` decoded from reading */ /**** print - accepts a `String` to encode and write - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier */ /**** read - accepts a maximum `Number` of bytes to read. - returns a `Binary` of however many bytes were actually read. */ /**** write - returns a `Number` of however many bytes were actually written. */ /**** readNonblock - accepts a maximum `Number` of bytes to read. - returns a `Binary` of however many bytes were read without blocking. */ /**** writeNonblock - accepts a `Binary` of bytes to write. - returns a `Number` of however many bytes were actually written without blocking. */ /**** isEof returns whether the read/write head is at or beyond the end of the stream. */ /**** iter an alias for `linesIter` */ /**** linesIter - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier returns an iteration on lines (`String`) of the stream. */ /**** charsIter - accepts an optional `String` encoding module identifier returns an iteration of characters (`String`) of the stream. */ /**** bytesIter returns an iteration on bytes (`Binary`) of the stream. */ /**** fcntl */ /**** getFileNo returns an integer `Number` for the process stream number that the IO object is attached to. */ /**** toNumber an alias for `getFileNo` */ /**** getLineNo returns the current "line" number from the file. updated on read. */ /**** isTty returns whether the stream is attached to a terminal device, a teletype, ``tty``. */ /**** getPos get the current byte offset of the read/write head in the stream. */ /**** setPos set the current byte offset of the read/write head in the stream. */ /**** rewind Equivalent to ``setPos(0)`` */ /**** seek Seeks to a given integer `Number` offset in the stream relative to a given position: Accepts: - ``offset``, an integer `Number` - ``whence``, an enumerated integer `Number` supplied by one of the following constants. Whence: ======== ================================== SEEK_CUR Seeks to current position plus ``offset`` SEEK_END Seeks to the end of the stream plus ``offset``, usually negative. SEEK_SET Seeks to the beginning of the stream plus ``offset`` ======== ================================== Example:: var file = require('file'); var io = require('io'); var f = file.File("testfile", "utf-8"); f.seek(-13, io.SEEK_END); var line = f.input() */ /**** stat */ /**** select */ /**** fsync */ /**** ioctl */ 85 2009-09-09T22:13:58Z Dantman 1 2 revisions:&#32;Import from https://wiki.mozilla.org/ServerJS This module and the file module in this proposal are a hybrid of mostly the Ruby API melded with Pythonic/Rhinocerous iteration, and liberated of the notion that certain things should be static methods as opposed to simply hosted by the module. /** */ /*** Io - :is:`iter#Iterable` */ /**** input - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier - returns a `String` decoded from reading */ /**** print - accepts a `String` to encode and write - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier */ /**** read - accepts a maximum `Number` of bytes to read. - returns a `Binary` of however many bytes were actually read. */ /**** write - returns a `Number` of however many bytes were actually written. */ /**** readNonblock - accepts a maximum `Number` of bytes to read. - returns a `Binary` of however many bytes were read without blocking. */ /**** writeNonblock - accepts a `Binary` of bytes to write. - returns a `Number` of however many bytes were actually written without blocking. */ /**** isEof returns whether the read/write head is at or beyond the end of the stream. */ /**** iter an alias for `linesIter` */ /**** linesIter - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier returns an iteration on lines (`String`) of the stream. */ /**** charsIter - accepts an optional `String` encoding module identifier returns an iteration of characters (`String`) of the stream. */ /**** bytesIter returns an iteration on bytes (`Binary`) of the stream. */ /**** fcntl */ /**** getFileNo returns an integer `Number` for the process stream number that the IO object is attached to. */ /**** toNumber an alias for `getFileNo` */ /**** getLineNo returns the current "line" number from the file. updated on read. */ /**** isTty returns whether the stream is attached to a terminal device, a teletype, ``tty``. */ /**** getPos get the current byte offset of the read/write head in the stream. */ /**** setPos set the current byte offset of the read/write head in the stream. */ /**** rewind Equivalent to ``setPos(0)`` */ /**** seek Seeks to a given integer `Number` offset in the stream relative to a given position: Accepts: - ``offset``, an integer `Number` - ``whence``, an enumerated integer `Number` supplied by one of the following constants. Whence: ======== ================================== SEEK_CUR Seeks to current position plus ``offset`` SEEK_END Seeks to the end of the stream plus ``offset``, usually negative. SEEK_SET Seeks to the beginning of the stream plus ``offset`` ======== ================================== Example:: var file = require('file'); var io = require('io'); var f = file.File("testfile", "utf-8"); f.seek(-13, io.SEEK_END); var line = f.input() */ /**** stat */ /**** select */ /**** fsync */ /**** ioctl */ 635 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API/io/ProposalK]] to [[CommonJS/API/io/ProposalK]]:&#32;Subpages needed to be enabled This module and the file module in this proposal are a hybrid of mostly the Ruby API melded with Pythonic/Rhinocerous iteration, and liberated of the notion that certain things should be static methods as opposed to simply hosted by the module. /** */ /*** Io - :is:`iter#Iterable` */ /**** input - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier - returns a `String` decoded from reading */ /**** print - accepts a `String` to encode and write - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier */ /**** read - accepts a maximum `Number` of bytes to read. - returns a `Binary` of however many bytes were actually read. */ /**** write - returns a `Number` of however many bytes were actually written. */ /**** readNonblock - accepts a maximum `Number` of bytes to read. - returns a `Binary` of however many bytes were read without blocking. */ /**** writeNonblock - accepts a `Binary` of bytes to write. - returns a `Number` of however many bytes were actually written without blocking. */ /**** isEof returns whether the read/write head is at or beyond the end of the stream. */ /**** iter an alias for `linesIter` */ /**** linesIter - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier returns an iteration on lines (`String`) of the stream. */ /**** charsIter - accepts an optional `String` encoding module identifier returns an iteration of characters (`String`) of the stream. */ /**** bytesIter returns an iteration on bytes (`Binary`) of the stream. */ /**** fcntl */ /**** getFileNo returns an integer `Number` for the process stream number that the IO object is attached to. */ /**** toNumber an alias for `getFileNo` */ /**** getLineNo returns the current "line" number from the file. updated on read. */ /**** isTty returns whether the stream is attached to a terminal device, a teletype, ``tty``. */ /**** getPos get the current byte offset of the read/write head in the stream. */ /**** setPos set the current byte offset of the read/write head in the stream. */ /**** rewind Equivalent to ``setPos(0)`` */ /**** seek Seeks to a given integer `Number` offset in the stream relative to a given position: Accepts: - ``offset``, an integer `Number` - ``whence``, an enumerated integer `Number` supplied by one of the following constants. Whence: ======== ================================== SEEK_CUR Seeks to current position plus ``offset`` SEEK_END Seeks to the end of the stream plus ``offset``, usually negative. SEEK_SET Seeks to the beginning of the stream plus ``offset`` ======== ================================== Example:: var file = require('file'); var io = require('io'); var f = file.File("testfile", "utf-8"); f.seek(-13, io.SEEK_END); var line = f.input() */ /**** stat */ /**** select */ /**** fsync */ /**** ioctl */ 985 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/io/ProposalK]] to [[OldAPI/io/ProposalK]] This module and the file module in this proposal are a hybrid of mostly the Ruby API melded with Pythonic/Rhinocerous iteration, and liberated of the notion that certain things should be static methods as opposed to simply hosted by the module. /** */ /*** Io - :is:`iter#Iterable` */ /**** input - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier - returns a `String` decoded from reading */ /**** print - accepts a `String` to encode and write - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier */ /**** read - accepts a maximum `Number` of bytes to read. - returns a `Binary` of however many bytes were actually read. */ /**** write - returns a `Number` of however many bytes were actually written. */ /**** readNonblock - accepts a maximum `Number` of bytes to read. - returns a `Binary` of however many bytes were read without blocking. */ /**** writeNonblock - accepts a `Binary` of bytes to write. - returns a `Number` of however many bytes were actually written without blocking. */ /**** isEof returns whether the read/write head is at or beyond the end of the stream. */ /**** iter an alias for `linesIter` */ /**** linesIter - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier returns an iteration on lines (`String`) of the stream. */ /**** charsIter - accepts an optional `String` encoding module identifier returns an iteration of characters (`String`) of the stream. */ /**** bytesIter returns an iteration on bytes (`Binary`) of the stream. */ /**** fcntl */ /**** getFileNo returns an integer `Number` for the process stream number that the IO object is attached to. */ /**** toNumber an alias for `getFileNo` */ /**** getLineNo returns the current "line" number from the file. updated on read. */ /**** isTty returns whether the stream is attached to a terminal device, a teletype, ``tty``. */ /**** getPos get the current byte offset of the read/write head in the stream. */ /**** setPos set the current byte offset of the read/write head in the stream. */ /**** rewind Equivalent to ``setPos(0)`` */ /**** seek Seeks to a given integer `Number` offset in the stream relative to a given position: Accepts: - ``offset``, an integer `Number` - ``whence``, an enumerated integer `Number` supplied by one of the following constants. Whence: ======== ================================== SEEK_CUR Seeks to current position plus ``offset`` SEEK_END Seeks to the end of the stream plus ``offset``, usually negative. SEEK_SET Seeks to the beginning of the stream plus ``offset`` ======== ================================== Example:: var file = require('file'); var io = require('io'); var f = file.File("testfile", "utf-8"); f.seek(-13, io.SEEK_END); var line = f.input() */ /**** stat */ /**** select */ /**** fsync */ /**** ioctl */ 13 86 2009-02-18T08:06:55Z KrisKowal Rough cut of an iteration module API for ServerJS /*** Iterable a mixin that adds convenience functions to types that implement `iter`. */ /**** iter a default ``iter`` that returns itself. */ /**** added */ /**** nextCatch */ /**** len a default, destructive implementation of `len` that consumes the remaining elements of the iteration and returns how many were encountered. */ /**** toObject */ /**** toArray */ /**** toList */ /**** toDict */ /**** toUnique returns a `Set` of the unique elements of the iterable. */ /**** toString returns the concatenation of the elements of the iterable coerced into `String` objects. */ /**** toNumber a polymorphic alias of `len`. */ /**** toBoolean returns whether `toNumber` is greater than 0. */ /**** sliced */ /**** forEach */ /**** forEachApply */ /**** each */ /**** eachIter */ /**** eachApply */ /**** eachApplyIter */ /**** where */ /**** whereIter */ /**** whereApply */ /**** whereApplyIter */ /**** zip */ /**** zipIter */ /**** transpose */ /**** transposeIter */ /**** enumerate */ /**** enumerateIter */ /**** reduce */ /**** reduced */ /**** flatten */ /**** flattened */ /**** group */ /**** sorted */ /**** reversed */ /**** min */ /**** mix */ /**** sum */ /**** product */ /**** all */ /**** any */ /**** join */ /*** Iter - :is:`Iterable` Accepts: - an optional ``next`` `Function`. Without a ``next`` function, returns an empty iteration. - an optional ``hasNext`` `Function``. */ /**** next */ /**** hasNext */ /*** iter Returns an iteration of a given object. Attempts to call the polymorphic `iter` of a typed object. Otherwise, coerces to the first applicable of `String`, `Array`, or `Object` types. */ /*** objectIter */ /*** arrayIter */ /*** stringIter */ /** Top Level Functions =================== Functions that operate on iterables, or objects coercible to iterables using the polymorphic `iter` function. */ /*** forEach */ /*** forEachApply */ /*** each */ /*** each */ /*** eachIter */ /*** eachApply */ /*** eachApplyIter */ /*** where */ /*** whereIter */ /*** whereApply */ /*** whereApplyIter */ /*** map */ /*** mapIter */ /*** forTimes */ /*** timesIter */ /*** times */ /*** transpose */ /*** transposeIter */ /*** zip */ /*** zipIter /*** enumerate */ /*** enumerateIter */ /*** reduce */ /*** cycle */ /*** chain */ /*** repeat */ /*** flatten */ /*** compact */ /*** compactIter */ /*** without */ /*** withoutIter */ /*** group */ /*** all */ /*** any */ /*** min */ /*** max */ 87 2009-09-09T22:13:58Z Dantman 1 1 revision:&#32;Import from https://wiki.mozilla.org/ServerJS /*** Iterable a mixin that adds convenience functions to types that implement `iter`. */ /**** iter a default ``iter`` that returns itself. */ /**** added */ /**** nextCatch */ /**** len a default, destructive implementation of `len` that consumes the remaining elements of the iteration and returns how many were encountered. */ /**** toObject */ /**** toArray */ /**** toList */ /**** toDict */ /**** toUnique returns a `Set` of the unique elements of the iterable. */ /**** toString returns the concatenation of the elements of the iterable coerced into `String` objects. */ /**** toNumber a polymorphic alias of `len`. */ /**** toBoolean returns whether `toNumber` is greater than 0. */ /**** sliced */ /**** forEach */ /**** forEachApply */ /**** each */ /**** eachIter */ /**** eachApply */ /**** eachApplyIter */ /**** where */ /**** whereIter */ /**** whereApply */ /**** whereApplyIter */ /**** zip */ /**** zipIter */ /**** transpose */ /**** transposeIter */ /**** enumerate */ /**** enumerateIter */ /**** reduce */ /**** reduced */ /**** flatten */ /**** flattened */ /**** group */ /**** sorted */ /**** reversed */ /**** min */ /**** mix */ /**** sum */ /**** product */ /**** all */ /**** any */ /**** join */ /*** Iter - :is:`Iterable` Accepts: - an optional ``next`` `Function`. Without a ``next`` function, returns an empty iteration. - an optional ``hasNext`` `Function``. */ /**** next */ /**** hasNext */ /*** iter Returns an iteration of a given object. Attempts to call the polymorphic `iter` of a typed object. Otherwise, coerces to the first applicable of `String`, `Array`, or `Object` types. */ /*** objectIter */ /*** arrayIter */ /*** stringIter */ /** Top Level Functions =================== Functions that operate on iterables, or objects coercible to iterables using the polymorphic `iter` function. */ /*** forEach */ /*** forEachApply */ /*** each */ /*** each */ /*** eachIter */ /*** eachApply */ /*** eachApplyIter */ /*** where */ /*** whereIter */ /*** whereApply */ /*** whereApplyIter */ /*** map */ /*** mapIter */ /*** forTimes */ /*** timesIter */ /*** times */ /*** transpose */ /*** transposeIter */ /*** zip */ /*** zipIter /*** enumerate */ /*** enumerateIter */ /*** reduce */ /*** cycle */ /*** chain */ /*** repeat */ /*** flatten */ /*** compact */ /*** compactIter */ /*** without */ /*** withoutIter */ /*** group */ /*** all */ /*** any */ /*** min */ /*** max */ 637 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API/iter/ProposalK]] to [[CommonJS/API/iter/ProposalK]]:&#32;Subpages needed to be enabled /*** Iterable a mixin that adds convenience functions to types that implement `iter`. */ /**** iter a default ``iter`` that returns itself. */ /**** added */ /**** nextCatch */ /**** len a default, destructive implementation of `len` that consumes the remaining elements of the iteration and returns how many were encountered. */ /**** toObject */ /**** toArray */ /**** toList */ /**** toDict */ /**** toUnique returns a `Set` of the unique elements of the iterable. */ /**** toString returns the concatenation of the elements of the iterable coerced into `String` objects. */ /**** toNumber a polymorphic alias of `len`. */ /**** toBoolean returns whether `toNumber` is greater than 0. */ /**** sliced */ /**** forEach */ /**** forEachApply */ /**** each */ /**** eachIter */ /**** eachApply */ /**** eachApplyIter */ /**** where */ /**** whereIter */ /**** whereApply */ /**** whereApplyIter */ /**** zip */ /**** zipIter */ /**** transpose */ /**** transposeIter */ /**** enumerate */ /**** enumerateIter */ /**** reduce */ /**** reduced */ /**** flatten */ /**** flattened */ /**** group */ /**** sorted */ /**** reversed */ /**** min */ /**** mix */ /**** sum */ /**** product */ /**** all */ /**** any */ /**** join */ /*** Iter - :is:`Iterable` Accepts: - an optional ``next`` `Function`. Without a ``next`` function, returns an empty iteration. - an optional ``hasNext`` `Function``. */ /**** next */ /**** hasNext */ /*** iter Returns an iteration of a given object. Attempts to call the polymorphic `iter` of a typed object. Otherwise, coerces to the first applicable of `String`, `Array`, or `Object` types. */ /*** objectIter */ /*** arrayIter */ /*** stringIter */ /** Top Level Functions =================== Functions that operate on iterables, or objects coercible to iterables using the polymorphic `iter` function. */ /*** forEach */ /*** forEachApply */ /*** each */ /*** each */ /*** eachIter */ /*** eachApply */ /*** eachApplyIter */ /*** where */ /*** whereIter */ /*** whereApply */ /*** whereApplyIter */ /*** map */ /*** mapIter */ /*** forTimes */ /*** timesIter */ /*** times */ /*** transpose */ /*** transposeIter */ /*** zip */ /*** zipIter /*** enumerate */ /*** enumerateIter */ /*** reduce */ /*** cycle */ /*** chain */ /*** repeat */ /*** flatten */ /*** compact */ /*** compactIter */ /*** without */ /*** withoutIter */ /*** group */ /*** all */ /*** any */ /*** min */ /*** max */ 987 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/iter/ProposalK]] to [[OldAPI/iter/ProposalK]] /*** Iterable a mixin that adds convenience functions to types that implement `iter`. */ /**** iter a default ``iter`` that returns itself. */ /**** added */ /**** nextCatch */ /**** len a default, destructive implementation of `len` that consumes the remaining elements of the iteration and returns how many were encountered. */ /**** toObject */ /**** toArray */ /**** toList */ /**** toDict */ /**** toUnique returns a `Set` of the unique elements of the iterable. */ /**** toString returns the concatenation of the elements of the iterable coerced into `String` objects. */ /**** toNumber a polymorphic alias of `len`. */ /**** toBoolean returns whether `toNumber` is greater than 0. */ /**** sliced */ /**** forEach */ /**** forEachApply */ /**** each */ /**** eachIter */ /**** eachApply */ /**** eachApplyIter */ /**** where */ /**** whereIter */ /**** whereApply */ /**** whereApplyIter */ /**** zip */ /**** zipIter */ /**** transpose */ /**** transposeIter */ /**** enumerate */ /**** enumerateIter */ /**** reduce */ /**** reduced */ /**** flatten */ /**** flattened */ /**** group */ /**** sorted */ /**** reversed */ /**** min */ /**** mix */ /**** sum */ /**** product */ /**** all */ /**** any */ /**** join */ /*** Iter - :is:`Iterable` Accepts: - an optional ``next`` `Function`. Without a ``next`` function, returns an empty iteration. - an optional ``hasNext`` `Function``. */ /**** next */ /**** hasNext */ /*** iter Returns an iteration of a given object. Attempts to call the polymorphic `iter` of a typed object. Otherwise, coerces to the first applicable of `String`, `Array`, or `Object` types. */ /*** objectIter */ /*** arrayIter */ /*** stringIter */ /** Top Level Functions =================== Functions that operate on iterables, or objects coercible to iterables using the polymorphic `iter` function. */ /*** forEach */ /*** forEachApply */ /*** each */ /*** each */ /*** eachIter */ /*** eachApply */ /*** eachApplyIter */ /*** where */ /*** whereIter */ /*** whereApply */ /*** whereApplyIter */ /*** map */ /*** mapIter */ /*** forTimes */ /*** timesIter */ /*** times */ /*** transpose */ /*** transposeIter */ /*** zip */ /*** zipIter /*** enumerate */ /*** enumerateIter */ /*** reduce */ /*** cycle */ /*** chain */ /*** repeat */ /*** flatten */ /*** compact */ /*** compactIter */ /*** without */ /*** withoutIter */ /*** group */ /*** all */ /*** any */ /*** min */ /*** max */ 14 88 2009-02-18T22:15:15Z KrisKowal Added a proposal for a lists module for ServerJS /*** List is `Iterable` Different than Python: - append: `push` - extend: `add` - count: `len` - index: `find` - insert: `put` - remove: `del` Same as Python: - `pop` - `sort` - `reverse` */ /**** toIter - `stateless` */ /**** len - `stateless` */ /**** push - `stateful` - `chainable` */ /**** pop - `stateful` */ /**** unshift - `stateful` - `chainable` */ /**** shift - `stateful` */ /**** reverse - `stateful` - `chainable` */ /**** reversed - `stateless` */ /**** reversedIter - `stateless` */ /**** sort - `stateful` - `chainable` */ /**** sorted - `stateless` - `chainable` */ /**** slice - `stateful` - `chainable` */ /**** sliced - `stateless` - `chainable` */ /**** splice - `stateful` */ /**** spliced - `stateless` - `chainable` */ /**** clear - `stateful` - `chainable` */ /**** first - `stateless` */ /**** last - `stateless` */ /**** begins returns whether the first elements of a given list-like-object are equal, by way of `eq`, the respective elements in this list. In Python, this function is called ``startswith``. This divergence from Python nomenclature is a matter of idealism. Ideally the semantic group of `start`, `stop`, `pause`, `resume`, and `run` are all temporal verbs, whereas the semantic group `begins`, `ends`, `first`, `last`, and such all apply to the state of spatial segments or lists. - `stateless` */ /**** ends returns whether the last elements of a given list-like-object are equal, by way of `eq`, the respective elements in this list. In Python, this function is called ``endsWith``. See ``startsWith`` for the rationale. - `stateless` */ /**** reduce reduce is an in place operation. see reduced for a stateless variant - `stateful` - `chainable` */ /**** keysIter - `stateless` */ /**** keys - `stateless` */ /**** valuesIter - `stateless` */ /**** values an alias of `copy` so that lists can be used as dictionary like objects. - `stateless` */ /**** itemsIter enumerates the values of the list. - `stateless` */ /**** items returns a list of the enumerated values from this list, using `itemsIter`. - `stateless` */ /**** get gets a value by its offset. - `stateless` */ /**** set sets a value at a particular offset. - `stateful` - `chainable` */ /**** put displaces the item at a given index, sending successive elements down the line. - `stateful` - `chainable` */ /**** cut gets the value at a given offset and delete the value from the list. - `stateful` */ /**** del removes a value from the list, shifting all successive values into its void. - `stateful` - `chainable` */ /**** has returns whether the list contains a given value. - `stateless` */ /**** hasKey returns whether the list contains a value at a given index. - `stateless` */ /**** hasValue retunrs whether the list contains a given value. Uses `has`. - `stateless` */ /**** find returns the first index of a given value in the list, or throws a `ValueError` if none can be found. - `stateless` */ /**** findReverse returns the last index of a given value in the list, or throws a `ValueError` if none can be found. - `stateless` */ /**** insert an alias of `push` */ /**** retrieve */ /**** remove */ /**** discard */ /**** add - `stateful` - `chainable` */ /**** added - `stateless` - `chainable` */ /**** eq returns whether this list has the same cardinality, order, and respective values as another object. - `stateless` */ /**** lt returns whether the the most significant, distinct value between the respective values of this list and another list-like object is less than the other. - `stateless` */ /**** join returns a `String` of the joined string values of the values in this list, on a given delimiter or simply concatenated. - `stateless` */ /**** repr - `stateless` */ /**** toArray - `stateless` */ /**** hash - `stateless` */ /*** toList constructs a `List` from any given iterable. Defers to a `toList` or `toIter` method of the given object if it exists. - `poymorphic` on `toList` or `toIter` */ /*** toArray constructs a native JavaScript `Array` from any iterable. - `polymorphic` on `toArray` or `toIter` */ /*** len returns the length of a `List`, `Array`, `Object`, or any other object that provides a `len` member function. - `polymorphic` */ /*** reversed returns a `List` of the values from an iterable in reversed order. - `stateless` */ /*** sorted returns a `List` of the values in a given `Iteration` in sorted order. Accepts an optional override of `compare`, a binary relation that returns a `Number` that has the same comparison relationship with ``0`` as the relationship between the given values. For example, ``-1`` if the first is less than the second, or ``0`` if they are equal. - `stateless` */ /*** slice - `polymorphic` - `not-curry` - `stateless` */ /*** splice */ 89 2009-09-09T22:13:58Z Dantman 1 1 revision:&#32;Import from https://wiki.mozilla.org/ServerJS /*** List is `Iterable` Different than Python: - append: `push` - extend: `add` - count: `len` - index: `find` - insert: `put` - remove: `del` Same as Python: - `pop` - `sort` - `reverse` */ /**** toIter - `stateless` */ /**** len - `stateless` */ /**** push - `stateful` - `chainable` */ /**** pop - `stateful` */ /**** unshift - `stateful` - `chainable` */ /**** shift - `stateful` */ /**** reverse - `stateful` - `chainable` */ /**** reversed - `stateless` */ /**** reversedIter - `stateless` */ /**** sort - `stateful` - `chainable` */ /**** sorted - `stateless` - `chainable` */ /**** slice - `stateful` - `chainable` */ /**** sliced - `stateless` - `chainable` */ /**** splice - `stateful` */ /**** spliced - `stateless` - `chainable` */ /**** clear - `stateful` - `chainable` */ /**** first - `stateless` */ /**** last - `stateless` */ /**** begins returns whether the first elements of a given list-like-object are equal, by way of `eq`, the respective elements in this list. In Python, this function is called ``startswith``. This divergence from Python nomenclature is a matter of idealism. Ideally the semantic group of `start`, `stop`, `pause`, `resume`, and `run` are all temporal verbs, whereas the semantic group `begins`, `ends`, `first`, `last`, and such all apply to the state of spatial segments or lists. - `stateless` */ /**** ends returns whether the last elements of a given list-like-object are equal, by way of `eq`, the respective elements in this list. In Python, this function is called ``endsWith``. See ``startsWith`` for the rationale. - `stateless` */ /**** reduce reduce is an in place operation. see reduced for a stateless variant - `stateful` - `chainable` */ /**** keysIter - `stateless` */ /**** keys - `stateless` */ /**** valuesIter - `stateless` */ /**** values an alias of `copy` so that lists can be used as dictionary like objects. - `stateless` */ /**** itemsIter enumerates the values of the list. - `stateless` */ /**** items returns a list of the enumerated values from this list, using `itemsIter`. - `stateless` */ /**** get gets a value by its offset. - `stateless` */ /**** set sets a value at a particular offset. - `stateful` - `chainable` */ /**** put displaces the item at a given index, sending successive elements down the line. - `stateful` - `chainable` */ /**** cut gets the value at a given offset and delete the value from the list. - `stateful` */ /**** del removes a value from the list, shifting all successive values into its void. - `stateful` - `chainable` */ /**** has returns whether the list contains a given value. - `stateless` */ /**** hasKey returns whether the list contains a value at a given index. - `stateless` */ /**** hasValue retunrs whether the list contains a given value. Uses `has`. - `stateless` */ /**** find returns the first index of a given value in the list, or throws a `ValueError` if none can be found. - `stateless` */ /**** findReverse returns the last index of a given value in the list, or throws a `ValueError` if none can be found. - `stateless` */ /**** insert an alias of `push` */ /**** retrieve */ /**** remove */ /**** discard */ /**** add - `stateful` - `chainable` */ /**** added - `stateless` - `chainable` */ /**** eq returns whether this list has the same cardinality, order, and respective values as another object. - `stateless` */ /**** lt returns whether the the most significant, distinct value between the respective values of this list and another list-like object is less than the other. - `stateless` */ /**** join returns a `String` of the joined string values of the values in this list, on a given delimiter or simply concatenated. - `stateless` */ /**** repr - `stateless` */ /**** toArray - `stateless` */ /**** hash - `stateless` */ /*** toList constructs a `List` from any given iterable. Defers to a `toList` or `toIter` method of the given object if it exists. - `poymorphic` on `toList` or `toIter` */ /*** toArray constructs a native JavaScript `Array` from any iterable. - `polymorphic` on `toArray` or `toIter` */ /*** len returns the length of a `List`, `Array`, `Object`, or any other object that provides a `len` member function. - `polymorphic` */ /*** reversed returns a `List` of the values from an iterable in reversed order. - `stateless` */ /*** sorted returns a `List` of the values in a given `Iteration` in sorted order. Accepts an optional override of `compare`, a binary relation that returns a `Number` that has the same comparison relationship with ``0`` as the relationship between the given values. For example, ``-1`` if the first is less than the second, or ``0`` if they are equal. - `stateless` */ /*** slice - `polymorphic` - `not-curry` - `stateless` */ /*** splice */ 639 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API/list/ProposalK]] to [[CommonJS/API/list/ProposalK]]:&#32;Subpages needed to be enabled /*** List is `Iterable` Different than Python: - append: `push` - extend: `add` - count: `len` - index: `find` - insert: `put` - remove: `del` Same as Python: - `pop` - `sort` - `reverse` */ /**** toIter - `stateless` */ /**** len - `stateless` */ /**** push - `stateful` - `chainable` */ /**** pop - `stateful` */ /**** unshift - `stateful` - `chainable` */ /**** shift - `stateful` */ /**** reverse - `stateful` - `chainable` */ /**** reversed - `stateless` */ /**** reversedIter - `stateless` */ /**** sort - `stateful` - `chainable` */ /**** sorted - `stateless` - `chainable` */ /**** slice - `stateful` - `chainable` */ /**** sliced - `stateless` - `chainable` */ /**** splice - `stateful` */ /**** spliced - `stateless` - `chainable` */ /**** clear - `stateful` - `chainable` */ /**** first - `stateless` */ /**** last - `stateless` */ /**** begins returns whether the first elements of a given list-like-object are equal, by way of `eq`, the respective elements in this list. In Python, this function is called ``startswith``. This divergence from Python nomenclature is a matter of idealism. Ideally the semantic group of `start`, `stop`, `pause`, `resume`, and `run` are all temporal verbs, whereas the semantic group `begins`, `ends`, `first`, `last`, and such all apply to the state of spatial segments or lists. - `stateless` */ /**** ends returns whether the last elements of a given list-like-object are equal, by way of `eq`, the respective elements in this list. In Python, this function is called ``endsWith``. See ``startsWith`` for the rationale. - `stateless` */ /**** reduce reduce is an in place operation. see reduced for a stateless variant - `stateful` - `chainable` */ /**** keysIter - `stateless` */ /**** keys - `stateless` */ /**** valuesIter - `stateless` */ /**** values an alias of `copy` so that lists can be used as dictionary like objects. - `stateless` */ /**** itemsIter enumerates the values of the list. - `stateless` */ /**** items returns a list of the enumerated values from this list, using `itemsIter`. - `stateless` */ /**** get gets a value by its offset. - `stateless` */ /**** set sets a value at a particular offset. - `stateful` - `chainable` */ /**** put displaces the item at a given index, sending successive elements down the line. - `stateful` - `chainable` */ /**** cut gets the value at a given offset and delete the value from the list. - `stateful` */ /**** del removes a value from the list, shifting all successive values into its void. - `stateful` - `chainable` */ /**** has returns whether the list contains a given value. - `stateless` */ /**** hasKey returns whether the list contains a value at a given index. - `stateless` */ /**** hasValue retunrs whether the list contains a given value. Uses `has`. - `stateless` */ /**** find returns the first index of a given value in the list, or throws a `ValueError` if none can be found. - `stateless` */ /**** findReverse returns the last index of a given value in the list, or throws a `ValueError` if none can be found. - `stateless` */ /**** insert an alias of `push` */ /**** retrieve */ /**** remove */ /**** discard */ /**** add - `stateful` - `chainable` */ /**** added - `stateless` - `chainable` */ /**** eq returns whether this list has the same cardinality, order, and respective values as another object. - `stateless` */ /**** lt returns whether the the most significant, distinct value between the respective values of this list and another list-like object is less than the other. - `stateless` */ /**** join returns a `String` of the joined string values of the values in this list, on a given delimiter or simply concatenated. - `stateless` */ /**** repr - `stateless` */ /**** toArray - `stateless` */ /**** hash - `stateless` */ /*** toList constructs a `List` from any given iterable. Defers to a `toList` or `toIter` method of the given object if it exists. - `poymorphic` on `toList` or `toIter` */ /*** toArray constructs a native JavaScript `Array` from any iterable. - `polymorphic` on `toArray` or `toIter` */ /*** len returns the length of a `List`, `Array`, `Object`, or any other object that provides a `len` member function. - `polymorphic` */ /*** reversed returns a `List` of the values from an iterable in reversed order. - `stateless` */ /*** sorted returns a `List` of the values in a given `Iteration` in sorted order. Accepts an optional override of `compare`, a binary relation that returns a `Number` that has the same comparison relationship with ``0`` as the relationship between the given values. For example, ``-1`` if the first is less than the second, or ``0`` if they are equal. - `stateless` */ /*** slice - `polymorphic` - `not-curry` - `stateless` */ /*** splice */ 989 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/list/ProposalK]] to [[OldAPI/list/ProposalK]] /*** List is `Iterable` Different than Python: - append: `push` - extend: `add` - count: `len` - index: `find` - insert: `put` - remove: `del` Same as Python: - `pop` - `sort` - `reverse` */ /**** toIter - `stateless` */ /**** len - `stateless` */ /**** push - `stateful` - `chainable` */ /**** pop - `stateful` */ /**** unshift - `stateful` - `chainable` */ /**** shift - `stateful` */ /**** reverse - `stateful` - `chainable` */ /**** reversed - `stateless` */ /**** reversedIter - `stateless` */ /**** sort - `stateful` - `chainable` */ /**** sorted - `stateless` - `chainable` */ /**** slice - `stateful` - `chainable` */ /**** sliced - `stateless` - `chainable` */ /**** splice - `stateful` */ /**** spliced - `stateless` - `chainable` */ /**** clear - `stateful` - `chainable` */ /**** first - `stateless` */ /**** last - `stateless` */ /**** begins returns whether the first elements of a given list-like-object are equal, by way of `eq`, the respective elements in this list. In Python, this function is called ``startswith``. This divergence from Python nomenclature is a matter of idealism. Ideally the semantic group of `start`, `stop`, `pause`, `resume`, and `run` are all temporal verbs, whereas the semantic group `begins`, `ends`, `first`, `last`, and such all apply to the state of spatial segments or lists. - `stateless` */ /**** ends returns whether the last elements of a given list-like-object are equal, by way of `eq`, the respective elements in this list. In Python, this function is called ``endsWith``. See ``startsWith`` for the rationale. - `stateless` */ /**** reduce reduce is an in place operation. see reduced for a stateless variant - `stateful` - `chainable` */ /**** keysIter - `stateless` */ /**** keys - `stateless` */ /**** valuesIter - `stateless` */ /**** values an alias of `copy` so that lists can be used as dictionary like objects. - `stateless` */ /**** itemsIter enumerates the values of the list. - `stateless` */ /**** items returns a list of the enumerated values from this list, using `itemsIter`. - `stateless` */ /**** get gets a value by its offset. - `stateless` */ /**** set sets a value at a particular offset. - `stateful` - `chainable` */ /**** put displaces the item at a given index, sending successive elements down the line. - `stateful` - `chainable` */ /**** cut gets the value at a given offset and delete the value from the list. - `stateful` */ /**** del removes a value from the list, shifting all successive values into its void. - `stateful` - `chainable` */ /**** has returns whether the list contains a given value. - `stateless` */ /**** hasKey returns whether the list contains a value at a given index. - `stateless` */ /**** hasValue retunrs whether the list contains a given value. Uses `has`. - `stateless` */ /**** find returns the first index of a given value in the list, or throws a `ValueError` if none can be found. - `stateless` */ /**** findReverse returns the last index of a given value in the list, or throws a `ValueError` if none can be found. - `stateless` */ /**** insert an alias of `push` */ /**** retrieve */ /**** remove */ /**** discard */ /**** add - `stateful` - `chainable` */ /**** added - `stateless` - `chainable` */ /**** eq returns whether this list has the same cardinality, order, and respective values as another object. - `stateless` */ /**** lt returns whether the the most significant, distinct value between the respective values of this list and another list-like object is less than the other. - `stateless` */ /**** join returns a `String` of the joined string values of the values in this list, on a given delimiter or simply concatenated. - `stateless` */ /**** repr - `stateless` */ /**** toArray - `stateless` */ /**** hash - `stateless` */ /*** toList constructs a `List` from any given iterable. Defers to a `toList` or `toIter` method of the given object if it exists. - `poymorphic` on `toList` or `toIter` */ /*** toArray constructs a native JavaScript `Array` from any iterable. - `polymorphic` on `toArray` or `toIter` */ /*** len returns the length of a `List`, `Array`, `Object`, or any other object that provides a `len` member function. - `polymorphic` */ /*** reversed returns a `List` of the values from an iterable in reversed order. - `stateless` */ /*** sorted returns a `List` of the values in a given `Iteration` in sorted order. Accepts an optional override of `compare`, a binary relation that returns a `Number` that has the same comparison relationship with ``0`` as the relationship between the given values. For example, ``-1`` if the first is less than the second, or ``0`` if they are equal. - `stateless` */ /*** slice - `polymorphic` - `not-curry` - `stateless` */ /*** splice */ 15 90 2009-02-18T08:13:50Z KrisKowal Preliminary posix module API for ServerJS /** */ /*** open Accepts: - ``fileName`` - ``mode`` Returns a file descriptor of unspecified type. Modes ===== Mode Meaning ==== ====================================================================== "r" read-only, starting at the beginning of the file "r+" read-write, starting at the beginning of the file "w" write-only, truncates an existing file to empty or creates a new file "w+" read-write, truncates an existing file to empty or creates a new file "a" write-only, starts at end of file if file exists or creates a new file "a+" read-write, starts at end of file if file exists or creates a new file "b" binary file mode, may appear before any of the modes above */ /*** close */ /*** creat */ /*** flush */ /*** tell */ /*** stat */ /*** lstat */ /*** unlink */ /*** chown */ /*** chmod */ /*** dup */ /*** dup2 */ /*** fctnl */ /*** ioctl */ /*** select */ /*** getcwd */ 91 2009-02-18T23:02:38Z KrisKowal The idea behind this module is that it would be implemented as a native module on each respective platform and hosted by the default loader. Other IO modules would use these functions as a basis. /** */ /*** open Accepts: - ``fileName`` - ``mode`` Returns a file descriptor of unspecified type. Modes ===== Mode Meaning ==== ====================================================================== "r" read-only, starting at the beginning of the file "r+" read-write, starting at the beginning of the file "w" write-only, truncates an existing file to empty or creates a new file "w+" read-write, truncates an existing file to empty or creates a new file "a" write-only, starts at end of file if file exists or creates a new file "a+" read-write, starts at end of file if file exists or creates a new file "b" binary file mode, may appear before any of the modes above */ /*** close */ /*** creat */ /*** flush */ /*** tell */ /*** stat */ /*** lstat */ /*** unlink */ /*** chown */ /*** chmod */ /*** dup */ /*** dup2 */ /*** fctnl */ /*** ioctl */ /*** select */ /*** getcwd */ 92 2009-09-09T22:13:58Z Dantman 1 2 revisions:&#32;Import from https://wiki.mozilla.org/ServerJS The idea behind this module is that it would be implemented as a native module on each respective platform and hosted by the default loader. Other IO modules would use these functions as a basis. /** */ /*** open Accepts: - ``fileName`` - ``mode`` Returns a file descriptor of unspecified type. Modes ===== Mode Meaning ==== ====================================================================== "r" read-only, starting at the beginning of the file "r+" read-write, starting at the beginning of the file "w" write-only, truncates an existing file to empty or creates a new file "w+" read-write, truncates an existing file to empty or creates a new file "a" write-only, starts at end of file if file exists or creates a new file "a+" read-write, starts at end of file if file exists or creates a new file "b" binary file mode, may appear before any of the modes above */ /*** close */ /*** creat */ /*** flush */ /*** tell */ /*** stat */ /*** lstat */ /*** unlink */ /*** chown */ /*** chmod */ /*** dup */ /*** dup2 */ /*** fctnl */ /*** ioctl */ /*** select */ /*** getcwd */ 641 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS/API/posix/ProposalK]] to [[CommonJS/API/posix/ProposalK]]:&#32;Subpages needed to be enabled The idea behind this module is that it would be implemented as a native module on each respective platform and hosted by the default loader. Other IO modules would use these functions as a basis. /** */ /*** open Accepts: - ``fileName`` - ``mode`` Returns a file descriptor of unspecified type. Modes ===== Mode Meaning ==== ====================================================================== "r" read-only, starting at the beginning of the file "r+" read-write, starting at the beginning of the file "w" write-only, truncates an existing file to empty or creates a new file "w+" read-write, truncates an existing file to empty or creates a new file "a" write-only, starts at end of file if file exists or creates a new file "a+" read-write, starts at end of file if file exists or creates a new file "b" binary file mode, may appear before any of the modes above */ /*** close */ /*** creat */ /*** flush */ /*** tell */ /*** stat */ /*** lstat */ /*** unlink */ /*** chown */ /*** chmod */ /*** dup */ /*** dup2 */ /*** fctnl */ /*** ioctl */ /*** select */ /*** getcwd */ 991 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/posix/ProposalK]] to [[OldAPI/posix/ProposalK]] The idea behind this module is that it would be implemented as a native module on each respective platform and hosted by the default loader. Other IO modules would use these functions as a basis. /** */ /*** open Accepts: - ``fileName`` - ``mode`` Returns a file descriptor of unspecified type. Modes ===== Mode Meaning ==== ====================================================================== "r" read-only, starting at the beginning of the file "r+" read-write, starting at the beginning of the file "w" write-only, truncates an existing file to empty or creates a new file "w+" read-write, truncates an existing file to empty or creates a new file "a" write-only, starts at end of file if file exists or creates a new file "a+" read-write, starts at end of file if file exists or creates a new file "b" binary file mode, may appear before any of the modes above */ /*** close */ /*** creat */ /*** flush */ /*** tell */ /*** stat */ /*** lstat */ /*** unlink */ /*** chown */ /*** chmod */ /*** dup */ /*** dup2 */ /*** fctnl */ /*** ioctl */ /*** select */ /*** getcwd */ 16 93 2009-02-18T21:37:51Z KrisKowal Added a proposal for a sets module for ServerJS /*** Set An unordered collection of unique values. Accepts: - optional ``values`` (may be ``undefined``, or any iterable object, by way of the polymorphic `toIter`) - optional custom ``hash`` relation. - optional custom ``eq`` binary equivalence relation. Inherits member functions from `Iterable`. `Set` operations operate in constant time best case, and linear for degenerate cases. If you insert an object in a set and modify that object in such a way that its ``hash`` result changes, it will be irrecoverable. Most other libraries enforce that only immutable objects should be inserted in sets for this reason, so be careful. */ /*** insert inserts a value in the `Set`. Position is not relevant. Replaces an existing value if the value has the same `hash` key and is `eq` to an existing value. The `hash` function and `eq` function can be overridden in the `Set` constructor. - `stateful` - `chainable` */ /*** retrieve retrieves a value from the `Set` that has the same `hash` key and is `eq` to a given value. `eq` and `hash` can be overridden in the `Set` constructor. - `stateless` */ /**** remove removes a value from the `Set` if it has the same `hash` and is `eq` to the value. throws a `ValueError` if no matching value can be found. - `stateful` - `chainable` */ /**** discard discards a value from the `Set` if it has the same `hash` and is `eq` to the value. Unlike `remove`, does not throw a `ValueError` if no matching value can be found. - `stateful` - `chainable` */ /**** clear removes all values in this set. - `stateful` - `chainable` */ /**** has returns whether a set contains a given value. uses `eq` and `hash` to attempt to find the value in the set. These functions can be overridden in the `Set` constructor. */ /**** find searches all of the values in set for one that is `eq` to a given value. returns that value. throws a `ValueError` if no value can be found. - accepts a value to find - accepts an optional override to the `eq` function - `stateless` */ /**** toIter */ /**** eq */ /**** union augments itself with any values that exist in another iterable. - `stateful` - `chainable` */ /**** intersect - `stateful` - `chainable` */ /**** difference - `stateful` - `chainable` */ /**** unioned returns all elements that are in itself and another iterable. - `stateless` - `chainable` */ /**** intersected returns all values that are in this set and another. - `stateless` - `chainable` */ /**** differenced returns the set of all values that are in this set but not another. - `stateless` - `chainable` */ /**** symmetricDifferenced returns the set of all values that are exactly one set between itself and another. - `stateless` - `chainable` */ /**** isSuperSet returns whether this set contains all of the values in a given container. - `stateless` */ /**** isSubSet returns whether a given container contains all of this set's values. - `stateless` */ /**** added alias of `unioned` - `stateless` - `chainable` */ /**** add alias of `union` - `stateful` - `chainable` */ /**** muled alias of `intersected` - `stateless` - `chainable` */ /**** mul alias of `intersect` - `stateful` - `chainable` */ /**** subed alias of `differenced` - `stateless` - `chainable` */ /**** sub alias of `difference` - `stateful` - `chainable` */ /**** and alias of `intersect` - `stateful` - `chainable` */ /**** anded alias of `intersected` - `stateless` - `chainable` */ /**** or alias of `union` - `stateful` - `chainable` */ /**** ored alias of `unioned` - `stateless` - `chainable` */ /**** xor alias of `symmetricDifferenced` - `stateful` - `chainable` */ /**** xored alias of `symmetricDifferenced` - `stateless` - `chainable` */ /** Functions ========= Functions that operate on sets, or arrays coercible to sets using the polymorphic `toSet` function. */ /*** toSet */ /*** insert */ /*** retrieve */ /*** remove */ /*** discard */ /*** clear */ /*** has */ /*** union */ /*** intersect */ /*** difference */ /*** symetricDifference */ /*** isSuperSet */ /*** isSubSet */ 94 2009-09-09T22:13:58Z Dantman 1 1 revision:&#32;Import from https://wiki.mozilla.org/ServerJS /*** Set An unordered collection of unique values. Accepts: - optional ``values`` (may be ``undefined``, or any iterable object, by way of the polymorphic `toIter`) - optional custom ``hash`` relation. - optional custom ``eq`` binary equivalence relation. Inherits member functions from `Iterable`. `Set` operations operate in constant time best case, and linear for degenerate cases. If you insert an object in a set and modify that object in such a way that its ``hash`` result changes, it will be irrecoverable. Most other libraries enforce that only immutable objects should be inserted in sets for this reason, so be careful. */ /*** insert inserts a value in the `Set`. Position is not relevant. Replaces an existing value if the value has the same `hash` key and is `eq` to an existing value. The `hash` function and `eq` function can be overridden in the `Set` constructor. - `stateful` - `chainable` */ /*** retrieve retrieves a value from the `Set` that has the same `hash` key and is `eq` to a given value. `eq` and `hash` can be overridden in the `Set` constructor. - `stateless` */ /**** remove removes a value from the `Set` if it has the same `hash` and is `eq` to the value. throws a `ValueError` if no matching value can be found. - `stateful` - `chainable` */ /**** discard discards a value from the `Set` if it has the same `hash` and is `eq` to the value. Unlike `remove`, does not throw a `ValueError` if no matching value can be found. - `stateful` - `chainable` */ /**** clear removes all values in this set. - `stateful` - `chainable` */ /**** has returns whether a set contains a given value. uses `eq` and `hash` to attempt to find the value in the set. These functions can be overridden in the `Set` constructor. */ /**** find searches all of the values in set for one that is `eq` to a given value. returns that value. throws a `ValueError` if no value can be found. - accepts a value to find - accepts an optional override to the `eq` function - `stateless` */ /**** toIter */ /**** eq */ /**** union augments itself with any values that exist in another iterable. - `stateful` - `chainable` */ /**** intersect - `stateful` - `chainable` */ /**** difference - `stateful` - `chainable` */ /**** unioned returns all elements that are in itself and another iterable. - `stateless` - `chainable` */ /**** intersected returns all values that are in this set and another. - `stateless` - `chainable` */ /**** differenced returns the set of all values that are in this set but not another. - `stateless` - `chainable` */ /**** symmetricDifferenced returns the set of all values that are exactly one set between itself and another. - `stateless` - `chainable` */ /**** isSuperSet returns whether this set contains all of the values in a given container. - `stateless` */ /**** isSubSet returns whether a given container contains all of this set's values. - `stateless` */ /**** added alias of `unioned` - `stateless` - `chainable` */ /**** add alias of `union` - `stateful` - `chainable` */ /**** muled alias of `intersected` - `stateless` - `chainable` */ /**** mul alias of `intersect` - `stateful` - `chainable` */ /**** subed alias of `differenced` - `stateless` - `chainable` */ /**** sub alias of `difference` - `stateful` - `chainable` */ /**** and alias of `intersect` - `stateful` - `chainable` */ /**** anded alias of `intersected` - `stateless` - `chainable` */ /**** or alias of `union` - `stateful` - `chainable` */ /**** ored alias of `unioned` - `stateless` - `chainable` */ /**** xor alias of `symmetricDifferenced` - `stateful` - `chainable` */ /**** xored alias of `symmetricDifferenced` - `stateless` - `chainable` */ /** Functions ========= Functions that operate on sets, or arrays coercible to sets using the polymorphic `toSet` function. */ /*** toSet */ /*** insert */ /*** retrieve */ /*** remove */ /*** discard */ /*** clear */ /*** has */ /*** union */ /*** intersect */ /*** difference */ /*** symetricDifference */ /*** isSuperSet */ /*** isSubSet */ 643 2009-09-09T22:29:29Z Dantman 1 moved [[ServerJS/API/set/ProposalK]] to [[CommonJS/API/set/ProposalK]]:&#32;Subpages needed to be enabled /*** Set An unordered collection of unique values. Accepts: - optional ``values`` (may be ``undefined``, or any iterable object, by way of the polymorphic `toIter`) - optional custom ``hash`` relation. - optional custom ``eq`` binary equivalence relation. Inherits member functions from `Iterable`. `Set` operations operate in constant time best case, and linear for degenerate cases. If you insert an object in a set and modify that object in such a way that its ``hash`` result changes, it will be irrecoverable. Most other libraries enforce that only immutable objects should be inserted in sets for this reason, so be careful. */ /*** insert inserts a value in the `Set`. Position is not relevant. Replaces an existing value if the value has the same `hash` key and is `eq` to an existing value. The `hash` function and `eq` function can be overridden in the `Set` constructor. - `stateful` - `chainable` */ /*** retrieve retrieves a value from the `Set` that has the same `hash` key and is `eq` to a given value. `eq` and `hash` can be overridden in the `Set` constructor. - `stateless` */ /**** remove removes a value from the `Set` if it has the same `hash` and is `eq` to the value. throws a `ValueError` if no matching value can be found. - `stateful` - `chainable` */ /**** discard discards a value from the `Set` if it has the same `hash` and is `eq` to the value. Unlike `remove`, does not throw a `ValueError` if no matching value can be found. - `stateful` - `chainable` */ /**** clear removes all values in this set. - `stateful` - `chainable` */ /**** has returns whether a set contains a given value. uses `eq` and `hash` to attempt to find the value in the set. These functions can be overridden in the `Set` constructor. */ /**** find searches all of the values in set for one that is `eq` to a given value. returns that value. throws a `ValueError` if no value can be found. - accepts a value to find - accepts an optional override to the `eq` function - `stateless` */ /**** toIter */ /**** eq */ /**** union augments itself with any values that exist in another iterable. - `stateful` - `chainable` */ /**** intersect - `stateful` - `chainable` */ /**** difference - `stateful` - `chainable` */ /**** unioned returns all elements that are in itself and another iterable. - `stateless` - `chainable` */ /**** intersected returns all values that are in this set and another. - `stateless` - `chainable` */ /**** differenced returns the set of all values that are in this set but not another. - `stateless` - `chainable` */ /**** symmetricDifferenced returns the set of all values that are exactly one set between itself and another. - `stateless` - `chainable` */ /**** isSuperSet returns whether this set contains all of the values in a given container. - `stateless` */ /**** isSubSet returns whether a given container contains all of this set's values. - `stateless` */ /**** added alias of `unioned` - `stateless` - `chainable` */ /**** add alias of `union` - `stateful` - `chainable` */ /**** muled alias of `intersected` - `stateless` - `chainable` */ /**** mul alias of `intersect` - `stateful` - `chainable` */ /**** subed alias of `differenced` - `stateless` - `chainable` */ /**** sub alias of `difference` - `stateful` - `chainable` */ /**** and alias of `intersect` - `stateful` - `chainable` */ /**** anded alias of `intersected` - `stateless` - `chainable` */ /**** or alias of `union` - `stateful` - `chainable` */ /**** ored alias of `unioned` - `stateless` - `chainable` */ /**** xor alias of `symmetricDifferenced` - `stateful` - `chainable` */ /**** xored alias of `symmetricDifferenced` - `stateless` - `chainable` */ /** Functions ========= Functions that operate on sets, or arrays coercible to sets using the polymorphic `toSet` function. */ /*** toSet */ /*** insert */ /*** retrieve */ /*** remove */ /*** discard */ /*** clear */ /*** has */ /*** union */ /*** intersect */ /*** difference */ /*** symetricDifference */ /*** isSuperSet */ /*** isSubSet */ 993 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/set/ProposalK]] to [[OldAPI/set/ProposalK]] /*** Set An unordered collection of unique values. Accepts: - optional ``values`` (may be ``undefined``, or any iterable object, by way of the polymorphic `toIter`) - optional custom ``hash`` relation. - optional custom ``eq`` binary equivalence relation. Inherits member functions from `Iterable`. `Set` operations operate in constant time best case, and linear for degenerate cases. If you insert an object in a set and modify that object in such a way that its ``hash`` result changes, it will be irrecoverable. Most other libraries enforce that only immutable objects should be inserted in sets for this reason, so be careful. */ /*** insert inserts a value in the `Set`. Position is not relevant. Replaces an existing value if the value has the same `hash` key and is `eq` to an existing value. The `hash` function and `eq` function can be overridden in the `Set` constructor. - `stateful` - `chainable` */ /*** retrieve retrieves a value from the `Set` that has the same `hash` key and is `eq` to a given value. `eq` and `hash` can be overridden in the `Set` constructor. - `stateless` */ /**** remove removes a value from the `Set` if it has the same `hash` and is `eq` to the value. throws a `ValueError` if no matching value can be found. - `stateful` - `chainable` */ /**** discard discards a value from the `Set` if it has the same `hash` and is `eq` to the value. Unlike `remove`, does not throw a `ValueError` if no matching value can be found. - `stateful` - `chainable` */ /**** clear removes all values in this set. - `stateful` - `chainable` */ /**** has returns whether a set contains a given value. uses `eq` and `hash` to attempt to find the value in the set. These functions can be overridden in the `Set` constructor. */ /**** find searches all of the values in set for one that is `eq` to a given value. returns that value. throws a `ValueError` if no value can be found. - accepts a value to find - accepts an optional override to the `eq` function - `stateless` */ /**** toIter */ /**** eq */ /**** union augments itself with any values that exist in another iterable. - `stateful` - `chainable` */ /**** intersect - `stateful` - `chainable` */ /**** difference - `stateful` - `chainable` */ /**** unioned returns all elements that are in itself and another iterable. - `stateless` - `chainable` */ /**** intersected returns all values that are in this set and another. - `stateless` - `chainable` */ /**** differenced returns the set of all values that are in this set but not another. - `stateless` - `chainable` */ /**** symmetricDifferenced returns the set of all values that are exactly one set between itself and another. - `stateless` - `chainable` */ /**** isSuperSet returns whether this set contains all of the values in a given container. - `stateless` */ /**** isSubSet returns whether a given container contains all of this set's values. - `stateless` */ /**** added alias of `unioned` - `stateless` - `chainable` */ /**** add alias of `union` - `stateful` - `chainable` */ /**** muled alias of `intersected` - `stateless` - `chainable` */ /**** mul alias of `intersect` - `stateful` - `chainable` */ /**** subed alias of `differenced` - `stateless` - `chainable` */ /**** sub alias of `difference` - `stateful` - `chainable` */ /**** and alias of `intersect` - `stateful` - `chainable` */ /**** anded alias of `intersected` - `stateless` - `chainable` */ /**** or alias of `union` - `stateful` - `chainable` */ /**** ored alias of `unioned` - `stateless` - `chainable` */ /**** xor alias of `symmetricDifferenced` - `stateful` - `chainable` */ /**** xored alias of `symmetricDifferenced` - `stateless` - `chainable` */ /** Functions ========= Functions that operate on sets, or arrays coercible to sets using the polymorphic `toSet` function. */ /*** toSet */ /*** insert */ /*** retrieve */ /*** remove */ /*** discard */ /*** clear */ /*** has */ /*** union */ /*** intersect */ /*** difference */ /*** symetricDifference */ /*** isSuperSet */ /*** isSubSet */ 17 95 2009-04-14T05:23:57Z KrisKowal Added a section for a potential "system" module. See the [[ServerJS/System|System]] proposal. It is as yet undecided whether the "system" object will be a free variable available to all modules, or a module that can be required. 96 2009-09-09T22:13:59Z Dantman 1 1 revision:&#32;Import from https://wiki.mozilla.org/ServerJS See the [[ServerJS/System|System]] proposal. It is as yet undecided whether the "system" object will be a free variable available to all modules, or a module that can be required. 645 2009-09-09T22:29:29Z Dantman 1 moved [[ServerJS/API/system]] to [[CommonJS/API/system]]:&#32;Subpages needed to be enabled See the [[ServerJS/System|System]] proposal. It is as yet undecided whether the "system" object will be a free variable available to all modules, or a module that can be required. 789 2009-09-09T22:40:48Z Dantman 1 Robot: Automated text replacement (-ServerJS +CommonJS) See the [[CommonJS/System|System]] proposal. It is as yet undecided whether the "system" object will be a free variable available to all modules, or a module that can be required. 995 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/system]] to [[OldAPI/system]] See the [[CommonJS/System|System]] proposal. It is as yet undecided whether the "system" object will be a free variable available to all modules, or a module that can be required. 1215 2009-09-12T02:31:32Z Dantman 1 Robot: Automated text replacement (-CommonJS/ +) See the [[System|System]] proposal. It is as yet undecided whether the "system" object will be a free variable available to all modules, or a module that can be required. 1248 2009-09-12T04:41:08Z Dantman 1 Robot: Automated text replacement (-\[\[(.+?)\|\1\]\] +[[\1]]) See the [[System]] proposal. It is as yet undecided whether the "system" object will be a free variable available to all modules, or a module that can be required. 18 97 2009-02-18T07:46:21Z KrisKowal Very early draft of an URL module for ServerJS. /*** resolve returns the real, absolute, fully-qualified URL arrived at from a ``base`` URL following an relative ``rel`` URL. When no ``base`` is provided, resolves the ``rel`` URL relative to the current working directory. - accepts ``rel`` - accepts an optional ``base`` */ /*** relative returns the relative URL between two fully-qualifed paths. */ 98 2009-09-09T22:13:59Z Dantman 1 1 revision:&#32;Import from https://wiki.mozilla.org/ServerJS /*** resolve returns the real, absolute, fully-qualified URL arrived at from a ``base`` URL following an relative ``rel`` URL. When no ``base`` is provided, resolves the ``rel`` URL relative to the current working directory. - accepts ``rel`` - accepts an optional ``base`` */ /*** relative returns the relative URL between two fully-qualifed paths. */ 647 2009-09-09T22:29:29Z Dantman 1 moved [[ServerJS/API/url/ProposalK]] to [[CommonJS/API/url/ProposalK]]:&#32;Subpages needed to be enabled /*** resolve returns the real, absolute, fully-qualified URL arrived at from a ``base`` URL following an relative ``rel`` URL. When no ``base`` is provided, resolves the ``rel`` URL relative to the current working directory. - accepts ``rel`` - accepts an optional ``base`` */ /*** relative returns the relative URL between two fully-qualifed paths. */ 997 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/url/ProposalK]] to [[OldAPI/url/ProposalK]] /*** resolve returns the real, absolute, fully-qualified URL arrived at from a ``base`` URL following an relative ``rel`` URL. When no ``base`` is provided, resolves the ``rel`` URL relative to the current working directory. - accepts ``rel`` - accepts an optional ``base`` */ /*** relative returns the relative URL between two fully-qualifed paths. */ 19 99 2009-02-05T07:54:39Z Ondras New page: == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</t... == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</tt> class. === Binary() object proposition === This is an interface of my proposed Binary object. /** * Creates a new variable holding binary data. * @param {number} initialData Variable amount if intial arguments. Every number represents a byte. * @returns {Binary} */ function Binary(initialData) {}; /** * Converts the binary variable to string by UTF-8 encoding its contents. * @returns {string} */ Binary.prototype.toString = function() {}; /** * Returns a byte value from a given index. * @param {number} index * @returns {number} */ Binary.prototype.getByte = function(index) {}; /** * Sets a byte value at given index. * @param {number} index */ Binary.prototype.setByte = function(index, value) {}; /** * These are essentialy copied from the Array class. */ Binary.prototype.pop = function() {}; Binary.prototype.push = function() {}; Binary.prototype.shift = function() {}; Binary.prototype.unshift = function() {}; /** * Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Calculates MD5 hash * @returns {string} */ Binary.prototype.md5 = function() {}; /** * Calculates SHA1 hash * @returns {string} */ Binary.prototype.sha1 = function() {}; /** * Decodes Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Decodes the Base64 encoded string * @returns {Binary} */ String.prototype.base64decode = function() {}; /** * Converts an UTF-8 encoded string into its binary (one byte per item) variant * @returns {Binary} */ String.prototype.toBinary = function() {}; 100 2009-02-05T07:56:44Z Ondras /* Binary() object proposition */ == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</tt> class. === Binary() object proposition === This is an interface of my proposed Binary object. /** * Creates a new variable holding binary data. * @param {number} initialData Variable amount if intial arguments. Every number represents a byte. * @returns {Binary} */ function Binary(initialData) {}; /** * Returns the number of bytes stored in this structure. * This is intentionally named "getLength" instead of "length" to indicate a method (and not a property). * @returns {number} */ Binary.prototype.getLength = function() {}; /** * Converts the binary variable to string by UTF-8 encoding its contents. * @returns {string} */ Binary.prototype.toString = function() {}; /** * Returns a byte value from a given index. * @param {number} index * @returns {number} */ Binary.prototype.getByte = function(index) {}; /** * Sets a byte value at given index. * @param {number} index */ Binary.prototype.setByte = function(index, value) {}; /** * These are essentialy copied from the Array class. */ Binary.prototype.pop = function() {}; Binary.prototype.push = function() {}; Binary.prototype.shift = function() {}; Binary.prototype.unshift = function() {}; /** * Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Calculates MD5 hash * @returns {string} */ Binary.prototype.md5 = function() {}; /** * Calculates SHA1 hash * @returns {string} */ Binary.prototype.sha1 = function() {}; /** * Decodes Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Decodes the Base64 encoded string * @returns {Binary} */ String.prototype.base64decode = function() {}; /** * Converts an UTF-8 encoded string into its binary (one byte per item) variant * @returns {Binary} */ String.prototype.toBinary = function() {}; 101 2009-02-05T08:22:25Z Ondras /* Binary() object proposition */ == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</tt> class. === Binary() object proposition === This is an interface of my proposed Binary object. I also created a sample implementation, see [[http://tmp.zarovi.cz/binary.js]]. /** * Creates a new variable holding binary data. * @param {number} initialData Variable amount if intial arguments. Every number represents a byte. * @returns {Binary} */ function Binary(initialData) {}; /** * Returns the number of bytes stored in this structure. * This is intentionally named "getLength" instead of "length" to indicate a method (and not a property). * @returns {number} */ Binary.prototype.getLength = function() {}; /** * Converts the binary variable to string by UTF-8 encoding its contents. * @returns {string} */ Binary.prototype.toString = function() {}; /** * Returns a byte value from a given index. * @param {number} index * @returns {number} */ Binary.prototype.getByte = function(index) {}; /** * Sets a byte value at given index. * @param {number} index */ Binary.prototype.setByte = function(index, value) {}; /** * These are essentialy copied from the Array class. */ Binary.prototype.pop = function() {}; Binary.prototype.push = function() {}; Binary.prototype.shift = function() {}; Binary.prototype.unshift = function() {}; /** * Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Calculates MD5 hash * @returns {string} */ Binary.prototype.md5 = function() {}; /** * Calculates SHA1 hash * @returns {string} */ Binary.prototype.sha1 = function() {}; /** * Decodes Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Decodes the Base64 encoded string * @returns {Binary} */ String.prototype.base64decode = function() {}; /** * Converts an UTF-8 encoded string into its binary (one byte per item) variant * @returns {Binary} */ String.prototype.toBinary = function() {}; 102 2009-02-05T08:24:28Z Ondras /* Binary() object proposition */ == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</tt> class. === Binary() object proposition === This is an interface of my proposed Binary object. I also created a sample implementation, see http://tmp.zarovi.cz/binary.js. /** * Creates a new variable holding binary data. * @param {number} initialData Variable amount if intial arguments. Every number represents a byte. * @returns {Binary} */ function Binary(initialData) {}; /** * Returns the number of bytes stored in this structure. * This is intentionally named "getLength" instead of "length" to indicate a method (and not a property). * @returns {number} */ Binary.prototype.getLength = function() {}; /** * Converts the binary variable to string by UTF-8 encoding its contents. * @returns {string} */ Binary.prototype.toString = function() {}; /** * Returns a byte value from a given index. * @param {number} index * @returns {number} */ Binary.prototype.getByte = function(index) {}; /** * Sets a byte value at given index. * @param {number} index */ Binary.prototype.setByte = function(index, value) {}; /** * These are essentialy copied from the Array class. */ Binary.prototype.pop = function() {}; Binary.prototype.push = function() {}; Binary.prototype.shift = function() {}; Binary.prototype.unshift = function() {}; /** * Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Calculates MD5 hash * @returns {string} */ Binary.prototype.md5 = function() {}; /** * Calculates SHA1 hash * @returns {string} */ Binary.prototype.sha1 = function() {}; /** * Decodes Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Decodes the Base64 encoded string * @returns {Binary} */ String.prototype.base64decode = function() {}; /** * Converts an UTF-8 encoded string into its binary (one byte per item) variant * @returns {Binary} */ String.prototype.toBinary = function() {}; [[User:Ondras|Ondras]] 08:24, 5 February 2009 (UTC) 103 2009-02-05T08:28:35Z Ondras /* Binary() object proposition */ == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</tt> class. === Binary() object proposition === This is an interface of my proposed Binary object. I also created a sample implementation, see http://tmp.zarovi.cz/binary.js. /** * Creates a new variable holding binary data. * @param {number} initialData Variable amount if initial arguments. Every number represents a byte. * @returns {Binary} */ function Binary(initialData) {}; /** * Returns the number of bytes stored in this structure. * This is intentionally named "getLength" instead of "length" to indicate a method (and not a property). * @returns {number} */ Binary.prototype.getLength = function() {}; /** * Converts the binary variable to string by UTF-8 encoding its contents. * @returns {string} */ Binary.prototype.toString = function() {}; /** * Returns a byte value from a given index. * @param {number} index * @returns {number} */ Binary.prototype.getByte = function(index) {}; /** * Sets a byte value at given index. * @param {number} index */ Binary.prototype.setByte = function(index, value) {}; /** * These are essentialy copied from the Array class. */ Binary.prototype.pop = function() {}; Binary.prototype.push = function() {}; Binary.prototype.shift = function() {}; Binary.prototype.unshift = function() {}; /** * Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Calculates MD5 hash * @returns {string} */ Binary.prototype.md5 = function() {}; /** * Calculates SHA1 hash * @returns {string} */ Binary.prototype.sha1 = function() {}; /** * Decodes Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Decodes the Base64 encoded string * @returns {Binary} */ String.prototype.base64decode = function() {}; /** * Converts an UTF-8 encoded string into its binary (one byte per item) variant * @returns {Binary} */ String.prototype.toBinary = function() {}; [[User:Ondras|Ondras]] 08:24, 5 February 2009 (UTC) 104 2009-03-05T01:00:49Z Atesgoral Removed duplicate base64encode == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</tt> class. === Binary() object proposition === This is an interface of my proposed Binary object. I also created a sample implementation, see http://tmp.zarovi.cz/binary.js. /** * Creates a new variable holding binary data. * @param {number} initialData Variable amount if initial arguments. Every number represents a byte. * @returns {Binary} */ function Binary(initialData) {}; /** * Returns the number of bytes stored in this structure. * This is intentionally named "getLength" instead of "length" to indicate a method (and not a property). * @returns {number} */ Binary.prototype.getLength = function() {}; /** * Converts the binary variable to string by UTF-8 encoding its contents. * @returns {string} */ Binary.prototype.toString = function() {}; /** * Returns a byte value from a given index. * @param {number} index * @returns {number} */ Binary.prototype.getByte = function(index) {}; /** * Sets a byte value at given index. * @param {number} index */ Binary.prototype.setByte = function(index, value) {}; /** * These are essentialy copied from the Array class. */ Binary.prototype.pop = function() {}; Binary.prototype.push = function() {}; Binary.prototype.shift = function() {}; Binary.prototype.unshift = function() {}; /** * Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Calculates MD5 hash * @returns {string} */ Binary.prototype.md5 = function() {}; /** * Calculates SHA1 hash * @returns {string} */ Binary.prototype.sha1 = function() {}; /** * Decodes the Base64 encoded string * @returns {Binary} */ String.prototype.base64decode = function() {}; /** * Converts an UTF-8 encoded string into its binary (one byte per item) variant * @returns {Binary} */ String.prototype.toBinary = function() {}; [[User:Ondras|Ondras]] 08:24, 5 February 2009 (UTC) 105 2009-04-08T06:47:59Z KrisKowal Reorganized the binary type discussion page to include information from the mailing list and make room for more proposals. = Proposals = # [[ServerJS/Binary/A]] Proposal A from Ondras # [[ServerJS/Binary/B]] Proposal B from Kris Kowal = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/serverjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] 106 2009-04-08T08:02:42Z KrisKowal JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[ServerJS/Binary/A]] Proposal A from Ondras # [[ServerJS/Binary/B]] Proposal B from Kris Kowal = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/serverjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] 107 2009-04-11T08:12:01Z KrisKowal /* Relevant Discussions */ added discussion links JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[ServerJS/Binary/A]] Proposal A from Ondras # [[ServerJS/Binary/B]] Proposal B from Kris Kowal = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/serverjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B [[ServerJS/Encodings|Encodings]] are a related topic. 108 2009-04-22T22:39:58Z MrN /* Prior Art */ JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[ServerJS/Binary/A]] Proposal A from Ondras # [[ServerJS/Binary/B]] Proposal B from Kris Kowal = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/serverjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B [[ServerJS/Encodings|Encodings]] are a related topic. 109 2009-07-30T19:46:15Z Dantman 1 JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[ServerJS/Binary/A]] Proposal A from Ondras # [[ServerJS/Binary/B]] Proposal B from Kris Kowal # [[ServerJS/Binary/C]] Proposal C from Daniel Friesen = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/serverjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B [[ServerJS/Encodings|Encodings]] are a related topic. 110 2009-07-30T22:09:58Z Ashb 7 /* Prior Art */ JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[ServerJS/Binary/A]] Proposal A from Ondras # [[ServerJS/Binary/B]] Proposal B from Kris Kowal # [[ServerJS/Binary/C]] Proposal C from Daniel Friesen = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/serverjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B [[ServerJS/Encodings|Encodings]] are a related topic. 111 2009-09-09T22:14:00Z Dantman 1 12 revisions:&#32;Import from https://wiki.mozilla.org/ServerJS JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[ServerJS/Binary/A]] Proposal A from Ondras # [[ServerJS/Binary/B]] Proposal B from Kris Kowal # [[ServerJS/Binary/C]] Proposal C from Daniel Friesen = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/serverjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B [[ServerJS/Encodings|Encodings]] are a related topic. 649 2009-09-09T22:29:29Z Dantman 1 moved [[ServerJS/Binary]] to [[CommonJS/Binary]]:&#32;Subpages needed to be enabled JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[ServerJS/Binary/A]] Proposal A from Ondras # [[ServerJS/Binary/B]] Proposal B from Kris Kowal # [[ServerJS/Binary/C]] Proposal C from Daniel Friesen = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/serverjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B [[ServerJS/Encodings|Encodings]] are a related topic. 790 2009-09-09T22:40:59Z Dantman 1 Robot: Automated text replacement (-ServerJS +CommonJS) JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[CommonJS/Binary/A]] Proposal A from Ondras # [[CommonJS/Binary/B]] Proposal B from Kris Kowal # [[CommonJS/Binary/C]] Proposal C from Daniel Friesen = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/serverjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B [[CommonJS/Encodings|Encodings]] are a related topic. 827 2009-09-10T02:10:08Z Dantman 1 Robot: Automated text replacement (-serverjs +commonjs) JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[CommonJS/Binary/A]] Proposal A from Ondras # [[CommonJS/Binary/B]] Proposal B from Kris Kowal # [[CommonJS/Binary/C]] Proposal C from Daniel Friesen = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) = Relevant Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B [[CommonJS/Encodings|Encodings]] are a related topic. 860 2009-09-10T02:45:57Z Dantman 1 moved [[CommonJS/Binary]] to [[Binary]] JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[CommonJS/Binary/A]] Proposal A from Ondras # [[CommonJS/Binary/B]] Proposal B from Kris Kowal # [[CommonJS/Binary/C]] Proposal C from Daniel Friesen = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) = Relevant Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B [[CommonJS/Encodings|Encodings]] are a related topic. 862 2009-09-10T02:46:36Z Dantman 1 JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal # [[Binary/C]] Proposal C from Daniel Friesen = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) = Relevant Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B [[Encodings]] are a related topic. 867 2009-09-10T02:47:55Z Dantman 1 moved [[Binary]] to [[CommonJS/Binary]] over redirect JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal # [[Binary/C]] Proposal C from Daniel Friesen = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) = Relevant Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B [[Encodings]] are a related topic. 869 2009-09-10T02:48:08Z Dantman 1 moved [[CommonJS/Binary]] to [[Binary]] over redirect JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. = Proposals = # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal # [[Binary/C]] Proposal C from Daniel Friesen = Prior Art = * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) = Relevant Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B [[Encodings]] are a related topic. 1194 2009-09-12T01:32:30Z KrisKowal 6 Cataloged relevant discussions. '''STATUS: PROPOSALS, DISCUSSION''' JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. == Proposals == # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal # [[Binary/C]] Proposal C from Daniel Friesen == Prior Art == * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B * [http://groups.google.com/group/commonjs/browse_thread/thread/0680b464e775726c Binary/C - range for memcopy] * [http://groups.google.com/group/commonjs/browse_thread/thread/8a0d9db68e81baae ByteString / ByteArray duality] * [http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 Alternate binary proposal] regarding [[Binary/C]] [[Encodings]] are a related topic. 1540 2009-10-03T15:56:26Z Ashb 7 '''STATUS: PROPOSALS, DISCUSSION''' JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. == Proposals == # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal (implemented by a few platforms) # [[Binary/C]] Proposal C from Daniel Friesen == Prior Art == * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B * [http://groups.google.com/group/commonjs/browse_thread/thread/0680b464e775726c Binary/C - range for memcopy] * [http://groups.google.com/group/commonjs/browse_thread/thread/8a0d9db68e81baae ByteString / ByteArray duality] * [http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 Alternate binary proposal] regarding [[Binary/C]] [[Encodings]] are a related topic. 1763 2009-11-25T09:27:14Z KrisKowal 6 first draft of binary/d posted '''STATUS: PROPOSALS, DISCUSSION''' JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. == Proposals == # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal (implemented by a few platforms) # [[Binary/C]] Proposal C from Daniel Friesen # [[Binary/D]] Proposal D from Kris Kowal (based on [[Binary/B]], -array-comprehsiveness, +bits, +radix-encoding) == Prior Art == * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B * [http://groups.google.com/group/commonjs/browse_thread/thread/0680b464e775726c Binary/C - range for memcopy] * [http://groups.google.com/group/commonjs/browse_thread/thread/8a0d9db68e81baae ByteString / ByteArray duality] * [http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 Alternate binary proposal] regarding [[Binary/C]] [[Encodings]] are a related topic. 1765 2009-11-26T21:29:30Z Alexandre Morgaut 40 /* Prior Art */ '''STATUS: PROPOSALS, DISCUSSION''' JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. == Proposals == # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal (implemented by a few platforms) # [[Binary/C]] Proposal C from Daniel Friesen # [[Binary/D]] Proposal D from Kris Kowal (based on [[Binary/B]], -array-comprehsiveness, +bits, +radix-encoding) == Prior Art == * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) * [http://www.w3.org/TR/FileAPI/ W3C File API] == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B * [http://groups.google.com/group/commonjs/browse_thread/thread/0680b464e775726c Binary/C - range for memcopy] * [http://groups.google.com/group/commonjs/browse_thread/thread/8a0d9db68e81baae ByteString / ByteArray duality] * [http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 Alternate binary proposal] regarding [[Binary/C]] [[Encodings]] are a related topic. 1767 2009-11-27T12:32:00Z Alexandre Morgaut 40 /* Prior Art */ '''STATUS: PROPOSALS, DISCUSSION''' JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. == Proposals == # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal (implemented by a few platforms) # [[Binary/C]] Proposal C from Daniel Friesen # [[Binary/D]] Proposal D from Kris Kowal (based on [[Binary/B]], -array-comprehsiveness, +bits, +radix-encoding) == Prior Art == * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) * [http://www.w3.org/TR/FileAPI/ W3C File API] (blob, FileBlob, readAsBinaryString, readAsDateUrl) == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B * [http://groups.google.com/group/commonjs/browse_thread/thread/0680b464e775726c Binary/C - range for memcopy] * [http://groups.google.com/group/commonjs/browse_thread/thread/8a0d9db68e81baae ByteString / ByteArray duality] * [http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 Alternate binary proposal] regarding [[Binary/C]] [[Encodings]] are a related topic. 1768 2009-11-27T12:32:19Z Alexandre Morgaut 40 /* Prior Art */ '''STATUS: PROPOSALS, DISCUSSION''' JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. == Proposals == # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal (implemented by a few platforms) # [[Binary/C]] Proposal C from Daniel Friesen # [[Binary/D]] Proposal D from Kris Kowal (based on [[Binary/B]], -array-comprehsiveness, +bits, +radix-encoding) == Prior Art == * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) * [http://www.w3.org/TR/FileAPI/ W3C File API] (blob, FileBlob, readAsBinaryString, readAsDataUrl) == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B * [http://groups.google.com/group/commonjs/browse_thread/thread/0680b464e775726c Binary/C - range for memcopy] * [http://groups.google.com/group/commonjs/browse_thread/thread/8a0d9db68e81baae ByteString / ByteArray duality] * [http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 Alternate binary proposal] regarding [[Binary/C]] [[Encodings]] are a related topic. 1949 2010-01-07T07:34:50Z Mob 56 /* Prior Art */ '''STATUS: PROPOSALS, DISCUSSION''' JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. == Proposals == # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal (implemented by a few platforms) # [[Binary/C]] Proposal C from Daniel Friesen # [[Binary/D]] Proposal D from Kris Kowal (based on [[Binary/B]], -array-comprehsiveness, +bits, +radix-encoding) == Prior Art == * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) * [http://www.w3.org/TR/FileAPI/ W3C File API] (blob, FileBlob, readAsBinaryString, readAsDataUrl) == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B * [http://groups.google.com/group/commonjs/browse_thread/thread/0680b464e775726c Binary/C - range for memcopy] * [http://groups.google.com/group/commonjs/browse_thread/thread/8a0d9db68e81baae ByteString / ByteArray duality] * [http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 Alternate binary proposal] regarding [[Binary/C]] [[Encodings]] are a related topic. 1997 2010-01-17T08:09:21Z KrisKowal 6 /* Proposals */ added Binary/E '''STATUS: PROPOSALS, DISCUSSION''' JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. == Proposals == # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal (implemented by a few platforms) # [[Binary/C]] Proposal C from Daniel Friesen # [[Binary/D]] Proposal D from Kris Kowal (based on [[Binary/B]], -array-comprehsiveness, +bits, +radix-encoding) # [[Binary/E]] Proposal E (based on [[Binary/D]] with byte string <nowiki>[[Get]]</nowiki> returning Number instead of ByteString, +Binary base type, -bits, -radix-encoding, -patching) == Prior Art == * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) * [http://www.w3.org/TR/FileAPI/ W3C File API] (blob, FileBlob, readAsBinaryString, readAsDataUrl) == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B * [http://groups.google.com/group/commonjs/browse_thread/thread/0680b464e775726c Binary/C - range for memcopy] * [http://groups.google.com/group/commonjs/browse_thread/thread/8a0d9db68e81baae ByteString / ByteArray duality] * [http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 Alternate binary proposal] regarding [[Binary/C]] [[Encodings]] are a related topic. 2033 2010-01-25T12:57:25Z Aristid 46 /* Proposals */ add Lite '''STATUS: PROPOSALS, DISCUSSION''' JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. == Proposals == # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal (implemented by a few platforms) # [[Binary/C]] Proposal C from Daniel Friesen # [[Binary/D]] Proposal D from Kris Kowal (based on [[Binary/B]], -array-comprehsiveness, +bits, +radix-encoding) # [[Binary/E]] Proposal E (based on [[Binary/D]] with byte string <nowiki>[[Get]]</nowiki> returning Number instead of ByteString, +Binary base type, -bits, -radix-encoding, -patching) # [[Binary/Lite]] Proposal "Lite" from Ondras == Prior Art == * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) * [http://www.w3.org/TR/FileAPI/ W3C File API] (blob, FileBlob, readAsBinaryString, readAsDataUrl) == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B * [http://groups.google.com/group/commonjs/browse_thread/thread/0680b464e775726c Binary/C - range for memcopy] * [http://groups.google.com/group/commonjs/browse_thread/thread/8a0d9db68e81baae ByteString / ByteArray duality] * [http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 Alternate binary proposal] regarding [[Binary/C]] [[Encodings]] are a related topic. 2126 2010-02-22T00:07:51Z KrisKowal 6 /* Proposals */ added Binary/F to the index '''STATUS: PROPOSALS, DISCUSSION''' JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. == Proposals == # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal (implemented by a few platforms) # [[Binary/C]] Proposal C from Daniel Friesen # [[Binary/D]] Proposal D from Kris Kowal (based on [[Binary/B]], -array-comprehsiveness, +bits, +radix-encoding) # [[Binary/E]] Proposal E (based on [[Binary/D]] with byte string <nowiki>[[Get]]</nowiki> returning Number instead of ByteString, +Binary base type, -bits, -radix-encoding, -patching) # [[Binary/Lite]] Proposal "Lite" from Ondras (single Binary type -charsets) # [[Binary/F]] Proposal F (based on [[Binary/E]] but viciously trimmed, -ByteString, s/ByteArray/Buffer/ -flexible length) == Prior Art == * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) * [http://www.w3.org/TR/FileAPI/ W3C File API] (blob, FileBlob, readAsBinaryString, readAsDataUrl) == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B * [http://groups.google.com/group/commonjs/browse_thread/thread/0680b464e775726c Binary/C - range for memcopy] * [http://groups.google.com/group/commonjs/browse_thread/thread/8a0d9db68e81baae ByteString / ByteArray duality] * [http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 Alternate binary proposal] regarding [[Binary/C]] [[Encodings]] are a related topic. 2772 2010-05-13T19:12:31Z Markm 54 /* Relevant Discussions */ '''STATUS: PROPOSALS, DISCUSSION''' JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. == Proposals == # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal (implemented by a few platforms) # [[Binary/C]] Proposal C from Daniel Friesen # [[Binary/D]] Proposal D from Kris Kowal (based on [[Binary/B]], -array-comprehsiveness, +bits, +radix-encoding) # [[Binary/E]] Proposal E (based on [[Binary/D]] with byte string <nowiki>[[Get]]</nowiki> returning Number instead of ByteString, +Binary base type, -bits, -radix-encoding, -patching) # [[Binary/Lite]] Proposal "Lite" from Ondras (single Binary type -charsets) # [[Binary/F]] Proposal F (based on [[Binary/E]] but viciously trimmed, -ByteString, s/ByteArray/Buffer/ -flexible length) == Prior Art == * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) * [http://www.w3.org/TR/FileAPI/ W3C File API] (blob, FileBlob, readAsBinaryString, readAsDataUrl) == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B * [http://groups.google.com/group/commonjs/browse_thread/thread/0680b464e775726c Binary/C - range for memcopy] * [http://groups.google.com/group/commonjs/browse_thread/thread/8a0d9db68e81baae ByteString / ByteArray duality] * [http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 Alternate binary proposal] regarding [[Binary/C]] * [http://wiki.ecmascript.org/doku.php?id=strawman:typed_arrays Typed Arrays strawman on the EcmaScript wiki] which cites Khronos's proposed [https://cvs.khronos.org/svn/repos/registry/trunk/public/webgl/doc/spec/TypedArray-spec.html TypedArray spec] as its primary source. [[Encodings]] are a related topic. 20 112 2009-04-08T02:22:40Z KrisKowal Movied first proposal for the binary API to a subpage. == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</tt> class. === Binary() object proposition === This is an interface of my proposed Binary object. I also created a sample implementation, see http://tmp.zarovi.cz/binary.js. /** * Creates a new variable holding binary data. * @param {number} initialData Variable amount if initial arguments. Every number represents a byte. * @returns {Binary} */ function Binary(initialData) {}; /** * Returns the number of bytes stored in this structure. * This is intentionally named "getLength" instead of "length" to indicate a method (and not a property). * @returns {number} */ Binary.prototype.getLength = function() {}; /** * Converts the binary variable to string by UTF-8 encoding its contents. * @returns {string} */ Binary.prototype.toString = function() {}; /** * Returns a byte value from a given index. * @param {number} index * @returns {number} */ Binary.prototype.getByte = function(index) {}; /** * Sets a byte value at given index. * @param {number} index */ Binary.prototype.setByte = function(index, value) {}; /** * These are essentialy copied from the Array class. */ Binary.prototype.pop = function() {}; Binary.prototype.push = function() {}; Binary.prototype.shift = function() {}; Binary.prototype.unshift = function() {}; /** * Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Calculates MD5 hash * @returns {string} */ Binary.prototype.md5 = function() {}; /** * Calculates SHA1 hash * @returns {string} */ Binary.prototype.sha1 = function() {}; /** * Decodes the Base64 encoded string * @returns {Binary} */ String.prototype.base64decode = function() {}; /** * Converts an UTF-8 encoded string into its binary (one byte per item) variant * @returns {Binary} */ String.prototype.toBinary = function() {}; [[User:Ondras|Ondras]] 08:24, 5 February 2009 (UTC) 113 2009-09-09T22:14:00Z Dantman 1 1 revision:&#32;Import from https://wiki.mozilla.org/ServerJS == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</tt> class. === Binary() object proposition === This is an interface of my proposed Binary object. I also created a sample implementation, see http://tmp.zarovi.cz/binary.js. /** * Creates a new variable holding binary data. * @param {number} initialData Variable amount if initial arguments. Every number represents a byte. * @returns {Binary} */ function Binary(initialData) {}; /** * Returns the number of bytes stored in this structure. * This is intentionally named "getLength" instead of "length" to indicate a method (and not a property). * @returns {number} */ Binary.prototype.getLength = function() {}; /** * Converts the binary variable to string by UTF-8 encoding its contents. * @returns {string} */ Binary.prototype.toString = function() {}; /** * Returns a byte value from a given index. * @param {number} index * @returns {number} */ Binary.prototype.getByte = function(index) {}; /** * Sets a byte value at given index. * @param {number} index */ Binary.prototype.setByte = function(index, value) {}; /** * These are essentialy copied from the Array class. */ Binary.prototype.pop = function() {}; Binary.prototype.push = function() {}; Binary.prototype.shift = function() {}; Binary.prototype.unshift = function() {}; /** * Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Calculates MD5 hash * @returns {string} */ Binary.prototype.md5 = function() {}; /** * Calculates SHA1 hash * @returns {string} */ Binary.prototype.sha1 = function() {}; /** * Decodes the Base64 encoded string * @returns {Binary} */ String.prototype.base64decode = function() {}; /** * Converts an UTF-8 encoded string into its binary (one byte per item) variant * @returns {Binary} */ String.prototype.toBinary = function() {}; [[User:Ondras|Ondras]] 08:24, 5 February 2009 (UTC) 651 2009-09-09T22:29:29Z Dantman 1 moved [[ServerJS/Binary/A]] to [[CommonJS/Binary/A]]:&#32;Subpages needed to be enabled == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</tt> class. === Binary() object proposition === This is an interface of my proposed Binary object. I also created a sample implementation, see http://tmp.zarovi.cz/binary.js. /** * Creates a new variable holding binary data. * @param {number} initialData Variable amount if initial arguments. Every number represents a byte. * @returns {Binary} */ function Binary(initialData) {}; /** * Returns the number of bytes stored in this structure. * This is intentionally named "getLength" instead of "length" to indicate a method (and not a property). * @returns {number} */ Binary.prototype.getLength = function() {}; /** * Converts the binary variable to string by UTF-8 encoding its contents. * @returns {string} */ Binary.prototype.toString = function() {}; /** * Returns a byte value from a given index. * @param {number} index * @returns {number} */ Binary.prototype.getByte = function(index) {}; /** * Sets a byte value at given index. * @param {number} index */ Binary.prototype.setByte = function(index, value) {}; /** * These are essentialy copied from the Array class. */ Binary.prototype.pop = function() {}; Binary.prototype.push = function() {}; Binary.prototype.shift = function() {}; Binary.prototype.unshift = function() {}; /** * Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Calculates MD5 hash * @returns {string} */ Binary.prototype.md5 = function() {}; /** * Calculates SHA1 hash * @returns {string} */ Binary.prototype.sha1 = function() {}; /** * Decodes the Base64 encoded string * @returns {Binary} */ String.prototype.base64decode = function() {}; /** * Converts an UTF-8 encoded string into its binary (one byte per item) variant * @returns {Binary} */ String.prototype.toBinary = function() {}; [[User:Ondras|Ondras]] 08:24, 5 February 2009 (UTC) 826 2009-09-09T23:29:25Z Dantman 1 == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</tt> class. === Binary() object proposition === This is an interface of my proposed Binary object. I also created a sample implementation, see http://tmp.zarovi.cz/binary.js. <source> /** * Creates a new variable holding binary data. * @param {number} initialData Variable amount if initial arguments. Every number represents a byte. * @returns {Binary} */ function Binary(initialData) {}; /** * Returns the number of bytes stored in this structure. * This is intentionally named "getLength" instead of "length" to indicate a method (and not a property). * @returns {number} */ Binary.prototype.getLength = function() {}; /** * Converts the binary variable to string by UTF-8 encoding its contents. * @returns {string} */ Binary.prototype.toString = function() {}; /** * Returns a byte value from a given index. * @param {number} index * @returns {number} */ Binary.prototype.getByte = function(index) {}; /** * Sets a byte value at given index. * @param {number} index */ Binary.prototype.setByte = function(index, value) {}; /** * These are essentialy copied from the Array class. */ Binary.prototype.pop = function() {}; Binary.prototype.push = function() {}; Binary.prototype.shift = function() {}; Binary.prototype.unshift = function() {}; /** * Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Calculates MD5 hash * @returns {string} */ Binary.prototype.md5 = function() {}; /** * Calculates SHA1 hash * @returns {string} */ Binary.prototype.sha1 = function() {}; /** * Decodes the Base64 encoded string * @returns {Binary} */ String.prototype.base64decode = function() {}; /** * Converts an UTF-8 encoded string into its binary (one byte per item) variant * @returns {Binary} */ String.prototype.toBinary = function() {}; [[User:Ondras|Ondras]] 08:24, 5 February 2009 (UTC) 871 2009-09-10T02:48:08Z Dantman 1 moved [[CommonJS/Binary/A]] to [[Binary/A]] == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</tt> class. === Binary() object proposition === This is an interface of my proposed Binary object. I also created a sample implementation, see http://tmp.zarovi.cz/binary.js. <source> /** * Creates a new variable holding binary data. * @param {number} initialData Variable amount if initial arguments. Every number represents a byte. * @returns {Binary} */ function Binary(initialData) {}; /** * Returns the number of bytes stored in this structure. * This is intentionally named "getLength" instead of "length" to indicate a method (and not a property). * @returns {number} */ Binary.prototype.getLength = function() {}; /** * Converts the binary variable to string by UTF-8 encoding its contents. * @returns {string} */ Binary.prototype.toString = function() {}; /** * Returns a byte value from a given index. * @param {number} index * @returns {number} */ Binary.prototype.getByte = function(index) {}; /** * Sets a byte value at given index. * @param {number} index */ Binary.prototype.setByte = function(index, value) {}; /** * These are essentialy copied from the Array class. */ Binary.prototype.pop = function() {}; Binary.prototype.push = function() {}; Binary.prototype.shift = function() {}; Binary.prototype.unshift = function() {}; /** * Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Calculates MD5 hash * @returns {string} */ Binary.prototype.md5 = function() {}; /** * Calculates SHA1 hash * @returns {string} */ Binary.prototype.sha1 = function() {}; /** * Decodes the Base64 encoded string * @returns {Binary} */ String.prototype.base64decode = function() {}; /** * Converts an UTF-8 encoded string into its binary (one byte per item) variant * @returns {Binary} */ String.prototype.toBinary = function() {}; [[User:Ondras|Ondras]] 08:24, 5 February 2009 (UTC) 21 114 2009-04-08T07:54:04Z KrisKowal Created a proposal for binary data. = Proposal B = All platforms support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, or undefined. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) == Philosophy == This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. The ByteString constructor accepts: * ByteString() * ByteString(byteString) * ByteString(byteArray) * ByteString(array) * ByteString(string, codecModuleId) The ByteString object has the following methods: * encode(string, codecModuleId) ByteString instances support the following: * immutable length property * toByteArray() * toArray() * toString(codecModuleId) * decode(codecModuleId) * hash(digestModuleId) * compress(compressionModuleId) * indexOf(Number or ByteString) * lastIndexOf(Number or ByteString) * charAt(offset) -> ByteString * charCodeAt(offset) -> Number * byteAt(offset) -> Number (same as charCodeAt) * split(Number or ByteString) -> Array of ByteStrings * substring(first, last) or substring(first) to the end * substr(first, length) or substr(length) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() returns itself ByteString does not implement toUpperCase() or toLowerCase(). == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. The ByteArray constructor has the following forms: * ByteArray() * ByteArray(length) * ByteArray(byteArray) * ByteArray(byteString) * ByteArray(array) * ByteString(string, codecModuleId) Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. The ByteArray object has the following methods: * encode(string, codecModuleId) ByteArray instances support the following: * mutable length property ** extending a byte array fills the new entries with 0. * toByteString() * toArray() * toString(codecModuleId) * decode(codecModuleId) returns String * hash(digestModuleId) * compress(compressionModuleId) * concat(iterable) * join(byteString byteArray or Number) * pop() * push(…variadic Numbers…) * shift() * unshift(…variadic Numbers…) * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() returns itself * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: * toByteArray(codecModuleId) * toByteString(codecModuleId) == Array == The Array prototype will be extended with the following members: * toByteArray(codecModuleId) * toByteString(codecModuleId) == Conventions == "codecModuleId" always defaults to "utf8". Codec modules must always export at least "encode", and "decode" methods to support byte strings and arrays. Digest modules must always export a "hash" method that accepts Array, ByteArray, or ByteString objects as their argument. Compression modules must always export a "compress" method. 115 2009-04-08T07:54:52Z KrisKowal All platforms support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, or undefined. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) == Philosophy == This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. The ByteString constructor accepts: * ByteString() * ByteString(byteString) * ByteString(byteArray) * ByteString(array) * ByteString(string, codecModuleId) The ByteString object has the following methods: * encode(string, codecModuleId) ByteString instances support the following: * immutable length property * toByteArray() * toArray() * toString(codecModuleId) * decode(codecModuleId) * hash(digestModuleId) * compress(compressionModuleId) * indexOf(Number or ByteString) * lastIndexOf(Number or ByteString) * charAt(offset) -> ByteString * charCodeAt(offset) -> Number * byteAt(offset) -> Number (same as charCodeAt) * split(Number or ByteString) -> Array of ByteStrings * substring(first, last) or substring(first) to the end * substr(first, length) or substr(length) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() returns itself ByteString does not implement toUpperCase() or toLowerCase(). == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. The ByteArray constructor has the following forms: * ByteArray() * ByteArray(length) * ByteArray(byteArray) * ByteArray(byteString) * ByteArray(array) * ByteString(string, codecModuleId) Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. The ByteArray object has the following methods: * encode(string, codecModuleId) ByteArray instances support the following: * mutable length property ** extending a byte array fills the new entries with 0. * toByteString() * toArray() * toString(codecModuleId) * decode(codecModuleId) returns String * hash(digestModuleId) * compress(compressionModuleId) * concat(iterable) * join(byteString byteArray or Number) * pop() * push(…variadic Numbers…) * shift() * unshift(…variadic Numbers…) * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() returns itself * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: * toByteArray(codecModuleId) * toByteString(codecModuleId) == Array == The Array prototype will be extended with the following members: * toByteArray(codecModuleId) * toByteString(codecModuleId) == Conventions == "codecModuleId" always defaults to "utf8". Codec modules must always export at least "encode", and "decode" methods to support byte strings and arrays. Digest modules must always export a "hash" method that accepts Array, ByteArray, or ByteString objects as their argument. Compression modules must always export a "compress" method. 116 2009-04-11T06:14:58Z KrisKowal Updated according to feedback from the list. All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) == Philosophy == This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a codec manager module, and may in turn use a system level codec or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. The ByteString constructor accepts: * ByteString() * ByteString(byteString) * ByteString(byteArray) * ByteString(array) * ByteString(string, codec) ByteString instances support the following: * immutable length property * toByteArray() -> byte for byte * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> copy * toByteString(sourceCodec, targetCodec) -> transcoded * toArray() -> byte value array * toArray(codec) -> decoded code point array * toString() -> a representation like "[ByteString 10]" * toString(codec) -> decoded * indexOf(byte:Number|ByteString|ByteArray) * indexOf(byte:Number|ByteString|ByteArray, start:Number) * indexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * lastIndexOf(byte:Number|ByteString|ByteArray) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * byteAt(offset) -> Number (same as charCodeAt) * charCodeAt(offset:Number) -> Number * charAt(offset:Number) -> byte:ByteString * split(delimiter:Number|ByteString) -> Array of ByteStrings * split(delimiter:Number|ByteString, count:Number) -> Array of ByteStrings * slice() * slice(begin) * slice(begin, end) * substr(start) * substr(start, length) * substring(first) * substring(first, last) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a codec. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. The ByteArray constructor has the following forms: * ByteArray() * ByteArray(length) * ByteArray(byteArray) * ByteArray(byteString) * ByteArray(array) * ByteString(string, codec) Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. ByteArray instances support the following: * mutable length property ** extending a byte array fills the new entries with 0. * toArray() -> an array of the byte values * toArray(codec) -> an array of the code points, decoded * toString() -> a string representation like "[ByteArray 10]" * toString(codec) - decoded * toByteArray() -> just a copy * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> byte for byte * toByteString(sourceCodec, targetCodec) -> transcoded * concat(other:ByteArray|ByteString|Array) * join(delimiter:ByteArray|ByteString|Array) * pop() -> byte:Number * push(...variadic Numbers...)-> count:Number * shift() -> byte:Number * unshift(...variadic Numbers...) -> count:Number * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: * toByteArray(codec) * toByteString(codec) * charCodes() -> Array of charcode:Number == Array == The Array prototype will be extended with the following members: * toByteArray(codec) * toByteString(codec) == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets. 117 2009-04-11T08:13:24Z KrisKowal Added a link to the corresponding discussion and organized the headings. All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a codec manager module, and may in turn use a system level codec or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. = Specification = == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. The ByteString constructor accepts: * ByteString() * ByteString(byteString) * ByteString(byteArray) * ByteString(array) * ByteString(string, codec) ByteString instances support the following: * immutable length property * toByteArray() -> byte for byte * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> copy * toByteString(sourceCodec, targetCodec) -> transcoded * toArray() -> byte value array * toArray(codec) -> decoded code point array * toString() -> a representation like "[ByteString 10]" * toString(codec) -> decoded * indexOf(byte:Number|ByteString|ByteArray) * indexOf(byte:Number|ByteString|ByteArray, start:Number) * indexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * lastIndexOf(byte:Number|ByteString|ByteArray) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * byteAt(offset) -> Number (same as charCodeAt) * charCodeAt(offset:Number) -> Number * charAt(offset:Number) -> byte:ByteString * split(delimiter:Number|ByteString) -> Array of ByteStrings * split(delimiter:Number|ByteString, count:Number) -> Array of ByteStrings * slice() * slice(begin) * slice(begin, end) * substr(start) * substr(start, length) * substring(first) * substring(first, last) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a codec. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. The ByteArray constructor has the following forms: * ByteArray() * ByteArray(length) * ByteArray(byteArray) * ByteArray(byteString) * ByteArray(array) * ByteString(string, codec) Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. ByteArray instances support the following: * mutable length property ** extending a byte array fills the new entries with 0. * toArray() -> an array of the byte values * toArray(codec) -> an array of the code points, decoded * toString() -> a string representation like "[ByteArray 10]" * toString(codec) - decoded * toByteArray() -> just a copy * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> byte for byte * toByteString(sourceCodec, targetCodec) -> transcoded * concat(other:ByteArray|ByteString|Array) * join(delimiter:ByteArray|ByteString|Array) * pop() -> byte:Number * push(...variadic Numbers...)-> count:Number * shift() -> byte:Number * unshift(...variadic Numbers...) -> count:Number * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: * toByteArray(codec) * toByteString(codec) * charCodes() -> Array of charcode:Number == Array == The Array prototype will be extended with the following members: * toByteArray(codec) * toByteString(codec) == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] 118 2009-04-11T12:15:08Z MrN /* ByteString */ use definition list for constructors All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a codec manager module, and may in turn use a system level codec or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. = Specification = == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. The ByteString constructor: ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, codec) : Convert a string. The ByteString will contain string encoded with codec. ByteString instances support the following: * immutable length property * toByteArray() -> byte for byte * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> copy * toByteString(sourceCodec, targetCodec) -> transcoded * toArray() -> byte value array * toArray(codec) -> decoded code point array * toString() -> a representation like "[ByteString 10]" * toString(codec) -> decoded * indexOf(byte:Number|ByteString|ByteArray) * indexOf(byte:Number|ByteString|ByteArray, start:Number) * indexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * lastIndexOf(byte:Number|ByteString|ByteArray) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * byteAt(offset) -> Number (same as charCodeAt) * charCodeAt(offset:Number) -> Number * charAt(offset:Number) -> byte:ByteString * split(delimiter:Number|ByteString) -> Array of ByteStrings * split(delimiter:Number|ByteString, count:Number) -> Array of ByteStrings * slice() * slice(begin) * slice(begin, end) * substr(start) * substr(start, length) * substring(first) * substring(first, last) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a codec. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. The ByteArray constructor has the following forms: * ByteArray() * ByteArray(length) * ByteArray(byteArray) * ByteArray(byteString) * ByteArray(array) * ByteString(string, codec) Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. ByteArray instances support the following: * mutable length property ** extending a byte array fills the new entries with 0. * toArray() -> an array of the byte values * toArray(codec) -> an array of the code points, decoded * toString() -> a string representation like "[ByteArray 10]" * toString(codec) - decoded * toByteArray() -> just a copy * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> byte for byte * toByteString(sourceCodec, targetCodec) -> transcoded * concat(other:ByteArray|ByteString|Array) * join(delimiter:ByteArray|ByteString|Array) * pop() -> byte:Number * push(...variadic Numbers...)-> count:Number * shift() -> byte:Number * unshift(...variadic Numbers...) -> count:Number * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: * toByteArray(codec) * toByteString(codec) * charCodes() -> Array of charcode:Number == Array == The Array prototype will be extended with the following members: * toByteArray(codec) * toByteString(codec) == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] 119 2009-04-11T12:31:31Z MrN /* Specification */ add sub-headings All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a codec manager module, and may in turn use a system level codec or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. = Specification = == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, codec) : Convert a string. The ByteString will contain string encoded with codec. === Instance properties === * immutable length property === Instance methods (in prototype) === * toByteArray() -> byte for byte * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> copy * toByteString(sourceCodec, targetCodec) -> transcoded * toArray() -> byte value array * toArray(codec) -> decoded code point array * toString() -> a representation like "[ByteString 10]" * toString(codec) -> decoded * indexOf(byte:Number|ByteString|ByteArray) * indexOf(byte:Number|ByteString|ByteArray, start:Number) * indexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * lastIndexOf(byte:Number|ByteString|ByteArray) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * byteAt(offset) -> Number (same as charCodeAt) * charCodeAt(offset:Number) -> Number * charAt(offset:Number) -> byte:ByteString * split(delimiter:Number|ByteString) -> Array of ByteStrings * split(delimiter:Number|ByteString, count:Number) -> Array of ByteStrings * slice() * slice(begin) * slice(begin, end) * substr(start) * substr(start, length) * substring(first) * substring(first, last) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a codec. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === * ByteArray() * ByteArray(length) * ByteArray(byteArray) * ByteArray(byteString) * ByteArray(array) * ByteString(string, codec) Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === * mutable length property ** extending a byte array fills the new entries with 0. === Instance methods (in prototype) === * toArray() -> an array of the byte values * toArray(codec) -> an array of the code points, decoded * toString() -> a string representation like "[ByteArray 10]" * toString(codec) - decoded * toByteArray() -> just a copy * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> byte for byte * toByteString(sourceCodec, targetCodec) -> transcoded * concat(other:ByteArray|ByteString|Array) * join(delimiter:ByteArray|ByteString|Array) * pop() -> byte:Number * push(...variadic Numbers...)-> count:Number * shift() -> byte:Number * unshift(...variadic Numbers...) -> count:Number * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: * toByteArray(codec) * toByteString(codec) * charCodes() -> Array of charcode:Number == Array == The Array prototype will be extended with the following members: * toByteArray(codec) * toByteString(codec) == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] 120 2009-04-11T12:42:15Z MrN /* Specification */ convert more methods to a definition list (ultimately all methods should be converted like this) All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a codec manager module, and may in turn use a system level codec or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. = Specification = == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, codec) : Convert a string. The ByteString will contain string encoded with codec. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCodec, targetCodec) : Returns a transcoded copy in a ByteArray. ; toByteString() : Copy. ; toByteString(sourceCodec, targetCodec) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(codec) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. ; toString(codec) : ''CONTROVERSIAL'' Returns the decoded ByteArray as a string. * indexOf(byte:Number|ByteString|ByteArray) * indexOf(byte:Number|ByteString|ByteArray, start:Number) * indexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * lastIndexOf(byte:Number|ByteString|ByteArray) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * byteAt(offset) -> Number (same as charCodeAt) * charCodeAt(offset:Number) -> Number * charAt(offset:Number) -> byte:ByteString * split(delimiter:Number|ByteString) -> Array of ByteStrings * split(delimiter:Number|ByteString, count:Number) -> Array of ByteStrings * slice() * slice(begin) * slice(begin, end) * substr(start) * substr(start, length) * substring(first) * substring(first, last) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a codec. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === * ByteArray() * ByteArray(length) * ByteArray(byteArray) * ByteArray(byteString) * ByteArray(array) * ByteString(string, codec) Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === * mutable length property ** extending a byte array fills the new entries with 0. === Instance methods (in prototype) === * toArray() -> an array of the byte values * toArray(codec) -> an array of the code points, decoded * toString() -> a string representation like "[ByteArray 10]" * toString(codec) - decoded * toByteArray() -> just a copy * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> byte for byte * toByteString(sourceCodec, targetCodec) -> transcoded * concat(other:ByteArray|ByteString|Array) * join(delimiter:ByteArray|ByteString|Array) * pop() -> byte:Number * push(...variadic Numbers...)-> count:Number * shift() -> byte:Number * unshift(...variadic Numbers...) -> count:Number * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: * toByteArray(codec) * toByteString(codec) * charCodes() -> Array of charcode:Number == Array == The Array prototype will be extended with the following members: * toByteArray(codec) * toByteString(codec) == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] 121 2009-04-11T13:20:34Z MrN /* Specification */ more definition lists All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a codec manager module, and may in turn use a system level codec or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. = Specification = == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, codec) : Convert a string. The ByteString will contain string encoded with codec. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCodec, targetCodec) : Returns a transcoded copy in a ByteArray. ; toByteString() : Copy. ; toByteString(sourceCodec, targetCodec) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(codec) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. ; toString(codec) : ''CONTROVERSIAL'' Returns the decoded ByteArray as a string. * indexOf(byte:Number|ByteString|ByteArray) * indexOf(byte:Number|ByteString|ByteArray, start:Number) * indexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * lastIndexOf(byte:Number|ByteString|ByteArray) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * byteAt(offset) -> Number (same as charCodeAt) * charCodeAt(offset:Number) -> Number * charAt(offset:Number) -> byte:ByteString * split(delimiter:Number|ByteString) -> Array of ByteStrings * split(delimiter:Number|ByteString, count:Number) -> Array of ByteStrings * slice() * slice(begin) * slice(begin, end) * substr(start) * substr(start, length) * substring(first) * substring(first, last) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a codec. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === * ByteArray() * ByteArray(length) * ByteArray(byteArray) * ByteArray(byteString) * ByteArray(array) * ByteString(string, codec) Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === * mutable length property ** extending a byte array fills the new entries with 0. === Instance methods (in prototype) === * toArray() -> an array of the byte values * toArray(codec) -> an array of the code points, decoded * toString() -> a string representation like "[ByteArray 10]" * toString(codec) - decoded * toByteArray() -> just a copy * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> byte for byte * toByteString(sourceCodec, targetCodec) -> transcoded * concat(other:ByteArray|ByteString|Array) * join(delimiter:ByteArray|ByteString|Array) * pop() -> byte:Number * push(...variadic Numbers...)-> count:Number * shift() -> byte:Number * unshift(...variadic Numbers...) -> count:Number * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(codec) : Converts a string to a ByteArray encoded in codec. ; toByteString(codec) : Converts a string to a ByteString encoded in codec. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(codec) : Converts an array of Unicode code points to a ByteArray encoded in codec. ; toByteString(codec) : Converts an array of Unicode code points to a ByteString encoded in codec. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] 122 2009-04-11T15:39:50Z MrN /* Constructor */ All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a codec manager module, and may in turn use a system level codec or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. = Specification = == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, codec) : Convert a string. The ByteString will contain string encoded with codec. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCodec, targetCodec) : Returns a transcoded copy in a ByteArray. ; toByteString() : Copy. ; toByteString(sourceCodec, targetCodec) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(codec) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. ; toString(codec) : ''CONTROVERSIAL'' Returns the decoded ByteArray as a string. * indexOf(byte:Number|ByteString|ByteArray) * indexOf(byte:Number|ByteString|ByteArray, start:Number) * indexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * lastIndexOf(byte:Number|ByteString|ByteArray) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number) * lastIndexOf(byte:Number|ByteString|ByteArray, start:Number, stop:Number) * byteAt(offset) -> Number (same as charCodeAt) * charCodeAt(offset:Number) -> Number * charAt(offset:Number) -> byte:ByteString * split(delimiter:Number|ByteString) -> Array of ByteStrings * split(delimiter:Number|ByteString, count:Number) -> Array of ByteStrings * slice() * slice(begin) * slice(begin, end) * substr(start) * substr(start, length) * substring(first) * substring(first, last) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a codec. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, codec) : Create a ByteArray from a Javascript string, the result being encoded with codec. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === * mutable length property ** extending a byte array fills the new entries with 0. === Instance methods (in prototype) === * toArray() -> an array of the byte values * toArray(codec) -> an array of the code points, decoded * toString() -> a string representation like "[ByteArray 10]" * toString(codec) - decoded * toByteArray() -> just a copy * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> byte for byte * toByteString(sourceCodec, targetCodec) -> transcoded * concat(other:ByteArray|ByteString|Array) * join(delimiter:ByteArray|ByteString|Array) * pop() -> byte:Number * push(...variadic Numbers...)-> count:Number * shift() -> byte:Number * unshift(...variadic Numbers...) -> count:Number * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(codec) : Converts a string to a ByteArray encoded in codec. ; toByteString(codec) : Converts a string to a ByteString encoded in codec. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(codec) : Converts an array of Unicode code points to a ByteArray encoded in codec. ; toByteString(codec) : Converts an array of Unicode code points to a ByteString encoded in codec. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] 123 2009-04-11T16:01:23Z MrN /* Specification */ definition lists + more doc for indexOf stuff All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a codec manager module, and may in turn use a system level codec or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. = Specification = == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, codec) : Convert a string. The ByteString will contain string encoded with codec. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCodec, targetCodec) : Returns a transcoded copy in a ByteArray. ; toByteString() : Copy. ; toByteString(sourceCodec, targetCodec) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(codec) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. ; toString(codec) : ''CONTROVERSIAL'' Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; byteAt(offset) ; charCodeAt(offset) : Return the byte at offset as a Number. ; charAt(offset) : Return the byte at offset as a ByteString. * split(delimiter:Number|ByteString) -> Array of ByteStrings * split(delimiter:Number|ByteString, count:Number) -> Array of ByteStrings * slice() * slice(begin) * slice(begin, end) * substr(start) * substr(start, length) * substring(first) * substring(first, last) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a codec. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, codec) : Create a ByteArray from a Javascript string, the result being encoded with codec. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === * mutable length property ** extending a byte array fills the new entries with 0. === Instance methods (in prototype) === * toArray() -> an array of the byte values * toArray(codec) -> an array of the code points, decoded * toString() -> a string representation like "[ByteArray 10]" * toString(codec) - decoded * toByteArray() -> just a copy * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> byte for byte * toByteString(sourceCodec, targetCodec) -> transcoded * concat(other:ByteArray|ByteString|Array) * join(delimiter:ByteArray|ByteString|Array) * pop() -> byte:Number * push(...variadic Numbers...)-> count:Number * shift() -> byte:Number * unshift(...variadic Numbers...) -> count:Number * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(codec) : Converts a string to a ByteArray encoded in codec. ; toByteString(codec) : Converts a string to a ByteString encoded in codec. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(codec) : Converts an array of Unicode code points to a ByteArray encoded in codec. ; toByteString(codec) : Converts an array of Unicode code points to a ByteString encoded in codec. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] 124 2009-04-11T23:59:14Z MrN /* Specification */ split and slice All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a codec manager module, and may in turn use a system level codec or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. = Specification = == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, codec) : Convert a string. The ByteString will contain string encoded with codec. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCodec, targetCodec) : Returns a transcoded copy in a ByteArray. ; toByteString() : Copy. ; toByteString(sourceCodec, targetCodec) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(codec) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. ; toString(codec) : ''CONTROVERSIAL'' Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; byteAt(offset) ; charCodeAt(offset) : Return the byte at offset as a Number. ; charAt(offset) : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters). : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] * substr(start) * substr(start, length) * substring(first) * substring(first, last) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a codec. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, codec) : Create a ByteArray from a Javascript string, the result being encoded with codec. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === * mutable length property ** extending a byte array fills the new entries with 0. === Instance methods (in prototype) === * toArray() -> an array of the byte values * toArray(codec) -> an array of the code points, decoded * toString() -> a string representation like "[ByteArray 10]" * toString(codec) - decoded * toByteArray() -> just a copy * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> byte for byte * toByteString(sourceCodec, targetCodec) -> transcoded * concat(other:ByteArray|ByteString|Array) * join(delimiter:ByteArray|ByteString|Array) * pop() -> byte:Number * push(...variadic Numbers...)-> count:Number * shift() -> byte:Number * unshift(...variadic Numbers...) -> count:Number * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(codec) : Converts a string to a ByteArray encoded in codec. ; toByteString(codec) : Converts a string to a ByteString encoded in codec. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(codec) : Converts an array of Unicode code points to a ByteArray encoded in codec. ; toByteString(codec) : Converts an array of Unicode code points to a ByteString encoded in codec. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] 125 2009-04-12T00:01:12Z MrN /* Specification */ toString(codec) -> decodeToString(codec) All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a codec manager module, and may in turn use a system level codec or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. = Specification = == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, codec) : Convert a string. The ByteString will contain string encoded with codec. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCodec, targetCodec) : Returns a transcoded copy in a ByteArray. ; toByteString() : Copy. ; toByteString(sourceCodec, targetCodec) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(codec) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. ; decodeToString(codec) : ''CONTROVERSIAL'' Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; byteAt(offset) ; charCodeAt(offset) : Return the byte at offset as a Number. ; charAt(offset) : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters). : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] * substr(start) * substr(start, length) * substring(first) * substring(first, last) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a codec. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, codec) : Create a ByteArray from a Javascript string, the result being encoded with codec. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === * mutable length property ** extending a byte array fills the new entries with 0. === Instance methods (in prototype) === * toArray() -> an array of the byte values * toArray(codec) -> an array of the code points, decoded * toString() -> a string representation like "[ByteArray 10]" * decodeToString(codec) - decoded * toByteArray() -> just a copy * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> byte for byte * toByteString(sourceCodec, targetCodec) -> transcoded * concat(other:ByteArray|ByteString|Array) * join(delimiter:ByteArray|ByteString|Array) * pop() -> byte:Number * push(...variadic Numbers...)-> count:Number * shift() -> byte:Number * unshift(...variadic Numbers...) -> count:Number * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(codec) : Converts a string to a ByteArray encoded in codec. ; toByteString(codec) : Converts a string to a ByteString encoded in codec. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(codec) : Converts an array of Unicode code points to a ByteArray encoded in codec. ; toByteString(codec) : Converts an array of Unicode code points to a ByteString encoded in codec. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] 126 2009-04-12T00:03:01Z MrN /* Instance methods (in prototype) */ All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible codecs or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a codec manager module, and may in turn use a system level codec or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. = Specification = == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, codec) : Convert a string. The ByteString will contain string encoded with codec. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCodec, targetCodec) : Returns a transcoded copy in a ByteArray. ; toByteString() : Copy. ; toByteString(sourceCodec, targetCodec) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(codec) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. ; decodeToString(codec) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; byteAt(offset) ; charCodeAt(offset) : Return the byte at offset as a Number. ; charAt(offset) : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters). : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] * substr(start) * substr(start, length) * substring(first) * substring(first, last) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a codec. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, codec) : Create a ByteArray from a Javascript string, the result being encoded with codec. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === * mutable length property ** extending a byte array fills the new entries with 0. === Instance methods (in prototype) === * toArray() -> an array of the byte values * toArray(codec) -> an array of the code points, decoded * toString() -> a string representation like "[ByteArray 10]" * decodeToString(codec) - decoded * toByteArray() -> just a copy * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> byte for byte * toByteString(sourceCodec, targetCodec) -> transcoded * concat(other:ByteArray|ByteString|Array) * join(delimiter:ByteArray|ByteString|Array) * pop() -> byte:Number * push(...variadic Numbers...)-> count:Number * shift() -> byte:Number * unshift(...variadic Numbers...) -> count:Number * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(codec) : Converts a string to a ByteArray encoded in codec. ; toByteString(codec) : Converts a string to a ByteString encoded in codec. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(codec) : Converts an array of Unicode code points to a ByteArray encoded in codec. ; toByteString(codec) : Converts an array of Unicode code points to a ByteString encoded in codec. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] 127 2009-05-15T05:58:04Z KrisKowal s/codec/charset/ in most places, and noted that ByteString().toByteString() can return itself instead of making a copy since it is immutable. All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named codec or digest module, assuming that the given module exports the specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. = Specification = == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCodec, targetCodec) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCodec, targetCodec) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; byteAt(offset) ; charCodeAt(offset) : Return the byte at offset as a Number. ; charAt(offset) : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters). : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] * substr(start) * substr(start, length) * substring(first) * substring(first, last) * The + operator returning new ByteStrings * The immutable [] operator returning ByteStrings * toSource() which would return "ByteString([])" for a null byte string * valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === * mutable length property ** extending a byte array fills the new entries with 0. === Instance methods (in prototype) === * toArray() -> an array of the byte values * toArray(charset) -> an array of the code points, decoded * toString() -> a string representation like "[ByteArray 10]" * decodeToString(charset) - decoded * toByteArray() -> just a copy * toByteArray(sourceCodec, targetCodec) -> transcoded * toByteString() -> byte for byte * toByteString(sourceCodec, targetCodec) -> transcoded * concat(other:ByteArray|ByteString|Array) * join(delimiter:ByteArray|ByteString|Array) * pop() -> byte:Number * push(...variadic Numbers...)-> count:Number * shift() -> byte:Number * unshift(...variadic Numbers...) -> count:Number * reverse() in place reversal * slice() * sort() * splice() * toSource() returns a string like "ByteArray([])" for a null byte-array. * valueOf() * The + operator returning new ByteArrays * The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Codec strings are as defined by IANA http://www.iana.org/assignments/character-sets. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] 128 2009-05-17T23:22:16Z KrisKowal Edits in response to byteAt thread. All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. = Specification = The "binary" top-level module must export "ByteArray" and "ByteString". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; byteAt(offset) ; charCodeAt(offset) : Return the byte at offset as a Number. ; charAt(offset) : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters). : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start) ; substr(start, length) ; substring(first) ; substring(first, last) ; The + operator returning new ByteStrings ; The immutable [] operator returning ByteStrings ; toSource() which would return "ByteString([])" for a null byte string ; valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : a string representation like "[ByteArray 10]" ; <u>toString(charset)</u> : <u>an alias for decodeToString(charset)</u> ; decodeToString() ; decodeToString(charset) : returns a String from its decoded bytes in a given charset. If no charset is provided, or if the charset is "undefined", assumes the default system encoding. ; toByteArray() : just a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; <u>byteAt(offset)</u> ; concat(other:ByteArray|ByteString|Array) ; <strike>join(delimiter:ByteArray|ByteString|Array)</strike> : <u>deemed unnecessary and semantically unclear</u> ; pop() -> byte:Number ; push(...variadic Numbers...)-> count:Number ; shift() -> byte:Number ; unshift(...variadic Numbers...) -> count:Number ; reverse() in place reversal ; slice() ; sort() ; splice() ; toSource() returns a string like "ByteArray([])" for a null byte-array. ; valueOf() ; The + operator returning new ByteArrays ; The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. ; <u>join(delimiter)</u> : <u>Overridden to distinguish its behavior on whether the delimiter is a ByteString, ByteArray, or String. Defaults to usual behavior for Strings. Coerces items to ByteString or ByteArray and joins them on the delimiter for delimiters with their respective types.</u> == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. <u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8".</u> Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. <u>Charsets are case insensitive.</u> = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] 129 2009-05-18T12:50:56Z MrN export Binary too! All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. = Specification = The "binary" top-level module must export "Binary", "ByteArray" and "ByteString". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; byteAt(offset) ; charCodeAt(offset) : Return the byte at offset as a Number. ; charAt(offset) : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters). : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start) ; substr(start, length) ; substring(first) ; substring(first, last) ; The + operator returning new ByteStrings ; The immutable [] operator returning ByteStrings ; toSource() which would return "ByteString([])" for a null byte string ; valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : a string representation like "[ByteArray 10]" ; <u>toString(charset)</u> : <u>an alias for decodeToString(charset)</u> ; decodeToString() ; decodeToString(charset) : returns a String from its decoded bytes in a given charset. If no charset is provided, or if the charset is "undefined", assumes the default system encoding. ; toByteArray() : just a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; <u>byteAt(offset)</u> ; concat(other:ByteArray|ByteString|Array) ; <strike>join(delimiter:ByteArray|ByteString|Array)</strike> : <u>deemed unnecessary and semantically unclear</u> ; pop() -> byte:Number ; push(...variadic Numbers...)-> count:Number ; shift() -> byte:Number ; unshift(...variadic Numbers...) -> count:Number ; reverse() in place reversal ; slice() ; sort() ; splice() ; toSource() returns a string like "ByteArray([])" for a null byte-array. ; valueOf() ; The + operator returning new ByteArrays ; The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. ; <u>join(delimiter)</u> : <u>Overridden to distinguish its behavior on whether the delimiter is a ByteString, ByteArray, or String. Defaults to usual behavior for Strings. Coerces items to ByteString or ByteArray and joins them on the delimiter for delimiters with their respective types.</u> == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. <u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8".</u> Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. <u>Charsets are case insensitive.</u> = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] 130 2009-05-18T14:07:20Z MrN move join the ByteString constructor, remove toString(charset) All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. = Specification = The "binary" top-level module must export "Binary", "ByteArray" and "ByteString". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Constructor methods === ; <u>join(array, delimiter)</u> : Like Array.prototype.join, but for Binarys. Returns a ByteString. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; byteAt(offset) ; charCodeAt(offset) : Return the byte at offset as a Number. ; charAt(offset) : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters). : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start) ; substr(start, length) ; substring(first) ; substring(first, last) ; The + operator returning new ByteStrings ; The immutable [] operator returning ByteStrings ; toSource() which would return "ByteString([])" for a null byte string ; valueOf() ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : A string debug representation like "[ByteArray 10]". Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString() ; decodeToString(charset) : returns a String from its decoded bytes in a given charset. If no charset is provided, or if the charset is "undefined", assumes the default system encoding. ; toByteArray() : just a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; <u>byteAt(offset)</u> ; concat(other:ByteArray|ByteString|Array) ; pop() -> byte:Number ; push(...variadic Numbers...)-> count:Number ; shift() -> byte:Number ; unshift(...variadic Numbers...) -> count:Number ; reverse() in place reversal ; slice() ; sort() ; splice() ; toSource() returns a string like "ByteArray([])" for a null byte-array. ; valueOf() ; The + operator returning new ByteArrays ; The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. <u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8".</u> Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. <u>Charsets are case insensitive.</u> = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] 131 2009-05-21T12:37:44Z MrN remove + operator and valueOf (the first not being implementable and the second being ununderstood) All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. = Specification = The "binary" top-level module must export "Binary", "ByteArray" and "ByteString". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Constructor methods === ; <u>join(array, delimiter)</u> : Like Array.prototype.join, but for Binarys. Returns a ByteString. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; byteAt(offset) ; charCodeAt(offset) : Return the byte at offset as a Number. ; charAt(offset) : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters). : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start) ; substr(start, length) ; substring(first) ; substring(first, last) ; The immutable [] operator returning ByteStrings ; toSource() which would return "ByteString([])" for a null byte string ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : A string debug representation like "[ByteArray 10]". Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString() ; decodeToString(charset) : returns a String from its decoded bytes in a given charset. If no charset is provided, or if the charset is "undefined", assumes the default system encoding. ; toByteArray() : just a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; <u>byteAt(offset)</u> ; concat(other:ByteArray|ByteString|Array) ; pop() -> byte:Number ; push(...variadic Numbers...)-> count:Number ; shift() -> byte:Number ; unshift(...variadic Numbers...) -> count:Number ; reverse() in place reversal ; slice() ; sort() ; splice() ; toSource() returns a string like "ByteArray([])" for a null byte-array. ; The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. <u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8".</u> Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. <u>Charsets are case insensitive.</u> = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] 132 2009-05-24T23:01:10Z KrisKowal Formatting and explication of byteAt, charAt, and their types. All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. = Specification = The "binary" top-level module must export "Binary", "ByteArray" and "ByteString". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Constructor methods === ; <u>join(array, delimiter)</u> : Like Array.prototype.join, but for Binarys. Returns a ByteString. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; charCodeAt(offset) : Return the byte at offset as a Number. ; byteAt(offset) ByteString ; charAt(offset) ByteString : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters). : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start) : ; substr(start, length) : ; substring(first) : ; substring(first, last) ; [] ByteString : the immutable [] operator returning ByteStrings ; toSource() : which would return "ByteString([])" for a null byte string ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : A string debug representation like "[ByteArray 10]". Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString() ; decodeToString(charset) : returns a String from its decoded bytes in a given charset. If no charset is provided, or if the charset is "undefined", assumes the default system encoding. ; toByteArray() : just a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; <u>byteAt(offset) ByteString</u> ; <u>charAt(offset) ByteString</u> : ; concat(other:ByteArray|ByteString|Array) ; pop() byte:Number : ; push(...variadic Numbers...) count:Number : ; shift() byte:Number : ; unshift(...variadic Numbers...) count:Number : ; reverse() in place reversal : ; slice() : ; sort() : ; splice() : ; toSource() : returns a string like "ByteArray([])" for a null byte-array. ; [] Number : The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. <u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8".</u> Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. <u>Charsets are case insensitive.</u> = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] 133 2009-05-25T08:20:10Z MrN /* Relevant Discussions */ add new discussion All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. = Specification = The "binary" top-level module must export "Binary", "ByteArray" and "ByteString". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Constructor methods === ; <u>join(array, delimiter)</u> : Like Array.prototype.join, but for Binarys. Returns a ByteString. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; charCodeAt(offset) : Return the byte at offset as a Number. ; byteAt(offset) ByteString ; charAt(offset) ByteString : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters). : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start) : ; substr(start, length) : ; substring(first) : ; substring(first, last) ; [] ByteString : the immutable [] operator returning ByteStrings ; toSource() : which would return "ByteString([])" for a null byte string ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : A string debug representation like "[ByteArray 10]". Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString() ; decodeToString(charset) : returns a String from its decoded bytes in a given charset. If no charset is provided, or if the charset is "undefined", assumes the default system encoding. ; toByteArray() : just a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; <u>byteAt(offset) ByteString</u> ; <u>charAt(offset) ByteString</u> : ; concat(other:ByteArray|ByteString|Array) ; pop() byte:Number : ; push(...variadic Numbers...) count:Number : ; shift() byte:Number : ; unshift(...variadic Numbers...) count:Number : ; reverse() in place reversal : ; slice() : ; sort() : ; splice() : ; toSource() : returns a string like "ByteArray([])" for a null byte-array. ; [] Number : The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. <u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8".</u> Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. <u>Charsets are case insensitive.</u> = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] * [http://groups.google.com/group/serverjs/browse_thread/thread/45190ac89d7b422a Binary/B Extension Proposals and Implementation Notes] 134 2009-05-25T12:01:00Z MrN /* Specification */ add some results from the discussion All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. = Specification = The "binary" top-level module must export "Binary", "ByteArray" and "ByteString". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Constructor methods === ; join(array, delimiter) : Like Array.prototype.join, but for Binarys. Returns a ByteString. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; charCodeAt(offset) ; <u>get(offset)</u> : Return the byte at offset as a Number. ; byteAt(offset) ByteString ; charAt(offset) ByteString : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters, i.e., "split at any of these delimiters"). Delimiters can have arbitrary size. : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements (ignoring delimiters) to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start) : ; substr(start, length) : ; substring(first) : ; substring(first, last) ; [] ByteString : the immutable [] operator returning ByteStrings ; toSource() : which would return "ByteString([])" for a null byte string ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : A string debug representation like "[ByteArray 10]". Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString() ; decodeToString(charset) : returns a String from its decoded bytes in a given charset. If no charset is provided, or if the charset is "undefined", assumes the default system encoding. ; toByteArray() : just a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; <u>byteAt(offset) ByteString</u> : Return the byte at offset as a ByteString. ; <u>get(offset) Number</u> : Return the byte at offset as a Number. ; concat(other:ByteArray|ByteString|Array) ; pop() byte:Number : ; push(...variadic Numbers...) -> count(Number) : ; <u>extendRight(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u> : ; shift() byte:Number : ; unshift(...variadic Numbers...) count:Number : ; <u>extendLeft(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u> : ; reverse() in place reversal : ; slice() : ; sort() : ; splice() : ; <u>indexOf()</u> : ; <u>lastIndexOf()</u> : ; <u>split()</u> : Returns an array of ByteArrays instead of ByteStrings. ; <u>filter()/u> : ; <u>forEach()/u> : ; <u>every()/u> : ; <u>some()/u> : ; <u>map()/u> : ; <u>reduce()/u> : ; <u>reduceRight()/u> : ; <u>displace(begin, end, values/ByteStrings/ByteArrays/Arrays...) -> length</u> : begin/end are specified like for slice. Can be used like splice but does not return the removed elements. ; toSource() : Returns a string like "ByteArray([])" for a null byte-array. ; [] Number : The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. <u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8".</u> Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. <u>Charsets are case insensitive.</u> = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] * [http://groups.google.com/group/serverjs/browse_thread/thread/45190ac89d7b422a Binary/B Extension Proposals and Implementation Notes] 135 2009-05-26T23:10:48Z KrisKowal markup errors All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. = Specification = The "binary" top-level module must export "Binary", "ByteArray" and "ByteString". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Constructor methods === ; join(array, delimiter) : Like Array.prototype.join, but for Binarys. Returns a ByteString. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; charCodeAt(offset) ; <u>get(offset)</u> : Return the byte at offset as a Number. ; byteAt(offset) ByteString ; charAt(offset) ByteString : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters, i.e., "split at any of these delimiters"). Delimiters can have arbitrary size. : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements (ignoring delimiters) to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start) : ; substr(start, length) : ; substring(first) : ; substring(first, last) ; [] ByteString : the immutable [] operator returning ByteStrings ; toSource() : which would return "ByteString([])" for a null byte string ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : A string debug representation like "[ByteArray 10]". Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString() ; decodeToString(charset) : returns a String from its decoded bytes in a given charset. If no charset is provided, or if the charset is "undefined", assumes the default system encoding. ; toByteArray() : just a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; <u>byteAt(offset) ByteString</u> : Return the byte at offset as a ByteString. ; <u>get(offset) Number</u> : Return the byte at offset as a Number. ; concat(other:ByteArray|ByteString|Array) ; pop() byte:Number : ; push(...variadic Numbers...) -> count(Number) : ; <u>extendRight(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u> : ; shift() byte:Number : ; unshift(...variadic Numbers...) count:Number : ; <u>extendLeft(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u> : ; reverse() in place reversal : ; slice() : ; sort() : ; splice() : ; <u>indexOf()</u> : ; <u>lastIndexOf()</u> : ; <u>split()</u> : Returns an array of ByteArrays instead of ByteStrings. ; <u>filter()</u> : ; <u>forEach()</u> : ; <u>every()</u> : ; <u>some()</u> : ; <u>map()</u> : ; <u>reduce()</u> : ; <u>reduceRight()</u> : ; <u>displace(begin, end, values/ByteStrings/ByteArrays/Arrays...) -> length</u> : begin/end are specified like for slice. Can be used like splice but does not return the removed elements. ; toSource() : Returns a string like "ByteArray([])" for a null byte-array. ; [] Number : The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. <u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8".</u> Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. <u>Charsets are case insensitive.</u> = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] * [http://groups.google.com/group/serverjs/browse_thread/thread/45190ac89d7b422a Binary/B Extension Proposals and Implementation Notes] 136 2009-06-05T19:28:44Z Tlrobinson Added link to tests All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. = Specification = The "binary" top-level module must export "Binary", "ByteArray" and "ByteString". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Constructor methods === ; join(array, delimiter) : Like Array.prototype.join, but for Binarys. Returns a ByteString. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; charCodeAt(offset) ; <u>get(offset)</u> : Return the byte at offset as a Number. ; byteAt(offset) ByteString ; charAt(offset) ByteString : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters, i.e., "split at any of these delimiters"). Delimiters can have arbitrary size. : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements (ignoring delimiters) to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start) : ; substr(start, length) : ; substring(first) : ; substring(first, last) ; [] ByteString : the immutable [] operator returning ByteStrings ; toSource() : which would return "ByteString([])" for a null byte string ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : A string debug representation like "[ByteArray 10]". Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString() ; decodeToString(charset) : returns a String from its decoded bytes in a given charset. If no charset is provided, or if the charset is "undefined", assumes the default system encoding. ; toByteArray() : just a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; <u>byteAt(offset) ByteString</u> : Return the byte at offset as a ByteString. ; <u>get(offset) Number</u> : Return the byte at offset as a Number. ; concat(other:ByteArray|ByteString|Array) ; pop() byte:Number : ; push(...variadic Numbers...) -> count(Number) : ; <u>extendRight(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u> : ; shift() byte:Number : ; unshift(...variadic Numbers...) count:Number : ; <u>extendLeft(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u> : ; reverse() in place reversal : ; slice() : ; sort() : ; splice() : ; <u>indexOf()</u> : ; <u>lastIndexOf()</u> : ; <u>split()</u> : Returns an array of ByteArrays instead of ByteStrings. ; <u>filter()</u> : ; <u>forEach()</u> : ; <u>every()</u> : ; <u>some()</u> : ; <u>map()</u> : ; <u>reduce()</u> : ; <u>reduceRight()</u> : ; <u>displace(begin, end, values/ByteStrings/ByteArrays/Arrays...) -> length</u> : begin/end are specified like for slice. Can be used like splice but does not return the removed elements. ; toSource() : Returns a string like "ByteArray([])" for a null byte-array. ; [] Number : The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. <u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8".</u> Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. <u>Charsets are case insensitive.</u> = Tests = * [http://github.com/tlrobinson/narwhal/tree/master/tests/serverjs ServerJS tests] compatible with [http://github.com/tlrobinson/narwhal/tree/master/lib/test this test framework]. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] * [http://groups.google.com/group/serverjs/browse_thread/thread/45190ac89d7b422a Binary/B Extension Proposals and Implementation Notes] 137 2009-06-06T15:40:56Z MrN /* Instance methods (in prototype) */ There is no "default charset". And there should be none. All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. = Specification = The "binary" top-level module must export "Binary", "ByteArray" and "ByteString". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Constructor methods === ; join(array, delimiter) : Like Array.prototype.join, but for Binarys. Returns a ByteString. === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; charCodeAt(offset) ; <u>get(offset)</u> : Return the byte at offset as a Number. ; byteAt(offset) ByteString ; charAt(offset) ByteString : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters, i.e., "split at any of these delimiters"). Delimiters can have arbitrary size. : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements (ignoring delimiters) to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start) : ; substr(start, length) : ; substring(first) : ; substring(first, last) ; [] ByteString : the immutable [] operator returning ByteStrings ; toSource() : which would return "ByteString([])" for a null byte string ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : A string debug representation like "[ByteArray 10]". Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : returns a String from its decoded bytes in a given charset. ; toByteArray() : just a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; <u>byteAt(offset) ByteString</u> : Return the byte at offset as a ByteString. ; <u>get(offset) Number</u> : Return the byte at offset as a Number. ; concat(other:ByteArray|ByteString|Array) ; pop() byte:Number : ; push(...variadic Numbers...) -> count(Number) : ; <u>extendRight(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u> : ; shift() byte:Number : ; unshift(...variadic Numbers...) count:Number : ; <u>extendLeft(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u> : ; reverse() in place reversal : ; slice() : ; sort() : ; splice() : ; <u>indexOf()</u> : ; <u>lastIndexOf()</u> : ; <u>split()</u> : Returns an array of ByteArrays instead of ByteStrings. ; <u>filter()</u> : ; <u>forEach()</u> : ; <u>every()</u> : ; <u>some()</u> : ; <u>map()</u> : ; <u>reduce()</u> : ; <u>reduceRight()</u> : ; <u>displace(begin, end, values/ByteStrings/ByteArrays/Arrays...) -> length</u> : begin/end are specified like for slice. Can be used like splice but does not return the removed elements. ; toSource() : Returns a string like "ByteArray([])" for a null byte-array. ; [] Number : The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. <u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8".</u> Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. <u>Charsets are case insensitive.</u> = Tests = * [http://github.com/tlrobinson/narwhal/tree/master/tests/serverjs ServerJS tests] compatible with [http://github.com/tlrobinson/narwhal/tree/master/lib/test this test framework]. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] * [http://groups.google.com/group/serverjs/browse_thread/thread/45190ac89d7b422a Binary/B Extension Proposals and Implementation Notes] 138 2009-07-10T01:25:03Z Tlrobinson /* Constructor methods */ All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. = Specification = The "binary" top-level module must export "Binary", "ByteArray" and "ByteString". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Constructor methods === ; join(array, delimiter) : Like Array.prototype.join, but for Binarys. Returns a ByteString. (TODO: clarify usage) === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; charCodeAt(offset) ; <u>get(offset)</u> : Return the byte at offset as a Number. ; byteAt(offset) ByteString ; charAt(offset) ByteString : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters, i.e., "split at any of these delimiters"). Delimiters can have arbitrary size. : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements (ignoring delimiters) to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start) : ; substr(start, length) : ; substring(first) : ; substring(first, last) ; [] ByteString : the immutable [] operator returning ByteStrings ; toSource() : which would return "ByteString([])" for a null byte string ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : A string debug representation like "[ByteArray 10]". Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : returns a String from its decoded bytes in a given charset. ; toByteArray() : just a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; <u>byteAt(offset) ByteString</u> : Return the byte at offset as a ByteString. ; <u>get(offset) Number</u> : Return the byte at offset as a Number. ; concat(other:ByteArray|ByteString|Array) ; pop() byte:Number : ; push(...variadic Numbers...) -> count(Number) : ; <u>extendRight(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u> : ; shift() byte:Number : ; unshift(...variadic Numbers...) count:Number : ; <u>extendLeft(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u> : ; reverse() in place reversal : ; slice() : ; sort() : ; splice() : ; <u>indexOf()</u> : ; <u>lastIndexOf()</u> : ; <u>split()</u> : Returns an array of ByteArrays instead of ByteStrings. ; <u>filter()</u> : ; <u>forEach()</u> : ; <u>every()</u> : ; <u>some()</u> : ; <u>map()</u> : ; <u>reduce()</u> : ; <u>reduceRight()</u> : ; <u>displace(begin, end, values/ByteStrings/ByteArrays/Arrays...) -> length</u> : begin/end are specified like for slice. Can be used like splice but does not return the removed elements. ; toSource() : Returns a string like "ByteArray([])" for a null byte-array. ; [] Number : The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. <u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8".</u> Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. <u>Charsets are case insensitive.</u> = Tests = * [http://github.com/tlrobinson/narwhal/tree/master/tests/serverjs ServerJS tests] compatible with [http://github.com/tlrobinson/narwhal/tree/master/lib/test this test framework]. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] * [http://groups.google.com/group/serverjs/browse_thread/thread/45190ac89d7b422a Binary/B Extension Proposals and Implementation Notes] 139 2009-07-12T07:07:49Z Tlrobinson Added args for some ByteArray methods All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. = Specification = The "binary" top-level module must export "Binary", "ByteArray" and "ByteString". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array. ByteString supports the String API, and indexing returns a byte substring of length 1. === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, an exception (''TODO'') is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Constructor methods === ; join(array, delimiter) : Like Array.prototype.join, but for Binarys. Returns a ByteString. (TODO: clarify usage) === Instance properties === ; length : The length in bytes. Immutable. === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; charCodeAt(offset) ; <u>get(offset)</u> : Return the byte at offset as a Number. ; byteAt(offset) ByteString ; charAt(offset) ByteString : Return the byte at offset as a ByteString. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters, i.e., "split at any of these delimiters"). Delimiters can have arbitrary size. : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements (ignoring delimiters) to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(begin) ; slice(begin, end) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start) : ; substr(start, length) : ; substring(first) : ; substring(first, last) ; [] ByteString : the immutable [] operator returning ByteStrings ; toSource() : which would return "ByteString([])" for a null byte string ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : A string debug representation like "[ByteArray 10]". Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; decodeToString(charset) : returns a String from its decoded bytes in a given charset. ; toByteArray() : just a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; <u>byteAt(offset) ByteString</u> : Return the byte at offset as a ByteString. ; <u>get(offset) Number</u> : Return the byte at offset as a Number. ; concat(other:ByteArray|ByteString|Array) ; pop() byte:Number : ; push(...variadic Numbers...) -> count(Number) : ; <u>extendRight(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u> : ; shift() byte:Number : ; unshift(...variadic Numbers...) count:Number : ; <u>extendLeft(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u> : ; reverse() in place reversal : ; slice() : ; sort() : ; splice() : ; <u>indexOf()</u> : ; <u>lastIndexOf()</u> : ; <u>split()</u> : Returns an array of ByteArrays instead of ByteStrings. ; <u>filter(callback[, thisObject])</u> : ; <u>forEach(callback[, thisObject])</u> : ; <u>every(callback[, thisObject])</u> : ; <u>some(callback[, thisObject])</u> : ; <u>map(callback[, thisObject])</u> : ; <u>reduce(callback[, initialValue])</u> : ; <u>reduceRight(callback[, initialValue])</u> : ; <u>displace(begin, end, values/ByteStrings/ByteArrays/Arrays...) -> length</u> : begin/end are specified like for slice. Can be used like splice but does not return the removed elements. ; toSource() : Returns a string like "ByteArray([])" for a null byte-array. ; [] Number : The mutable [] operator for numbers == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. <u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8".</u> Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. <u>Charsets are case insensitive.</u> = Tests = * [http://github.com/tlrobinson/narwhal/tree/master/tests/serverjs ServerJS tests] compatible with [http://github.com/tlrobinson/narwhal/tree/master/lib/test this test framework]. = Relevant Discussions = * [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] * [http://groups.google.com/group/serverjs/browse_thread/thread/45190ac89d7b422a Binary/B Extension Proposals and Implementation Notes] 140 2009-09-05T12:34:08Z Hannesw Added notes section All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[ServerJS/Binary|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and wi