1. Ryan Riley
  2. fparsec

Source

fparsec / Doc / html / users-guide / parser-functions.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
 <title>Parser functions</title>
 <link rel="stylesheet" type="text/css" media="all" href="../css/style.css" />
 <link rel="stylesheet" type="text/css" media="screen" href="../css/screen-sidebar.css" />
 <!--[if lt IE 9]>
 <link rel="stylesheet" type="text/css" media="all" href="../css/style-ie.css" />
 <![endif]-->
 <!--[if IE 6]>
 <link rel="stylesheet" type="text/css" media="all" href="../css/style-ie6.css" />
 <![endif]-->
 <link rel="stylesheet" type="text/css" media="print" href="../css/print.css" />
</head>
<body>
 <div id="fixed-layer">
 <div id="fixed-wrapper">
 <div id="sidebar">
  <div id="top-links"><span><a href="http://bitbucket.org/fparsec/main">FParsec @ BitBucket</a> | <a href="https://bitbucket.org/fparsec/main/issues">Report a bug</a> | <a href="mailto:fparsec [at] quanttec.com?subject=FParsec&amp;body=Hello Stephan,%0A%0A[your feedback]">Feedback</a></span></div>
  <div id="nav-tree">
   <table class="nav n1">
    <tbody class="nav-open n1">
     <tr class="nav-entry n1 _1">
      <td class="nav-number n1"></td>
      <td class="nav-title n1"><a href="../index.html">FParsec Documentation</a></td>
     </tr>
     <tr class="nav-subentries n1 _1">
      <td class="nav-subentries-number n1"></td>
      <td class="nav-subentries n1">
       <table class="nav n2">
        <tbody class="nav-before-open n2">
         <tr class="nav-entry n2 _1">
          <td class="nav-number n2"><a href="../about/index.html"><span class="section-number">1</span><span class="nav-space"></span></a></td>
          <td class="nav-title n2"><a href="../about/index.html">About FParsec</a></td>
         </tr>
         <tr class="nav-entry n2 _2">
          <td class="nav-number n2"><a href="../license.html"><span class="section-number">2</span><span class="nav-space"></span></a></td>
          <td class="nav-title n2"><a href="../license.html">License</a></td>
         </tr>
         <tr class="nav-entry n2 _3">
          <td class="nav-number n2">
           <a href="../download-and-installation.html"><span class="section-number">3</span><span class="nav-space"></span></a>
          </td>
          <td class="nav-title n2"><a href="../download-and-installation.html">Download and installation</a></td>
         </tr>
         <tr class="nav-entry n2 _4">
          <td class="nav-number n2"><a href="../tutorial.html"><span class="section-number">4</span><span class="nav-space"></span></a></td>
          <td class="nav-title n2"><a href="../tutorial.html">Tutorial</a></td>
         </tr>
        </tbody>
        <tbody class="nav-open n2">
         <tr class="nav-entry n2 _5">
          <td class="nav-number n2"><a href="index.html"><span class="section-number">5</span><span class="nav-space"></span></a></td>
          <td class="nav-title n2"><a href="index.html">User’s Guide</a></td>
         </tr>
         <tr class="nav-subentries n2 _5">
          <td class="nav-subentries-number n2"></td>
          <td class="nav-subentries n2">
           <table class="nav n3">
            <tbody class="nav-open selected n3">
             <tr class="nav-entry selected n3 _1">
              <td class="nav-number selected n3"><a href="#"><span class="section-number">1</span><span class="nav-space"></span></a></td>
              <td class="nav-title selected n3"><a href="#">Parser functions</a></td>
             </tr>
            </tbody>
            <tbody class="nav-after-open n3">
             <tr class="nav-entry n3 _2">
              <td class="nav-number n3">
               <a href="running-parsers-on-input.html"><span class="section-number">2</span><span class="nav-space"></span></a>
              </td>
              <td class="nav-title n3"><a href="running-parsers-on-input.html">Running parsers on input</a></td>
             </tr>
             <tr class="nav-entry n3 _3">
              <td class="nav-number n3">
               <a href="internals-of-a-simple-parser-function.html"><span class="section-number">3</span><span class="nav-space"></span></a>
              </td>
              <td class="nav-title n3">
               <a href="internals-of-a-simple-parser-function.html">Internals of a simple <code class="fsharp"><span class="ci">Parser</span></code>
               function</a>
              </td>
             </tr>
             <tr class="nav-entry n3 _4">
              <td class="nav-number n3">
               <a href="applying-parsers-in-sequence.html"><span class="section-number">4</span><span class="nav-space"></span></a>
              </td>
              <td class="nav-title n3"><a href="applying-parsers-in-sequence.html">Applying parsers in sequence</a></td>
             </tr>
             <tr class="nav-entry n3 _5">
              <td class="nav-number n3"><a href="parsing-sequences.html"><span class="section-number">5</span><span class="nav-space"></span></a></td>
              <td class="nav-title n3"><a href="parsing-sequences.html">Parsing sequences</a></td>
             </tr>
             <tr class="nav-entry n3 _6">
              <td class="nav-number n3">
               <a href="parsing-alternatives.html"><span class="section-number">6</span><span class="nav-space"></span></a>
              </td>
              <td class="nav-title n3"><a href="parsing-alternatives.html">Parsing alternatives</a></td>
             </tr>
             <tr class="nav-entry n3 _7">
              <td class="nav-number n3">
               <a href="looking-ahead-and-backtracking.html"><span class="section-number">7</span><span class="nav-space"></span></a>
              </td>
              <td class="nav-title n3"><a href="looking-ahead-and-backtracking.html">Looking ahead and backtracking</a></td>
             </tr>
             <tr class="nav-entry n3 _8">
              <td class="nav-number n3">
               <a href="customizing-error-messages.html"><span class="section-number">8</span><span class="nav-space"></span></a>
              </td>
              <td class="nav-title n3"><a href="customizing-error-messages.html">Customizing error messages</a></td>
             </tr>
             <tr class="nav-entry n3 _9">
              <td class="nav-number n3">
               <a href="parsing-with-user-state.html"><span class="section-number">9</span><span class="nav-space"></span></a>
              </td>
              <td class="nav-title n3"><a href="parsing-with-user-state.html">Parsing with user state</a></td>
             </tr>
             <tr class="nav-entry n3 _0">
              <td class="nav-number n3">
               <a href="where-is-the-monad.html"><span class="section-number">10</span><span class="nav-space"></span></a>
              </td>
              <td class="nav-title n3"><a href="where-is-the-monad.html">Where is the monad?</a></td>
             </tr>
             <tr class="nav-entry n3 _1">
              <td class="nav-number n3">
               <a href="debugging-a-parser.html"><span class="section-number">11</span><span class="nav-space"></span></a>
              </td>
              <td class="nav-title n3"><a href="debugging-a-parser.html">Debugging a parser</a></td>
             </tr>
             <tr class="nav-entry n3 _2">
              <td class="nav-number n3">
               <a href="performance-optimizations.html"><span class="section-number">12</span><span class="nav-space"></span></a>
              </td>
              <td class="nav-title n3"><a href="performance-optimizations.html">Performance optimizations</a></td>
             </tr>
             <tr class="nav-entry n3 _3">
              <td class="nav-number n3"><a href="tips-and-tricks.html"><span class="section-number">13</span><span class="nav-space"></span></a></td>
              <td class="nav-title n3"><a href="tips-and-tricks.html">Tips and tricks</a></td>
             </tr>
            </tbody>
           </table>
          </td>
         </tr>
        </tbody>
        <tbody class="nav-after-open n2">
         <tr class="nav-entry n2 _6">
          <td class="nav-number n2"><a href="../reference/index.html"><span class="section-number">6</span><span class="nav-space"></span></a></td>
          <td class="nav-title n2"><a href="../reference/index.html">Reference</a></td>
         </tr>
        </tbody>
       </table>
      </td>
     </tr>
    </tbody>
   </table>
  </div>
  <div id="copyright">
    <span>Copyright © 2012 <a href="../about/contact.html">Stephan Tolksdorf</a></span>
  </div>
 </div>
 </div>
 </div>
 <div id="wrapper">
 <div id="main">
 <div id="main-content">
 <div id="breadcrumbs">
  <span class="breadcrumbs">
   <span id="breadcrumbs-parents"><a href="../index.html">FParsec Documentation</a><span class="breadcrumbs-sep"> > </span><a href="index.html">User’s Guide</a></span><span class="breadcrumbs-sep"> > </span>Parser functions
  </span>
 </div>
 <div class="section s2">
  <h1 class="title h2"><span><span class="section-number">5.1</span> Parser functions</span></h1>
  <div class="intro i2">
   <div class="para _1">
    <p>
     An FParsec parser is a function that reads input from a text stream. When it succeeds, it returns a result value (e.g. a parsed number or an <a
     href="http://en.wikipedia.org/wiki/Abstract_syntax_tree">AST</a> node); when it fails, it returns error messages describing what went wrong.
    </p>
   </div>
   <div class="para _2 lcinp">
    <p>
     The following type abbreviation from the <code class="fsharp"><a href="../reference/primitives.html"><span
     class="ci">Primitives</span></a></code> module defines the basic type of parser function supported throughout the FParsec library:
    </p>
