System/1.0
From CommonJS Spec Wiki
STATUS: IMPLEMENTATIONS
- Implementations
- [[Implementations/Flusspferd|]], [[Implementations/GPSEE|]], [[Implementations/NarwhalRhino|]] (0.2), [[Implementations/NarwhalNode|]] (0.5), [[Implementations/NarwhalJSC|]] (0.2), [[Implementations/RingoJS|]], [[Implementations/SproutCore|]], [[Implementations/TeaJS|]], [[Implementations/Wakanda|]] (partial), [[Implementations/common-node|]], [[Implementations/sorrow.js|]]
Contents
System Interface
All platforms must support a module, "system", that MUST contain the following attributes.
- stdin: the standard input stream, an object with the same API as a file opened with the mode "r" with no encoding.
- stdout: the standard output stream, an object with the same API as a file opened with the mode "w" with no encoding.
- stderr: the standard error stream, an object with the same API as a file opened with the mode "w" with no encoding.
- env: an Object containing posix-style or CGI environment variables.
- args: an Array containing the command line arguments for the invoking arguments, not including the interpreter/engine but including the path to the program as it was executed. See also the Command Line page.
Any names not mentioned here or amended into this specification later should begin with "x" and a vendor-specific label as a prefix, like system.xCajaDomita. This will permit the future standardization of additional names as needed. Please request additional standard names below.
Compliant Implementations
- Narwhal
- Flusspferd (in 0.7)
- RingoJS (in 0.4)
- v8cgi
Proposals for Future Versions
The following names have been proposed but not ratified for inclusion in the System proposal.
The "system" module MAY export the following functions, that if present MUST behave as specified.
- print: a function that forwards its thisp and arguments to "system.stdout.print" with lazy binding (meaning that, if system.stdout is replaced, print MUST forward to the new stdout).
- log: a function that accepts a "message" and an optional "label" String.
- The label MAY be one of "log", "debug", "warn", "error", "pass", "fail".
- Any other, unspecified label MUST be in lower-case and begin with "x" and a vendor-specific label like "x-v8cgi-database".
- Still not sure that this belongs system. (There are lots of flavours of logging: log("x", "debug") vs log.debug("x"). Also prefixed logging (by namespace) doesn't work with this form) Ashb
- platform: a string with its vendor-specific platform name.
- Is this meant to be the OS name or the commonjs project name ("flusspferd","gpsee","narwhal" etc)? Ashb
- global: the "system" MAY contain a reference to the global object.
- command: an array containing argv[0] and any subsequent arguments that would be relevant for "Usage:" lines. argv[0] would be removed from system.args. [1] Supporters: KrisKowal, ChristophDorn, AshBerlin, DonnyViszneki
- Split "env", "args", and "command" into one module, so stdio can be alternately imported as synchronous or asynchronous in another module.
Removed proposals
- fs: a file default file system root object conforming to the File System API
- print (proposal A): The "system" MAY have a "print" function that accepts a "message" and an optional "label" String.
- The label MAY be one of "log", "warn", "error", "pass", "fail".
- Any other, unspecified label MUST be in lower-case and begin with "x" and a vendor-specific label like "x-v8cgi-database".
- Counter-argument This is infact not printing, but logging. 1) there is lots of logging frameworks, 2) it probably doesn't belong on sys, certainl not called print
- Counter-argument However, print has meant to write a line to stdout in many languages. That it would frequently be used for logging in non-stdio contexts is not necessarily relevant.
