as
break
crate
-do
else enum extern
false fn for
if impl in
let loop
match mod mut
-priv pub
+priv proc pub
ref return
self static struct super
true trait type
## Paths
~~~~ {.notrust .ebnf .gram}
-expr_path : ident [ "::" expr_path_tail ] + ;
+expr_path : [ "::" ] ident [ "::" expr_path_tail ] + ;
expr_path_tail : '<' type_expr [ ',' type_expr ] + '>'
| expr_path ;
# }
~~~~
+Paths can be denoted with various leading qualifiers to change the meaning of
+how it is resolved:
+
+* Paths starting with `::` are considered to be global paths where the
+ components of the path start being resolved from the crate root. Each
+ identifier in the path must resolve to an item.
+
+ ```rust
+ mod a {
+ pub fn foo() {}
+ }
+ mod b {
+ pub fn foo() {
+ ::a::foo(); // call a's foo function
+ }
+ }
+ # fn main() {}
+ ```
+
+* Paths starting with the keyword `super` begin resolution relative to the
+ parent module. Each further identifier must resolve to an item
+
+ ```rust
+ mod a {
+ pub fn foo() {}
+ }
+ mod b {
+ pub fn foo() {
+ super::a::foo(); // call a's foo function
+ }
+ }
+ # fn main() {}
+ ```
+
+* Paths starting with the keyword `self` begin resolution relative to the
+ current module. Each further identifier must resolve to an item.
+
+ ```rust
+ fn foo() {}
+ fn bar() {
+ self::foo();
+ }
+ # fn main() {}
+ ```
+
# Syntax extensions
A number of minor features of Rust are not central enough to have their own
Attributes on the anonymous crate module define important metadata that influences
the behavior of the compiler.
-~~~~
+~~~~ {.rust}
// Crate ID
#![crate_id = "projx#2.5"]
An example of what will and will not work for `use` items:
~~~~
-# #[allow(unused_imports)];
+# #![allow(unused_imports)]
use foo::native::start; // good: foo is at the root of the crate
use foo::baz::foobaz; // good: foo is at the root of the crate
Cat { name: ~str, weight: f64 }
}
-let mut a: Animal = Dog(~"Cocoa", 37.2);
-a = Cat{ name: ~"Spotty", weight: 2.7 };
+let mut a: Animal = Dog("Cocoa".to_owned(), 37.2);
+a = Cat{ name: "Spotty".to_owned(), weight: 2.7 };
~~~~
In this example, `Cat` is a _struct-like enum variant_,
and are instead terminated by a semicolon.
~~~~
-# use std::libc::{c_char, FILE};
+extern crate libc;
+use libc::{c_char, FILE};
extern {
fn fopen(filename: *c_char, mode: *c_char) -> *FILE;
}
+# fn main() {}
~~~~
Functions within external blocks may be called by Rust code,
field: int
}
-// Declare a public enum with public and private variants
+// Declare a public enum with two public variants
pub enum State {
PubliclyAccessibleState,
- priv PrivatelyAccessibleState
+ PubliclyAccessibleState2,
}
~~~~
~~~~
Static entities in Rust -- crates, modules and items -- may have _attributes_
-applied to them. Attributes in Rust are modeled on Attributes in ECMA-335, C#.
-An attribute is a general, free-form metadatum that is interpreted according
-to name, convention, and language and compiler version. Attributes may appear
-as any of:
+applied to them. Attributes in Rust are modeled on Attributes in ECMA-335,
+with the syntax coming from ECMA-334 (C#). An attribute is a general,
+free-form metadatum that is interpreted according to name, convention, and
+language and compiler version. Attributes may appear as any of:
* A single identifier, the attribute name
* An identifier followed by the equals sign '=' and a literal, providing a
Attributes with a bang ("!") after the hash ("#") apply to the item that the
attribute is declared within. Attributes that do not have a bang after the
-hash by a semi-colon apply to the next item.
+hash apply to the item that follows the attribute.
An example of attributes:
-~~~~
+~~~~ {.rust}
// General metadata applied to the enclosing module or crate.
#![license = "BSD"]
// A lint attribute used to suppress a warning/error
#[allow(non_camel_case_types)]
-pub type int8_t = i8;
+type int8_t = i8;
~~~~
> **Note:** At some point in the future, the compiler will distinguish between
### Crate-only attributes
+- `crate_id` - specify the this crate's crate ID.
- `crate_type` - see [linkage](#linkage).
- `feature` - see [compiler features](#compiler-features).
+- `no_main` - disable emitting the `main` symbol. Useful when some other
+ object being linked to defines `main`.
- `no_start` - disable linking to the `native` crate, which specifies the
"start" language item.
-- `no_main` - disable emitting the `main` symbol. Useful when some
- other object being linked to defines `main`.
- `no_std` - disable linking to the `std` crate.
-- `crate_id` - specify the this crate's crate ID.
### Module-only attributes
-- `path` - specifies the file to load the module from. `#[path="foo.rs"] mod
- bar;` is equivalent to `mod bar { /* contents of foo.rs */ }`
- `macro_escape` - macros defined in this module will be visible in the
module's parent, after this module has been included.
- `no_implicit_prelude` - disable injecting `use std::prelude::*` in this
module.
+- `path` - specifies the file to load the module from. `#[path="foo.rs"] mod
+ bar;` is equivalent to `mod bar { /* contents of foo.rs */ }`. The path is
+ taken relative to the directory that the current module is in.
### Function-only attributes
-- `start` - indicates that this function should be used as the entry point,
- overriding the "start" language item. See the "start" [language
- item](#language-items) for more details.
-- `main` - indicates that this function should be passed to the entry point,
- rather than the function in the crate root named `main`.
- `macro_registrar` - when using loadable syntax extensions, mark this
function as the registration point for the current crate's syntax
extensions.
+- `main` - indicates that this function should be passed to the entry point,
+ rather than the function in the crate root named `main`.
+- `start` - indicates that this function should be used as the entry point,
+ overriding the "start" language item. See the "start" [language
+ item](#language-items) for more details.
### Static-only attributes
+- `address_insignificant` - references to this static may alias with
+ references to other statics, potentially of unrelated type.
- `thread_local` - on a `static mut`, this signals that the value of this
static may change depending on the current thread. The exact consequences of
this are implementation-defined.
-- `address_insignificant` - references to this static may alias with
- references to other statics, potentially of unrelated type.
### FFI attributes
On an `extern` block, the following attributes are interpreted:
-- `link` - indicate that a native library should be linked to for the
- declarations in this block to be linked correctly. See [external
- blocks](#external-blocks)
- `link_args` - specify arguments to the linker, rather than just the library
name and type. This is feature gated and the exact behavior is
implementation-defined (due to variety of linker invocation syntax).
+- `link` - indicate that a native library should be linked to for the
+ declarations in this block to be linked correctly. See [external
+ blocks](#external-blocks)
On declarations inside an `extern` block, the following attributes are
interpreted:
### Miscellaneous attributes
-- `simd` - on certain tuple structs, derive the arithmetic operators, which
- lower to the target's SIMD instructions, if any.
- `link_section` - on statics and functions, this specifies the section of the
object file that this item's contents will be placed into.
-- `static_assert` - on statics whose type is `bool`, terminates compilation
- with an error if it is not initialized to `true`.
-- `repr` - on C-like enums, this sets the underlying type used for
- representation. Useful for FFI.
+- `macro_export` - export a macro for cross-crate usage.
- `no_mangle` - on any item, do not apply the standard name mangling. Set the
symbol for this item to its identifier.
- `packed` - on structs or enums, eliminate any padding that would be used to
align fields.
+- `repr` - on C-like enums, this sets the underlying type used for
+ representation. Useful for FFI. Takes one argument, which is the primitive
+ type this enum should be represented for, or `C`, which specifies that it
+ should be the default `enum` size of the C ABI for that platform. Note that
+ enum representation in C is undefined, and this may be incorrect when the C
+ code is compiled with certain flags.
+- `simd` - on certain tuple structs, derive the arithmetic operators, which
+ lower to the target's SIMD instructions, if any.
+- `static_assert` - on statics whose type is `bool`, terminates compilation
+ with an error if it is not initialized to `true`.
- `unsafe_destructor` - allow implementations of the "drop" language item
where the type it is implemented for does not implement the "send" language
item.
- `unsafe_no_drop_flag` - on structs, remove the flag that prevents
destructors from being run twice. Destructors might be run multiple times on
the same object with this attribute.
-- `macro_export` - export a macro for cross-crate usage.
### Conditional compilation
* `deny(C)` signals an error after encountering a violation of `C`,
* `allow(C)` overrides the check for `C` so that violations will go
unreported,
- * `forbid(C)` is the same as `deny(C)`, but also forbids uses of
- `allow(C)` within the attribute.
+ * `forbid(C)` is the same as `deny(C)`, but also forbids changing the lint
+ level afterwards.
The lint checks supported by the compiler can be found via `rustc -W help`,
along with their default settings.
#### Built-in Traits
-`send`
+* `send`
: Able to be sent across task boundaries.
-`sized`
+* `sized`
: Has a size known at compile time.
-`copy`
+* `copy`
: Types that do not move ownership when used by-value.
-`share`
+* `share`
: Able to be safely shared between tasks when aliased.
-`drop`
+* `drop`
: Have destructors.
#### Operators
These language items are traits:
-`add`
+* `add`
: Elements can be added (for example, integers and floats).
-`sub`
+* `sub`
: Elements can be subtracted.
-`mul`
+* `mul`
: Elements can be multiplied.
-`div`
+* `div`
: Elements have a division operation.
-`rem`
+* `rem`
: Elements have a remainder operation.
-`neg`
+* `neg`
: Elements can be negated arithmetically.
-`not`
+* `not`
: Elements can be negated logically.
-`bitxor`
+* `bitxor`
: Elements have an exclusive-or operation.
-`bitand`
+* `bitand`
: Elements have a bitwise `and` operation.
-`bitor`
+* `bitor`
: Elements have a bitwise `or` operation.
-`shl`
+* `shl`
: Elements have a left shift operation.
-`shr`
+* `shr`
: Elements have a right shift operation.
-`index`
+* `index`
: Elements can be indexed.
-`eq`
+* `eq`
: Elements can be compared for equality.
-`ord`
+* `ord`
: Elements have a partial ordering.
-`deref`
+* `deref`
: `*` can be applied, yielding a reference to another type
-`deref_mut`
+* `deref_mut`
: `*` can be applied, yielding a mutable reference to another type
These are functions:
-`str_eq`
+* `str_eq`
: Compare two strings (`&str`) for equality.
-`uniq_str_eq`
+* `uniq_str_eq`
: Compare two owned strings (`~str`) for equality.
-`strdup_uniq`
+* `strdup_uniq`
: Return a new unique string
containing a copy of the contents of a unique string.
#### Types
-`unsafe`
+* `unsafe`
: A type whose contents can be mutated through an immutable reference
-`type_id`
+* `type_id`
: The type returned by the `type_id` intrinsic.
#### Marker types
These types help drive the compiler's analysis
-`covariant_type`
+* `covariant_type`
: The type parameter should be considered covariant
-`contravariant_type`
+* `contravariant_type`
: The type parameter should be considered contravariant
-`invariant_type`
+* `invariant_type`
: The type parameter should be considered invariant
-`covariant_lifetime`
+* `covariant_lifetime`
: The lifetime parameter should be considered covariant
-`contravariant_lifetime`
+* `contravariant_lifetime`
: The lifetime parameter should be considered contravariant
-`invariant_lifetime`
+* `invariant_lifetime`
: The lifetime parameter should be considered invariant
-`no_send_bound`
+* `no_send_bound`
: This type does not implement "send", even if eligible
-`no_copy_bound`
+* `no_copy_bound`
: This type does not implement "copy", even if eligible
-`no_share_bound`
+* `no_share_bound`
: This type does not implement "share", even if eligible
-`managed_bound`
+* `managed_bound`
: This type implements "managed"
-`fail_`
+* `fail_`
: Abort the program with an error.
-`fail_bounds_check`
+* `fail_bounds_check`
: Abort the program with a bounds check error.
-`exchange_malloc`
+* `exchange_malloc`
: Allocate memory on the exchange heap.
-`exchange_free`
+* `exchange_free`
: Free memory that was allocated on the exchange heap.
-`malloc`
+* `malloc`
: Allocate memory on the managed heap.
-`free`
+* `free`
: Free memory that was allocated on the managed heap.
> **Note:** This list is likely to become out of date. We should auto-generate it
string that will be displayed when the lint flags the use of an item.
~~~~ {.ignore}
-#[warn(unstable)];
+#![warn(unstable)]
#[deprecated="replaced by `best`"]
fn bad() {
~~~~ {.ignore}
# use std::task;
-# do task::spawn {
+# task::spawn(proc() {
([1, 2, 3, 4])[0];
(["a", "b"])[10]; // fails
-# }
+# })
~~~~
### Unary operator expressions
They are all written as prefix operators,
before the expression they apply to.
-`-`
+* `-`
: Negation. May only be applied to numeric types.
-`*`
+* `*`
: Dereference. When applied to a [pointer](#pointer-types) it denotes the pointed-to location.
For pointers to mutable locations, the resulting [lvalue](#lvalues-rvalues-and-temporaries) can be assigned to.
On non-pointer types, it calls the `deref` method of the `std::ops::Deref` trait, or the
for an outer expression that will or could mutate the dereference), and produces the
result of dereferencing the `&` or `&mut` borrowed pointer returned from the overload method.
-`!`
+* `!`
: Logical negation. On the boolean type, this flips between `true` and
`false`. On integer types, this inverts the individual bits in the
two's complement representation of the value.
-`~`
+* `~`
: [Boxing](#pointer-types) operators. Allocate a box to hold the value they are applied to,
and store the value in it. `~` creates an owned box.
-`&`
+* `&`
: Borrow operator. Returns a reference, pointing to its operand.
The operand of a borrow is statically proven to outlive the resulting pointer.
If the borrow-checker cannot prove this, it is a compilation error.
This means that arithmetic operators can be overridden for user-defined types.
The default meaning of the operators on standard types is given here.
-`+`
+* `+`
: Addition and vector/string concatenation.
Calls the `add` method on the `std::ops::Add` trait.
-`-`
+* `-`
: Subtraction.
Calls the `sub` method on the `std::ops::Sub` trait.
-`*`
+* `*`
: Multiplication.
Calls the `mul` method on the `std::ops::Mul` trait.
-`/`
+* `/`
: Quotient.
Calls the `div` method on the `std::ops::Div` trait.
-`%`
+* `%`
: Remainder.
Calls the `rem` method on the `std::ops::Rem` trait.
This means that bitwise operators can be overridden for user-defined types.
The default meaning of the operators on standard types is given here.
-`&`
+* `&`
: And.
Calls the `bitand` method of the `std::ops::BitAnd` trait.
-`|`
+* `|`
: Inclusive or.
Calls the `bitor` method of the `std::ops::BitOr` trait.
-`^`
+* `^`
: Exclusive or.
Calls the `bitxor` method of the `std::ops::BitXor` trait.
-`<<`
+* `<<`
: Logical left shift.
Calls the `shl` method of the `std::ops::Shl` trait.
-`>>`
+* `>>`
: Logical right shift.
Calls the `shr` method of the `std::ops::Shr` trait.
This means that comparison operators can be overridden for user-defined types.
The default meaning of the operators on standard types is given here.
-`==`
+* `==`
: Equal to.
Calls the `eq` method on the `std::cmp::Eq` trait.
-`!=`
+* `!=`
: Unequal to.
Calls the `ne` method on the `std::cmp::Eq` trait.
-`<`
+* `<`
: Less than.
Calls the `lt` method on the `std::cmp::Ord` trait.
-`>`
+* `>`
: Greater than.
Calls the `gt` method on the `std::cmp::Ord` trait.
-`<=`
+* `<=`
: Less than or equal.
Calls the `le` method on the `std::cmp::Ord` trait.
-`>=`
+* `>=`
: Greater than or equal.
Calls the `ge` method on the `std::cmp::Ord` trait.
They can be copied, stored into data structures, and returned from functions.
There are four varieties of pointer in Rust:
-Owning pointers (`~`)
+* Owning pointers (`~`)
: These point to owned heap allocations (or "boxes") in the shared, inter-task heap.
Each owned box has a single owning pointer; pointer and pointee retain a 1:1 relationship at all times.
Owning pointers are written `~content`,
it involves allocating a new owned box and copying the contents of the old box into the new box.
Releasing an owning pointer immediately releases its corresponding owned box.
-References (`&`)
+* References (`&`)
: These point to memory _owned by some other value_.
References arise by (automatic) conversion from owning pointers, managed pointers,
or by applying the borrowing operator `&` to some other value,
with the exception of temporary values,
which are released when the last reference to them is released.
-Raw pointers (`*`)
+* Raw pointers (`*`)
: Raw pointers are pointers without safety or liveness guarantees.
Raw pointers are written `*content`,
for example `*int` means a raw pointer to an integer.
let mut x = add(5,7);
-type Binop<'a> = 'a |int,int| -> int;
+type Binop<'a> = |int,int|: 'a -> int;
let bo: Binop = add;
x = bo(5,7);
~~~~
### Closure types
-The type of a closure mapping an input of type `A` to an output of type `B` is `|A| -> B`. A closure with no arguments or return values has type `||`.
+~~~~ {.notrust .ebnf .notation}
+closure_type := [ 'unsafe' ] [ '<' lifetime-list '>' ] '|' arg-list '|'
+ [ ':' bound-list ] [ '->' type ]
+procedure_type := 'proc' [ '<' lifetime-list '>' ] '(' arg-list ')'
+ [ ':' bound-list ] [ '->' type ]
+lifetime-list := lifetime | lifetime ',' lifetime-list
+arg-list := ident ':' type | ident ':' type ',' arg-list
+bound-list := bound | bound '+' bound-list
+bound := path | lifetime
+~~~~
+The type of a closure mapping an input of type `A` to an output of type `B` is
+`|A| -> B`. A closure with no arguments or return values has type `||`.
+Similarly, a procedure mapping `A` to `B` is `proc(A) -> B` and a no-argument
+and no-return value closure has type `proc()`.
An example of creating and calling a closure:
```
+Unlike closures, procedures may only be invoked once, but own their
+environment, and are allowed to move out of their environment. Procedures are
+allocated on the heap (unlike closures). An example of creating and calling a
+procedure:
+
+```rust
+let string = "Hello".to_owned();
+
+// Creates a new procedure, passing it to the `spawn` function.
+spawn(proc() {
+ println!("{} world!", string);
+});
+
+// the variable `string` has been moved into the previous procedure, so it is
+// no longer usable.
+
+
+// Create an invoke a procedure. Note that the procedure is *moved* when
+// invoked, so it cannot be invoked again.
+let f = proc(n: int) { n + 22 };
+println!("answer: {}", f(20));
+
+```
+
### Object types
Every trait item (see [traits](#traits)) defines a type with the same name as the trait.
Types in Rust are categorized into kinds, based on various properties of the components of the type.
The kinds are:
-`Send`
+* `Send`
: Types of this kind can be safely sent between tasks.
This kind includes scalars, owning pointers, owned closures, and
structural types containing only other owned types.
All `Send` types are `'static`.
-`Copy`
+* `Copy`
: Types of this kind consist of "Plain Old Data"
which can be copied by simply moving bits.
All values of this kind can be implicitly copied.
This kind includes scalars and immutable references,
as well as structural types containing other `Copy` types.
-`'static`
+* `'static`
: Types of this kind do not contain any references (except for
references with the `static` lifetime, which are allowed).
This can be a useful guarantee for code
that breaks borrowing assumptions
using [`unsafe` operations](#unsafe-functions).
-`Drop`
+* `Drop`
: This is not strictly a kind,
but its presence interacts with kinds:
the `Drop` trait provides a single method `drop`
before any of the values it owns run their destructors.
Only `Send` types can implement `Drop`.
-_Default_
+* _Default_
: Types with destructors, closure environments,
and various other _non-first-class_ types,
are not copyable at all.
found in the [ffi tutorial][ffi].
In one session of compilation, the compiler can generate multiple artifacts
-through the usage of command line flags and the `crate_type` attribute.
+through the usage of either command line flags or the `crate_type` attribute.
+If one or more command line flag is specified, all `crate_type` attributes will
+be ignored in favor of only building the artifacts specified by command line.
* `--crate-type=bin`, `#[crate_type = "bin"]` - A runnable executable will be
produced. This requires that there is a `main` function in the crate which
Note that these outputs are stackable in the sense that if multiple are
specified, then the compiler will produce each form of output at once without
-having to recompile.
+having to recompile. However, this only applies for outputs specified by the same
+method. If only `crate_type` attributes are specified, then they will all be
+built, but if one or more `--crate-type` command line flag is specified,
+then only those outputs will be built.
With all these different kinds of outputs, if crate A depends on crate B, then
the compiler could find B in various different forms throughout the system. The
with the extension removed. In that case, to turn on logging for a program
compiled from, e.g. `helloworld.rs`, `RUST_LOG` should be set to `helloworld`.
-As a convenience, the logging spec can also be set to a special pseudo-crate,
-`::help`. In this case, when the application starts, the runtime will
-simply output a list of loaded modules containing log expressions, then exit.
-
#### Logging Expressions
Rust provides several macros to log information. Here's a simple Rust program
that demonstrates all four of them:
~~~~
-#[feature(phase)];
+#![feature(phase)]
#[phase(syntax, link)] extern crate log;
fn main() {
projects / rust.git / blobdiff