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

Merge pull request #4001 from jesse99/features/docs

Browse Source 
Features/docs
This commit is contained in:
Graydon Hoare 2012-11-19 16:10:31 -08:00
commit 34b7db3bbc
3 changed files with 104 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
doc/README Normal file
View File

@ -0,0 +1,13 @@
The markdown docs are only generated by make when node is installed (use
`make doc`). If you don't have node installed you can generate them yourself.
Unfortunately there's no real standard for markdown and all the tools work
differently. pandoc is one that seems to work well.
To generate an html version of a doc do something like:
pandoc --from=markdown --to=html --number-sections -o build/doc/rust.html doc/rust.md && git web--browse build/doc/rust.html
The syntax for pandoc flavored markdown can be found at:
http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
A nice quick reference (for non-pandoc markdown) is at:
http://kramdown.rubyforge.org/quickref.html

68
doc/rust.md
View File

@ -510,9 +510,8 @@ For parsing reasons, delimiters must be balanced, but they are otherwise not spe
In the matcher, `$` _name_ `:` _designator_ matches the nonterminal in the
Rust syntax named by _designator_. Valid designators are `item`, `block`,
`stmt`, `pat`, `expr`, `ty`, `ident`, `path`, `tt`, `matchers`. The last two
are the right-hand side and the left-hand side respectively of the `=>` in
macro rules. In the transcriber, the designator is already known, and so only
`stmt`, `pat`, `expr`, `ty` (type), `ident`, `path`, `matchers` (lhs of the `=>` in macro rules),
`tt` (rhs of the `=>` in macro rules). In the transcriber, the designator is already known, and so only
the name of a matched nonterminal comes after the dollar sign.
In both the matcher and transcriber, the Kleene star-like operator indicates repetition.
@ -799,7 +798,7 @@ extern mod ruststd (name = "std"); // linking to 'std' under another name
##### Use declarations
~~~~~~~~ {.ebnf .gram}
use_decl : "use" ident [ '=' path
use_decl : "pub"? "use" ident [ '=' path
| "::" path_glob ] ;
path_glob : ident [ "::" path_glob ] ?
@ -1104,6 +1103,17 @@ Constants are declared with the `const` keyword.
A constant item must have an expression giving its definition.
The definition expression of a constant is limited to expression forms that can be evaluated at compile time.
Constants must be explicitly typed. The type may be ```bool```, ```char```, a number, or a type derived from
those primitive types. The derived types are borrowed pointers, static arrays, tuples, and structs.
~~~~
const bit1: uint = 1 << 0;
const bit2: uint = 1 << 1;
const bits: [uint * 2] = [bit1, bit2];
const bits_r: &[uint] = &bits;
~~~~
### Traits
A _trait_ describes a set of method types.
@ -1175,6 +1185,9 @@ Values with a trait type can have [methods called](#method-call-expressions) on
for any method in the trait,
and can be used to instantiate type parameters that are bounded by the trait.
Trait methods may be static. Currently implementations of static methods behave like
functions declared in the implentation's module.
### Implementations
An _implementation_ is an item that implements a [trait](#traits) for a specific type.
@ -1304,9 +1317,8 @@ Attributes may appear as any of
* 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
Attributes are applied to an entity by placing them within a hash-list
(`#[...]`) as either a prefix to the entity or as a semicolon-delimited
declaration within the entity body.
Attributes terminated by a semi-colon apply to the entity that the attribute is declared
within. Attributes that are not terminated by a semi-colon apply to the next entity.
An example of attributes:
@ -1326,9 +1338,9 @@ mod bar {
...
}
// A documentation attribute
#[doc = "Add two numbers together."]
fn add(x: int, y: int) { x + y }
// A lint attribute used to suppress a warning/error
#[allow(non_camel_case_types)]
pub type int8_t = i8;
~~~~~~~~
> **Note:** In future versions of Rust, user-provided extensions to the compiler will be able to interpret attributes.
@ -1341,6 +1353,8 @@ names are effectively reserved. Some significant attributes include:
* The `cfg` attribute, for conditional-compilation by build-configuration.
* The `link` attribute, for describing linkage metadata for a crate.
* The `test` attribute, for marking functions as unit tests.
* The `allow`, `warn`, `forbid`, and `deny` attributes, for controling lint checks. Lint checks supported
by the compiler can be found via `rustc -W help`.
Other attributes may be added or removed during development of the language.
@ -1546,7 +1560,9 @@ it is automatically derferenced to make the field access possible.
### Vector expressions
~~~~~~~~{.ebnf .gram}
vec_expr : '[' "mut" ? [ expr [ ',' expr ] * ] ? ']'
vec_expr : '[' "mut"? vec_elems? ']'
vec_elems : [expr [',' expr]*] | [expr ',' ".." expr]
~~~~~~~~
A [_vector_](#vector-types) _expression_ is written by enclosing zero or
@ -1558,6 +1574,7 @@ When no mutability is specified, the vector is immutable.
~~~~
[1, 2, 3, 4];
["a", "b", "c", "d"];
[0, ..128]; // vector with 128 zeros
[mut 0u8, 0u8, 0u8, 0u8];
~~~~
@ -1889,7 +1906,7 @@ let x: int = add(1, 2);
~~~~~~~~ {.abnf .gram}
ident_list : [ ident [ ',' ident ]* ] ? ;
lambda_expr : '|' ident_list '| expr ;
lambda_expr : '|' ident_list '|' expr ;
~~~~~~~~
A _lambda expression_ (a.k.a. "anonymous function expression") defines a function and denotes it as a value,
@ -2170,17 +2187,6 @@ When matching fields of a record,
the fields being matched are specified first,
then a placeholder (`_`) represents the remaining fields.
A pattern that's just a variable binding,
like `Nil` in the previous answer,
could either refer to an enum variant that's in scope,
or bind a new variable.
The compiler resolves this ambiguity by forbidding variable bindings that occur in ```match``` patterns from shadowing names of variants that are in scope.
For example, wherever ```List``` is in scope,
a ```match``` pattern would not be able to bind ```Nil``` as a new name.
The compiler interprets a variable pattern `x` as a binding _only_ if there is no variant named `x` in scope.
A convention you can use to avoid conflicts is simply to name variants with upper-case letters,
and local variables with lower-case letters.
~~~~
# type options = {choose: bool, size: ~str};
# type player = {player: ~str, stats: (), options: options};
@ -2212,6 +2218,22 @@ fn main() {
}
~~~~
Patterns that bind variables default to binding to a copy of the matched value. This can be made
explicit using the ```copy``` keyword, changed to bind to a borrowed pointer by using the ```ref```
keyword, or to a mutable borrowed pointer using ```ref mut```, or the value can be moved into
the new binding using ```move```.
A pattern that's just an identifier,
like `Nil` in the previous answer,
could either refer to an enum variant that's in scope,
or bind a new variable.
The compiler resolves this ambiguity by forbidding variable bindings that occur in ```match``` patterns from shadowing names of variants that are in scope.
For example, wherever ```List``` is in scope,
a ```match``` pattern would not be able to bind ```Nil``` as a new name.
The compiler interprets a variable pattern `x` as a binding _only_ if there is no variant named `x` in scope.
A convention you can use to avoid conflicts is simply to name variants with upper-case letters,
and local variables with lower-case letters.
Multiple match patterns may be joined with the `|` operator. A
range of values may be specified with `..`. For example:

47
src/libcore/extfmt.rs
View File

@ -1,4 +1,46 @@
#[doc(hidden)];
//! Support for fmt! expressions.
//!
//! The syntax is close to that of Posix format strings:
//!
//! ~~~~~~
//! Format := '%' Parameter? Flag* Width? Precision? Type
//! Parameter := [0-9]+ '$'
//! Flag := [ 0#+-]
//! Width := Parameter | [0-9]+
//! Precision := '.' [0-9]+
//! Type := [bcdfiostuxX?]
//! ~~~~~~
//!
//! * Parameter is the 1-based argument to apply the format to. Currently not
//! implemented.
//! * Flag 0 causes leading zeros to be used for padding when converting
//! numbers.
//! * Flag # causes the conversion to be done in an *alternative* manner.
//! Currently not implemented.
//! * Flag + causes signed numbers to always be prepended with a sign
//! character.
//! * Flag - left justifies the result
//! * Width specifies the minimum field width of the result. By default
//! leading spaces are added.
//! * Precision specifies the minimum number of digits for integral types
//! and the minimum number
//! of decimal places for float.
//!
//! The types currently supported are:
//!
//! * b - bool
//! * c - char
//! * d - int
//! * f - float
//! * i - int (same as d)
//! * o - uint as octal
//! * t - uint as binary
//! * u - uint
//! * x - uint as lower-case hexadecimal
//! * X - uint as upper-case hexadecimal
//! * s - str (any flavor)
//! * ? - arbitrary type (does not use the to_str trait)
// NB: transitionary, de-mode-ing.
#[forbid(deprecated_mode)];
#[forbid(deprecated_pattern)];
@ -44,6 +86,7 @@ use option::{Some, None};
*/
// Functions used by the fmt extension at compile time
#[doc(hidden)]
pub mod ct {
pub enum Signedness { Signed, Unsigned, }
pub enum Caseness { CaseUpper, CaseLower, }
@ -277,6 +320,7 @@ pub mod ct {
// decisions made a runtime. If it proves worthwhile then some of these
// conditions can be evaluated at compile-time. For now though it's cleaner to
// implement it 0this way, I think.
#[doc(hidden)]
pub mod rt {
pub const flag_none : u32 = 0u32;
pub const flag_left_justify : u32 = 0b00000000000001u32;
@ -483,6 +527,7 @@ pub mod rt {
}
}
// Bulk of the tests are in src/test/run-pass/syntax-extension-fmt.rs
#[cfg(test)]
mod test {
#[test]