[ ESL - Guidelines ]
Euphoria Standard Library (ESL) - General Guidelines
Status of this topic : Agreed upon
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 as many of the routines that are needed
for everyday programming as possible.
(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 should work identically
for all supported platforms (DOS, Windows, Linux, and FreeBSD).
It is not a requirement, however, that all routines work in all platforms, only
those platforms for which 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.
- The style of code and documentation shall in general be similar to the style
of the material contained in the official Euphoria release.
(See Coding standard for the project)
- All algorithms used should be as efficient, flexible, and robust as
- The library should provide several global standard types.
These types should not all be written in a single
"type module", but instead
- they should be included in the respective module
(e.g. math.e, string.e).
- or they should be in separate files such as
- All routines should normally use standard types (integer, atom, sequence,
object) for parameter declaration unless specifically designed to handle new data
- The library should not contain GUI routines or wrappers for GUI
functions of any operating sytem. It should contain only utility routines
instead (which are also useful for GUI libraries) so that these libraries
can concentrate on their real goal of being general purpose and portable.
- 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,
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
- All files distributed with the standard 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).