<pre class="code fsharp"><span class="ck">type</span> <a href="../reference/primitives.html#members.Parser"><span class="ci">Parser</span></a><span class="cp">&lt;</span><span class="ctv">'Result</span><span class="cp">,</span><span class="ctv">'UserState</span><span class="cp">&gt;</span> <span class="cp">=</span> <a href="../reference/charstream.html#CharStream"><span class="ci">CharStream</span></a><span class="cp">&lt;</span><span class="ctv">'UserState</span><span class="cp">&gt;</span> <span class="cr">-&gt;</span> <a href="../reference/reply.html"><span class="ci">Reply</span></a><span class="cp">&lt;</span><span class="ctv">'Result</span><span class="cp">&gt;</span></pre>
   </div>
   <div class="para _3">
    <p>
     As you can see from this definition, parser functions only accept a single argument: a <code class="fsharp"><a
     href="../reference/charstream.html#CharStream"><span class="ci">CharStream</span></a><span class="cp">&lt;</span><span
     class="ctv">'UserState</span><span class="cp">&gt;</span></code> instance. The <code class="fsharp"><a
     href="../reference/charstream.html#CharStream"><span class="ci">CharStream</span></a></code> class is FParsec’s specialized stream type for
     &#x201C;text&#x201D; streams, i.e. streams of Unicode chars. A <code class="fsharp"><a href="../reference/charstream.html#CharStream"><span
     class="ci">CharStream</span></a></code> can either be created directly from a string or it can be created from a file path or <code
     class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span
     class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code>. In the latter cases the <code
     class="fsharp"><a href="../reference/charstream.html#CharStream"><span class="ci">CharStream</span></a></code> will take care of decoding the
     binary input into UTF‐16 chars, similar to what a <code class="fsharp"><span class="ci">System</span><span class="cm">.</span><span
     class="ci">IO</span><span class="cm">.</span><span class="ci">StreamReader</span></code> does. What separates <code class="fsharp"><a
     href="../reference/charstream.html#CharStream"><span class="ci">CharStream</span></a></code> from the <code class="fsharp"><span
     class="ci">StreamReader</span></code> and similar classes is that it comes with some advanced features that make it especially suitable for
     backtracking parser applications.
    </p>
   </div>
   <div class="para _4">
    <p>
     We will discuss the purpose of the <code class="fsharp"><span class="ctv">'UserState</span></code> type in more detail in later chapters. For now
     it’s enough to note that the user state is a user‐definable component of the <code class="fsharp"><a
     href="../reference/charstream.html#CharStream"><span class="ci">CharStream</span></a></code> state. If you don’t need a user state, you will
     normally define <code class="fsharp"><span class="ctv">'UserState</span></code> to be <code class="fsharp"><span class="ci">unit</span></code>.
     To save some key strokes and screen real estate, we usually abbreviate <code class="fsharp"><span class="ctv">'UserState</span></code> as <code
     class="fsharp"><span class="ctv">'u</span></code>.
    </p>
   </div>
   <div class="para _5">
    <p>
     The <code class="fsharp"><a href="../reference/reply.html"><span class="ci">Reply</span></a><span class="cp">&lt;</span><span
     class="ctv">'Result</span><span class="cp">&gt;</span></code> value returned from a parser function is a a simple value type container for the
     parser result and possible error messages. It contains a status field indicating whether the parser succeeded or not, a field for the result
     value (of type <code class="fsharp"><span class="ctv">'Result</span></code>) and a field with a possibly empty list of error messages. We will
     explain these fields in more details in <a href="internals-of-a-simple-parser-function.html">section 5.3</a>.
    </p>
   </div>
   <div class="para _6">
    <p>
     A very basic example of a parser is the <code class="fsharp"><a href="../reference/charparsers.html#members.asciiLower"><span
     class="ci">asciiLower</span></a></code> parser from the <code class="fsharp"><a href="../reference/charparsers.html"><span
     class="ci">CharParsers</span></a></code> module:
    </p>
<pre class="code fsharp"><span class="ck">val</span> <a href="../reference/charparsers.html#members.asciiLower"><span class="ci">asciiLower</span></a><span class="cp">:</span> <a href="../reference/primitives.html#members.Parser"><span class="ci">Parser</span></a><span class="cp">&lt;</span><span class="ci">char</span><span class="cp">,</span><span class="ctv">'u</span><span class="cp">&gt;</span></pre>
    <p>
     It parses any lower case ASCII char, i.e. any char in the range <code class="fsharp"><span class="cc"><span class="cld">'</span>a<span
     class="crd">'</span></span></code><code class="fsharp"><span class="cc"><span class="cld">'</span>z<span class="crd">'</span></span></code>,
     and, if successful, returns the parsed char as part of its reply.
    </p>
   </div>
   <div class="para _7">
    <p>
     Many predefined parsers expect one or more parameter values as arguments. Take for instance the <code class="fsharp"><span
     class="ci">skipString</span></code> function:
    </p>
<pre class="code fsharp"><span class="ck">val</span> <span class="ci">skipString</span><span class="cp">:</span> <span class="ci">string</span> <span class="cr">-&gt;</span> <a href="../reference/primitives.html#members.Parser"><span class="ci">Parser</span></a><span class="cp">&lt;</span><span class="ci">unit</span><span class="cp">,</span><span class="ctv">'u</span><span class="cp">&gt;</span></pre>
    <p>It takes a string as an argument and returns a parser that skips over this (and only this) string in the input.</p>
   </div>
   <div class="para _8 lcinp">
    <div class="admonition">
     <div class="admonition-title">Note</div>
     <div class="admonition-body">
      <div class="para _1">
       <p>
        Implementing parser grammars with FParsec usually means composing parsers for higher‐level grammar rules from parsers for lower‐level rules.
        You start with simple parsers for the leaf nodes of your grammar and then work your way up step‐by‐step until you eventually obtain a parser
        for the complete grammar. The simple representation of parsers as functions makes this composition particularly easy and allows for a
        straightforward and intuitive implementation of the library primitives.
       </p>
      </div>
     </div>
    </div>
   </div>
  </div>
 </div>
 </div>
 </div>
 </div>
</body>
</html>