Euphoria Standard Library (ESL) - General Guidelines

General Guidelines

Status of this topic : under discussion

The Euphoria Standard Library is mainly supposed to be a a reliable tool, that supplements the official Euphoria release in a way, so that the average Euphoria programmer is supplied with about 80% of the routines that is needed for everyday programming.
( Think of Pareto's principle: Eighty percent of your work is accomplished with twenty percent of your tools. )

The library is built in a modular way. Each module has it's own .e file(s) (e.g. string.e, math.e). The modules should be as independent as possible from each other.
All routines that are meant to be called by the user must work for all supported platforms: DOS, Windows, Linux, and FreeBSD.
In cases where there must be platform specific code (e.g. file I/O), there is a separate .e file for each platform, as well as a file that contains the wrapper functions that are called by the user. Example:
- files_dos.e
- files_win.e
- files_lnx.e
- files_bsd.e
- files.e –> contains the code that is called by the user
It is not a requirement that all routines work in all platforms, only those platforms that it makes sense. For example, a function that returns a list of Drive letters available only makes sense for Windows and DOS platforms, and not unix. But the unix platform should have the function available, even it only returns an empty list. controversial
OR the file can use platform() to detect the platform.
The style of code and documentation shall in general be close to the style of the material contained in the official Euphoria release.
All used algorithms should be as efficient, flexible and robust as possible.
The library should provide several global standard types.
These types should not all be written in a single "type module", but
- they should be included in the respective module (e.g. math.e, string.e), as far as possible or
- they should be in separate files such as mathtypes.e, stringtypes.e
However, maybe there should be a file such as types.e, that contains frequently used global types (e.g. boolean()), that don't fit into another module properly.
All routines should normally use standard types for parameter declaration.
The library should not contain GUI routines or wrappers for GUI functions of any operating sytem. It should contain utility routines instead, that are useful also for GUI libraries, so that these libraries can concentrate on their real goal.
Selected modules (especially those containing math routines) will be written in a way, so that the routines can be applied to sequences as well as to single numbers (atoms) when possible, see Operations on Sequences.
Each module comes with a test program that performs a sanity check for all routines in it.
Each routine will have a list, by date, of who has approved it and any modifications made, so it is clear if any modifications have been made after approval.
What should a function return in case of an error? While this probably is a case-by-case issue for the most part, we might want to at least establish some rules of thumb, e.g. The same data type should be returned that is returned as a legal value, if possible. controversial
Should the library have a global error function (such as the Windows function GetLastError), or a global error flag? controversial
All files distributed with the stanndard library must have 8.3 filenames in respect to DOS.
For all things that are handled differently in different countries (like the date format), our code and documentation follows generally accepted international recommendations, mainly ISO and the RFCs, as far as internet communication is concerned.
Although e.g. the date 2005-07-06 is unambiguous according to ISO, some people might not realize that this is ISO format, or might not know the ISO rules, and so it may be read erraneously as June 7th 2005 by some. In order to express dates unambiguously, all dates used in comments and documentation should preferably use the name of the month rather than its number (e.g. July 6, 2005).