Modules
Euphoria Modules
Standard Library
The OpenEuphoria Standard Library consists of a collection of modules. Each module expands the power of OpenEuphoria with additional features.
A module is "an include file containing useful procedures, functions, and constants written in OpenEuphoria code." You can examine how each routine is written to better understand how to use it. You can use module routines as samples for creating your own routines. (Because a module is a plain text file, a module is sometimes called "an include.")
For example the display routine is a convenient output procedure. To use it you have to include the std/console.e module:
include std/console.e display("The answer to [1] was [2]", {"'why'", 42}) --> the output is: -- The answer to 'why' was 42
When you save an OpenEuphoria application (either by compiling or binding) all unused routines are excluded from your final product. Modules are only read once; duplicated include files are quietly ignored. There is no penalty for including too many modules as you develop an application.
A typical OpenEuphoria program is written with several modules. You will see a few lines of include statements at the top of most programs. Probably you will use the same set of includes in many of your programs. It is simple to collect your favourite modules and turn them into a single module.
For example you may use cmdline.e (to process command line arguments) console.e (for extra output routines), io.e (for file reading and writing), and a few others on a regular basis. Put all of your include statements into one file as:
-- MyModules.e public include std/cmdline.e public include std/console.e public include std/io.e -- add more modules as needed...
Now you only need a single include statement for your programs,
include MyModules.e display( "Hello Modules!") --> Hello Modules!
and save on repeated typing. The public keyword is required to make the list of modules contained in MyModules.e visible to the main program.
As you increase the number of modules in your program it is inevitable that some identifiers will be duplicated. For example the identifier find is a built-in function and find is a function in the regular expressions module. This creates problems:
include std/regex.e sequence s1 = { "cats", "and", "dogs" } ? find( "dogs", s1 ) --> 3 -- "dogs" is the third item in s1 sequence s2 = "cats and dogs" object r = new( "dog" ) ? find( r, s2 ) --> 0 -- very bad! -- substring "dog" not located in string "cats and dogs" ? regex:find( r, s2 ) --> { {10,12} } -- as expected -- "dog" starts at index 10 and finishes at index 12
You have to distinguish between two different "find" functions. The regex.e module has a namespace identifier, which in this case is regex, that can be used to uniquely identify find as as function in the regex.e module and not the built-in OpenEuphoria function. The default namespace identifier for each module is described in the Standard Library documentation.
The namespace identifer is a prefix before the original identifier name; use the colon (:) to join the two names together.
If you do not like a default namespace identifier you can invent your own:
include std/regex.e as re ? re:find( re:new("dog"), "cats and dogs" ) --> { {10,12} } -- as expected
It is now clear that re:new and re:find represent functions found in the regex.e module.
All built-in identifiers belong to the eu namespace.
For example if you do not like the built-in print function you can write:
procedure print( object stuff ) eu:print(1, stuff ) end procedure print( 123 ) --> 123 -- success! -- you no longer need the argument "1" eu:print(1, 456 ) --> 456 -- success! -- the original print function still works
The OpenEuphoria namespace design is simple and flexible.
Personalized Modules
When creating a personalized module you can assign a default namespace. Write the keyword namespace followed by the identifier you want to use; place this line as the first executable statement of your module. You can ignore the namespace identifier in most cases. You can override a default namespace identifier in the main program using this syntax: include module.e as my_new_namepace_name.
Use the keyword public before each module you want. Without the public keyword the contents of the modules will not be visible to the main program.
Some identifiers in the Standard Library are duplicated; use the namespace prefixes to distinguish between these identifiers. Comments following module names recognize identifiers that may cause conflicts.
You can give any name you wish to your modules and default namespaces; the sample names are just a suggestion.
Modules can contain other modules. For example:
-- everything.e -- list of modules that contain other modules public include general.e public include string.e public include sequence.e -- ... add more as needed
The following examples can be used as a basis for designing your own personalized modules. Cut and paste to create your ideal module system:
General Modules
-- general.e namespace gen --> possible duplicates <-- competing modules public include std/cmdline.e --> parse public include std/console.e public include std/datetime.e --> datetime, format public include std/filesys.e public include std/io.e --> STDERR, STDIN, STDOUT public include std/os.e public include std/pipeio.e --> close, create, wrap public include std/pretty.e public include std/task.e public include std/types.e public include std/utils.e
Sequence Modules
-- sequence.e namespace seq public include std/convert.e public include std/get.e public include std/search.e public include std/sequence.e public include std/serialize.e public include std/sort.e
String Modules
-- string.e namespace str public include std/locale.e --> datetime, get, set public include std/localeconv.e public include std/regex.e --> escape, find, find_all, find_replace, new, split public include std/text.e --> escape, format, wrap public include std/wildcard.e public include std/base64.e --> is_match
Math Modules
-- maths.e namespace mat public include std/math.e --> size, sum <-- stats.e public include std/mathcons.e public include std/rand.e public include std/stats.e --> size, sum <-- math.e
Data Modules
-- data.e namespace dat public include std/eds.e public include std/primes.e public include std/flags.e public include std/hash.e public include std/map.e --> clear, compare, map, new, remove public include std/stack.e --> clear, new, set
Network Modules
-- network.e namespace net public include std/socket.e --> close, create public include std/net/common.e --> URL_PROTOCOL public include std/net/dns.e public include std/net/http.e public include std/net/url.e --> decode, parse, URL_PROTOCOL
Low Level Modules
-- lowlevel.e namespace low public include std/dll.e public include std/error.e public include std/eumem.e --> free <-- machine.e public include std/machine.e --> free <-- eumem.e public include std/memconst.e
Graphic Modules
-- graphic.e namespace gra public include std/graphcst.e public include std/graphics.e --> wrap <-- text.e public include std/image.e
Euphoria Modules
-- euphoria.e namespace oe public include euphoria/info.e public include euphoria/keywords.e public include euphoria/syncolor.e --> keep_newlines, new, reset public include euphoria/tokenize.e --> keep_newlines, new, reset public include std/unittest.e public include euphoria/debug/debug.e
Windows Modules
-- win32.e namespace win public include std/win32/msgbox.e public include std/win32/sounds.e