Just An Application

June 11, 2013

Programming With Rust — Part Three: Things We Need To Know – Modules

1.0 Modules

A Rust module defines both a namespace and an access-control boundary.

In this example

    mod fish
    {
        enum FlatFish
        {
            Dab,
            Halibut,
            Flounder,
            Sole,
            Turbot
        }
    }

the type FlatFish could be referenced from within the fish module using the identifier FlatFish.

However it is not visible outside the module.

2.0 Access Control

To make it visible it is necessary to make it public it like this.

    mod fish
    {
        pub enum FlatFish
        {
            Dab,
            Halibut,
            Flounder,
            Sole,
            Turbot
        }
    }

The FlatFish type can now be referenced from other modules.

3.0 Paths

Now that the FlatFish type is public it can be referenced from outside the fish module using its path, that is, its fully qualified name, which is

    fish::FlatFish

4.0 Name Binding

Alternatively the name FlatFish can be bound locally in another module like this

    use fish::FlatFish;

Now the local name FlatFish can be used to reference the name FlatFish in the fish module.

5.0 Nested Modules

Modules can be nested.

For example

    mod underwater_creatures
    {
        mod fish
        {
            pub enum FlatFish
            {
                Dab,
                Halibut,
                Flounder,
                Sole,
                Turbot
            }
        }
    }

The path of the FlatFish type is, as you might expect

    underwater_creatures::fish::FlatFish

and to bind the name FlatFish locally you do this

    use underwater_creatures::fish::FlatFish;

6.0 Binding Module Names

You can also bind the name of a module locally, but visibility constraints apply to modules as well.

Given the example above you cannot do this

    use underwater_creatures::fish;

because the fish module is not public.

If the fish module is made public

    mod underwater_creatures
    {
        pub mod fish
        {
            pub enum FlatFish
            {
                Dab,
                Halibut,
                Flounder,
                Sole,
                Turbot
            }
        }
    }

then you can do this

    use underwater_creatures::fish;

and you can then refer to the FlatFish type using the path

    fish::FlatFish

This is useful if you want to use a prefix to qualify a name either to avoid name clashes and/or to identify where the name is from, but you do not want to use its path because of its length.

7.0 Aliasing

A name can be bound to an alias like this

    use ff = fish::FlatFish;

Now the local name ff can be used to reference the name FlatFish in the fish module.

8.0 Access Control And Name Bindings

By default name bindings are not visible outside the module in which they occur, but they can be made public in the same way
as enum types and modules.

The effect of doing this is that the local name is now visible outside the module and it in turn can now be referenced using its path and bound to a local name in another module and so on.

For example, if we do this

    mod underwater_creatures
    {
        pub use underwater_creatures::fish::FlatFish;
    
        mod fish
        {
            pub enum FlatFish
            {
                Dab,
                Flounder,
                Halibut,
                Sole,
                Turbot
            }
        }
    }

then you can use the path

   underwater_creatures::FlatFish

to reference the FlatFish type.

Alternatively you can bind the name locally like this

   use underwater_creatures::FlatFish

and the local name FlatFish will reference the FlatFish type.

Using aliasing in conjunction with a public name binding it is possible to re-name things in very confusing ways if you choose to do so.

For example,

    mod underwater_creatures
    {
        pub use FlatFish = underwater_creatures::fish::OtherFish;
    
        mod fish
        {
            pub enum FlatFish
            {
                Dab,
                Flounder,
                Halibut,
                Sole,
                Turbot
            }
        
            pub enum OtherFish
            {
                Perch,
                Roach,
                Tench
            }
        }
    }

Now the path

   underwater_creatures::FlatFish

references the OtherFish type in the fish module.


Copyright (c) 2013 By Simon Lewis. All Rights Reserved.

Unauthorized use and/or duplication of this material without express and written permission from this blog’s author and owner Simon Lewis is strictly prohibited.

Excerpts and links may be used, provided that full and clear credit is given to Simon Lewis and justanapplication.wordpress.com with appropriate and specific direction to the original content.

Advertisements

2 Comments »

  1. […] make use of the definitions in the externally linked crates we set up some name bindings like […]

    Pingback by Programming With Rust — Part Nine: Let’s Build A Program | Just An Application — June 14, 2013 @ 2:16 pm


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: