From d701fcd8a52fdd1cf85516c546edcc8de9b5d400 Mon Sep 17 00:00:00 2001 From: Jesse Jones Date: Sun, 18 Nov 2012 09:08:31 -0800 Subject: [PATCH 01/11] Added a readme explaining how to generate html from markdown docs w/o node --- doc/README | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 doc/README diff --git a/doc/README b/doc/README new file mode 100644 index 00000000000..505b5383dcd --- /dev/null +++ b/doc/README @@ -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 \ No newline at end of file From d106ef88e6a87d726630fea997699d4255fb5ebb Mon Sep 17 00:00:00 2001 From: Jesse Jones Date: Sun, 18 Nov 2012 09:23:09 -0800 Subject: [PATCH 02/11] Improved attribute section, mostly by mentioning lint attributes. Closes #2769 --- doc/rust.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/rust.md b/doc/rust.md index e1ccdc579c6..9f1baf809a0 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -1304,9 +1304,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 +1325,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 +1340,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. From d107e586eaec04cf2a5d3b08cc49a6bdd14990cd Mon Sep 17 00:00:00 2001 From: Jesse Jones Date: Sun, 18 Nov 2012 11:00:39 -0800 Subject: [PATCH 03/11] Documented fmt! expression syntax. Closes #3280 --- src/libcore/extfmt.rs | 41 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/src/libcore/extfmt.rs b/src/libcore/extfmt.rs index c7139b16934..4017dddad63 100644 --- a/src/libcore/extfmt.rs +++ b/src/libcore/extfmt.rs @@ -1,4 +1,40 @@ -#[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 +80,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 +314,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; @@ -464,6 +502,7 @@ pub mod rt { } } +// Bulk of the tests are in src/test/run-pass/syntax-extension-fmt.rs #[cfg(test)] mod test { #[test] From 67d421d62dcfe5ee6c45970aaf25ddaf4cc577df Mon Sep 17 00:00:00 2001 From: Jesse Jones Date: Sun, 18 Nov 2012 11:36:09 -0800 Subject: [PATCH 04/11] Document [0, ..8] vector syntax. Closes #3336 --- doc/rust.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/rust.md b/doc/rust.md index 9f1baf809a0..ac3c16b6e85 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -1547,7 +1547,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 @@ -1557,8 +1559,10 @@ indicate that the elements of the resulting vector may be mutated. 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]; ~~~~ @@ -1890,7 +1894,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, From e46de5381b7d16797ff690e7770acf8ba49ba8c3 Mon Sep 17 00:00:00 2001 From: Jesse Jones Date: Sun, 18 Nov 2012 15:15:12 -0800 Subject: [PATCH 05/11] Moved the matching structs example next to the prose talking about struct matching --- doc/rust.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/doc/rust.md b/doc/rust.md index ac3c16b6e85..dddd372dcc8 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -2174,17 +2174,6 @@ Records and structures can also be pattern-matched and their fields bound to var 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}; @@ -2217,6 +2206,17 @@ fn main() { } ~~~~ +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. + Multiple match patterns may be joined with the `|` operator. A range of values may be specified with `..`. For example: From 57c203ef7fdd6efdecbece708df44e7944a3f317 Mon Sep 17 00:00:00 2001 From: Jesse Jones Date: Sun, 18 Nov 2012 15:26:12 -0800 Subject: [PATCH 06/11] Documented copy, ref, move in patterns. Closes #3337 --- doc/rust.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/rust.md b/doc/rust.md index dddd372dcc8..5936f6b2848 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -2206,7 +2206,12 @@ fn main() { } ~~~~ -A pattern that's just a variable binding, +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. From a1bf75978350332ab48828868fa04dfcca8e1d9f Mon Sep 17 00:00:00 2001 From: Jesse Jones Date: Sun, 18 Nov 2012 15:49:53 -0800 Subject: [PATCH 07/11] Added brief discussion of static trait methods. Closes #3339 --- doc/rust.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/rust.md b/doc/rust.md index 5936f6b2848..bf28f2523af 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -1175,6 +1175,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. From e5c9a8a4796d668d20cae1b65e70dd6c2114562a Mon Sep 17 00:00:00 2001 From: Jesse Jones Date: Sun, 18 Nov 2012 17:05:04 -0800 Subject: [PATCH 08/11] Fixed lint problems --- src/libcore/extfmt.rs | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/src/libcore/extfmt.rs b/src/libcore/extfmt.rs index 4017dddad63..8930f809ff3 100644 --- a/src/libcore/extfmt.rs +++ b/src/libcore/extfmt.rs @@ -1,7 +1,7 @@ //! Support for fmt! expressions. //! //! The syntax is close to that of Posix format strings: -//! +//! //! ~~~~~~ //! Format := '%' Parameter? Flag* Width? Precision? Type //! Parameter := [0-9]+ '$' @@ -10,18 +10,24 @@ //! 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. +//! +//! * 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 +//! * 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 From a24da7e254110dcd38183e73fa1bb9ef143a6b27 Mon Sep 17 00:00:00 2001 From: Jesse Jones Date: Sun, 18 Nov 2012 17:05:24 -0800 Subject: [PATCH 09/11] Discuss the types that may be used with const items. Also removed vector example that doesn't compile. IMO closes #3341. --- doc/rust.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/doc/rust.md b/doc/rust.md index bf28f2523af..3ca414006ce 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -1104,6 +1104,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. @@ -1562,7 +1573,6 @@ indicate that the elements of the resulting vector may be mutated. When no mutability is specified, the vector is immutable. ~~~~ -[] [1, 2, 3, 4]; ["a", "b", "c", "d"]; [0, ..128]; // vector with 128 zeros From 76712476c270c952d392d33626cc86f3c450e2cb Mon Sep 17 00:00:00 2001 From: Jesse Jones Date: Sun, 18 Nov 2012 18:25:06 -0800 Subject: [PATCH 10/11] Slightly better description of macro designators. Closes #3378 --- doc/rust.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/rust.md b/doc/rust.md index 3ca414006ce..e9cb59f05b1 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -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. From ca332a68fa810de4bc1d8abc16020fdb3027333f Mon Sep 17 00:00:00 2001 From: Jesse Jones Date: Sun, 18 Nov 2012 18:28:05 -0800 Subject: [PATCH 11/11] Added optional pub to use_decl EBNF. --- doc/rust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/rust.md b/doc/rust.md index e9cb59f05b1..2a99acdef41 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -798,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 ] ?