OpenEuphoria

1. confusion about include

• Posted by Jerry_Story Aug 07, 2010
• 1345 views

The Euphoria 4.0 documentation, under "4.8.1 include" does not clearly explain "public" and "export".

What exactly do these lines do?

include file1.e 
public include file2.e 
export include file3.e 
-- Is there such a thing as global include file4.e 

It used to be simple. Include something and it's included for all my files. What do I gotta do to make it work like it used to?

3. Re: confusion about include

• Posted by Jerry_Story Aug 07, 2010
• 1341 views

In the good old days when Euphoria was simple, 'include' included files for the entire rest of the program. So I could do this:

-- main file 
include GtkEngine.e 
include myfile1.e  -- GtkEngine.e would be recognized in each of these files. 
include myfile2.e 
include myfile3.e 
 
-- bunchuv code 
 
-- end main file 

Now it's different:

-- main file 
include GtkEngine.e 
include myfile1.e  -- GtkEngine.e must be included in each of these files. 
include myfile2.e 
include myfile3.e 
 
-- bunchuv code 
 
-- end main file 

Is there a way to do 'include' in Euphoria 4.0 that works the same way as 'include' in Euphoria 3.1?

5. Re: confusion about include

• Posted by DerekParnell (admin) Aug 07, 2010
• 1302 views

include file1.e 
public include file2.e 
export include file3.e 
-- Is there such a thing as global include file4.e 

OK, I'll have a go at an explanation of how and why it works the way it does now.

This will be a lot of words but it's not really that complex is when you come to use it.

A bit if background first ...

Scope

A scope is block of code that can access a symbol. There are five levels of scoping in which symbols can be declared ...

1. Application
2. File (module)
3. Routine
4. if ... end if (Not in v3)
5. loops (Only for ... end for in V3)

Version 3 Scope

A symbol is either private or global. It is private if it does not have the global keyword before the declaration.

The effect of these rules is that if a library writer wants applications to access a symbol in the library file. that symbol must be declared as 'global'. The side effect of this is that the symbol is now accessible by all modules in the application, and that can lead to interpreter errors when multiple libraries just happen to use the same 'global' identifier name. Most of these situations can be worked around by using the namespace qualifier but some situations can only be fixed by editing a third party library.

In other words, if your application includes AA.E then all global symbols, and only global symbols, declared inside AA.E can be accessed by your application. Furthermore, global symbols declared inside files that are in turn included inside AA.E are also accessible to your application. So if AA.E includes BB.E then your application can also see the globals declared inside BB.EE

Now consider large libraries like Win32Lib. This library consists of many files, some of which have symbols declared for internal usage only and applications are not really supposed to have access them. But in V3, you need 'global' to expose these internal-use symbols to other files within the library, and this inadvertently exposes them to the application and third-party included files too.

Version 4 Scope

The private and global scopes still exist with identical semantics in V4. However, additionally V4 has public symbols. A public symbol can only be declared at the file scope level and makes the symbol accessible by anything in the same file and by any file the directly includes it. Its kind of like the visibility is raised one level only.

For example, if CC.E declares a public symbol FOO and BB.E includes CC.E, then code in BB.E can access FOO. But if AA.E includes BB.E then code in AA.E cannot see FOO.

Let's go back to the Win32Lib library. In version 4, an application that wants to use the library has

include win32lib.ew 

Now if win32lib.ew includes a file called structure.ew that has public symbols declared (eg. public function acquire_mem() ) it means that code in win32lib.ew can use acquire_mem(). Now, as that is a public symbol it means that the application cannot see the function, which is not the desired result.

In V4, we have introduced the public include statement. This has the effect of propagating any public symbols visible in the included file up one more level. So, in our example, win32lib.ew actually has public include structure.ew, which means that not only can code in win32lib.ew see the function, so can anything that includes win32lib.ew. It is not like global in that this propagation goes up one level only and not all levels.

By using public declared symbols, we decrease the chance of accidental name clashes between third party libraries.

Again, returning to the Win32LIb library. While the public include concept solves one problem for us, it doesn't solve the issue of preventing internal-use symbols from being exposed to applications. To overcome this, V4 has a slight variant of the public declared symbol; it can declare a symbol as export rather than public. The only difference is that export symbols are not propagated by the public include statement whereas public symbols are.

All these new refinements of scope are really of interest to library writers only. People writing applications would just use the simple include statement to get access to a library's API. Library writer would declare symbols as export if they are only intended to be used within a multi-file library's own include files, otherwise they would declare all symbols needed by an application as public and use the public include for its own internal include files.

global

After decades of computer programming research, it has been shown that 'global' symbols should be avoided because they increase maintenance costs and increase the chance of bugs. This will become increasingly obvious as multi-core architectures split an application up into parallel tasks, which frown on having shared symbols between tasks. I can envisage that a future version of Euphoria will implement multi-core support with symbols being 'thread-safe' by default and using 'global' symbols as shared data between threads.

I told a slight untruth before. In V4, the semantics of 'global' is a little different. Visibility is strictly limited to a reference's include tree. Let me illustrate...

