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 


Quick Links

User menu

Not signed in.

Misc Menu