Browsing French translation

1.

# Introduction

2.

% The Rust Macros Guide

3.

<div class="unstable-feature"> <b>Warning:</b> There are currently various problems with invoking macros, how they interact with their environment, and how they are used outside of the location in which they are defined. Macro definitions are likely to change slightly in the future. For this reason, they are hidden behind the <code>macro_rules</code> <a href="reference.html#compiler-features">feature attribute</a>. </div>

4.

Functions are the primary tool that programmers can use to build abstractions. Sometimes, however, programmers want to abstract over compile-time syntax rather than run-time values. Macros provide syntactic abstraction. For an example of how this can be useful, consider the following two code fragments, which both pattern-match on their input and both return early in one case, doing nothing otherwise:

5.

~~~~
# enum T { SpecialA(uint), SpecialB(uint) }
# fn f() -> uint {
# let input_1 = SpecialA(0);
# let input_2 = SpecialA(0);
match input_1 {
SpecialA(x) => { return x; }
_ => {}
}
// ...
match input_2 {
SpecialB(x) => { return x; }
_ => {}
}
# return 0u;
# }
~~~~

6.

This code could become tiresome if repeated many times. However, no function can capture its functionality to make it possible to abstract the repetition away. Rust's macro system, however, can eliminate the repetition. Macros are lightweight custom syntax extensions, themselves defined using the `macro_rules!` syntax extension. The following `early_return` macro captures the pattern in the above code:

7.

~~~~
# #![feature(macro_rules)]
# enum T { SpecialA(uint), SpecialB(uint) }
# fn f() -> uint {
# let input_1 = SpecialA(0);
# let input_2 = SpecialA(0);
macro_rules! early_return(
($inp:expr $sp:ident) => ( // invoke it like `(input_5 SpecialE)`
match $inp {
$sp(x) => { return x; }
_ => {}
}
);
)
// ...
early_return!(input_1 SpecialA);
// ...
early_return!(input_2 SpecialB);
# return 0;
# }
# fn main() {}
~~~~

8.

Macros are defined in pattern-matching style: in the above example, the text `($inp:expr $sp:ident)` that appears on the left-hand side of the `=>` is the *macro invocation syntax*, a pattern denoting how to write a call to the macro. The text on the right-hand side of the `=>`, beginning with `match $inp`, is the *macro transcription syntax*: what the macro expands to.

9.

# Invocation syntax

10.

The macro invocation syntax specifies the syntax for the arguments to the macro. It appears on the left-hand side of the `=>` in a macro definition. It conforms to the following rules: