Rust模块

一、模块
模块是用于在crate内部继续进行分层和封装的机制。模块内部又可以包含模块。Rust中的模块是一个典型的树形结构。每个crate会自动产生一个跟当前crate同名的模块，作为这个树形结构的根节点。

模块是item的集合，item可以是：函数，结构体，trait，impl 块，甚至其它模块。

模块是一种抽象的概念，文件是承载这个概念的实体。但是模块和文件并不是简单的一一对应关系，用户可以自己维护这个映射关系。

在一个crate内部创建新模块有以下方式：

1. 一个文件中创建内嵌模块。直接使用mod关键字即可，模块内容包含到大括号内部。
2. 独立的一个文件就是一个模块。文件名即是模块名。
3. 一个文件夹也可以创建一个模块。文件夹内部要有一个mod.rs文件，这个文件就是这个模块的入口。

二、可见性
模块的可见性分为私有和公开两种。默认情况下是私有。
公开和私有的访问权限规则如下：

1. 如果一个元素是私有的，那么只有本模块内的元素以及它的子模块可以访问。
2. 如果一个元素是公开的，那么上一层的模块就有权访问它。

以下是代码样例：

// 一个名为 `my_mod` 的模块
mod my_mod {
    // 模块中的项默认具有私有的可见性
    fn private_function() {
        println!("called `my_mod::private_function()`");
    }

    // 使用 `pub` 修饰语来改变默认可见性。
    pub fn function() {
        println!("called `my_mod::function()`");
    }

    // 在同一模块中，项可以访问其它项，即使它是私有的。
    pub fn indirect_access() {
        print!("called `my_mod::indirect_access()`, that\n> ");
        private_function();
    }

    // 模块也可以嵌套
    pub mod nested {
        pub fn function() {
            println!("called `my_mod::nested::function()`");
        }

        #[allow(dead_code)]
        fn private_function() {
            println!("called `my_mod::nested::private_function()`");
        }

        // 使用 `pub(in path)` 语法定义的函数只在给定的路径中可见。
        // `path` 必须是父模块（parent module）或祖先模块（ancestor module）
        pub(in crate::my_mod) fn public_function_in_my_mod() {
            print!("called `my_mod::nested::public_function_in_my_mod()`, that\n > ");
            public_function_in_nested()
        }

        // 使用 `pub(self)` 语法定义的函数则只在当前模块中可见。
        pub(self) fn public_function_in_nested() {
            println!("called `my_mod::nested::public_function_in_nested");
        }

        // 使用 `pub(super)` 语法定义的函数只在父模块中可见。
        pub(super) fn public_function_in_super_mod() {
            println!("called my_mod::nested::public_function_in_super_mod");
        }
    }

    pub fn call_public_function_in_my_mod() {
        print!("called `my_mod::call_public_funcion_in_my_mod()`, that\n> ");
        nested::public_function_in_my_mod();
        print!("> ");
        nested::public_function_in_super_mod();
    }

    // `pub(crate)` 使得函数只在当前 crate 中可见
    pub(crate) fn public_function_in_crate() {
        println!("called `my_mod::public_function_in_crate()");
    }

    // 嵌套模块的可见性遵循相同的规则
    mod private_nested {
        #[allow(dead_code)]
        pub fn function() {
            println!("called `my_mod::private_nested::function()`");
        }
    }
}

fn function() {
    println!("called `function()`");
}

fn main() {
    // 模块机制消除了相同名字的项之间的歧义。
    function();
    my_mod::function();

    // 公有项，包括嵌套模块内的，都可以在父模块外部访问。
    my_mod::indirect_access();
    my_mod::nested::function();
    my_mod::call_public_function_in_my_mod();

    // pub(crate) 项可以在同一个 crate 中的任何地方访问
    my_mod::public_function_in_crate();

    // pub(in path) 项只能在指定的模块中访问
    // 报错！函数 `public_function_in_my_mod` 是私有的
    //my_mod::nested::public_function_in_my_mod();

    // 模块的私有项不能直接访问，即便它是嵌套在公有模块内部的

    // 报错！`private_function` 是私有的
    //my_mod::private_function();

    // 报错！`private_function` 是私有的
    //my_mod::nested::private_function();

    // Error! `private_nested` is a private module
    //my_mod::private_nested::function();
}

三、use关键字
use声明可以将一个完整的路径绑定到一个新的名字，如果我们需要经常重复性地写很长的路径，那么可以使用use语句把相应的元素引入到当前的作用域中来，从而更容易访问

use语句的通常有以下几种使用方法：

1. use语句可以用大括号，一句话引入多个元素，如：use std::io::{self, Read, Write}; 这个语句引入了io / Read / Write 三个名字。
2. use语句的大括号可以嵌套使用，如：use a:️:{c, d, e::{f, g::{h, i}} }。
3. use语句可以使用星号，引入所有的元素，如：use std::io::prelude:; 这个语句引入了 std::io::prelude下面所有的名字。
4. use语句不仅可以用在模块中，还可以用在函数、trait、impl等地方。
5. use语句允许使用as重命名，避免名字冲突。

以下是代码样例：

// 将 `deeply::nested::function` 路径绑定到 `other_function`。
use deeply::nested::function as other_function;

fn function() {
    println!("called `function()`");
}

mod deeply {
    pub mod nested {
        pub fn function() {
            println!("called `deeply::nested::function()`")
        }
    }
}

fn main() {
    // 更容易访问 `deeply::nested::funcion`
    other_function();

    println!("Entering block");
    {
        // 这和 `use deeply::nested::function as function` 等价。
        // 此 `function()` 将遮蔽外部的同名函数。
        use deeply::nested::function;
        function();

        // `use` 绑定拥有局部作用域。在这个例子中，`function()`的遮蔽只存在这个代码块中。
        println!("Leaving block");
    }

    function();
}

四、模块路径
Rust里面的路径有不同写法，它们代表的含义如下：

1. 以crate::开头的路径，代表全局路径。它是从crate的根部开始算的。
2. 以super关键字开头的路径是相对路径。它是从上层模块开始算的。
3. 以self关键字开头的路径是相对路径。它是从当前模块开始算的。

以下是代码样例：

 fn function() {
    println!("called `function()`");
}

mod cool {
    pub fn function() {
        println!("called `cool::function()`");
    }
}

mod my {
    fn function() {
        println!("called `my::function()`");
    }

    mod cool {
        pub fn function() {
            println!("called `my::cool::function()`");
        }
    }

    pub fn indirect_call() {
        // 让我们从这个作用域中访问所有名为 `function` 的函数！
        println!("called `my::indirect_call()`, that\n ");

        // self关键字路径
        self::function();
        function();

        // self关键字路径
        self::cool::function();

        // super关键字路径
        super::function();

        // crate::作用域。
        {
            use crate::cool::function as root_function;
            root_function();
        }
    }
}

fn main() {
    my::indirect_call();
}