[ ESL - Index ]
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).