OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

manual: many fixes

Browse Source 
Mostly around attributes and language items.
This commit is contained in:
Corey Richardson 2014-03-30 08:30:25 -04:00
parent a410833a7f
commit 2eccb1d0c2
1 changed files with 170 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
src/doc/rust.md
View File

@ -611,7 +611,7 @@ Attributes on the anonymous crate module define important metadata that influenc
the behavior of the compiler. the behavior of the compiler.
~~~~ ~~~~
// Package ID // Crate ID
#[ crate_id = "projx#2.5" ]; #[ crate_id = "projx#2.5" ];
// Additional metadata attributes // Additional metadata attributes
@ -792,7 +792,7 @@ extern crate std; // equivalent to: extern crate std = "std";
extern crate ruststd = "std"; // linking to 'std' under another name extern crate ruststd = "std"; // linking to 'std' under another name
extern crate foo = "some/where/rust-foo#foo:1.0"; // a full package ID for external tools extern crate foo = "some/where/rust-foo#foo:1.0"; // a full crate ID for external tools
~~~~ ~~~~
##### Use declarations ##### Use declarations
@ -1505,11 +1505,9 @@ specified name.
extern { } extern { }
~~~~ ~~~~
The type of a function The type of a function declared in an extern block is `extern "abi" fn(A1,
declared in an extern block ..., An) -> R`, where `A1...An` are the declared types of its arguments and
is `extern "abi" fn(A1, ..., An) -> R`, `R` is the declared return type.
where `A1...An` are the declared types of its arguments
and `R` is the decalred return type.
## Visibility and Privacy ## Visibility and Privacy
@ -1680,41 +1678,43 @@ import public items from their destination, not private items.
## Attributes ## Attributes
~~~~ {.notrust .ebnf .gram} ~~~~ {.notrust .ebnf .gram}
attribute : '#' '[' attr_list ']' ; attribute : '#' '!' ? '[' attr_list ']'
attr_list : attr [ ',' attr_list ]* ; attr_list : attr [ ',' attr_list ]*
attr : ident [ '=' literal attr : ident [ '=' literal
| '(' attr_list ')' ] ? ; | '(' attr_list ')' ] ?
~~~~ ~~~~
Static entities in Rust -- crates, modules and items -- may have _attributes_ Static entities in Rust -- crates, modules and items -- may have _attributes_
applied to them. ^[Attributes in Rust are modeled on Attributes in ECMA-335, applied to them. Attributes in Rust are modeled on Attributes in ECMA-335, C#.
C#] An attribute is a general, free-form metadatum that is interpreted according
An attribute is a general, free-form metadatum that is interpreted according to name, convention, and language and compiler version. to name, convention, and language and compiler version. Attributes may appear
Attributes may appear as any of as any of:
* A single identifier, the attribute name * A single identifier, the attribute name
* An identifier followed by the equals sign '=' and a literal, providing a key/value pair * An identifier followed by the equals sign '=' and a literal, providing a
key/value pair
* An identifier followed by a parenthesized list of sub-attribute arguments * An identifier followed by a parenthesized list of sub-attribute arguments
Attributes terminated by a semi-colon apply to the entity that the attribute is declared Attributes with a bang ("!") after the hash ("#") apply to the item that the
within. Attributes that are not terminated by a semi-colon apply to the next entity. attribute is declared within. Attributes that do not have a bang after the
hash by a semi-colon apply to the next item.
An example of attributes: An example of attributes:
~~~~ {.ignore} ~~~~
// General metadata applied to the enclosing module or crate. // General metadata applied to the enclosing module or crate.
#[license = "BSD"]; #![license = "BSD"]
// A function marked as a unit test // A function marked as a unit test
#[test] #[test]
fn test_foo() { fn test_foo() {
... /* ... */
} }
// A conditionally-compiled module // A conditionally-compiled module
#[cfg(target_os="linux")] #[cfg(target_os="linux")]
mod bar { mod bar {
... /* ... */
} }
// A lint attribute used to suppress a warning/error // A lint attribute used to suppress a warning/error
@ -1727,29 +1727,85 @@ pub type int8_t = i8;
> effectively no difference between an attribute handled by a loadable syntax > effectively no difference between an attribute handled by a loadable syntax
> extension and the compiler. > extension and the compiler.
Some significant attributes include: ### Crate-only attributes
* The `doc` attribute, for documenting code in-place. - `crate_type` - see [linkage](#linkage).
* The `cfg` attribute, for conditional-compilation by build-configuration (see - `feature` - see [compiler features](#compiler-features).
[Conditional compilation](#conditional-compilation)). - `no_start` - disable linking to the `native` crate, which specifies the
* The `crate_id` attribute, for describing the package ID of a crate. "start" language item.
* The `lang` attribute, for custom definitions of traits and functions that are - `no_main` - disable emitting the `main` symbol. Useful when some
known to the Rust compiler (see [Language items](#language-items)). other object being linked to defines `main`.
* The `link` attribute, for describing linkage metadata for a extern blocks. - `no_std` - disable linking to the `std` crate.
* The `test` attribute, for marking functions as unit tests. - `crate_id` - specify the this crate's crate ID.
* The `allow`, `warn`, `forbid`, and `deny` attributes, for
controlling lint checks (see [Lint check attributes](#lint-check-attributes)).
* The `deriving` attribute, for automatically generating implementations of
certain traits.
* The `inline` attribute, for expanding functions at caller location (see
[Inline attributes](#inline-attributes)).
* The `static_assert` attribute, for asserting that a static bool is true at
compiletime.
* The `thread_local` attribute, for defining a `static mut` as a thread-local.
Note that this is only a low-level building block, and is not local to a
*task*, nor does it provide safety.
Other attributes may be added or removed during development of the language. ### 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.
### 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.
### Static-only attributes
- `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).
On declarations inside an `extern` block, the following attributes are
interpreted:
- `link_name` - the name of the symbol that this function or static should be
imported as.
- `linkage` - on a static, this specifies the [linkage
type](http://llvm.org/docs/LangRef.html#linkage-types).
### 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.
- `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.
- `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 ### Conditional compilation
@ -1791,9 +1847,7 @@ one of `foo` and `bar` to be defined (this resembles in the disjunctive normal
form). Additionally, one can reverse a condition by enclosing it in a form). Additionally, one can reverse a condition by enclosing it in a
`not(...)`, like e. g. `#[cfg(not(target_os = "win32"))]`. `not(...)`, like e. g. `#[cfg(not(target_os = "win32"))]`.
To pass a configuration option which triggers a `#[cfg(identifier)]` one can use The following configurations must be defined by the implementation:
`rustc --cfg identifier`. In addition to that, the following configurations are
pre-defined by the compiler:
* `target_arch = "..."`. Target CPU architecture, such as `"x86"`, `"x86_64"` * `target_arch = "..."`. Target CPU architecture, such as `"x86"`, `"x86_64"`
`"mips"`, or `"arm"`. `"mips"`, or `"arm"`.
@ -1805,8 +1859,8 @@ pre-defined by the compiler:
* `target_os = "..."`. Operating system of the target, examples include * `target_os = "..."`. Operating system of the target, examples include
`"win32"`, `"macos"`, `"linux"`, `"android"` or `"freebsd"`. `"win32"`, `"macos"`, `"linux"`, `"android"` or `"freebsd"`.
* `target_word_size = "..."`. Target word size in bits. This is set to `"32"` * `target_word_size = "..."`. Target word size in bits. This is set to `"32"`
for 32-bit CPU targets, and likewise set to `"64"` for 64-bit CPU targets. for targets with 32-bit pointers, and likewise set to `"64"` for 64-bit
* `test`. Only set in test builds (`rustc --test`). pointers.
* `unix`. See `target_family`. * `unix`. See `target_family`.
* `windows`. See `target_family`. * `windows`. See `target_family`.
@ -1823,7 +1877,7 @@ For any lint check `C`:
* `allow(C)` overrides the check for `C` so that violations will go * `allow(C)` overrides the check for `C` so that violations will go
unreported, unreported,
* `forbid(C)` is the same as `deny(C)`, but also forbids uses of * `forbid(C)` is the same as `deny(C)`, but also forbids uses of
`allow(C)` within the entity. `allow(C)` within the attribute.
The lint checks supported by the compiler can be found via `rustc -W help`, The lint checks supported by the compiler can be found via `rustc -W help`,
along with their default settings. along with their default settings.
@ -1881,11 +1935,11 @@ mod m3 {
### Language items ### Language items
Some primitive Rust operations are defined in Rust code, Some primitive Rust operations are defined in Rust code, rather than being
rather than being implemented directly in C or assembly language. implemented directly in C or assembly language. The definitions of these
The definitions of these operations have to be easy for the compiler to find. operations have to be easy for the compiler to find. The `lang` attribute
The `lang` attribute makes it possible to declare these operations. makes it possible to declare these operations. For example, the `str` module
For example, the `str` module in the Rust standard library defines the string equality function: in the Rust standard library defines the string equality function:
~~~~ {.ignore} ~~~~ {.ignore}
#[lang="str_eq"] #[lang="str_eq"]
@ -1900,16 +1954,23 @@ when generating calls to the string equality function.
A complete list of the built-in language items follows: A complete list of the built-in language items follows:
#### Traits #### Built-in Traits
`const` `send`
: Cannot be mutated. : Able to be sent across task boundaries.
`owned` `sized`
: Are uniquely owned. : Has a size known at compile time.
`durable` `copy`
: Contain references. : Types that do not move ownership when used by-value.
`share`
: Able to be safely shared between tasks when aliased.
`drop` `drop`
: Have finalizers. : Have destructors.
#### Operators
These language items are traits:
`add` `add`
: Elements can be added (for example, integers and floats). : Elements can be added (for example, integers and floats).
`sub` `sub`
@ -1940,17 +2001,54 @@ A complete list of the built-in language items follows:
: Elements can be compared for equality. : Elements can be compared for equality.
`ord` `ord`
: Elements have a partial ordering. : Elements have a partial ordering.
`deref`
: `*` can be applied, yielding a reference to another type
`deref_mut`
: `*` can be applied, yielding a mutable reference to another type
#### Operations
These are functions:
`str_eq` `str_eq`
: Compare two strings for equality. : Compare two strings (`&str`) for equality.
`uniq_str_eq` `uniq_str_eq`
: Compare two owned strings for equality. : Compare two owned strings (`~str`) for equality.
`annihilate` `strdup_uniq`
: Destroy a box before freeing it. : Return a new unique string
`log_type` containing a copy of the contents of a unique string.
: Generically print a string representation of any type.
#### Types
`unsafe`
: A type whose contents can be mutated through an immutable reference
`type_id`
: The type returned by the `type_id` intrinsic.
#### Marker types
These types help drive the compiler's analysis
`covariant_type`
: The type parameter should be considered covariant
`contravariant_type`
: The type parameter should be considered contravariant
`invariant_type`
: The type parameter should be considered invariant
`covariant_lifetime`
: The lifetime parameter should be considered covariant
`contravariant_lifetime`
: The lifetime parameter should be considered contravariant
`invariant_lifetime`
: The lifetime parameter should be considered invariant
`no_send_bound`
: This type does not implement "send", even if eligible
`no_copy_bound`
: This type does not implement "copy", even if eligible
`no_share_bound`
: This type does not implement "share", even if eligible
`managed_bound`
: This type implements "managed"
`fail_` `fail_`
: Abort the program with an error. : Abort the program with an error.
`fail_bounds_check` `fail_bounds_check`
@ -1963,15 +2061,6 @@ A complete list of the built-in language items follows:
: Allocate memory on the managed heap. : Allocate memory on the managed heap.
`free` `free`
: Free memory that was allocated on the managed heap. : Free memory that was allocated on the managed heap.
`borrow_as_imm`
: Create an immutable reference to a mutable value.
`return_to_mut`
: Release a reference created with `return_to_mut`
`check_not_borrowed`
: Fail if a value has existing references to it.
`strdup_uniq`
: Return a new unique string
containing a copy of the contents of a unique string.
> **Note:** This list is likely to become out of date. We should auto-generate it > **Note:** This list is likely to become out of date. We should auto-generate it
> from `librustc/middle/lang_items.rs`. > from `librustc/middle/lang_items.rs`.
@ -2039,6 +2128,7 @@ Supported traits for `deriving` are:
* `Show`, to format a value using the `{}` formatter. * `Show`, to format a value using the `{}` formatter.
### Stability ### Stability
One can indicate the stability of an API using the following attributes: One can indicate the stability of an API using the following attributes:
* `deprecated`: This item should no longer be used, e.g. it has been * `deprecated`: This item should no longer be used, e.g. it has been
@ -2101,10 +2191,10 @@ necessarily ready for every-day use. These features are often of "prototype
quality" or "almost production ready", but may not be stable enough to be quality" or "almost production ready", but may not be stable enough to be
considered a full-fleged language feature. considered a full-fleged language feature.
For this reason, rust recognizes a special crate-level attribute of the form: For this reason, Rust recognizes a special crate-level attribute of the form:
~~~~ {.ignore} ~~~~ {.ignore}
#[feature(feature1, feature2, feature3)] #![feature(feature1, feature2, feature3)]
~~~~ ~~~~
This directive informs the compiler that the feature list: `feature1`, This directive informs the compiler that the feature list: `feature1`,
@ -2112,7 +2202,7 @@ This directive informs the compiler that the feature list: `feature1`,
crate-level, not at a module-level. Without this directive, all features are crate-level, not at a module-level. Without this directive, all features are
considered off, and using the features will result in a compiler error. considered off, and using the features will result in a compiler error.
The currently implemented features of the compiler are: The currently implemented features of the reference compiler are:
* `macro_rules` - The definition of new macros. This does not encompass * `macro_rules` - The definition of new macros. This does not encompass
macro-invocation, that is always enabled by default, this only macro-invocation, that is always enabled by default, this only