Merge pull request rust-lang#87 from brauliobz/grammar_crates

Added crates grammar

Author: steveklabnik

src/crates-and-source-files.md

@@ -1,5 +1,16 @@
 # Crates and source files
 
+> **<sup>Syntax</sup>**  
+> _Crate_ :  
+> &nbsp;&nbsp; UTF8BOM<sup>?</sup>  
+> &nbsp;&nbsp; SHEBANG<sup>?</sup>  
+> &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>  
+> &nbsp;&nbsp; [_Item_]<sup>\*</sup>  
+
+> **<sup>Lexer</sup>**  
+> UTF8BOM : `\uFEFF`  
+> SHEBANG : `#!` ~[`[` `\n`] ~`\n`<sup>*</sup>
+
 Although Rust, like any other language, can be implemented by an interpreter as
 well as a compiler, the only existing implementation is a compiler,
 and the language has
@@ -59,6 +70,24 @@ A crate that contains a `main` function can be compiled to an executable. If a
 `main` function is present, its return type must be `()`
 ("[unit]") and it must take no arguments.
 
+The optional [_UTF8 byte order mark_] (UTF8BOM production) indicates that the
+file is encoded in UTF8. It can only occur at the beginning of the file and
+is ignored by the compiler.
+
+A source file can have a [_shebang_] (SHEBANG production), which indicates
+to the operating system what program to use to execute this file. It serves
+essentially to treat the source file as an executable script. The shebang
+can only occur at the beginning of the file (but after the optional
+_UTF8BOM_). It is ignored by the compiler. For example:
+
+```text,ignore
+#!/usr/bin/env rustx
+
+fn main() {
+    println!("Hello!");
+}
+```
+
 [^phase-distinction]: This distinction would also exist in an interpreter.
     Static checks like syntactic analysis, type checking, and lints should
     happen before the program is executed regardless of when it is executed.
@@ -70,4 +99,8 @@ A crate that contains a `main` function can be compiled to an executable. If a
 [module]: items.html#modules
 [module path]: paths.html
 [attributes]: items-and-attributes.html
-[unit]: types.html#tuple-types
+[unit]: types.html#tuple-types
+[_InnerAttribute_]: attributes.html
+[_Item_]: items.html
+[_shebang_]: https://en.wikipedia.org/wiki/Shebang_(Unix)
+[_utf8 byte order mark_]: https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8