The file DD.E contains the declaration global constant foo ... and BB.E includes DD.E so it can use its foo symbol. No problem there. Furthermore the file EE.E contains the declaration global procedure foo( ) and CC.E includes EE.E so it can use its foo symbol. Still no problem. Now, AA.EX includes BB.E. Still no problem. But when AA.EX also includes CC.E, version 3 Euphoria has a problem. The interpreter no longer knows which 'foo' BB.E wants to use - the one in DD.E or the one in EE.E which has suddenly become exposed by including CC.E.

        ---DD.E----------------                 ---EE.E------------------- 
        global constant foo = 1                 global function foo() ... 
        -----------------------                 -------------------------- 
                  |                                   | 
                  |                                   |  
                  v                                   v 
            ---BB.E-------------             ---CC.E-----------      
            include DD.E                     include EE.E 
            constant x = foo                 constant y = foo() 
            --------------------             ------------------ 
                       \                           / 
                        \                         / 
                         \                       / 
                          v                     v 
                         -----------AA.EX------------ 
                                 include BB.E 
                                 include CC.E 
                         ---------------------------- 

The version 3 interpreter allows BB.E to see the 'foo' declared in EE.E, even though it is not in the same include tree. In version 4, the interpreter realizes that BB.E doesn't know that CC.E, and thus EE.E, even exists so it doesn't raise a name clash error in BB.E (or CC.E for that matter).

Of course, a V4 library would be using public rather than global so it would never had been a problem anyway.

Cheating the System

Of course, if you want to revert to the poorer coding style of not having to directly include only the files that your application is using, there is a trick.

Create a file, let's call it ALL.E for this example, and let it only contain a list of public includes for the standard library ...

---- all.e ---- 
public include std/cmdline.e 
public include std/common.e 
public include std/complex.e 
public include std/console.e 
public include std/convert.e 
public include std/datetime.e 
public include std/dll.e 
public include std/eds.e 
public include std/error.e 
public include std/eumem.e 
public include std/filesys.e 
public include std/flags.e 
public include std/format.e 
public include std/get.e 
public include std/graphcst.e 
public include std/graphics.e 
public include std/image.e 
public include std/io.e 
public include std/lcid.e 
public include std/locale.e 
public include std/localeconv.e 
public include std/machine.e 
public include std/map.e 
public include std/math.e 
public include std/mathcons.e 
public include std/memconst.e 
public include std/memory.e 
public include std/mouse.e 
public include std/os.e 
public include std/pipeio.e 
public include std/pretty.e 
public include std/primes.e 
public include std/rand.e 
public include std/regex.e 
public include std/search.e 
public include std/sequence.e 
public include std/serialize.e 
public include std/sets.e 
public include std/socket.e 
public include std/sort.e 
public include std/stack.e 
public include std/stats.e 
public include std/task.e 
public include std/text.e 
public include std/types.e 
public include std/unittest.e 
public include std/utils.e 
public include std/wildcard.e 
-------------- 

Then all your applications ever have to include is ALL.E to get access to every public system in the standard library.

7. Re: confusion about include

• Posted by ChrisB (moderator) Aug 07, 2010
• 1261 views

include file1.e 
public include file2.e 
export include file3.e 
-- Is there such a thing as global include file4.e 

Hi

Still can keep it simple. Here's what I do, distilling out all the other stuff from Derek and Matt

1. old global still works, or use new export for functions / procedures / variables / constants (plea to devs - please make sure global stays working!) 2. for every 'new file' within your program, include the file that contains the function / procedure or global variable you want to access from your 'new file' 3. use of namespaces is entirely optional

Converted my 20000 + line vet program a while ago using these rules, and it works absolutely fine.

Someone is bound to say, 'yes, but what about the case when.....' - these are likely to be few and far between cases, and I'll cross those bridges when I come to them.

Chris

9. Re: confusion about include

• Posted by DerekParnell (admin) Aug 07, 2010
• 1253 views

There is no plan or intention to remove 'global' from the language.

• It is needed for backward compatibility
• It is needed for those coders who prefer that coding style
• It may be needed in future to support shared data between (true) threads.

11. Re: confusion about include

• Posted by DerekParnell (admin) Aug 07, 2010
• 1244 views

-- main file 
include GtkEngine.e 
include myfile1.e  -- GtkEngine.e would be recognized in each of these files. 
include myfile2.e 
include myfile3.e 
 
-- bunchuv code 
 
-- end main file 

-- main file 
include GtkEngine.e 
include myfile1.e  -- GtkEngine.e must be included in each of these files. 
include myfile2.e 
include myfile3.e 
 
-- bunchuv code 
 
-- end main file 

If the 'myfile' code is using stuff declared in GtkEngine.e and those declarations are 'public' or 'export' then yes, the 'myfile' files will need to directly include 'GtkEngine.e'.

Remember than the idea behind 'include' files is that these files are assumed to be re-usable modules that can be included into any file that needs access to the module's API. It is generally regarded as bad coding style to have implicit dependencies in a module on symbols declared outside the module. The 'global' concept allows that coding style if you want to use it though.

13. Re: confusion about include

• Posted by mattlewis (admin) Aug 07, 2010
• 1204 views

That hasn't changed. I think Derek mixed up private and local. Private symbols have scope inside of a routine. Local symbols are scoped to a file, and a local symbol takes precedence over an export, public or global symbols. Private symbols take precedence over all other symbols.

Matt

15. Re: confusion about include

• Posted by Jerry_Story Aug 07, 2010
• 1205 views

Thanks for the lengthy explanation. Could all that or something like that be added to the official Euphoria documentation?