<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Macros By Example - The Rust Reference</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<base href="">
<link rel="stylesheet" href="book.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<link rel="shortcut icon" href="favicon.png">
<!-- Font Awesome -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<!-- MathJax -->
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<!-- Fetch JQuery from CDN but have a local fallback -->
<script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
<script>
if (typeof jQuery == 'undefined') {
document.write(unescape("%3Cscript src='jquery.js'%3E%3C/script%3E"));
}
</script>
</head>
<body class="light">
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme = localStorage.getItem('theme');
if (theme == null) { theme = 'light'; }
$('body').removeClass().addClass(theme);
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var sidebar = localStorage.getItem('sidebar');
if (sidebar === "hidden") { $("html").addClass("sidebar-hidden") }
else if (sidebar === "visible") { $("html").addClass("sidebar-visible") }
</script>
<div id="sidebar" class="sidebar">
<ul class="chapter"><li class="affix"><a href="introduction.html">Introduction</a></li><li><a href="notation.html"><strong>1.</strong> Notation</a></li><li><ul class="section"><li><a href="unicode-productions.html"><strong>1.1.</strong> Unicode productions</a></li><li><a href="string-table-productions.html"><strong>1.2.</strong> String table productions</a></li></ul></li><li><a href="lexical-structure.html"><strong>2.</strong> Lexical structure</a></li><li><ul class="section"><li><a href="input-format.html"><strong>2.1.</strong> Input format</a></li><li><a href="identifiers.html"><strong>2.2.</strong> Identifiers</a></li><li><a href="comments.html"><strong>2.3.</strong> Comments</a></li><li><a href="whitespace.html"><strong>2.4.</strong> Whitespace</a></li><li><a href="tokens.html"><strong>2.5.</strong> Tokens</a></li><li><a href="paths.html"><strong>2.6.</strong> Paths</a></li></ul></li><li><a href="macros.html"><strong>3.</strong> Macros</a></li><li><ul class="section"><li><a href="macros-by-example.html" class="active"><strong>3.1.</strong> Macros By Example</a></li><li><a href="procedural-macros.html"><strong>3.2.</strong> Procedural Macros</a></li></ul></li><li><a href="crates-and-source-files.html"><strong>4.</strong> Crates and source files</a></li><li><a href="items-and-attributes.html"><strong>5.</strong> Items and attributes</a></li><li><ul class="section"><li><a href="items.html"><strong>5.1.</strong> Items</a></li><li><a href="visibility-and-privacy.html"><strong>5.2.</strong> Visibility and Privacy</a></li><li><a href="attributes.html"><strong>5.3.</strong> Attributes</a></li></ul></li><li><a href="statements-and-expressions.html"><strong>6.</strong> Statements and expressions</a></li><li><ul class="section"><li><a href="statements.html"><strong>6.1.</strong> Statements</a></li><li><a href="expressions.html"><strong>6.2.</strong> Expressions</a></li></ul></li><li><a href="type-system.html"><strong>7.</strong> Type system</a></li><li><ul class="section"><li><a href="types.html"><strong>7.1.</strong> Types</a></li><li><a href="subtyping.html"><strong>7.2.</strong> Subtyping</a></li><li><a href="type-coercions.html"><strong>7.3.</strong> Type coercions</a></li></ul></li><li><a href="special-traits.html"><strong>8.</strong> Special traits</a></li><li><ul class="section"><li><a href="the-copy-trait.html"><strong>8.1.</strong> The Copy trait</a></li><li><a href="the-sized-trait.html"><strong>8.2.</strong> The Sized trait</a></li><li><a href="the-drop-trait.html"><strong>8.3.</strong> The Drop trait</a></li><li><a href="the-deref-trait.html"><strong>8.4.</strong> The Deref trait</a></li><li><a href="the-send-trait.html"><strong>8.5.</strong> The Send trait</a></li><li><a href="the-sync-trait.html"><strong>8.6.</strong> The Sync trait</a></li></ul></li><li><a href="memory-model.html"><strong>9.</strong> Memory model</a></li><li><ul class="section"><li><a href="memory-allocation-and-lifetime.html"><strong>9.1.</strong> Memory allocation and lifetime</a></li><li><a href="memory-ownership.html"><strong>9.2.</strong> Memory ownership</a></li><li><a href="variables.html"><strong>9.3.</strong> Variables</a></li></ul></li><li><a href="linkage.html"><strong>10.</strong> Linkage</a></li><li><a href="unsafety.html"><strong>11.</strong> Unsafety</a></li><li><ul class="section"><li><a href="unsafe-functions.html"><strong>11.1.</strong> Unsafe functions</a></li><li><a href="unsafe-blocks.html"><strong>11.2.</strong> Unsafe blocks</a></li><li><a href="behavior-considered-undefined.html"><strong>11.3.</strong> Behavior considered undefined</a></li><li><a href="behavior-not-considered-unsafe.html"><strong>11.4.</strong> Behavior not considered unsafe</a></li></ul></li><li><a href="influences.html">Appendix: Influences</a></li><li class="affix"><a href="undocumented.html">Appendix: As-yet-undocumented Features</a></li></ul>
</div>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar" class="menu-bar">
<div class="left-buttons">
<i id="sidebar-toggle" class="fa fa-bars"></i>
<i id="theme-toggle" class="fa fa-paint-brush"></i>
</div>
<h1 class="menu-title">The Rust Reference</h1>
<div class="right-buttons">
<i id="print-button" class="fa fa-print" title="Print this book"></i>
</div>
</div>
<div id="content" class="content">
<a class="header" href="macros-by-example.html#macros-by-example" id="macros-by-example"><h1>Macros By Example</h1></a>
<p><code>macro_rules</code> allows users to define syntax extension in a declarative way. We
call such extensions "macros by example" or simply "macros".</p>
<p>Currently, macros can expand to expressions, statements, items, or patterns.</p>
<p>(A <code>sep_token</code> is any token other than <code>*</code> and <code>+</code>. A <code>non_special_token</code> is
any token other than a delimiter or <code>$</code>.)</p>
<p>The macro expander looks up macro invocations by name, and tries each macro
rule in turn. It transcribes the first successful match. Matching and
transcription are closely related to each other, and we will describe them
together.</p>
<p>The macro expander matches and transcribes every token that does not begin with
a <code>$</code> literally, including delimiters. For parsing reasons, delimiters must be
balanced, but they are otherwise not special.</p>
<p>In the matcher, <code>$</code> <em>name</em> <code>:</code> <em>designator</em> matches the nonterminal in the Rust
syntax named by <em>designator</em>. Valid designators are:</p>
<ul>
<li><code>item</code>: an <a href="items.html">item</a></li>
<li><code>block</code>: a <a href="expressions.html#block-expressions">block</a></li>
<li><code>stmt</code>: a <a href="statements.html">statement</a></li>
<li><code>pat</code>: a <a href="expressions.html#match-expressions">pattern</a></li>
<li><code>expr</code>: an <a href="expressions.html">expression</a></li>
<li><code>ty</code>: a <a href="types.html">type</a></li>
<li><code>ident</code>: an <a href="identifiers.html">identifier</a></li>
<li><code>path</code>: a <a href="paths.html">path</a></li>
<li><code>tt</code>: a token tree (a single <a href="tokens.html">token</a> by matching <code>()</code>, <code>[]</code>, or <code>{}</code>)</li>
<li><code>meta</code>: the contents of an <a href="attributes.html">attribute</a></li>
</ul>
<p>In the transcriber, the
designator is already known, and so only the name of a matched nonterminal comes
after the dollar sign.</p>
<p>In both the matcher and transcriber, the Kleene star-like operator indicates
repetition. The Kleene star operator consists of <code>$</code> and parentheses, optionally
followed by a separator token, followed by <code>*</code> or <code>+</code>. <code>*</code> means zero or more
repetitions, <code>+</code> means at least one repetition. The parentheses are not matched or
transcribed. On the matcher side, a name is bound to <em>all</em> of the names it
matches, in a structure that mimics the structure of the repetition encountered
on a successful match. The job of the transcriber is to sort that structure
out.</p>
<p>The rules for transcription of these repetitions are called "Macro By Example".
Essentially, one "layer" of repetition is discharged at a time, and all of them
must be discharged by the time a name is transcribed. Therefore, <code>( $( $i:ident ),* ) => ( $i )</code> is an invalid macro, but <code>( $( $i:ident ),* ) => ( $( $i:ident ),* )</code> is acceptable (if trivial).</p>
<p>When Macro By Example encounters a repetition, it examines all of the <code>$</code>
<em>name</em> s that occur in its body. At the "current layer", they all must repeat
the same number of times, so <code>( $( $i:ident ),* ; $( $j:ident ),* ) => ( $( ($i,$j) ),* )</code> is valid if given the argument <code>(a,b,c ; d,e,f)</code>, but not
<code>(a,b,c ; d,e)</code>. The repetition walks through the choices at that layer in
lockstep, so the former input transcribes to <code>(a,d), (b,e), (c,f)</code>.</p>
<p>Nested repetitions are allowed.</p>
<a class="header" href="macros-by-example.html#parsing-limitations" id="parsing-limitations"><h3>Parsing limitations</h3></a>
<p>The parser used by the macro system is reasonably powerful, but the parsing of
Rust syntax is restricted in two ways:</p>
<ol>
<li>Macro definitions are required to include suitable separators after parsing
expressions and other bits of the Rust grammar. This implies that
a macro definition like <code>$i:expr [ , ]</code> is not legal, because <code>[</code> could be part
of an expression. A macro definition like <code>$i:expr,</code> or <code>$i:expr;</code> would be legal,
however, because <code>,</code> and <code>;</code> are legal separators. See <a href="https://github.com/rust-lang/rfcs/blob/master/text/0550-macro-future-proofing.md">RFC 550</a> for more information.</li>
<li>The parser must have eliminated all ambiguity by the time it reaches a <code>$</code>
<em>name</em> <code>:</code> <em>designator</em>. This requirement most often affects name-designator
pairs when they occur at the beginning of, or immediately after, a <code>$(...)*</code>;
requiring a distinctive token in front can solve the problem.</li>
</ol>
</div>
<!-- Mobile navigation buttons -->
<a href="macros.html" class="mobile-nav-chapters previous">
<i class="fa fa-angle-left"></i>
</a>
<a href="procedural-macros.html" class="mobile-nav-chapters next">
<i class="fa fa-angle-right"></i>
</a>
</div>
<a href="macros.html" class="nav-chapters previous" title="You can navigate through the chapters using the arrow keys">
<i class="fa fa-angle-left"></i>
</a>
<a href="procedural-macros.html" class="nav-chapters next" title="You can navigate through the chapters using the arrow keys">
<i class="fa fa-angle-right"></i>
</a>
</div>
<!-- Local fallback for Font Awesome -->
<script>
if ($(".fa").css("font-family") !== "FontAwesome") {
$('<link rel="stylesheet" type="text/css" href="_FontAwesome/css/font-awesome.css">').prependTo('head');
}
</script>
<!-- Livereload script (if served using the cli tool) -->
<script src="highlight.js"></script>
<script src="book.js"></script>
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
564935689ab5527f955e5449ded02799
>
files
>
2538
