@@ -239,13 +239,14 @@ literal : string_lit | char_lit | num_lit ;
239239
240240~~~~~~~~ {.ebnf .gram}
241241char_lit : '\x27' char_body '\x27' ;
242- string_lit : '"' string_body * '"' ;
242+ string_lit : '"' string_body * '"' | 'r' raw_string ;
243243
244244char_body : non_single_quote
245245 | '\x5c' [ '\x27' | common_escape ] ;
246246
247247string_body : non_double_quote
248248 | '\x5c' [ '\x22' | common_escape ] ;
249+ raw_string : '"' raw_string_body '"' | '#' raw_string '#' ;
249250
250251common_escape : '\x5c'
251252 | 'n' | 'r' | 't' | '0'
@@ -267,9 +268,10 @@ which must be _escaped_ by a preceding U+005C character (`\`).
267268
268269A _ string literal_ is a sequence of any Unicode characters enclosed within
269270two ` U+0022 ` (double-quote) characters, with the exception of ` U+0022 `
270- itself, which must be _ escaped_ by a preceding ` U+005C ` character (` \ ` ).
271+ itself, which must be _ escaped_ by a preceding ` U+005C ` character (` \ ` ),
272+ or a _ raw string literal_ .
271273
272- Some additional _ escapes_ are available in either character or string
274+ Some additional _ escapes_ are available in either character or non-raw string
273275literals. An escape starts with a ` U+005C ` (` \ ` ) and continues with one of
274276the following forms:
275277
@@ -285,9 +287,35 @@ the following forms:
285287 * A _ whitespace escape_ is one of the characters ` U+006E ` (` n ` ), ` U+0072 `
286288 (` r ` ), or ` U+0074 ` (` t ` ), denoting the unicode values ` U+000A ` (LF),
287289 ` U+000D ` (CR) or ` U+0009 ` (HT) respectively.
288- * The _ backslash escape_ is the character U+005C (` \ ` ) which must be
290+ * The _ backslash escape_ is the character ` U+005C ` (` \ ` ) which must be
289291 escaped in order to denote * itself* .
290292
293+ Raw string literals do not process any escapes. They start with the character
294+ ` U+0072 ` (` r ` ), followed zero or more of the character ` U+0023 ` (` # ` ) and a
295+ ` U+0022 ` (double-quote) character. The _ raw string body_ is not defined in the
296+ EBNF grammar above: it can contain any sequence of Unicode characters and is
297+ terminated only by another ` U+0022 ` (double-quote) character, followed by the
298+ same number of ` U+0023 ` (` # ` ) characters that preceeded the opening ` U+0022 `
299+ (double-quote) character.
300+
301+ All Unicode characters contained in the raw string body represent themselves,
302+ the characters ` U+0022 ` (double-quote) (except when followed by at least as
303+ many ` U+0023 ` (` # ` ) characters as were used to start the raw string literal) or
304+ ` U+005C ` (` \ ` ) do not have any special meaning.
305+
306+ Examples for string literals:
307+
308+ ~~~
309+ "foo"; r"foo"; // foo
310+ "\"foo\""; r#""foo""#; // "foo"
311+
312+ "foo #\"# bar";
313+ r##"foo #"# bar"##; // foo #"# bar
314+
315+ "\x52"; "R"; r"R"; // R
316+ "\\x52"; r"\x52"; // \x52
317+ ~~~
318+
291319#### Number literals
292320
293321~~~~~~~~ {.ebnf .gram}
@@ -1501,6 +1529,171 @@ is `extern "abi" fn(A1, ..., An) -> R`,
15011529where ` A1...An ` are the declared types of its arguments
15021530and ` R ` is the decalred return type.
15031531
1532+ ## Visibility and Privacy
1533+
1534+ These two terms are often used interchangeably, and what they are attempting to
1535+ convey is the answer to the question "Can this item be used at this location?"
1536+
1537+ Rust's name resolution operates on a global hierarchy of namespaces. Each level
1538+ in the hierarchy can be thought of as some item. The items are one of those
1539+ mentioned above, but also include external crates. Declaring or defining a new
1540+ module can be thought of as inserting a new tree into the hierarchy at the
1541+ location of the definition.
1542+
1543+ To control whether interfaces can be used across modules, Rust checks each use
1544+ of an item to see whether it should be allowed or not. This is where privacy
1545+ warnings are generated, or otherwise "you used a private item of another module
1546+ and weren't allowed to."
1547+
1548+ By default, everything in rust is * private* , with two exceptions. The first
1549+ exception is that struct fields are public by default (but the struct itself is
1550+ still private by default), and the remaining exception is that enum variants in
1551+ a ` pub ` enum are the default visibility of the enum container itself.. You are
1552+ allowed to alter this default visibility with the ` pub ` keyword (or ` priv `
1553+ keyword for struct fields and enum variants). When an item is declared as ` pub ` ,
1554+ it can be thought of as being accessible to the outside world. For example:
1555+
1556+ ~~~
1557+ // Declare a private struct
1558+ struct Foo;
1559+
1560+ // Declare a public struct with a private field
1561+ pub struct Bar {
1562+ priv field: int
1563+ }
1564+
1565+ // Declare a public enum with public and private variants
1566+ pub enum State {
1567+ PubliclyAccessibleState,
1568+ priv PrivatelyAccessibleState
1569+ }
1570+ ~~~
1571+
1572+ With the notion of an item being either public or private, Rust allows item
1573+ accesses in two cases:
1574+
1575+ 1 . If an item is public, then it can be used externally through any of its
1576+ public ancestors.
1577+ 2 . If an item is private, it may be accessed by the current module and its
1578+ descendants.
1579+
1580+ These two cases are surprisingly powerful for creating module hierarchies
1581+ exposing public APIs while hiding internal implementation details. To help
1582+ explain, here's a few use cases and what they would entail.
1583+
1584+ * A library developer needs to expose functionality to crates which link against
1585+ their library. As a consequence of the first case, this means that anything
1586+ which is usable externally must be ` pub ` from the root down to the destination
1587+ item. Any private item in the chain will disallow external accesses.
1588+
1589+ * A crate needs a global available "helper module" to itself, but it doesn't
1590+ want to expose the helper module as a public API. To accomplish this, the root
1591+ of the crate's hierarchy would have a private module which then internally has
1592+ a "public api". Because the entire crate is an ancestor of the root, then the
1593+ entire local crate can access this private module through the second case.
1594+
1595+ * When writing unit tests for a module, it's often a common idiom to have an
1596+ immediate child of the module to-be-tested named ` mod test ` . This module could
1597+ access any items of the parent module through the second case, meaning that
1598+ internal implementation details could also be seamlessly tested from the child
1599+ module.
1600+
1601+ In the second case, it mentions that a private item "can be accessed" by the
1602+ current module and its descendants, but the exact meaning of accessing an item
1603+ depends on what the item is. Accessing a module, for example, would mean looking
1604+ inside of it (to import more items). On the other hand, accessing a function
1605+ would mean that it is invoked.
1606+
1607+ Here's an example of a program which exemplifies the three cases outlined above.
1608+
1609+ ~~~
1610+ // This module is private, meaning that no external crate can access this
1611+ // module. Because it is private at the root of this current crate, however, any
1612+ // module in the crate may access any publicly visible item in this module.
1613+ mod crate_helper_module {
1614+
1615+ // This function can be used by anything in the current crate
1616+ pub fn crate_helper() {}
1617+
1618+ // This function *cannot* be used by anything else in the crate. It is not
1619+ // publicly visible outside of the `crate_helper_module`, so only this
1620+ // current module and its descendants may access it.
1621+ fn implementation_detail() {}
1622+ }
1623+
1624+ // This function is "public to the root" meaning that it's available to external
1625+ // crates linking against this one.
1626+ pub fn public_api() {}
1627+
1628+ // Similarly to 'public_api', this module is public so external crates may look
1629+ // inside of it.
1630+ pub mod submodule {
1631+ use crate_helper_module;
1632+
1633+ pub fn my_method() {
1634+ // Any item in the local crate may invoke the helper module's public
1635+ // interface through a combination of the two rules above.
1636+ crate_helper_module::crate_helper();
1637+ }
1638+
1639+ // This function is hidden to any module which is not a descendant of
1640+ // `submodule`
1641+ fn my_implementation() {}
1642+
1643+ #[cfg(test)]
1644+ mod test {
1645+
1646+ #[test]
1647+ fn test_my_implementation() {
1648+ // Because this module is a descendant of `submodule`, it's allowed
1649+ // to access private items inside of `submodule` without a privacy
1650+ // violation.
1651+ super::my_implementation();
1652+ }
1653+ }
1654+ }
1655+
1656+ # fn main() {}
1657+ ~~~
1658+
1659+ For a rust program to pass the privacy checking pass, all paths must be valid
1660+ accesses given the two rules above. This includes all use statements,
1661+ expressions, types, etc.
1662+
1663+ ### Re-exporting and Visibility
1664+
1665+ Rust allows publicly re-exporting items through a ` pub use ` directive. Because
1666+ this is a public directive, this allows the item to be used in the current
1667+ module through the rules above. It essentially allows public access into the
1668+ re-exported item. For example, this program is valid:
1669+
1670+ ~~~
1671+ pub use api = self::implementation;
1672+
1673+ mod implementation {
1674+ pub fn f() {}
1675+ }
1676+
1677+ # fn main() {}
1678+ ~~~
1679+
1680+ This means that any external crate referencing ` implementation::f ` would receive
1681+ a privacy violation, while the path ` api::f ` would be allowed.
1682+
1683+ When re-exporting a private item, it can be thought of as allowing the "privacy
1684+ chain" being short-circuited through the reexport instead of passing through the
1685+ namespace hierarchy as it normally would.
1686+
1687+ ### Glob imports and Visibility
1688+
1689+ Currently glob imports are considered an "experimental" language feature. For
1690+ sanity purpose along with helping the implementation, glob imports will only
1691+ import public items from their destination, not private items.
1692+
1693+ > ** Note:** This is subject to change, glob exports may be removed entirely or
1694+ > they could possibly import private items for a privacy error to later be
1695+ > issued if the item is used.
1696+
15041697## Attributes
15051698
15061699~~~~~~~~ {.ebnf .gram}
@@ -1775,6 +1968,7 @@ Supported traits for `deriving` are:
17751968 ` obj.to_str() ` has similar output as ` fmt!("%?", obj) ` , but it differs in that
17761969 each constituent field of the type must also implement ` ToStr ` and will have
17771970 ` field.to_str() ` invoked to build up the result.
1971+ * ` FromPrimitive ` , to create an instance from a numeric primitve.
17781972
17791973### Stability
17801974One can indicate the stability of an API using the following attributes:
@@ -1832,6 +2026,58 @@ fn main() {
18322026> individual functions, structs, methods and enum variants, * not* to
18332027> entire modules, traits, impls or enums themselves.
18342028
2029+ ### Compiler Features
2030+
2031+ Certain aspects of Rust may be implemented in the compiler, but they're not
2032+ necessarily ready for every-day use. These features are often of "prototype
2033+ quality" or "almost production ready", but may not be stable enough to be
2034+ considered a full-fleged language feature.
2035+
2036+ For this reason, rust recognizes a special crate-level attribute of the form:
2037+
2038+ ~~~ {.xfail-test}
2039+ #[feature(feature1, feature2, feature3)]
2040+ ~~~
2041+
2042+ This directive informs the compiler that the feature list: ` feature1 ` ,
2043+ ` feature2 ` , and ` feature3 ` should all be enabled. This is only recognized at a
2044+ crate-level, not at a module-level. Without this directive, all features are
2045+ considered off, and using the features will result in a compiler error.
2046+
2047+ The currently implemented features of the compiler are:
2048+
2049+ * ` macro_rules ` - The definition of new macros. This does not encompass
2050+ macro-invocation, that is always enabled by default, this only
2051+ covers the definition of new macros. There are currently
2052+ various problems with invoking macros, how they interact with
2053+ their environment, and possibly how they are used outside of
2054+ location in which they are defined. Macro definitions are
2055+ likely to change slightly in the future, so they are currently
2056+ hidden behind this feature.
2057+
2058+ * ` globs ` - Importing everything in a module through ` * ` . This is currently a
2059+ large source of bugs in name resolution for Rust, and it's not clear
2060+ whether this will continue as a feature or not. For these reasons,
2061+ the glob import statement has been hidden behind this feature flag.
2062+
2063+ * ` struct_variant ` - Structural enum variants (those with named fields). It is
2064+ currently unknown whether this style of enum variant is as
2065+ fully supported as the tuple-forms, and it's not certain
2066+ that this style of variant should remain in the language.
2067+ For now this style of variant is hidden behind a feature
2068+ flag.
2069+
2070+ If a feature is promoted to a language feature, then all existing programs will
2071+ start to receive compilation warnings about #[ feature] directives which enabled
2072+ the new feature (because the directive is no longer necessary). However, if
2073+ a feature is decided to be removed from the language, errors will be issued (if
2074+ there isn't a parser error first). The directive in this case is no longer
2075+ necessary, and it's likely that existing code will break if the feature isn't
2076+ removed.
2077+
2078+ If a unknown feature is found in a directive, it results in a compiler error. An
2079+ unknown feature is one which has never been recognized by the compiler.
2080+
18352081# Statements and expressions
18362082
18372083Rust is _ primarily_ an expression language. This means that most forms of
0 commit comments