

<!DOCTYPE html>
<!-- Server: sfs-forge-3 -->


    

















<html lang="en" class="no-js">
<head>
    <meta content="text/html; charset=UTF-8" http-equiv="content-type"/>
    <title>
  XSB / Src  (SVN)-old /
  [r6869]
  /trunk/XSB/docs/userman/library.tex
</title>
    

<meta name="viewport" content="width=1100">


<link rel="icon" sizes="180x180" href="https://a.fsdn.com/con/img/sandiego/logo-180x180.png" type="image/png">
<link rel="icon" sizes="any" href="https://a.fsdn.com/con/img/sandiego/svg/originals/sf-icon-orange-no_sf.svg" type="image/svg+xml">
<link rel="apple-touch-icon" sizes="180x180" href="https://a.fsdn.com/con/img/sandiego/logo-180x180.png">
<link rel="mask-icon" href="https://a.fsdn.com/con/img/sandiego/svg/originals/sf-icon-orange-no_sf.svg" color="#FF6600">


<script src="https://a.fsdn.com/allura/nf/1753722141/_ew_/theme/sftheme/js/sftheme/cmp2.js"></script>






    
    
    
    
    
    
    
    
    <link rel="stylesheet" href="https://a.fsdn.com/con/css/lato.css?">


<script>
if (!window.SF) { window.SF = {}; }
SF.sandiego = false;
SF.sandiego_chrome = true;
SF.cdn = "https://a.fsdn.com/con";
SF.fpid = '4a069542-71c8-4d9a-a4e6-2bb5405af62a';
SF.billboard_route = '/software/product/$slug/';
</script>
    
        <!-- ew:head_css -->

    
        <link rel="stylesheet"
                type="text/css"
                href="https://a.fsdn.com/allura/nf/1753722141/_ew_/_slim/css?href=allura%2Fcss%2Fforge%2Fhilite.css%3Ballura%2Fcss%2Fforge%2Ftooltipster.css"
                >
    
        <link rel="stylesheet"
                type="text/css"
                href="https://a.fsdn.com/allura/nf/1753722141/_ew_/allura/css/font-awesome.min.css"
                >
    
        <link rel="stylesheet"
                type="text/css"
                href="https://a.fsdn.com/allura/nf/1753722141/_ew_/theme/sftheme/css/forge.css"
                >
    
        
<!-- /ew:head_css -->

    
    
        <!-- ew:head_js -->

    
        <script type="text/javascript" src="https://a.fsdn.com/allura/nf/1753722141/_ew_/_slim/js?href=allura%2Fjs%2Fjquery-3.6.0.min.js%3Ballura%2Fjs%2Fjquery.cookie-1.4.1.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fshared_head.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Ftypescript%2Fcompliance.js"></script>
    
        
<!-- /ew:head_js -->

    

    
        <style type="text/css">
            /* make URL &amp; Project custom fields in support tickets not get hidden as much */
.project-forge.mountpoint-site-support .view_holder .grid-4:nth-child(5),
.project-forge.mountpoint-site-support .view_holder .grid-4:nth-child(6) {
  overflow: visible;
  font-size: 22px;
  width: 340px;
  line-height: 1;
  margin-bottom: 5px;
}
.project-forge.mountpoint-site-support .view_holder .grid-4:nth-child(5) label, .project-forge.mountpoint-site-support .view_holder .grid-4:nth-child(6) label {
  font-size: 14px;
}
        </style>
    
    
    <link rel="alternate" type="application/rss+xml" title="RSS" href="/p/xsb/src/feed.rss"/>
    <link rel="alternate" type="application/atom+xml" title="Atom" href="/p/xsb/src/feed.atom"/>
    <style type="text/css">
        #access_urls .btn-set {
            
            min-width: 14em;
        }
    </style>

    <style>.XJExcHjxKFVjDmsOEcOFwppVwoDlsKwExMQ {
        display: none
    }</style>

    
    
    
        <link rel="canonical" href="https://sourceforge.net/p/xsb/src/6869/tree/trunk/XSB/docs/userman/library.tex" />
    


    

<script>
    var data = {hem: null };
    bizx.uids.gatherAndClean(data);
</script>



<script>
    function initPiwik(){
      var _paq = window._paq = window._paq || [];
      _paq.push(['trackPageView', document.title, {
            dimension1: 'xsb',
            dimension2: 'svn'
      }]);
      _paq.push(['enableLinkTracking']);
      
          _paq.push(['enableHeartBeatTimer']);
      
      (function() {
        var u="//analytics.slashdotmedia.com/";
        _paq.push(['setTrackerUrl', u+'sf.php']);
        _paq.push(['setSiteId', 39]);
        
        var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
        g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'sf.js'; s.parentNode.insertBefore(g,s);
      })();
    }
    bizx.cmp.ifConsent({ purposes: ['storage', 'measurement'], vendors: 'sdm'}, initPiwik);
</script>






<!-- Hubspot tracking -->






 <script>
    $(function() {
        bizx.cmp.ifConsent({ purposes: 'all' , vendors: 'narrative'}, function() {
            var current_time = (new Date()).getTime();
            let imageUrl = "https://io.narrative.io/?companyId=2440&id=first_party%3A4a069542-71c8-4d9a-a4e6-2bb5405af62a&id=site_name%3Asourceforge.net&id=url%3A%2Fp%2Fxsb%2Fsrc%2F6869%2Ftree%2Ftrunk%2FXSB%2Fdocs%2Fuserman%2Flibrary.tex&id=pagetitle%3A%24PAGE_TITLE&id=vertical%3AOpen+Source+Software&id=product%3AXSB";
            imageUrl = imageUrl.replace(encodeURIComponent("$PAGE_TITLE"), document.title);  

            imageUrl = URL.parse(imageUrl);
            let hem = bizx.uids.getHem();
            if (hem) {
                imageUrl.searchParams.append('id', 'hem:' + hem);
            }
            imageUrl.searchParams.append('rand', current_time);

            var image = new Image();
            image.src = imageUrl.toString();
            image.style.display = "none";
            image.style.height = 0;
            image.style.width = 0;
            document.body.appendChild(image);
        });
    });
</script>



</head>

<body class="
body_class sandiego_chrome  legacy_chrome  l-allow-natural-width 
" id="forge">

    
        <!-- ew:body_top_js -->

    
        
<!-- /ew:body_top_js -->

    





<div class="off-canvas position-right" id="offCanvas" data-off-canvas>
    <!-- Menu -->
    <ul class="header-nav-menulist">
        <li class="highlight search">
            
            
                
            
            
    <form method="get" action="/directory/" class="m-search-form">
    
        <input type="text" placeholder="Search for software or solutions" autocomplete="off" name="q" >
        
        <label >
            <input type="submit" class="bt" value="">
            


<svg  data-name="search" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1216 832q0-185-131.5-316.5t-316.5-131.5-316.5 131.5-131.5 316.5 131.5 316.5 316.5 131.5 316.5-131.5 131.5-316.5zm512 832q0 52-38 90t-90 38q-54 0-90-38l-343-342q-179 124-399 124-143 0-273.5-55.5t-225-150-150-225-55.5-273.5 55.5-273.5 150-225 225-150 273.5-55.5 273.5 55.5 225 150 150 225 55.5 273.5q0 220-124 399l343 343q37 37 37 90z"/></svg>
        </label>
    </form>
        </li>
        
        <li class="highlight"><a href="/auth/">Join/Login</a></li>
        
        <li><a href="/software/">Business Software</a></li>
        <li><a href="/directory/">Open Source Software</a></li>
        <li><a  href="/software/vendors/" title="For Vendors">For Vendors</a></li>
        <li><a href="/blog/" title="Blog">Blog</a></li>
        <li><a href="/about">About</a></li>
        <li><a id="header-nav-more" data-toggle="header-nav-more header-nav-more-content" data-toggler=".toggled">More</a></li>
        <li>
            <ul id="header-nav-more-content" class="toggled" data-toggler=".toggled">
                
    

    
    
        <li><a href="/articles/">Articles</a></li>
    
    

    
 
                
                <li><a href="/create">Create</a></li>
                
                <li><a href="https://sourceforge.net/articles/category/sourceforge-podcast/">SourceForge Podcast</a></li>
                
                    <li><a href="https://sourceforge.net/p/forge/documentation/Docs%20Home/">Site Documentation</a></li>
                
                <li><a href="/user/newsletters">Subscribe to our Newsletter</a></li>
                <li><a href="/support">Support Request</a></li>
            </ul>
        </li>
    </ul>
</div>
<div class="off-canvas-content" data-off-canvas-content>

    




<script>
    SF.linkout_icon = '<svg  data-name="sf-linkout-icon" xmlns="http://www.w3.org/2000/svg" x="0px" y="0px" viewBox="0 0 300 300" style="enable-background:new 0 0 300 300;" xml:space="preserve"><polygon class="st0" points="243.2,243.2 56.8,243.2 56.8,56.8 123,56.8 123,9 9,9 9,291 291,291 291,179.4 243.2,179 "/><polygon class="st0" points="128.5,213 155,186.5 176,165.5 206.7,196.3 235.5,132.5 248.9,102.6 290.6,9.8 291,9 290.6,9.2 197.4,51.1 169.1,63.8 103.7,93.3 137,126.5 115.9,147.5 89.5,174 "/></svg>';
</script>


<div class="l-header-nav  sandiego">

    <section class="sandiego l-header-nav-top show-for-large">
        <div class="row">
            <a href="/" title="Home" class="sf-logo">
                
    
    <img src="https://a.fsdn.com/con/images/sandiego/sf-logo-full.svg"  alt="SourceForge logo" class="sf-logo-full"/>
            </a>
            <nav class="links">
                
                    <a href="/user/newsletters" title="Subscribe to our newsletter"><span class="newsletter-icon">


<svg  data-name="mmSF_11mail" xmlns="http://www.w3.org/2000/svg" x="0px" y="0px" viewBox="0 0 42 42" enable-background="new 0 0 42 42" xml:space="preserve"><path fill="#FFFFFF" d="M0,6v30h42V6H0z M24.2,21.2c-0.8,0.8-2.3,2-3.2,2c-0.9,0-2.4-1.2-3.2-2L5.8,9.7h30.3L24.2,21.2z M13.7,21l-9.9,9.4V11.6L13.7,21z M15.7,23L15.7,23c0.5,0.5,2.9,2.9,5.3,2.9c2.4,0,4.8-2.4,5.2-2.8l0.1-0.1l9.8,9.4H5.8L15.7,23z M28.3,21l9.9-9.5v18.9L28.3,21z"/></svg></span></a>
                
                <a href="/software/vendors/" title="For Vendors">For Vendors</a>
                
                
                    <a href="/support" title="Help">Help</a>
                    <a href="/create/" title="Create">Create</a>
                

                
                <a href="/user/registration" title="Join" >Join</a>
                <a href="/auth/" title="Login">Login</a>
                
            </nav>
        </div>
    </section>

    <section class="sandiego l-header-nav-top hide-for-large">
        <div class="row">
            <a href="/" title="Home" class="sf-logo">
                
    
    <img src="https://a.fsdn.com/con/images/sandiego/sf-logo-full.svg"  alt="SourceForge logo" class="sf-logo-full"/>
            </a>
            <div class="title-bar-right">
                <button type="button" aria-label="Toggle Main Menu" class="menu-icon" data-toggle="offCanvas"></button>
            </div>
        </div>
    </section>
    <section class="sandiego l-header-nav-bottom">
        <nav class="row">
            <a href="/" title="Home" class="sf-logo">
                
    
    <img src="https://a.fsdn.com/con/images/sandiego/sf-logo-full.svg"  alt="SourceForge logo" class="sf-logo-full"/>
            </a>
            <div class="links">
                
    
        <div class="nav-dropdown">
            <a href="/software/">Business Software</a>
            
        </div>
        <div class="nav-dropdown">
            <a href="/directory/" title="Browse">Open Source Software</a>
            
        </div>
        <div class="nav-dropdown">
            <a href="https://sourceforge.net/articles/category/sourceforge-podcast/">SourceForge Podcast</a>
        </div>
        <div class="nav-dropdown">
            <a>Resources</a>
            <ul class="nav-dropdown-menu">
                  <li><a href="/articles/">Articles</a></li>
                  
                  <li><a href="/software/case-studies/">Case Studies</a></li>
                  
                  <li><a href="/blog/">Blog</a></li>
            </ul>
        </div>
    

                <div class="dev-menu-when-stuck">
                    Menu
                    <ul class="dev-menu-dropdown header-nav-menulist">
                        <li><a href="/support">Help</a></li>
                        <li><a href="/create">Create</a></li>
                        <li><a href="/user/registration/" title="Join" >Join</a></li>
                        <li><a href="/auth/" title="Login">Login</a></li>
                    </ul>
                </div>
                <div class="search-toggle-when-stuck">
                    <a class="search-toggle">
                        


<svg  data-name="search" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1216 832q0-185-131.5-316.5t-316.5-131.5-316.5 131.5-131.5 316.5 131.5 316.5 316.5 131.5 316.5-131.5 131.5-316.5zm512 832q0 52-38 90t-90 38q-54 0-90-38l-343-342q-179 124-399 124-143 0-273.5-55.5t-225-150-150-225-55.5-273.5 55.5-273.5 150-225 225-150 273.5-55.5 273.5 55.5 225 150 150 225 55.5 273.5q0 220-124 399l343 343q37 37 37 90z"/></svg>
                    </a>
                </div>
            </div>

            <div class="search">
                
                
    
    
        <div class="main-nav-link">
            
            
            <a href="https://www.avast.com/lp-free-av?full_trSrc=mmm_srf_dlp_008_406_a&amp;utm_medium=referral&amp;utm_source=sourceforge&amp;utm_campaign=srf_dlp_008_406_a:site_banner" rel="nofollow" target="_blank" id="main-nav-badge-link" data-label="avastjuly">
                <img src="https://a.fsdn.com/con/assets/maxnav/sourceforge/ai-protection-32-75dd98b2.png"  srcset="https://a.fsdn.com/con/assets/maxnav/sourceforge/ai-protection-75de80f6.png 2x"  alt="" id="main-nav-image"/>
            </a>
        </div>
    


                
                    
                
                
                
                
    <form method="get" action="/directory/" class="m-search-form">
    
    <div class="typeahead__container">
      <div class="typeahead__field">
        <div class="typeahead__query">
        
        <input type="text" placeholder="Search for software or solutions" autocomplete="off" name="q" >
        
        </div>
        
        <label >
            <input type="submit" class="bt" value="">
            


<svg  data-name="search" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1216 832q0-185-131.5-316.5t-316.5-131.5-316.5 131.5-131.5 316.5 131.5 316.5 316.5 131.5 316.5-131.5 131.5-316.5zm512 832q0 52-38 90t-90 38q-54 0-90-38l-343-342q-179 124-399 124-143 0-273.5-55.5t-225-150-150-225-55.5-273.5 55.5-273.5 150-225 225-150 273.5-55.5 273.5 55.5 225 150 150 225 55.5 273.5q0 220-124 399l343 343q37 37 37 90z"/></svg>
        </label>
      </div>
    </div>
    
    </form>
                
            </div>
        </nav>
        
    </section>
    
</div>
    
    
    <div class="notification-on-project-page">
    
        
    
    
    
    </div>
    
    


    <section id="page-body" class=" neighborhood-Projects project-xsb mountpoint-src 

">
        <div id="nav_menu_holder">
            
                
                    
    <div class="sandiego"> 
            
            
            
            
<section class="project-masthead"> 
    
    

    
<div class="backdrop" style="box-sizing: content-box; padding-bottom: 24px"></div>

    <div class="content">
    
        
    <nav id="breadcrumbs" class="breadcrumbs rtl">
        <ul itemscope itemtype="http://schema.org/BreadcrumbList">
            <li itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
                <a itemprop="item" href="/"><span itemprop="name">Home</span></a>
                <meta itemprop="position" content="1"/>
            </li>
            <li itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
                <a itemprop="item" href="/directory/"><span itemprop="name">Browse</span></a>
                <meta itemprop="position" content="2"/>
            </li>
            
            
                
                
            
            
                
            
            
                <li itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
                    <a itemprop="item" href="/p/xsb/"><span itemprop="name">XSB</span></a>
                <meta itemprop="position" content="3"/>
                </li>
            
                <li itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
                    <span itemprop="name">Src  (SVN)-old</span>
                <meta itemprop="position" content="4"/>
                </li>
            
        </ul>
    </nav>
    
    
    
        
                
                
<div class="overview">
    


<div class="project-icon   " >
    
    
    <img itemprop="image" alt="XSB" title="XSB" 
    
    
    src="https://a.fsdn.com/allura/p/xsb/icon?1368563712"
    /></div>


    
    <div class="title "> 

        <meta itemprop="name" content="XSB"/>
        <h1  >XSB Src  (SVN)-old
        </h1>
        
            
            
          
        
            
            
            <div class="as-h3 brought-by">
                
                Brought to you by:
                
                    <a href="/u/carlandersen/profile/">carlandersen</a>,
                    
                
                    <a href="/u/dwarren/profile/">dwarren</a>,
                    
                
                    <a href="/u/evansbj/profile/">evansbj</a>,
                    
                
                    <a href="/u/kifer/profile/">kifer</a>,
                    
                
                    
                        and <a href="/p/xsb/_members/">3 others</a>
                    
                
            </div>
            
        

        

        
    </div>


    

</div>

                
                
    
  
            
            
        
    </div>
</section>

        </div>
    

                
            
        </div>
        <div id="top_nav" class="">
            
                
<div id="top_nav_admin">
<ul class="dropdown">
  
  
    <li class="">
        <a href="/projects/xsb/" class="tool-summary-32" >
            Summary
        </a>
        
        
    </li>
  
    <li class="">
        <a href="/projects/xsb/files/" class="tool-files-sf-32" >
            Files
        </a>
        
        
    </li>
  
    <li class="">
        <a href="/projects/xsb/reviews/" class="tool-reviews-32" >
            Reviews
        </a>
        
        
    </li>
  
    <li class="">
        <a href="/projects/xsb/support" class="tool-support-32" >
            Support
        </a>
        
        
    </li>
  
    <li class="">
        <a href="/p/xsb/mailman/" class="tool-mailman-32" >
            Mail Lists
        </a>
        
        
    </li>
  
    <li class="">
        <a href="/p/xsb/_list/tickets" class="tool-tickets-32" >
            Tickets ▾
        </a>
        
        
            <ul>
                
                    <li class=""><a href="/p/xsb/bugs/" >Bugs</a></li>
                
                    <li class=""><a href="/p/xsb/feature-requests/" >Feature Requests</a></li>
                
                    <li class=""><a href="/p/xsb/support-requests/" >Support Requests</a></li>
                
                    <li class=""><a href="/p/xsb/patches/" >Patches</a></li>
                
            </ul>
        
    </li>
  
    <li class="">
        <a href="/p/xsb/news/" class="tool-blog-32" >
            News
        </a>
        
        
    </li>
  
    <li class="">
        <a href="/p/xsb/code/" class="tool-git-32" >
            Sources (GIT)
        </a>
        
        
    </li>
  
    <li class="selected">
        <a href="/p/xsb/src/" class="tool-svn-32" >
            Src  (SVN)-old
        </a>
        
        
    </li>
  
  
</ul>
</div>


            
        </div>
        <div id="content_base">
            

    
                
                    
<a id="sidebar-activate" href="#">
    <span class="btn-label">Menu</span>
    <span class="btn-arrow-down">▾</span>
    <span class="btn-arrow-up">▴</span>
</a>

                        


<div id="sidebar">
  
    <div class="placeholder-no-searchbox">&nbsp;</div>
  
    
    
      
      
        
    
      <ul class="sidebarmenu">
      
    
  <li>
      
        <a class="icon" href="/p/xsb/src/commit_browser" rel="nofollow" title="Browse Commits"><i class="fa fa-list"></i>
      
      <span>Browse Commits</span>
      </a>
  </li>
  
      
        
    
  <li>
      
        <a href="/p/xsb/src/"  rel="nofollow" >
      
      <span>Browse Files</span>
      </a>
  </li>
  
      
    
    
      </ul>
      
    
    
</div>



<script>
$('#sidebar-admin-header').on('click', function(e){
    $("#sidebar-admin-menu").toggleClass("hidden");
    $(this).toggleClass("expanded");
    e.preventDefault();
});
</script>

                    

                    
                
                
                    
                
                <div class="grid-20 pad">
                    <h2 class="dark title">
                        <span>
<a href="/p/xsb/src/6869/" rel="nofollow">[r6869]</a>:

  
      <a href="./../../../../" rel="nofollow"><b class="fa fa-folder-open-o" title="Root directory"></b></a> /
  
  
    <a href="./../../../" rel="nofollow">trunk</a> /
  
    <a href="./../../" rel="nofollow">XSB</a> /
  
    <a href="./../" rel="nofollow">docs</a> /
  
    <a href="./" rel="nofollow">userman</a> /
  
 library.tex
</span>
                        <!-- actions -->
                        <small>
                            

    
    <a class="icon" href="#" id="maximize-content" title="Maximize"><i class="fa fa-expand"></i>&nbsp;Maximize</a>
    <a class="icon" href="#" id="restore-content" title="Restore"><i class="fa fa-compress"></i>&nbsp;Restore</a>
<a class="icon" href="/p/xsb/src/6869/log/?path=/trunk/XSB/docs/userman/library.tex" rel="nofollow" title="History"><i class="fa fa-calendar"></i>&nbsp;History</a>

                        </small>
                        <!-- /actions -->
                    </h2>
                    
                    <div>
                        
  

                        
  
    <p><a rel="nofollow" href="?format=raw">Download this file</a></p>
    <div class="clip grid-19 codebrowser">
      <h3>
        3202 lines (2720 with data), 126.9 kB
      </h3>
      
        <div class="codehilite"><table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">   1</span>
<span class="normal">   2</span>
<span class="normal">   3</span>
<span class="normal">   4</span>
<span class="normal">   5</span>
<span class="normal">   6</span>
<span class="normal">   7</span>
<span class="normal">   8</span>
<span class="normal">   9</span>
<span class="normal">  10</span>
<span class="normal">  11</span>
<span class="normal">  12</span>
<span class="normal">  13</span>
<span class="normal">  14</span>
<span class="normal">  15</span>
<span class="normal">  16</span>
<span class="normal">  17</span>
<span class="normal">  18</span>
<span class="normal">  19</span>
<span class="normal">  20</span>
<span class="normal">  21</span>
<span class="normal">  22</span>
<span class="normal">  23</span>
<span class="normal">  24</span>
<span class="normal">  25</span>
<span class="normal">  26</span>
<span class="normal">  27</span>
<span class="normal">  28</span>
<span class="normal">  29</span>
<span class="normal">  30</span>
<span class="normal">  31</span>
<span class="normal">  32</span>
<span class="normal">  33</span>
<span class="normal">  34</span>
<span class="normal">  35</span>
<span class="normal">  36</span>
<span class="normal">  37</span>
<span class="normal">  38</span>
<span class="normal">  39</span>
<span class="normal">  40</span>
<span class="normal">  41</span>
<span class="normal">  42</span>
<span class="normal">  43</span>
<span class="normal">  44</span>
<span class="normal">  45</span>
<span class="normal">  46</span>
<span class="normal">  47</span>
<span class="normal">  48</span>
<span class="normal">  49</span>
<span class="normal">  50</span>
<span class="normal">  51</span>
<span class="normal">  52</span>
<span class="normal">  53</span>
<span class="normal">  54</span>
<span class="normal">  55</span>
<span class="normal">  56</span>
<span class="normal">  57</span>
<span class="normal">  58</span>
<span class="normal">  59</span>
<span class="normal">  60</span>
<span class="normal">  61</span>
<span class="normal">  62</span>
<span class="normal">  63</span>
<span class="normal">  64</span>
<span class="normal">  65</span>
<span class="normal">  66</span>
<span class="normal">  67</span>
<span class="normal">  68</span>
<span class="normal">  69</span>
<span class="normal">  70</span>
<span class="normal">  71</span>
<span class="normal">  72</span>
<span class="normal">  73</span>
<span class="normal">  74</span>
<span class="normal">  75</span>
<span class="normal">  76</span>
<span class="normal">  77</span>
<span class="normal">  78</span>
<span class="normal">  79</span>
<span class="normal">  80</span>
<span class="normal">  81</span>
<span class="normal">  82</span>
<span class="normal">  83</span>
<span class="normal">  84</span>
<span class="normal">  85</span>
<span class="normal">  86</span>
<span class="normal">  87</span>
<span class="normal">  88</span>
<span class="normal">  89</span>
<span class="normal">  90</span>
<span class="normal">  91</span>
<span class="normal">  92</span>
<span class="normal">  93</span>
<span class="normal">  94</span>
<span class="normal">  95</span>
<span class="normal">  96</span>
<span class="normal">  97</span>
<span class="normal">  98</span>
<span class="normal">  99</span>
<span class="normal"> 100</span>
<span class="normal"> 101</span>
<span class="normal"> 102</span>
<span class="normal"> 103</span>
<span class="normal"> 104</span>
<span class="normal"> 105</span>
<span class="normal"> 106</span>
<span class="normal"> 107</span>
<span class="normal"> 108</span>
<span class="normal"> 109</span>
<span class="normal"> 110</span>
<span class="normal"> 111</span>
<span class="normal"> 112</span>
<span class="normal"> 113</span>
<span class="normal"> 114</span>
<span class="normal"> 115</span>
<span class="normal"> 116</span>
<span class="normal"> 117</span>
<span class="normal"> 118</span>
<span class="normal"> 119</span>
<span class="normal"> 120</span>
<span class="normal"> 121</span>
<span class="normal"> 122</span>
<span class="normal"> 123</span>
<span class="normal"> 124</span>
<span class="normal"> 125</span>
<span class="normal"> 126</span>
<span class="normal"> 127</span>
<span class="normal"> 128</span>
<span class="normal"> 129</span>
<span class="normal"> 130</span>
<span class="normal"> 131</span>
<span class="normal"> 132</span>
<span class="normal"> 133</span>
<span class="normal"> 134</span>
<span class="normal"> 135</span>
<span class="normal"> 136</span>
<span class="normal"> 137</span>
<span class="normal"> 138</span>
<span class="normal"> 139</span>
<span class="normal"> 140</span>
<span class="normal"> 141</span>
<span class="normal"> 142</span>
<span class="normal"> 143</span>
<span class="normal"> 144</span>
<span class="normal"> 145</span>
<span class="normal"> 146</span>
<span class="normal"> 147</span>
<span class="normal"> 148</span>
<span class="normal"> 149</span>
<span class="normal"> 150</span>
<span class="normal"> 151</span>
<span class="normal"> 152</span>
<span class="normal"> 153</span>
<span class="normal"> 154</span>
<span class="normal"> 155</span>
<span class="normal"> 156</span>
<span class="normal"> 157</span>
<span class="normal"> 158</span>
<span class="normal"> 159</span>
<span class="normal"> 160</span>
<span class="normal"> 161</span>
<span class="normal"> 162</span>
<span class="normal"> 163</span>
<span class="normal"> 164</span>
<span class="normal"> 165</span>
<span class="normal"> 166</span>
<span class="normal"> 167</span>
<span class="normal"> 168</span>
<span class="normal"> 169</span>
<span class="normal"> 170</span>
<span class="normal"> 171</span>
<span class="normal"> 172</span>
<span class="normal"> 173</span>
<span class="normal"> 174</span>
<span class="normal"> 175</span>
<span class="normal"> 176</span>
<span class="normal"> 177</span>
<span class="normal"> 178</span>
<span class="normal"> 179</span>
<span class="normal"> 180</span>
<span class="normal"> 181</span>
<span class="normal"> 182</span>
<span class="normal"> 183</span>
<span class="normal"> 184</span>
<span class="normal"> 185</span>
<span class="normal"> 186</span>
<span class="normal"> 187</span>
<span class="normal"> 188</span>
<span class="normal"> 189</span>
<span class="normal"> 190</span>
<span class="normal"> 191</span>
<span class="normal"> 192</span>
<span class="normal"> 193</span>
<span class="normal"> 194</span>
<span class="normal"> 195</span>
<span class="normal"> 196</span>
<span class="normal"> 197</span>
<span class="normal"> 198</span>
<span class="normal"> 199</span>
<span class="normal"> 200</span>
<span class="normal"> 201</span>
<span class="normal"> 202</span>
<span class="normal"> 203</span>
<span class="normal"> 204</span>
<span class="normal"> 205</span>
<span class="normal"> 206</span>
<span class="normal"> 207</span>
<span class="normal"> 208</span>
<span class="normal"> 209</span>
<span class="normal"> 210</span>
<span class="normal"> 211</span>
<span class="normal"> 212</span>
<span class="normal"> 213</span>
<span class="normal"> 214</span>
<span class="normal"> 215</span>
<span class="normal"> 216</span>
<span class="normal"> 217</span>
<span class="normal"> 218</span>
<span class="normal"> 219</span>
<span class="normal"> 220</span>
<span class="normal"> 221</span>
<span class="normal"> 222</span>
<span class="normal"> 223</span>
<span class="normal"> 224</span>
<span class="normal"> 225</span>
<span class="normal"> 226</span>
<span class="normal"> 227</span>
<span class="normal"> 228</span>
<span class="normal"> 229</span>
<span class="normal"> 230</span>
<span class="normal"> 231</span>
<span class="normal"> 232</span>
<span class="normal"> 233</span>
<span class="normal"> 234</span>
<span class="normal"> 235</span>
<span class="normal"> 236</span>
<span class="normal"> 237</span>
<span class="normal"> 238</span>
<span class="normal"> 239</span>
<span class="normal"> 240</span>
<span class="normal"> 241</span>
<span class="normal"> 242</span>
<span class="normal"> 243</span>
<span class="normal"> 244</span>
<span class="normal"> 245</span>
<span class="normal"> 246</span>
<span class="normal"> 247</span>
<span class="normal"> 248</span>
<span class="normal"> 249</span>
<span class="normal"> 250</span>
<span class="normal"> 251</span>
<span class="normal"> 252</span>
<span class="normal"> 253</span>
<span class="normal"> 254</span>
<span class="normal"> 255</span>
<span class="normal"> 256</span>
<span class="normal"> 257</span>
<span class="normal"> 258</span>
<span class="normal"> 259</span>
<span class="normal"> 260</span>
<span class="normal"> 261</span>
<span class="normal"> 262</span>
<span class="normal"> 263</span>
<span class="normal"> 264</span>
<span class="normal"> 265</span>
<span class="normal"> 266</span>
<span class="normal"> 267</span>
<span class="normal"> 268</span>
<span class="normal"> 269</span>
<span class="normal"> 270</span>
<span class="normal"> 271</span>
<span class="normal"> 272</span>
<span class="normal"> 273</span>
<span class="normal"> 274</span>
<span class="normal"> 275</span>
<span class="normal"> 276</span>
<span class="normal"> 277</span>
<span class="normal"> 278</span>
<span class="normal"> 279</span>
<span class="normal"> 280</span>
<span class="normal"> 281</span>
<span class="normal"> 282</span>
<span class="normal"> 283</span>
<span class="normal"> 284</span>
<span class="normal"> 285</span>
<span class="normal"> 286</span>
<span class="normal"> 287</span>
<span class="normal"> 288</span>
<span class="normal"> 289</span>
<span class="normal"> 290</span>
<span class="normal"> 291</span>
<span class="normal"> 292</span>
<span class="normal"> 293</span>
<span class="normal"> 294</span>
<span class="normal"> 295</span>
<span class="normal"> 296</span>
<span class="normal"> 297</span>
<span class="normal"> 298</span>
<span class="normal"> 299</span>
<span class="normal"> 300</span>
<span class="normal"> 301</span>
<span class="normal"> 302</span>
<span class="normal"> 303</span>
<span class="normal"> 304</span>
<span class="normal"> 305</span>
<span class="normal"> 306</span>
<span class="normal"> 307</span>
<span class="normal"> 308</span>
<span class="normal"> 309</span>
<span class="normal"> 310</span>
<span class="normal"> 311</span>
<span class="normal"> 312</span>
<span class="normal"> 313</span>
<span class="normal"> 314</span>
<span class="normal"> 315</span>
<span class="normal"> 316</span>
<span class="normal"> 317</span>
<span class="normal"> 318</span>
<span class="normal"> 319</span>
<span class="normal"> 320</span>
<span class="normal"> 321</span>
<span class="normal"> 322</span>
<span class="normal"> 323</span>
<span class="normal"> 324</span>
<span class="normal"> 325</span>
<span class="normal"> 326</span>
<span class="normal"> 327</span>
<span class="normal"> 328</span>
<span class="normal"> 329</span>
<span class="normal"> 330</span>
<span class="normal"> 331</span>
<span class="normal"> 332</span>
<span class="normal"> 333</span>
<span class="normal"> 334</span>
<span class="normal"> 335</span>
<span class="normal"> 336</span>
<span class="normal"> 337</span>
<span class="normal"> 338</span>
<span class="normal"> 339</span>
<span class="normal"> 340</span>
<span class="normal"> 341</span>
<span class="normal"> 342</span>
<span class="normal"> 343</span>
<span class="normal"> 344</span>
<span class="normal"> 345</span>
<span class="normal"> 346</span>
<span class="normal"> 347</span>
<span class="normal"> 348</span>
<span class="normal"> 349</span>
<span class="normal"> 350</span>
<span class="normal"> 351</span>
<span class="normal"> 352</span>
<span class="normal"> 353</span>
<span class="normal"> 354</span>
<span class="normal"> 355</span>
<span class="normal"> 356</span>
<span class="normal"> 357</span>
<span class="normal"> 358</span>
<span class="normal"> 359</span>
<span class="normal"> 360</span>
<span class="normal"> 361</span>
<span class="normal"> 362</span>
<span class="normal"> 363</span>
<span class="normal"> 364</span>
<span class="normal"> 365</span>
<span class="normal"> 366</span>
<span class="normal"> 367</span>
<span class="normal"> 368</span>
<span class="normal"> 369</span>
<span class="normal"> 370</span>
<span class="normal"> 371</span>
<span class="normal"> 372</span>
<span class="normal"> 373</span>
<span class="normal"> 374</span>
<span class="normal"> 375</span>
<span class="normal"> 376</span>
<span class="normal"> 377</span>
<span class="normal"> 378</span>
<span class="normal"> 379</span>
<span class="normal"> 380</span>
<span class="normal"> 381</span>
<span class="normal"> 382</span>
<span class="normal"> 383</span>
<span class="normal"> 384</span>
<span class="normal"> 385</span>
<span class="normal"> 386</span>
<span class="normal"> 387</span>
<span class="normal"> 388</span>
<span class="normal"> 389</span>
<span class="normal"> 390</span>
<span class="normal"> 391</span>
<span class="normal"> 392</span>
<span class="normal"> 393</span>
<span class="normal"> 394</span>
<span class="normal"> 395</span>
<span class="normal"> 396</span>
<span class="normal"> 397</span>
<span class="normal"> 398</span>
<span class="normal"> 399</span>
<span class="normal"> 400</span>
<span class="normal"> 401</span>
<span class="normal"> 402</span>
<span class="normal"> 403</span>
<span class="normal"> 404</span>
<span class="normal"> 405</span>
<span class="normal"> 406</span>
<span class="normal"> 407</span>
<span class="normal"> 408</span>
<span class="normal"> 409</span>
<span class="normal"> 410</span>
<span class="normal"> 411</span>
<span class="normal"> 412</span>
<span class="normal"> 413</span>
<span class="normal"> 414</span>
<span class="normal"> 415</span>
<span class="normal"> 416</span>
<span class="normal"> 417</span>
<span class="normal"> 418</span>
<span class="normal"> 419</span>
<span class="normal"> 420</span>
<span class="normal"> 421</span>
<span class="normal"> 422</span>
<span class="normal"> 423</span>
<span class="normal"> 424</span>
<span class="normal"> 425</span>
<span class="normal"> 426</span>
<span class="normal"> 427</span>
<span class="normal"> 428</span>
<span class="normal"> 429</span>
<span class="normal"> 430</span>
<span class="normal"> 431</span>
<span class="normal"> 432</span>
<span class="normal"> 433</span>
<span class="normal"> 434</span>
<span class="normal"> 435</span>
<span class="normal"> 436</span>
<span class="normal"> 437</span>
<span class="normal"> 438</span>
<span class="normal"> 439</span>
<span class="normal"> 440</span>
<span class="normal"> 441</span>
<span class="normal"> 442</span>
<span class="normal"> 443</span>
<span class="normal"> 444</span>
<span class="normal"> 445</span>
<span class="normal"> 446</span>
<span class="normal"> 447</span>
<span class="normal"> 448</span>
<span class="normal"> 449</span>
<span class="normal"> 450</span>
<span class="normal"> 451</span>
<span class="normal"> 452</span>
<span class="normal"> 453</span>
<span class="normal"> 454</span>
<span class="normal"> 455</span>
<span class="normal"> 456</span>
<span class="normal"> 457</span>
<span class="normal"> 458</span>
<span class="normal"> 459</span>
<span class="normal"> 460</span>
<span class="normal"> 461</span>
<span class="normal"> 462</span>
<span class="normal"> 463</span>
<span class="normal"> 464</span>
<span class="normal"> 465</span>
<span class="normal"> 466</span>
<span class="normal"> 467</span>
<span class="normal"> 468</span>
<span class="normal"> 469</span>
<span class="normal"> 470</span>
<span class="normal"> 471</span>
<span class="normal"> 472</span>
<span class="normal"> 473</span>
<span class="normal"> 474</span>
<span class="normal"> 475</span>
<span class="normal"> 476</span>
<span class="normal"> 477</span>
<span class="normal"> 478</span>
<span class="normal"> 479</span>
<span class="normal"> 480</span>
<span class="normal"> 481</span>
<span class="normal"> 482</span>
<span class="normal"> 483</span>
<span class="normal"> 484</span>
<span class="normal"> 485</span>
<span class="normal"> 486</span>
<span class="normal"> 487</span>
<span class="normal"> 488</span>
<span class="normal"> 489</span>
<span class="normal"> 490</span>
<span class="normal"> 491</span>
<span class="normal"> 492</span>
<span class="normal"> 493</span>
<span class="normal"> 494</span>
<span class="normal"> 495</span>
<span class="normal"> 496</span>
<span class="normal"> 497</span>
<span class="normal"> 498</span>
<span class="normal"> 499</span>
<span class="normal"> 500</span>
<span class="normal"> 501</span>
<span class="normal"> 502</span>
<span class="normal"> 503</span>
<span class="normal"> 504</span>
<span class="normal"> 505</span>
<span class="normal"> 506</span>
<span class="normal"> 507</span>
<span class="normal"> 508</span>
<span class="normal"> 509</span>
<span class="normal"> 510</span>
<span class="normal"> 511</span>
<span class="normal"> 512</span>
<span class="normal"> 513</span>
<span class="normal"> 514</span>
<span class="normal"> 515</span>
<span class="normal"> 516</span>
<span class="normal"> 517</span>
<span class="normal"> 518</span>
<span class="normal"> 519</span>
<span class="normal"> 520</span>
<span class="normal"> 521</span>
<span class="normal"> 522</span>
<span class="normal"> 523</span>
<span class="normal"> 524</span>
<span class="normal"> 525</span>
<span class="normal"> 526</span>
<span class="normal"> 527</span>
<span class="normal"> 528</span>
<span class="normal"> 529</span>
<span class="normal"> 530</span>
<span class="normal"> 531</span>
<span class="normal"> 532</span>
<span class="normal"> 533</span>
<span class="normal"> 534</span>
<span class="normal"> 535</span>
<span class="normal"> 536</span>
<span class="normal"> 537</span>
<span class="normal"> 538</span>
<span class="normal"> 539</span>
<span class="normal"> 540</span>
<span class="normal"> 541</span>
<span class="normal"> 542</span>
<span class="normal"> 543</span>
<span class="normal"> 544</span>
<span class="normal"> 545</span>
<span class="normal"> 546</span>
<span class="normal"> 547</span>
<span class="normal"> 548</span>
<span class="normal"> 549</span>
<span class="normal"> 550</span>
<span class="normal"> 551</span>
<span class="normal"> 552</span>
<span class="normal"> 553</span>
<span class="normal"> 554</span>
<span class="normal"> 555</span>
<span class="normal"> 556</span>
<span class="normal"> 557</span>
<span class="normal"> 558</span>
<span class="normal"> 559</span>
<span class="normal"> 560</span>
<span class="normal"> 561</span>
<span class="normal"> 562</span>
<span class="normal"> 563</span>
<span class="normal"> 564</span>
<span class="normal"> 565</span>
<span class="normal"> 566</span>
<span class="normal"> 567</span>
<span class="normal"> 568</span>
<span class="normal"> 569</span>
<span class="normal"> 570</span>
<span class="normal"> 571</span>
<span class="normal"> 572</span>
<span class="normal"> 573</span>
<span class="normal"> 574</span>
<span class="normal"> 575</span>
<span class="normal"> 576</span>
<span class="normal"> 577</span>
<span class="normal"> 578</span>
<span class="normal"> 579</span>
<span class="normal"> 580</span>
<span class="normal"> 581</span>
<span class="normal"> 582</span>
<span class="normal"> 583</span>
<span class="normal"> 584</span>
<span class="normal"> 585</span>
<span class="normal"> 586</span>
<span class="normal"> 587</span>
<span class="normal"> 588</span>
<span class="normal"> 589</span>
<span class="normal"> 590</span>
<span class="normal"> 591</span>
<span class="normal"> 592</span>
<span class="normal"> 593</span>
<span class="normal"> 594</span>
<span class="normal"> 595</span>
<span class="normal"> 596</span>
<span class="normal"> 597</span>
<span class="normal"> 598</span>
<span class="normal"> 599</span>
<span class="normal"> 600</span>
<span class="normal"> 601</span>
<span class="normal"> 602</span>
<span class="normal"> 603</span>
<span class="normal"> 604</span>
<span class="normal"> 605</span>
<span class="normal"> 606</span>
<span class="normal"> 607</span>
<span class="normal"> 608</span>
<span class="normal"> 609</span>
<span class="normal"> 610</span>
<span class="normal"> 611</span>
<span class="normal"> 612</span>
<span class="normal"> 613</span>
<span class="normal"> 614</span>
<span class="normal"> 615</span>
<span class="normal"> 616</span>
<span class="normal"> 617</span>
<span class="normal"> 618</span>
<span class="normal"> 619</span>
<span class="normal"> 620</span>
<span class="normal"> 621</span>
<span class="normal"> 622</span>
<span class="normal"> 623</span>
<span class="normal"> 624</span>
<span class="normal"> 625</span>
<span class="normal"> 626</span>
<span class="normal"> 627</span>
<span class="normal"> 628</span>
<span class="normal"> 629</span>
<span class="normal"> 630</span>
<span class="normal"> 631</span>
<span class="normal"> 632</span>
<span class="normal"> 633</span>
<span class="normal"> 634</span>
<span class="normal"> 635</span>
<span class="normal"> 636</span>
<span class="normal"> 637</span>
<span class="normal"> 638</span>
<span class="normal"> 639</span>
<span class="normal"> 640</span>
<span class="normal"> 641</span>
<span class="normal"> 642</span>
<span class="normal"> 643</span>
<span class="normal"> 644</span>
<span class="normal"> 645</span>
<span class="normal"> 646</span>
<span class="normal"> 647</span>
<span class="normal"> 648</span>
<span class="normal"> 649</span>
<span class="normal"> 650</span>
<span class="normal"> 651</span>
<span class="normal"> 652</span>
<span class="normal"> 653</span>
<span class="normal"> 654</span>
<span class="normal"> 655</span>
<span class="normal"> 656</span>
<span class="normal"> 657</span>
<span class="normal"> 658</span>
<span class="normal"> 659</span>
<span class="normal"> 660</span>
<span class="normal"> 661</span>
<span class="normal"> 662</span>
<span class="normal"> 663</span>
<span class="normal"> 664</span>
<span class="normal"> 665</span>
<span class="normal"> 666</span>
<span class="normal"> 667</span>
<span class="normal"> 668</span>
<span class="normal"> 669</span>
<span class="normal"> 670</span>
<span class="normal"> 671</span>
<span class="normal"> 672</span>
<span class="normal"> 673</span>
<span class="normal"> 674</span>
<span class="normal"> 675</span>
<span class="normal"> 676</span>
<span class="normal"> 677</span>
<span class="normal"> 678</span>
<span class="normal"> 679</span>
<span class="normal"> 680</span>
<span class="normal"> 681</span>
<span class="normal"> 682</span>
<span class="normal"> 683</span>
<span class="normal"> 684</span>
<span class="normal"> 685</span>
<span class="normal"> 686</span>
<span class="normal"> 687</span>
<span class="normal"> 688</span>
<span class="normal"> 689</span>
<span class="normal"> 690</span>
<span class="normal"> 691</span>
<span class="normal"> 692</span>
<span class="normal"> 693</span>
<span class="normal"> 694</span>
<span class="normal"> 695</span>
<span class="normal"> 696</span>
<span class="normal"> 697</span>
<span class="normal"> 698</span>
<span class="normal"> 699</span>
<span class="normal"> 700</span>
<span class="normal"> 701</span>
<span class="normal"> 702</span>
<span class="normal"> 703</span>
<span class="normal"> 704</span>
<span class="normal"> 705</span>
<span class="normal"> 706</span>
<span class="normal"> 707</span>
<span class="normal"> 708</span>
<span class="normal"> 709</span>
<span class="normal"> 710</span>
<span class="normal"> 711</span>
<span class="normal"> 712</span>
<span class="normal"> 713</span>
<span class="normal"> 714</span>
<span class="normal"> 715</span>
<span class="normal"> 716</span>
<span class="normal"> 717</span>
<span class="normal"> 718</span>
<span class="normal"> 719</span>
<span class="normal"> 720</span>
<span class="normal"> 721</span>
<span class="normal"> 722</span>
<span class="normal"> 723</span>
<span class="normal"> 724</span>
<span class="normal"> 725</span>
<span class="normal"> 726</span>
<span class="normal"> 727</span>
<span class="normal"> 728</span>
<span class="normal"> 729</span>
<span class="normal"> 730</span>
<span class="normal"> 731</span>
<span class="normal"> 732</span>
<span class="normal"> 733</span>
<span class="normal"> 734</span>
<span class="normal"> 735</span>
<span class="normal"> 736</span>
<span class="normal"> 737</span>
<span class="normal"> 738</span>
<span class="normal"> 739</span>
<span class="normal"> 740</span>
<span class="normal"> 741</span>
<span class="normal"> 742</span>
<span class="normal"> 743</span>
<span class="normal"> 744</span>
<span class="normal"> 745</span>
<span class="normal"> 746</span>
<span class="normal"> 747</span>
<span class="normal"> 748</span>
<span class="normal"> 749</span>
<span class="normal"> 750</span>
<span class="normal"> 751</span>
<span class="normal"> 752</span>
<span class="normal"> 753</span>
<span class="normal"> 754</span>
<span class="normal"> 755</span>
<span class="normal"> 756</span>
<span class="normal"> 757</span>
<span class="normal"> 758</span>
<span class="normal"> 759</span>
<span class="normal"> 760</span>
<span class="normal"> 761</span>
<span class="normal"> 762</span>
<span class="normal"> 763</span>
<span class="normal"> 764</span>
<span class="normal"> 765</span>
<span class="normal"> 766</span>
<span class="normal"> 767</span>
<span class="normal"> 768</span>
<span class="normal"> 769</span>
<span class="normal"> 770</span>
<span class="normal"> 771</span>
<span class="normal"> 772</span>
<span class="normal"> 773</span>
<span class="normal"> 774</span>
<span class="normal"> 775</span>
<span class="normal"> 776</span>
<span class="normal"> 777</span>
<span class="normal"> 778</span>
<span class="normal"> 779</span>
<span class="normal"> 780</span>
<span class="normal"> 781</span>
<span class="normal"> 782</span>
<span class="normal"> 783</span>
<span class="normal"> 784</span>
<span class="normal"> 785</span>
<span class="normal"> 786</span>
<span class="normal"> 787</span>
<span class="normal"> 788</span>
<span class="normal"> 789</span>
<span class="normal"> 790</span>
<span class="normal"> 791</span>
<span class="normal"> 792</span>
<span class="normal"> 793</span>
<span class="normal"> 794</span>
<span class="normal"> 795</span>
<span class="normal"> 796</span>
<span class="normal"> 797</span>
<span class="normal"> 798</span>
<span class="normal"> 799</span>
<span class="normal"> 800</span>
<span class="normal"> 801</span>
<span class="normal"> 802</span>
<span class="normal"> 803</span>
<span class="normal"> 804</span>
<span class="normal"> 805</span>
<span class="normal"> 806</span>
<span class="normal"> 807</span>
<span class="normal"> 808</span>
<span class="normal"> 809</span>
<span class="normal"> 810</span>
<span class="normal"> 811</span>
<span class="normal"> 812</span>
<span class="normal"> 813</span>
<span class="normal"> 814</span>
<span class="normal"> 815</span>
<span class="normal"> 816</span>
<span class="normal"> 817</span>
<span class="normal"> 818</span>
<span class="normal"> 819</span>
<span class="normal"> 820</span>
<span class="normal"> 821</span>
<span class="normal"> 822</span>
<span class="normal"> 823</span>
<span class="normal"> 824</span>
<span class="normal"> 825</span>
<span class="normal"> 826</span>
<span class="normal"> 827</span>
<span class="normal"> 828</span>
<span class="normal"> 829</span>
<span class="normal"> 830</span>
<span class="normal"> 831</span>
<span class="normal"> 832</span>
<span class="normal"> 833</span>
<span class="normal"> 834</span>
<span class="normal"> 835</span>
<span class="normal"> 836</span>
<span class="normal"> 837</span>
<span class="normal"> 838</span>
<span class="normal"> 839</span>
<span class="normal"> 840</span>
<span class="normal"> 841</span>
<span class="normal"> 842</span>
<span class="normal"> 843</span>
<span class="normal"> 844</span>
<span class="normal"> 845</span>
<span class="normal"> 846</span>
<span class="normal"> 847</span>
<span class="normal"> 848</span>
<span class="normal"> 849</span>
<span class="normal"> 850</span>
<span class="normal"> 851</span>
<span class="normal"> 852</span>
<span class="normal"> 853</span>
<span class="normal"> 854</span>
<span class="normal"> 855</span>
<span class="normal"> 856</span>
<span class="normal"> 857</span>
<span class="normal"> 858</span>
<span class="normal"> 859</span>
<span class="normal"> 860</span>
<span class="normal"> 861</span>
<span class="normal"> 862</span>
<span class="normal"> 863</span>
<span class="normal"> 864</span>
<span class="normal"> 865</span>
<span class="normal"> 866</span>
<span class="normal"> 867</span>
<span class="normal"> 868</span>
<span class="normal"> 869</span>
<span class="normal"> 870</span>
<span class="normal"> 871</span>
<span class="normal"> 872</span>
<span class="normal"> 873</span>
<span class="normal"> 874</span>
<span class="normal"> 875</span>
<span class="normal"> 876</span>
<span class="normal"> 877</span>
<span class="normal"> 878</span>
<span class="normal"> 879</span>
<span class="normal"> 880</span>
<span class="normal"> 881</span>
<span class="normal"> 882</span>
<span class="normal"> 883</span>
<span class="normal"> 884</span>
<span class="normal"> 885</span>
<span class="normal"> 886</span>
<span class="normal"> 887</span>
<span class="normal"> 888</span>
<span class="normal"> 889</span>
<span class="normal"> 890</span>
<span class="normal"> 891</span>
<span class="normal"> 892</span>
<span class="normal"> 893</span>
<span class="normal"> 894</span>
<span class="normal"> 895</span>
<span class="normal"> 896</span>
<span class="normal"> 897</span>
<span class="normal"> 898</span>
<span class="normal"> 899</span>
<span class="normal"> 900</span>
<span class="normal"> 901</span>
<span class="normal"> 902</span>
<span class="normal"> 903</span>
<span class="normal"> 904</span>
<span class="normal"> 905</span>
<span class="normal"> 906</span>
<span class="normal"> 907</span>
<span class="normal"> 908</span>
<span class="normal"> 909</span>
<span class="normal"> 910</span>
<span class="normal"> 911</span>
<span class="normal"> 912</span>
<span class="normal"> 913</span>
<span class="normal"> 914</span>
<span class="normal"> 915</span>
<span class="normal"> 916</span>
<span class="normal"> 917</span>
<span class="normal"> 918</span>
<span class="normal"> 919</span>
<span class="normal"> 920</span>
<span class="normal"> 921</span>
<span class="normal"> 922</span>
<span class="normal"> 923</span>
<span class="normal"> 924</span>
<span class="normal"> 925</span>
<span class="normal"> 926</span>
<span class="normal"> 927</span>
<span class="normal"> 928</span>
<span class="normal"> 929</span>
<span class="normal"> 930</span>
<span class="normal"> 931</span>
<span class="normal"> 932</span>
<span class="normal"> 933</span>
<span class="normal"> 934</span>
<span class="normal"> 935</span>
<span class="normal"> 936</span>
<span class="normal"> 937</span>
<span class="normal"> 938</span>
<span class="normal"> 939</span>
<span class="normal"> 940</span>
<span class="normal"> 941</span>
<span class="normal"> 942</span>
<span class="normal"> 943</span>
<span class="normal"> 944</span>
<span class="normal"> 945</span>
<span class="normal"> 946</span>
<span class="normal"> 947</span>
<span class="normal"> 948</span>
<span class="normal"> 949</span>
<span class="normal"> 950</span>
<span class="normal"> 951</span>
<span class="normal"> 952</span>
<span class="normal"> 953</span>
<span class="normal"> 954</span>
<span class="normal"> 955</span>
<span class="normal"> 956</span>
<span class="normal"> 957</span>
<span class="normal"> 958</span>
<span class="normal"> 959</span>
<span class="normal"> 960</span>
<span class="normal"> 961</span>
<span class="normal"> 962</span>
<span class="normal"> 963</span>
<span class="normal"> 964</span>
<span class="normal"> 965</span>
<span class="normal"> 966</span>
<span class="normal"> 967</span>
<span class="normal"> 968</span>
<span class="normal"> 969</span>
<span class="normal"> 970</span>
<span class="normal"> 971</span>
<span class="normal"> 972</span>
<span class="normal"> 973</span>
<span class="normal"> 974</span>
<span class="normal"> 975</span>
<span class="normal"> 976</span>
<span class="normal"> 977</span>
<span class="normal"> 978</span>
<span class="normal"> 979</span>
<span class="normal"> 980</span>
<span class="normal"> 981</span>
<span class="normal"> 982</span>
<span class="normal"> 983</span>
<span class="normal"> 984</span>
<span class="normal"> 985</span>
<span class="normal"> 986</span>
<span class="normal"> 987</span>
<span class="normal"> 988</span>
<span class="normal"> 989</span>
<span class="normal"> 990</span>
<span class="normal"> 991</span>
<span class="normal"> 992</span>
<span class="normal"> 993</span>
<span class="normal"> 994</span>
<span class="normal"> 995</span>
<span class="normal"> 996</span>
<span class="normal"> 997</span>
<span class="normal"> 998</span>
<span class="normal"> 999</span>
<span class="normal">1000</span>
<span class="normal">1001</span>
<span class="normal">1002</span>
<span class="normal">1003</span>
<span class="normal">1004</span>
<span class="normal">1005</span>
<span class="normal">1006</span>
<span class="normal">1007</span>
<span class="normal">1008</span>
<span class="normal">1009</span>
<span class="normal">1010</span>
<span class="normal">1011</span>
<span class="normal">1012</span>
<span class="normal">1013</span>
<span class="normal">1014</span>
<span class="normal">1015</span>
<span class="normal">1016</span>
<span class="normal">1017</span>
<span class="normal">1018</span>
<span class="normal">1019</span>
<span class="normal">1020</span>
<span class="normal">1021</span>
<span class="normal">1022</span>
<span class="normal">1023</span>
<span class="normal">1024</span>
<span class="normal">1025</span>
<span class="normal">1026</span>
<span class="normal">1027</span>
<span class="normal">1028</span>
<span class="normal">1029</span>
<span class="normal">1030</span>
<span class="normal">1031</span>
<span class="normal">1032</span>
<span class="normal">1033</span>
<span class="normal">1034</span>
<span class="normal">1035</span>
<span class="normal">1036</span>
<span class="normal">1037</span>
<span class="normal">1038</span>
<span class="normal">1039</span>
<span class="normal">1040</span>
<span class="normal">1041</span>
<span class="normal">1042</span>
<span class="normal">1043</span>
<span class="normal">1044</span>
<span class="normal">1045</span>
<span class="normal">1046</span>
<span class="normal">1047</span>
<span class="normal">1048</span>
<span class="normal">1049</span>
<span class="normal">1050</span>
<span class="normal">1051</span>
<span class="normal">1052</span>
<span class="normal">1053</span>
<span class="normal">1054</span>
<span class="normal">1055</span>
<span class="normal">1056</span>
<span class="normal">1057</span>
<span class="normal">1058</span>
<span class="normal">1059</span>
<span class="normal">1060</span>
<span class="normal">1061</span>
<span class="normal">1062</span>
<span class="normal">1063</span>
<span class="normal">1064</span>
<span class="normal">1065</span>
<span class="normal">1066</span>
<span class="normal">1067</span>
<span class="normal">1068</span>
<span class="normal">1069</span>
<span class="normal">1070</span>
<span class="normal">1071</span>
<span class="normal">1072</span>
<span class="normal">1073</span>
<span class="normal">1074</span>
<span class="normal">1075</span>
<span class="normal">1076</span>
<span class="normal">1077</span>
<span class="normal">1078</span>
<span class="normal">1079</span>
<span class="normal">1080</span>
<span class="normal">1081</span>
<span class="normal">1082</span>
<span class="normal">1083</span>
<span class="normal">1084</span>
<span class="normal">1085</span>
<span class="normal">1086</span>
<span class="normal">1087</span>
<span class="normal">1088</span>
<span class="normal">1089</span>
<span class="normal">1090</span>
<span class="normal">1091</span>
<span class="normal">1092</span>
<span class="normal">1093</span>
<span class="normal">1094</span>
<span class="normal">1095</span>
<span class="normal">1096</span>
<span class="normal">1097</span>
<span class="normal">1098</span>
<span class="normal">1099</span>
<span class="normal">1100</span>
<span class="normal">1101</span>
<span class="normal">1102</span>
<span class="normal">1103</span>
<span class="normal">1104</span>
<span class="normal">1105</span>
<span class="normal">1106</span>
<span class="normal">1107</span>
<span class="normal">1108</span>
<span class="normal">1109</span>
<span class="normal">1110</span>
<span class="normal">1111</span>
<span class="normal">1112</span>
<span class="normal">1113</span>
<span class="normal">1114</span>
<span class="normal">1115</span>
<span class="normal">1116</span>
<span class="normal">1117</span>
<span class="normal">1118</span>
<span class="normal">1119</span>
<span class="normal">1120</span>
<span class="normal">1121</span>
<span class="normal">1122</span>
<span class="normal">1123</span>
<span class="normal">1124</span>
<span class="normal">1125</span>
<span class="normal">1126</span>
<span class="normal">1127</span>
<span class="normal">1128</span>
<span class="normal">1129</span>
<span class="normal">1130</span>
<span class="normal">1131</span>
<span class="normal">1132</span>
<span class="normal">1133</span>
<span class="normal">1134</span>
<span class="normal">1135</span>
<span class="normal">1136</span>
<span class="normal">1137</span>
<span class="normal">1138</span>
<span class="normal">1139</span>
<span class="normal">1140</span>
<span class="normal">1141</span>
<span class="normal">1142</span>
<span class="normal">1143</span>
<span class="normal">1144</span>
<span class="normal">1145</span>
<span class="normal">1146</span>
<span class="normal">1147</span>
<span class="normal">1148</span>
<span class="normal">1149</span>
<span class="normal">1150</span>
<span class="normal">1151</span>
<span class="normal">1152</span>
<span class="normal">1153</span>
<span class="normal">1154</span>
<span class="normal">1155</span>
<span class="normal">1156</span>
<span class="normal">1157</span>
<span class="normal">1158</span>
<span class="normal">1159</span>
<span class="normal">1160</span>
<span class="normal">1161</span>
<span class="normal">1162</span>
<span class="normal">1163</span>
<span class="normal">1164</span>
<span class="normal">1165</span>
<span class="normal">1166</span>
<span class="normal">1167</span>
<span class="normal">1168</span>
<span class="normal">1169</span>
<span class="normal">1170</span>
<span class="normal">1171</span>
<span class="normal">1172</span>
<span class="normal">1173</span>
<span class="normal">1174</span>
<span class="normal">1175</span>
<span class="normal">1176</span>
<span class="normal">1177</span>
<span class="normal">1178</span>
<span class="normal">1179</span>
<span class="normal">1180</span>
<span class="normal">1181</span>
<span class="normal">1182</span>
<span class="normal">1183</span>
<span class="normal">1184</span>
<span class="normal">1185</span>
<span class="normal">1186</span>
<span class="normal">1187</span>
<span class="normal">1188</span>
<span class="normal">1189</span>
<span class="normal">1190</span>
<span class="normal">1191</span>
<span class="normal">1192</span>
<span class="normal">1193</span>
<span class="normal">1194</span>
<span class="normal">1195</span>
<span class="normal">1196</span>
<span class="normal">1197</span>
<span class="normal">1198</span>
<span class="normal">1199</span>
<span class="normal">1200</span>
<span class="normal">1201</span>
<span class="normal">1202</span>
<span class="normal">1203</span>
<span class="normal">1204</span>
<span class="normal">1205</span>
<span class="normal">1206</span>
<span class="normal">1207</span>
<span class="normal">1208</span>
<span class="normal">1209</span>
<span class="normal">1210</span>
<span class="normal">1211</span>
<span class="normal">1212</span>
<span class="normal">1213</span>
<span class="normal">1214</span>
<span class="normal">1215</span>
<span class="normal">1216</span>
<span class="normal">1217</span>
<span class="normal">1218</span>
<span class="normal">1219</span>
<span class="normal">1220</span>
<span class="normal">1221</span>
<span class="normal">1222</span>
<span class="normal">1223</span>
<span class="normal">1224</span>
<span class="normal">1225</span>
<span class="normal">1226</span>
<span class="normal">1227</span>
<span class="normal">1228</span>
<span class="normal">1229</span>
<span class="normal">1230</span>
<span class="normal">1231</span>
<span class="normal">1232</span>
<span class="normal">1233</span>
<span class="normal">1234</span>
<span class="normal">1235</span>
<span class="normal">1236</span>
<span class="normal">1237</span>
<span class="normal">1238</span>
<span class="normal">1239</span>
<span class="normal">1240</span>
<span class="normal">1241</span>
<span class="normal">1242</span>
<span class="normal">1243</span>
<span class="normal">1244</span>
<span class="normal">1245</span>
<span class="normal">1246</span>
<span class="normal">1247</span>
<span class="normal">1248</span>
<span class="normal">1249</span>
<span class="normal">1250</span>
<span class="normal">1251</span>
<span class="normal">1252</span>
<span class="normal">1253</span>
<span class="normal">1254</span>
<span class="normal">1255</span>
<span class="normal">1256</span>
<span class="normal">1257</span>
<span class="normal">1258</span>
<span class="normal">1259</span>
<span class="normal">1260</span>
<span class="normal">1261</span>
<span class="normal">1262</span>
<span class="normal">1263</span>
<span class="normal">1264</span>
<span class="normal">1265</span>
<span class="normal">1266</span>
<span class="normal">1267</span>
<span class="normal">1268</span>
<span class="normal">1269</span>
<span class="normal">1270</span>
<span class="normal">1271</span>
<span class="normal">1272</span>
<span class="normal">1273</span>
<span class="normal">1274</span>
<span class="normal">1275</span>
<span class="normal">1276</span>
<span class="normal">1277</span>
<span class="normal">1278</span>
<span class="normal">1279</span>
<span class="normal">1280</span>
<span class="normal">1281</span>
<span class="normal">1282</span>
<span class="normal">1283</span>
<span class="normal">1284</span>
<span class="normal">1285</span>
<span class="normal">1286</span>
<span class="normal">1287</span>
<span class="normal">1288</span>
<span class="normal">1289</span>
<span class="normal">1290</span>
<span class="normal">1291</span>
<span class="normal">1292</span>
<span class="normal">1293</span>
<span class="normal">1294</span>
<span class="normal">1295</span>
<span class="normal">1296</span>
<span class="normal">1297</span>
<span class="normal">1298</span>
<span class="normal">1299</span>
<span class="normal">1300</span>
<span class="normal">1301</span>
<span class="normal">1302</span>
<span class="normal">1303</span>
<span class="normal">1304</span>
<span class="normal">1305</span>
<span class="normal">1306</span>
<span class="normal">1307</span>
<span class="normal">1308</span>
<span class="normal">1309</span>
<span class="normal">1310</span>
<span class="normal">1311</span>
<span class="normal">1312</span>
<span class="normal">1313</span>
<span class="normal">1314</span>
<span class="normal">1315</span>
<span class="normal">1316</span>
<span class="normal">1317</span>
<span class="normal">1318</span>
<span class="normal">1319</span>
<span class="normal">1320</span>
<span class="normal">1321</span>
<span class="normal">1322</span>
<span class="normal">1323</span>
<span class="normal">1324</span>
<span class="normal">1325</span>
<span class="normal">1326</span>
<span class="normal">1327</span>
<span class="normal">1328</span>
<span class="normal">1329</span>
<span class="normal">1330</span>
<span class="normal">1331</span>
<span class="normal">1332</span>
<span class="normal">1333</span>
<span class="normal">1334</span>
<span class="normal">1335</span>
<span class="normal">1336</span>
<span class="normal">1337</span>
<span class="normal">1338</span>
<span class="normal">1339</span>
<span class="normal">1340</span>
<span class="normal">1341</span>
<span class="normal">1342</span>
<span class="normal">1343</span>
<span class="normal">1344</span>
<span class="normal">1345</span>
<span class="normal">1346</span>
<span class="normal">1347</span>
<span class="normal">1348</span>
<span class="normal">1349</span>
<span class="normal">1350</span>
<span class="normal">1351</span>
<span class="normal">1352</span>
<span class="normal">1353</span>
<span class="normal">1354</span>
<span class="normal">1355</span>
<span class="normal">1356</span>
<span class="normal">1357</span>
<span class="normal">1358</span>
<span class="normal">1359</span>
<span class="normal">1360</span>
<span class="normal">1361</span>
<span class="normal">1362</span>
<span class="normal">1363</span>
<span class="normal">1364</span>
<span class="normal">1365</span>
<span class="normal">1366</span>
<span class="normal">1367</span>
<span class="normal">1368</span>
<span class="normal">1369</span>
<span class="normal">1370</span>
<span class="normal">1371</span>
<span class="normal">1372</span>
<span class="normal">1373</span>
<span class="normal">1374</span>
<span class="normal">1375</span>
<span class="normal">1376</span>
<span class="normal">1377</span>
<span class="normal">1378</span>
<span class="normal">1379</span>
<span class="normal">1380</span>
<span class="normal">1381</span>
<span class="normal">1382</span>
<span class="normal">1383</span>
<span class="normal">1384</span>
<span class="normal">1385</span>
<span class="normal">1386</span>
<span class="normal">1387</span>
<span class="normal">1388</span>
<span class="normal">1389</span>
<span class="normal">1390</span>
<span class="normal">1391</span>
<span class="normal">1392</span>
<span class="normal">1393</span>
<span class="normal">1394</span>
<span class="normal">1395</span>
<span class="normal">1396</span>
<span class="normal">1397</span>
<span class="normal">1398</span>
<span class="normal">1399</span>
<span class="normal">1400</span>
<span class="normal">1401</span>
<span class="normal">1402</span>
<span class="normal">1403</span>
<span class="normal">1404</span>
<span class="normal">1405</span>
<span class="normal">1406</span>
<span class="normal">1407</span>
<span class="normal">1408</span>
<span class="normal">1409</span>
<span class="normal">1410</span>
<span class="normal">1411</span>
<span class="normal">1412</span>
<span class="normal">1413</span>
<span class="normal">1414</span>
<span class="normal">1415</span>
<span class="normal">1416</span>
<span class="normal">1417</span>
<span class="normal">1418</span>
<span class="normal">1419</span>
<span class="normal">1420</span>
<span class="normal">1421</span>
<span class="normal">1422</span>
<span class="normal">1423</span>
<span class="normal">1424</span>
<span class="normal">1425</span>
<span class="normal">1426</span>
<span class="normal">1427</span>
<span class="normal">1428</span>
<span class="normal">1429</span>
<span class="normal">1430</span>
<span class="normal">1431</span>
<span class="normal">1432</span>
<span class="normal">1433</span>
<span class="normal">1434</span>
<span class="normal">1435</span>
<span class="normal">1436</span>
<span class="normal">1437</span>
<span class="normal">1438</span>
<span class="normal">1439</span>
<span class="normal">1440</span>
<span class="normal">1441</span>
<span class="normal">1442</span>
<span class="normal">1443</span>
<span class="normal">1444</span>
<span class="normal">1445</span>
<span class="normal">1446</span>
<span class="normal">1447</span>
<span class="normal">1448</span>
<span class="normal">1449</span>
<span class="normal">1450</span>
<span class="normal">1451</span>
<span class="normal">1452</span>
<span class="normal">1453</span>
<span class="normal">1454</span>
<span class="normal">1455</span>
<span class="normal">1456</span>
<span class="normal">1457</span>
<span class="normal">1458</span>
<span class="normal">1459</span>
<span class="normal">1460</span>
<span class="normal">1461</span>
<span class="normal">1462</span>
<span class="normal">1463</span>
<span class="normal">1464</span>
<span class="normal">1465</span>
<span class="normal">1466</span>
<span class="normal">1467</span>
<span class="normal">1468</span>
<span class="normal">1469</span>
<span class="normal">1470</span>
<span class="normal">1471</span>
<span class="normal">1472</span>
<span class="normal">1473</span>
<span class="normal">1474</span>
<span class="normal">1475</span>
<span class="normal">1476</span>
<span class="normal">1477</span>
<span class="normal">1478</span>
<span class="normal">1479</span>
<span class="normal">1480</span>
<span class="normal">1481</span>
<span class="normal">1482</span>
<span class="normal">1483</span>
<span class="normal">1484</span>
<span class="normal">1485</span>
<span class="normal">1486</span>
<span class="normal">1487</span>
<span class="normal">1488</span>
<span class="normal">1489</span>
<span class="normal">1490</span>
<span class="normal">1491</span>
<span class="normal">1492</span>
<span class="normal">1493</span>
<span class="normal">1494</span>
<span class="normal">1495</span>
<span class="normal">1496</span>
<span class="normal">1497</span>
<span class="normal">1498</span>
<span class="normal">1499</span>
<span class="normal">1500</span>
<span class="normal">1501</span>
<span class="normal">1502</span>
<span class="normal">1503</span>
<span class="normal">1504</span>
<span class="normal">1505</span>
<span class="normal">1506</span>
<span class="normal">1507</span>
<span class="normal">1508</span>
<span class="normal">1509</span>
<span class="normal">1510</span>
<span class="normal">1511</span>
<span class="normal">1512</span>
<span class="normal">1513</span>
<span class="normal">1514</span>
<span class="normal">1515</span>
<span class="normal">1516</span>
<span class="normal">1517</span>
<span class="normal">1518</span>
<span class="normal">1519</span>
<span class="normal">1520</span>
<span class="normal">1521</span>
<span class="normal">1522</span>
<span class="normal">1523</span>
<span class="normal">1524</span>
<span class="normal">1525</span>
<span class="normal">1526</span>
<span class="normal">1527</span>
<span class="normal">1528</span>
<span class="normal">1529</span>
<span class="normal">1530</span>
<span class="normal">1531</span>
<span class="normal">1532</span>
<span class="normal">1533</span>
<span class="normal">1534</span>
<span class="normal">1535</span>
<span class="normal">1536</span>
<span class="normal">1537</span>
<span class="normal">1538</span>
<span class="normal">1539</span>
<span class="normal">1540</span>
<span class="normal">1541</span>
<span class="normal">1542</span>
<span class="normal">1543</span>
<span class="normal">1544</span>
<span class="normal">1545</span>
<span class="normal">1546</span>
<span class="normal">1547</span>
<span class="normal">1548</span>
<span class="normal">1549</span>
<span class="normal">1550</span>
<span class="normal">1551</span>
<span class="normal">1552</span>
<span class="normal">1553</span>
<span class="normal">1554</span>
<span class="normal">1555</span>
<span class="normal">1556</span>
<span class="normal">1557</span>
<span class="normal">1558</span>
<span class="normal">1559</span>
<span class="normal">1560</span>
<span class="normal">1561</span>
<span class="normal">1562</span>
<span class="normal">1563</span>
<span class="normal">1564</span>
<span class="normal">1565</span>
<span class="normal">1566</span>
<span class="normal">1567</span>
<span class="normal">1568</span>
<span class="normal">1569</span>
<span class="normal">1570</span>
<span class="normal">1571</span>
<span class="normal">1572</span>
<span class="normal">1573</span>
<span class="normal">1574</span>
<span class="normal">1575</span>
<span class="normal">1576</span>
<span class="normal">1577</span>
<span class="normal">1578</span>
<span class="normal">1579</span>
<span class="normal">1580</span>
<span class="normal">1581</span>
<span class="normal">1582</span>
<span class="normal">1583</span>
<span class="normal">1584</span>
<span class="normal">1585</span>
<span class="normal">1586</span>
<span class="normal">1587</span>
<span class="normal">1588</span>
<span class="normal">1589</span>
<span class="normal">1590</span>
<span class="normal">1591</span>
<span class="normal">1592</span>
<span class="normal">1593</span>
<span class="normal">1594</span>
<span class="normal">1595</span>
<span class="normal">1596</span>
<span class="normal">1597</span>
<span class="normal">1598</span>
<span class="normal">1599</span>
<span class="normal">1600</span>
<span class="normal">1601</span>
<span class="normal">1602</span>
<span class="normal">1603</span>
<span class="normal">1604</span>
<span class="normal">1605</span>
<span class="normal">1606</span>
<span class="normal">1607</span>
<span class="normal">1608</span>
<span class="normal">1609</span>
<span class="normal">1610</span>
<span class="normal">1611</span>
<span class="normal">1612</span>
<span class="normal">1613</span>
<span class="normal">1614</span>
<span class="normal">1615</span>
<span class="normal">1616</span>
<span class="normal">1617</span>
<span class="normal">1618</span>
<span class="normal">1619</span>
<span class="normal">1620</span>
<span class="normal">1621</span>
<span class="normal">1622</span>
<span class="normal">1623</span>
<span class="normal">1624</span>
<span class="normal">1625</span>
<span class="normal">1626</span>
<span class="normal">1627</span>
<span class="normal">1628</span>
<span class="normal">1629</span>
<span class="normal">1630</span>
<span class="normal">1631</span>
<span class="normal">1632</span>
<span class="normal">1633</span>
<span class="normal">1634</span>
<span class="normal">1635</span>
<span class="normal">1636</span>
<span class="normal">1637</span>
<span class="normal">1638</span>
<span class="normal">1639</span>
<span class="normal">1640</span>
<span class="normal">1641</span>
<span class="normal">1642</span>
<span class="normal">1643</span>
<span class="normal">1644</span>
<span class="normal">1645</span>
<span class="normal">1646</span>
<span class="normal">1647</span>
<span class="normal">1648</span>
<span class="normal">1649</span>
<span class="normal">1650</span>
<span class="normal">1651</span>
<span class="normal">1652</span>
<span class="normal">1653</span>
<span class="normal">1654</span>
<span class="normal">1655</span>
<span class="normal">1656</span>
<span class="normal">1657</span>
<span class="normal">1658</span>
<span class="normal">1659</span>
<span class="normal">1660</span>
<span class="normal">1661</span>
<span class="normal">1662</span>
<span class="normal">1663</span>
<span class="normal">1664</span>
<span class="normal">1665</span>
<span class="normal">1666</span>
<span class="normal">1667</span>
<span class="normal">1668</span>
<span class="normal">1669</span>
<span class="normal">1670</span>
<span class="normal">1671</span>
<span class="normal">1672</span>
<span class="normal">1673</span>
<span class="normal">1674</span>
<span class="normal">1675</span>
<span class="normal">1676</span>
<span class="normal">1677</span>
<span class="normal">1678</span>
<span class="normal">1679</span>
<span class="normal">1680</span>
<span class="normal">1681</span>
<span class="normal">1682</span>
<span class="normal">1683</span>
<span class="normal">1684</span>
<span class="normal">1685</span>
<span class="normal">1686</span>
<span class="normal">1687</span>
<span class="normal">1688</span>
<span class="normal">1689</span>
<span class="normal">1690</span>
<span class="normal">1691</span>
<span class="normal">1692</span>
<span class="normal">1693</span>
<span class="normal">1694</span>
<span class="normal">1695</span>
<span class="normal">1696</span>
<span class="normal">1697</span>
<span class="normal">1698</span>
<span class="normal">1699</span>
<span class="normal">1700</span>
<span class="normal">1701</span>
<span class="normal">1702</span>
<span class="normal">1703</span>
<span class="normal">1704</span>
<span class="normal">1705</span>
<span class="normal">1706</span>
<span class="normal">1707</span>
<span class="normal">1708</span>
<span class="normal">1709</span>
<span class="normal">1710</span>
<span class="normal">1711</span>
<span class="normal">1712</span>
<span class="normal">1713</span>
<span class="normal">1714</span>
<span class="normal">1715</span>
<span class="normal">1716</span>
<span class="normal">1717</span>
<span class="normal">1718</span>
<span class="normal">1719</span>
<span class="normal">1720</span>
<span class="normal">1721</span>
<span class="normal">1722</span>
<span class="normal">1723</span>
<span class="normal">1724</span>
<span class="normal">1725</span>
<span class="normal">1726</span>
<span class="normal">1727</span>
<span class="normal">1728</span>
<span class="normal">1729</span>
<span class="normal">1730</span>
<span class="normal">1731</span>
<span class="normal">1732</span>
<span class="normal">1733</span>
<span class="normal">1734</span>
<span class="normal">1735</span>
<span class="normal">1736</span>
<span class="normal">1737</span>
<span class="normal">1738</span>
<span class="normal">1739</span>
<span class="normal">1740</span>
<span class="normal">1741</span>
<span class="normal">1742</span>
<span class="normal">1743</span>
<span class="normal">1744</span>
<span class="normal">1745</span>
<span class="normal">1746</span>
<span class="normal">1747</span>
<span class="normal">1748</span>
<span class="normal">1749</span>
<span class="normal">1750</span>
<span class="normal">1751</span>
<span class="normal">1752</span>
<span class="normal">1753</span>
<span class="normal">1754</span>
<span class="normal">1755</span>
<span class="normal">1756</span>
<span class="normal">1757</span>
<span class="normal">1758</span>
<span class="normal">1759</span>
<span class="normal">1760</span>
<span class="normal">1761</span>
<span class="normal">1762</span>
<span class="normal">1763</span>
<span class="normal">1764</span>
<span class="normal">1765</span>
<span class="normal">1766</span>
<span class="normal">1767</span>
<span class="normal">1768</span>
<span class="normal">1769</span>
<span class="normal">1770</span>
<span class="normal">1771</span>
<span class="normal">1772</span>
<span class="normal">1773</span>
<span class="normal">1774</span>
<span class="normal">1775</span>
<span class="normal">1776</span>
<span class="normal">1777</span>
<span class="normal">1778</span>
<span class="normal">1779</span>
<span class="normal">1780</span>
<span class="normal">1781</span>
<span class="normal">1782</span>
<span class="normal">1783</span>
<span class="normal">1784</span>
<span class="normal">1785</span>
<span class="normal">1786</span>
<span class="normal">1787</span>
<span class="normal">1788</span>
<span class="normal">1789</span>
<span class="normal">1790</span>
<span class="normal">1791</span>
<span class="normal">1792</span>
<span class="normal">1793</span>
<span class="normal">1794</span>
<span class="normal">1795</span>
<span class="normal">1796</span>
<span class="normal">1797</span>
<span class="normal">1798</span>
<span class="normal">1799</span>
<span class="normal">1800</span>
<span class="normal">1801</span>
<span class="normal">1802</span>
<span class="normal">1803</span>
<span class="normal">1804</span>
<span class="normal">1805</span>
<span class="normal">1806</span>
<span class="normal">1807</span>
<span class="normal">1808</span>
<span class="normal">1809</span>
<span class="normal">1810</span>
<span class="normal">1811</span>
<span class="normal">1812</span>
<span class="normal">1813</span>
<span class="normal">1814</span>
<span class="normal">1815</span>
<span class="normal">1816</span>
<span class="normal">1817</span>
<span class="normal">1818</span>
<span class="normal">1819</span>
<span class="normal">1820</span>
<span class="normal">1821</span>
<span class="normal">1822</span>
<span class="normal">1823</span>
<span class="normal">1824</span>
<span class="normal">1825</span>
<span class="normal">1826</span>
<span class="normal">1827</span>
<span class="normal">1828</span>
<span class="normal">1829</span>
<span class="normal">1830</span>
<span class="normal">1831</span>
<span class="normal">1832</span>
<span class="normal">1833</span>
<span class="normal">1834</span>
<span class="normal">1835</span>
<span class="normal">1836</span>
<span class="normal">1837</span>
<span class="normal">1838</span>
<span class="normal">1839</span>
<span class="normal">1840</span>
<span class="normal">1841</span>
<span class="normal">1842</span>
<span class="normal">1843</span>
<span class="normal">1844</span>
<span class="normal">1845</span>
<span class="normal">1846</span>
<span class="normal">1847</span>
<span class="normal">1848</span>
<span class="normal">1849</span>
<span class="normal">1850</span>
<span class="normal">1851</span>
<span class="normal">1852</span>
<span class="normal">1853</span>
<span class="normal">1854</span>
<span class="normal">1855</span>
<span class="normal">1856</span>
<span class="normal">1857</span>
<span class="normal">1858</span>
<span class="normal">1859</span>
<span class="normal">1860</span>
<span class="normal">1861</span>
<span class="normal">1862</span>
<span class="normal">1863</span>
<span class="normal">1864</span>
<span class="normal">1865</span>
<span class="normal">1866</span>
<span class="normal">1867</span>
<span class="normal">1868</span>
<span class="normal">1869</span>
<span class="normal">1870</span>
<span class="normal">1871</span>
<span class="normal">1872</span>
<span class="normal">1873</span>
<span class="normal">1874</span>
<span class="normal">1875</span>
<span class="normal">1876</span>
<span class="normal">1877</span>
<span class="normal">1878</span>
<span class="normal">1879</span>
<span class="normal">1880</span>
<span class="normal">1881</span>
<span class="normal">1882</span>
<span class="normal">1883</span>
<span class="normal">1884</span>
<span class="normal">1885</span>
<span class="normal">1886</span>
<span class="normal">1887</span>
<span class="normal">1888</span>
<span class="normal">1889</span>
<span class="normal">1890</span>
<span class="normal">1891</span>
<span class="normal">1892</span>
<span class="normal">1893</span>
<span class="normal">1894</span>
<span class="normal">1895</span>
<span class="normal">1896</span>
<span class="normal">1897</span>
<span class="normal">1898</span>
<span class="normal">1899</span>
<span class="normal">1900</span>
<span class="normal">1901</span>
<span class="normal">1902</span>
<span class="normal">1903</span>
<span class="normal">1904</span>
<span class="normal">1905</span>
<span class="normal">1906</span>
<span class="normal">1907</span>
<span class="normal">1908</span>
<span class="normal">1909</span>
<span class="normal">1910</span>
<span class="normal">1911</span>
<span class="normal">1912</span>
<span class="normal">1913</span>
<span class="normal">1914</span>
<span class="normal">1915</span>
<span class="normal">1916</span>
<span class="normal">1917</span>
<span class="normal">1918</span>
<span class="normal">1919</span>
<span class="normal">1920</span>
<span class="normal">1921</span>
<span class="normal">1922</span>
<span class="normal">1923</span>
<span class="normal">1924</span>
<span class="normal">1925</span>
<span class="normal">1926</span>
<span class="normal">1927</span>
<span class="normal">1928</span>
<span class="normal">1929</span>
<span class="normal">1930</span>
<span class="normal">1931</span>
<span class="normal">1932</span>
<span class="normal">1933</span>
<span class="normal">1934</span>
<span class="normal">1935</span>
<span class="normal">1936</span>
<span class="normal">1937</span>
<span class="normal">1938</span>
<span class="normal">1939</span>
<span class="normal">1940</span>
<span class="normal">1941</span>
<span class="normal">1942</span>
<span class="normal">1943</span>
<span class="normal">1944</span>
<span class="normal">1945</span>
<span class="normal">1946</span>
<span class="normal">1947</span>
<span class="normal">1948</span>
<span class="normal">1949</span>
<span class="normal">1950</span>
<span class="normal">1951</span>
<span class="normal">1952</span>
<span class="normal">1953</span>
<span class="normal">1954</span>
<span class="normal">1955</span>
<span class="normal">1956</span>
<span class="normal">1957</span>
<span class="normal">1958</span>
<span class="normal">1959</span>
<span class="normal">1960</span>
<span class="normal">1961</span>
<span class="normal">1962</span>
<span class="normal">1963</span>
<span class="normal">1964</span>
<span class="normal">1965</span>
<span class="normal">1966</span>
<span class="normal">1967</span>
<span class="normal">1968</span>
<span class="normal">1969</span>
<span class="normal">1970</span>
<span class="normal">1971</span>
<span class="normal">1972</span>
<span class="normal">1973</span>
<span class="normal">1974</span>
<span class="normal">1975</span>
<span class="normal">1976</span>
<span class="normal">1977</span>
<span class="normal">1978</span>
<span class="normal">1979</span>
<span class="normal">1980</span>
<span class="normal">1981</span>
<span class="normal">1982</span>
<span class="normal">1983</span>
<span class="normal">1984</span>
<span class="normal">1985</span>
<span class="normal">1986</span>
<span class="normal">1987</span>
<span class="normal">1988</span>
<span class="normal">1989</span>
<span class="normal">1990</span>
<span class="normal">1991</span>
<span class="normal">1992</span>
<span class="normal">1993</span>
<span class="normal">1994</span>
<span class="normal">1995</span>
<span class="normal">1996</span>
<span class="normal">1997</span>
<span class="normal">1998</span>
<span class="normal">1999</span>
<span class="normal">2000</span>
<span class="normal">2001</span>
<span class="normal">2002</span>
<span class="normal">2003</span>
<span class="normal">2004</span>
<span class="normal">2005</span>
<span class="normal">2006</span>
<span class="normal">2007</span>
<span class="normal">2008</span>
<span class="normal">2009</span>
<span class="normal">2010</span>
<span class="normal">2011</span>
<span class="normal">2012</span>
<span class="normal">2013</span>
<span class="normal">2014</span>
<span class="normal">2015</span>
<span class="normal">2016</span>
<span class="normal">2017</span>
<span class="normal">2018</span>
<span class="normal">2019</span>
<span class="normal">2020</span>
<span class="normal">2021</span>
<span class="normal">2022</span>
<span class="normal">2023</span>
<span class="normal">2024</span>
<span class="normal">2025</span>
<span class="normal">2026</span>
<span class="normal">2027</span>
<span class="normal">2028</span>
<span class="normal">2029</span>
<span class="normal">2030</span>
<span class="normal">2031</span>
<span class="normal">2032</span>
<span class="normal">2033</span>
<span class="normal">2034</span>
<span class="normal">2035</span>
<span class="normal">2036</span>
<span class="normal">2037</span>
<span class="normal">2038</span>
<span class="normal">2039</span>
<span class="normal">2040</span>
<span class="normal">2041</span>
<span class="normal">2042</span>
<span class="normal">2043</span>
<span class="normal">2044</span>
<span class="normal">2045</span>
<span class="normal">2046</span>
<span class="normal">2047</span>
<span class="normal">2048</span>
<span class="normal">2049</span>
<span class="normal">2050</span>
<span class="normal">2051</span>
<span class="normal">2052</span>
<span class="normal">2053</span>
<span class="normal">2054</span>
<span class="normal">2055</span>
<span class="normal">2056</span>
<span class="normal">2057</span>
<span class="normal">2058</span>
<span class="normal">2059</span>
<span class="normal">2060</span>
<span class="normal">2061</span>
<span class="normal">2062</span>
<span class="normal">2063</span>
<span class="normal">2064</span>
<span class="normal">2065</span>
<span class="normal">2066</span>
<span class="normal">2067</span>
<span class="normal">2068</span>
<span class="normal">2069</span>
<span class="normal">2070</span>
<span class="normal">2071</span>
<span class="normal">2072</span>
<span class="normal">2073</span>
<span class="normal">2074</span>
<span class="normal">2075</span>
<span class="normal">2076</span>
<span class="normal">2077</span>
<span class="normal">2078</span>
<span class="normal">2079</span>
<span class="normal">2080</span>
<span class="normal">2081</span>
<span class="normal">2082</span>
<span class="normal">2083</span>
<span class="normal">2084</span>
<span class="normal">2085</span>
<span class="normal">2086</span>
<span class="normal">2087</span>
<span class="normal">2088</span>
<span class="normal">2089</span>
<span class="normal">2090</span>
<span class="normal">2091</span>
<span class="normal">2092</span>
<span class="normal">2093</span>
<span class="normal">2094</span>
<span class="normal">2095</span>
<span class="normal">2096</span>
<span class="normal">2097</span>
<span class="normal">2098</span>
<span class="normal">2099</span>
<span class="normal">2100</span>
<span class="normal">2101</span>
<span class="normal">2102</span>
<span class="normal">2103</span>
<span class="normal">2104</span>
<span class="normal">2105</span>
<span class="normal">2106</span>
<span class="normal">2107</span>
<span class="normal">2108</span>
<span class="normal">2109</span>
<span class="normal">2110</span>
<span class="normal">2111</span>
<span class="normal">2112</span>
<span class="normal">2113</span>
<span class="normal">2114</span>
<span class="normal">2115</span>
<span class="normal">2116</span>
<span class="normal">2117</span>
<span class="normal">2118</span>
<span class="normal">2119</span>
<span class="normal">2120</span>
<span class="normal">2121</span>
<span class="normal">2122</span>
<span class="normal">2123</span>
<span class="normal">2124</span>
<span class="normal">2125</span>
<span class="normal">2126</span>
<span class="normal">2127</span>
<span class="normal">2128</span>
<span class="normal">2129</span>
<span class="normal">2130</span>
<span class="normal">2131</span>
<span class="normal">2132</span>
<span class="normal">2133</span>
<span class="normal">2134</span>
<span class="normal">2135</span>
<span class="normal">2136</span>
<span class="normal">2137</span>
<span class="normal">2138</span>
<span class="normal">2139</span>
<span class="normal">2140</span>
<span class="normal">2141</span>
<span class="normal">2142</span>
<span class="normal">2143</span>
<span class="normal">2144</span>
<span class="normal">2145</span>
<span class="normal">2146</span>
<span class="normal">2147</span>
<span class="normal">2148</span>
<span class="normal">2149</span>
<span class="normal">2150</span>
<span class="normal">2151</span>
<span class="normal">2152</span>
<span class="normal">2153</span>
<span class="normal">2154</span>
<span class="normal">2155</span>
<span class="normal">2156</span>
<span class="normal">2157</span>
<span class="normal">2158</span>
<span class="normal">2159</span>
<span class="normal">2160</span>
<span class="normal">2161</span>
<span class="normal">2162</span>
<span class="normal">2163</span>
<span class="normal">2164</span>
<span class="normal">2165</span>
<span class="normal">2166</span>
<span class="normal">2167</span>
<span class="normal">2168</span>
<span class="normal">2169</span>
<span class="normal">2170</span>
<span class="normal">2171</span>
<span class="normal">2172</span>
<span class="normal">2173</span>
<span class="normal">2174</span>
<span class="normal">2175</span>
<span class="normal">2176</span>
<span class="normal">2177</span>
<span class="normal">2178</span>
<span class="normal">2179</span>
<span class="normal">2180</span>
<span class="normal">2181</span>
<span class="normal">2182</span>
<span class="normal">2183</span>
<span class="normal">2184</span>
<span class="normal">2185</span>
<span class="normal">2186</span>
<span class="normal">2187</span>
<span class="normal">2188</span>
<span class="normal">2189</span>
<span class="normal">2190</span>
<span class="normal">2191</span>
<span class="normal">2192</span>
<span class="normal">2193</span>
<span class="normal">2194</span>
<span class="normal">2195</span>
<span class="normal">2196</span>
<span class="normal">2197</span>
<span class="normal">2198</span>
<span class="normal">2199</span>
<span class="normal">2200</span>
<span class="normal">2201</span>
<span class="normal">2202</span>
<span class="normal">2203</span>
<span class="normal">2204</span>
<span class="normal">2205</span>
<span class="normal">2206</span>
<span class="normal">2207</span>
<span class="normal">2208</span>
<span class="normal">2209</span>
<span class="normal">2210</span>
<span class="normal">2211</span>
<span class="normal">2212</span>
<span class="normal">2213</span>
<span class="normal">2214</span>
<span class="normal">2215</span>
<span class="normal">2216</span>
<span class="normal">2217</span>
<span class="normal">2218</span>
<span class="normal">2219</span>
<span class="normal">2220</span>
<span class="normal">2221</span>
<span class="normal">2222</span>
<span class="normal">2223</span>
<span class="normal">2224</span>
<span class="normal">2225</span>
<span class="normal">2226</span>
<span class="normal">2227</span>
<span class="normal">2228</span>
<span class="normal">2229</span>
<span class="normal">2230</span>
<span class="normal">2231</span>
<span class="normal">2232</span>
<span class="normal">2233</span>
<span class="normal">2234</span>
<span class="normal">2235</span>
<span class="normal">2236</span>
<span class="normal">2237</span>
<span class="normal">2238</span>
<span class="normal">2239</span>
<span class="normal">2240</span>
<span class="normal">2241</span>
<span class="normal">2242</span>
<span class="normal">2243</span>
<span class="normal">2244</span>
<span class="normal">2245</span>
<span class="normal">2246</span>
<span class="normal">2247</span>
<span class="normal">2248</span>
<span class="normal">2249</span>
<span class="normal">2250</span>
<span class="normal">2251</span>
<span class="normal">2252</span>
<span class="normal">2253</span>
<span class="normal">2254</span>
<span class="normal">2255</span>
<span class="normal">2256</span>
<span class="normal">2257</span>
<span class="normal">2258</span>
<span class="normal">2259</span>
<span class="normal">2260</span>
<span class="normal">2261</span>
<span class="normal">2262</span>
<span class="normal">2263</span>
<span class="normal">2264</span>
<span class="normal">2265</span>
<span class="normal">2266</span>
<span class="normal">2267</span>
<span class="normal">2268</span>
<span class="normal">2269</span>
<span class="normal">2270</span>
<span class="normal">2271</span>
<span class="normal">2272</span>
<span class="normal">2273</span>
<span class="normal">2274</span>
<span class="normal">2275</span>
<span class="normal">2276</span>
<span class="normal">2277</span>
<span class="normal">2278</span>
<span class="normal">2279</span>
<span class="normal">2280</span>
<span class="normal">2281</span>
<span class="normal">2282</span>
<span class="normal">2283</span>
<span class="normal">2284</span>
<span class="normal">2285</span>
<span class="normal">2286</span>
<span class="normal">2287</span>
<span class="normal">2288</span>
<span class="normal">2289</span>
<span class="normal">2290</span>
<span class="normal">2291</span>
<span class="normal">2292</span>
<span class="normal">2293</span>
<span class="normal">2294</span>
<span class="normal">2295</span>
<span class="normal">2296</span>
<span class="normal">2297</span>
<span class="normal">2298</span>
<span class="normal">2299</span>
<span class="normal">2300</span>
<span class="normal">2301</span>
<span class="normal">2302</span>
<span class="normal">2303</span>
<span class="normal">2304</span>
<span class="normal">2305</span>
<span class="normal">2306</span>
<span class="normal">2307</span>
<span class="normal">2308</span>
<span class="normal">2309</span>
<span class="normal">2310</span>
<span class="normal">2311</span>
<span class="normal">2312</span>
<span class="normal">2313</span>
<span class="normal">2314</span>
<span class="normal">2315</span>
<span class="normal">2316</span>
<span class="normal">2317</span>
<span class="normal">2318</span>
<span class="normal">2319</span>
<span class="normal">2320</span>
<span class="normal">2321</span>
<span class="normal">2322</span>
<span class="normal">2323</span>
<span class="normal">2324</span>
<span class="normal">2325</span>
<span class="normal">2326</span>
<span class="normal">2327</span>
<span class="normal">2328</span>
<span class="normal">2329</span>
<span class="normal">2330</span>
<span class="normal">2331</span>
<span class="normal">2332</span>
<span class="normal">2333</span>
<span class="normal">2334</span>
<span class="normal">2335</span>
<span class="normal">2336</span>
<span class="normal">2337</span>
<span class="normal">2338</span>
<span class="normal">2339</span>
<span class="normal">2340</span>
<span class="normal">2341</span>
<span class="normal">2342</span>
<span class="normal">2343</span>
<span class="normal">2344</span>
<span class="normal">2345</span>
<span class="normal">2346</span>
<span class="normal">2347</span>
<span class="normal">2348</span>
<span class="normal">2349</span>
<span class="normal">2350</span>
<span class="normal">2351</span>
<span class="normal">2352</span>
<span class="normal">2353</span>
<span class="normal">2354</span>
<span class="normal">2355</span>
<span class="normal">2356</span>
<span class="normal">2357</span>
<span class="normal">2358</span>
<span class="normal">2359</span>
<span class="normal">2360</span>
<span class="normal">2361</span>
<span class="normal">2362</span>
<span class="normal">2363</span>
<span class="normal">2364</span>
<span class="normal">2365</span>
<span class="normal">2366</span>
<span class="normal">2367</span>
<span class="normal">2368</span>
<span class="normal">2369</span>
<span class="normal">2370</span>
<span class="normal">2371</span>
<span class="normal">2372</span>
<span class="normal">2373</span>
<span class="normal">2374</span>
<span class="normal">2375</span>
<span class="normal">2376</span>
<span class="normal">2377</span>
<span class="normal">2378</span>
<span class="normal">2379</span>
<span class="normal">2380</span>
<span class="normal">2381</span>
<span class="normal">2382</span>
<span class="normal">2383</span>
<span class="normal">2384</span>
<span class="normal">2385</span>
<span class="normal">2386</span>
<span class="normal">2387</span>
<span class="normal">2388</span>
<span class="normal">2389</span>
<span class="normal">2390</span>
<span class="normal">2391</span>
<span class="normal">2392</span>
<span class="normal">2393</span>
<span class="normal">2394</span>
<span class="normal">2395</span>
<span class="normal">2396</span>
<span class="normal">2397</span>
<span class="normal">2398</span>
<span class="normal">2399</span>
<span class="normal">2400</span>
<span class="normal">2401</span>
<span class="normal">2402</span>
<span class="normal">2403</span>
<span class="normal">2404</span>
<span class="normal">2405</span>
<span class="normal">2406</span>
<span class="normal">2407</span>
<span class="normal">2408</span>
<span class="normal">2409</span>
<span class="normal">2410</span>
<span class="normal">2411</span>
<span class="normal">2412</span>
<span class="normal">2413</span>
<span class="normal">2414</span>
<span class="normal">2415</span>
<span class="normal">2416</span>
<span class="normal">2417</span>
<span class="normal">2418</span>
<span class="normal">2419</span>
<span class="normal">2420</span>
<span class="normal">2421</span>
<span class="normal">2422</span>
<span class="normal">2423</span>
<span class="normal">2424</span>
<span class="normal">2425</span>
<span class="normal">2426</span>
<span class="normal">2427</span>
<span class="normal">2428</span>
<span class="normal">2429</span>
<span class="normal">2430</span>
<span class="normal">2431</span>
<span class="normal">2432</span>
<span class="normal">2433</span>
<span class="normal">2434</span>
<span class="normal">2435</span>
<span class="normal">2436</span>
<span class="normal">2437</span>
<span class="normal">2438</span>
<span class="normal">2439</span>
<span class="normal">2440</span>
<span class="normal">2441</span>
<span class="normal">2442</span>
<span class="normal">2443</span>
<span class="normal">2444</span>
<span class="normal">2445</span>
<span class="normal">2446</span>
<span class="normal">2447</span>
<span class="normal">2448</span>
<span class="normal">2449</span>
<span class="normal">2450</span>
<span class="normal">2451</span>
<span class="normal">2452</span>
<span class="normal">2453</span>
<span class="normal">2454</span>
<span class="normal">2455</span>
<span class="normal">2456</span>
<span class="normal">2457</span>
<span class="normal">2458</span>
<span class="normal">2459</span>
<span class="normal">2460</span>
<span class="normal">2461</span>
<span class="normal">2462</span>
<span class="normal">2463</span>
<span class="normal">2464</span>
<span class="normal">2465</span>
<span class="normal">2466</span>
<span class="normal">2467</span>
<span class="normal">2468</span>
<span class="normal">2469</span>
<span class="normal">2470</span>
<span class="normal">2471</span>
<span class="normal">2472</span>
<span class="normal">2473</span>
<span class="normal">2474</span>
<span class="normal">2475</span>
<span class="normal">2476</span>
<span class="normal">2477</span>
<span class="normal">2478</span>
<span class="normal">2479</span>
<span class="normal">2480</span>
<span class="normal">2481</span>
<span class="normal">2482</span>
<span class="normal">2483</span>
<span class="normal">2484</span>
<span class="normal">2485</span>
<span class="normal">2486</span>
<span class="normal">2487</span>
<span class="normal">2488</span>
<span class="normal">2489</span>
<span class="normal">2490</span>
<span class="normal">2491</span>
<span class="normal">2492</span>
<span class="normal">2493</span>
<span class="normal">2494</span>
<span class="normal">2495</span>
<span class="normal">2496</span>
<span class="normal">2497</span>
<span class="normal">2498</span>
<span class="normal">2499</span>
<span class="normal">2500</span>
<span class="normal">2501</span>
<span class="normal">2502</span>
<span class="normal">2503</span>
<span class="normal">2504</span>
<span class="normal">2505</span>
<span class="normal">2506</span>
<span class="normal">2507</span>
<span class="normal">2508</span>
<span class="normal">2509</span>
<span class="normal">2510</span>
<span class="normal">2511</span>
<span class="normal">2512</span>
<span class="normal">2513</span>
<span class="normal">2514</span>
<span class="normal">2515</span>
<span class="normal">2516</span>
<span class="normal">2517</span>
<span class="normal">2518</span>
<span class="normal">2519</span>
<span class="normal">2520</span>
<span class="normal">2521</span>
<span class="normal">2522</span>
<span class="normal">2523</span>
<span class="normal">2524</span>
<span class="normal">2525</span>
<span class="normal">2526</span>
<span class="normal">2527</span>
<span class="normal">2528</span>
<span class="normal">2529</span>
<span class="normal">2530</span>
<span class="normal">2531</span>
<span class="normal">2532</span>
<span class="normal">2533</span>
<span class="normal">2534</span>
<span class="normal">2535</span>
<span class="normal">2536</span>
<span class="normal">2537</span>
<span class="normal">2538</span>
<span class="normal">2539</span>
<span class="normal">2540</span>
<span class="normal">2541</span>
<span class="normal">2542</span>
<span class="normal">2543</span>
<span class="normal">2544</span>
<span class="normal">2545</span>
<span class="normal">2546</span>
<span class="normal">2547</span>
<span class="normal">2548</span>
<span class="normal">2549</span>
<span class="normal">2550</span>
<span class="normal">2551</span>
<span class="normal">2552</span>
<span class="normal">2553</span>
<span class="normal">2554</span>
<span class="normal">2555</span>
<span class="normal">2556</span>
<span class="normal">2557</span>
<span class="normal">2558</span>
<span class="normal">2559</span>
<span class="normal">2560</span>
<span class="normal">2561</span>
<span class="normal">2562</span>
<span class="normal">2563</span>
<span class="normal">2564</span>
<span class="normal">2565</span>
<span class="normal">2566</span>
<span class="normal">2567</span>
<span class="normal">2568</span>
<span class="normal">2569</span>
<span class="normal">2570</span>
<span class="normal">2571</span>
<span class="normal">2572</span>
<span class="normal">2573</span>
<span class="normal">2574</span>
<span class="normal">2575</span>
<span class="normal">2576</span>
<span class="normal">2577</span>
<span class="normal">2578</span>
<span class="normal">2579</span>
<span class="normal">2580</span>
<span class="normal">2581</span>
<span class="normal">2582</span>
<span class="normal">2583</span>
<span class="normal">2584</span>
<span class="normal">2585</span>
<span class="normal">2586</span>
<span class="normal">2587</span>
<span class="normal">2588</span>
<span class="normal">2589</span>
<span class="normal">2590</span>
<span class="normal">2591</span>
<span class="normal">2592</span>
<span class="normal">2593</span>
<span class="normal">2594</span>
<span class="normal">2595</span>
<span class="normal">2596</span>
<span class="normal">2597</span>
<span class="normal">2598</span>
<span class="normal">2599</span>
<span class="normal">2600</span>
<span class="normal">2601</span>
<span class="normal">2602</span>
<span class="normal">2603</span>
<span class="normal">2604</span>
<span class="normal">2605</span>
<span class="normal">2606</span>
<span class="normal">2607</span>
<span class="normal">2608</span>
<span class="normal">2609</span>
<span class="normal">2610</span>
<span class="normal">2611</span>
<span class="normal">2612</span>
<span class="normal">2613</span>
<span class="normal">2614</span>
<span class="normal">2615</span>
<span class="normal">2616</span>
<span class="normal">2617</span>
<span class="normal">2618</span>
<span class="normal">2619</span>
<span class="normal">2620</span>
<span class="normal">2621</span>
<span class="normal">2622</span>
<span class="normal">2623</span>
<span class="normal">2624</span>
<span class="normal">2625</span>
<span class="normal">2626</span>
<span class="normal">2627</span>
<span class="normal">2628</span>
<span class="normal">2629</span>
<span class="normal">2630</span>
<span class="normal">2631</span>
<span class="normal">2632</span>
<span class="normal">2633</span>
<span class="normal">2634</span>
<span class="normal">2635</span>
<span class="normal">2636</span>
<span class="normal">2637</span>
<span class="normal">2638</span>
<span class="normal">2639</span>
<span class="normal">2640</span>
<span class="normal">2641</span>
<span class="normal">2642</span>
<span class="normal">2643</span>
<span class="normal">2644</span>
<span class="normal">2645</span>
<span class="normal">2646</span>
<span class="normal">2647</span>
<span class="normal">2648</span>
<span class="normal">2649</span>
<span class="normal">2650</span>
<span class="normal">2651</span>
<span class="normal">2652</span>
<span class="normal">2653</span>
<span class="normal">2654</span>
<span class="normal">2655</span>
<span class="normal">2656</span>
<span class="normal">2657</span>
<span class="normal">2658</span>
<span class="normal">2659</span>
<span class="normal">2660</span>
<span class="normal">2661</span>
<span class="normal">2662</span>
<span class="normal">2663</span>
<span class="normal">2664</span>
<span class="normal">2665</span>
<span class="normal">2666</span>
<span class="normal">2667</span>
<span class="normal">2668</span>
<span class="normal">2669</span>
<span class="normal">2670</span>
<span class="normal">2671</span>
<span class="normal">2672</span>
<span class="normal">2673</span>
<span class="normal">2674</span>
<span class="normal">2675</span>
<span class="normal">2676</span>
<span class="normal">2677</span>
<span class="normal">2678</span>
<span class="normal">2679</span>
<span class="normal">2680</span>
<span class="normal">2681</span>
<span class="normal">2682</span>
<span class="normal">2683</span>
<span class="normal">2684</span>
<span class="normal">2685</span>
<span class="normal">2686</span>
<span class="normal">2687</span>
<span class="normal">2688</span>
<span class="normal">2689</span>
<span class="normal">2690</span>
<span class="normal">2691</span>
<span class="normal">2692</span>
<span class="normal">2693</span>
<span class="normal">2694</span>
<span class="normal">2695</span>
<span class="normal">2696</span>
<span class="normal">2697</span>
<span class="normal">2698</span>
<span class="normal">2699</span>
<span class="normal">2700</span>
<span class="normal">2701</span>
<span class="normal">2702</span>
<span class="normal">2703</span>
<span class="normal">2704</span>
<span class="normal">2705</span>
<span class="normal">2706</span>
<span class="normal">2707</span>
<span class="normal">2708</span>
<span class="normal">2709</span>
<span class="normal">2710</span>
<span class="normal">2711</span>
<span class="normal">2712</span>
<span class="normal">2713</span>
<span class="normal">2714</span>
<span class="normal">2715</span>
<span class="normal">2716</span>
<span class="normal">2717</span>
<span class="normal">2718</span>
<span class="normal">2719</span>
<span class="normal">2720</span>
<span class="normal">2721</span>
<span class="normal">2722</span>
<span class="normal">2723</span>
<span class="normal">2724</span>
<span class="normal">2725</span>
<span class="normal">2726</span>
<span class="normal">2727</span>
<span class="normal">2728</span>
<span class="normal">2729</span>
<span class="normal">2730</span>
<span class="normal">2731</span>
<span class="normal">2732</span>
<span class="normal">2733</span>
<span class="normal">2734</span>
<span class="normal">2735</span>
<span class="normal">2736</span>
<span class="normal">2737</span>
<span class="normal">2738</span>
<span class="normal">2739</span>
<span class="normal">2740</span>
<span class="normal">2741</span>
<span class="normal">2742</span>
<span class="normal">2743</span>
<span class="normal">2744</span>
<span class="normal">2745</span>
<span class="normal">2746</span>
<span class="normal">2747</span>
<span class="normal">2748</span>
<span class="normal">2749</span>
<span class="normal">2750</span>
<span class="normal">2751</span>
<span class="normal">2752</span>
<span class="normal">2753</span>
<span class="normal">2754</span>
<span class="normal">2755</span>
<span class="normal">2756</span>
<span class="normal">2757</span>
<span class="normal">2758</span>
<span class="normal">2759</span>
<span class="normal">2760</span>
<span class="normal">2761</span>
<span class="normal">2762</span>
<span class="normal">2763</span>
<span class="normal">2764</span>
<span class="normal">2765</span>
<span class="normal">2766</span>
<span class="normal">2767</span>
<span class="normal">2768</span>
<span class="normal">2769</span>
<span class="normal">2770</span>
<span class="normal">2771</span>
<span class="normal">2772</span>
<span class="normal">2773</span>
<span class="normal">2774</span>
<span class="normal">2775</span>
<span class="normal">2776</span>
<span class="normal">2777</span>
<span class="normal">2778</span>
<span class="normal">2779</span>
<span class="normal">2780</span>
<span class="normal">2781</span>
<span class="normal">2782</span>
<span class="normal">2783</span>
<span class="normal">2784</span>
<span class="normal">2785</span>
<span class="normal">2786</span>
<span class="normal">2787</span>
<span class="normal">2788</span>
<span class="normal">2789</span>
<span class="normal">2790</span>
<span class="normal">2791</span>
<span class="normal">2792</span>
<span class="normal">2793</span>
<span class="normal">2794</span>
<span class="normal">2795</span>
<span class="normal">2796</span>
<span class="normal">2797</span>
<span class="normal">2798</span>
<span class="normal">2799</span>
<span class="normal">2800</span>
<span class="normal">2801</span>
<span class="normal">2802</span>
<span class="normal">2803</span>
<span class="normal">2804</span>
<span class="normal">2805</span>
<span class="normal">2806</span>
<span class="normal">2807</span>
<span class="normal">2808</span>
<span class="normal">2809</span>
<span class="normal">2810</span>
<span class="normal">2811</span>
<span class="normal">2812</span>
<span class="normal">2813</span>
<span class="normal">2814</span>
<span class="normal">2815</span>
<span class="normal">2816</span>
<span class="normal">2817</span>
<span class="normal">2818</span>
<span class="normal">2819</span>
<span class="normal">2820</span>
<span class="normal">2821</span>
<span class="normal">2822</span>
<span class="normal">2823</span>
<span class="normal">2824</span>
<span class="normal">2825</span>
<span class="normal">2826</span>
<span class="normal">2827</span>
<span class="normal">2828</span>
<span class="normal">2829</span>
<span class="normal">2830</span>
<span class="normal">2831</span>
<span class="normal">2832</span>
<span class="normal">2833</span>
<span class="normal">2834</span>
<span class="normal">2835</span>
<span class="normal">2836</span>
<span class="normal">2837</span>
<span class="normal">2838</span>
<span class="normal">2839</span>
<span class="normal">2840</span>
<span class="normal">2841</span>
<span class="normal">2842</span>
<span class="normal">2843</span>
<span class="normal">2844</span>
<span class="normal">2845</span>
<span class="normal">2846</span>
<span class="normal">2847</span>
<span class="normal">2848</span>
<span class="normal">2849</span>
<span class="normal">2850</span>
<span class="normal">2851</span>
<span class="normal">2852</span>
<span class="normal">2853</span>
<span class="normal">2854</span>
<span class="normal">2855</span>
<span class="normal">2856</span>
<span class="normal">2857</span>
<span class="normal">2858</span>
<span class="normal">2859</span>
<span class="normal">2860</span>
<span class="normal">2861</span>
<span class="normal">2862</span>
<span class="normal">2863</span>
<span class="normal">2864</span>
<span class="normal">2865</span>
<span class="normal">2866</span>
<span class="normal">2867</span>
<span class="normal">2868</span>
<span class="normal">2869</span>
<span class="normal">2870</span>
<span class="normal">2871</span>
<span class="normal">2872</span>
<span class="normal">2873</span>
<span class="normal">2874</span>
<span class="normal">2875</span>
<span class="normal">2876</span>
<span class="normal">2877</span>
<span class="normal">2878</span>
<span class="normal">2879</span>
<span class="normal">2880</span>
<span class="normal">2881</span>
<span class="normal">2882</span>
<span class="normal">2883</span>
<span class="normal">2884</span>
<span class="normal">2885</span>
<span class="normal">2886</span>
<span class="normal">2887</span>
<span class="normal">2888</span>
<span class="normal">2889</span>
<span class="normal">2890</span>
<span class="normal">2891</span>
<span class="normal">2892</span>
<span class="normal">2893</span>
<span class="normal">2894</span>
<span class="normal">2895</span>
<span class="normal">2896</span>
<span class="normal">2897</span>
<span class="normal">2898</span>
<span class="normal">2899</span>
<span class="normal">2900</span>
<span class="normal">2901</span>
<span class="normal">2902</span>
<span class="normal">2903</span>
<span class="normal">2904</span>
<span class="normal">2905</span>
<span class="normal">2906</span>
<span class="normal">2907</span>
<span class="normal">2908</span>
<span class="normal">2909</span>
<span class="normal">2910</span>
<span class="normal">2911</span>
<span class="normal">2912</span>
<span class="normal">2913</span>
<span class="normal">2914</span>
<span class="normal">2915</span>
<span class="normal">2916</span>
<span class="normal">2917</span>
<span class="normal">2918</span>
<span class="normal">2919</span>
<span class="normal">2920</span>
<span class="normal">2921</span>
<span class="normal">2922</span>
<span class="normal">2923</span>
<span class="normal">2924</span>
<span class="normal">2925</span>
<span class="normal">2926</span>
<span class="normal">2927</span>
<span class="normal">2928</span>
<span class="normal">2929</span>
<span class="normal">2930</span>
<span class="normal">2931</span>
<span class="normal">2932</span>
<span class="normal">2933</span>
<span class="normal">2934</span>
<span class="normal">2935</span>
<span class="normal">2936</span>
<span class="normal">2937</span>
<span class="normal">2938</span>
<span class="normal">2939</span>
<span class="normal">2940</span>
<span class="normal">2941</span>
<span class="normal">2942</span>
<span class="normal">2943</span>
<span class="normal">2944</span>
<span class="normal">2945</span>
<span class="normal">2946</span>
<span class="normal">2947</span>
<span class="normal">2948</span>
<span class="normal">2949</span>
<span class="normal">2950</span>
<span class="normal">2951</span>
<span class="normal">2952</span>
<span class="normal">2953</span>
<span class="normal">2954</span>
<span class="normal">2955</span>
<span class="normal">2956</span>
<span class="normal">2957</span>
<span class="normal">2958</span>
<span class="normal">2959</span>
<span class="normal">2960</span>
<span class="normal">2961</span>
<span class="normal">2962</span>
<span class="normal">2963</span>
<span class="normal">2964</span>
<span class="normal">2965</span>
<span class="normal">2966</span>
<span class="normal">2967</span>
<span class="normal">2968</span>
<span class="normal">2969</span>
<span class="normal">2970</span>
<span class="normal">2971</span>
<span class="normal">2972</span>
<span class="normal">2973</span>
<span class="normal">2974</span>
<span class="normal">2975</span>
<span class="normal">2976</span>
<span class="normal">2977</span>
<span class="normal">2978</span>
<span class="normal">2979</span>
<span class="normal">2980</span>
<span class="normal">2981</span>
<span class="normal">2982</span>
<span class="normal">2983</span>
<span class="normal">2984</span>
<span class="normal">2985</span>
<span class="normal">2986</span>
<span class="normal">2987</span>
<span class="normal">2988</span>
<span class="normal">2989</span>
<span class="normal">2990</span>
<span class="normal">2991</span>
<span class="normal">2992</span>
<span class="normal">2993</span>
<span class="normal">2994</span>
<span class="normal">2995</span>
<span class="normal">2996</span>
<span class="normal">2997</span>
<span class="normal">2998</span>
<span class="normal">2999</span>
<span class="normal">3000</span>
<span class="normal">3001</span>
<span class="normal">3002</span>
<span class="normal">3003</span>
<span class="normal">3004</span>
<span class="normal">3005</span>
<span class="normal">3006</span>
<span class="normal">3007</span>
<span class="normal">3008</span>
<span class="normal">3009</span>
<span class="normal">3010</span>
<span class="normal">3011</span>
<span class="normal">3012</span>
<span class="normal">3013</span>
<span class="normal">3014</span>
<span class="normal">3015</span>
<span class="normal">3016</span>
<span class="normal">3017</span>
<span class="normal">3018</span>
<span class="normal">3019</span>
<span class="normal">3020</span>
<span class="normal">3021</span>
<span class="normal">3022</span>
<span class="normal">3023</span>
<span class="normal">3024</span>
<span class="normal">3025</span>
<span class="normal">3026</span>
<span class="normal">3027</span>
<span class="normal">3028</span>
<span class="normal">3029</span>
<span class="normal">3030</span>
<span class="normal">3031</span>
<span class="normal">3032</span>
<span class="normal">3033</span>
<span class="normal">3034</span>
<span class="normal">3035</span>
<span class="normal">3036</span>
<span class="normal">3037</span>
<span class="normal">3038</span>
<span class="normal">3039</span>
<span class="normal">3040</span>
<span class="normal">3041</span>
<span class="normal">3042</span>
<span class="normal">3043</span>
<span class="normal">3044</span>
<span class="normal">3045</span>
<span class="normal">3046</span>
<span class="normal">3047</span>
<span class="normal">3048</span>
<span class="normal">3049</span>
<span class="normal">3050</span>
<span class="normal">3051</span>
<span class="normal">3052</span>
<span class="normal">3053</span>
<span class="normal">3054</span>
<span class="normal">3055</span>
<span class="normal">3056</span>
<span class="normal">3057</span>
<span class="normal">3058</span>
<span class="normal">3059</span>
<span class="normal">3060</span>
<span class="normal">3061</span>
<span class="normal">3062</span>
<span class="normal">3063</span>
<span class="normal">3064</span>
<span class="normal">3065</span>
<span class="normal">3066</span>
<span class="normal">3067</span>
<span class="normal">3068</span>
<span class="normal">3069</span>
<span class="normal">3070</span>
<span class="normal">3071</span>
<span class="normal">3072</span>
<span class="normal">3073</span>
<span class="normal">3074</span>
<span class="normal">3075</span>
<span class="normal">3076</span>
<span class="normal">3077</span>
<span class="normal">3078</span>
<span class="normal">3079</span>
<span class="normal">3080</span>
<span class="normal">3081</span>
<span class="normal">3082</span>
<span class="normal">3083</span>
<span class="normal">3084</span>
<span class="normal">3085</span>
<span class="normal">3086</span>
<span class="normal">3087</span>
<span class="normal">3088</span>
<span class="normal">3089</span>
<span class="normal">3090</span>
<span class="normal">3091</span>
<span class="normal">3092</span>
<span class="normal">3093</span>
<span class="normal">3094</span>
<span class="normal">3095</span>
<span class="normal">3096</span>
<span class="normal">3097</span>
<span class="normal">3098</span>
<span class="normal">3099</span>
<span class="normal">3100</span>
<span class="normal">3101</span>
<span class="normal">3102</span>
<span class="normal">3103</span>
<span class="normal">3104</span>
<span class="normal">3105</span>
<span class="normal">3106</span>
<span class="normal">3107</span>
<span class="normal">3108</span>
<span class="normal">3109</span>
<span class="normal">3110</span>
<span class="normal">3111</span>
<span class="normal">3112</span>
<span class="normal">3113</span>
<span class="normal">3114</span>
<span class="normal">3115</span>
<span class="normal">3116</span>
<span class="normal">3117</span>
<span class="normal">3118</span>
<span class="normal">3119</span>
<span class="normal">3120</span>
<span class="normal">3121</span>
<span class="normal">3122</span>
<span class="normal">3123</span>
<span class="normal">3124</span>
<span class="normal">3125</span>
<span class="normal">3126</span>
<span class="normal">3127</span>
<span class="normal">3128</span>
<span class="normal">3129</span>
<span class="normal">3130</span>
<span class="normal">3131</span>
<span class="normal">3132</span>
<span class="normal">3133</span>
<span class="normal">3134</span>
<span class="normal">3135</span>
<span class="normal">3136</span>
<span class="normal">3137</span>
<span class="normal">3138</span>
<span class="normal">3139</span>
<span class="normal">3140</span>
<span class="normal">3141</span>
<span class="normal">3142</span>
<span class="normal">3143</span>
<span class="normal">3144</span>
<span class="normal">3145</span>
<span class="normal">3146</span>
<span class="normal">3147</span>
<span class="normal">3148</span>
<span class="normal">3149</span>
<span class="normal">3150</span>
<span class="normal">3151</span>
<span class="normal">3152</span>
<span class="normal">3153</span>
<span class="normal">3154</span>
<span class="normal">3155</span>
<span class="normal">3156</span>
<span class="normal">3157</span>
<span class="normal">3158</span>
<span class="normal">3159</span>
<span class="normal">3160</span>
<span class="normal">3161</span>
<span class="normal">3162</span>
<span class="normal">3163</span>
<span class="normal">3164</span>
<span class="normal">3165</span>
<span class="normal">3166</span>
<span class="normal">3167</span>
<span class="normal">3168</span>
<span class="normal">3169</span>
<span class="normal">3170</span>
<span class="normal">3171</span>
<span class="normal">3172</span>
<span class="normal">3173</span>
<span class="normal">3174</span>
<span class="normal">3175</span>
<span class="normal">3176</span>
<span class="normal">3177</span>
<span class="normal">3178</span>
<span class="normal">3179</span>
<span class="normal">3180</span>
<span class="normal">3181</span>
<span class="normal">3182</span>
<span class="normal">3183</span>
<span class="normal">3184</span>
<span class="normal">3185</span>
<span class="normal">3186</span>
<span class="normal">3187</span>
<span class="normal">3188</span>
<span class="normal">3189</span>
<span class="normal">3190</span>
<span class="normal">3191</span>
<span class="normal">3192</span>
<span class="normal">3193</span>
<span class="normal">3194</span>
<span class="normal">3195</span>
<span class="normal">3196</span>
<span class="normal">3197</span>
<span class="normal">3198</span>
<span class="normal">3199</span>
<span class="normal">3200</span>
<span class="normal">3201</span></pre></div></td><td class="code"><div><pre><div id="l1" class="code_block"><span class="k">\chapter</span><span class="nb">{</span>Library Utilities<span class="nb">}</span> <span class="k">\label</span><span class="nb">{</span>library<span class="nb">_</span>utilities<span class="nb">}</span>
</div><div id="l2" class="code_block"><span class="c">%====================================================</span>
</div><div id="l3" class="code_block">
</div><div id="l4" class="code_block">In this chapter we introduce libraries of some useful predicates that
</div><div id="l5" class="code_block">are supplied with XSB.  Interfaces and more elaborate packages are
</div><div id="l6" class="code_block">documented in later chapters.  These predicates are available only
</div><div id="l7" class="code_block">when imported them from (or explicitly consult) the corresponding
</div><div id="l8" class="code_block">modules.
</div><div id="l9" class="code_block">
</div><div id="l10" class="code_block">
</div><div id="l11" class="code_block"><span class="k">\section</span><span class="nb">{</span>List Processing<span class="nb">}</span>
</div><div id="l12" class="code_block"><span class="c">%========================</span>
</div><div id="l13" class="code_block">The XSB library contains various list utilities, some of which 
</div><div id="l14" class="code_block">are listed below.  These predicates should be explicitly imported from
</div><div id="l15" class="code_block">the module specified after the skeletal specification of each predicate.
</div><div id="l16" class="code_block">There are a lot more useful list processing predicates in various modules
</div><div id="l17" class="code_block">of the XSB system, and the interested user can find them by 
</div><div id="l18" class="code_block">looking at the sources.
</div><div id="l19" class="code_block">
</div><div id="l20" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l21" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>append(?List1, ?List2, ?List3)<span class="nb">}{</span>basics<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>append/3<span class="nb">}}</span>
</div><div id="l22" class="code_block"><span class="c">%\predindex{append/3~(L)}</span>
</div><div id="l23" class="code_block">    Succeeds if list <span class="nb">{</span><span class="k">\tt</span> List3<span class="nb">}</span> is the concatenation of lists 
</div><div id="l24" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> List1<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> List2<span class="nb">}</span>.
</div><div id="l25" class="code_block">
</div><div id="l26" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>member(?Element, ?List)<span class="nb">}{</span>basics<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>member/2<span class="nb">}}</span>
</div><div id="l27" class="code_block"><span class="c">%\predindex{member/2~(L)}</span>
</div><div id="l28" class="code_block">    Checks whether <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span> unifies with any element of list 
</div><div id="l29" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span>, succeeding more than once if there are multiple 
</div><div id="l30" class="code_block">    such elements.
</div><div id="l31" class="code_block">
</div><div id="l32" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>memberchk(?Element, ?List)<span class="nb">}{</span>basics<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>memberchk/2<span class="nb">}}</span>
</div><div id="l33" class="code_block"><span class="c">%\predindex{memberchk/2~(L)}</span>
</div><div id="l34" class="code_block">    Similar to <span class="nb">{</span><span class="k">\tt</span> member<span class="nb">}</span>/2, except that <span class="nb">{</span><span class="k">\tt</span> memberchk<span class="nb">}</span>/2 is
</div><div id="l35" class="code_block">    deterministic, i.e.<span class="k">\</span> does not succeed more than once for any call.
</div><div id="l36" class="code_block">
</div><div id="l37" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>ith(?Index, ?List, ?Element)<span class="nb">}{</span>basics<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>ith/3<span class="nb">}}</span>
</div><div id="l38" class="code_block"><span class="c">%\predindex{ith/3~(L)}</span>
</div><div id="l39" class="code_block">    Succeeds if the <span class="s">$</span><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> Index^{th}}</span><span class="s">$</span> element of the list <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span> 
</div><div id="l40" class="code_block">    unifies with <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span>.  Fails if <span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span> is not a positive
</div><div id="l41" class="code_block">    integer or greater than the length of <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span>.
</div><div id="l42" class="code_block">    Either <span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span>, or <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span>, 
</div><div id="l43" class="code_block">    should be instantiated (but not necessarily ground) at the time of 
</div><div id="l44" class="code_block">    the call.
</div><div id="l45" class="code_block">
</div><div id="l46" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>delete<span class="k">\_ith</span>(+Index, +List, ?Element, ?RestList)<span class="nb">}{</span>listutil<span class="nb">}</span>
</div><div id="l47" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>delete<span class="k">\_ith</span>/4<span class="nb">}}</span>
</div><div id="l48" class="code_block"><span class="c">%\predindex{delete\_ith/4~(L)}</span>
</div><div id="l49" class="code_block">    Succeeds if the <span class="s">$</span><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> Index^{th}}</span><span class="s">$</span> element of the list <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span>
</div><div id="l50" class="code_block">    unifies with <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span>, and <span class="nb">{</span><span class="k">\tt</span> RestList<span class="nb">}</span> is <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span> with
</div><div id="l51" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span> removed.  Fails if <span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span> is not a positive
</div><div id="l52" class="code_block">    integer or greater than the length of <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span>.
</div><div id="l53" class="code_block">
</div><div id="l54" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>log<span class="k">\_ith</span>(?Index, ?Tree, ?Element)<span class="nb">}{</span>basics<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>log<span class="k">\_ith</span>/3<span class="nb">}}</span>
</div><div id="l55" class="code_block"><span class="c">%\predindex{log\_ith/3~(L)}</span>
</div><div id="l56" class="code_block">    Succeeds if the <span class="s">$</span><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> Index^{th}}</span><span class="s">$</span> element of the Tree <span class="nb">{</span><span class="k">\tt</span> Tree<span class="nb">}</span>
</div><div id="l57" class="code_block">    unifies with <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span>.  Fails if <span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span> is not a
</div><div id="l58" class="code_block">    positive integer or greater than the number of elements that can
</div><div id="l59" class="code_block">    be in <span class="nb">{</span><span class="k">\tt</span> Tree<span class="nb">}</span>.  Either <span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> Tree<span class="nb">}</span>, or <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l60" class="code_block">    Tree<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span>, should be instantiated (but not
</div><div id="l61" class="code_block">    necessarily ground) at the time of the call.  Tree is a list of
</div><div id="l62" class="code_block">    full binary trees, the first being of depth 0, and each one being
</div><div id="l63" class="code_block">    of depth one greater than its predecessor.  So <span class="nb">{</span><span class="k">\tt</span> log<span class="k">\_ith</span>/3<span class="nb">}</span> is
</div><div id="l64" class="code_block">    very similar to <span class="nb">{</span><span class="k">\tt</span> ith/3<span class="nb">}</span> except it uses a tree instead of a
</div><div id="l65" class="code_block">    list to obtain log-time access to its elements.
</div><div id="l66" class="code_block">
</div><div id="l67" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>log<span class="k">\_ith\_bound</span>(?Index, ?Tree, ?Element)<span class="nb">}{</span>basics<span class="nb">}</span>
</div><div id="l68" class="code_block">        <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>log<span class="k">\_ith\_bound</span>/3<span class="nb">}}</span>
</div><div id="l69" class="code_block"><span class="c">%\predindex{log\_ith\_bound/3~(L)}</span>
</div><div id="l70" class="code_block">    is like <span class="nb">{</span><span class="k">\tt</span> log<span class="k">\_ith</span>/3<span class="nb">}</span>, but only if the <span class="s">$</span><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> Index^{th}}</span><span class="s">$</span> element
</div><div id="l71" class="code_block">    of <span class="nb">{</span><span class="k">\tt</span> Tree<span class="nb">}</span> is non-variable and equal to Element.  This predicate
</div><div id="l72" class="code_block">    can be used in both directions, and is most useful with Index
</div><div id="l73" class="code_block">    unbound, since it will then bind <span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span> for
</div><div id="l74" class="code_block">    each non-variable element in <span class="nb">{</span><span class="k">\tt</span> Tree<span class="nb">}</span> (in time proportional to
</div><div id="l75" class="code_block">    <span class="s">$</span><span class="nb">N</span><span class="o">*</span><span class="nb">logN</span><span class="s">$</span>, for <span class="s">$</span><span class="nb">N</span><span class="s">$</span> the number of non-variable entries in <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l76" class="code_block">    Tree<span class="nb">}</span>.)
</div><div id="l77" class="code_block">
</div><div id="l78" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>length(?List, ?Length)<span class="nb">}{</span>basics<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>length/2<span class="nb">}}</span>
</div><div id="l79" class="code_block"><span class="c">%\predindex{length/2~(L)}</span>
</div><div id="l80" class="code_block">    Succeeds if the length of the list <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span> is <span class="nb">{</span><span class="k">\tt</span> Length<span class="nb">}</span>.
</div><div id="l81" class="code_block">    This predicate is deterministic if <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span> is instantiated 
</div><div id="l82" class="code_block">    to a list of definite length, but is nondeterministic if 
</div><div id="l83" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span> is a variable or has a variable tail.  If <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span>
</div><div id="l84" class="code_block">    is uninstantiated, it is unified with a list of length <span class="nb">{</span><span class="k">\tt</span> Length<span class="nb">}</span>
</div><div id="l85" class="code_block">    that contains variables.
</div><div id="l86" class="code_block">
</div><div id="l87" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>same<span class="k">\_length</span>(?List1, ?List2)<span class="nb">}{</span>basics<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>same<span class="k">\_length</span>/2<span class="nb">}}</span>
</div><div id="l88" class="code_block"><span class="c">%\predindex{same\_length/2~(L)}</span>
</div><div id="l89" class="code_block">    Succeeds if list <span class="nb">{</span><span class="k">\tt</span> List1<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> List2<span class="nb">}</span> are both lists of
</div><div id="l90" class="code_block">    the same number of elements.  No relation between the types or
</div><div id="l91" class="code_block">    values of their elements is implied.  This predicate may be used
</div><div id="l92" class="code_block">    to generate either list (containing variables as elements) given
</div><div id="l93" class="code_block">    the other, or to generate two lists of the same length, in which
</div><div id="l94" class="code_block">    case the arguments will be bound to lists of length <span class="s">$</span><span class="m">0</span><span class="nb">,</span><span class="m">1</span><span class="nb">,</span><span class="m">2</span><span class="nb">,</span><span class="nv">\ldots</span><span class="s">$</span>.
</div><div id="l95" class="code_block">
</div><div id="l96" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>select(?Element, ?L1, ?L2)<span class="nb">}{</span>basics<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>select/3<span class="nb">}}</span>
</div><div id="l97" class="code_block"><span class="c">%\predindex{select/3~(L)}</span>
</div><div id="l98" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> List2<span class="nb">}</span> derives from <span class="nb">{</span><span class="k">\tt</span> List1<span class="nb">}</span> by selecting (removing) an 
</div><div id="l99" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span> non-deterministically.
</div><div id="l100" class="code_block">
</div><div id="l101" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>reverse(+List, ?ReversedList)<span class="nb">}{</span>basics<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>reverse/2<span class="nb">}}</span>
</div><div id="l102" class="code_block"><span class="c">%\predindex{reverse/2~(L)}</span>
</div><div id="l103" class="code_block">    Succeeds if <span class="nb">{</span><span class="k">\tt</span> ReversedList<span class="nb">}</span> is the reverse of list <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span>.
</div><div id="l104" class="code_block">    If <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span> is not a proper list, <span class="nb">{</span><span class="k">\tt</span> reverse/2<span class="nb">}</span> can succeed
</div><div id="l105" class="code_block">    arbitrarily many times.  It works only one way.
</div><div id="l106" class="code_block">
</div><div id="l107" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>perm(+List, ?Perm)<span class="nb">}{</span>basics<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>perm/2<span class="nb">}}</span>
</div><div id="l108" class="code_block"><span class="c">%\predindex{perm/2~(L)}</span>
</div><div id="l109" class="code_block">    Succeeds when <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> Perm<span class="nb">}</span> are permutations of each
</div><div id="l110" class="code_block">    other.  The main use of <span class="nb">{</span><span class="k">\tt</span> perm/2<span class="nb">}</span> is to generate permutations
</div><div id="l111" class="code_block">    of a given list.  <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span> must be a proper list.
</div><div id="l112" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> Perm<span class="nb">}</span> may be partly instantiated.
</div><div id="l113" class="code_block">
</div><div id="l114" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>subseq(?Sequence, ?SubSequence, ?Complement)<span class="nb">}{</span>basics<span class="nb">}</span>
</div><div id="l115" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>subseq/3<span class="nb">}}</span>
</div><div id="l116" class="code_block"><span class="c">%\predindex{subseq/3(L)}</span>
</div><div id="l117" class="code_block">    Succeeds when <span class="nb">{</span><span class="k">\tt</span> SubSequence<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> Complement<span class="nb">}</span> are both
</div><div id="l118" class="code_block">    subsequences of the list <span class="nb">{</span><span class="k">\tt</span> Sequence<span class="nb">}</span> (the order of corresponding
</div><div id="l119" class="code_block">    elements being preserved) and every element of <span class="nb">{</span><span class="k">\tt</span> Sequence<span class="nb">}</span> which
</div><div id="l120" class="code_block">    is not in <span class="nb">{</span><span class="k">\tt</span> SubSequence<span class="nb">}</span> is in the <span class="nb">{</span><span class="k">\tt</span> Complement<span class="nb">}</span> and vice
</div><div id="l121" class="code_block">    versa.  That is,
</div><div id="l122" class="code_block">    <span class="sb">\[</span><span class="nb"> length</span><span class="o">(</span><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> Sequence}</span><span class="o">)</span><span class="nb"> </span><span class="o">=</span>
</div><div id="l123" class="code_block"><span class="nb">                length</span><span class="o">(</span><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> SubSequence}</span><span class="o">)+</span><span class="nb">length</span><span class="o">(</span><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> Complement}</span><span class="o">)</span><span class="nb"> </span><span class="s">\]</span>
</div><div id="l124" class="code_block">    for example, <span class="nb">{</span><span class="k">\tt</span> subseq([1,2,3,4], [1,3], [2,4]).<span class="nb">}</span>
</div><div id="l125" class="code_block">    The main use of <span class="nb">{</span><span class="k">\tt</span> subseq/3<span class="nb">}</span> is to generate subsets and their
</div><div id="l126" class="code_block">    complements together, but can also be used to interleave two lists
</div><div id="l127" class="code_block">    in all possible ways.
</div><div id="l128" class="code_block">
</div><div id="l129" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>merge(+List1, +List2, ?List3)<span class="nb">}{</span>listutil<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>merge/3<span class="nb">}}</span>
</div><div id="l130" class="code_block"><span class="c">%\predindex{merge/3~(L)}</span>
</div><div id="l131" class="code_block">    Succeeds if <span class="nb">{</span><span class="k">\tt</span> List3<span class="nb">}</span> is the list resulting from ``merging&#39;&#39; lists 
</div><div id="l132" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> List1<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> List2<span class="nb">}</span>,
</div><div id="l133" class="code_block">    i.e.<span class="k">\</span> the elements of <span class="nb">{</span><span class="k">\tt</span> List1<span class="nb">}</span> together with any element of 
</div><div id="l134" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> List2<span class="nb">}</span> not occurring in <span class="nb">{</span><span class="k">\tt</span> List1<span class="nb">}</span>.
</div><div id="l135" class="code_block">    If~<span class="nb">{</span><span class="k">\tt</span> List1<span class="nb">}</span> or~<span class="nb">{</span><span class="k">\tt</span> List2<span class="nb">}</span> contain duplicates, <span class="nb">{</span><span class="k">\tt</span> List3<span class="nb">}</span> may 
</div><div id="l136" class="code_block">    also contain duplicates.
</div><div id="l137" class="code_block">
</div><div id="l138" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>absmerge(+List1, +List2, ?List3)<span class="nb">}{</span>listutil<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>absmerge/3<span class="nb">}}</span>
</div><div id="l139" class="code_block">    Predicate <span class="nb">{</span><span class="k">\tt</span> absmerge/3<span class="nb">}</span> is similar to <span class="nb">{</span><span class="k">\tt</span> merge/3<span class="nb">}</span>, except that 
</div><div id="l140" class="code_block">    it uses predicate <span class="nb">{</span><span class="k">\tt</span> absmember/2<span class="nb">}</span> described below rather than 
</div><div id="l141" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> member/2<span class="nb">}</span>.
</div><div id="l142" class="code_block">
</div><div id="l143" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>absmember(+Element, +List)<span class="nb">}{</span>listutil<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>absmember/2<span class="nb">}}</span>
</div><div id="l144" class="code_block">    Similar to <span class="nb">{</span><span class="k">\tt</span> member<span class="nb">}</span>/2, except that it checks for identity
</div><div id="l145" class="code_block">    (through the use of predicate <span class="nb">{</span><span class="k">\tt</span> &#39;==&#39;/2<span class="nb">}</span>) rather than unifiability 
</div><div id="l146" class="code_block">    (through <span class="nb">{</span><span class="k">\tt</span> &#39;=&#39;/2<span class="nb">}</span>) of <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span> with elements of <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span>.
</div><div id="l147" class="code_block">
</div><div id="l148" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>member2(?Element, ?List)<span class="nb">}{</span>listutil<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>member2/2<span class="nb">}}</span>
</div><div id="l149" class="code_block">    Checks whether <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span> unifies with any of the actual elements 
</div><div id="l150" class="code_block">    of <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span>.  The only difference between this predicate and 
</div><div id="l151" class="code_block">    predicate <span class="nb">{</span><span class="k">\tt</span> member/2<span class="nb">}</span> is on lists having a variable tail, 
</div><div id="l152" class="code_block">    e.g.<span class="k">\</span> <span class="k">\verb</span>&#39;[a, b, c | <span class="nb">_</span> ]&#39;: while <span class="nb">{</span><span class="k">\tt</span> member/2<span class="nb">}</span> would insert 
</div><div id="l153" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span> at the end of such a list if it did not find it, 
</div><div id="l154" class="code_block">    Predicate <span class="nb">{</span><span class="k">\tt</span> member2/2<span class="nb">}</span> only checks for membership but does not 
</div><div id="l155" class="code_block">    insert the <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span> into the list if it is not there.
</div><div id="l156" class="code_block">
</div><div id="l157" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>closetail(?List)<span class="nb">}{</span>listutil<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>closetail/1<span class="nb">}}</span>
</div><div id="l158" class="code_block">    Predicate <span class="nb">{</span><span class="k">\tt</span> closetail/1<span class="nb">}</span> closes the tail of an open-ended list.
</div><div id="l159" class="code_block">    It succeeds only once.
</div><div id="l160" class="code_block">
</div><div id="l161" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l162" class="code_block">
</div><div id="l163" class="code_block"><span class="k">\subsection</span><span class="nb">{</span>Processing Comma Lists<span class="nb">}</span>
</div><div id="l164" class="code_block"><span class="c">%===========================</span>
</div><div id="l165" class="code_block">
</div><div id="l166" class="code_block">It is often useful to process comma lists when meta-interpreting or
</div><div id="l167" class="code_block">preprocessing.  XSB libraries include the following simple utilities.
</div><div id="l168" class="code_block">
</div><div id="l169" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l170" class="code_block">
</div><div id="l171" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>comma<span class="k">\_to\_list</span>(+CommaList,-List)<span class="nb">}{</span>basics<span class="nb">}</span>
</div><div id="l172" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>comma<span class="k">\_to\_list</span>/2<span class="nb">}}</span>
</div><div id="l173" class="code_block"><span class="c">%</span>
</div><div id="l174" class="code_block">Transforms <span class="nb">{</span><span class="k">\tt</span> CommaList<span class="nb">}</span> to <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span>.
</div><div id="l175" class="code_block">
</div><div id="l176" class="code_block"><span class="k">\ourrepeatnewitem</span><span class="nb">{</span>comma<span class="k">\_append</span>(?CL1,?CL2,?CL3)<span class="nb">}{</span>basics<span class="nb">}</span>
</div><div id="l177" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>comma<span class="k">\_append</span>/3<span class="nb">}}</span>
</div><div id="l178" class="code_block"><span class="c">%</span>
</div><div id="l179" class="code_block"><span class="k">\ourrepeatnewitem</span><span class="nb">{</span>comma<span class="k">\_length</span>(?CommaList,?Length)<span class="nb">}{</span>basics<span class="nb">}</span>
</div><div id="l180" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>comma<span class="k">\_length</span>/2<span class="nb">}}</span>
</div><div id="l181" class="code_block"><span class="c">%</span>
</div><div id="l182" class="code_block"><span class="k">\ourrepeatnewitem</span><span class="nb">{</span>comma<span class="k">\_member</span>(?Element,?CommaList)<span class="nb">}{</span>basics<span class="nb">}</span>
</div><div id="l183" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>comma<span class="k">\_member</span>/2<span class="nb">}}</span>
</div><div id="l184" class="code_block"><span class="c">%</span>
</div><div id="l185" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>comma<span class="k">\_member</span>(?Element,?CommaList)<span class="nb">}{</span>basics<span class="nb">}</span>
</div><div id="l186" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>comma<span class="k">\_memberchk</span>/2<span class="nb">}}</span>
</div><div id="l187" class="code_block"><span class="c">%</span>
</div><div id="l188" class="code_block">Analogues for comma lists of <span class="nb">{</span><span class="k">\tt</span> append/3<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span> length/3<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span> member/2<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l189" class="code_block">memberchk/2<span class="nb">}</span>, respectively.
</div><div id="l190" class="code_block">
</div><div id="l191" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l192" class="code_block">	
</div><div id="l193" class="code_block"><span class="k">\section</span><span class="nb">{</span>Attributed Variables<span class="nb">}</span> <span class="k">\label</span><span class="nb">{</span>sec:attributed-variables<span class="nb">}</span>
</div><div id="l194" class="code_block"><span class="c">%=============================</span>
</div><div id="l195" class="code_block">
</div><div id="l196" class="code_block"><span class="k">\index</span><span class="nb">{</span>Prologs!hProlog<span class="nb">}</span>
</div><div id="l197" class="code_block"><span class="k">\index</span><span class="nb">{</span>Prologs!SWI<span class="nb">}</span>
</div><div id="l198" class="code_block"><span class="c">%</span>
</div><div id="l199" class="code_block">Attributed variables are a special data type that associates variables
</div><div id="l200" class="code_block">with arbitrary attributes as well as supports extensible unification.
</div><div id="l201" class="code_block">Attributed variables have proven to be a flexible and powerful
</div><div id="l202" class="code_block">mechanism to extend a classic logic programming system with the
</div><div id="l203" class="code_block">ability of constraint solving.  Our low-level API for constraints
</div><div id="l204" class="code_block">closely resembles that of hProlog~<span class="k">\cite</span><span class="nb">{</span>hprolog<span class="nb">}</span> and
</div><div id="l205" class="code_block">SWI~<span class="k">\cite</span><span class="nb">{</span>SWI-manual<span class="nb">}</span>.
</div><div id="l206" class="code_block">
</div><div id="l207" class="code_block"><span class="k">\subsection</span><span class="nb">{</span>Lowlevel Interface<span class="nb">}</span>
</div><div id="l208" class="code_block"><span class="c">%</span>
</div><div id="l209" class="code_block">Attributes of variables are pairs of attribute module names and
</div><div id="l210" class="code_block">values.  An attribute module name can be any atom.  A value can be any
</div><div id="l211" class="code_block">XSB value (term, variable, atom, <span class="k">\ldots</span>). Any variable has at most one
</div><div id="l212" class="code_block">attribute for a particular attribute module.  Attribute modules are
</div><div id="l213" class="code_block">distinct from XSB modules: although it is most efficient to keep each
</div><div id="l214" class="code_block">handlers for each attribute module in their own XSB module.
</div><div id="l215" class="code_block">c
</div><div id="l216" class="code_block">Attributes can be manipulated with the following three predicates
</div><div id="l217" class="code_block">(<span class="k">\texttt</span><span class="nb">{</span>get<span class="k">\_attr</span>/3<span class="nb">}</span>, <span class="k">\texttt</span><span class="nb">{</span>put<span class="k">\_attr</span>/3<span class="nb">}</span> and <span class="k">\texttt</span><span class="nb">{</span>del<span class="k">\_attr</span>/2<span class="nb">}</span>)
</div><div id="l218" class="code_block">defined in the module <span class="k">\texttt</span><span class="nb">{</span>machine<span class="nb">}</span>.
</div><div id="l219" class="code_block">
</div><div id="l220" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l221" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>get<span class="k">\_attr</span>(-Var,+Mod, ?Val)<span class="nb">}{</span>machine<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>get<span class="k">\_attr</span>/3<span class="nb">}}</span> 
</div><div id="l222" class="code_block"><span class="c">%</span>
</div><div id="l223" class="code_block">Gets the value of the attribute of <span class="k">\texttt</span><span class="nb">{</span>Var<span class="nb">}</span> in attribute module
</div><div id="l224" class="code_block"><span class="k">\texttt</span><span class="nb">{</span>Mod<span class="nb">}</span>. Non-variable terms in <span class="k">\texttt</span><span class="nb">{</span>Var<span class="nb">}</span> cause a type
</div><div id="l225" class="code_block">error. <span class="k">\texttt</span><span class="nb">{</span>Val<span class="nb">}</span> will be unified with the value of the attribute,
</div><div id="l226" class="code_block">if it exists. Otherwise the predicate fails.
</div><div id="l227" class="code_block">
</div><div id="l228" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>put<span class="k">\_attr</span>(-Var,+Mod, ?Val)<span class="nb">}{</span>machine<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>put<span class="k">\_attr</span>/3<span class="nb">}}</span>
</div><div id="l229" class="code_block"><span class="c">%</span>
</div><div id="l230" class="code_block">Sets the value of the attribute of <span class="k">\texttt</span><span class="nb">{</span>Var<span class="nb">}</span> in attribute module
</div><div id="l231" class="code_block"><span class="k">\texttt</span><span class="nb">{</span>Mod<span class="nb">}</span>. Non-variable terms in <span class="k">\texttt</span><span class="nb">{</span>Var<span class="nb">}</span> cause a type
</div><div id="l232" class="code_block">error. The previous value of the attribute is overwritten, if it
</div><div id="l233" class="code_block">exists.
</div><div id="l234" class="code_block">
</div><div id="l235" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>del<span class="k">\_attr</span>(-Var,  +Mod)<span class="nb">}{</span>machine<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>del<span class="k">\_attr</span>/2<span class="nb">}}</span> 
</div><div id="l236" class="code_block"><span class="c">%</span>
</div><div id="l237" class="code_block">Removes the attribute of <span class="k">\texttt</span><span class="nb">{</span>Var<span class="nb">}</span> in attribute module
</div><div id="l238" class="code_block"><span class="k">\texttt</span><span class="nb">{</span>Mod<span class="nb">}</span>. Non-variable terms in <span class="k">\texttt</span><span class="nb">{</span>Var<span class="nb">}</span> cause a type
</div><div id="l239" class="code_block">error. The previous value of the attribute is removed, if it exists.
</div><div id="l240" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l241" class="code_block">
</div><div id="l242" class="code_block">One has to extend the default unification algorithm for used
</div><div id="l243" class="code_block">attributes by installing a handler in the following way:
</div><div id="l244" class="code_block">
</div><div id="l245" class="code_block"><span class="k">\noindent</span>
</div><div id="l246" class="code_block"><span class="nb">{</span><span class="k">\tt</span>
</div><div id="l247" class="code_block">:- install<span class="k">\_verify\_attribute\_handler</span>(<span class="s">$</span><span class="o">+</span><span class="nb">Mod, </span><span class="o">-</span><span class="nb">AttrValue, </span><span class="o">-</span><span class="nb">Target, </span><span class="o">+</span><span class="nb">Handler, </span><span class="o">+</span><span class="nb">WarningFlag</span><span class="s">$</span>)<span class="nb">}</span>
</div><div id="l248" class="code_block"><span class="k">\\</span>
</div><div id="l249" class="code_block"><span class="nb">{</span><span class="k">\tt</span>
</div><div id="l250" class="code_block">  :- install<span class="k">\_verify\_attribute\_handler</span>(<span class="s">$</span><span class="o">+</span><span class="nb">Mod, </span><span class="o">-</span><span class="nb">AttrValue, </span><span class="o">-</span><span class="nb">Target, </span><span class="o">+</span><span class="nb">Handler</span><span class="s">$</span>)<span class="nb">}</span>
</div><div id="l251" class="code_block">
</div><div id="l252" class="code_block"><span class="k">\noindent</span> The
</div><div id="l253" class="code_block">predicates
</div><div id="l254" class="code_block"><span class="k">\texttt</span><span class="nb">{</span>install<span class="k">\_verify\_attribute\_handler</span>/5<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>install<span class="k">\_verify\_attribute\_handler</span>/5<span class="nb">}}</span>
</div><div id="l255" class="code_block">and
</div><div id="l256" class="code_block"><span class="k">\texttt</span><span class="nb">{</span>install<span class="k">\_verify\_attribute\_handler</span>/4<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>install<span class="k">\_verify\_attribute\_handler</span>/4<span class="nb">}}</span>
</div><div id="l257" class="code_block">are defined in module <span class="k">\texttt</span><span class="nb">{</span>machine<span class="nb">}</span>. <span class="s">$</span><span class="nb">Mod</span><span class="s">$</span> is the
</div><div id="l258" class="code_block">attribute <span class="nb">{</span><span class="k">\tt</span> Module<span class="nb">}</span> and <span class="s">$</span><span class="nb">Handler</span><span class="s">$</span> is a term with arguments
</div><div id="l259" class="code_block"><span class="s">$</span><span class="nb">AttrValue</span><span class="s">$</span> and <span class="s">$</span><span class="nb">Target</span><span class="s">$</span>. The <span class="s">$</span><span class="nb">Handler</span><span class="s">$</span> term has to correspond to a
</div><div id="l260" class="code_block">handler predicate that takes the value of the attribute (<span class="s">$</span><span class="nb">AttrValue</span><span class="s">$</span>)
</div><div id="l261" class="code_block">and the term that the attributed value is bound to (<span class="s">$</span><span class="nb">Target</span><span class="s">$</span>) as
</div><div id="l262" class="code_block">arguments. The argument <span class="s">$</span><span class="nb">WarningFlag</span><span class="s">$</span> in the 5-argument version of the
</div><div id="l263" class="code_block">predicate can be used to suppress the warning issued when replacing the
</div><div id="l264" class="code_block"><span class="nb">{</span><span class="k">\tt</span> verify<span class="k">\_attribute\_handler</span><span class="nb">}</span> for a module. If the argument is
</div><div id="l265" class="code_block"><span class="nb">{</span><span class="k">\tt</span> warning<span class="k">\_on</span><span class="nb">}</span> then the warning is issued if a handler for the module
</div><div id="l266" class="code_block">already exists. Otherwise, the warning is suppressed. 
</div><div id="l267" class="code_block">The 4-argument version of the predicate does <span class="k">\emph</span><span class="nb">{</span>not<span class="nb">}</span> suppress the
</div><div id="l268" class="code_block">warning. 
</div><div id="l269" class="code_block">
</div><div id="l270" class="code_block">To get good efficiency, it is usually best to keep the
</div><div id="l271" class="code_block">handlers for each attribute module in separate XSB modules.
</div><div id="l272" class="code_block">The handler is called after the unification of an attributed variable
</div><div id="l273" class="code_block">with a term or other attributed variable, if the attributed variable
</div><div id="l274" class="code_block">has an attribute in the corresponding module. The two arguments of the
</div><div id="l275" class="code_block">unification are already bound at the time the handler is called,
</div><div id="l276" class="code_block">i.e. the handler is a post-unify handler.
</div><div id="l277" class="code_block">
</div><div id="l278" class="code_block">Here, by giving the implementation of a simple finite domain
</div><div id="l279" class="code_block">constraint solver (see the file <span class="k">\texttt</span><span class="nb">{</span>fd.P<span class="nb">}</span> below), we show how
</div><div id="l280" class="code_block">these lowlevel predicates for attributed variables can be used.  In
</div><div id="l281" class="code_block">this example, an attribute in the module <span class="k">\texttt</span><span class="nb">{</span>fd<span class="nb">}</span> is used and the
</div><div id="l282" class="code_block">value of this attribute is a list of terms.
</div><div id="l283" class="code_block">
</div><div id="l284" class="code_block"><span class="k">\begin</span><span class="nb">{</span>small<span class="nb">}</span>
</div><div id="l285" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l286" class="code_block"><span class="c">%% File: fd.P</span>
</div><div id="l287" class="code_block"><span class="c">%%</span>
</div><div id="l288" class="code_block"><span class="c">%% A simple finite domain constrait solver implemented using the lowlevel </span>
</div><div id="l289" class="code_block"><span class="c">%% attributes variables interface.  </span>
</div><div id="l290" class="code_block">
</div><div id="l291" class="code_block">:- import put<span class="nb">_</span>attr/3, get<span class="nb">_</span>attr/3, del<span class="nb">_</span>attr/3, 
</div><div id="l292" class="code_block">   install<span class="nb">_</span>verify<span class="nb">_</span>attribute<span class="nb">_</span>handler/4 from machine.
</div><div id="l293" class="code_block">:- import member/2 from basics.
</div><div id="l294" class="code_block">
</div><div id="l295" class="code_block">:- install<span class="nb">_</span>verify<span class="nb">_</span>attribute<span class="nb">_</span>handler(fd,AttrValue,Target,fd<span class="nb">_</span>handler(AttrValue,Target)).
</div><div id="l296" class="code_block">
</div><div id="l297" class="code_block">fd<span class="nb">_</span>handler(Da, Target) :-
</div><div id="l298" class="code_block">        (var(Target),                       <span class="c">% Target is an attributed variable</span>
</div><div id="l299" class="code_block">         get<span class="nb">_</span>attr(Target, fd, Db) -&gt;        <span class="c">% has a domain</span>
</div><div id="l300" class="code_block">           intersection(Da, Db, [E|Es]),    <span class="c">% intersection not empty</span>
</div><div id="l301" class="code_block">           (Es = [] -&gt;                      <span class="c">% exactly one element</span>
</div><div id="l302" class="code_block">              Target = E                    <span class="c">% bind Var (and Value) to E</span>
</div><div id="l303" class="code_block">           ;  put<span class="nb">_</span>attr(Target, fd, [E|Es])  <span class="c">% update Var&#39;s (and Value&#39;s)</span>
</div><div id="l304" class="code_block">           )
</div><div id="l305" class="code_block">        ;  member(Target, Da)               <span class="c">% is Target a member of Da?</span>
</div><div id="l306" class="code_block">        ).
</div><div id="l307" class="code_block">
</div><div id="l308" class="code_block">intersection([], <span class="nb">_</span>, []).
</div><div id="l309" class="code_block">intersection([H|T], L2, [H|L3]) :-
</div><div id="l310" class="code_block">        member(H, L2), !,
</div><div id="l311" class="code_block">        intersection(T, L2, L3).
</div><div id="l312" class="code_block">intersection([<span class="nb">_</span>|T], L2, L3) :-
</div><div id="l313" class="code_block">        intersection(T, L2, L3).
</div><div id="l314" class="code_block">
</div><div id="l315" class="code_block">domain(X, Dom) :- 
</div><div id="l316" class="code_block">        var(Dom), !, 
</div><div id="l317" class="code_block">        get<span class="nb">_</span>attr(X, fd, Dom). 
</div><div id="l318" class="code_block">domain(X, List) :- 
</div><div id="l319" class="code_block">        List = [El|Els],                     <span class="c">% at least one element </span>
</div><div id="l320" class="code_block">        (Els = []                            <span class="c">% exactly one element</span>
</div><div id="l321" class="code_block">         -&gt; X = El                           <span class="c">% implied binding </span>
</div><div id="l322" class="code_block">        ;  put<span class="nb">_</span>attr(Fresh, fd, List),        <span class="c">% create a new attributed variable</span>
</div><div id="l323" class="code_block">           X = Fresh                         <span class="c">% may call verify_attributes/2</span>
</div><div id="l324" class="code_block">        ).
</div><div id="l325" class="code_block">
</div><div id="l326" class="code_block">show<span class="nb">_</span>domain(X) :-                            <span class="c">% print out the domain of X</span>
</div><div id="l327" class="code_block">        var(X),                              <span class="c">% X must be a variable</span>
</div><div id="l328" class="code_block">        get<span class="nb">_</span>attr(X, fd, D),
</div><div id="l329" class="code_block">        write(&#39;Domain of &#39;), write(X),
</div><div id="l330" class="code_block">        write(&#39; is &#39;), writeln(D).
</div><div id="l331" class="code_block">
</div><div id="l332" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l333" class="code_block"><span class="k">\end</span><span class="nb">{</span>small<span class="nb">}</span>
</div><div id="l334" class="code_block">
</div><div id="l335" class="code_block">When writing or porting a constraint package, it is usually useful to
</div><div id="l336" class="code_block">adjust the way that correct answer substitutions are shown in the
</div><div id="l337" class="code_block">command line.  This can be controlled using the following two predicates:
</div><div id="l338" class="code_block">
</div><div id="l339" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l340" class="code_block">
</div><div id="l341" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>install<span class="k">\_attribute\_portray\_hook</span>(Module,Attribute,Handler)<span class="nb">}{</span>machine<span class="nb">}</span>
</div><div id="l342" class="code_block"><span class="k">\index</span><span class="nb">{</span>install<span class="k">\_attribute\_portray\_hook</span>/3<span class="nb">}</span>
</div><div id="l343" class="code_block"><span class="c">%</span>
</div><div id="l344" class="code_block">This hook is called by the command-line interpreter when printing out
</div><div id="l345" class="code_block">the value of each variable in a top-level query.  When a printing out
</div><div id="l346" class="code_block">an attributed variable, any appropriate handlers are called to portray
</div><div id="l347" class="code_block">the constraints represented by the attribute.  As an example, the <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l348" class="code_block">  bounds<span class="nb">}</span> package (Section~<span class="k">\ref</span><span class="nb">{</span>sec:bounds<span class="nb">}</span>) uses a hook to print out
</div><div id="l349" class="code_block">the bounds of variables:
</div><div id="l350" class="code_block"><span class="c">%</span>
</div><div id="l351" class="code_block"><span class="k">\begin</span><span class="nb">{</span>small<span class="nb">}</span>
</div><div id="l352" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l353" class="code_block">| ?- X in 1..10,Y in 1..10,X + 4 #&lt; Y -3.
</div><div id="l354" class="code_block">
</div><div id="l355" class="code_block">X = <span class="nb">_</span>h629 <span class="nb">{</span> bounds : 1 .. 2 <span class="nb">}</span>
</div><div id="l356" class="code_block">Y = <span class="nb">_</span>h673 <span class="nb">{</span> bounds : 9 .. 10 <span class="nb">}</span>
</div><div id="l357" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l358" class="code_block"><span class="k">\end</span><span class="nb">{</span>small<span class="nb">}</span>
</div><div id="l359" class="code_block"><span class="c">%</span>
</div><div id="l360" class="code_block">Writing a handler can be as simple as possible or as elaborate as
</div><div id="l361" class="code_block">desired.  In the case of <span class="nb">{</span><span class="k">\tt</span> bounds<span class="nb">}</span> the handler is simple:
</div><div id="l362" class="code_block">
</div><div id="l363" class="code_block"><span class="nb">{</span><span class="k">\small</span>
</div><div id="l364" class="code_block"><span class="nb">{</span><span class="k">\tt</span> bounds<span class="k">\_attr\_portray\_hook</span>(bounds(L,U,<span class="k">\_</span>)) :- write(L..U).<span class="nb">}</span>
</div><div id="l365" class="code_block"><span class="nb">}</span>
</div><div id="l366" class="code_block">
</div><div id="l367" class="code_block">The hook is installed when the constraint package is loaded by placing
</div><div id="l368" class="code_block">in the package loader directive such as:
</div><div id="l369" class="code_block">
</div><div id="l370" class="code_block"><span class="nb">{</span><span class="k">\small</span>
</div><div id="l371" class="code_block"><span class="nb">{</span><span class="k">\tt</span>  :- install<span class="k">\_attribute\_portray\_hook</span>(bounds,Attr,bounds<span class="k">\_attr\_portray\_hook</span>(Attr)).<span class="nb">}</span>
</div><div id="l372" class="code_block"><span class="nb">}</span>
</div><div id="l373" class="code_block">
</div><div id="l374" class="code_block">Note that the hook will be indexed on the module associated with the
</div><div id="l375" class="code_block">attribute (in this case <span class="nb">{</span><span class="k">\tt</span> bounds<span class="nb">}</span>).  XSB&#39;s command-line interpreter
</div><div id="l376" class="code_block">will unify the second argument of the portray hook with the attribute,
</div><div id="l377" class="code_block">and then call <span class="nb">{</span><span class="k">\tt</span> Handler<span class="nb">}</span>.
</div><div id="l378" class="code_block">
</div><div id="l379" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>install<span class="k">\_attribute\_constraint\_hook</span>(Module,Vars,Names,Handler)<span class="nb">}{</span>machine<span class="nb">}</span>
</div><div id="l380" class="code_block"><span class="k">\index</span><span class="nb">{</span>install<span class="k">\_attribute\_constraint\_hook</span>/4<span class="nb">}</span>
</div><div id="l381" class="code_block"><span class="c">%</span>
</div><div id="l382" class="code_block">For some constraint packages, it may not be particularly useful to
</div><div id="l383" class="code_block">associate constraints with variables: instead, the projection of
</div><div id="l384" class="code_block">global constraints onto the variables of the top-level query may be
</div><div id="l385" class="code_block">more useful.  This is the case in the CLP(R) package
</div><div id="l386" class="code_block">(Section~<span class="k">\ref</span><span class="nb">{</span>sec:clpr<span class="nb">}</span>), where the command-line interaction may look as follows:
</div><div id="l387" class="code_block"><span class="c">%</span>
</div><div id="l388" class="code_block"><span class="nb">{</span><span class="k">\small</span>
</div><div id="l389" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l390" class="code_block">| ?- <span class="nb">{</span>X = 2*Y,Y &gt;= 7<span class="nb">}</span>,inf(X,F).
</div><div id="l391" class="code_block"> <span class="nb">{</span> X &gt;= 14.0000 <span class="nb">}</span>
</div><div id="l392" class="code_block"> <span class="nb">{</span> Y = 0.5000 * X <span class="nb">}</span>
</div><div id="l393" class="code_block">
</div><div id="l394" class="code_block">X = <span class="nb">_</span>h8841
</div><div id="l395" class="code_block">Y = <span class="nb">_</span>h9506
</div><div id="l396" class="code_block">F = 14.0000
</div><div id="l397" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l398" class="code_block"><span class="nb">}</span>
</div><div id="l399" class="code_block"><span class="c">%</span>
</div><div id="l400" class="code_block">In XSB, the (projection of the) global constraints in CLP(R) are
</div><div id="l401" class="code_block">displayed by the following routines:
</div><div id="l402" class="code_block"><span class="c">%</span>
</div><div id="l403" class="code_block"><span class="nb">{</span><span class="k">\small</span>
</div><div id="l404" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l405" class="code_block">clpr<span class="nb">_</span>portray<span class="nb">_</span>varlist(Vars,Names):- 
</div><div id="l406" class="code_block">	filter<span class="nb">_</span>varlist(Vars,Names,V1,N1),
</div><div id="l407" class="code_block">	dump(V1,N1,Constraints),
</div><div id="l408" class="code_block">	member(C,Constraints),
</div><div id="l409" class="code_block">	console<span class="nb">_</span>write(&#39; <span class="nb">{</span> &#39;), console<span class="nb">_</span>write(C),	console<span class="nb">_</span>writeln(&#39; <span class="nb">}</span> &#39;),
</div><div id="l410" class="code_block">	fail.
</div><div id="l411" class="code_block">clpr<span class="nb">_</span>portray<span class="nb">_</span>varlist(<span class="nb">_</span>V,<span class="nb">_</span>N).
</div><div id="l412" class="code_block">
</div><div id="l413" class="code_block">filter<span class="nb">_</span>varlist([],[],[],[]).
</div><div id="l414" class="code_block">filter<span class="nb">_</span>varlist([V1|R1],[N1|R2],[V1|R3],[N1|R4]):- 
</div><div id="l415" class="code_block">	var(V1),!,
</div><div id="l416" class="code_block">	filter<span class="nb">_</span>varlist(R1,R2,R3,R4).
</div><div id="l417" class="code_block">filter<span class="nb">_</span>varlist([<span class="nb">_</span>V1|R1],[<span class="nb">_</span>N1|R2],R3,R4):- 
</div><div id="l418" class="code_block">	filter<span class="nb">_</span>varlist(R1,R2,R3,R4).
</div><div id="l419" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l420" class="code_block"><span class="nb">}</span>
</div><div id="l421" class="code_block"><span class="c">%</span>
</div><div id="l422" class="code_block">This predicate sets up a call to the CLP(R) library predicate <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l423" class="code_block">  dump/3<span class="nb">}</span>, whose constraints it then writes out to the console.
</div><div id="l424" class="code_block">Analogous to the portray hook, the console hook is installed using the
</div><div id="l425" class="code_block">directive:
</div><div id="l426" class="code_block"><span class="c">%</span>
</div><div id="l427" class="code_block"><span class="nb">{</span><span class="k">\small</span>
</div><div id="l428" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l429" class="code_block">:- install<span class="nb">_</span>constraint<span class="nb">_</span>portray<span class="nb">_</span>hook(clpr,Vars,Names,clpr<span class="nb">_</span>portray<span class="nb">_</span>varlist(Vars,Names)).
</div><div id="l430" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l431" class="code_block"><span class="nb">}</span>
</div><div id="l432" class="code_block"><span class="c">%</span>
</div><div id="l433" class="code_block">If the <span class="nb">{</span><span class="k">\tt</span> clpr<span class="nb">}</span> module is loaded, the command line interpreter
</div><div id="l434" class="code_block">checks any constraint portray hooks upon the first success of a
</div><div id="l435" class="code_block">top-level goal.  It then unifies the second argument <span class="nb">{</span><span class="k">\tt</span> Vars<span class="nb">}</span> with
</div><div id="l436" class="code_block">the variables of the goal, and <span class="nb">{</span><span class="k">\tt</span> Names<span class="nb">}</span> with the names of the
</div><div id="l437" class="code_block">variables of the goal which are then passed on to <span class="nb">{</span><span class="k">\tt</span> Handler<span class="nb">}</span>
</div><div id="l438" class="code_block">
</div><div id="l439" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l440" class="code_block">
</div><div id="l441" class="code_block"><span class="k">\section</span><span class="nb">{{</span><span class="k">\tt</span> constraintLib<span class="nb">}</span>: a library for CLP<span class="nb">}</span> <span class="k">\label</span><span class="nb">{</span>constraintLib<span class="nb">}</span>
</div><div id="l442" class="code_block"><span class="c">%====================================================================</span>
</div><div id="l443" class="code_block">
</div><div id="l444" class="code_block">XSB supports constraint logic programming through its engine-level
</div><div id="l445" class="code_block">support of attributed variables
</div><div id="l446" class="code_block">(Section~<span class="k">\ref</span><span class="nb">{</span>sec:attributed-variables<span class="nb">}</span>), and its support for
</div><div id="l447" class="code_block">constraint handling rules (CHR) (Chapter~<span class="k">\ref</span><span class="nb">{</span>chr<span class="nb">}</span>).  The <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l448" class="code_block">constraintLib<span class="nb">}</span> library includes routines for delaying and examining
</div><div id="l449" class="code_block">bindings that are commonly used to implement CHR and other constraint
</div><div id="l450" class="code_block">libraries.
</div><div id="l451" class="code_block">
</div><div id="l452" class="code_block">When processing constraints, it is often useful to delay a goal based
</div><div id="l453" class="code_block">on the instantiation level of a term or set of terms.  For instance a
</div><div id="l454" class="code_block"><span class="nb">{</span><span class="k">\tt</span> 3 &gt; X + Y<span class="nb">}</span> should be delayed until both <span class="nb">{</span><span class="k">\tt</span> X<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> Y<span class="nb">}</span> are
</div><div id="l455" class="code_block">instantiated.  However the goal should be reinvoked as soon as
</div><div id="l456" class="code_block">possible after both are instantiated in order to prune search paths
</div><div id="l457" class="code_block">that may not be useful to pursue.  The predicate <span class="nb">{</span><span class="k">\tt</span> when/2<span class="nb">}</span> provides
</div><div id="l458" class="code_block">a useful mechanism to delay goals based on instantiation
</div><div id="l459" class="code_block">patterns~<span class="k">\footnote</span><span class="nb">{</span>Despite the similar name, this method of delaying
</div><div id="l460" class="code_block">is conceptually different from SLG <span class="nb">{</span><span class="k">\sc</span> delaying<span class="nb">}</span> discussed in Volume
</div><div id="l461" class="code_block">1 of this manual, which is used for resolving cycles of dependencies
</div><div id="l462" class="code_block">in computing the well-founded semantics, and is not based on the state
</div><div id="l463" class="code_block">of instantiation of a term.<span class="nb">}</span>.
</div><div id="l464" class="code_block">
</div><div id="l465" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l466" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>when(+Condition,Goal)<span class="nb">}{</span>constraintLib<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>when/2<span class="nb">}}</span>
</div><div id="l467" class="code_block"><span class="c">%</span>
</div><div id="l468" class="code_block">Delays the execution of <span class="nb">{</span><span class="k">\tt</span> Goal<span class="nb">}</span> until <span class="nb">{</span><span class="k">\tt</span> Condition<span class="nb">}</span> is satisfied,
</div><div id="l469" class="code_block">whereupon <span class="nb">{</span><span class="k">\tt</span> Goal<span class="nb">}</span> will be executed.  Condition can have the form
</div><div id="l470" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l471" class="code_block"><span class="k">\item</span> <span class="nb">{</span><span class="k">\tt</span> ?=(Term1,Term2)<span class="nb">}</span>
</div><div id="l472" class="code_block"><span class="k">\item</span> <span class="nb">{</span><span class="k">\tt</span> nonvar(Term)<span class="nb">}</span>
</div><div id="l473" class="code_block"><span class="k">\item</span> <span class="nb">{</span><span class="k">\tt</span> ground(Term)<span class="nb">}</span>~<span class="k">\footnote</span><span class="nb">{</span>To use <span class="nb">{</span><span class="k">\tt</span> ground/1<span class="nb">}</span> in the
</div><div id="l474" class="code_block">condition, it must be imported into the file where it is used.<span class="nb">}</span>
</div><div id="l475" class="code_block"><span class="k">\item</span> <span class="nb">{</span><span class="k">\tt</span> (Condition,Condition)<span class="nb">}</span>
</div><div id="l476" class="code_block"><span class="k">\item</span> <span class="nb">{</span><span class="k">\tt</span> (Condition ; Condition)<span class="nb">}</span>
</div><div id="l477" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l478" class="code_block">
</div><div id="l479" class="code_block"><span class="nb">{</span><span class="k">\bf</span> Example:<span class="nb">}</span> The following session illustrates the use of when/2 to
</div><div id="l480" class="code_block">delay a goal.
</div><div id="l481" class="code_block"><span class="c">%</span>
</div><div id="l482" class="code_block"><span class="k">\begin</span><span class="nb">{</span>small<span class="nb">}</span>
</div><div id="l483" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l484" class="code_block">|?- when(nonvar(X),writeln(test(1-2,nonvar))),writeln(test(1,nonvar)),X = f(<span class="nb">_</span>Y).
</div><div id="l485" class="code_block">
</div><div id="l486" class="code_block">test(1,nonvar)
</div><div id="l487" class="code_block">test(1 - 2,nonvar)
</div><div id="l488" class="code_block">
</div><div id="l489" class="code_block">X = f(<span class="nb">_</span>h245)
</div><div id="l490" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l491" class="code_block"><span class="k">\end</span><span class="nb">{</span>small<span class="nb">}</span>
</div><div id="l492" class="code_block">
</div><div id="l493" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>unifiable(X, Y, -Unifier)<span class="nb">}{</span>constraintLib<span class="nb">}</span>
</div><div id="l494" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>unifiable/3<span class="nb">}}</span>
</div><div id="l495" class="code_block"><span class="c">%</span>
</div><div id="l496" class="code_block">If <span class="nb">{</span><span class="k">\tt</span> X<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> Y<span class="nb">}</span> can unify, succeeds unifying <span class="nb">{</span><span class="k">\tt</span> Unifier<span class="nb">}</span> with
</div><div id="l497" class="code_block">a list of terms of the form <span class="nb">{</span><span class="k">\tt</span> Var = Value<span class="nb">}</span> representing a most
</div><div id="l498" class="code_block">general unifier of <span class="nb">{</span><span class="k">\tt</span> X<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> Y<span class="nb">}</span>.<span class="k">\</span>  <span class="nb">{</span><span class="k">\tt</span> unifiable/3<span class="nb">}</span> can handle
</div><div id="l499" class="code_block">cyclic terms. Attributed variables are handles as normal
</div><div id="l500" class="code_block">variables. Associated hooks are not executed~<span class="k">\footnote</span><span class="nb">{</span>In <span class="k">\version</span> ,
</div><div id="l501" class="code_block">  <span class="nb">{</span><span class="k">\tt</span> unifiable/3<span class="nb">}</span> is written as a Prolog predicate and so is slower
</div><div id="l502" class="code_block">  than many of the predicates in this section.<span class="nb">}</span>.
</div><div id="l503" class="code_block">
</div><div id="l504" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>setarg(+Index,+Term,+Value)<span class="nb">}{</span>constraintLib<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>setarg/3<span class="nb">}}</span>
</div><div id="l505" class="code_block"><span class="c">%</span>
</div><div id="l506" class="code_block">The predicate <span class="nb">{</span><span class="k">\tt</span> setarg/3<span class="nb">}</span> provides an efficient but non-logical way
</div><div id="l507" class="code_block">to update argument <span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span> of a Prolog term <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span> to <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l508" class="code_block">  Value<span class="nb">}</span> via destructive assignment and without the necessity of
</div><div id="l509" class="code_block">copying <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span>.  <span class="nb">{</span><span class="k">\tt</span> setarg/3<span class="nb">}</span> should be used sparingly, to
</div><div id="l510" class="code_block">ensure both clarity and portability of code.
</div><div id="l511" class="code_block">
</div><div id="l512" class="code_block"><span class="nb">{</span><span class="k">\bf</span> Example<span class="nb">}</span>
</div><div id="l513" class="code_block"><span class="nb">{</span><span class="k">\small</span>
</div><div id="l514" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l515" class="code_block">|?- X = p(f(1),g(2),r([a])),
</div><div id="l516" class="code_block">    writeln(zero(X)),
</div><div id="l517" class="code_block">    (  set<span class="nb">_</span>arg(X,2,g([b])),
</div><div id="l518" class="code_block">       writeln(one(X)),
</div><div id="l519" class="code_block">       fail
</div><div id="l520" class="code_block">     ; writeln(two(X))).
</div><div id="l521" class="code_block">zero(p(f(1),g(2),r([a])))
</div><div id="l522" class="code_block">one(p(f(1),g([b]),r([a])))
</div><div id="l523" class="code_block">two(p(f(1),g(2),r([a])))
</div><div id="l524" class="code_block">
</div><div id="l525" class="code_block">X = p(f(1),g(2),r([a]))
</div><div id="l526" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l527" class="code_block"><span class="nb">}</span>
</div><div id="l528" class="code_block">
</div><div id="l529" class="code_block"><span class="nb">{</span><span class="k">\bf</span> Error Cases<span class="nb">}</span> 
</div><div id="l530" class="code_block"><span class="k">\bi</span>
</div><div id="l531" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span> is a variable
</div><div id="l532" class="code_block"><span class="k">\bi</span>
</div><div id="l533" class="code_block"><span class="k">\item</span>    <span class="nb">{</span><span class="k">\tt</span> instantiation<span class="k">\_error</span><span class="nb">}</span>
</div><div id="l534" class="code_block"><span class="k">\ei</span>
</div><div id="l535" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span> neither a variable nor an integer
</div><div id="l536" class="code_block"><span class="k">\bi</span>
</div><div id="l537" class="code_block"><span class="k">\item</span>    <span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(integer,Index)<span class="nb">}</span>
</div><div id="l538" class="code_block"><span class="k">\ei</span>
</div><div id="l539" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span> is less than 0
</div><div id="l540" class="code_block"><span class="k">\bi</span>
</div><div id="l541" class="code_block"><span class="k">\item</span>    <span class="nb">{</span><span class="k">\tt</span> domain<span class="k">\_error</span>(not<span class="k">\_less\_than\_zero</span>,Index)<span class="nb">}</span>
</div><div id="l542" class="code_block"><span class="k">\ei</span>
</div><div id="l543" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span> is a variable
</div><div id="l544" class="code_block"><span class="k">\bi</span>
</div><div id="l545" class="code_block"><span class="k">\item</span>    <span class="nb">{</span><span class="k">\tt</span> instantiation<span class="k">\_error</span><span class="nb">}</span>
</div><div id="l546" class="code_block"><span class="k">\ei</span>
</div><div id="l547" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span> neither a variable nor a compound term
</div><div id="l548" class="code_block"><span class="k">\bi</span>
</div><div id="l549" class="code_block"><span class="k">\item</span>    <span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(compound,Term)<span class="nb">}</span>
</div><div id="l550" class="code_block"><span class="k">\ei</span>
</div><div id="l551" class="code_block"><span class="k">\ei</span>
</div><div id="l552" class="code_block">
</div><div id="l553" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>term<span class="k">\_variables</span>(+Term,-Variables<span class="nb">}{</span>constraintLib<span class="nb">}</span>
</div><div id="l554" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>term<span class="k">\_variables</span>/2<span class="nb">}}</span>
</div><div id="l555" class="code_block"><span class="c">% </span>
</div><div id="l556" class="code_block">Given any Prolog term <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span> as input, returns a sorted list of
</div><div id="l557" class="code_block">variables in the term.  
</div><div id="l558" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l559" class="code_block">
</div><div id="l560" class="code_block"><span class="k">\section</span><span class="nb">{</span>Formatted Output<span class="nb">}</span>
</div><div id="l561" class="code_block">
</div><div id="l562" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l563" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>format(+String,+Control)<span class="nb">}{</span>format<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>format/2<span class="nb">}}</span>
</div><div id="l564" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>format(+Stream,+String,+Control)<span class="nb">}{</span>format<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>format/3<span class="nb">}}</span>
</div><div id="l565" class="code_block">
</div><div id="l566" class="code_block"><span class="nb">{</span><span class="k">\tt</span> format/2<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> format/3<span class="nb">}</span> act as a Prolog analog to the C <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l567" class="code_block">stdio<span class="nb">}</span> function <span class="nb">{</span><span class="k">\tt</span> printf()<span class="nb">}</span>, allowing formatted
</div><div id="l568" class="code_block">output~<span class="k">\footnote</span><span class="nb">{</span>The <span class="nb">{</span><span class="k">\tt</span> format<span class="nb">}</span> family of predicates is due to
</div><div id="l569" class="code_block">Quintus Prolog, by way of Ciao.<span class="nb">}</span>.
</div><div id="l570" class="code_block">
</div><div id="l571" class="code_block">Output is formatted according to <span class="nb">{</span><span class="k">\tt</span> String<span class="nb">}</span> which can contain either
</div><div id="l572" class="code_block">a format control sequence, or any other character which will appear
</div><div id="l573" class="code_block">verbatim in the output. Control sequences act as place-holders for the
</div><div id="l574" class="code_block">actual terms that will be output.  Thus
</div><div id="l575" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l576" class="code_block">        ?- format(&quot;Hello ~q!&quot;,world).
</div><div id="l577" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l578" class="code_block">
</div><div id="l579" class="code_block"><span class="k">\noindent</span>
</div><div id="l580" class="code_block">will print <span class="nb">{</span><span class="k">\tt</span> Hello world!<span class="nb">}</span>.
</div><div id="l581" class="code_block">
</div><div id="l582" class="code_block">If there is only one control sequence, the corresponding element may
</div><div id="l583" class="code_block">be supplied alone in <span class="nb">{</span><span class="k">\tt</span> Control<span class="nb">}</span>.  If there are more, <span class="nb">{</span><span class="k">\tt</span> Control<span class="nb">}</span>
</div><div id="l584" class="code_block">must be a list of these elements. If there are none then <span class="nb">{</span><span class="k">\tt</span> Control<span class="nb">}</span>
</div><div id="l585" class="code_block">must be an empty list. There have to be as many elements in <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l586" class="code_block">Control<span class="nb">}</span> as control sequences in <span class="nb">{</span><span class="k">\tt</span> String<span class="nb">}</span>.
</div><div id="l587" class="code_block">
</div><div id="l588" class="code_block">The character <span class="k">\verb</span>|~| introduces a control sequence. To print 
</div><div id="l589" class="code_block">        a <span class="k">\verb</span>|~| just repeat it:  
</div><div id="l590" class="code_block">        <span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l591" class="code_block">        ?- format(&quot;Hello ~~world!&quot;, []).
</div><div id="l592" class="code_block">        <span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l593" class="code_block">      <span class="k">\noindent</span>
</div><div id="l594" class="code_block">        will output  <span class="k">\verb</span>|Hello ~world!|.
</div><div id="l595" class="code_block">
</div><div id="l596" class="code_block"><span class="c">%--------------------------------------------------------------------------------------------------</span>
</div><div id="l597" class="code_block"><span class="k">\comment</span><span class="nb">{</span>
</div><div id="l598" class="code_block"><span class="c">% TLS: the \\c does not work properly.</span>
</div><div id="l599" class="code_block">
</div><div id="l600" class="code_block">A format may be spread over several lines. The control
</div><div id="l601" class="code_block">        sequence <span class="nb">{</span><span class="k">\tt</span> <span class="k">\\</span>c<span class="nb">}</span> followed by a @key<span class="nb">{</span>LFD<span class="nb">}</span> will translate to the 
</div><div id="l602" class="code_block">        empty string:  
</div><div id="l603" class="code_block">        <span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l604" class="code_block">        ?- format(&quot;Hello <span class="k">\\</span>c
</div><div id="l605" class="code_block">        world!&quot;, []).
</div><div id="l606" class="code_block">        <span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l607" class="code_block">        <span class="k">\noindent</span>
</div><div id="l608" class="code_block">        will result in <span class="nb">{</span><span class="k">\tt</span> Hello world!<span class="nb">}</span>.
</div><div id="l609" class="code_block"><span class="nb">}</span>
</div><div id="l610" class="code_block"><span class="c">%--------------------------------------------------------------------------------------------------</span>
</div><div id="l611" class="code_block">
</div><div id="l612" class="code_block">The general format of a control sequence is <span class="k">\verb</span>|~NC|.  The character
</div><div id="l613" class="code_block"><span class="nb">{</span><span class="k">\tt</span> C<span class="nb">}</span> determines the type of the control sequence.  <span class="nb">{</span><span class="k">\tt</span> N<span class="nb">}</span> is an
</div><div id="l614" class="code_block">optional numeric argument.  An alternative form of <span class="nb">{</span><span class="k">\tt</span> N<span class="nb">}</span> is <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l615" class="code_block">*<span class="nb">}</span>. <span class="nb">{</span><span class="k">\tt</span> *<span class="nb">}</span> implies that the next argument in <span class="nb">{</span><span class="k">\tt</span> Arguments<span class="nb">}</span> should
</div><div id="l616" class="code_block">be used as a numeric argument in the control sequence.  For example:
</div><div id="l617" class="code_block">
</div><div id="l618" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l619" class="code_block">?- format(&quot;Hello~4cworld!&quot;, [0&#39;x]).
</div><div id="l620" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l621" class="code_block">
</div><div id="l622" class="code_block"><span class="k">\noindent</span>
</div><div id="l623" class="code_block">and
</div><div id="l624" class="code_block">
</div><div id="l625" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l626" class="code_block">?- format(&quot;Hello~*cworld!&quot;, [4,0&#39;x]).
</div><div id="l627" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l628" class="code_block">
</div><div id="l629" class="code_block"><span class="k">\noindent</span>
</div><div id="l630" class="code_block">both produce
</div><div id="l631" class="code_block">
</div><div id="l632" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l633" class="code_block">Helloxxxxworld!
</div><div id="l634" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l635" class="code_block">
</div><div id="l636" class="code_block">The following control sequences are available in XSB.
</div><div id="l637" class="code_block">
</div><div id="l638" class="code_block"><span class="c">%TLS: printf-style integers and floats are not currently supported in XSB!</span>
</div><div id="l639" class="code_block">
</div><div id="l640" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l641" class="code_block">
</div><div id="l642" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~a|
</div><div id="l643" class="code_block">The argument is an atom.  The atom is printed without quoting.  
</div><div id="l644" class="code_block">
</div><div id="l645" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~Nc|
</div><div id="l646" class="code_block">(Print character.)  The argument is a number that will be interpreted as an
</div><div id="l647" class="code_block">ASCII code. <span class="nb">{</span><span class="k">\tt</span> N<span class="nb">}</span> defaults to one and is interpreted as the number of
</div><div id="l648" class="code_block">times to print the character.  
</div><div id="l649" class="code_block">
</div><div id="l650" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~f|
</div><div id="l651" class="code_block">(Print float).  The argument is a float.  The float will be printed out by XSB.
</div><div id="l652" class="code_block">
</div><div id="l653" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~d|
</div><div id="l654" class="code_block">(Print integer).  The argument is an integer, and will be printed out by XSB.
</div><div id="l655" class="code_block">
</div><div id="l656" class="code_block"><span class="c">%-------------------------------------------------------------------------</span>
</div><div id="l657" class="code_block"><span class="k">\comment</span><span class="nb">{</span>
</div><div id="l658" class="code_block">Various shadings don&#39;t work -- TLS
</div><div id="l659" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~Ne|
</div><div id="l660" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~NE|
</div><div id="l661" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~Nf|
</div><div id="l662" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~Ng|
</div><div id="l663" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~NG|
</div><div id="l664" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l665" class="code_block">printf(&quot;<span class="c">%.@var{N}e&quot;, @var{Arg})</span>
</div><div id="l666" class="code_block">printf(&quot;<span class="c">%.@var{N}E&quot;, @var{Arg})</span>
</div><div id="l667" class="code_block">printf(&quot;<span class="c">%.@var{N}f&quot;, @var{Arg})</span>
</div><div id="l668" class="code_block">printf(&quot;<span class="c">%.@var{N}g&quot;, @var{Arg})</span>
</div><div id="l669" class="code_block">printf(&quot;<span class="c">%.@var{N}G&quot;, @var{Arg})</span>
</div><div id="l670" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l671" class="code_block">
</div><div id="l672" class="code_block">If @var<span class="nb">{</span>N<span class="nb">}</span> is not supplied the action defaults to
</div><div id="l673" class="code_block">
</div><div id="l674" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l675" class="code_block">printf(&quot;<span class="c">%e&quot;, @var{Arg})</span>
</div><div id="l676" class="code_block">printf(&quot;<span class="c">%E&quot;, @var{Arg})</span>
</div><div id="l677" class="code_block">printf(&quot;<span class="c">%f&quot;, @var{Arg})</span>
</div><div id="l678" class="code_block">printf(&quot;<span class="c">%g&quot;, @var{Arg})</span>
</div><div id="l679" class="code_block">printf(&quot;<span class="c">%G&quot;, @var{Arg})</span>
</div><div id="l680" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l681" class="code_block">
</div><div id="l682" class="code_block"><span class="k">\item</span> ~@var<span class="nb">{</span>N<span class="nb">}</span>d
</div><div id="l683" class="code_block">(Print decimal.) The argument is an integer. @var<span class="nb">{</span>N<span class="nb">}</span> is interpreted as the
</div><div id="l684" class="code_block">number of digits after the decimal point.  If @var<span class="nb">{</span>N<span class="nb">}</span> is 0 or missing, no
</div><div id="l685" class="code_block">decimal point will be printed.  Example:  
</div><div id="l686" class="code_block">
</div><div id="l687" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l688" class="code_block">?- format(&quot;Hello ~1d world!&quot;, [42]).
</div><div id="l689" class="code_block">?- format(&quot;Hello ~d world!&quot;, [42]).
</div><div id="l690" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l691" class="code_block">
</div><div id="l692" class="code_block"><span class="k">\noindent</span>
</div><div id="l693" class="code_block">will print as
</div><div id="l694" class="code_block">
</div><div id="l695" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l696" class="code_block">Hello 4.2 world!
</div><div id="l697" class="code_block">Hello 42 world!
</div><div id="l698" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l699" class="code_block">
</div><div id="l700" class="code_block"><span class="k">\noindent</span>
</div><div id="l701" class="code_block">respectively.
</div><div id="l702" class="code_block">
</div><div id="l703" class="code_block"><span class="k">\item</span> ~@var<span class="nb">{</span>N<span class="nb">}</span>D
</div><div id="l704" class="code_block">(Print decimal.) The argument is an integer.  Identical to @tt<span class="nb">{</span>~@var<span class="nb">{</span>N<span class="nb">}</span>d<span class="nb">}</span>
</div><div id="l705" class="code_block">except that @tt<span class="nb">{</span>,<span class="nb">}</span> will separate groups of three digits to the left of the
</div><div id="l706" class="code_block">decimal point.  Example:  
</div><div id="l707" class="code_block">
</div><div id="l708" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l709" class="code_block">?- format(&quot;Hello ~1D world!&quot;, [12345]).
</div><div id="l710" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l711" class="code_block">
</div><div id="l712" class="code_block"><span class="k">\noindent</span>
</div><div id="l713" class="code_block">will print as
</div><div id="l714" class="code_block">
</div><div id="l715" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l716" class="code_block">Hello 1,234.5 world!
</div><div id="l717" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l718" class="code_block">
</div><div id="l719" class="code_block"><span class="k">\item</span> ~@var<span class="nb">{</span>N<span class="nb">}</span>r
</div><div id="l720" class="code_block">(Print radix.) The argument is an integer. @var<span class="nb">{</span>N<span class="nb">}</span> is interpreted as a radix.
</div><div id="l721" class="code_block">@var<span class="nb">{</span>N<span class="nb">}</span> should be &gt;= 2 and &lt;= 36.  If @var<span class="nb">{</span>N<span class="nb">}</span> is missing the radix defaults to
</div><div id="l722" class="code_block">8.  The letters @tt<span class="nb">{</span>a-z<span class="nb">}</span> will denote digits larger than 9.  Example:  
</div><div id="l723" class="code_block">
</div><div id="l724" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l725" class="code_block">?- format(&quot;Hello ~2r world!&quot;, [15]).
</div><div id="l726" class="code_block">?- format(&quot;Hello ~16r world!&quot;, [15]).
</div><div id="l727" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l728" class="code_block">
</div><div id="l729" class="code_block"><span class="k">\noindent</span>
</div><div id="l730" class="code_block">will print as
</div><div id="l731" class="code_block">
</div><div id="l732" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l733" class="code_block">Hello 1111 world!
</div><div id="l734" class="code_block">Hello f world!V
</div><div id="l735" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l736" class="code_block">
</div><div id="l737" class="code_block"><span class="k">\noindent</span>
</div><div id="l738" class="code_block">respectively.
</div><div id="l739" class="code_block">
</div><div id="l740" class="code_block"><span class="k">\item</span> ~@var<span class="nb">{</span>N<span class="nb">}</span>R
</div><div id="l741" class="code_block">(Print radix.) The argument is an integer.  Identical to @tt<span class="nb">{</span>~@var<span class="nb">{</span>N<span class="nb">}</span>r<span class="nb">}</span> except
</div><div id="l742" class="code_block">that the letters @tt<span class="nb">{</span>A-Z<span class="nb">}</span> will denote digits larger than 9.  Example:  
</div><div id="l743" class="code_block">
</div><div id="l744" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l745" class="code_block">?- format(&quot;Hello ~16R world!&quot;, [15]).
</div><div id="l746" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l747" class="code_block">
</div><div id="l748" class="code_block"><span class="k">\noindent</span>
</div><div id="l749" class="code_block">will print as
</div><div id="l750" class="code_block">
</div><div id="l751" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l752" class="code_block">Hello F world!
</div><div id="l753" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l754" class="code_block">
</div><div id="l755" class="code_block"><span class="nb">}</span>
</div><div id="l756" class="code_block"><span class="c">%-------------------------------------------------------------------------</span>
</div><div id="l757" class="code_block">
</div><div id="l758" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~Ns|
</div><div id="l759" class="code_block">(Print string.) The argument is a list of ASCII codes.  Exactly <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l760" class="code_block">N<span class="nb">}</span> characters will be printed. <span class="nb">{</span><span class="k">\tt</span> N<span class="nb">}</span> defaults to the length of the
</div><div id="l761" class="code_block">string.  Example:
</div><div id="l762" class="code_block">
</div><div id="l763" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l764" class="code_block">?- format(&quot;Hello ~4s ~4s!&quot;, [&quot;new&quot;,&quot;world&quot;]).
</div><div id="l765" class="code_block">?- format(&quot;Hello ~s world!&quot;, [&quot;new&quot;]).
</div><div id="l766" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l767" class="code_block">
</div><div id="l768" class="code_block"><span class="k">\noindent</span>
</div><div id="l769" class="code_block">will print as
</div><div id="l770" class="code_block">
</div><div id="l771" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l772" class="code_block">Hello new worl!
</div><div id="l773" class="code_block">Hello new world!
</div><div id="l774" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l775" class="code_block">
</div><div id="l776" class="code_block"><span class="k">\noindent</span>
</div><div id="l777" class="code_block">respectively.
</div><div id="l778" class="code_block">
</div><div id="l779" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~i|
</div><div id="l780" class="code_block">(Ignore argument.) The argument may be of any type.  The argument will be
</div><div id="l781" class="code_block">ignored.  Example:  
</div><div id="l782" class="code_block">
</div><div id="l783" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l784" class="code_block">?- format(&quot;Hello ~i~s world!&quot;, [&quot;old&quot;,&quot;new&quot;]).
</div><div id="l785" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l786" class="code_block">
</div><div id="l787" class="code_block"><span class="k">\noindent</span>
</div><div id="l788" class="code_block">will print as
</div><div id="l789" class="code_block">
</div><div id="l790" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l791" class="code_block">Hello new world!
</div><div id="l792" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l793" class="code_block">
</div><div id="l794" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~k|
</div><div id="l795" class="code_block">(Print canonical.) The argument may be of any type.  The argument will be
</div><div id="l796" class="code_block">passed to <span class="nb">{</span><span class="k">\tt</span> write<span class="k">\_canonical</span>/2<span class="nb">}</span> ).  Example:  
</div><div id="l797" class="code_block">
</div><div id="l798" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l799" class="code_block">?- format(&quot;Hello ~k world!&quot;, a+b+c).
</div><div id="l800" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l801" class="code_block">
</div><div id="l802" class="code_block"><span class="k">\noindent</span>
</div><div id="l803" class="code_block">will print as
</div><div id="l804" class="code_block">
</div><div id="l805" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l806" class="code_block">Hello +(+(a,b),c) world!
</div><div id="l807" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l808" class="code_block">
</div><div id="l809" class="code_block"><span class="c">%------------------------------------------------------------------------------------------</span>
</div><div id="l810" class="code_block"><span class="k">\comment</span><span class="nb">{</span>
</div><div id="l811" class="code_block"><span class="k">\item</span> ~p
</div><div id="l812" class="code_block">(print.) The argument may be of any type.  The argument will be passed to
</div><div id="l813" class="code_block"><span class="nb">{</span><span class="k">\tt</span> print/2<span class="nb">}</span>.  Example:
</div><div id="l814" class="code_block">
</div><div id="l815" class="code_block"><span class="k">\noindent</span>
</div><div id="l816" class="code_block">supposing the user has defined the predicate
</div><div id="l817" class="code_block">
</div><div id="l818" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l819" class="code_block">portray([X|Y]) :- print(cons(X,Y)).
</div><div id="l820" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l821" class="code_block">
</div><div id="l822" class="code_block"><span class="k">\noindent</span>
</div><div id="l823" class="code_block">then
</div><div id="l824" class="code_block">
</div><div id="l825" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l826" class="code_block">?- format(&quot;Hello ~p world!&quot;, [[a,b,c]]).
</div><div id="l827" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l828" class="code_block">
</div><div id="l829" class="code_block"><span class="k">\noindent</span>
</div><div id="l830" class="code_block">will print as
</div><div id="l831" class="code_block">
</div><div id="l832" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l833" class="code_block">Hello cons(a,cons(b,cons(c,[]))) world!
</div><div id="l834" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l835" class="code_block"><span class="nb">}</span>
</div><div id="l836" class="code_block"><span class="c">%------------------------------------------------------------------------------------------</span>
</div><div id="l837" class="code_block">
</div><div id="l838" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~q|
</div><div id="l839" class="code_block">(Print quoted.) The argument may be of any type.  The argument will be
</div><div id="l840" class="code_block">passed to <span class="nb">{</span><span class="k">\tt</span> writeq/2<span class="nb">}</span>.  Example:
</div><div id="l841" class="code_block">
</div><div id="l842" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l843" class="code_block">?- format(&quot;Hello ~q world!&quot;, [[&#39;A&#39;,&#39;B&#39;]]).
</div><div id="l844" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l845" class="code_block">
</div><div id="l846" class="code_block"><span class="k">\noindent</span>
</div><div id="l847" class="code_block">will print as
</div><div id="l848" class="code_block">
</div><div id="l849" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l850" class="code_block">Hello [&#39;A&#39;,&#39;B&#39;] world!
</div><div id="l851" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l852" class="code_block">
</div><div id="l853" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~w|
</div><div id="l854" class="code_block">(write.) The argument may be of any type.  The argument will be passed
</div><div id="l855" class="code_block">to <span class="nb">{</span><span class="k">\tt</span> write/2<span class="nb">}</span>.  Example:
</div><div id="l856" class="code_block">
</div><div id="l857" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l858" class="code_block">?- format(&quot;Hello ~w world!&quot;, [[&#39;A&#39;,&#39;B&#39;]]).
</div><div id="l859" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l860" class="code_block">
</div><div id="l861" class="code_block"><span class="k">\noindent</span>
</div><div id="l862" class="code_block">will print as
</div><div id="l863" class="code_block">
</div><div id="l864" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l865" class="code_block">Hello [A,B] world!
</div><div id="l866" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l867" class="code_block">
</div><div id="l868" class="code_block"><span class="k">\item</span> <span class="k">\verb</span>|~Nn|
</div><div id="l869" class="code_block">(Print newline.) Print <span class="nb">{</span><span class="k">\tt</span> N<span class="nb">}</span> newlines. <span class="nb">{</span><span class="k">\tt</span> N<span class="nb">}</span> defaults to 1.
</div><div id="l870" class="code_block">Example:
</div><div id="l871" class="code_block">
</div><div id="l872" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l873" class="code_block">?- format(&quot;Hello ~n world!&quot;, []).
</div><div id="l874" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l875" class="code_block">
</div><div id="l876" class="code_block"><span class="k">\noindent</span>
</div><div id="l877" class="code_block">will print as
</div><div id="l878" class="code_block">
</div><div id="l879" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l880" class="code_block">Hello
</div><div id="l881" class="code_block"> world!
</div><div id="l882" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l883" class="code_block">
</div><div id="l884" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l885" class="code_block">
</div><div id="l886" class="code_block"><span class="c">%-------------------------------------------------------------------------------------------------------</span>
</div><div id="l887" class="code_block"><span class="k">\comment</span><span class="nb">{</span>
</div><div id="l888" class="code_block"><span class="k">\item</span> ~N
</div><div id="l889" class="code_block">(Fresh line.) Print a newline, if not already at the beginning of a line.
</div><div id="l890" class="code_block">
</div><div id="l891" class="code_block"><span class="c">% TLS: dont keep track of line_position.</span>
</div><div id="l892" class="code_block">The following control sequences are also available for compatibility,
</div><div id="l893" class="code_block">but do not perform any useful functions.
</div><div id="l894" class="code_block">
</div><div id="l895" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l896" class="code_block"><span class="k">\item</span> ~@var<span class="nb">{</span>N<span class="nb">}</span>|
</div><div id="l897" class="code_block">(Set tab.) Set a tab stop at position @var<span class="nb">{</span>N<span class="nb">}</span>, where @var<span class="nb">{</span>N<span class="nb">}</span> defaults to
</div><div id="l898" class="code_block">the current position, and advance the current position there.
</div><div id="l899" class="code_block">
</div><div id="l900" class="code_block"><span class="k">\item</span> ~@var<span class="nb">{</span>N<span class="nb">}</span>+
</div><div id="l901" class="code_block">(Advance tab.) Set a tab stop at @var<span class="nb">{</span>N<span class="nb">}</span> positions past the current
</div><div id="l902" class="code_block">position, where @var<span class="nb">{</span>N<span class="nb">}</span> defaults to 8, and advance the current position
</div><div id="l903" class="code_block">there.
</div><div id="l904" class="code_block">
</div><div id="l905" class="code_block"><span class="k">\item</span> ~@var<span class="nb">{</span>N<span class="nb">}</span>t
</div><div id="l906" class="code_block">(Set fill character.) Set the fill character to be used in the next
</div><div id="l907" class="code_block">position movement to @var<span class="nb">{</span>N<span class="nb">}</span>, where @var<span class="nb">{</span>N<span class="nb">}</span> defaults to @key<span class="nb">{</span>SPC<span class="nb">}</span>.
</div><div id="l908" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l909" class="code_block"><span class="nb">}</span>
</div><div id="l910" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l911" class="code_block"><span class="c">%-------------------------------------------------------------------------------------------------------</span>
</div><div id="l912" class="code_block">
</div><div id="l913" class="code_block"><span class="c">%-------------------------------------------------------------------------------------</span>
</div><div id="l914" class="code_block"><span class="k">\comment</span><span class="nb">{</span>
</div><div id="l915" class="code_block">
</div><div id="l916" class="code_block"><span class="k">\section</span><span class="nb">{</span>Lower-Level I/O<span class="nb">}</span>
</div><div id="l917" class="code_block"><span class="k">\label</span><span class="nb">{</span>sec-low-level-io<span class="nb">}</span>
</div><div id="l918" class="code_block"><span class="c">%======================</span>
</div><div id="l919" class="code_block">
</div><div id="l920" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l921" class="code_block">
</div><div id="l922" class="code_block"><span class="c">%\ourmoditem{current\_input\_port(-IOport)}{curr\_sym} \index{\texttt{current\_input\_port/}}</span>
</div><div id="l923" class="code_block"><span class="c">%   See {\tt current\_output\_port/1}.</span>
</div><div id="l924" class="code_block"><span class="c">%\ourmoditem{current\_output\_port(-IOport)}{curr\_sym} \index{\texttt{current\_output\_port/}}</span>
</div><div id="l925" class="code_block"><span class="c">%   The above two predicates instantiate {\tt IOport} to the XSB I/O port</span>
</div><div id="l926" class="code_block"><span class="c">%   for the current user input and output ({\it i.e.}, the things </span>
</div><div id="l927" class="code_block"><span class="c">%   that are manipulated through {\tt see/seen} and {\tt tell/told} predicates).</span>
</div><div id="l928" class="code_block"><span class="c">%   Once the I/O port is obtained, it is possible to safely use the</span>
</div><div id="l929" class="code_block"><span class="c">%   lower-level I/O predicates described below interchangeably with stream</span>
</div><div id="l930" class="code_block"><span class="c">%   I/O. </span>
</div><div id="l931" class="code_block">    
</div><div id="l932" class="code_block"><span class="c">%\ourmoditem{file\_open(+FileName,+Mode,-IOport)}{file\_io} \index{\texttt{file\_open/3}}</span>
</div><div id="l933" class="code_block"><span class="c">%    Opens a file with name {\tt FileName} to be accessed</span>
</div><div id="l934" class="code_block"><span class="c">%    in mode {\tt Mode} and returns a file-descriptor in {\tt IOport} that</span>
</div><div id="l935" class="code_block"><span class="c">%    can be used to access the file.  If {\tt Mode} is atom ``{\tt r}&#39;&#39;, the</span>
</div><div id="l936" class="code_block"><span class="c">%    the file is opened for reading; if it is ``{\tt w}&#39;&#39;, the file is</span>
</div><div id="l937" class="code_block"><span class="c">%    opened for writing; if it is ``{\tt a}&#39;&#39;, the file is opened for</span>
</div><div id="l938" class="code_block"><span class="c">%    appending.  If {\tt Mode} is ``{\tt sr}&#39;&#39;, then the string making</span>
</div><div id="l939" class="code_block"><span class="c">%    up the atom {\tt FileName} is treated as the contents of the file, and</span>
</div><div id="l940" class="code_block"><span class="c">%    a descriptor is returned that allows ``file&#39;&#39; access to that string.</span>
</div><div id="l941" class="code_block"><span class="c">%    This is how one can use XSB&#39;s term I/O routines to build terms from</span>
</div><div id="l942" class="code_block"><span class="c">%    atoms. Mode ``{\tt sw}&#39;&#39; is reserved for ``open string for writing,&#39;&#39;</span>
</div><div id="l943" class="code_block"><span class="c">%    but this has not been implemented as of yet.</span>
</div><div id="l944" class="code_block">
</div><div id="l945" class="code_block"><span class="c">%    The old-style mode specification, 0 ({\tt OREAD}), 1 ({\tt OWRITE}), 2</span>
</div><div id="l946" class="code_block"><span class="c">%    ({\tt OAPPEND}), or 3 ({\tt OSTRING}), is also supported.</span>
</div><div id="l947" class="code_block"><span class="c">%</span>
</div><div id="l948" class="code_block"><span class="c">%\ourmoditem{file\_close(+IOport)}{file\_io}\index{\texttt{file\_close/1}}</span>
</div><div id="l949" class="code_block"><span class="c">%    Closes the file (or string) for descriptor {\tt IOport}.</span>
</div><div id="l950" class="code_block">
</div><div id="l951" class="code_block"><span class="c">%\ourmoditem{ioport2iostream(+IOport, -Stream)}{file\_io}</span>
</div><div id="l952" class="code_block"><span class="c">%\index{\texttt{ioport2iostream/2}}</span>
</div><div id="l953" class="code_block"><span class="c">%Takes a valid open I/O port and returns an I/O stream. This stream can then</span>
</div><div id="l954" class="code_block"><span class="c">%be used by the standard I/O predicates, like see/1, tell/1, read/1, etc.</span>
</div><div id="l955" class="code_block"><span class="c">%The stream returns by this predicate is identified by a newly created atom,</span>
</div><div id="l956" class="code_block"><span class="c">%such as \verb|_$newstream_#123|. </span>
</div><div id="l957" class="code_block">
</div><div id="l958" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>file<span class="k">\_write</span>(+IOport,+Term)<span class="nb">}{</span>xsb<span class="k">\_writ</span><span class="nb">}</span>
</div><div id="l959" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>file<span class="k">\_write</span>/2<span class="nb">}}</span>
</div><div id="l960" class="code_block">    Writes the term <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span> to the file (or string) with descriptor <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l961" class="code_block">    IOport<span class="nb">}</span>.
</div><div id="l962" class="code_block">
</div><div id="l963" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>file<span class="k">\_read</span>(+IOport,-Term)<span class="nb">}{</span>xsb<span class="k">\_read</span><span class="nb">}</span>
</div><div id="l964" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>file<span class="k">\_read</span>/2<span class="nb">}}</span>
</div><div id="l965" class="code_block">    Reads a term from the file (or string) with descriptor <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l966" class="code_block">    IOport<span class="nb">}</span> into <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span>.  Note that the term must be terminated
</div><div id="l967" class="code_block">    with a period (.) (whether it appears in a file or in a string.)
</div><div id="l968" class="code_block">
</div><div id="l969" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>file<span class="k">\_read</span>(+IOport,-Term,-Vars)<span class="nb">}{</span>xsb<span class="k">\_read</span><span class="nb">}</span>
</div><div id="l970" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>file<span class="k">\_read</span>/3<span class="nb">}}</span>
</div><div id="l971" class="code_block">    Reads a term from the file (or string) with descriptor <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l972" class="code_block">    IOport<span class="nb">}</span> into <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span>, and returns in <span class="nb">{</span><span class="k">\tt</span> Vars<span class="nb">}</span> an open-tailed list of
</div><div id="l973" class="code_block">    pairs of names of variables and the variables themselves that
</div><div id="l974" class="code_block">    appear in Term.  For example, reading a term <span class="nb">{</span><span class="k">\tt</span> f(a,X,Y,X)<span class="nb">}</span>
</div><div id="l975" class="code_block">    would result in <span class="nb">{</span><span class="k">\tt</span> term<span class="nb">}</span> being bound to <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l976" class="code_block">    f(a,<span class="k">\_</span>25,<span class="k">\_</span>26,<span class="k">\_</span>25)<span class="nb">}</span> (for some internal variables) and <span class="nb">{</span><span class="k">\tt</span> Vars<span class="nb">}</span>
</div><div id="l977" class="code_block">    being bound to <span class="nb">{</span>[vv(&#39;X&#39;,<span class="k">\_</span>25) vv(&#39;Y&#39;,<span class="k">\_</span>26) <span class="s">$</span><span class="nv">\mid</span><span class="s">$</span> <span class="k">\_</span>83]<span class="nb">}</span>.  Note that the
</div><div id="l978" class="code_block">    pairing functor symbol is <span class="nb">{</span><span class="k">\tt</span> vv/2<span class="nb">}</span> and it must be imported from
</div><div id="l979" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> xsb<span class="k">\_read</span><span class="nb">}</span> along with this read predicate.  Also note that 
</div><div id="l980" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> Vars<span class="nb">}</span> is not a proper list, but has a free variable instead 
</div><div id="l981" class="code_block">    of [] at its end.
</div><div id="l982" class="code_block">
</div><div id="l983" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>file<span class="k">\_read\_canonical</span>(+IOport,-Term,-Psc)<span class="nb">}{</span>machine<span class="nb">}</span>
</div><div id="l984" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>file<span class="k">\_read\_canonical</span>/3<span class="nb">}}</span>
</div><div id="l985" class="code_block">    Reads a term that is in canonical format from the the I/O port
</div><div id="l986" class="code_block">    indicated by <span class="nb">{</span><span class="k">\tt</span> IOport<span class="nb">}</span> (as returned by <span class="nb">{</span><span class="k">\tt</span> file<span class="k">\_open</span>/3<span class="nb">}</span> or
</div><div id="l987" class="code_block">    by <span class="nb">{</span><span class="k">\tt</span> stat<span class="k">\_flag</span>(10,IOport))<span class="nb">}</span>, and returns it in <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span>.
</div><div id="l988" class="code_block">    It also returns (in <span class="nb">{</span><span class="k">\tt</span> Psc<span class="nb">}</span>) the psc address of the main functor
</div><div id="l989" class="code_block">    symbol of the term, if it is the same as that of the previously
</div><div id="l990" class="code_block">    read term, and the current term is a ground (non 0-ary) fact.
</div><div id="l991" class="code_block">    (This is used for efficiency in the implementation of <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l992" class="code_block">    load<span class="k">\_dync</span>/1<span class="nb">}</span>).  Otherwise <span class="nb">{</span><span class="k">\tt</span> Psc<span class="nb">}</span> is set to 0.  To initialize
</div><div id="l993" class="code_block">    its previous psc value to zero, this predicate can be called with
</div><div id="l994" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> IOport<span class="nb">}</span> of -1000.
</div><div id="l995" class="code_block">
</div><div id="l996" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>fget<span class="k">\_line</span>(+Str,-Inlist,-Next)<span class="nb">}{</span>scrptutl<span class="nb">}</span>
</div><div id="l997" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>fget<span class="k">\_line</span>/3<span class="nb">}}</span>
</div><div id="l998" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> fget<span class="k">\_line</span>/3<span class="nb">}</span> reads one line from the input stream <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span> and
</div><div id="l999" class="code_block">    unifies <span class="nb">{</span><span class="k">\tt</span> Inlist<span class="nb">}</span> to the list of ASCII integers representing the
</div><div id="l1000" class="code_block">    characters in the line, and <span class="nb">{</span><span class="k">\tt</span> Next<span class="nb">}</span> to the line terminator, either
</div><div id="l1001" class="code_block">    a newline (<span class="nb">{</span><span class="k">\tt</span> 10<span class="nb">}</span>) or EOF (<span class="nb">{</span><span class="k">\tt</span>-1<span class="nb">}</span>).
</div><div id="l1002" class="code_block">    
</div><div id="l1003" class="code_block">    This predicate is obsolete and
</div><div id="l1004" class="code_block">    <span class="k">\verb</span>|file<span class="nb">_</span>read<span class="nb">_</span>line<span class="nb">_</span>list| should be used instead.
</div><div id="l1005" class="code_block">
</div><div id="l1006" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1007" class="code_block">
</div><div id="l1008" class="code_block"><span class="nb">}</span>
</div><div id="l1009" class="code_block"><span class="c">%-------------------------------------------------------------------------------------</span>
</div><div id="l1010" class="code_block">
</div><div id="l1011" class="code_block"><span class="c">%%$ -- so that font-lock-mode works in Emacs</span>
</div><div id="l1012" class="code_block">
</div><div id="l1013" class="code_block"><span class="k">\section</span><span class="nb">{</span>String Manipulation<span class="nb">}</span>
</div><div id="l1014" class="code_block"><span class="k">\label</span><span class="nb">{</span>sec-strings<span class="nb">}</span>
</div><div id="l1015" class="code_block">
</div><div id="l1016" class="code_block">XSB has a number of powerful predicates that simplify the job of
</div><div id="l1017" class="code_block">string manipulation. These predicates are especially powerful when
</div><div id="l1018" class="code_block">they are combined with pattern-matching facilities provided by the
</div><div id="l1019" class="code_block"><span class="nb">{</span><span class="k">\tt</span> regmatch<span class="nb">}</span> package described in
</div><div id="l1020" class="code_block">Chapter~<span class="k">\ref</span><span class="nb">{</span>chap-posix<span class="nb">}</span>~<span class="k">\footnote</span><span class="nb">{</span>Not all string
</div><div id="l1021" class="code_block">  manipulation predicates have been made thread-safe in <span class="k">\version</span><span class="nb">{}</span>.<span class="nb">}</span>.
</div><div id="l1022" class="code_block">
</div><div id="l1023" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1024" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>str<span class="k">\_sub</span>(+Sub, +Str, ?Pos)<span class="nb">}{</span>string<span class="nb">}</span>
</div><div id="l1025" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>str<span class="k">\_sub</span>/3<span class="nb">}}</span>
</div><div id="l1026" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>str<span class="k">\_sub</span>/2<span class="nb">}}</span>
</div><div id="l1027" class="code_block">
</div><div id="l1028" class="code_block">Succeeds if <span class="nb">{</span><span class="k">\tt</span> Sub<span class="nb">}</span> is a substring of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span>. In that case, <span class="nb">{</span><span class="k">\tt</span> Pos<span class="nb">}</span>
</div><div id="l1029" class="code_block">unifies with the position where the match occurred. Positions start
</div><div id="l1030" class="code_block">from 0. <span class="nb">{</span><span class="k">\tt</span> str<span class="k">\_sub</span>/2<span class="nb">}</span> is also available, which is equivalent
</div><div id="l1031" class="code_block">to having <span class="nb">{</span><span class="k">\tt</span> <span class="k">\_</span><span class="nb">}</span> in the third argument of <span class="nb">{</span><span class="k">\tt</span> str<span class="k">\_sub</span>/3<span class="nb">}</span>.
</div><div id="l1032" class="code_block">
</div><div id="l1033" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>str<span class="k">\_match</span>(+Sub, +Str, +Direction, ?Beg, ?End)<span class="nb">}{</span>string<span class="nb">}</span>
</div><div id="l1034" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>str<span class="k">\_match</span>/5<span class="nb">}}</span>
</div><div id="l1035" class="code_block">
</div><div id="l1036" class="code_block">This is an enhanced version of the previous predicate.
</div><div id="l1037" class="code_block"><span class="nb">{</span><span class="k">\tt</span> Direction<span class="nb">}</span> can be <span class="nb">{</span><span class="k">\tt</span> forward<span class="nb">}</span> or <span class="nb">{</span><span class="k">\tt</span> reverse<span class="nb">}</span> (or any abbreviation
</div><div id="l1038" class="code_block">of these). If <span class="nb">{</span><span class="k">\tt</span> forward<span class="nb">}</span>, the predicate finds the first match of <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1039" class="code_block">  Sub<span class="nb">}</span> from the beginning of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span>. If <span class="nb">{</span><span class="k">\tt</span> reverse<span class="nb">}</span>, it finds the
</div><div id="l1040" class="code_block">first match from the end of the string (<span class="nb">{</span><span class="k">\it</span> i.e.<span class="nb">}</span>, the last match of <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1041" class="code_block">  Sub<span class="nb">}</span> from the beginning of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span>). <span class="nb">{</span><span class="k">\tt</span> Beg<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> End<span class="nb">}</span> must be
</div><div id="l1042" class="code_block">integers or unbound variables. (It is possible that one is bound and
</div><div id="l1043" class="code_block">another is not.)
</div><div id="l1044" class="code_block"><span class="nb">{</span><span class="k">\tt</span> Beg<span class="nb">}</span> unifies with the offset of the first character where <span class="nb">{</span><span class="k">\tt</span> Sub<span class="nb">}</span>
</div><div id="l1045" class="code_block">matched, and <span class="nb">{</span><span class="k">\tt</span> End<span class="nb">}</span> unifies with the offset of the next character to the
</div><div id="l1046" class="code_block">right of <span class="nb">{</span><span class="k">\tt</span> Sub<span class="nb">}</span> (such a character might not exist, but the offset is
</div><div id="l1047" class="code_block">still defined). Offsets start from 0.
</div><div id="l1048" class="code_block">
</div><div id="l1049" class="code_block">Both <span class="nb">{</span><span class="k">\tt</span> Beg<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> End<span class="nb">}</span> can be bound to negative integers.
</div><div id="l1050" class="code_block">In this case, the value represents the offset from the <span class="k">\emph</span><span class="nb">{</span>second<span class="nb">}</span>
</div><div id="l1051" class="code_block">character past the end of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span>. Thus <span class="nb">{</span><span class="k">\tt</span> -1<span class="nb">}</span> represents the character
</div><div id="l1052" class="code_block">next to the end of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span> and can be used to check where the end of <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1053" class="code_block">  Sub<span class="nb">}</span>  matches in <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span>. In the following examples
</div><div id="l1054" class="code_block"><span class="c">%%</span>
</div><div id="l1055" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1056" class="code_block">    ?- string<span class="nb">_</span>match(Sub,Str,forw,X,-1).  
</div><div id="l1057" class="code_block">    ?- string<span class="nb">_</span>match(Sub,Str,rev,X,-1).  
</div><div id="l1058" class="code_block">    ?- string<span class="nb">_</span>match(Sub,Str,forw,0,X).  
</div><div id="l1059" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1060" class="code_block"><span class="c">%%</span>
</div><div id="l1061" class="code_block">the first checks if the <span class="k">\emph</span><span class="nb">{</span>first<span class="nb">}</span> match of <span class="nb">{</span><span class="k">\tt</span> Sub<span class="nb">}</span> from the beginning
</div><div id="l1062" class="code_block">of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span> is a suffix of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span> (because <span class="nb">{</span><span class="k">\tt</span> End<span class="nb">}</span> represents the
</div><div id="l1063" class="code_block">character next to the last character in <span class="nb">{</span><span class="k">\tt</span> Sub<span class="nb">}</span>, so <span class="nb">{</span><span class="k">\tt</span> End=-1<span class="nb">}</span> means
</div><div id="l1064" class="code_block">that the last characters of <span class="nb">{</span><span class="k">\tt</span> Sub<span class="nb">}</span> and of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span> occupy the same
</div><div id="l1065" class="code_block">position). If so, <span class="nb">{</span><span class="k">\tt</span> X<span class="nb">}</span> is bound to the offset (from the end of <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1066" class="code_block">  Str<span class="nb">}</span>) of the first character of <span class="nb">{</span><span class="k">\tt</span> Sub<span class="nb">}</span>. The second example checks if
</div><div id="l1067" class="code_block">the <span class="k">\emph</span><span class="nb">{</span>last<span class="nb">}</span> match of <span class="nb">{</span><span class="k">\tt</span> Sub<span class="nb">}</span> in <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span> is a suffix of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span>
</div><div id="l1068" class="code_block">and binds <span class="nb">{</span><span class="k">\tt</span> X<span class="nb">}</span> to the offset of the beginning of that match (counted
</div><div id="l1069" class="code_block">from the beginning of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span>).  The last example checks if the first
</div><div id="l1070" class="code_block">match of <span class="nb">{</span><span class="k">\tt</span> Sub<span class="nb">}</span> is a prefix of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span>. If so, <span class="nb">{</span><span class="k">\tt</span> X<span class="nb">}</span> is bound to the
</div><div id="l1071" class="code_block">offset (from the beginning of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span>) of the last character of <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1072" class="code_block">  Sub<span class="nb">}</span>.
</div><div id="l1073" class="code_block">
</div><div id="l1074" class="code_block"><span class="c">%-----------------------------------------------------------------------</span>
</div><div id="l1075" class="code_block">
</div><div id="l1076" class="code_block"><span class="k">\comment</span><span class="nb">{</span>
</div><div id="l1077" class="code_block"><span class="c">% taken out -- most people should be using atom_length/2</span>
</div><div id="l1078" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>str<span class="k">\_length</span>(+Str, ?Result)<span class="nb">}{</span>string<span class="nb">}</span>
</div><div id="l1079" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>str<span class="k">\_length</span>/2<span class="nb">}}</span>
</div><div id="l1080" class="code_block">
</div><div id="l1081" class="code_block">Unifies the <span class="nb">{</span><span class="k">\tt</span> Result<span class="nb">}</span>  with the length of <span class="nb">{</span><span class="k">\tt</span> Str<span class="nb">}</span>.
</div><div id="l1082" class="code_block"><span class="nb">}</span>
</div><div id="l1083" class="code_block">
</div><div id="l1084" class="code_block"><span class="c">%%</span>
</div><div id="l1085" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>substring(+String, +BeginOffset, +EndOffset, -Result)<span class="nb">}{</span>string<span class="nb">}</span>
</div><div id="l1086" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>substring/4<span class="nb">}}</span>
</div><div id="l1087" class="code_block"><span class="c">%%</span>
</div><div id="l1088" class="code_block"><span class="nb">{</span><span class="k">\tt</span> String<span class="nb">}</span> can be an atom or a list of characters, and the offsets must
</div><div id="l1089" class="code_block">be integers.  If <span class="nb">{</span><span class="k">\tt</span> EndOffset<span class="nb">}</span> is negative, endof(<span class="nb">{</span><span class="k">\tt</span> String<span class="nb">}</span>)+<span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1090" class="code_block">  EndOffset<span class="nb">}</span>+1 is assumed. Thus, <span class="nb">{</span><span class="k">\tt</span> -1<span class="nb">}</span> means end of string.  If <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1091" class="code_block">  BeginOffset<span class="nb">}</span> is less than 0, then 0 is assumed; if it is greater than the
</div><div id="l1092" class="code_block">length of the string, then string end is assumed. If <span class="nb">{</span><span class="k">\tt</span> EndOffset<span class="nb">}</span> is
</div><div id="l1093" class="code_block">non-negative, but is less than <span class="nb">{</span><span class="k">\tt</span> BeginOffset<span class="nb">}</span>, then empty string is
</div><div id="l1094" class="code_block">returned.
</div><div id="l1095" class="code_block">
</div><div id="l1096" class="code_block">Offsets start from 0.
</div><div id="l1097" class="code_block">
</div><div id="l1098" class="code_block">The result returned in the fourth argument is a string, if <span class="nb">{</span><span class="k">\tt</span> String<span class="nb">}</span> is
</div><div id="l1099" class="code_block">an atom, or a list of characters, if so is <span class="nb">{</span><span class="k">\tt</span> String<span class="nb">}</span>.
</div><div id="l1100" class="code_block">
</div><div id="l1101" class="code_block">The <span class="k">\verb</span>|substring/4| predicate always succeeds (unless there is an error,
</div><div id="l1102" class="code_block">such as wrong argument type).
</div><div id="l1103" class="code_block">
</div><div id="l1104" class="code_block">Here are some examples: 
</div><div id="l1105" class="code_block"><span class="c">%%</span>
</div><div id="l1106" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1107" class="code_block">| ?- substring(&#39;abcdefg&#39;, 3, 5, L).
</div><div id="l1108" class="code_block">
</div><div id="l1109" class="code_block">L = de
</div><div id="l1110" class="code_block">
</div><div id="l1111" class="code_block">| ?- substring(&quot;abcdefg&quot;, 4, -1, L).
</div><div id="l1112" class="code_block">
</div><div id="l1113" class="code_block">L = [101,102]
</div><div id="l1114" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1115" class="code_block"><span class="c">%%</span>
</div><div id="l1116" class="code_block">(<span class="nb">{</span><span class="k">\it</span> i.e.<span class="nb">}</span>, L = ef represented using ASCII codes).
</div><div id="l1117" class="code_block">
</div><div id="l1118" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>string<span class="k">\_substitute</span>(+InpStr, +SubstrList, +SubstitutionList, -OutStr)<span class="nb">}{</span>string<span class="nb">}</span>
</div><div id="l1119" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>string<span class="k">\_substitute</span>/4<span class="nb">}}</span>
</div><div id="l1120" class="code_block">
</div><div id="l1121" class="code_block"><span class="nb">{</span><span class="k">\tt</span> InputStr<span class="nb">}</span> can an atom or a list of characters.  <span class="nb">{</span><span class="k">\tt</span> SubstrList<span class="nb">}</span> must
</div><div id="l1122" class="code_block">be a list of terms of the form <span class="nb">{</span><span class="k">\tt</span> s(BegOffset, EndOffset)<span class="nb">}</span>, where the
</div><div id="l1123" class="code_block">name of the functor is immaterial.  The meaning of the offsets is the same
</div><div id="l1124" class="code_block">as for <span class="nb">{</span><span class="k">\tt</span> substring/4<span class="nb">}</span>. (In particular, negative offsets represent
</div><div id="l1125" class="code_block">offsets from the first character past the end of <span class="nb">{</span><span class="k">\tt</span> String<span class="nb">}</span>.)  Each such
</div><div id="l1126" class="code_block">term specifies a substring (between <span class="nb">{</span><span class="k">\tt</span> BegOffset<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> EndOffset<span class="nb">}</span>;
</div><div id="l1127" class="code_block">negative <span class="nb">{</span><span class="k">\tt</span> EndOffset<span class="nb">}</span> stands for the end of string) to be replaced.
</div><div id="l1128" class="code_block"><span class="nb">{</span><span class="k">\tt</span> SubstitutionList<span class="nb">}</span> must be a list of atoms or character lists.
</div><div id="l1129" class="code_block">
</div><div id="l1130" class="code_block">Offsets start from 0, as in C/Java.
</div><div id="l1131" class="code_block">
</div><div id="l1132" class="code_block">This predicate replaces the substrings specified in <span class="nb">{</span><span class="k">\tt</span> SubstrList<span class="nb">}</span> with
</div><div id="l1133" class="code_block">the corresponding strings from <span class="nb">{</span><span class="k">\tt</span> SubstitutionList<span class="nb">}</span>.  The result is
</div><div id="l1134" class="code_block">returned in <span class="nb">{</span><span class="k">\tt</span> OutStr<span class="nb">}</span>. <span class="nb">{</span><span class="k">\tt</span> OutStr<span class="nb">}</span> is a list of characters, if so is
</div><div id="l1135" class="code_block"><span class="nb">{</span><span class="k">\tt</span> InputStr<span class="nb">}</span>; otherwise, it is an atom.
</div><div id="l1136" class="code_block">
</div><div id="l1137" class="code_block">If <span class="nb">{</span><span class="k">\tt</span> SubstitutionList<span class="nb">}</span> is shorter than <span class="nb">{</span><span class="k">\tt</span> SubstrList<span class="nb">}</span> then the last
</div><div id="l1138" class="code_block">string in <span class="nb">{</span><span class="k">\tt</span> SubstitutionList<span class="nb">}</span> is used for substituting the extra
</div><div id="l1139" class="code_block">substrings specified in <span class="nb">{</span><span class="k">\tt</span> SubstitutionList<span class="nb">}</span>. As a special case, this
</div><div id="l1140" class="code_block">makes it possible to replace all specified substrings with a single string.
</div><div id="l1141" class="code_block">
</div><div id="l1142" class="code_block">As in the case of <span class="nb">{</span><span class="k">\tt</span> re<span class="k">\_substring</span>/4<span class="nb">}</span>, if <span class="nb">{</span><span class="k">\tt</span> OutStr<span class="nb">}</span> is an atom, it is
</div><div id="l1143" class="code_block">not interned.  The user should either intern this string or convert it into
</div><div id="l1144" class="code_block">a list, as explained previously.
</div><div id="l1145" class="code_block">
</div><div id="l1146" class="code_block">The <span class="k">\verb</span>|string<span class="nb">_</span>substitute/4| predicate always succeeds.
</div><div id="l1147" class="code_block">
</div><div id="l1148" class="code_block">Here are some examples:
</div><div id="l1149" class="code_block"><span class="c">%%</span>
</div><div id="l1150" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1151" class="code_block">| ?- string<span class="nb">_</span>substitute(&#39;qaddf&#39;, [s(2,4)], [&#39;123&#39;] ,L).
</div><div id="l1152" class="code_block">
</div><div id="l1153" class="code_block">L = qa123f
</div><div id="l1154" class="code_block">
</div><div id="l1155" class="code_block">| ?- string<span class="nb">_</span>substitute(&#39;qaddf&#39;, [s(2,-1)], [&#39;123&#39;] ,L).
</div><div id="l1156" class="code_block">
</div><div id="l1157" class="code_block">L = qa123
</div><div id="l1158" class="code_block">
</div><div id="l1159" class="code_block">| ?- string<span class="nb">_</span>substitute(&quot;abcdefg&quot;, [s(4,-1)], [&quot;123&quot;],L).
</div><div id="l1160" class="code_block">
</div><div id="l1161" class="code_block">L = [97,98,99,100,49,50,51]
</div><div id="l1162" class="code_block">
</div><div id="l1163" class="code_block">| ?- string<span class="nb">_</span>substitute(&#39;1234567890123&#39;, [f(1,5),f(5,7),f(9,-2)], [&quot;pppp&quot;, lll],X).
</div><div id="l1164" class="code_block">
</div><div id="l1165" class="code_block">X = 1pppplll89lll
</div><div id="l1166" class="code_block">
</div><div id="l1167" class="code_block">| ?- string<span class="nb">_</span>substitute(&#39;1234567890123&#39;, [f(1,5),f(6,7),f(9,-2)], [&#39;---&#39;],X).
</div><div id="l1168" class="code_block">
</div><div id="l1169" class="code_block">X = 1---6---89---
</div><div id="l1170" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1171" class="code_block"><span class="c">%%</span>
</div><div id="l1172" class="code_block">
</div><div id="l1173" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>concat<span class="k">\_atom</span>(+AtomList,?Atom)<span class="nb">}{</span>string<span class="nb">}</span>
</div><div id="l1174" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>concat<span class="k">\_atom</span>/2 <span class="nb">}}</span>
</div><div id="l1175" class="code_block">
</div><div id="l1176" class="code_block"><span class="nb">{</span><span class="k">\tt</span> AtomList<span class="nb">}</span> must be a list structure containing atoms, integers
</div><div id="l1177" class="code_block">and/or floats.  This predicate flattens <span class="nb">{</span><span class="k">\tt</span> AtomList<span class="nb">}</span> and
</div><div id="l1178" class="code_block">concatenates the atoms and integers into a single atom, returned in
</div><div id="l1179" class="code_block"><span class="nb">{</span><span class="k">\tt</span> Atom<span class="nb">}</span>.  Integers and floats are converted to character strings
</div><div id="l1180" class="code_block">using <span class="nb">{</span><span class="k">\tt</span> number<span class="k">\_codes</span>/2<span class="nb">}</span>.
</div><div id="l1181" class="code_block">
</div><div id="l1182" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>concat<span class="k">\_atom</span>(+AtomList,+Sep,?Atom)<span class="nb">}{</span>string<span class="nb">}</span>
</div><div id="l1183" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>concat<span class="k">\_atom</span>/3 <span class="nb">}}</span>
</div><div id="l1184" class="code_block">
</div><div id="l1185" class="code_block"><span class="nb">{</span><span class="k">\tt</span> AtomList<span class="nb">}</span> must be a list containing atoms, integers and/or
</div><div id="l1186" class="code_block">floats, and <span class="nb">{</span><span class="k">\tt</span> Sep<span class="nb">}</span> must be an atom.  This predicate concatenates
</div><div id="l1187" class="code_block">the atoms and integers into a single atom, separating each by <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1188" class="code_block">Sep<span class="nb">}</span>, return the resulting atom in <span class="nb">{</span><span class="k">\tt</span> Atom<span class="nb">}</span>.  Integers and floats
</div><div id="l1189" class="code_block">are converted to character strings using <span class="nb">{</span><span class="k">\tt</span> number<span class="k">\_codes</span>/2<span class="nb">}</span>.
</div><div id="l1190" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1191" class="code_block">
</div><div id="l1192" class="code_block"><span class="c">%%</span>
</div><div id="l1193" class="code_block"><span class="c">%------------------------------------------------------------------------------</span>
</div><div id="l1194" class="code_block">
</div><div id="l1195" class="code_block"><span class="k">\section</span><span class="nb">{</span>Script Writing Utilities<span class="nb">}</span>
</div><div id="l1196" class="code_block"><span class="c">%========================</span>
</div><div id="l1197" class="code_block">
</div><div id="l1198" class="code_block">Prolog, (in particular XSB!) can be useful for writing scripts.
</div><div id="l1199" class="code_block">Prolog&#39;s simple syntax and declarative semantics make it especially
</div><div id="l1200" class="code_block">suitable for scripts that involve text processing.  There are several
</div><div id="l1201" class="code_block">ways to access script-writing commands from XSB.  The first is to
</div><div id="l1202" class="code_block">execute the command via the predicates <span class="nb">{</span><span class="k">\tt</span> shell/1<span class="nb">}</span> or <span class="nb">{</span><span class="k">\tt</span> shell/2<span class="nb">}</span>.
</div><div id="l1203" class="code_block">These predicates can execute any command but they do not provide
</div><div id="l1204" class="code_block">streamability across UNIX and Windows commands, and they do not return
</div><div id="l1205" class="code_block">any output of commands to Prolog.  Special predicates are provided to
</div><div id="l1206" class="code_block">handle cross-platform compatibility and to bring output into XSB.
</div><div id="l1207" class="code_block">
</div><div id="l1208" class="code_block">Effort has been made to make the these thread-safe; however in
</div><div id="l1209" class="code_block"><span class="k">\version</span>, calls to the XSB script writing utilities go through a
</div><div id="l1210" class="code_block">single mutex, and may cause contention if many threads seek to
</div><div id="l1211" class="code_block">concurrently use sockets.
</div><div id="l1212" class="code_block">
</div><div id="l1213" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1214" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>expand<span class="k">\_filename</span>(+FileName,-ExpandedName)<span class="nb">}{</span>machine<span class="nb">}</span>
</div><div id="l1215" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>expand<span class="k">\_filename</span>/2<span class="nb">}}</span>
</div><div id="l1216" class="code_block"><span class="c">%</span>
</div><div id="l1217" class="code_block">Expands the file name passed as the first argument and binds the
</div><div id="l1218" class="code_block">variable in the second argument to the expanded name. This includes
</div><div id="l1219" class="code_block">(1) expanding Unix tildes, (2) prepending <span class="nb">{</span><span class="k">\tt</span> FileName<span class="nb">}</span> to the
</div><div id="l1220" class="code_block">current directory, and (3) ``rectifying&#39;&#39; the expanded file name.  In
</div><div id="l1221" class="code_block">rectification, the expanded file name is ``rectified&#39;&#39; so that
</div><div id="l1222" class="code_block">multiple repeated slashes are replaced with a single slash, the
</div><div id="l1223" class="code_block">intervening ``./&#39;&#39; are removed, and ``../&#39;&#39; are applied so that the
</div><div id="l1224" class="code_block">preceding item in the path name is deleted. For instance, if the
</div><div id="l1225" class="code_block">current directory is <span class="nb">{</span><span class="k">\tt</span> /home<span class="nb">}</span>, then <span class="nb">{</span><span class="k">\tt</span> abc//cde/..///ff/./b<span class="nb">}</span> will
</div><div id="l1226" class="code_block">be converted into <span class="nb">{</span><span class="k">\tt</span> /home/abc/ff/b<span class="nb">}</span>.
</div><div id="l1227" class="code_block">
</div><div id="l1228" class="code_block">Under Windows, this predicates does rectification as described above,
</div><div id="l1229" class="code_block">(using backslashes when appropriate), but it does not expand the
</div><div id="l1230" class="code_block">tildes.
</div><div id="l1231" class="code_block">
</div><div id="l1232" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>expand<span class="k">\_filename\_no\_prepend</span>(+FileName,-ExpandedName)<span class="nb">}{</span>shell<span class="nb">}</span>
</div><div id="l1233" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>expand<span class="k">\_filename\_no\_prepend</span>/2<span class="nb">}}</span>
</div><div id="l1234" class="code_block">This predicate behaves as <span class="nb">{</span><span class="k">\tt</span> expand<span class="k">\_filename</span>/2<span class="nb">}</span>, but only expands
</div><div id="l1235" class="code_block">tildes and does rectification. It does not prepend the current working
</div><div id="l1236" class="code_block">directory to relative file names.
</div><div id="l1237" class="code_block">
</div><div id="l1238" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>parse<span class="k">\_filename</span>(+FileName,-Dir,-Base,-Extension)<span class="nb">}{</span>machine<span class="nb">}</span>
</div><div id="l1239" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>parse<span class="k">\_filename</span>/4<span class="nb">}}</span>
</div><div id="l1240" class="code_block">This predicate parses file names by separating the directory part, the base
</div><div id="l1241" class="code_block">name part, and file extension. If file extension is found, it is removed
</div><div id="l1242" class="code_block">from the base name. Also, directory names are rectified and if a directory
</div><div id="l1243" class="code_block">name starts with a tilde (in Unix), then it is expanded. Directory names
</div><div id="l1244" class="code_block">always end with a slash or a backslash, as appropriate for the OS at hand.
</div><div id="l1245" class="code_block">
</div><div id="l1246" class="code_block">For instance, <span class="nb">{</span><span class="k">\tt</span> <span class="s">$</span><span class="nv">\sim</span><span class="s">$</span>john///doe/dir1//../foo.bar<span class="nb">}</span> will be parsed into:
</div><div id="l1247" class="code_block"><span class="nb">{</span><span class="k">\tt</span> /home/john/doe/<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span> foo<span class="nb">}</span>, and <span class="nb">{</span><span class="k">\tt</span> bar<span class="nb">}</span> (where we assume that    
</div><div id="l1248" class="code_block"><span class="nb">{</span><span class="k">\tt</span> /home/john<span class="nb">}</span> is what <span class="nb">{</span><span class="k">\tt</span> <span class="s">$</span><span class="nv">\sim</span><span class="s">$</span>john<span class="nb">}</span> expands into).  
</div><div id="l1249" class="code_block">
</div><div id="l1250" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>sleep(+Seconds)<span class="nb">}{</span>shell<span class="nb">}</span>
</div><div id="l1251" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>sleep/1<span class="nb">}}</span>
</div><div id="l1252" class="code_block">Put XSB to sleep for a given number of seconds.  
</div><div id="l1253" class="code_block">
</div><div id="l1254" class="code_block"><span class="nb">{</span><span class="k">\bf</span> Error Cases<span class="nb">}</span>
</div><div id="l1255" class="code_block"><span class="k">\bi</span>
</div><div id="l1256" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Seconds<span class="nb">}</span> is a variable
</div><div id="l1257" class="code_block"><span class="k">\bi</span>
</div><div id="l1258" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> instantiation<span class="k">\_error</span><span class="nb">}</span>.
</div><div id="l1259" class="code_block"><span class="k">\ei</span>
</div><div id="l1260" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Seconds<span class="nb">}</span> is not an integer
</div><div id="l1261" class="code_block"><span class="k">\bi</span>
</div><div id="l1262" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(integer, Seconds)<span class="nb">}</span>.
</div><div id="l1263" class="code_block"><span class="k">\ei</span>
</div><div id="l1264" class="code_block"><span class="k">\ei</span>
</div><div id="l1265" class="code_block">
</div><div id="l1266" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>sys<span class="k">\_pid</span>(-Pid)<span class="nb">}{</span>shell<span class="nb">}</span>
</div><div id="l1267" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>pid/1<span class="nb">}}</span>
</div><div id="l1268" class="code_block">Get Id of the current process.
</div><div id="l1269" class="code_block">
</div><div id="l1270" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>getenv(+VarName,-VarVal<span class="nb">}{</span>machine<span class="nb">}</span> 
</div><div id="l1271" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>getenv/2<span class="nb">}}</span>
</div><div id="l1272" class="code_block"><span class="c">%</span>
</div><div id="l1273" class="code_block">Unifies <span class="nb">{</span><span class="k">\tt</span> VarVal<span class="nb">}</span> with the value of <span class="nb">{</span><span class="k">\tt</span> VarName<span class="nb">}</span> in the current
</div><div id="l1274" class="code_block">shell.  If <span class="nb">{</span><span class="k">\tt</span> VarName<span class="nb">}</span> is not an environment varible, the predicate
</div><div id="l1275" class="code_block">fails.
</div><div id="l1276" class="code_block">
</div><div id="l1277" class="code_block"><span class="nb">{</span><span class="k">\em</span> Example:<span class="nb">}</span>
</div><div id="l1278" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1279" class="code_block">:- import getenv/2 from machine.
</div><div id="l1280" class="code_block">
</div><div id="l1281" class="code_block">yes
</div><div id="l1282" class="code_block">| ?- getenv(&#39;HOSTTYPE&#39;,F).
</div><div id="l1283" class="code_block">
</div><div id="l1284" class="code_block">F = intel-pc
</div><div id="l1285" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1286" class="code_block">
</div><div id="l1287" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>putenv(+String)<span class="nb">}{</span>machine<span class="nb">}</span> 
</div><div id="l1288" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>putenv/3<span class="nb">}}</span>
</div><div id="l1289" class="code_block"><span class="c">%</span>
</div><div id="l1290" class="code_block">If <span class="nb">{</span><span class="k">\tt</span> String<span class="nb">}</span> is of the form <span class="nb">{</span><span class="k">\tt</span> VarName=Value<span class="nb">}</span>, inserts or resets
</div><div id="l1291" class="code_block">the environment variable <span class="nb">{</span><span class="k">\tt</span> VarName<span class="nb">}</span>.  If <span class="nb">{</span><span class="k">\tt</span> VarName<span class="nb">}</span> does not
</div><div id="l1292" class="code_block">exist, it is inserted with <span class="nb">{</span><span class="k">\tt</span> VarVal<span class="nb">}</span>.  If the <span class="nb">{</span><span class="k">\tt</span> VarName<span class="nb">}</span> does
</div><div id="l1293" class="code_block">exist, it is reset to <span class="nb">{</span><span class="k">\tt</span> VarVal<span class="nb">}</span>.  <span class="nb">{</span><span class="k">\tt</span> putenv/2<span class="nb">}</span> always succeeds.
</div><div id="l1294" class="code_block">
</div><div id="l1295" class="code_block">Exceptions:
</div><div id="l1296" class="code_block">    <span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1297" class="code_block">    <span class="k">\item</span><span class="na">[{\tt instantiation\_error}]</span> <span class="nb">{</span><span class="k">\tt</span> String<span class="nb">}</span> is
</div><div id="l1298" class="code_block">      not instantiated at the time of call.
</div><div id="l1299" class="code_block">    <span class="k">\item</span><span class="na">[{\tt type\_error}]</span>
</div><div id="l1300" class="code_block">        <span class="nb">{</span><span class="k">\tt</span> VarName<span class="nb">}</span> or <span class="nb">{</span><span class="k">\tt</span> VarVal<span class="nb">}</span> is not an atom or a list of atoms.
</div><div id="l1301" class="code_block">    <span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1302" class="code_block">
</div><div id="l1303" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1304" class="code_block">
</div><div id="l1305" class="code_block"><span class="c">%---------------------------------------------------------------------------------------</span>
</div><div id="l1306" class="code_block"><span class="k">\comment</span><span class="nb">{</span>
</div><div id="l1307" class="code_block">TLS: Taken out of doc.  But I didn&#39;t touch the code, so as to not
</div><div id="l1308" class="code_block">introduce any incompatibilities.
</div><div id="l1309" class="code_block">
</div><div id="l1310" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>rm(+Path)<span class="nb">}{</span>shell<span class="nb">}</span>
</div><div id="l1311" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>rm/1<span class="nb">}}</span>
</div><div id="l1312" class="code_block">Remove file.
</div><div id="l1313" class="code_block">
</div><div id="l1314" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>ls<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>ls/0<span class="nb">}}</span> 
</div><div id="l1315" class="code_block">    Under UNIX, this command lists in the current output stream the files 
</div><div id="l1316" class="code_block">    in the system&#39;s current directory if it can do so.  If so, it succeeds.
</div><div id="l1317" class="code_block">    It is the same as <span class="nb">{</span><span class="k">\tt</span> shell(&#39;ls -F&#39;, 0)<span class="nb">}</span>.  
</div><div id="l1318" class="code_block">
</div><div id="l1319" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>cd(+Dir)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>cd/1<span class="nb">}}</span>
</div><div id="l1320" class="code_block">    Under UNIX and Windows, this predicate changes the interpreter&#39;s
</div><div id="l1321" class="code_block">    working directory to <span class="nb">{</span><span class="k">\tt</span> Dir<span class="nb">}</span>.  If the directory specified does
</div><div id="l1322" class="code_block">    not exist or is not a directory, or the user does not have execute
</div><div id="l1323" class="code_block">    permission for that directory, predicate <span class="nb">{</span><span class="k">\tt</span> cd/1<span class="nb">}</span> simply fails
</div><div id="l1324" class="code_block">    raising no permission error.
</div><div id="l1325" class="code_block">
</div><div id="l1326" class="code_block">    Exceptions:
</div><div id="l1327" class="code_block">    <span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1328" class="code_block">    <span class="k">\item</span><span class="na">[{\tt instantiation\_error}]</span>
</div><div id="l1329" class="code_block">        <span class="nb">{</span><span class="k">\tt</span> Dir<span class="nb">}</span> is not instantiated at the time of call.
</div><div id="l1330" class="code_block">    <span class="k">\item</span><span class="na">[{\tt type\_error}]</span>
</div><div id="l1331" class="code_block">        <span class="nb">{</span><span class="k">\tt</span> Dir<span class="nb">}</span> is not an atom.
</div><div id="l1332" class="code_block">    <span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1333" class="code_block">
</div><div id="l1334" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>edit(+Module)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>edit/1<span class="nb">}}</span>
</div><div id="l1335" class="code_block">    Provided that the environment variable <span class="nb">{</span><span class="k">\tt</span> EDITOR<span class="nb">}</span> has been set,
</div><div id="l1336" class="code_block">    and the system is executing under UNIX, 
</div><div id="l1337" class="code_block">    a call to <span class="nb">{</span><span class="k">\tt</span> edit(foo)<span class="nb">}</span> will call the default editor on the file
</div><div id="l1338" class="code_block">    named <span class="nb">{</span><span class="k">\tt</span> foo.P<span class="nb">}</span>.  The argument to <span class="nb">{</span><span class="k">\tt</span> edit/1<span class="nb">}</span>, should be instantiated,
</div><div id="l1339" class="code_block">    it can be an absolute or a relative file name, but it should <span class="nb">{</span><span class="k">\em</span> not<span class="nb">}</span>
</div><div id="l1340" class="code_block">    contain the suffix <span class="nb">{</span><span class="k">\tt</span> .P<span class="nb">}</span>.  Users can also set their preferred options
</div><div id="l1341" class="code_block">    of calling the default editor by setting an environment variable named
</div><div id="l1342" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> EDITOR<span class="k">\_OPTIONS</span><span class="nb">}</span>.
</div><div id="l1343" class="code_block">
</div><div id="l1344" class="code_block">    Examples of possible uses of predicate <span class="nb">{</span><span class="k">\tt</span> edit/1<span class="nb">}</span> are:
</div><div id="l1345" class="code_block">    <span class="k">\begin</span><span class="nb">{</span>enumerate<span class="nb">}</span>
</div><div id="l1346" class="code_block">    <span class="k">\item</span> If the environment variables have been set as follows:
</div><div id="l1347" class="code_block">          <span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1348" class="code_block">                setenv EDITOR /usr/ucb/vi
</div><div id="l1349" class="code_block">                setenv EDITOR<span class="nb">_</span>OPTIONS -l
</div><div id="l1350" class="code_block">          <span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1351" class="code_block">          a call like:
</div><div id="l1352" class="code_block">          <span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1353" class="code_block">                | ?- edit(foo).
</div><div id="l1354" class="code_block">          <span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1355" class="code_block">          will call the vi editor in the mode where left and right parentheses
</div><div id="l1356" class="code_block">          and curly brackets are checked for balance for the file <span class="nb">{</span><span class="k">\tt</span> foo.P<span class="nb">}</span>
</div><div id="l1357" class="code_block">          in the current working directory.
</div><div id="l1358" class="code_block">    <span class="k">\item</span> If, on the other hand, they have been set as follows:
</div><div id="l1359" class="code_block">          <span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1360" class="code_block">                setenv EDITOR /usr/local/bin/emacs
</div><div id="l1361" class="code_block">                setenv EDITOR<span class="nb">_</span>OPTIONS -r
</div><div id="l1362" class="code_block">          <span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1363" class="code_block">          a call like:
</div><div id="l1364" class="code_block">          <span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1365" class="code_block">                | ?- edit(&#39;~/foo&#39;).
</div><div id="l1366" class="code_block">          <span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>	
</div><div id="l1367" class="code_block">          will call the emacs editor in reverse video for the file <span class="nb">{</span><span class="k">\tt</span> foo.P<span class="nb">}</span>
</div><div id="l1368" class="code_block">          in user&#39;s home directory.
</div><div id="l1369" class="code_block">    <span class="k">\end</span><span class="nb">{</span>enumerate<span class="nb">}</span>
</div><div id="l1370" class="code_block">
</div><div id="l1371" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>file<span class="k">\_time</span>(+FileName, -time(Time1,Time2))<span class="nb">}{</span>file<span class="k">\_io</span><span class="nb">}</span>
</div><div id="l1372" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>file<span class="k">\_time</span>/2<span class="nb">}}</span>
</div><div id="l1373" class="code_block">
</div><div id="l1374" class="code_block">Returns file&#39;s modification time. Because XSB steals 5 bits from each
</div><div id="l1375" class="code_block">word, time must be returned as two words: Time1, representing the most
</div><div id="l1376" class="code_block">significant digits, and Time2, representing the less significant
</div><div id="l1377" class="code_block">digits.
</div><div id="l1378" class="code_block">
</div><div id="l1379" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>file<span class="k">\_size</span>(+FileName, -Size)<span class="nb">}{</span>file<span class="k">\_io</span><span class="nb">}</span>
</div><div id="l1380" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>file<span class="k">\_size</span>/2<span class="nb">}}</span>
</div><div id="l1381" class="code_block">
</div><div id="l1382" class="code_block">Returns file size.
</div><div id="l1383" class="code_block">
</div><div id="l1384" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>cwd(-Dir)<span class="nb">}{</span>shell<span class="nb">}</span>
</div><div id="l1385" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>cwd/1<span class="nb">}}</span>
</div><div id="l1386" class="code_block">Get current working directory.
</div><div id="l1387" class="code_block">
</div><div id="l1388" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>is<span class="k">\_absolute\_filename</span>(+FileName)<span class="nb">}{</span>machine<span class="nb">}</span> 
</div><div id="l1389" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>is<span class="k">\_absolute\_filename</span>/1<span class="nb">}}</span> Succeeds, if file name is absolute; fails
</div><div id="l1390" class="code_block">otherwise.  This predicate works also under Windows, <span class="nb">{</span><span class="k">\it</span>
</div><div id="l1391" class="code_block">i.e.<span class="nb">}</span>, it recognizes drive letters, etc.
</div><div id="l1392" class="code_block">
</div><div id="l1393" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>cd(+Path)<span class="nb">}{</span>shell<span class="nb">}</span>
</div><div id="l1394" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>cd/1<span class="nb">}}</span>
</div><div id="l1395" class="code_block">Change directory.
</div><div id="l1396" class="code_block">
</div><div id="l1397" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>rename(+Old,-New)<span class="nb">}{</span>shell<span class="nb">}</span>
</div><div id="l1398" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>rename/2<span class="nb">}}</span>
</div><div id="l1399" class="code_block">Rename file.
</div><div id="l1400" class="code_block">
</div><div id="l1401" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>directory(+Path,?Directory)<span class="nb">}{</span>directry<span class="nb">}</span>
</div><div id="l1402" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>directory/2<span class="nb">}}</span>
</div><div id="l1403" class="code_block">
</div><div id="l1404" class="code_block">Unifies <span class="nb">{</span><span class="k">\tt</span> Directory<span class="nb">}</span> with a list of files in the directory specified by
</div><div id="l1405" class="code_block">path.  Information about the files is similar to that obtained by <span class="nb">{</span><span class="k">\tt</span> ls
</div><div id="l1406" class="code_block">  -l<span class="nb">}</span>, but transformed for ease of processing.  This currently works for
</div><div id="l1407" class="code_block">Unix only, is slow, and should be reimplemented in C using <span class="nb">{</span><span class="k">\tt</span> opendir()<span class="nb">}</span>
</div><div id="l1408" class="code_block">and <span class="nb">{</span><span class="k">\tt</span> readdir()<span class="nb">}</span>.
</div><div id="l1409" class="code_block">
</div><div id="l1410" class="code_block">TLS: I think I put this in, and I think its overtaken by
</div><div id="l1411" class="code_block">file<span class="nb">_</span>read<span class="nb">_</span>line<span class="nb">_</span>list plus scan . 
</div><div id="l1412" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>file<span class="k">\_to\_list</span>(S, List)<span class="nb">}{</span>scrptutls<span class="nb">}</span>
</div><div id="l1413" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>file<span class="k">\_to\_list</span>/2<span class="nb">}}</span>
</div><div id="l1414" class="code_block"><span class="c">%%</span>
</div><div id="l1415" class="code_block">Read lines from an <span class="k">\emph</span><span class="nb">{</span>open<span class="nb">}</span> I/O port. Return a
</div><div id="l1416" class="code_block">list of terms, one per each line read. Each such term is a list of tokens
</div><div id="l1417" class="code_block">on the corresponding line.  Tokens are lists of characters separated by a
</div><div id="l1418" class="code_block">space symbol (space, newline, return, tabs, formfeed). For instance, if
</div><div id="l1419" class="code_block"><span class="nb">{</span><span class="k">\tt</span> IOport<span class="nb">}</span> 10 is bound to a file
</div><div id="l1420" class="code_block"><span class="c">%%</span>
</div><div id="l1421" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1422" class="code_block">ads sdfdsfd ee
</div><div id="l1423" class="code_block">112 444
</div><div id="l1424" class="code_block">4555  
</div><div id="l1425" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1426" class="code_block"><span class="c">%%</span>
</div><div id="l1427" class="code_block">then
</div><div id="l1428" class="code_block"><span class="c">%%</span>
</div><div id="l1429" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1430" class="code_block">| ?- file<span class="nb">_</span>to<span class="nb">_</span>list(10, L).  
</div><div id="l1431" class="code_block">L = [[ads,sdfdsfd,ee],[112,444],[4555]]
</div><div id="l1432" class="code_block">yes
</div><div id="l1433" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1434" class="code_block"><span class="c">%%</span>
</div><div id="l1435" class="code_block">Note: <span class="nb">{</span><span class="k">\tt</span> file<span class="k">\_to\_list</span>/2<span class="nb">}</span> does not close the I/O port, so it is an
</div><div id="l1436" class="code_block">application program responsibility.
</div><div id="l1437" class="code_block">
</div><div id="l1438" class="code_block">
</div><div id="l1439" class="code_block"><span class="c">%% This predicate is superseded by spawn_process/5 and shell/5</span>
</div><div id="l1440" class="code_block"><span class="c">%% Do not use it!</span>
</div><div id="l1441" class="code_block"><span class="c">%%</span>
</div><div id="l1442" class="code_block"><span class="c">%%\ourmoditem{sysin(+Command,?Output)}{scrptutl}</span>
</div><div id="l1443" class="code_block"><span class="c">%%\index{\texttt{sysin/2}}</span>
</div><div id="l1444" class="code_block"><span class="c">%%</span>
</div><div id="l1445" class="code_block"><span class="c">%%      Unifies {\tt Output} with the stdout of {\tt Command}</span>
</div><div id="l1446" class="code_block"><span class="c">%%represented as a list of lists of tokens, where each element in the</span>
</div><div id="l1447" class="code_block"><span class="c">%%outer list of {\tt Command} represents a line of stdout.</span>
</div><div id="l1448" class="code_block"><span class="c">%%</span>
</div><div id="l1449" class="code_block"><span class="c">%%Example:</span>
</div><div id="l1450" class="code_block"><span class="c">%%{\footnotesize</span>
</div><div id="l1451" class="code_block"><span class="c">%%\begin{verbatim}</span>
</div><div id="l1452" class="code_block"><span class="c">%%                &gt; uname -a</span>
</div><div id="l1453" class="code_block"><span class="c">%%                Linux swiftlap 1.2.8 #1 Sun May 7 13:10:10 CDT 1995 i486</span>
</div><div id="l1454" class="code_block"><span class="c">%%                | ?- sysin(&#39;uname -a&#39;,Output).</span>
</div><div id="l1455" class="code_block"><span class="c">%%</span>
</div><div id="l1456" class="code_block"><span class="c">%%                Output = [[Linux,swiftlap,1.2.8,#1,Sun,May,7,13:10:10,CDT,1995,i486]]</span>
</div><div id="l1457" class="code_block"><span class="c">%%</span>
</div><div id="l1458" class="code_block"><span class="c">%%                yes</span>
</div><div id="l1459" class="code_block"><span class="c">%%\end{verbatim}}</span>
</div><div id="l1460" class="code_block">
</div><div id="l1461" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>ls<span class="nb">}{</span>shell<span class="nb">}</span>
</div><div id="l1462" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>ls/0<span class="nb">}}</span>
</div><div id="l1463" class="code_block">Does <span class="nb">{</span><span class="k">\tt</span> ls -F<span class="nb">}</span> in Unix, and a <span class="nb">{</span><span class="k">\tt</span> dir<span class="nb">}</span> in Windows.
</div><div id="l1464" class="code_block">
</div><div id="l1465" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>edit(+Path)<span class="nb">}{</span>shell<span class="nb">}</span>
</div><div id="l1466" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>edit/1<span class="nb">}}</span>
</div><div id="l1467" class="code_block">Edit file using your favorite editor (specified by the environment variable
</div><div id="l1468" class="code_block"><span class="nb">{</span><span class="k">\tt</span> EDITOR<span class="nb">}</span>. Unix only.
</div><div id="l1469" class="code_block"><span class="nb">}</span>
</div><div id="l1470" class="code_block"><span class="c">%----------------------------------------------------------------------------------------</span>
</div><div id="l1471" class="code_block">
</div><div id="l1472" class="code_block"><span class="k">\subsection</span><span class="nb">{</span>Communication with Subprocesses<span class="nb">}</span> <span class="k">\label</span><span class="nb">{</span>sec:subprocesses<span class="nb">}</span>
</div><div id="l1473" class="code_block">
</div><div id="l1474" class="code_block">In the previous section, we have seen several predicates that allow XSB to
</div><div id="l1475" class="code_block">create other processes. However, these predicates offer only a very limited
</div><div id="l1476" class="code_block">way to communicate with these processes. The predicate
</div><div id="l1477" class="code_block"><span class="k">\verb</span>|spawn<span class="nb">_</span>process/5| and friends come to the rescue. It allows a user to spawn
</div><div id="l1478" class="code_block">any process (including multiple copies of XSB) and redirect its
</div><div id="l1479" class="code_block">standard input and output to XSB streams. XSB can then write to the
</div><div id="l1480" class="code_block">process and read from it. The section of socket I/O describes yet
</div><div id="l1481" class="code_block">another mode of interprocess communication.
</div><div id="l1482" class="code_block">
</div><div id="l1483" class="code_block">In addition, the predicate <span class="nb">{</span><span class="k">\tt</span> pipe<span class="k">\_open</span>/2<span class="nb">}</span> described in this
</div><div id="l1484" class="code_block">section lets one create any number of pipes (that do not need to be
</div><div id="l1485" class="code_block">connected to the standard I/O stream) and talk to child processes
</div><div id="l1486" class="code_block">through these pipes.
</div><div id="l1487" class="code_block"><span class="c">%</span>
</div><div id="l1488" class="code_block">All predicates in this section, except <span class="nb">{</span><span class="k">\tt</span> pipe<span class="k">\_open</span>/2<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1489" class="code_block">fd2stream/2<span class="nb">}</span>, must be imported from module <span class="nb">{</span><span class="k">\tt</span> shell<span class="nb">}</span>.  The
</div><div id="l1490" class="code_block">predicates <span class="nb">{</span><span class="k">\tt</span> pipe<span class="k">\_open</span>/2<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> fd2stream/2<span class="nb">}</span> must be imported
</div><div id="l1491" class="code_block">from <span class="nb">{</span><span class="k">\tt</span> file<span class="k">\_io</span><span class="nb">}</span>.
</div><div id="l1492" class="code_block">
</div><div id="l1493" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1494" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>spawn<span class="k">\_process</span>(+CmdSpec,-StreamToProc,-StreamFromProc,-ProcStderrStream,-ProcId)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>spawn<span class="k">\_process</span>/5<span class="nb">}}</span> 
</div><div id="l1495" class="code_block">Spawn a new process specified by <span class="nb">{</span><span class="k">\tt</span> CmdSpec<span class="nb">}</span>. <span class="nb">{</span><span class="k">\tt</span> CmdSpec<span class="nb">}</span> must be
</div><div id="l1496" class="code_block">either a single atom or a <span class="k">\emph</span><span class="nb">{</span>list<span class="nb">}</span> of atoms.
</div><div id="l1497" class="code_block">If it is an atom, then it must represent a shell command.
</div><div id="l1498" class="code_block">If it is a list, the first member of the list must be the name of the
</div><div id="l1499" class="code_block">program to run and the 
</div><div id="l1500" class="code_block">other elements must be arguments to the program. Program name must be specified
</div><div id="l1501" class="code_block">in such a way as to make sure the OS can find it using the contents of the
</div><div id="l1502" class="code_block">environment variable <span class="nb">{</span><span class="k">\tt</span> PATH<span class="nb">}</span>.
</div><div id="l1503" class="code_block">Also note that pipes, I/O redirection and such are not allowed in command
</div><div id="l1504" class="code_block">specification. That is, <span class="nb">{</span><span class="k">\tt</span> CmdSpec<span class="nb">}</span> must represent a single command.
</div><div id="l1505" class="code_block">(But read about process plumbing below and about the related predicate
</div><div id="l1506" class="code_block"><span class="nb">{</span><span class="k">\tt</span> shell/5<span class="nb">}</span>.)
</div><div id="l1507" class="code_block">
</div><div id="l1508" class="code_block">The next three parameters of <span class="k">\verb</span>|spawn<span class="nb">_</span>process| are XSB I/O stream
</div><div id="l1509" class="code_block">identifiers for the process (leading to the subprocess standard
</div><div id="l1510" class="code_block">input), from the process (from its standard output), and a stream
</div><div id="l1511" class="code_block">capturing the subprocess standard error output. The last parameter is
</div><div id="l1512" class="code_block">the system process id.
</div><div id="l1513" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1514" class="code_block"><span class="c">%%</span>
</div><div id="l1515" class="code_block">
</div><div id="l1516" class="code_block"><span class="k">\noindent</span>
</div><div id="l1517" class="code_block">Here is a simple example of how it works.
</div><div id="l1518" class="code_block">
</div><div id="l1519" class="code_block"><span class="c">%%</span>
</div><div id="l1520" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1521" class="code_block">| ?- import file<span class="nb">_</span>flush/2, file<span class="nb">_</span>read<span class="nb">_</span>line<span class="nb">_</span>atom/2 from file<span class="nb">_</span>io.
</div><div id="l1522" class="code_block">| ?- import file<span class="nb">_</span>nl/1 , file<span class="nb">_</span>write/2 from xsb<span class="nb">_</span>writ.  
</div><div id="l1523" class="code_block">
</div><div id="l1524" class="code_block">| ?- spawn<span class="nb">_</span>process([cat, &#39;-&#39;], To, From, Stderr, Pid),
</div><div id="l1525" class="code_block">     writeln(To,&#39;Hello cat!&#39;), flush<span class="nb">_</span>output(To,<span class="nb">_</span>), file<span class="nb">_</span>read<span class="nb">_</span>line<span class="nb">_</span>atom(From,Y).
</div><div id="l1526" class="code_block">
</div><div id="l1527" class="code_block">To = 3
</div><div id="l1528" class="code_block">From = 4
</div><div id="l1529" class="code_block">Stderr = 5
</div><div id="l1530" class="code_block">Pid = 14328
</div><div id="l1531" class="code_block">Y = Hello cat!
</div><div id="l1532" class="code_block">
</div><div id="l1533" class="code_block">yes
</div><div id="l1534" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1535" class="code_block"><span class="c">%%</span>
</div><div id="l1536" class="code_block">
</div><div id="l1537" class="code_block">Here we created a new process, which runs the ``<span class="nb">{</span><span class="k">\tt</span> cat<span class="nb">}</span>&#39;&#39; program
</div><div id="l1538" class="code_block">with argument ``--&#39;&#39;. This forces <span class="nb">{</span><span class="k">\tt</span> cat<span class="nb">}</span> to read from standard
</div><div id="l1539" class="code_block">input and write to standard output. The next line writes an atom and
</div><div id="l1540" class="code_block">newline to the XSB stream <span class="nb">{</span><span class="k">\tt</span> To<span class="nb">}</span>, which is bound to the standard
</div><div id="l1541" class="code_block">input of the <span class="nb">{</span><span class="k">\tt</span> cat<span class="nb">}</span> process (proc id <span class="nb">{</span><span class="k">\tt</span> 14328<span class="nb">}</span>). The <span class="nb">{</span><span class="k">\tt</span> cat<span class="nb">}</span>
</div><div id="l1542" class="code_block">process then copies the input to its standard output.  Since standard
</div><div id="l1543" class="code_block">output of the cat process is redirected to the XSB stream <span class="nb">{</span><span class="k">\tt</span> From<span class="nb">}</span>
</div><div id="l1544" class="code_block">in the parent process, the last line in our program is able to read it
</div><div id="l1545" class="code_block">and return in the variable <span class="nb">{</span><span class="k">\tt</span> Y<span class="nb">}</span>.
</div><div id="l1546" class="code_block"><span class="c">%</span>
</div><div id="l1547" class="code_block">Note that in the second line we used <span class="nb">{</span><span class="k">\tt</span> flush<span class="k">\_output</span>/2<span class="nb">}</span>. Flushing
</div><div id="l1548" class="code_block">the output is extremely important here, because XSB I/O pipe (file)
</div><div id="l1549" class="code_block">streams are buffered.  Thus, <span class="nb">{</span><span class="k">\tt</span> cat<span class="nb">}</span> might not see its input until
</div><div id="l1550" class="code_block">the buffer is filled up, so the above clause might hang. <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1551" class="code_block">flush<span class="k">\_output</span>/2<span class="nb">}</span> makes sure that the input is immediately available to
</div><div id="l1552" class="code_block">the subprocess.
</div><div id="l1553" class="code_block">
</div><div id="l1554" class="code_block">In addition to the above general schema, the user can tell
</div><div id="l1555" class="code_block"><span class="k">\verb</span>|spawn<span class="nb">_</span>process/5| not to open one of the communication streams or to
</div><div id="l1556" class="code_block">use one of the existing communication streams.  This is useful when
</div><div id="l1557" class="code_block">you do not expect to write or read to/from the subprocess or when one
</div><div id="l1558" class="code_block">process wants to write to another (see the process plumbing example
</div><div id="l1559" class="code_block">below).
</div><div id="l1560" class="code_block"><span class="c">%</span>
</div><div id="l1561" class="code_block">To tell that a certain stream is not needed, it suffices to bind that
</div><div id="l1562" class="code_block">stream to an atom.  For instance,
</div><div id="l1563" class="code_block"><span class="c">%%</span>
</div><div id="l1564" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1565" class="code_block">| ?- spawn<span class="nb">_</span>process([cat, &#39;-&#39;], To, none, none, <span class="nb">_</span>),
</div><div id="l1566" class="code_block">     nl(To), writeln(To,&#39;Hello cat!&#39;), flush<span class="nb">_</span>output(To).
</div><div id="l1567" class="code_block">
</div><div id="l1568" class="code_block">
</div><div id="l1569" class="code_block">To = 3,
</div><div id="l1570" class="code_block">Hello cat!
</div><div id="l1571" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1572" class="code_block"><span class="c">%%</span>
</div><div id="l1573" class="code_block">reads from XSB and copies the result to standard output. Likewise,
</div><div id="l1574" class="code_block"><span class="c">%%</span>
</div><div id="l1575" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1576" class="code_block">| ?- spawn<span class="nb">_</span>process(&#39;cat library.tex&#39;, none, From, none, <span class="nb">_</span>),
</div><div id="l1577" class="code_block">     file<span class="nb">_</span>read<span class="nb">_</span>line<span class="nb">_</span>atom(From, S).
</div><div id="l1578" class="code_block">
</div><div id="l1579" class="code_block">From = 4
</div><div id="l1580" class="code_block">S = <span class="k">\chapter</span><span class="nb">{</span>Library Utilities<span class="nb">}</span> <span class="k">\label</span><span class="nb">{</span>library<span class="nb">_</span>utilities<span class="nb">}</span>
</div><div id="l1581" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1582" class="code_block"><span class="c">%%</span>
</div><div id="l1583" class="code_block">In each case, only one of the streams is open. (Note that the shell
</div><div id="l1584" class="code_block">command is specified as an atom rather than a list.) Finally, if both
</div><div id="l1585" class="code_block">streams are suppressed, then <span class="k">\verb</span>|spawn<span class="nb">_</span>process| reduces to the usual
</div><div id="l1586" class="code_block"><span class="nb">{</span><span class="k">\tt</span> shell/1<span class="nb">}</span> call (in fact, this is how <span class="nb">{</span><span class="k">\tt</span> shell/1<span class="nb">}</span> is
</div><div id="l1587" class="code_block">implemented):
</div><div id="l1588" class="code_block"><span class="c">%%</span>
</div><div id="l1589" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1590" class="code_block">| ?- spawn<span class="nb">_</span>process([pwd], none, none).
</div><div id="l1591" class="code_block">
</div><div id="l1592" class="code_block">/usr/local/foo/bar
</div><div id="l1593" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1594" class="code_block"><span class="c">%%</span>
</div><div id="l1595" class="code_block">On the other hand, if any one of the three stream variables in
</div><div id="l1596" class="code_block"><span class="k">\verb</span>|spawn<span class="nb">_</span>process| is bound to an already existing file stream, then the
</div><div id="l1597" class="code_block">subprocess will use that stream (see the process plumbing example
</div><div id="l1598" class="code_block">below).
</div><div id="l1599" class="code_block">
</div><div id="l1600" class="code_block">One of the uses of XSB subprocesses is to create XSB servers that spawn
</div><div id="l1601" class="code_block">subprocesses and control them. A spawned subprocess can be another XSB
</div><div id="l1602" class="code_block">process. The following example shows one XSB process spawning another,
</div><div id="l1603" class="code_block">sending it a goal to evaluate and obtaining the result:
</div><div id="l1604" class="code_block"><span class="c">%%</span>
</div><div id="l1605" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1606" class="code_block">| ?- spawn<span class="nb">_</span>process([xsb], To, From,Err,<span class="nb">_</span>),
</div><div id="l1607" class="code_block">     write(To,&#39;assert(p(1)).&#39;), flush<span class="nb">_</span>output(To,<span class="nb">_</span>),
</div><div id="l1608" class="code_block">     write(To,&#39;p(X), writeln(X).&#39;), flush<span class="nb">_</span>output(To,<span class="nb">_</span>), 
</div><div id="l1609" class="code_block">     file<span class="nb">_</span>read<span class="nb">_</span>line<span class="nb">_</span>atom(From,XX).  
</div><div id="l1610" class="code_block">
</div><div id="l1611" class="code_block">XX = 1
</div><div id="l1612" class="code_block">
</div><div id="l1613" class="code_block">yes
</div><div id="l1614" class="code_block">| ?-
</div><div id="l1615" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1616" class="code_block"><span class="c">%%</span>
</div><div id="l1617" class="code_block">Here the parent XSB process sends ``<span class="k">\verb</span>|assert(p(1)).|&#39;&#39; and then
</div><div id="l1618" class="code_block">``<span class="k">\verb</span>|p(X), writeln(X).|&#39;&#39; to the spawned XSB subprocess. The latter
</div><div id="l1619" class="code_block">evaluates the goal and prints (via ``<span class="k">\verb</span>|writeln(X)|&#39;&#39;) to its
</div><div id="l1620" class="code_block">standard output. The main process reads it through the <span class="nb">{</span><span class="k">\tt</span> From<span class="nb">}</span>
</div><div id="l1621" class="code_block">stream and binds the variable <span class="nb">{</span><span class="k">\tt</span> XX<span class="nb">}</span> to that output.
</div><div id="l1622" class="code_block">
</div><div id="l1623" class="code_block">Finally, we should note that the stream variables in the
</div><div id="l1624" class="code_block"><span class="k">\verb</span>|spawn<span class="nb">_</span>process| predicate can be used to do process plumbing, <span class="nb">{</span><span class="k">\it</span>
</div><div id="l1625" class="code_block">  i.e.<span class="nb">}</span>, redirect output of one subprocess into the input of another. Here
</div><div id="l1626" class="code_block">is an example:
</div><div id="l1627" class="code_block"><span class="c">%%</span>
</div><div id="l1628" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1629" class="code_block">| ?- open(test,write,Stream),
</div><div id="l1630" class="code_block">     spawn<span class="nb">_</span>process([cat, &#39;data&#39;], none, FromCat1, none, <span class="nb">_</span>),
</div><div id="l1631" class="code_block">     spawn<span class="nb">_</span>process([sort], FromCat1,Stream, none, <span class="nb">_</span>).  
</div><div id="l1632" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1633" class="code_block"><span class="c">%%</span>
</div><div id="l1634" class="code_block">Here, we first open file <span class="nb">{</span><span class="k">\tt</span> test<span class="nb">}</span>. Then <span class="k">\verb</span>|cat data| is spawned.
</div><div id="l1635" class="code_block">This process has the input and standard error stream blocked (as
</div><div id="l1636" class="code_block">indicated by the atom <span class="nb">{</span><span class="k">\tt</span> none<span class="nb">}</span>), and its output goes into stream
</div><div id="l1637" class="code_block"><span class="nb">{</span><span class="k">\tt</span> FromCat1<span class="nb">}</span>.  Then we spawn another process, <span class="nb">{</span><span class="k">\tt</span> sort<span class="nb">}</span>, which
</div><div id="l1638" class="code_block">picks the output from the first process (since it uses the stream <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1639" class="code_block">FromCat1<span class="nb">}</span> as its input) and sends its own output (the sorted version
</div><div id="l1640" class="code_block">of <span class="nb">{</span><span class="k">\tt</span> data<span class="nb">}</span>) to its output stream <span class="nb">{</span><span class="k">\tt</span> Stream<span class="nb">}</span>.  However, <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1641" class="code_block">Stream<span class="nb">}</span> has already been open for output into the file <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1642" class="code_block">test<span class="nb">}</span>. Thus, the overall result of the above clause is tantamount to
</div><div id="l1643" class="code_block">the following shell command:
</div><div id="l1644" class="code_block"><span class="c">%%</span>
</div><div id="l1645" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1646" class="code_block">        cat data | sort &gt; test  
</div><div id="l1647" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1648" class="code_block"><span class="c">%%</span>
</div><div id="l1649" class="code_block">
</div><div id="l1650" class="code_block"><span class="k">\paragraph</span><span class="nb">{{</span><span class="k">\em</span> Important notes about spawned processes<span class="k">\/</span><span class="nb">}</span>:<span class="nb">}</span>
</div><div id="l1651" class="code_block"><span class="k">\begin</span><span class="nb">{</span>enumerate<span class="nb">}</span>
</div><div id="l1652" class="code_block"><span class="k">\item</span> Asynchronous processes spawned by XSB do not disappear (at least on
</div><div id="l1653" class="code_block">  Unix) when they terminate, <span class="k">\emph</span><span class="nb">{</span>unless<span class="nb">}</span> the XSB program executes a
</div><div id="l1654" class="code_block">  <span class="k">\emph</span><span class="nb">{</span>wait<span class="nb">}</span> on them (see <span class="nb">{</span><span class="k">\tt</span> process<span class="k">\_control</span><span class="nb">}</span> below). Instead, such
</div><div id="l1655" class="code_block">  processes become defunct <span class="k">\emph</span><span class="nb">{</span>zombies<span class="nb">}</span> (in Unix terminology); they do
</div><div id="l1656" class="code_block">  not do anything, but consume resources (such as file descriptors). So,
</div><div id="l1657" class="code_block">  when a subprocess is known to terminate, it must be waited on.
</div><div id="l1658" class="code_block">  
</div><div id="l1659" class="code_block"><span class="k">\item</span> The XSB parent process must know how to terminate the asynchronous
</div><div id="l1660" class="code_block">  subprocesses it spawns. The drastic way is to kill it (see <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1661" class="code_block">    process<span class="k">\_control</span><span class="nb">}</span> below). Sometimes a subprocess might terminate by
</div><div id="l1662" class="code_block">  itself (<span class="nb">{</span><span class="k">\it</span> e.g.<span class="nb">}</span>, having finished reading a file). In other cases, the
</div><div id="l1663" class="code_block">  parent and the child programs must agree on a protocol by which the
</div><div id="l1664" class="code_block">  parent can tell the child to exit. The programs in the XSB subdirectory
</div><div id="l1665" class="code_block">  <span class="nb">{</span><span class="k">\tt</span> examples/subprocess<span class="nb">}</span> illustrate this idea. If the child subprocess
</div><div id="l1666" class="code_block">  is another XSB process, then it can be terminated by sending the atom
</div><div id="l1667" class="code_block">  <span class="nb">{</span><span class="k">\tt</span> end<span class="k">\_of\_file</span><span class="nb">}</span> or <span class="nb">{</span><span class="k">\tt</span> halt<span class="nb">}</span> to the standard input of the child.
</div><div id="l1668" class="code_block">  (For this to work, the child XSB must waiting at the prompt).
</div><div id="l1669" class="code_block"><span class="k">\item</span> It is very important to not forget to close the streams that the
</div><div id="l1670" class="code_block">  parent uses to communicate with the child. These are the streams
</div><div id="l1671" class="code_block">  that are provided in arguments 2,3,4 of <span class="nb">{</span><span class="k">\tt</span> spawn<span class="k">\_process</span><span class="nb">}</span>. The
</div><div id="l1672" class="code_block">  reason is that the child might terminate, but these streams to the
</div><div id="l1673" class="code_block">  standard input of the child will remain open, since they belong to
</div><div id="l1674" class="code_block">  the parent process. As a result, the parent will own defunct I/O
</div><div id="l1675" class="code_block">  streams and might eventually run out of file descriptors or streams.
</div><div id="l1676" class="code_block"><span class="k">\end</span><span class="nb">{</span>enumerate<span class="nb">}</span>
</div><div id="l1677" class="code_block">
</div><div id="l1678" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1679" class="code_block">  <span class="k">\ouritem</span><span class="nb">{</span>process<span class="k">\_status</span>(+Pid,-Status)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>process<span class="k">\_status</span>/2<span class="nb">}}</span>
</div><div id="l1680" class="code_block">  This predicate always succeeds. Given a process id, it binds the second
</div><div id="l1681" class="code_block">  argument (which must be an unbound variable) to one of the following
</div><div id="l1682" class="code_block">  atoms: <span class="nb">{</span><span class="k">\tt</span> running<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span> stopped<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span> exited<span class="k">\_normally</span><span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1683" class="code_block">    exited<span class="k">\_abnormally</span><span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span> aborted<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span> invalid<span class="nb">}</span>, and <span class="nb">{</span><span class="k">\tt</span> unknown<span class="nb">}</span>.
</div><div id="l1684" class="code_block">  The <span class="nb">{</span><span class="k">\tt</span> invalid<span class="nb">}</span> status is given to processes that never existed or that
</div><div id="l1685" class="code_block">  are not children of the parent XSB process. The <span class="nb">{</span><span class="k">\tt</span> unknown<span class="nb">}</span> status is
</div><div id="l1686" class="code_block">  assigned when none of the other statuses can be assigned.
</div><div id="l1687" class="code_block">  
</div><div id="l1688" class="code_block">  Note: process status (other than <span class="nb">{</span><span class="k">\tt</span> running<span class="nb">}</span>) is system dependent.
</div><div id="l1689" class="code_block">  Windows does not seem to support <span class="nb">{</span><span class="k">\tt</span> stopped<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> aborted<span class="nb">}</span>.  Also,
</div><div id="l1690" class="code_block">  processes killed using the <span class="k">\verb</span>|process<span class="nb">_</span>control| predicate (described
</div><div id="l1691" class="code_block">  next) are often marked as <span class="nb">{</span><span class="k">\tt</span> invalid<span class="nb">}</span> rather than <span class="nb">{</span><span class="k">\tt</span> exited<span class="nb">}</span>, because
</div><div id="l1692" class="code_block">  Windows seems to lose all information about such processes. Process
</div><div id="l1693" class="code_block">  status might be inaccurate in some Unix systems as well, if the process
</div><div id="l1694" class="code_block">  has terminated and <span class="nb">{</span><span class="k">\tt</span> wait()<span class="nb">}</span> has been executed on that process.
</div><div id="l1695" class="code_block">
</div><div id="l1696" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>process<span class="k">\_control</span>(+Pid,+Operation)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>process<span class="k">\_control</span>/2<span class="nb">}}</span> 
</div><div id="l1697" class="code_block">    Perform a process control <span class="nb">{</span><span class="k">\tt</span> operation<span class="nb">}</span> on the process with the given
</div><div id="l1698" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> Pid<span class="nb">}</span>. 
</div><div id="l1699" class="code_block">    Currently, the only supported operations are <span class="nb">{</span><span class="k">\tt</span> kill<span class="nb">}</span> (an atom) and <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1700" class="code_block">    wait(Code)<span class="nb">}</span> (a term).
</div><div id="l1701" class="code_block">    The former causes the process to exit unconditionally, and the latter
</div><div id="l1702" class="code_block">    waits for process completion. When the process exits, <span class="nb">{</span><span class="k">\tt</span> Code<span class="nb">}</span> is
</div><div id="l1703" class="code_block">    bound to the process exit code. The code for normal termination is 0.
</div><div id="l1704" class="code_block">
</div><div id="l1705" class="code_block">    This predicate succeeds, if the operation was performed successfully.
</div><div id="l1706" class="code_block">    Otherwise, it fails. The <span class="nb">{</span><span class="k">\tt</span> wait<span class="nb">}</span> operation fails if the process
</div><div id="l1707" class="code_block">    specified in <span class="nb">{</span><span class="k">\tt</span> Pid<span class="nb">}</span> does not exist or is not a child of the parent
</div><div id="l1708" class="code_block">    XSB process. 
</div><div id="l1709" class="code_block">    
</div><div id="l1710" class="code_block">    The <span class="nb">{</span><span class="k">\tt</span> kill<span class="nb">}</span> operation might fail, if the process to be killed does
</div><div id="l1711" class="code_block">    not exist or if the parent XSB process does not have the permission to
</div><div id="l1712" class="code_block">    terminate that process. Unix and Windows have different ideas as to
</div><div id="l1713" class="code_block">    what these permissions are. See <span class="k">\emph</span><span class="nb">{</span>kill(2)<span class="nb">}</span> for Unix and
</div><div id="l1714" class="code_block">    <span class="k">\emph</span><span class="nb">{</span>TerminateProcess<span class="nb">}</span> for Windows.
</div><div id="l1715" class="code_block">    
</div><div id="l1716" class="code_block">    <span class="k">\emph</span><span class="nb">{</span>Note<span class="nb">}</span>: under Windows, the programmer&#39;s manual warns of dire
</div><div id="l1717" class="code_block">    consequences if one kills a process that has DLLs attached to it.
</div><div id="l1718" class="code_block"><span class="c">%</span>
</div><div id="l1719" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>get<span class="k">\_process\_table</span>(-ProcessList)<span class="nb">}{</span>shell<span class="nb">}</span>
</div><div id="l1720" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>get<span class="k">\_process\_table</span>/1<span class="nb">}}</span> 
</div><div id="l1721" class="code_block">    This predicate is imported from module <span class="nb">{</span><span class="k">\tt</span> shell<span class="nb">}</span>.
</div><div id="l1722" class="code_block">    It binds <span class="nb">{</span><span class="k">\tt</span> ProcessList<span class="nb">}</span> to the list of terms, each describing one of
</div><div id="l1723" class="code_block">    the active XSB subprocesses (created via <span class="k">\verb</span>|spawn<span class="nb">_</span>process/5|).
</div><div id="l1724" class="code_block">    Each term has the form:
</div><div id="l1725" class="code_block">    <span class="c">%%</span>
</div><div id="l1726" class="code_block">    <span class="k">\begin</span><span class="nb">{</span>center<span class="nb">}</span>
</div><div id="l1727" class="code_block">      <span class="k">\verb</span>|process(Pid,ToStream,FromStream,StderrStream,CommandLine)|. 
</div><div id="l1728" class="code_block">    <span class="k">\end</span><span class="nb">{</span>center<span class="nb">}</span>
</div><div id="l1729" class="code_block">    <span class="c">%%</span>
</div><div id="l1730" class="code_block">    The first argument in the term is the process id of the corresponding
</div><div id="l1731" class="code_block">    process, the next three arguments describe the three standard streams
</div><div id="l1732" class="code_block">    of the process, and the last is an atom that shows the command line used
</div><div id="l1733" class="code_block">    to invoke the process.
</div><div id="l1734" class="code_block">    This predicate always succeeds.
</div><div id="l1735" class="code_block">
</div><div id="l1736" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>shell(+CmdSpec,-StreamToProc, -StreamFromProc, -ProcStderr,
</div><div id="l1737" class="code_block">  -ErrorCode)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>shell/5<span class="nb">}}</span> 
</div><div id="l1738" class="code_block"><span class="c">%</span>
</div><div id="l1739" class="code_block">The arguments of this predicate are similar to those of
</div><div id="l1740" class="code_block"><span class="k">\verb</span>|spawn<span class="nb">_</span>process|, except for the following: (1) The first argument
</div><div id="l1741" class="code_block">is an atom or a list of atoms, like in <span class="k">\verb</span>|spawn<span class="nb">_</span>process|. However,
</div><div id="l1742" class="code_block">if it is a list of atoms, then the resulting shell command is obtained
</div><div id="l1743" class="code_block">by string concatenation. This is different from <span class="k">\verb</span>|spawn<span class="nb">_</span>process|
</div><div id="l1744" class="code_block">where each member of the list must represent an argument to the
</div><div id="l1745" class="code_block">program being invoked (and which must be the first member of that
</div><div id="l1746" class="code_block">list).  (2) The last argument is the error code returned by the shell
</div><div id="l1747" class="code_block">command and not a process id. The code -1 and 127 mean that the shell
</div><div id="l1748" class="code_block">command failed.
</div><div id="l1749" class="code_block">    
</div><div id="l1750" class="code_block">    The <span class="nb">{</span><span class="k">\tt</span> shell/5<span class="nb">}</span> predicate is similar to <span class="k">\verb</span>|spawn<span class="nb">_</span>process| in
</div><div id="l1751" class="code_block">    that it spawns another process and can capture that process&#39; input
</div><div id="l1752" class="code_block">    and output streams.
</div><div id="l1753" class="code_block"><span class="c">%    </span>
</div><div id="l1754" class="code_block">    The important difference, however, is that XSB will ways until the
</div><div id="l1755" class="code_block">    process spawned by <span class="nb">{</span><span class="k">\tt</span> shell/5<span class="nb">}</span> terminates. In contrast, the process
</div><div id="l1756" class="code_block">    spawned by <span class="k">\verb</span>|spawn<span class="nb">_</span>process| will run concurrently with XSB.  In
</div><div id="l1757" class="code_block">    this latter case, XSB must explicitly synchronize with the spawned
</div><div id="l1758" class="code_block">    subprocess using the predicate <span class="k">\verb</span>|process<span class="nb">_</span>control/2| (using the <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1759" class="code_block">      wait<span class="nb">}</span> operation), as described earlier.
</div><div id="l1760" class="code_block">    
</div><div id="l1761" class="code_block">    The fact that XSB must wait until <span class="nb">{</span><span class="k">\tt</span> shell/5<span class="nb">}</span> finishes has a very
</div><div id="l1762" class="code_block">    important implication: the amount of data the can be sent to and from
</div><div id="l1763" class="code_block">    the shell command is limited (1K is probably safe). This is because the
</div><div id="l1764" class="code_block">    shell command communicates with XSB via pipes, which have limited
</div><div id="l1765" class="code_block">    capacity.  So, if the pipe is filled, XSB will hang waiting for <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1766" class="code_block">      shell/5<span class="nb">}</span> to finish and <span class="nb">{</span><span class="k">\tt</span> shell/5<span class="nb">}</span> will wait for XSB to consume data
</div><div id="l1767" class="code_block">    from the pipe.  Thus, use <span class="k">\verb</span>|spawn<span class="nb">_</span>process/5| for any kind of
</div><div id="l1768" class="code_block">    significant data exchange between external processes and XSB.
</div><div id="l1769" class="code_block">  
</div><div id="l1770" class="code_block">  Another difference between these two forms of spawning subprocesses is
</div><div id="l1771" class="code_block">  that <span class="nb">{</span><span class="k">\tt</span> CmdSpec<span class="nb">}</span> in <span class="nb">{</span><span class="k">\tt</span> shell/5<span class="nb">}</span> can represent <span class="k">\emph</span><span class="nb">{</span>any<span class="nb">}</span> shell
</div><div id="l1772" class="code_block">  statement, including those that have pipes and I/O redirection. In
</div><div id="l1773" class="code_block">  contrast, <span class="k">\verb</span>|spawn<span class="nb">_</span>process| only allows command of the form ``program
</div><div id="l1774" class="code_block">  args&#39;&#39;. For instance,
</div><div id="l1775" class="code_block"><span class="c">%%</span>
</div><div id="l1776" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1777" class="code_block">| ?- open(test,write,Stream),
</div><div id="l1778" class="code_block">     shell(&#39;cat | sort &gt; data&#39;, Stream, none, none, ErrCode)
</div><div id="l1779" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1780" class="code_block"><span class="c">%%</span>
</div><div id="l1781" class="code_block">As seen from this example, the same rules for blocking I/O streams
</div><div id="l1782" class="code_block">apply to <span class="nb">{</span><span class="k">\tt</span> shell/5<span class="nb">}</span>. Finally, we should note that the already
</div><div id="l1783" class="code_block">familiar standard predicates <span class="nb">{</span><span class="k">\tt</span> shell/1<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> shell/2<span class="nb">}</span>
</div><div id="l1784" class="code_block">(documented in Volume 1) are implemented using <span class="nb">{</span><span class="k">\tt</span> shell/5<span class="nb">}</span>, and <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1785" class="code_block">  shell/5<span class="nb">}</span> shares their error cases.
</div><div id="l1786" class="code_block">
</div><div id="l1787" class="code_block"><span class="k">\paragraph</span><span class="nb">{</span><span class="k">\em</span> Notes:<span class="nb">}</span>
</div><div id="l1788" class="code_block"><span class="c">%%</span>
</div><div id="l1789" class="code_block"><span class="k">\begin</span><span class="nb">{</span>enumerate<span class="nb">}</span>
</div><div id="l1790" class="code_block">  <span class="k">\item</span>  With <span class="nb">{</span><span class="k">\tt</span> shell/5<span class="nb">}</span>, you do not have to worry about terminating
</div><div id="l1791" class="code_block">    child processes: XSB waits until the child exits automatically.
</div><div id="l1792" class="code_block">    However, since communication pipes have limited capacity, this method
</div><div id="l1793" class="code_block">    can be used only for exchanging small amounts of information between
</div><div id="l1794" class="code_block">    parent and child.
</div><div id="l1795" class="code_block">  <span class="k">\item</span> The earlier remark about the need to close I/O streams to the child
</div><div id="l1796" class="code_block">    <span class="k">\emph</span><span class="nb">{</span>does<span class="nb">}</span> apply.
</div><div id="l1797" class="code_block"><span class="k">\end</span><span class="nb">{</span>enumerate<span class="nb">}</span>
</div><div id="l1798" class="code_block"><span class="c">%%</span>
</div><div id="l1799" class="code_block">
</div><div id="l1800" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>pipe<span class="k">\_open</span>(-ReadPipe, -WritePipe)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>pipe<span class="k">\_open</span>/2<span class="nb">}}</span> 
</div><div id="l1801" class="code_block">Open a new pipe and return the read end and the write end of that
</div><div id="l1802" class="code_block">pipe.  If the operation fails, both <span class="nb">{</span><span class="k">\tt</span> ReadPipe<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> WritePipe<span class="nb">}</span>
</div><div id="l1803" class="code_block">are bound to negative numbers.
</div><div id="l1804" class="code_block"><span class="c">%  </span>
</div><div id="l1805" class="code_block">The pipes returned by the <span class="nb">{</span><span class="k">\tt</span> pipe<span class="k">\_open</span>/2<span class="nb">}</span> predicate are small
</div><div id="l1806" class="code_block">integers that represent file descriptors used by the underlying
</div><div id="l1807" class="code_block">OS. They are <span class="nb">{</span><span class="k">\bf</span> not XSB I/O streams<span class="nb">}</span>, and they cannot be used for
</div><div id="l1808" class="code_block">I/O directly. To use them, one must convert them to streams using <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1809" class="code_block">open/3<span class="nb">}</span> or <span class="nb">{</span><span class="k">\tt</span> open/4<span class="nb">}</span>.~<span class="k">\footnote</span><span class="nb">{</span>
</div><div id="l1810" class="code_block"><span class="c">%% </span>
</div><div id="l1811" class="code_block">XSB does not convert pipe file descriptors into I/O streams
</div><div id="l1812" class="code_block">automatically.  Because of the way XSB I/O streams are represented,
</div><div id="l1813" class="code_block">they are not inherited by the child process and they do not make sense
</div><div id="l1814" class="code_block">to the child process (especially if the child is not another XSB
</div><div id="l1815" class="code_block">process). Therefore, we must pass the child processes an OS file
</div><div id="l1816" class="code_block">descriptor instead. The child then converts these descriptor into XSB
</div><div id="l1817" class="code_block">I/O streams.  
</div><div id="l1818" class="code_block"><span class="c">%% </span>
</div><div id="l1819" class="code_block"><span class="nb">}</span>
</div><div id="l1820" class="code_block">
</div><div id="l1821" class="code_block">    The best way to illustrate how one can create a new pipe to a child
</div><div id="l1822" class="code_block">    (even if the child has been created earlier) is to show an example.
</div><div id="l1823" class="code_block">    Consider two programs, <span class="nb">{</span><span class="k">\tt</span> parent.P<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> child.P<span class="nb">}</span>. The parent
</div><div id="l1824" class="code_block">    copy of XSB consults <span class="nb">{</span><span class="k">\tt</span> parent.P<span class="nb">}</span>, which does the following: First, it
</div><div id="l1825" class="code_block">    creates a pipe and spawns a copy of XSB. Then it tells the
</div><div id="l1826" class="code_block">    child copy of XSB to assert the fact <span class="nb">{</span><span class="k">\tt</span> pipe(RP)<span class="nb">}</span>, where <span class="nb">{</span><span class="k">\tt</span> RP<span class="nb">}</span> is
</div><div id="l1827" class="code_block">    a number representing the read part of the pipe. Next, the parent XSB tells
</div><div id="l1828" class="code_block">    the child XSB to consult the program <span class="nb">{</span><span class="k">\tt</span> child.P<span class="nb">}</span>. Finally, it sends
</div><div id="l1829" class="code_block">    the message <span class="nb">{</span><span class="k">\tt</span> Hello!<span class="nb">}</span>.
</div><div id="l1830" class="code_block">
</div><div id="l1831" class="code_block">    The <span class="nb">{</span><span class="k">\tt</span> child.P<span class="nb">}</span> program gets the pipe from predicate <span class="nb">{</span><span class="k">\tt</span> pipe/1<span class="nb">}</span>
</div><div id="l1832" class="code_block">    (note that the parent tells the child XSB to first assert <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1833" class="code_block">    pipe(RP)<span class="nb">}</span> and only then to consult the <span class="nb">{</span><span class="k">\tt</span> child.P<span class="nb">}</span> file).
</div><div id="l1834" class="code_block">  After that, the child reads a message from the pipe and prints it to its
</div><div id="l1835" class="code_block">    standard output. Both programs are shown below:
</div><div id="l1836" class="code_block">    <span class="c">%%</span>
</div><div id="l1837" class="code_block">    <span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1838" class="code_block"><span class="c">%% parent.P      </span>
</div><div id="l1839" class="code_block">:- import pipe<span class="nb">_</span>open/2 from file<span class="nb">_</span>io.
</div><div id="l1840" class="code_block"><span class="c">%% Create the pipe and pass it to the child process</span>
</div><div id="l1841" class="code_block">?- pipe<span class="nb">_</span>open(RP,WP),
</div><div id="l1842" class="code_block">   <span class="c">%% WF is now the XSB I/O stream bound to the write part of the pipe</span>
</div><div id="l1843" class="code_block">   open(pipe(WP),write,WF),
</div><div id="l1844" class="code_block">   <span class="c">%% ProcInput becomes the XSB stream leading directly to the child&#39;s stdin</span>
</div><div id="l1845" class="code_block">   spawn<span class="nb">_</span>process(nxsb1, ProcInput, block, block, Process),
</div><div id="l1846" class="code_block">   <span class="c">%% Tell the child where the reading part of the pipe is</span>
</div><div id="l1847" class="code_block">   fmt<span class="nb">_</span>write(ProcInput, &quot;assert(pipe(<span class="c">%d)).\n&quot;, arg(RP)),</span>
</div><div id="l1848" class="code_block">   fmt<span class="nb">_</span>write(ProcInput, &quot;[child].<span class="k">\n</span>&quot;, <span class="nb">_</span>),
</div><div id="l1849" class="code_block">   flush<span class="nb">_</span>output(ProcInput, <span class="nb">_</span>),
</div><div id="l1850" class="code_block">   <span class="c">%% Pass a message through the pipe</span>
</div><div id="l1851" class="code_block">   fmt<span class="nb">_</span>write(WF, &quot;Hello!<span class="k">\n</span>&quot;, <span class="nb">_</span>),
</div><div id="l1852" class="code_block">   flush<span class="nb">_</span>output(WF, <span class="nb">_</span>),
</div><div id="l1853" class="code_block">   fmt<span class="nb">_</span>write(ProcInput, &quot;end<span class="nb">_</span>of<span class="nb">_</span>file.<span class="k">\n</span>&quot;,<span class="nb">_</span>), <span class="c">% send end_of_file atom to child</span>
</div><div id="l1854" class="code_block">   flush<span class="nb">_</span>output(ProcInput, <span class="nb">_</span>),
</div><div id="l1855" class="code_block">   <span class="c">%% wait for child (so as to not leave zombies around; </span>
</div><div id="l1856" class="code_block">   <span class="c">%% zombies quit when the parent finishes, but they consume resources)</span>
</div><div id="l1857" class="code_block">   process<span class="nb">_</span>control(Process, wait),
</div><div id="l1858" class="code_block">   <span class="c">%% Close the ports used to commuicate with the process</span>
</div><div id="l1859" class="code_block">   <span class="c">%% Otherwise, the parent might run out of file descriptors </span>
</div><div id="l1860" class="code_block">   <span class="c">%% (if many processes were spawned)</span>
</div><div id="l1861" class="code_block">   close(ProcInput), close(WF).
</div><div id="l1862" class="code_block">    <span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1863" class="code_block">    <span class="c">%%</span>
</div><div id="l1864" class="code_block">    <span class="c">%%</span>
</div><div id="l1865" class="code_block">    <span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1866" class="code_block"><span class="c">%% child.P</span>
</div><div id="l1867" class="code_block">:- import file<span class="nb">_</span>read<span class="nb">_</span>line<span class="nb">_</span>atom/2 from file<span class="nb">_</span>io.
</div><div id="l1868" class="code_block">:- dynamic pipe/1.
</div><div id="l1869" class="code_block">?- pipe(P), open(pipe(P),read,F),
</div><div id="l1870" class="code_block">   <span class="c">%% Acknowledge receipt of the pipe</span>
</div><div id="l1871" class="code_block">   fmt<span class="nb">_</span>write(&quot;<span class="k">\nPipe</span> <span class="c">%d received\n&quot;, arg(P)),</span>
</div><div id="l1872" class="code_block">   <span class="c">%% Get a message from the parent and print it to stdout</span>
</div><div id="l1873" class="code_block">   file<span class="nb">_</span>read<span class="nb">_</span>line<span class="nb">_</span>atom(F, Line), write(&#39;Message was: &#39;), writeln(Line).
</div><div id="l1874" class="code_block">    <span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1875" class="code_block">    <span class="c">%%</span>
</div><div id="l1876" class="code_block">    This produces the following output:
</div><div id="l1877" class="code_block">    <span class="c">%%</span>
</div><div id="l1878" class="code_block">    <span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1879" class="code_block">| ?- [parent].                    &lt;- parent XSB consults parent.P
</div><div id="l1880" class="code_block">[parent loaded]
</div><div id="l1881" class="code_block">yes
</div><div id="l1882" class="code_block">| ?- [xsb<span class="nb">_</span>configuration loaded]   &lt;- parent.P spawns a child copy of XSB
</div><div id="l1883" class="code_block">[sysinitrc loaded]                   Here we see the startup messages of
</div><div id="l1884" class="code_block">[packaging loaded]                   the child copy
</div><div id="l1885" class="code_block">XSB Version 2.0 (Gouden Carolus) of June 27, 1999
</div><div id="l1886" class="code_block">[i686-pc-linux-gnu; mode: optimal; engine: slg-wam; scheduling: batched]
</div><div id="l1887" class="code_block">| ?- 
</div><div id="l1888" class="code_block">yes
</div><div id="l1889" class="code_block">| ?- [Compiling ./child]          &lt;- The child copy of received the pipe from
</div><div id="l1890" class="code_block">[child compiled, cpu time used: 0.1300 seconds]     the parent and then the
</div><div id="l1891" class="code_block">[child loaded]                                      request to consult child.P
</div><div id="l1892" class="code_block">Pipe 15 received                  &lt;- child.P acknowledges receipt of the pipe
</div><div id="l1893" class="code_block">Message was: Hello!               &lt;- child.P gets the message and prints it
</div><div id="l1894" class="code_block">yes       
</div><div id="l1895" class="code_block">    <span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l1896" class="code_block">    <span class="c">%%</span>
</div><div id="l1897" class="code_block">    
</div><div id="l1898" class="code_block">    Observe that the parent process is very careful about making sure
</div><div id="l1899" class="code_block">    that the child terminates and also about closing the I/O streams
</div><div id="l1900" class="code_block">    after they are no longer needed.
</div><div id="l1901" class="code_block">    
</div><div id="l1902" class="code_block">    Finally, we should note that this mechanism can be used to
</div><div id="l1903" class="code_block">    communicate through pipes with non-XSB processes as well. Indeed,
</div><div id="l1904" class="code_block">    an XSB process can create a pipe using <span class="nb">{</span><span class="k">\tt</span> pipe<span class="k">\_open</span><span class="nb">}</span>
</div><div id="l1905" class="code_block">    (<span class="k">\emph</span><span class="nb">{</span>before<span class="nb">}</span> spawning a child process), pass one end of the pipe
</div><div id="l1906" class="code_block">    to a child process (which can be a C program), and use <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1907" class="code_block">    open/3<span class="nb">}</span> to convert the other end of the pipe to an XSB
</div><div id="l1908" class="code_block">    stream. The C program, of course, does not need <span class="nb">{</span><span class="k">\tt</span> open/3<span class="nb">}</span>,
</div><div id="l1909" class="code_block">    since it can use the pipe file handle directly. Likewise, a C
</div><div id="l1910" class="code_block">    program can spawn off an XSB process and pass it one end of a
</div><div id="l1911" class="code_block">    pipe.  The XSB child-process can then convert this pipe fd to a
</div><div id="l1912" class="code_block">    file using <span class="nb">{</span><span class="k">\tt</span> fd2iostream<span class="nb">}</span> and then talk to the parent C program.
</div><div id="l1913" class="code_block">
</div><div id="l1914" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>fd2iostream(+Pipe, -IOstream)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>fd2iostream/2<span class="nb">}}</span> 
</div><div id="l1915" class="code_block">Take a file descriptor and convert it to an XSB I/O stream. This
</div><div id="l1916" class="code_block">predicate should be used only for user-defined I/O.  Otherwise, use
</div><div id="l1917" class="code_block"><span class="nb">{</span><span class="k">\tt</span> open/<span class="k">\{</span>3,4<span class="k">\}</span><span class="nb">}</span> when possible.
</div><div id="l1918" class="code_block">
</div><div id="l1919" class="code_block">
</div><div id="l1920" class="code_block"><span class="c">%------------------------------------------------------------------------------------------</span>
</div><div id="l1921" class="code_block"><span class="k">\comment</span><span class="nb">{</span>
</div><div id="l1922" class="code_block"><span class="c">% TLS: Redefining ISO halt/1 as sys_exit/1.</span>
</div><div id="l1923" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>sys<span class="k">\_exit</span>(-ExitCode)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>sys<span class="k">\_exit</span>/1<span class="nb">}}</span> 
</div><div id="l1924" class="code_block">This predicate causes XSB subprocess to exit unconditionally with the exit
</div><div id="l1925" class="code_block">code <span class="nb">{</span><span class="k">\tt</span> ExitCode<span class="nb">}</span>. Normally <span class="nb">{</span><span class="k">\tt</span> 0<span class="nb">}</span> is considered to indicate normal
</div><div id="l1926" class="code_block">termination, while other exit codes are used to report various degrees of
</div><div id="l1927" class="code_block">abnormality.
</div><div id="l1928" class="code_block"><span class="nb">}</span>
</div><div id="l1929" class="code_block"><span class="c">%------------------------------------------------------------------------------------------</span>
</div><div id="l1930" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1931" class="code_block">
</div><div id="l1932" class="code_block">
</div><div id="l1933" class="code_block">
</div><div id="l1934" class="code_block"><span class="k">\section</span><span class="nb">{</span>Socket I/O<span class="nb">}</span>
</div><div id="l1935" class="code_block">
</div><div id="l1936" class="code_block">The XSB socket library defines a number of predicates for
</div><div id="l1937" class="code_block">communication over BSD-style sockets. Most are modeled after and are
</div><div id="l1938" class="code_block">interfaces to the socket functions with the same name. For detailed
</div><div id="l1939" class="code_block">information on sockets, the reader is referred to the Unix man pages
</div><div id="l1940" class="code_block">(another good source is <span class="k">\emph</span><span class="nb">{</span>Unix Network Programming<span class="nb">}</span>, by W.
</div><div id="l1941" class="code_block">Richard Stevens).  Several examples of the use of the XSB sockets
</div><div id="l1942" class="code_block">interface can be found in the <span class="nb">{</span><span class="k">\tt</span> XSB/examples/<span class="nb">}</span> directory in the XSB
</div><div id="l1943" class="code_block">distribution.
</div><div id="l1944" class="code_block">
</div><div id="l1945" class="code_block">XSB supports two modes of communication via sockets:
</div><div id="l1946" class="code_block"><span class="k">\emph</span><span class="nb">{</span>stream-oriented<span class="nb">}</span> and <span class="k">\emph</span><span class="nb">{</span>message-oriented<span class="nb">}</span>. In turn,
</div><div id="l1947" class="code_block">stream-oriented communication can be <span class="k">\emph</span><span class="nb">{</span>buffered<span class="nb">}</span> or
</div><div id="l1948" class="code_block"><span class="k">\emph</span><span class="nb">{</span>character-at-a-time<span class="nb">}</span>.
</div><div id="l1949" class="code_block">
</div><div id="l1950" class="code_block">To use <span class="k">\emph</span><span class="nb">{</span>buffered<span class="nb">}</span> stream-oriented communication, system socket
</div><div id="l1951" class="code_block">handles must be converted to XSB I/O streams using <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1952" class="code_block">  fd2iostream/2<span class="nb">}</span>.  In these stream-oriented communication, messages
</div><div id="l1953" class="code_block">have no boundaries, and communication appears to the processes as
</div><div id="l1954" class="code_block">reading and writing to a file.  At present, buffered stream-oriented
</div><div id="l1955" class="code_block">communication works under Unix only.
</div><div id="l1956" class="code_block">
</div><div id="l1957" class="code_block"><span class="k">\emph</span><span class="nb">{</span>Character-at-a-time<span class="nb">}</span> stream communication is accomplished using
</div><div id="l1958" class="code_block">the primitives <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_put</span>/3<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_get</span>0/3<span class="nb">}</span>. These
</div><div id="l1959" class="code_block">correspond to the usual Prolog <span class="nb">{</span><span class="k">\tt</span> put/1<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> get0/1<span class="nb">}</span> I/O primitives.
</div><div id="l1960" class="code_block">
</div><div id="l1961" class="code_block">In message-oriented communication, processes exchange messages that have
</div><div id="l1962" class="code_block">well-defined boundaries. The communicating processes use <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l1963" class="code_block">  socket<span class="k">\_send</span>/3<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_recv</span>/3<span class="nb">}</span> to talk to each other.
</div><div id="l1964" class="code_block">XSB messages are represented as strings where the first four bytes
</div><div id="l1965" class="code_block">(<span class="nb">{</span><span class="k">\tt</span> sizeof(int)<span class="nb">}</span>) is an integer (represented in the binary network format
</div><div id="l1966" class="code_block">--- see the functions <span class="nb">{</span><span class="k">\tt</span> htonl<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> ntohl<span class="nb">}</span> in socket documentation)
</div><div id="l1967" class="code_block">and the rest is the body of the message. The integer in the header
</div><div id="l1968" class="code_block">represents the length of the message body.
</div><div id="l1969" class="code_block">
</div><div id="l1970" class="code_block">Effort has been made to make the socket interface thread-safe; however
</div><div id="l1971" class="code_block">in <span class="k">\version</span>, calls to the XSB socket interface go through a single
</div><div id="l1972" class="code_block">mutex, and may cause contention if many threads seek to concurrently
</div><div id="l1973" class="code_block">use sockets.
</div><div id="l1974" class="code_block">
</div><div id="l1975" class="code_block">We now describe the XSB socket interface.  All predicates below must be
</div><div id="l1976" class="code_block">imported from the module <span class="nb">{</span><span class="k">\tt</span> socket<span class="nb">}</span>. Note that almost all predicates have
</div><div id="l1977" class="code_block">the last argument that unifies with the error code returned from the
</div><div id="l1978" class="code_block">corresponding socket operation. This argument is explained separately.
</div><div id="l1979" class="code_block">
</div><div id="l1980" class="code_block"><span class="k">\paragraph</span><span class="nb">{</span>General socket calls.<span class="nb">}</span>
</div><div id="l1981" class="code_block">These are used to open/close sockets, to establish connections, and set
</div><div id="l1982" class="code_block">special socket options.
</div><div id="l1983" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l1984" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket(-Sockfd, ?ErrorCode)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket/2<span class="nb">}}</span>
</div><div id="l1985" class="code_block">    A socket <span class="nb">{</span><span class="k">\tt</span> Sockfd<span class="nb">}</span>  in the AF<span class="k">\_INET</span> domain is created.
</div><div id="l1986" class="code_block">    (The AF<span class="k">\_UNIX</span> domain is not yet implemented). 
</div><div id="l1987" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> Sockfd<span class="nb">}</span> is bound to a small integer, called socket descriptor or
</div><div id="l1988" class="code_block">    socket handle.
</div><div id="l1989" class="code_block">
</div><div id="l1990" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_set\_option</span>(+Sockfd,+OptionName,+Value)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_set\_option</span>/3<span class="nb">}}</span>
</div><div id="l1991" class="code_block">    Set socket option. At present, only the <span class="nb">{</span><span class="k">\tt</span> linger<span class="nb">}</span> option is
</div><div id="l1992" class="code_block">    supported. ``Lingering&#39;&#39; is a situation when a socket continues to live
</div><div id="l1993" class="code_block">    after it was shut down by the owner. This is used in order to let the
</div><div id="l1994" class="code_block">    client program that uses the socket to finish reading or writing
</div><div id="l1995" class="code_block">    from/to the socket. <span class="nb">{</span><span class="k">\tt</span> Value<span class="nb">}</span> represents the number of seconds to linger.
</div><div id="l1996" class="code_block">    The value -1 means do not linger at all.
</div><div id="l1997" class="code_block">
</div><div id="l1998" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_close</span>(+Sockfd, ?ErrorCode)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_close</span>/2<span class="nb">}}</span>
</div><div id="l1999" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> Sockfd<span class="nb">}</span> is closed. Sockets used in <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_connect</span>/2<span class="nb">}</span>  should
</div><div id="l2000" class="code_block">    not be closed by <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_close</span>/1<span class="nb">}</span>  as they will be closed when the
</div><div id="l2001" class="code_block">    corresponding stream is closed.
</div><div id="l2002" class="code_block">
</div><div id="l2003" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_bind</span>(+Sockfd,+Port, ?ErrorCode)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_bind</span>/3<span class="nb">}}</span>
</div><div id="l2004" class="code_block">   The socket <span class="nb">{</span><span class="k">\tt</span> Sockfd<span class="nb">}</span>  is bound to the specified local port number.
</div><div id="l2005" class="code_block">
</div><div id="l2006" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_connect</span>(+Sockfd,+Port,+Hostname,?ErrorCode)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_connect</span>/4<span class="nb">}}</span>
</div><div id="l2007" class="code_block">    The socket Sockfd is connected to the address (<span class="nb">{</span><span class="k">\tt</span> Hostname<span class="nb">}</span>  and
</div><div id="l2008" class="code_block"><span class="nb">{</span><span class="k">\tt</span> Port<span class="nb">}</span>). If <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_connect</span>/4<span class="nb">}</span> terminates abnormally for any reason
</div><div id="l2009" class="code_block">(connection refused, timeout, etc.), then XSb closes the socket <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2010" class="code_block">    Sockfd<span class="nb">}</span> automatically, because such a socket cannot be used according
</div><div id="l2011" class="code_block">    to the BSD semantics. Therefore, it is always a good idea to check to
</div><div id="l2012" class="code_block">    the return code and reopen the socket, if the error code is not
</div><div id="l2013" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> SOCK<span class="k">\_OK</span><span class="nb">}</span>.
</div><div id="l2014" class="code_block">
</div><div id="l2015" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_listen</span>(+Socket, +Length, ?ErrorCode)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_listen</span>/3<span class="nb">}}</span>
</div><div id="l2016" class="code_block">    The socket <span class="nb">{</span><span class="k">\tt</span> Sockfd<span class="nb">}</span>  is defined to have a maximum backlog queue of
</div><div id="l2017" class="code_block"><span class="nb">{</span><span class="k">\tt</span> Length<span class="nb">}</span>  pending connections.
</div><div id="l2018" class="code_block">
</div><div id="l2019" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_accept</span>(+Sockfd,-SockOut, ?ErrorCode)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_accept</span>/3<span class="nb">}}</span>
</div><div id="l2020" class="code_block">    Block the caller until a connection attempt arrives. If the incoming 
</div><div id="l2021" class="code_block">    queue is not empty, the first connection request is accepted, the call
</div><div id="l2022" class="code_block">    succeeds and returns a new socket, <span class="nb">{</span><span class="k">\tt</span> SockOut<span class="nb">}</span>, which can be used for
</div><div id="l2023" class="code_block">    this new connection.
</div><div id="l2024" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2025" class="code_block">
</div><div id="l2026" class="code_block"><span class="k">\paragraph</span><span class="nb">{</span>Buffered, message-based communication.<span class="nb">}</span>
</div><div id="l2027" class="code_block">These calls are similar to the <span class="nb">{</span><span class="k">\tt</span> recv<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> send<span class="nb">}</span> calls in C, except
</div><div id="l2028" class="code_block">that XSB wraps a higher-level message protocol around these low-level
</div><div id="l2029" class="code_block">functions. More precisely, <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_send</span>/3<span class="nb">}</span> prepends a 4-byte field
</div><div id="l2030" class="code_block">to each message, which indicates the length of the message
</div><div id="l2031" class="code_block">body. When <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_recv</span>/3<span class="nb">}</span> reads a message, it first reads the 4-byte
</div><div id="l2032" class="code_block">field to determine the length of the message and then reads the remainder
</div><div id="l2033" class="code_block">of the message. 
</div><div id="l2034" class="code_block">
</div><div id="l2035" class="code_block">All this is transparent to the XSB user, but you should know these details
</div><div id="l2036" class="code_block">if you want to use these details to communicate with external processes
</div><div id="l2037" class="code_block">written in C and such. All this means that these external programs must
</div><div id="l2038" class="code_block">implement the same protocol. The subtle point here is that different
</div><div id="l2039" class="code_block">machines represent integers differently, so an integer must first be
</div><div id="l2040" class="code_block">converted into the machine-independent network format using the functions
</div><div id="l2041" class="code_block"><span class="nb">{</span><span class="k">\tt</span> htonl<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> ntohl<span class="nb">}</span> provided by the socket library. For instance,
</div><div id="l2042" class="code_block">to send a message to XSB, one must do something like this:
</div><div id="l2043" class="code_block"><span class="c">%%</span>
</div><div id="l2044" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2045" class="code_block">char *message, *msg<span class="nb">_</span>body;
</div><div id="l2046" class="code_block">unsigned int msg<span class="nb">_</span>body<span class="nb">_</span>len, network<span class="nb">_</span>encoded<span class="nb">_</span>len;
</div><div id="l2047" class="code_block">
</div><div id="l2048" class="code_block">  msg<span class="nb">_</span>body<span class="nb">_</span>len = strlen(msg<span class="nb">_</span>body);
</div><div id="l2049" class="code_block">  network<span class="nb">_</span>encoded<span class="nb">_</span>len = (unsigned int) htonl((unsigned long int) msg<span class="nb">_</span>body<span class="nb">_</span>len);
</div><div id="l2050" class="code_block">  memcpy((void *) message, (void *) <span class="nb">&amp;</span>network<span class="nb">_</span>encoded<span class="nb">_</span>len, 4);
</div><div id="l2051" class="code_block">  strcpy(message+4, msg<span class="nb">_</span>body);
</div><div id="l2052" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2053" class="code_block"><span class="c">%%</span>
</div><div id="l2054" class="code_block">To read a message sent by XSB, one can do as follows:
</div><div id="l2055" class="code_block"><span class="c">%%</span>
</div><div id="l2056" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2057" class="code_block">int actual<span class="nb">_</span>len;
</div><div id="l2058" class="code_block">char lenbuf[4], msg<span class="nb">_</span>buff;
</div><div id="l2059" class="code_block">unsigned int msglen, net<span class="nb">_</span>encoded<span class="nb">_</span>len;  
</div><div id="l2060" class="code_block">
</div><div id="l2061" class="code_block">  actual<span class="nb">_</span>len = (long)recvfrom(sock<span class="nb">_</span>handle, lenbuf, 4, 0, NULL, 0);
</div><div id="l2062" class="code_block">  memcpy((void *) <span class="nb">&amp;</span>net<span class="nb">_</span>encoded<span class="nb">_</span>len, (void *) lenbuf, 4);
</div><div id="l2063" class="code_block">  msglen = ntohl(net<span class="nb">_</span>encoded<span class="nb">_</span>len);
</div><div id="l2064" class="code_block">
</div><div id="l2065" class="code_block">  msg<span class="nb">_</span>buff = calloc(msglen+1, sizeof(char))); // check if this suceeded!!!
</div><div id="l2066" class="code_block">  recvfrom(sock<span class="nb">_</span>handle, msg<span class="nb">_</span>buff, msglen, 0, NULL, 0);
</div><div id="l2067" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2068" class="code_block"><span class="c">%%</span>
</div><div id="l2069" class="code_block">If making the external processes follow the XSB protocol is not practical
</div><div id="l2070" class="code_block">(because you did not write these programs), then you should use the
</div><div id="l2071" class="code_block">character-at-a-time interface or, better, the buffered
</div><div id="l2072" class="code_block">stream-based interface both of which are described in this section.
</div><div id="l2073" class="code_block">At present, however, the buffered stream-based interface does not work on
</div><div id="l2074" class="code_block">Windows.
</div><div id="l2075" class="code_block"><span class="c">%%</span>
</div><div id="l2076" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2077" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_recv</span>(+Sockfd,-Message, ?ErrorCode)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_recv</span>/3<span class="nb">}}</span>
</div><div id="l2078" class="code_block">    Receives a message from the connection identified by the socket descriptor
</div><div id="l2079" class="code_block">    <span class="nb">{</span><span class="k">\tt</span> Sockfd<span class="nb">}</span>. Binds <span class="nb">{</span><span class="k">\tt</span> Message<span class="nb">}</span> to the message. <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_recv</span>/3<span class="nb">}</span>
</div><div id="l2080" class="code_block">    provides a message-oriented interface. It understands message
</div><div id="l2081" class="code_block">    boundaries set by <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_send</span>/3<span class="nb">}</span>.
</div><div id="l2082" class="code_block">
</div><div id="l2083" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_send</span>(+Sockfd,+Message, ?ErrorCode)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_send</span>/3<span class="nb">}}</span>
</div><div id="l2084" class="code_block">    Takes a message (which must be an atom) and sends it through the
</div><div id="l2085" class="code_block">    connection specified by <span class="nb">{</span><span class="k">\tt</span> Sockfd<span class="nb">}</span>. <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_send</span>/3<span class="nb">}</span> provides
</div><div id="l2086" class="code_block">    message-oriented communication. It prepends a 4-byte header to the
</div><div id="l2087" class="code_block">    message, which tells <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_recv</span>/3<span class="nb">}</span> the length of the message body.
</div><div id="l2088" class="code_block">
</div><div id="l2089" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2090" class="code_block">
</div><div id="l2091" class="code_block"><span class="k">\paragraph</span><span class="nb">{</span>Stream-oriented, character-at-a-time interface.<span class="nb">}</span>
</div><div id="l2092" class="code_block">Internally, this interface uses the same <span class="nb">{</span><span class="k">\tt</span> sendto<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> recvfrom<span class="nb">}</span>
</div><div id="l2093" class="code_block">socket calls, but they are executed for each character separately.
</div><div id="l2094" class="code_block">This interface is appropriate when the message format is not known or when
</div><div id="l2095" class="code_block">message boundaries are determined using special delimiters.
</div><div id="l2096" class="code_block">
</div><div id="l2097" class="code_block"><span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_get</span>0/3<span class="nb">}</span> creates the end-of-file condition when it receives the
</div><div id="l2098" class="code_block">end-of-file character <span class="nb">{</span><span class="k">\tt</span> CH<span class="k">\_EOF\_P</span><span class="nb">}</span> (a.k.a. 255) defined in <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2099" class="code_block">  char<span class="k">\_defs</span>.h<span class="nb">}</span> (which must be included in the XSB program). C programs
</div><div id="l2100" class="code_block">that need to send an end-of-file character should send <span class="nb">{</span><span class="k">\tt</span> (char)-1<span class="nb">}</span>.
</div><div id="l2101" class="code_block"><span class="c">%%</span>
</div><div id="l2102" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2103" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_get</span>0(+Sockfd, -Char, ?ErrorCode)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_get</span>0/3<span class="nb">}}</span>
</div><div id="l2104" class="code_block">The equivalent of <span class="nb">{</span><span class="k">\tt</span> get0<span class="nb">}</span> for sockets.
</div><div id="l2105" class="code_block">
</div><div id="l2106" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_put</span>(+Sockfd, +Char, ?ErrorCode)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_put</span>/3<span class="nb">}}</span>
</div><div id="l2107" class="code_block">Similar to put/1, but works on sockets.
</div><div id="l2108" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2109" class="code_block"><span class="c">%%</span>
</div><div id="l2110" class="code_block">
</div><div id="l2111" class="code_block"><span class="k">\paragraph</span><span class="nb">{</span>Socket-probing.<span class="nb">}</span>
</div><div id="l2112" class="code_block">With the help of the predicate <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_select</span>/6<span class="nb">}</span> one can establish a
</div><div id="l2113" class="code_block">group of asynchronous or synchronous socket connections. In the synchronous
</div><div id="l2114" class="code_block">mode, this call is blocked until one of the sockets in the group becomes
</div><div id="l2115" class="code_block">available for reading or writing, as described below.  In the asynchronous
</div><div id="l2116" class="code_block">mode, this call is used to probe the sockets periodically, to find out
</div><div id="l2117" class="code_block">which sockets have data available for reading or which sockets have room in
</div><div id="l2118" class="code_block">the buffer to write to.
</div><div id="l2119" class="code_block">
</div><div id="l2120" class="code_block">The directory <span class="nb">{</span><span class="k">\tt</span> XSB/examples/socket/select/<span class="nb">}</span> has a number of examples of
</div><div id="l2121" class="code_block">the use of the socket-probing calls.
</div><div id="l2122" class="code_block"><span class="c">%%</span>
</div><div id="l2123" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2124" class="code_block">  <span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_select</span>(+SymConName,+Timeout,-ReadSockL,-WriteSockL,-ErrSockL,?ErrorCode)<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_select</span>/6<span class="nb">}}</span>
</div><div id="l2125" class="code_block">  <span class="nb">{</span><span class="k">\tt</span> SymConName<span class="nb">}</span> must be an atom that
</div><div id="l2126" class="code_block">  denotes an existing connection group, which must be previously created with
</div><div id="l2127" class="code_block">  <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_set\_select</span>/4<span class="nb">}</span> (described below). <span class="nb">{</span><span class="k">\tt</span> ReadSockL<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2128" class="code_block">    WriteSockL<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span> ErrSockL<span class="nb">}</span> are lists of socket handles (as returned by
</div><div id="l2129" class="code_block">  <span class="nb">{</span><span class="k">\tt</span> socket/2<span class="nb">}</span>) that specify the available sockets that are available for
</div><div id="l2130" class="code_block">  reading, writing, or on which exception conditions occurred.  <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2131" class="code_block">    Timeout<span class="nb">}</span> must be an integer that specifies the timeout in seconds (0
</div><div id="l2132" class="code_block">  means probe and exit immediately). If <span class="nb">{</span><span class="k">\tt</span> Timeout<span class="nb">}</span> is a variable, then
</div><div id="l2133" class="code_block">  wait indefinitely until one of the sockets becomes available.
</div><div id="l2134" class="code_block">
</div><div id="l2135" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_set\_select</span>(+SymConName,+ReadSockFdLst,+WriteSockFdLst,+ErrorSockFdLst)<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_set\_select</span>/4<span class="nb">}}</span>
</div><div id="l2136" class="code_block">Creates a connection group with the symbolic name <span class="nb">{</span><span class="k">\tt</span> SymConName<span class="nb">}</span>
</div><div id="l2137" class="code_block">(an atom) for subsequent use by <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_select</span>/6<span class="nb">}</span>.
</div><div id="l2138" class="code_block"><span class="nb">{</span><span class="k">\tt</span> ReadSockFdLst<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span> WriteSockFdLst<span class="nb">}</span>, and <span class="nb">{</span><span class="k">\tt</span> ErrorSockFdLst<span class="nb">}</span> are
</div><div id="l2139" class="code_block">lists of sockets for which <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_select</span>/6<span class="nb">}</span> will be used to monitor read,
</div><div id="l2140" class="code_block">write, or exception conditions.
</div><div id="l2141" class="code_block">
</div><div id="l2142" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>socket<span class="k">\_select\_destroy</span>(+SymConName)<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>socket<span class="k">\_select\_destroy</span>/1<span class="nb">}}</span>
</div><div id="l2143" class="code_block">Destroys the specified connection group.
</div><div id="l2144" class="code_block">
</div><div id="l2145" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2146" class="code_block">
</div><div id="l2147" class="code_block">
</div><div id="l2148" class="code_block"><span class="k">\paragraph</span><span class="nb">{</span>Error codes.<span class="nb">}</span>
</div><div id="l2149" class="code_block">The error code argument unifies with the error code returned by the
</div><div id="l2150" class="code_block">corresponding socket commands. The error code -2 signifies
</div><div id="l2151" class="code_block"><span class="k">\emph</span><span class="nb">{</span>timeout<span class="nb">}</span> for timeout-enabled primitives (see below). The error code
</div><div id="l2152" class="code_block">of zero signifies normal termination. Positive error codes denote specific
</div><div id="l2153" class="code_block">failures, as defined in BSD sockets. When such a failure occurs, an error
</div><div id="l2154" class="code_block">message is printed, but the predicate succeeds anyway. The specific error
</div><div id="l2155" class="code_block">codes are part of the socket documentation. Unfortunately, the symbolic
</div><div id="l2156" class="code_block">names and error numbers of these failures are different between Unix
</div><div id="l2157" class="code_block">compilers and Visual C++. Thus, there is no portable, reliable way to refer
</div><div id="l2158" class="code_block">to these error codes. The only reliably portable error codes that can be 
</div><div id="l2159" class="code_block">used in XSB programs defined through these symbolic constants:
</div><div id="l2160" class="code_block"><span class="c">%%</span>
</div><div id="l2161" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2162" class="code_block">#include &quot;socket<span class="nb">_</span>defs<span class="nb">_</span>xsb.h&quot;  
</div><div id="l2163" class="code_block">
</div><div id="l2164" class="code_block">#define SOCK<span class="nb">_</span>OK       0      /* indicates sucessful return from socket      */
</div><div id="l2165" class="code_block">#define SOCK<span class="nb">_</span>EOF     -1      /* end of file in socket<span class="nb">_</span>recv, socket<span class="nb">_</span>get0     */
</div><div id="l2166" class="code_block">
</div><div id="l2167" class="code_block">#include &quot;timer<span class="nb">_</span>defs<span class="nb">_</span>xsb.h&quot;
</div><div id="l2168" class="code_block">
</div><div id="l2169" class="code_block">#define TIMEOUT<span class="nb">_</span>ERR -2                 /* Timeout error code */
</div><div id="l2170" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2171" class="code_block"><span class="c">%%</span>
</div><div id="l2172" class="code_block">
</div><div id="l2173" class="code_block"><span class="k">\paragraph</span><span class="nb">{</span>Timeouts.<span class="nb">}</span>
</div><div id="l2174" class="code_block">XSB socket interface allows the programer to specify timeouts for certain
</div><div id="l2175" class="code_block">operations. If the operations does not finish within the specified period
</div><div id="l2176" class="code_block">of time, the operation is aborted and the corresponding predicate succeeds
</div><div id="l2177" class="code_block">with the <span class="nb">{</span><span class="k">\tt</span> TIMEOUT<span class="k">\_ERR</span><span class="nb">}</span> error code. The following primitives are
</div><div id="l2178" class="code_block">timeout-enabled: <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_connect</span>/4<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_accept</span>/3<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2179" class="code_block">  socket<span class="k">\_recv</span>/3<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_send</span>/3<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_get</span>0/3<span class="nb">}</span>, and <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2180" class="code_block">  socket<span class="k">\_put</span>/3<span class="nb">}</span>.  To set a timeout value for any of the above primitives,
</div><div id="l2181" class="code_block">the user should execute <span class="nb">{</span><span class="k">\tt</span> set<span class="k">\_timer</span>/1<span class="nb">}</span> right before the subgoal to be
</div><div id="l2182" class="code_block">timed. Note that timeouts are disabled after the corresponding timeout-enabled
</div><div id="l2183" class="code_block">call completes or times out. Therefore, one must use <span class="nb">{</span><span class="k">\tt</span> set<span class="k">\_timer</span>/1<span class="nb">}</span>
</div><div id="l2184" class="code_block">before each call that needs to be controlled by a timeout mechanism.
</div><div id="l2185" class="code_block">
</div><div id="l2186" class="code_block">The most common use of timeouts is to either abort or retry the operation
</div><div id="l2187" class="code_block">that times out. For the latter, XSB provides the <span class="nb">{</span><span class="k">\tt</span> sleep/1<span class="nb">}</span> primitive,
</div><div id="l2188" class="code_block">which allows the program to wait for a few seconds before retrying.
</div><div id="l2189" class="code_block">
</div><div id="l2190" class="code_block">The <span class="nb">{</span><span class="k">\tt</span> set<span class="k">\_timer</span>/1<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> sleep/1<span class="nb">}</span> primitives are described below.
</div><div id="l2191" class="code_block">They are standard predicates and do not need to be explicitly imported.
</div><div id="l2192" class="code_block"><span class="c">%%</span>
</div><div id="l2193" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2194" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>set<span class="k">\_timer</span>(+Seconds)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>set<span class="k">\_timer</span>/1<span class="nb">}}</span>
</div><div id="l2195" class="code_block">Set timeout value. If a timer-enabled goal executes after this value is
</div><div id="l2196" class="code_block">set, the clock begins ticking. If the goal does not finish in time, it
</div><div id="l2197" class="code_block">succeeds with the error code set to <span class="nb">{</span><span class="k">\tt</span> TIMEOUT<span class="k">\_ERR</span><span class="nb">}</span>. The timer is turned
</div><div id="l2198" class="code_block">off after the goal executes (whether timed out or not and whether it
</div><div id="l2199" class="code_block">succeeds or fails). This goal always succeeds.
</div><div id="l2200" class="code_block">
</div><div id="l2201" class="code_block">Note that if the timer is not set, the timer-enabled goals execute
</div><div id="l2202" class="code_block">``normally,&#39;&#39; without timeouts. In particular, they might block (say, on
</div><div id="l2203" class="code_block"><span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_recv</span><span class="nb">}</span>, if data is not available).
</div><div id="l2204" class="code_block">
</div><div id="l2205" class="code_block"><span class="k">\ouritem</span><span class="nb">{</span>sleep(+Seconds)<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>sleep/1<span class="nb">}}</span>
</div><div id="l2206" class="code_block">Put XSB to sleep for the specified number of seconds. Execution resumes
</div><div id="l2207" class="code_block">after the <span class="nb">{</span><span class="k">\tt</span> Seconds<span class="nb">}</span> number of seconds. This goal always succeeds.
</div><div id="l2208" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2209" class="code_block"><span class="c">%%</span>
</div><div id="l2210" class="code_block">Here is an example of the use of the timer:
</div><div id="l2211" class="code_block"><span class="c">%%</span>
</div><div id="l2212" class="code_block"><span class="k">\begin</span><span class="nb">{</span>samepage<span class="nb">}</span>
</div><div id="l2213" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2214" class="code_block">:- compiler<span class="nb">_</span>options([xpp<span class="nb">_</span>on]).
</div><div id="l2215" class="code_block">#include &quot;timer<span class="nb">_</span>defs<span class="nb">_</span>xsb.h&quot;
</div><div id="l2216" class="code_block">
</div><div id="l2217" class="code_block">?- set<span class="nb">_</span>timer(3),  <span class="c">% wait for 3 secs</span>
</div><div id="l2218" class="code_block">   socket<span class="nb">_</span>recv(Sockfd, Msg, ErrorCode),
</div><div id="l2219" class="code_block">   (ErrorCode == TIMEOUT<span class="nb">_</span>ERR
</div><div id="l2220" class="code_block">   -&gt; writeln(&#39;Socket read timed out, retrying&#39;),
</div><div id="l2221" class="code_block">      try<span class="nb">_</span>again(Sockfd)
</div><div id="l2222" class="code_block">   ;  write(&#39;Data received: &#39;), writeln(Msg)
</div><div id="l2223" class="code_block">   ).
</div><div id="l2224" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2225" class="code_block"><span class="k">\end</span><span class="nb">{</span>samepage<span class="nb">}</span>
</div><div id="l2226" class="code_block"><span class="c">%%</span>
</div><div id="l2227" class="code_block">
</div><div id="l2228" class="code_block"><span class="k">\noindent</span>
</div><div id="l2229" class="code_block">Apart from the above timer-enabled primitives, a timeout value can be given
</div><div id="l2230" class="code_block">to <span class="nb">{</span><span class="k">\tt</span> socket<span class="k">\_select</span>/6<span class="nb">}</span> directly, as an argument.
</div><div id="l2231" class="code_block">
</div><div id="l2232" class="code_block">
</div><div id="l2233" class="code_block"><span class="k">\paragraph</span><span class="nb">{</span>Buffered, stream-oriented communication.<span class="nb">}</span>
</div><div id="l2234" class="code_block">In Unix, socket descriptors can be ``promoted&#39;&#39; to file streams and the
</div><div id="l2235" class="code_block">regular read/write commands can be used with such streams. In XSB, such
</div><div id="l2236" class="code_block">promotion can be done using the following predicate:
</div><div id="l2237" class="code_block"><span class="c">%%</span>
</div><div id="l2238" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2239" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>fd2ioport(+Pipe, -IOport)<span class="nb">}{</span>shell<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>fd2ioport/2<span class="nb">}}</span> 
</div><div id="l2240" class="code_block">    Take a socket descriptor and convert it to an XSB I/O port that can be used
</div><div id="l2241" class="code_block">    for regular file I/O. 
</div><div id="l2242" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2243" class="code_block"><span class="c">%%</span>
</div><div id="l2244" class="code_block">Once <span class="nb">{</span><span class="k">\tt</span> IOport<span class="nb">}</span> is obtained, all normal I/O primitives can be used by
</div><div id="l2245" class="code_block">specifying the <span class="nb">{</span><span class="k">\tt</span> IOport<span class="nb">}</span> as their first argument. This is, perhaps, the
</div><div id="l2246" class="code_block">easiest and the most convenient way to use sockets in XSB. (This feature
</div><div id="l2247" class="code_block">has not been implemented for Windows.)
</div><div id="l2248" class="code_block">
</div><div id="l2249" class="code_block"><span class="k">\noindent</span>
</div><div id="l2250" class="code_block">Here is an example of the use of this feature:
</div><div id="l2251" class="code_block"><span class="c">%%</span>
</div><div id="l2252" class="code_block"><span class="k">\begin</span><span class="nb">{</span>samepage<span class="nb">}</span>
</div><div id="l2253" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2254" class="code_block">:- compiler<span class="nb">_</span>options([xpp<span class="nb">_</span>on]).
</div><div id="l2255" class="code_block">#include &quot;socket<span class="nb">_</span>defs<span class="nb">_</span>xsb.h&quot;
</div><div id="l2256" class="code_block">
</div><div id="l2257" class="code_block">?- (socket(Sockfd, SOCK<span class="nb">_</span>OK)
</div><div id="l2258" class="code_block">   -&gt;   socket<span class="nb">_</span>connect(Sockfd1, 6020, localhost, Ecode),
</div><div id="l2259" class="code_block">        (Ecode == SOCK<span class="nb">_</span>OK
</div><div id="l2260" class="code_block">        -&gt; fd2ioport(Sockfd, SockIOport),
</div><div id="l2261" class="code_block">           file<span class="nb">_</span>write(SockIOport, &#39;Hello Server!&#39;)
</div><div id="l2262" class="code_block">        ;  writeln(&#39;Can&#39;&#39;t connect to server&#39;)
</div><div id="l2263" class="code_block">        ),
</div><div id="l2264" class="code_block">    ;   writeln(&#39;Can&#39;&#39;t open socket&#39;), fail
</div><div id="l2265" class="code_block">    ).
</div><div id="l2266" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2267" class="code_block"><span class="k">\end</span><span class="nb">{</span>samepage<span class="nb">}</span>
</div><div id="l2268" class="code_block"><span class="c">%%</span>
</div><div id="l2269" class="code_block">
</div><div id="l2270" class="code_block">
</div><div id="l2271" class="code_block"><span class="k">\section</span><span class="nb">{</span>Arrays<span class="nb">}</span>
</div><div id="l2272" class="code_block"><span class="c">%===============</span>
</div><div id="l2273" class="code_block">
</div><div id="l2274" class="code_block">The module <span class="nb">{</span><span class="k">\tt</span> array1<span class="nb">}</span> provides a simple backtrackable array
</div><div id="l2275" class="code_block">implementation that requires no copying.  In Version 3.2, this package
</div><div id="l2276" class="code_block">was changed to make use of the backtrackable destructive assignment
</div><div id="l2277" class="code_block">made possible by <span class="nb">{</span><span class="k">\tt</span> setarg/3<span class="nb">}</span>.  We note that as of Version 3.2 this
</div><div id="l2278" class="code_block">library provides simple syntactic sugar for <span class="nb">{</span><span class="k">\tt</span> functor/3<span class="nb">}</span>, <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2279" class="code_block">  arg/3<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> setarg/3<span class="nb">}</span> and relies on error messages for these
</div><div id="l2280" class="code_block">predicates.
</div><div id="l2281" class="code_block">
</div><div id="l2282" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2283" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>array<span class="k">\_new</span>(-Array,+Size)<span class="nb">}{</span>array<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>array<span class="k">\_new</span>/2<span class="nb">}}</span>
</div><div id="l2284" class="code_block"><span class="c">%</span>
</div><div id="l2285" class="code_block">Creates a one dimensional empty array of size <span class="nb">{</span><span class="k">\tt</span> Size<span class="nb">}</span>.  All the
</div><div id="l2286" class="code_block">elements of this array are variables.  
</div><div id="l2287" class="code_block">
</div><div id="l2288" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>array<span class="k">\_elt</span>(+Array, +Index, ?Element)<span class="nb">}{</span>array<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>array<span class="k">\_elt</span>/3<span class="nb">}}</span> 
</div><div id="l2289" class="code_block"><span class="c">%</span>
</div><div id="l2290" class="code_block">Succeeds iff <span class="nb">{</span><span class="k">\tt</span> Element<span class="nb">}</span> unifies with the <span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span>-th element of
</div><div id="l2291" class="code_block">array <span class="nb">{</span><span class="k">\tt</span> Array<span class="nb">}</span>.  
</div><div id="l2292" class="code_block"><span class="c">%</span>
</div><div id="l2293" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>array<span class="k">\_update</span>(+Array, +Index, +Elem)<span class="nb">}{</span>array<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>array<span class="k">\_update</span>/3<span class="nb">}}</span> 
</div><div id="l2294" class="code_block"><span class="c">%</span>
</div><div id="l2295" class="code_block">Updates the array <span class="nb">{</span><span class="k">\tt</span> Array<span class="nb">}</span> such that the <span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span>-th element of
</div><div id="l2296" class="code_block">the new array is <span class="nb">{</span><span class="k">\tt</span> Elem<span class="nb">}</span> using destructive assignement.  The
</div><div id="l2297" class="code_block">implementation is quite efficient in that it avoids the copying of the
</div><div id="l2298" class="code_block">entire array.
</div><div id="l2299" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2300" class="code_block">
</div><div id="l2301" class="code_block">The following example shows the use of these predicates:
</div><div id="l2302" class="code_block"><span class="nb">{</span><span class="k">\footnotesize</span>
</div><div id="l2303" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2304" class="code_block">| ?- import array<span class="nb">_</span>new/2, array<span class="nb">_</span>elt/3, array<span class="nb">_</span>update/4 from array.
</div><div id="l2305" class="code_block">
</div><div id="l2306" class="code_block">yes
</div><div id="l2307" class="code_block">| ?- array<span class="nb">_</span>new(A,3), array<span class="nb">_</span>update(A,1,1), array<span class="nb">_</span>update(A,2,2),
</div><div id="l2308" class="code_block">     ( array<span class="nb">_</span>update(A,3,3), writeln(first(A))
</div><div id="l2309" class="code_block">     ; array<span class="nb">_</span>update(A,3,6), writeln(second(A))
</div><div id="l2310" class="code_block">     ; array<span class="nb">_</span>update(A,3,7), writeln(third(A))),fail.
</div><div id="l2311" class="code_block">
</div><div id="l2312" class="code_block">first(array(1,2,3))
</div><div id="l2313" class="code_block">second(array(1,2,6))
</div><div id="l2314" class="code_block">third(array(1,2,7))
</div><div id="l2315" class="code_block">
</div><div id="l2316" class="code_block">no
</div><div id="l2317" class="code_block"><span class="k">\end</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2318" class="code_block"><span class="nb">}</span>
</div><div id="l2319" class="code_block">
</div><div id="l2320" class="code_block"><span class="k">\section</span><span class="nb">{</span>The Profiling Library<span class="nb">}</span> <span class="k">\label</span><span class="nb">{</span>sec:profile<span class="nb">}</span>
</div><div id="l2321" class="code_block"><span class="c">%==============================</span>
</div><div id="l2322" class="code_block">
</div><div id="l2323" class="code_block">XSB can provide Prolog-level profiling for Prolog programs, which
</div><div id="l2324" class="code_block">allows the Prolog programmer to determine what proportion of time is
</div><div id="l2325" class="code_block">spent executing code for each predicate.  To enable profiling, XSB
</div><div id="l2326" class="code_block">must be started with the command line parameter of -p.  The module
</div><div id="l2327" class="code_block"><span class="nb">{</span><span class="k">\tt</span> xsb<span class="k">\_profiling</span><span class="nb">}</span> contains the predicate <span class="nb">{</span><span class="k">\tt</span> profile<span class="k">\_call</span>/1<span class="nb">}</span> that
</div><div id="l2328" class="code_block">invokes profiling~<span class="k">\footnote</span><span class="nb">{</span>The profiling library should only be used
</div><div id="l2329" class="code_block">  with the single-threaded engine in <span class="k">\version</span><span class="nb">{}</span>.<span class="nb">}</span>.
</div><div id="l2330" class="code_block">
</div><div id="l2331" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2332" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>profile<span class="k">\_call</span>(+Goal)<span class="nb">}{</span>xsb<span class="k">\_profiling</span><span class="nb">}</span><span class="k">\index</span><span class="nb">{</span>profile<span class="k">\_call</span>/1<span class="nb">}</span>
</div><div id="l2333" class="code_block">
</div><div id="l2334" class="code_block">Calls the goal <span class="nb">{</span><span class="k">\tt</span> Goal<span class="nb">}</span>, and when it first returns, prints out (on
</div><div id="l2335" class="code_block">userout) a table of predicate names indicating for each, the
</div><div id="l2336" class="code_block">percentage of time spent executing that predicate&#39;s code.  XSB must
</div><div id="l2337" class="code_block">have been started with the -p command line parameter to obtain this
</div><div id="l2338" class="code_block">table.  The percentages are accumulated by module.  <span class="nb">{</span><span class="k">\tt</span> Goal<span class="nb">}</span> may
</div><div id="l2339" class="code_block">backtrack, but profiling is done only for the time to the first
</div><div id="l2340" class="code_block">success.  So it is most appropriate to profile succeeding
</div><div id="l2341" class="code_block">deterministic goals.
</div><div id="l2342" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2343" class="code_block">
</div><div id="l2344" class="code_block">Profiling works by starting another thread that interrupts every 100th
</div><div id="l2345" class="code_block">of a second and sets a flag so that the XSB emulator will determine
</div><div id="l2346" class="code_block">the predicate of the currently executing code.  The printout also
</div><div id="l2347" class="code_block">includes the total number of interrupts and for each predicate, the
</div><div id="l2348" class="code_block">raw number of times its code was determined to be executing.  A
</div><div id="l2349" class="code_block">predicate is printed only if its code was interrupted at least once.
</div><div id="l2350" class="code_block">The numbers will be meaningful only for relatively long-running
</div><div id="l2351" class="code_block">predicates, taking more than a couple of seconds.
</div><div id="l2352" class="code_block">
</div><div id="l2353" class="code_block">When an interrupt occurs, the <span class="nb">{</span><span class="k">\bf</span> next<span class="nb">}</span> WAM call, execute, proceed or
</div><div id="l2354" class="code_block">trust instruction to be executed will log its associated predicate.
</div><div id="l2355" class="code_block">The system does not keep track of code addresses for tries (used to
</div><div id="l2356" class="code_block">represent the results of completed tables, and trie-indexed asserted
</div><div id="l2357" class="code_block">code), so for some interrupts the associated executing predicate
</div><div id="l2358" class="code_block">cannot be determined.  In these cases the interrupt is charged against
</div><div id="l2359" class="code_block">an ``unknown/?&#39;&#39; pseudo-predicate, and this count is included in the
</div><div id="l2360" class="code_block">output.
</div><div id="l2361" class="code_block">
</div><div id="l2362" class="code_block">Profiling does not give the context from which the predicate is
</div><div id="l2363" class="code_block">called, so you may want to make renamed copies of basic predicates to
</div><div id="l2364" class="code_block">use in particular circumstances to determine their times.
</div><div id="l2365" class="code_block">
</div><div id="l2366" class="code_block">Predicates compiled with the ``optimize&#39;&#39; option may provide
</div><div id="l2367" class="code_block">misleading results under profiling.  Note that all system predicates
</div><div id="l2368" class="code_block">(including those in <span class="nb">{</span><span class="k">\tt</span> basics<span class="nb">}</span>) are compiled with the ``optimize&#39;&#39;
</div><div id="l2369" class="code_block">option, by default.  That option causes tail-recursive predicates to
</div><div id="l2370" class="code_block">use a ``jump&#39;&#39; instruction rather than an ``execute&#39;&#39; instruction to
</div><div id="l2371" class="code_block">make the recursive call, and so an interrupt in such a loop will not
</div><div id="l2372" class="code_block">be charged until the next <span class="nb">{</span><span class="k">\bf</span> logging<span class="nb">}</span> instruction is executed.  If
</div><div id="l2373" class="code_block">much time is spent in the recursion, this might not be for a long
</div><div id="l2374" class="code_block">time, and the interrupt might ultimately be charged to another
</div><div id="l2375" class="code_block">predicate.  (If an interrupt has not been charged by the time of the
</div><div id="l2376" class="code_block">next interrupt, it is lost.)
</div><div id="l2377" class="code_block">
</div><div id="l2378" class="code_block">Profiling currently works under Windows, and somewhat under Linux.
</div><div id="l2379" class="code_block">For the profiling algorithm to work, the thread that wakes and sets
</div><div id="l2380" class="code_block">the interrupt flag must be of high priority and given the CPU when it
</div><div id="l2381" class="code_block">wants it.  I haven&#39;t figured out how to get this scheduling on some
</div><div id="l2382" class="code_block">machines, so if you want profiling to work somewhere it doesn&#39;t, maybe
</div><div id="l2383" class="code_block">you can help figure out how to get appropriate scheduling.
</div><div id="l2384" class="code_block">
</div><div id="l2385" class="code_block">The profiling module also provides some support for determining the
</div><div id="l2386" class="code_block">modes in which a predicate is called.  This can be used to determine
</div><div id="l2387" class="code_block">whether indexing is appropriately declared for important dynamic
</div><div id="l2388" class="code_block">predicates.  This is a primitive facility, but has been found useful.
</div><div id="l2389" class="code_block">
</div><div id="l2390" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2391" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>profile<span class="k">\_mode\_call</span>(+Goal)<span class="nb">}{</span>xsb<span class="k">\_profiling</span><span class="nb">}</span><span class="k">\index</span><span class="nb">{</span>profile<span class="k">\_mode\_call</span>/1<span class="nb">}</span>
</div><div id="l2392" class="code_block">
</div><div id="l2393" class="code_block">Calls the goal <span class="nb">{</span><span class="k">\tt</span> Goal<span class="nb">}</span> and constructs a table of the modes in which
</div><div id="l2394" class="code_block">the predicate is called and the number of times it is called in that
</div><div id="l2395" class="code_block">mode.  Modes are simply ``b&#39;&#39; for ground and ``f&#39;&#39; for variable.
</div><div id="l2396" class="code_block">Counts are kept in a table with entries of the form <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2397" class="code_block">Pred(Md1,Md2,..,Mdn)<span class="nb">}</span> where Pred is the name of the called predicate
</div><div id="l2398" class="code_block">and the Mdi are either &#39;f&#39; or &#39;b&#39;, indicating free or bound for the
</div><div id="l2399" class="code_block">corresponding argument.  The table can be printed using <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2400" class="code_block">profile<span class="k">\_mode\_dump</span>/0<span class="nb">}</span> and can be cleared using <span class="nb">{</span><span class="k">\tt</span> profile<span class="k">\_mode\_init</span>/0<span class="nb">}</span>.
</div><div id="l2401" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2402" class="code_block">
</div><div id="l2403" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2404" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>profile<span class="k">\_mode\_dump</span><span class="nb">}{</span>xsb<span class="k">\_profiling</span><span class="nb">}</span><span class="k">\index</span><span class="nb">{</span>profile<span class="k">\_mode\_dump</span>/0<span class="nb">}</span>
</div><div id="l2405" class="code_block">
</div><div id="l2406" class="code_block">Prints out the counts of calls in particular modes as accumulated using <span class="k">\\</span>
</div><div id="l2407" class="code_block"><span class="nb">{</span><span class="k">\tt</span> profile<span class="k">\_mode\_call</span>(+Goal)<span class="nb">}</span>.
</div><div id="l2408" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2409" class="code_block">
</div><div id="l2410" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2411" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>profile<span class="k">\_mode\_init</span><span class="nb">}{</span>xsb<span class="k">\_profiling</span><span class="nb">}</span><span class="k">\index</span><span class="nb">{</span>profile<span class="k">\_mode\_init</span>/0<span class="nb">}</span>
</div><div id="l2412" class="code_block">
</div><div id="l2413" class="code_block">Clears the table that accumulates counts of calls in particular modes
</div><div id="l2414" class="code_block">(done by<span class="k">\\</span> <span class="nb">{</span><span class="k">\tt</span> profile<span class="k">\_mode\_call</span>(+Goal)<span class="nb">}</span>.
</div><div id="l2415" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2416" class="code_block">
</div><div id="l2417" class="code_block">
</div><div id="l2418" class="code_block"><span class="c">%----------------------------------------------------------------------</span>
</div><div id="l2419" class="code_block"><span class="k">\comment</span><span class="nb">{</span>
</div><div id="l2420" class="code_block"><span class="c">% Replaced by tries section in volume 1.</span>
</div><div id="l2421" class="code_block">
</div><div id="l2422" class="code_block"><span class="k">\section</span><span class="nb">{</span>Low-level Trie Manipulation Utilities<span class="nb">}</span>
</div><div id="l2423" class="code_block">
</div><div id="l2424" class="code_block">Chapter 8 of Volume 1 indicates how tries can be used as an efficient
</div><div id="l2425" class="code_block">mechanism to store thread-private and thread-shared terms.  However,
</div><div id="l2426" class="code_block">while they are efficient, the trie manipulation routines in Chapter 8
</div><div id="l2427" class="code_block">of Volume 1 may not be suitable
</div><div id="l2428" class="code_block">
</div><div id="l2429" class="code_block">and thread-safe manner Interned tries can be used to assert an retract
</div><div id="l2430" class="code_block">facts in an extremely efficient manner.  Terms can be interned within
</div><div id="l2431" class="code_block">different tries, designated by a <span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span>, or left as default.  Like
</div><div id="l2432" class="code_block">trie-indexed dynamic code and unlike normal asserted code, interned
</div><div id="l2433" class="code_block">tries have a set semantics: the variant of a term can occur in a trie
</div><div id="l2434" class="code_block">only once, additional asserts have no effect.  In addition, no
</div><div id="l2435" class="code_block">ordering of terms within the trie is guaranteed.  In <span class="k">\version</span><span class="nb">{}</span> of
</div><div id="l2436" class="code_block">XSB, when multiple threads are used, all interned tries are private to
</div><div id="l2437" class="code_block">a thread, so that information interned by one trie will not be visible
</div><div id="l2438" class="code_block">to other threads.  In order to ensure efficiency for these routines,
</div><div id="l2439" class="code_block">not all possible error checking is done on their inputs.
</div><div id="l2440" class="code_block">
</div><div id="l2441" class="code_block">
</div><div id="l2442" class="code_block">Section~<span class="k">\ref</span><span class="nb">{</span>sec:intern-basic<span class="nb">}</span> below provides an overview for the
</div><div id="l2443" class="code_block">basic interface to interned tries, while
</div><div id="l2444" class="code_block">Section~<span class="k">\ref</span><span class="nb">{</span>sec:intern-advanced<span class="nb">}</span> describes more advanced features.
</div><div id="l2445" class="code_block">See also the module <span class="nb">{</span><span class="k">\tt</span> storage<span class="nb">}</span> in Volume 1 which uses interned
</div><div id="l2446" class="code_block">tries for backtrackable updates and associative arrays.
</div><div id="l2447" class="code_block">
</div><div id="l2448" class="code_block"><span class="k">\subsection</span><span class="nb">{</span>A Basic API for Interned Tries<span class="nb">}</span> <span class="k">\label</span><span class="nb">{</span>sec:intern-basic<span class="nb">}</span>
</div><div id="l2449" class="code_block"><span class="c">%%</span>
</div><div id="l2450" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2451" class="code_block">  <span class="c">%%</span>
</div><div id="l2452" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>new<span class="k">\_trie</span>(-Root)<span class="nb">}{</span>intern<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>newtrie/1<span class="nb">}}</span>
</div><div id="l2453" class="code_block">        <span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is instantiated to a handle for a new trie.
</div><div id="l2454" class="code_block">
</div><div id="l2455" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>trie<span class="k">\_intern</span>(+Term,+Root)<span class="nb">}{</span>intern<span class="nb">}</span>
</div><div id="l2456" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>trie<span class="k">\_intern</span>/2<span class="nb">}}</span>
</div><div id="l2457" class="code_block"><span class="c">% </span>
</div><div id="l2458" class="code_block">Effectively asserts <span class="k">\texttt</span><span class="nb">{</span>Term<span class="nb">}</span> by interning into the trie
</div><div id="l2459" class="code_block">designated by <span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span>.  If a variant of <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span> is already in
</div><div id="l2460" class="code_block"><span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> the predicate succeeds, but a new copy of <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span> is not
</div><div id="l2461" class="code_block">added to the trie.
</div><div id="l2462" class="code_block">
</div><div id="l2463" class="code_block"><span class="nb">{</span><span class="k">\bf</span> Error Cases<span class="nb">}</span>
</div><div id="l2464" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2465" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is uninstantiated
</div><div id="l2466" class="code_block"><span class="k">\bi</span>
</div><div id="l2467" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> instantiation<span class="k">\_error</span><span class="nb">}</span>
</div><div id="l2468" class="code_block"><span class="k">\ei</span>
</div><div id="l2469" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is instantiated, but not an integer (trie handle)
</div><div id="l2470" class="code_block"><span class="k">\bi</span>
</div><div id="l2471" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(integer,Root)<span class="nb">}</span>
</div><div id="l2472" class="code_block"><span class="k">\ei</span>
</div><div id="l2473" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2474" class="code_block"><span class="c">%%</span>
</div><div id="l2475" class="code_block">
</div><div id="l2476" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>trie<span class="k">\_interned</span>(?Term,+Root)<span class="nb">}{</span>intern<span class="nb">}</span>
</div><div id="l2477" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>trie<span class="k">\_interned</span>/2<span class="nb">}}</span>
</div><div id="l2478" class="code_block"><span class="c">%%</span>
</div><div id="l2479" class="code_block">This predicate backtracks through the terms that unify with <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span>
</div><div id="l2480" class="code_block">and that are interned into the trie represented by the handle <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2481" class="code_block">  Root<span class="nb">}</span>.  <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span> may be free, or partially bound.
</div><div id="l2482" class="code_block">
</div><div id="l2483" class="code_block"><span class="nb">{</span><span class="k">\bf</span> Error Cases<span class="nb">}</span>
</div><div id="l2484" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2485" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is uninstantiated
</div><div id="l2486" class="code_block"><span class="k">\bi</span>
</div><div id="l2487" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> instantiation<span class="k">\_error</span><span class="nb">}</span>
</div><div id="l2488" class="code_block"><span class="k">\ei</span>
</div><div id="l2489" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is instantiated, but not an integer (trie handle)
</div><div id="l2490" class="code_block"><span class="k">\bi</span>
</div><div id="l2491" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(integer,Root)<span class="nb">}</span>
</div><div id="l2492" class="code_block"><span class="k">\ei</span>
</div><div id="l2493" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2494" class="code_block"><span class="c">%%</span>
</div><div id="l2495" class="code_block">
</div><div id="l2496" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>delete<span class="k">\_trie</span>(+Root)<span class="nb">}{</span>intern<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>delete<span class="k">\_trie</span>/1<span class="nb">}}</span>
</div><div id="l2497" class="code_block"><span class="c">%%</span>
</div><div id="l2498" class="code_block">Deletes all the terms in the trie pointed to by <span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span>.
</div><div id="l2499" class="code_block">
</div><div id="l2500" class="code_block"><span class="nb">{</span><span class="k">\bf</span> Error Cases<span class="nb">}</span>
</div><div id="l2501" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2502" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is uninstantiated
</div><div id="l2503" class="code_block"><span class="k">\bi</span>
</div><div id="l2504" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> instantiation<span class="k">\_error</span><span class="nb">}</span>
</div><div id="l2505" class="code_block"><span class="k">\ei</span>
</div><div id="l2506" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is instantiated, but not an integer (trie handle)
</div><div id="l2507" class="code_block"><span class="k">\bi</span>
</div><div id="l2508" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(integer,Root)<span class="nb">}</span>
</div><div id="l2509" class="code_block"><span class="k">\ei</span>
</div><div id="l2510" class="code_block"><span class="k">\item</span> 	Failure continuations point to one or more nodes in the trie with root <span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span>
</div><div id="l2511" class="code_block"><span class="k">\bi</span>
</div><div id="l2512" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> misc<span class="k">\_error</span><span class="nb">}</span>
</div><div id="l2513" class="code_block"><span class="k">\ei</span>
</div><div id="l2514" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2515" class="code_block"><span class="c">%%</span>
</div><div id="l2516" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2517" class="code_block">
</div><div id="l2518" class="code_block"><span class="c">%=======================</span>
</div><div id="l2519" class="code_block">
</div><div id="l2520" class="code_block"><span class="k">\subsection</span><span class="nb">{</span>Low-level Trie Manipulation Utilities<span class="nb">}</span> <span class="k">\label</span><span class="nb">{</span>sec:intern-advanced<span class="nb">}</span>
</div><div id="l2521" class="code_block">
</div><div id="l2522" class="code_block">The utilities in this section are very low-level and require good
</div><div id="l2523" class="code_block">understanding of the trie mechanism in XSB.  Improper calls to these
</div><div id="l2524" class="code_block">predicates can cause core dumps, particularly if an improper trie
</div><div id="l2525" class="code_block">value is passed to them.  Despite these drawbacks, they can be used to
</div><div id="l2526" class="code_block">implement modules such as the <span class="nb">{</span><span class="k">\tt</span> storage<span class="nb">}</span> module described in Volume
</div><div id="l2527" class="code_block">1.
</div><div id="l2528" class="code_block">
</div><div id="l2529" class="code_block"><span class="c">%%</span>
</div><div id="l2530" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2531" class="code_block">  <span class="c">%%</span>
</div><div id="l2532" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>trie<span class="k">\_intern</span>(+Term,+Root,-Leaf,-Flag,-Skel)<span class="nb">}{</span>intern<span class="nb">}</span>
</div><div id="l2533" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>trie<span class="k">\_intern</span>/5<span class="nb">}}</span>
</div><div id="l2534" class="code_block"><span class="c">%%</span>
</div><div id="l2535" class="code_block">Acts as <span class="nb">{</span><span class="k">\tt</span> trie<span class="k">\_intern</span>/2<span class="nb">}</span> but returns additional information: <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2536" class="code_block">  Leaf<span class="nb">}</span> is the handle for the interned <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span> in the trie.  <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2537" class="code_block">  Flag<span class="nb">}</span> is 1 if the term is ``old&#39;&#39; (already exists in the trie); it
</div><div id="l2538" class="code_block">is 0, if the term is newly inserted.  <span class="nb">{</span><span class="k">\tt</span> Skel<span class="nb">}</span> represents the
</div><div id="l2539" class="code_block">collection of all the variables in <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span>. It has the form <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2540" class="code_block">  ret(V1,V2,...,VN)<span class="nb">}</span>, exactly as in <span class="nb">{</span><span class="k">\tt</span> get<span class="k">\_calls</span><span class="nb">}</span> (see Vol. 1 of
</div><div id="l2541" class="code_block">the XSB manual).
</div><div id="l2542" class="code_block">
</div><div id="l2543" class="code_block"><span class="nb">{</span><span class="k">\bf</span> Error Cases<span class="nb">}</span>
</div><div id="l2544" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2545" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is uninstantiated
</div><div id="l2546" class="code_block"><span class="k">\bi</span>
</div><div id="l2547" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> instantiation<span class="k">\_error</span><span class="nb">}</span>
</div><div id="l2548" class="code_block"><span class="k">\ei</span>
</div><div id="l2549" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is instantiated, but not an integer (trie handle)
</div><div id="l2550" class="code_block"><span class="k">\bi</span>
</div><div id="l2551" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(integer,Root)<span class="nb">}</span>
</div><div id="l2552" class="code_block"><span class="k">\ei</span>
</div><div id="l2553" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2554" class="code_block"><span class="c">%%</span>
</div><div id="l2555" class="code_block">
</div><div id="l2556" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>trie<span class="k">\_intern</span>(+Term,-Leaf,-Skel)<span class="nb">}{</span>intern<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>trie<span class="k">\_intern</span>/3<span class="nb">}}</span>
</div><div id="l2557" class="code_block"><span class="c">%%</span>
</div><div id="l2558" class="code_block">Acts as <span class="nb">{</span><span class="k">\tt</span> trie<span class="k">\_intern</span>/5<span class="nb">}</span>, but interns <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span> into the default
</div><div id="l2559" class="code_block">trie and does not return the new/old flag.
</div><div id="l2560" class="code_block">
</div><div id="l2561" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>trie<span class="k">\_interned</span>(?Term,+Root,?Leaf,-Skel)<span class="nb">}{</span>intern<span class="nb">}</span>
</div><div id="l2562" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>trie<span class="k">\_interned</span>/4<span class="nb">}}</span>
</div><div id="l2563" class="code_block"><span class="c">%%</span>
</div><div id="l2564" class="code_block">This predicate backtracks through the terms that unify with <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span>
</div><div id="l2565" class="code_block">interned into the trie represented by the handle <span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> if <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2566" class="code_block">  Leaf<span class="nb">}</span> is a free variable.  Otherwise, if <span class="nb">{</span><span class="k">\tt</span> Leaf<span class="nb">}</span> is bound, it
</div><div id="l2567" class="code_block">will backtrack over the terms in the trie that unify with the term
</div><div id="l2568" class="code_block">pointed to by Leaf <span class="nb">{</span><span class="k">\tt</span> to<span class="nb">}</span>.  <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span> is the term to be retrieved;
</div><div id="l2569" class="code_block">it can be either (partially) bound or free.  <span class="nb">{</span><span class="k">\tt</span> Skel<span class="nb">}</span> is the
</div><div id="l2570" class="code_block">collection of all the variables in <span class="nb">{</span><span class="k">\tt</span> Term<span class="nb">}</span>; it has the form <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2571" class="code_block">  ret(V1,...,Vn)<span class="nb">}</span>.
</div><div id="l2572" class="code_block">
</div><div id="l2573" class="code_block"><span class="nb">{</span><span class="k">\bf</span> Error Cases<span class="nb">}</span>
</div><div id="l2574" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2575" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is uninstantiated
</div><div id="l2576" class="code_block"><span class="k">\bi</span>
</div><div id="l2577" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> instantiation<span class="k">\_error</span><span class="nb">}</span>
</div><div id="l2578" class="code_block"><span class="k">\ei</span>
</div><div id="l2579" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is instantiated, but not an integer (trie handle)
</div><div id="l2580" class="code_block"><span class="k">\bi</span>
</div><div id="l2581" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(integer,Root)<span class="nb">}</span>
</div><div id="l2582" class="code_block"><span class="k">\ei</span>
</div><div id="l2583" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2584" class="code_block"><span class="c">%%</span>
</div><div id="l2585" class="code_block">
</div><div id="l2586" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>trie<span class="k">\_interned</span>(?Term,?Leaf,-Skel)<span class="nb">}{</span>intern<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>trie<span class="k">\_interned</span>/3<span class="nb">}}</span>
</div><div id="l2587" class="code_block"><span class="c">%%</span>
</div><div id="l2588" class="code_block">Similar to <span class="nb">{</span><span class="k">\tt</span> trie<span class="k">\_interned</span>/4<span class="nb">}</span>  but uses the default trie.
</div><div id="l2589" class="code_block">
</div><div id="l2590" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>trie<span class="k">\_unintern</span>(+Root,+Leaf)<span class="nb">}{</span>intern<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>trie<span class="k">\_unintern</span>/2<span class="nb">}}</span>
</div><div id="l2591" class="code_block"><span class="c">%%</span>
</div><div id="l2592" class="code_block">Uninterns a term indicated by <span class="nb">{</span><span class="k">\tt</span> Leaf<span class="nb">}</span> from the trie indicated by
</div><div id="l2593" class="code_block">root.  If there are failure continuations that point to trie nodes in
</div><div id="l2594" class="code_block"><span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span>, the term is marked as deleted but space is not reclaimed.
</div><div id="l2595" class="code_block">Otherwise, the term is really deleted.
</div><div id="l2596" class="code_block"><span class="c">%%</span>
</div><div id="l2597" class="code_block">
</div><div id="l2598" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>trie<span class="k">\_unintern\_nr</span>(+Root,+Leaf)<span class="nb">}{</span>intern<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>trie<span class="k">\_unintern\_nr</span>/2<span class="nb">}}</span>
</div><div id="l2599" class="code_block"><span class="c">%%</span>
</div><div id="l2600" class="code_block">This is a safe version of <span class="nb">{</span><span class="k">\tt</span> trie<span class="k">\_unintern</span>/2<span class="nb">}</span>. The term pointed to by
</div><div id="l2601" class="code_block"><span class="nb">{</span><span class="k">\tt</span> Leaf<span class="nb">}</span> is marked as deleted, but is not deleted from the trie. This
</div><div id="l2602" class="code_block">permits an efficient implementation of backtrackable updates.
</div><div id="l2603" class="code_block">
</div><div id="l2604" class="code_block"><span class="nb">{</span><span class="k">\bf</span> Error Cases<span class="nb">}</span>
</div><div id="l2605" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2606" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> or <span class="nb">{</span><span class="k">\tt</span> Leaf<span class="nb">}</span> is uninstantiated
</div><div id="l2607" class="code_block"><span class="k">\bi</span>
</div><div id="l2608" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> instantiation<span class="k">\_error</span><span class="nb">}</span>
</div><div id="l2609" class="code_block"><span class="k">\ei</span>
</div><div id="l2610" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> or <span class="nb">{</span><span class="k">\tt</span> Leaf<span class="nb">}</span> is instantiated, but not an integer
</div><div id="l2611" class="code_block">  (trie handle or trie leaf) 
</div><div id="l2612" class="code_block"><span class="k">\bi</span>
</div><div id="l2613" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(integer,Root)<span class="nb">}</span> or <span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(integer,Leaf)<span class="nb">}</span>
</div><div id="l2614" class="code_block"><span class="k">\ei</span>
</div><div id="l2615" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2616" class="code_block"><span class="c">%%</span>
</div><div id="l2617" class="code_block">
</div><div id="l2618" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>unmark<span class="k">\_uninterned\_nr</span>(+Root,+Leaf)<span class="nb">}{</span>intern<span class="nb">}</span><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>unmark<span class="k">\_uninterned\_nr</span>/2<span class="nb">}}</span>
</div><div id="l2619" class="code_block">The term pointed to by <span class="nb">{</span><span class="k">\tt</span> Leaf<span class="nb">}</span> should have been previously marked for
</div><div id="l2620" class="code_block">deletion using
</div><div id="l2621" class="code_block"><span class="nb">{</span><span class="k">\tt</span> trie<span class="k">\_unintern\_nr</span>/2<span class="nb">}</span>. This term is then ``unmarked&#39;&#39; (or undeleted)
</div><div id="l2622" class="code_block">and becomes again a normal interned term.
</div><div id="l2623" class="code_block">
</div><div id="l2624" class="code_block"><span class="nb">{</span><span class="k">\bf</span> Error Cases<span class="nb">}</span>
</div><div id="l2625" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2626" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> or <span class="nb">{</span><span class="k">\tt</span> Leaf<span class="nb">}</span> is uninstantiated
</div><div id="l2627" class="code_block"><span class="k">\bi</span>
</div><div id="l2628" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> instantiation<span class="k">\_error</span><span class="nb">}</span>
</div><div id="l2629" class="code_block"><span class="k">\ei</span>
</div><div id="l2630" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> or <span class="nb">{</span><span class="k">\tt</span> Leaf<span class="nb">}</span> is instantiated, but not an integer
</div><div id="l2631" class="code_block">  (trie handle or trie leaf) 
</div><div id="l2632" class="code_block"><span class="k">\bi</span>
</div><div id="l2633" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(integer,Root)<span class="nb">}</span> or <span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(integer,Leaf)<span class="nb">}</span>
</div><div id="l2634" class="code_block"><span class="k">\ei</span>
</div><div id="l2635" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2636" class="code_block"><span class="c">%%</span>
</div><div id="l2637" class="code_block">
</div><div id="l2638" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>reclaim<span class="k">\_uninterned\_nr</span>(+Root)<span class="nb">}{</span>intern<span class="nb">}</span>
</div><div id="l2639" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>reclaim<span class="k">\_uninterned\_rn</span>/1<span class="nb">}}</span>
</div><div id="l2640" class="code_block"><span class="c">%%</span>
</div><div id="l2641" class="code_block">Runs through the chain of leaves of the trie <span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> and deletes
</div><div id="l2642" class="code_block">the terms that have been marked for deletion by <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2643" class="code_block">  trie<span class="k">\_unintern\_nr</span>/2<span class="nb">}</span>. This is a garbage collection step that should
</div><div id="l2644" class="code_block">be done just before returning to the top level or when it can
</div><div id="l2645" class="code_block">otherwise be ensure that no failure continuations point to a node in
</div><div id="l2646" class="code_block"><span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span>.
</div><div id="l2647" class="code_block">
</div><div id="l2648" class="code_block"><span class="nb">{</span><span class="k">\bf</span> Error Cases<span class="nb">}</span>
</div><div id="l2649" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2650" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is uninstantiated
</div><div id="l2651" class="code_block"><span class="k">\bi</span>
</div><div id="l2652" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> instantiation<span class="k">\_error</span><span class="nb">}</span>
</div><div id="l2653" class="code_block"><span class="k">\ei</span>
</div><div id="l2654" class="code_block"><span class="k">\item</span> 	<span class="nb">{</span><span class="k">\tt</span> Root<span class="nb">}</span> is instantiated, but not an integer (trie handle)
</div><div id="l2655" class="code_block"><span class="k">\bi</span>
</div><div id="l2656" class="code_block"><span class="k">\item</span> 	 <span class="nb">{</span><span class="k">\tt</span> type<span class="k">\_error</span>(integer,Root)<span class="nb">}</span>
</div><div id="l2657" class="code_block"><span class="k">\ei</span>
</div><div id="l2658" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2659" class="code_block">
</div><div id="l2660" class="code_block">
</div><div id="l2661" class="code_block"><span class="c">%%</span>
</div><div id="l2662" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2663" class="code_block"><span class="nb">}</span>
</div><div id="l2664" class="code_block"><span class="k">\section</span><span class="nb">{</span>Gensym<span class="nb">}</span>
</div><div id="l2665" class="code_block"><span class="c">%================================</span>
</div><div id="l2666" class="code_block">
</div><div id="l2667" class="code_block">The Gensym library provides a convenient way to generate unique
</div><div id="l2668" class="code_block">integers or constants.  
</div><div id="l2669" class="code_block">
</div><div id="l2670" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2671" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>prepare(+Index)<span class="nb">}{</span>gensym<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>prepare/1<span class="nb">}}</span>
</div><div id="l2672" class="code_block"><span class="c">%</span>
</div><div id="l2673" class="code_block">Sets the initial integer to be used for generation to <span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span>.
</div><div id="l2674" class="code_block">Thus, the command <span class="nb">{</span><span class="k">\tt</span> ?- prepare(0)<span class="nb">}</span> would cause the first call to
</div><div id="l2675" class="code_block"><span class="nb">{</span><span class="k">\tt</span> gennum/1<span class="nb">}</span> to return <span class="nb">{</span><span class="k">\tt</span> 1<span class="nb">}</span>.  <span class="nb">{</span><span class="k">\tt</span> Index<span class="nb">}</span> must be a non-negative
</div><div id="l2676" class="code_block">integer.
</div><div id="l2677" class="code_block">
</div><div id="l2678" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>gennum(-Var)<span class="nb">}{</span>gensym<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>gennum/1<span class="nb">}}</span>
</div><div id="l2679" class="code_block"><span class="c">%</span>
</div><div id="l2680" class="code_block">Unifies <span class="nb">{</span><span class="k">\tt</span> Var<span class="nb">}</span> with a new integer.
</div><div id="l2681" class="code_block">
</div><div id="l2682" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>gensym(+Atom,-Var)<span class="nb">}{</span>gensym<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>gensym/2<span class="nb">}}</span>
</div><div id="l2683" class="code_block"><span class="c">%</span>
</div><div id="l2684" class="code_block">Generates a new integer, and concatenates this integer with <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2685" class="code_block">Atom<span class="nb">}</span>, unifying the result with <span class="nb">{</span><span class="k">\tt</span> Var<span class="nb">}</span>.  For instance a call <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2686" class="code_block">?- gensym(foo,Var)<span class="nb">}</span> might unify <span class="nb">{</span><span class="k">\tt</span> Var<span class="nb">}</span> with <span class="nb">{</span><span class="k">\tt</span> foo32<span class="nb">}</span>.
</div><div id="l2687" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2688" class="code_block">
</div><div id="l2689" class="code_block"><span class="k">\section</span><span class="nb">{</span>Random Number Generator<span class="nb">}</span>
</div><div id="l2690" class="code_block"><span class="c">%================================</span>
</div><div id="l2691" class="code_block">
</div><div id="l2692" class="code_block">The following predicates are provided in module <span class="k">\texttt</span><span class="nb">{</span>random<span class="nb">}</span> to
</div><div id="l2693" class="code_block">generate random numbers (both integers and floating numbers), based on
</div><div id="l2694" class="code_block">the Wichmann-Hill Algorithm <span class="k">\cite</span><span class="nb">{</span>WicH82,McLe85<span class="nb">}</span>.  The random number
</div><div id="l2695" class="code_block">generator is entirely portable, and does not require any calls to the
</div><div id="l2696" class="code_block">operating system.  As noted below, it does require 3 seeds, each of
</div><div id="l2697" class="code_block">which must be an integer in a given range.  These seeds are
</div><div id="l2698" class="code_block">thread-specific: thus different threads may generate independent
</div><div id="l2699" class="code_block">sequences of random numbers.
</div><div id="l2700" class="code_block">
</div><div id="l2701" class="code_block"><span class="k">\index</span><span class="nb">{</span>Random Variables<span class="nb">}</span>
</div><div id="l2702" class="code_block">
</div><div id="l2703" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2704" class="code_block">
</div><div id="l2705" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>random(-Number)<span class="nb">}{</span>random<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>random/1<span class="nb">}}</span>
</div><div id="l2706" class="code_block"><span class="c">%</span>
</div><div id="l2707" class="code_block">Binds <span class="k">\texttt</span><span class="nb">{</span>Number<span class="nb">}</span> to a random float in the interval [0.0, 1.0).
</div><div id="l2708" class="code_block">Note that 1.0 will never be generated.
</div><div id="l2709" class="code_block">
</div><div id="l2710" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>random(+Lower,+Upper,-Number)<span class="nb">}{</span>random<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>random/3<span class="nb">}}</span>
</div><div id="l2711" class="code_block">    Binds <span class="k">\texttt</span><span class="nb">{</span>Number<span class="nb">}</span> to a random integer in the interval
</div><div id="l2712" class="code_block">    [<span class="k">\texttt</span><span class="nb">{</span>Lower<span class="nb">}</span>,<span class="k">\texttt</span><span class="nb">{</span>Upper<span class="nb">}</span>) if <span class="k">\texttt</span><span class="nb">{</span>Lower<span class="nb">}</span> and <span class="k">\texttt</span><span class="nb">{</span>Upper<span class="nb">}</span>
</div><div id="l2713" class="code_block">    are integers.  Otherwise <span class="k">\texttt</span><span class="nb">{</span>Number<span class="nb">}</span> is bound to a random float
</div><div id="l2714" class="code_block">    between <span class="k">\texttt</span><span class="nb">{</span>Lower<span class="nb">}</span> and <span class="k">\texttt</span><span class="nb">{</span>Upper<span class="nb">}</span>.  <span class="k">\texttt</span><span class="nb">{</span>Upper<span class="nb">}</span> will
</div><div id="l2715" class="code_block">    never be generated.
</div><div id="l2716" class="code_block">
</div><div id="l2717" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>getrand(?State)<span class="nb">}{</span>random<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>getrand/1<span class="nb">}}</span>
</div><div id="l2718" class="code_block">    Tries to unify <span class="k">\texttt</span><span class="nb">{</span>State<span class="nb">}</span> with the term <span class="k">\texttt</span><span class="nb">{</span>rand(X,Y,Z)<span class="nb">}</span>
</div><div id="l2719" class="code_block">    where <span class="k">\texttt</span><span class="nb">{</span>X<span class="nb">}</span>,<span class="k">\texttt</span><span class="nb">{</span>Y<span class="nb">}</span>,and <span class="k">\texttt</span><span class="nb">{</span>Z<span class="nb">}</span> are integers describing
</div><div id="l2720" class="code_block">    the state of the random generator.
</div><div id="l2721" class="code_block">
</div><div id="l2722" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>setrand(rand(+X,+Y,+Z))<span class="nb">}{</span>random<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>setrand/1<span class="nb">}}</span>
</div><div id="l2723" class="code_block">    Sets the state of the random generator.  <span class="k">\texttt</span><span class="nb">{</span>X<span class="nb">}</span>,<span class="k">\texttt</span><span class="nb">{</span>Y<span class="nb">}</span>, and
</div><div id="l2724" class="code_block">    <span class="k">\texttt</span><span class="nb">{</span>Z<span class="nb">}</span> must be integers in the ranges [1,30269), [1,30307),
</div><div id="l2725" class="code_block">    [1,30323), respectively.
</div><div id="l2726" class="code_block">
</div><div id="l2727" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>datime<span class="k">\_setrand</span><span class="nb">}{</span>random<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>datime<span class="k">\_setrand</span>/0<span class="nb">}}</span>
</div><div id="l2728" class="code_block">This simple initialization utility sets the random seed triple based on a
</div><div id="l2729" class="code_block">function of the current day, hour, minute and second. 
</div><div id="l2730" class="code_block">
</div><div id="l2731" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>randseq(+K, +N, -RandomSeq)<span class="nb">}{</span>random<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>randseq/3<span class="nb">}}</span>
</div><div id="l2732" class="code_block">    Generates a sequence of <span class="k">\texttt</span><span class="nb">{</span>K<span class="nb">}</span> unique integers chosen randomly
</div><div id="l2733" class="code_block">    in the range from 1 to <span class="k">\texttt</span><span class="nb">{</span>N<span class="nb">}</span>.  <span class="k">\texttt</span><span class="nb">{</span>RandomSeq<span class="nb">}</span> is not
</div><div id="l2734" class="code_block">    returned in any particular order.
</div><div id="l2735" class="code_block">
</div><div id="l2736" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>randset(+K, +N, -RandomSet)<span class="nb">}{</span>random<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>randset/3<span class="nb">}}</span>
</div><div id="l2737" class="code_block">    Generates an ordered set of <span class="k">\texttt</span><span class="nb">{</span>K<span class="nb">}</span> unique integers chosen
</div><div id="l2738" class="code_block">    randomly in the range from 1 to <span class="k">\texttt</span><span class="nb">{</span>N<span class="nb">}</span>.  The set is returned in
</div><div id="l2739" class="code_block">    reversed order, with the largest element first and the smallest
</div><div id="l2740" class="code_block">    last.
</div><div id="l2741" class="code_block">
</div><div id="l2742" class="code_block"><span class="k">\index</span><span class="nb">{</span>Random Variables!Normal<span class="nb">}</span>
</div><div id="l2743" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>gauss(-G1,-G2)<span class="nb">}{</span>ramdom<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>gauss/2<span class="nb">}}</span>
</div><div id="l2744" class="code_block"><span class="c">%</span>
</div><div id="l2745" class="code_block">Generates two random numbers that are normally distributed with mean 0
</div><div id="l2746" class="code_block">and standard deviation 1.  It uses the polar form of the Box-Muller
</div><div id="l2747" class="code_block">transformation~<span class="k">\cite</span><span class="nb">{</span>BoxM58<span class="nb">}</span> of uniform random variables as generated by
</div><div id="l2748" class="code_block"><span class="nb">{</span><span class="k">\tt</span> random/1<span class="nb">}</span>.
</div><div id="l2749" class="code_block">
</div><div id="l2750" class="code_block"><span class="k">\index</span><span class="nb">{</span>Random Variables!Weibull<span class="nb">}</span>
</div><div id="l2751" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>weibull(K,Lambda,X)<span class="nb">}{</span>ramdom<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>weibull/3<span class="nb">}}</span>
</div><div id="l2752" class="code_block"><span class="c">%</span>
</div><div id="l2753" class="code_block">Generates a random number for the Weibull distribution:
</div><div id="l2754" class="code_block"><span class="sb">\[</span>
</div><div id="l2755" class="code_block"><span class="nb">  f</span><span class="o">(</span><span class="nb">x;k,</span><span class="nv">\lambda</span><span class="o">)</span><span class="nb"> </span><span class="o">=</span><span class="nb"> </span><span class="nv">\frac</span><span class="nb">{k}{</span><span class="nv">\lambda</span><span class="nb">}</span><span class="o">(</span><span class="nv">\frac</span><span class="nb">{x}{</span><span class="nv">\lambda</span><span class="nb">}</span><span class="o">)</span><span class="nb">^{k</span><span class="o">-</span><span class="m">1</span><span class="nb">}e^{</span><span class="o">-(</span><span class="nb">x</span><span class="o">/</span><span class="nv">\lambda</span><span class="o">)</span><span class="nb">^h}</span>
</div><div id="l2756" class="code_block"><span class="s">\]</span>
</div><div id="l2757" class="code_block">based on the transformation
</div><div id="l2758" class="code_block"><span class="sb">\[</span>
</div><div id="l2759" class="code_block"><span class="nb">  x </span><span class="o">=</span><span class="nb"> </span><span class="nv">\lambda</span><span class="o">(-</span><span class="nb">ln</span><span class="o">(</span><span class="nb">U</span><span class="o">))</span><span class="nb">^{</span><span class="m">1</span><span class="o">/</span><span class="nb">k}</span>
</div><div id="l2760" class="code_block"><span class="s">\]</span>
</div><div id="l2761" class="code_block">of a uniformly distributed ranom variable produce by <span class="nb">{</span><span class="k">\tt</span> random/1<span class="nb">}</span>
</div><div id="l2762" class="code_block">
</div><div id="l2763" class="code_block"><span class="k">\index</span><span class="nb">{</span>Random Variables!Exponential<span class="nb">}</span>
</div><div id="l2764" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>exponential(K,X)<span class="nb">}{</span>ramdom<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>exponential/2<span class="nb">}}</span>
</div><div id="l2765" class="code_block"><span class="c">%</span>
</div><div id="l2766" class="code_block">Generates a random number for the exponential distribution:
</div><div id="l2767" class="code_block"><span class="sb">\[</span>
</div><div id="l2768" class="code_block"><span class="nb">  f</span><span class="o">(</span><span class="nb">x;k,</span><span class="nv">\lambda</span><span class="o">)</span><span class="nb"> </span><span class="o">=</span><span class="nb"> </span><span class="nv">\frac</span><span class="nb">{e^{</span><span class="o">-(</span><span class="nb">x</span><span class="o">/</span><span class="nv">\lambda</span><span class="o">)</span><span class="nb">^h}}{</span><span class="nv">\lambda</span><span class="nb">}</span>
</div><div id="l2769" class="code_block"><span class="s">\]</span>
</div><div id="l2770" class="code_block">based on the transformation
</div><div id="l2771" class="code_block"><span class="sb">\[</span>
</div><div id="l2772" class="code_block"><span class="nb">  x </span><span class="o">=</span><span class="nb"> </span><span class="nv">\lambda</span><span class="o">(-</span><span class="nb">ln</span><span class="o">(</span><span class="nb">U</span><span class="o">))</span>
</div><div id="l2773" class="code_block"><span class="s">\]</span>
</div><div id="l2774" class="code_block">of a uniformly distributed ranom variable produce by <span class="nb">{</span><span class="k">\tt</span> random/1<span class="nb">}</span>.
</div><div id="l2775" class="code_block">This is the same as the Weibull distribution with <span class="s">$</span><span class="nb">k </span><span class="o">=</span><span class="nb"> </span><span class="m">1</span><span class="s">$</span>.
</div><div id="l2776" class="code_block">
</div><div id="l2777" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2778" class="code_block">
</div><div id="l2779" class="code_block"><span class="k">\section</span><span class="nb">{</span>Loading Separated Files<span class="nb">}</span>
</div><div id="l2780" class="code_block">
</div><div id="l2781" class="code_block">A common file format uses comma separated values, the so-called csv
</div><div id="l2782" class="code_block">files.  The XSB module, <span class="nb">{</span><span class="k">\tt</span> proc<span class="k">\_files</span><span class="nb">}</span>, supports the loading of
</div><div id="l2783" class="code_block">files in this, and similar, formats to define Prolog predicates.
</div><div id="l2784" class="code_block">
</div><div id="l2785" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2786" class="code_block">
</div><div id="l2787" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>load<span class="k">\_csv</span>(+FileName,+PredSpec)<span class="nb">}{</span>proc<span class="k">\_files</span><span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>load<span class="k">\_csv</span>/2<span class="nb">}}</span>
</div><div id="l2788" class="code_block">
</div><div id="l2789" class="code_block"><span class="nb">{</span><span class="k">\tt</span> load<span class="k">\_csv</span>/2<span class="nb">}</span> takes a file name and a predicate specification, and
</div><div id="l2790" class="code_block">reads a csv-formatted file into memory, defining the indicated dynamic
</div><div id="l2791" class="code_block">predicate.  The simplest form of <span class="nb">{</span><span class="k">\tt</span> PredSpec<span class="nb">}</span> is <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2792" class="code_block">PredName/Arity<span class="nb">}</span>.  In this case the arity must equal the number of
</div><div id="l2793" class="code_block">fields in the csv file, and the predicate must be dynamic.  Each line
</div><div id="l2794" class="code_block">in the file will define one fact of the predicate <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2795" class="code_block">PredName/Arity<span class="nb">}</span>.  Fields in the file enclosed in double quotes will
</div><div id="l2796" class="code_block">be treated as single fields (and thus can contain commas and
</div><div id="l2797" class="code_block">new-lines.)  The dynamic predicate will be emptied before the facts
</div><div id="l2798" class="code_block">from the file are added.  Each field will be loaded as an atom
</div><div id="l2799" class="code_block">(including fields that contain just integers.)
</div><div id="l2800" class="code_block">
</div><div id="l2801" class="code_block">Alternatively, <span class="nb">{</span><span class="k">\tt</span> PredSpec<span class="nb">}</span> may be of the form <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2802" class="code_block">predName(TypeSpec1,...,TypeSpecN)<span class="nb">}</span>, where <span class="nb">{</span><span class="k">\tt</span> predName<span class="nb">}</span> is the name
</div><div id="l2803" class="code_block">of the dynamic predicate to be defined by the file contents, and each
</div><div id="l2804" class="code_block"><span class="nb">{</span><span class="k">\tt</span> TypeSpecI<span class="nb">}</span> indicates the type of the corresponding field in the
</div><div id="l2805" class="code_block">file.  The permitted values of <span class="nb">{</span><span class="k">\tt</span> TypeSpec<span class="nb">}</span> are:
</div><div id="l2806" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2807" class="code_block"><span class="k">\item</span><span class="na">[{\tt atom}]</span> The corresponding field value will become an atom in
</div><div id="l2808" class="code_block">the loaded fact.
</div><div id="l2809" class="code_block"><span class="k">\item</span><span class="na">[{\tt integer}]</span> The corresponding field value will be converted
</div><div id="l2810" class="code_block">to an integer in the loaded fact.
</div><div id="l2811" class="code_block"><span class="k">\item</span><span class="na">[{\tt float}]</span> The corresponding field value will be converted to
</div><div id="l2812" class="code_block">a float in the loaded fact.
</div><div id="l2813" class="code_block"><span class="k">\item</span><span class="na">[{\tt term}]</span> The corresponding field must contain a Prolog term in
</div><div id="l2814" class="code_block">canonical form, and it will be converted to that term in the loaded
</div><div id="l2815" class="code_block">fact. 
</div><div id="l2816" class="code_block"><span class="k">\item</span><span class="na">[\_\_]</span> (A variable) Treated as <span class="nb">{</span><span class="k">\tt</span> atom<span class="nb">}</span>.
</div><div id="l2817" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2818" class="code_block">
</div><div id="l2819" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>load<span class="k">\_dsv</span>(+FileName,+PredSpec,+Options)<span class="nb">}{</span>proc<span class="k">\_files</span><span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>load<span class="k">\_dsv</span>/3<span class="nb">}}</span>
</div><div id="l2820" class="code_block">
</div><div id="l2821" class="code_block">This predicate supports the loading of more general forms of files
</div><div id="l2822" class="code_block">with value-separated fields.  The <span class="nb">{</span><span class="k">\tt</span> FileName<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span> PredSpec<span class="nb">}</span>
</div><div id="l2823" class="code_block">parameters are exactly as in <span class="nb">{</span><span class="k">\tt</span> load<span class="k">\_csv</span>/2<span class="nb">}</span>, as described just
</div><div id="l2824" class="code_block">above.  <span class="nb">{</span><span class="k">\tt</span> Options<span class="nb">}</span> is a list of options.  (With an empty list, <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2825" class="code_block">load<span class="k">\_dsv</span><span class="nb">}</span> acts as <span class="nb">{</span><span class="k">\tt</span> load<span class="k">\_csv</span>/2<span class="nb">}</span>.)  The options are:
</div><div id="l2826" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2827" class="code_block"><span class="k">\item</span><span class="na">[{\tt separator=&#39;&#39;Sep&#39;&#39;}]</span> which indicates that the character(s) <span class="nb">{</span><span class="k">\tt</span> Sep<span class="nb">}</span>
</div><div id="l2828" class="code_block">will be used as the field separator.  There may be one or more
</div><div id="l2829" class="code_block">characters. 
</div><div id="l2830" class="code_block"><span class="k">\item</span><span class="na">[{\tt delimiter=&#39;&#39;C&#39;&#39;}]</span> which indicates that the single character <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2831" class="code_block">C<span class="nb">}</span> will be used as the field delimiter (the default being ``&#39;&#39;&#39;&#39;&#39;&#39;,
</div><div id="l2832" class="code_block">and I&#39;ve yet to find a situation in which I want to change it.)
</div><div id="l2833" class="code_block"><span class="k">\item</span><span class="na">[{\tt titles}]</span> which indicates that the first line of the file should
</div><div id="l2834" class="code_block">be ignored and not contribute a fact to the dynamic predicate.
</div><div id="l2835" class="code_block"><span class="k">\end</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2836" class="code_block">
</div><div id="l2837" class="code_block"><span class="k">\end</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2838" class="code_block">
</div><div id="l2839" class="code_block"><span class="k">\section</span><span class="nb">{</span>Scanning in Prolog<span class="nb">}</span>
</div><div id="l2840" class="code_block">
</div><div id="l2841" class="code_block">Scanners, (sometimes called tokenizers) take an input string, usually
</div><div id="l2842" class="code_block">in ASCII or similar format, and produce a scanned sequence of tokens.
</div><div id="l2843" class="code_block">The requirements that various applications have for scanning differ in
</div><div id="l2844" class="code_block">small but important ways -- a character that is special to one
</div><div id="l2845" class="code_block">application may be part of the token of another; or some applications
</div><div id="l2846" class="code_block">may want lower case text converted to upper-case test.  The <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2847" class="code_block">stdscan.P<span class="nb">}</span> library provides a simple scanner written in XSB that can
</div><div id="l2848" class="code_block">be configured in several ways.  While useful, this scanner is not
</div><div id="l2849" class="code_block">intended to be as powerful as general-purpose scanners such as <span class="nb">{</span><span class="k">\em</span>
</div><div id="l2850" class="code_block">lex<span class="nb">}</span> or <span class="nb">{</span><span class="k">\em</span> flex<span class="nb">}</span>.
</div><div id="l2851" class="code_block">
</div><div id="l2852" class="code_block"><span class="k">\begin</span><span class="nb">{</span>description<span class="nb">}</span>
</div><div id="l2853" class="code_block">
</div><div id="l2854" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>scan(+List,-Tokens)<span class="nb">}{</span>stdscan<span class="nb">}</span> <span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>scan/2<span class="nb">}}</span>  
</div><div id="l2855" class="code_block">
</div><div id="l2856" class="code_block">Given as input a <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span> of character codes, <span class="nb">{</span><span class="k">\tt</span> scan/2<span class="nb">}</span> scans
</div><div id="l2857" class="code_block">this list producing a list of atoms constituting the lexical tokens.
</div><div id="l2858" class="code_block">Its parameters are set via <span class="nb">{</span><span class="k">\tt</span> set<span class="k">\_scan\_pars</span>/1<span class="nb">}</span>.
</div><div id="l2859" class="code_block">
</div><div id="l2860" class="code_block">Tokens produced are either a sequence of <span class="nb">{</span><span class="k">\em</span> letters<span class="nb">}</span> and/or <span class="nb">{</span><span class="k">\em</span>
</div><div id="l2861" class="code_block">numbers<span class="nb">}</span> or consist of a single <span class="nb">{</span><span class="k">\em</span> special character<span class="nb">}</span> (e.g. <span class="nb">{</span><span class="k">\tt</span> (<span class="nb">}</span>
</div><div id="l2862" class="code_block">or <span class="nb">{</span><span class="k">\tt</span> )<span class="nb">}</span>).  Whitespaces may occur between tokens.
</div><div id="l2863" class="code_block">
</div><div id="l2864" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>scan(+List,+FieldSeparator,-Tokens)<span class="nb">}{</span>stdscan<span class="nb">}</span> 
</div><div id="l2865" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>scan/3<span class="nb">}}</span>  
</div><div id="l2866" class="code_block">
</div><div id="l2867" class="code_block">Given as input a <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span> of character codes, along with a character
</div><div id="l2868" class="code_block">code for a field separator, <span class="nb">{</span><span class="k">\tt</span> scan/3<span class="nb">}</span> scans this list producing a
</div><div id="l2869" class="code_block">list of list of atoms constituting the lexical tokens in each field.
</div><div id="l2870" class="code_block"><span class="nb">{</span><span class="k">\em</span> scan/3<span class="nb">}</span> thus can be used to scan tabular information.  Its
</div><div id="l2871" class="code_block">parameters are set via <span class="nb">{</span><span class="k">\tt</span> set<span class="k">\_scan\_pars</span>/1<span class="nb">}</span>.
</div><div id="l2872" class="code_block">
</div><div id="l2873" class="code_block"><span class="k">\ourmoditem</span><span class="nb">{</span>set<span class="k">\_scan\_pars</span>(+List)<span class="nb">}{</span>stdscan<span class="nb">}</span> 
</div><div id="l2874" class="code_block"><span class="k">\index</span><span class="nb">{</span><span class="k">\texttt</span><span class="nb">{</span>set<span class="k">\_scan\_pars</span>/1<span class="nb">}}</span>  
</div><div id="l2875" class="code_block">
</div><div id="l2876" class="code_block"><span class="nb">{</span><span class="k">\tt</span> set<span class="k">\_scan\_pars</span>(+List)<span class="nb">}</span> is used to configure the tokenizer to a
</div><div id="l2877" class="code_block">particular need.  <span class="nb">{</span><span class="k">\tt</span> List<span class="nb">}</span> is a list of parameters including the
</div><div id="l2878" class="code_block">following:
</div><div id="l2879" class="code_block">
</div><div id="l2880" class="code_block"><span class="k">\begin</span><span class="nb">{</span>itemize<span class="nb">}</span>
</div><div id="l2881" class="code_block">
</div><div id="l2882" class="code_block"><span class="k">\item</span><span class="nb">{{</span><span class="k">\tt</span> whitespace<span class="nb">}}</span>.  The default action of the scanner is to return a
</div><div id="l2883" class="code_block">list of tokens, with any whitespace removed.  If <span class="nb">{</span><span class="k">\tt</span> whitespace<span class="nb">}</span> is a
</div><div id="l2884" class="code_block">parameter, then the scanner returns the token <span class="nb">{</span><span class="k">\tt</span> &#39;&#39;<span class="nb">}</span> when it finds
</div><div id="l2885" class="code_block">whitespace separating two tokens (unless the two tokens are letter
</div><div id="l2886" class="code_block">sequences; since two letter sequences can be two tokens ONLY if they
</div><div id="l2887" class="code_block">are separated by whitespace, such an indication of whitespace would be
</div><div id="l2888" class="code_block">redundant.)  Including the parameter <span class="nb">{</span><span class="k">\tt</span> no<span class="k">\_whitespace</span><span class="nb">}</span> undoes the
</div><div id="l2889" class="code_block">effect of previously including <span class="nb">{</span><span class="k">\tt</span> whitespace<span class="nb">}</span>.
</div><div id="l2890" class="code_block">
</div><div id="l2891" class="code_block"><span class="k">\item</span><span class="nb">{{</span><span class="k">\tt</span> upper<span class="k">\_case</span><span class="nb">}}</span> The default action of the parser is to treat
</div><div id="l2892" class="code_block">lowercase letter differently from uppercase letters.  This parameter
</div><div id="l2893" class="code_block">should be set if conversion to uppercase should be done when producing
</div><div id="l2894" class="code_block">a token that does <span class="nb">{</span><span class="k">\em</span> not<span class="nb">}</span> consist entirely of letters (e.g. one with
</div><div id="l2895" class="code_block">mixed letters and digits).  Including the parameter <span class="nb">{</span><span class="k">\tt</span> no<span class="k">\_case</span><span class="nb">}</span>
</div><div id="l2896" class="code_block">undoes the effect of previously including <span class="nb">{</span><span class="k">\tt</span> upper<span class="k">\_case</span><span class="nb">}</span>.
</div><div id="l2897" class="code_block">
</div><div id="l2898" class="code_block"><span class="k">\item</span><span class="nb">{{</span><span class="k">\tt</span> upper<span class="k">\_case\_in\_lit</span><span class="nb">}}</span> The default action of the parser is
</div><div id="l2899" class="code_block">to treat lowercase letter differently from uppercase letters.  This
</div><div id="l2900" class="code_block">parameter should be set if conversion to uppercase should be done when
</div><div id="l2901" class="code_block">producing a token that consists entirely of letters.  Including the
</div><div id="l2902" class="code_block">parameter <span class="nb">{</span><span class="k">\tt</span> no<span class="k">\_case\_in\_lit</span><span class="nb">}</span> undoes the effect of previously
</div><div id="l2903" class="code_block">including <span class="nb">{</span><span class="k">\tt</span> upper<span class="k">\_case</span><span class="nb">}</span>.
</div><div id="l2904" class="code_block">
</div><div id="l2905" class="code_block"><span class="k">\item</span><span class="nb">{{</span><span class="k">\tt</span> whitespace(Code)<span class="nb">}}</span> adds <span class="nb">{</span><span class="k">\tt</span> Code<span class="nb">}</span> as a whitespace code.
</div><div id="l2906" class="code_block">By default, all ASCII codes less than or equal to <span class="nb">{</span><span class="k">\tt</span> 32<span class="nb">}</span> are
</div><div id="l2907" class="code_block">regarded as whitespace.
</div><div id="l2908" class="code_block">
</div><div id="l2909" class="code_block"><span class="k">\item</span><span class="nb">{{</span><span class="k">\tt</span> letter(Code)<span class="nb">}}</span> adds <span class="nb">{</span><span class="k">\tt</span> Code<span class="nb">}</span> as a letter constituting a
</div><div id="l2910" class="code_block">token. By default, ASCII codes for characters <span class="nb">{</span><span class="k">\tt</span> a--z<span class="nb">}</span> and <span class="nb">{</span><span class="k">\tt</span>
</div><div id="l2911" class="code_block">A--Z<span class="nb">}</span> are regarded as letters.
</div><div id="l2912" class="code_block">
</div><div id="l2913" class="code_block"><span class="k">\item</span><span class="nb">{{</span><span class="k">\tt</span> special<span class="k">\_char</span>(Code)<span class="nb">}}</span> adds <span class="nb">{</span><span class="k">\tt</span> Code<span class="nb">}</span> as a special
</div><div id="l2914" class="code_block">  character.  By default, ASCII codes for the following characters are
</div><div id="l2915" class="code_block">  regarded as special characters:
</div><div id="l2916" class="code_block">
</div><div id="l2917" class="code_block"><span class="k">\begin</span><span class="nb">{</span>verbatim<span class="nb">}</span>
</div><div id="l2918" class="code_block">| <span class="nb">{</span> <span class="nb">}</span> [ ] &quot; <span class="s">$</span><span class="nb"> </span><span class="c">% &amp; &#39; ( ) * + , - . / : ; &lt; = &gt; ? @ \ ^ _ ~ `</span>
</div><div id="l2919" class="code_block"><span class="nv">\end</span><span class="nb">{verbatim}</span>
</div><div id="l2920" class="code_block"><span class="nv">\end</span><span class="nb">{itemize}</span>
</div><div id="l2921" class="code_block">
</div><div id="l2922" class="code_block"><span class="nv">\ourmoditem</span><span class="nb">{get</span><span class="nv">\_</span><span class="nb">scan</span><span class="nv">\_</span><span class="nb">pars</span><span class="o">(-</span><span class="nb">List</span><span class="o">)</span><span class="nb">}{stdscan} </span>
</div><div id="l2923" class="code_block"><span class="nv">\index</span><span class="nb">{</span><span class="nv">\texttt</span><span class="nb">{get</span><span class="nv">\_</span><span class="nb">scan</span><span class="nv">\_</span><span class="nb">pars</span><span class="o">/</span><span class="m">1</span><span class="nb">}}  </span>
</div><div id="l2924" class="code_block"><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> get</span><span class="nv">\_</span><span class="nb">scan</span><span class="nv">\_</span><span class="nb">pars</span><span class="o">/</span><span class="m">1</span><span class="nb">} returns a list of the currently active</span>
</div><div id="l2925" class="code_block"><span class="nb">parameters.</span>
</div><div id="l2926" class="code_block">
</div><div id="l2927" class="code_block"><span class="nv">\end</span><span class="nb">{description} </span>
</div><div id="l2928" class="code_block">
</div><div id="l2929" class="code_block"><span class="nv">\section</span><span class="nb">{XSB Lint}</span>
</div><div id="l2930" class="code_block"><span class="c">%================================</span>
</div><div id="l2931" class="code_block">
</div><div id="l2932" class="code_block"><span class="nb">The {</span><span class="nv">\tt</span><span class="nb"> xsb</span><span class="nv">\_</span><span class="nb">lint</span><span class="nv">\_</span><span class="nb">impexp.P} file contains a simple tool to analyze</span>
</div><div id="l2933" class="code_block"><span class="nb">import</span><span class="o">/</span><span class="nb">exports and definitions and uses of predicates.  It tries to</span>
</div><div id="l2934" class="code_block"><span class="nb">find possible inconsistencies, producing warnings when it finds them</span>
</div><div id="l2935" class="code_block"><span class="nb">and generating {</span><span class="nv">\tt</span><span class="nb"> document</span><span class="nv">\_</span><span class="nb">import}</span><span class="o">/</span><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> document</span><span class="nv">\_</span><span class="nb">export}</span>
</div><div id="l2936" class="code_block"><span class="nb">declarations that might be useful.  It can be used after a large</span>
</div><div id="l2937" class="code_block"><span class="nb">multi</span><span class="o">-</span><span class="nb">file, multi</span><span class="o">-</span><span class="nb">module XSB program has been written to find possible</span>
</div><div id="l2938" class="code_block"><span class="nb">inconsistencies in </span><span class="o">(</span><span class="nb">or interesting aspects of</span><span class="o">)</span><span class="nb"> how predicates are</span>
</div><div id="l2939" class="code_block"><span class="nb">defined and used.</span>
</div><div id="l2940" class="code_block">
</div><div id="l2941" class="code_block"><span class="nb">XSB source files that contain an {</span><span class="nv">\tt</span><span class="nb"> export} compiler directive are</span>
</div><div id="l2942" class="code_block"><span class="nb">considered as modules.  Predicates defined in modules, but not</span>
</div><div id="l2943" class="code_block"><span class="nb">exported, are local to that module.  When compiling a module, the XSB</span>
</div><div id="l2944" class="code_block"><span class="nb">compiler generates useful warnings when predicates are used but not</span>
</div><div id="l2945" class="code_block"><span class="nb">defined or defined but not used.  All predicates that are defined in</span>
</div><div id="l2946" class="code_block"><span class="nb">source files that do not contain an {</span><span class="nv">\tt</span><span class="nb"> export} directive are</span>
</div><div id="l2947" class="code_block"><span class="nb">compiled to be defined in a global module, called {</span><span class="nv">\tt</span><span class="nb"> usermod}, and</span>
</div><div id="l2948" class="code_block"><span class="nb">no warning messages are generated.  The user may add {</span><span class="nv">\tt</span>
</div><div id="l2949" class="code_block"><span class="nb">document</span><span class="nv">\_</span><span class="nb">export} and {</span><span class="nv">\tt</span><span class="nb"> document</span><span class="nv">\_</span><span class="nb">import} compiler directives</span>
</div><div id="l2950" class="code_block"><span class="o">(</span><span class="nb">exactly analogous to the {</span><span class="nv">\tt</span><span class="nb"> export} and {</span><span class="nv">\tt</span><span class="nb"> import} directives</span><span class="o">)</span><span class="nb"> to</span>
</div><div id="l2951" class="code_block"><span class="nb">non</span><span class="o">-</span><span class="nb">module source files.  These directives are ignored by the compiler</span>
</div><div id="l2952" class="code_block"><span class="nb">for its compilation, but cause the define</span><span class="o">-</span><span class="nb">use analysis to be done and</span>
</div><div id="l2953" class="code_block"><span class="nb">any warning messages to be issued, if appropriate.  This allows a user</span>
</div><div id="l2954" class="code_block"><span class="nb">to get the benefit of the define</span><span class="o">-</span><span class="nb">use analysis without using modules.</span>
</div><div id="l2955" class="code_block"><span class="o">(</span><span class="nb">See Volume </span><span class="m">1</span><span class="nb">, Chapter </span><span class="m">3</span><span class="nb"> for more details.</span><span class="o">)</span>
</div><div id="l2956" class="code_block">
</div><div id="l2957" class="code_block"><span class="nb">The {</span><span class="nv">\tt</span><span class="nb"> xsb</span><span class="nv">\_</span><span class="nb">lint</span><span class="nv">\_</span><span class="nb">impexp} utility processes both modules and regular</span>
</div><div id="l2958" class="code_block"><span class="nb">XSB source files that contain {</span><span class="nv">\tt</span><span class="nb"> document</span><span class="nv">\_</span><span class="nb">export} statements.</span>
</div><div id="l2959" class="code_block"><span class="c">%</span>
</div><div id="l2960" class="code_block"><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> xsb</span><span class="nv">\_</span><span class="nb">lint</span><span class="nv">\_</span><span class="nb">impexp} is not itself a module.  To use it, {</span><span class="nv">\tt</span>
</div><div id="l2961" class="code_block"><span class="o">[</span><span class="nb">xsb</span><span class="nv">\_</span><span class="nb">lint</span><span class="nv">\_</span><span class="nb">impexp</span><span class="o">]</span><span class="nb">} must be consulted, which will define the {</span><span class="nv">\tt</span>
</div><div id="l2962" class="code_block"><span class="nb">checkImpExps</span><span class="o">/</span><span class="nv">\{</span><span class="m">1</span><span class="nb">,</span><span class="m">2</span><span class="nv">\}</span><span class="nb">} and {</span><span class="nv">\tt</span><span class="nb"> add</span><span class="nv">\_</span><span class="nb">libraries</span><span class="o">/</span><span class="m">1</span><span class="nb">} predicates in {</span><span class="nv">\tt</span>
</div><div id="l2963" class="code_block"><span class="nb">usermod}.</span>
</div><div id="l2964" class="code_block">
</div><div id="l2965" class="code_block"><span class="nv">\begin</span><span class="nb">{description}</span>
</div><div id="l2966" class="code_block"><span class="nv">\ouritem</span><span class="nb">{add</span><span class="nv">\_</span><span class="nb">libraries</span><span class="o">(+</span><span class="nb">DirectoryNameList</span><span class="o">)</span><span class="nb">}</span>
</div><div id="l2967" class="code_block"><span class="c">%</span>
</div><div id="l2968" class="code_block"><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> add</span><span class="nv">\_</span><span class="nb">libraries</span><span class="o">/</span><span class="m">1</span><span class="nb">} takes a list of directory names and adds them</span>
</div><div id="l2969" class="code_block"><span class="nb">to the {</span><span class="nv">\tt</span><span class="nb"> library</span><span class="nv">\_</span><span class="nb">directory</span><span class="o">/</span><span class="m">1</span><span class="nb">} predicate.  This causes the XSB</span>
</div><div id="l2970" class="code_block"><span class="nb">system to look for XSB source code files in these directories.  To use</span>
</div><div id="l2971" class="code_block"><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> checkImpExps</span><span class="o">/</span><span class="nv">\{</span><span class="m">1</span><span class="nb">,</span><span class="m">2</span><span class="nv">\}</span><span class="nb">}, all the directories that contain files </span><span class="o">(</span><span class="nb">or</span>
</div><div id="l2972" class="code_block"><span class="nb">modules</span><span class="o">)</span><span class="nb"> referenced </span><span class="o">(</span><span class="nb">recursively</span><span class="o">)</span><span class="nb"> in the files to be processed must be</span>
</div><div id="l2973" class="code_block"><span class="nb">in the {</span><span class="nv">\tt</span><span class="nb"> library</span><span class="nv">\_</span><span class="nb">directory</span><span class="o">/</span><span class="m">1</span><span class="nb">} predicate.  This predicate can be</span>
</div><div id="l2974" class="code_block"><span class="nb">used to add a number of directories at once.</span>
</div><div id="l2975" class="code_block">
</div><div id="l2976" class="code_block"><span class="nv">\ouritem</span><span class="nb">{checkImpExps</span><span class="o">(+</span><span class="nb">Options,</span><span class="o">+</span><span class="nb">FileNameList</span><span class="o">)</span><span class="nb">}</span>
</div><div id="l2977" class="code_block"><span class="c">%</span>
</div><div id="l2978" class="code_block"><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> checkImpExps</span><span class="o">/</span><span class="m">1</span><span class="nb">} reads all the XSB source files named in the list</span>
</div><div id="l2979" class="code_block"><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> FileNameList}, and all files they reference </span><span class="o">(</span><span class="nb">recursively</span><span class="o">)</span><span class="nb">, and</span>
</div><div id="l2980" class="code_block"><span class="nb">produces a listing that describes properties of how they reference</span>
</div><div id="l2981" class="code_block"><span class="nb">predicates.</span>
</div><div id="l2982" class="code_block">
</div><div id="l2983" class="code_block"><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> Options} is a list of atoms </span><span class="o">(</span><span class="nb">from the following list</span><span class="o">)</span><span class="nb"> indicating</span>
</div><div id="l2984" class="code_block"><span class="nb">details of how {</span><span class="nv">\tt</span><span class="nb"> checkImpExps} should work.</span>
</div><div id="l2985" class="code_block">
</div><div id="l2986" class="code_block"><span class="nv">\begin</span><span class="nb">{enumerate}</span>
</div><div id="l2987" class="code_block"><span class="nv">\item</span>
</div><div id="l2988" class="code_block"><span class="nb">   {</span><span class="nv">\tt</span><span class="nb"> used</span><span class="nv">\_</span><span class="nb">elsewhere}: Print a warning message in the case of a</span>
</div><div id="l2989" class="code_block"><span class="nb">   predicate defined in a file, not used there, but used elsewhere </span><span class="o">(</span><span class="nb">in</span>
</div><div id="l2990" class="code_block"><span class="nb">   a file in {</span><span class="nv">\tt</span><span class="nb"> FileNameList}</span><span class="o">)</span><span class="nb">. This can be useful to see whether it</span>
</div><div id="l2991" class="code_block"><span class="nb">   might be better to move the predicate definition to another file,</span>
</div><div id="l2992" class="code_block"><span class="nb">   but it produces many warnings for predicates in multi</span><span class="o">-</span><span class="nb">use</span>
</div><div id="l2993" class="code_block"><span class="nb">   libraries.</span>
</div><div id="l2994" class="code_block"><span class="nv">\item</span>
</div><div id="l2995" class="code_block"><span class="nb">   {</span><span class="nv">\tt</span><span class="nb"> unused}: Print a warning message in the case of a predicate that is</span>
</div><div id="l2996" class="code_block"><span class="nb">   exported but never used.  This can be useful to see if predicate is</span>
</div><div id="l2997" class="code_block"><span class="nb">   not used anywhere, and thus could be deleted.  Again this produces</span>
</div><div id="l2998" class="code_block"><span class="nb">   many warnings for predicates in multi</span><span class="o">-</span><span class="nb">use libraries.</span>
</div><div id="l2999" class="code_block"><span class="nv">\item</span>
</div><div id="l3000" class="code_block"><span class="nb">   {</span><span class="nv">\tt</span><span class="nb"> all</span><span class="nv">\_</span><span class="nb">files}: By default, only predicates in files that contain a {</span><span class="nv">\tt</span>
</div><div id="l3001" class="code_block"><span class="nb">   :</span><span class="o">-</span><span class="nb"> document</span><span class="nv">\_</span><span class="nb">export} or {</span><span class="nv">\tt</span><span class="nb"> :</span><span class="o">-</span><span class="nb"> export} declaration are processed.</span>
</div><div id="l3002" class="code_block"><span class="nb">   This option causes predicates of {</span><span class="nv">\em</span><span class="nb"> all} files </span><span class="o">(</span><span class="nb">and modules</span><span class="o">)</span><span class="nb"> to be</span>
</div><div id="l3003" class="code_block"><span class="nb">   processed.</span>
</div><div id="l3004" class="code_block"><span class="nv">\item</span>
</div><div id="l3005" class="code_block"><span class="nb">   {</span><span class="nv">\tt</span><span class="nb"> all</span><span class="nv">\_</span><span class="nb">symbol</span><span class="nv">\_</span><span class="nb">uses}: Treat {</span><span class="nv">\em</span><span class="nb"> all} non</span><span class="o">-</span><span class="nb">predicate uses of symbols</span>
</div><div id="l3006" class="code_block"><span class="nb">   </span><span class="o">(</span><span class="nb">even constants</span><span class="o">)</span><span class="nb"> as predicate uses for the purpose of generating</span>
</div><div id="l3007" class="code_block"><span class="nb">   imports.</span>
</div><div id="l3008" class="code_block"><span class="nv">\item</span>
</div><div id="l3009" class="code_block"><span class="nb">   {</span><span class="nv">\tt</span><span class="nb"> no</span><span class="nv">\_</span><span class="nb">symbol</span><span class="nv">\_</span><span class="nb">uses}: Don&#39;t treat any non</span><span class="o">-</span><span class="nb">predicate uses of symbols as</span>
</div><div id="l3010" class="code_block"><span class="nb">   predicate uses for the purpose of generating imports.</span>
</div><div id="l3011" class="code_block"><span class="nv">\end</span><span class="nb">{enumerate}</span>
</div><div id="l3012" class="code_block">
</div><div id="l3013" class="code_block"><span class="nb">We further explain the final two options, which allow the user to</span>
</div><div id="l3014" class="code_block"><span class="nb">determine more precisely what uses of a symbol are considered as uses</span>
</div><div id="l3015" class="code_block"><span class="nb">of it as the predicate symbol.  All uses of symbols that appear in a</span>
</div><div id="l3016" class="code_block"><span class="nb">``predicate context&quot;, i.e., in the body of a rule or in a</span>
</div><div id="l3017" class="code_block"><span class="nb">meta</span><span class="o">-</span><span class="nb">predicate argument position of a use of a meta</span><span class="o">-</span><span class="nb">predicate, are</span>
</div><div id="l3018" class="code_block"><span class="nb">considered uses of that predicate symbol.  The default is also to</span>
</div><div id="l3019" class="code_block"><span class="nb">allow nonconstant symbols appearing in any other context to also count</span>
</div><div id="l3020" class="code_block"><span class="nb">as uses of that symbol as that predicate symbol.  This is useful for</span>
</div><div id="l3021" class="code_block"><span class="nb">programs that define their own meta</span><span class="o">-</span><span class="nb">predicates.</span>
</div><div id="l3022" class="code_block">
</div><div id="l3023" class="code_block"><span class="nv">\ouritem</span><span class="nb">{checkImpExps</span><span class="o">(+</span><span class="nb">FileNameList</span><span class="o">)</span><span class="nb">}</span>
</div><div id="l3024" class="code_block"><span class="c">%</span>
</div><div id="l3025" class="code_block"><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> checkImpExps</span><span class="o">/</span><span class="m">1</span><span class="nb">}  is</span>
</div><div id="l3026" class="code_block"><span class="nb">currently equivalent to {</span><span class="nv">\tt</span><span class="nb"> checkImpExps</span><span class="o">([]</span><span class="nb">,FileNameList</span><span class="o">)</span><span class="nb">}.</span>
</div><div id="l3027" class="code_block"><span class="nv">\end</span><span class="nb">{description}</span>
</div><div id="l3028" class="code_block">
</div><div id="l3029" class="code_block"><span class="c">%=======================================================================</span>
</div><div id="l3030" class="code_block"><span class="nv">\section</span><span class="nb">{Miscellaneous Predicates}</span>
</div><div id="l3031" class="code_block">
</div><div id="l3032" class="code_block"><span class="nv">\begin</span><span class="nb">{description}</span>
</div><div id="l3033" class="code_block">
</div><div id="l3034" class="code_block"><span class="nv">\ourmoditem</span><span class="nb">{term</span><span class="nv">\_</span><span class="nb">hash</span><span class="o">(+</span><span class="nb">Term,</span><span class="o">+</span><span class="nb">HashSize,</span><span class="o">-</span><span class="nb">HashVal</span><span class="o">)</span><span class="nb">}{machine}</span>
</div><div id="l3035" class="code_block"><span class="nv">\index</span><span class="nb">{</span><span class="nv">\texttt</span><span class="nb">{term</span><span class="nv">\_</span><span class="nb">hash</span><span class="o">/</span><span class="m">3</span><span class="nb">}}</span>
</div><div id="l3036" class="code_block"><span class="c">%</span>
</div><div id="l3037" class="code_block"><span class="nb">Given an arbitrary Prolog term, {</span><span class="nv">\tt</span><span class="nb"> Term}, that is to be hashed into</span>
</div><div id="l3038" class="code_block"><span class="nb">a table of {</span><span class="nv">\tt</span><span class="nb"> HashSize} buckets, this predicate returns a hash value</span>
</div><div id="l3039" class="code_block"><span class="nb">for {</span><span class="nv">\tt</span><span class="nb"> Term} that is between {</span><span class="nv">\tt</span><span class="nb"> </span><span class="m">0</span><span class="nb">} and {</span><span class="nv">\tt</span><span class="nb"> HashSize </span><span class="o">-</span><span class="m">1</span><span class="nb">}.</span>
</div><div id="l3040" class="code_block">
</div><div id="l3041" class="code_block"><span class="nv">\ourmoditem</span><span class="nb">{pretty</span><span class="nv">\_</span><span class="nb">print</span><span class="o">(+</span><span class="nb">ClausePairs</span><span class="o">)</span><span class="nb">}{pretty</span><span class="nv">\_</span><span class="nb">print}</span>
</div><div id="l3042" class="code_block"><span class="nv">\index</span><span class="nb">{</span><span class="nv">\texttt</span><span class="nb">{pretty</span><span class="nv">\_</span><span class="nb">print</span><span class="o">/</span><span class="m">1</span><span class="nb">}}</span>
</div><div id="l3043" class="code_block"><span class="c">%</span>
</div><div id="l3044" class="code_block"><span class="nb">The input to {</span><span class="nv">\tt</span><span class="nb"> pretty</span><span class="nv">\_</span><span class="nb">print</span><span class="o">/</span><span class="m">1</span><span class="nb">}, {</span><span class="nv">\tt</span><span class="nb"> ClausePairs}, can be either a</span>
</div><div id="l3045" class="code_block"><span class="nb">list of clause pairs or a single clause pair.  A clause pair is either</span>
</div><div id="l3046" class="code_block"><span class="nb">a Prolog clause </span><span class="o">(</span><span class="nb">or declaration</span><span class="o">)</span><span class="nb"> or a pair:</span>
</div><div id="l3047" class="code_block"><span class="c">%</span>
</div><div id="l3048" class="code_block"><span class="nv">\begin</span><span class="nb">{center}</span>
</div><div id="l3049" class="code_block"><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> </span><span class="o">(</span><span class="nb">Clause,Dict</span><span class="o">)</span><span class="nb">} </span>
</div><div id="l3050" class="code_block"><span class="nv">\end</span><span class="nb">{center}</span>
</div><div id="l3051" class="code_block"><span class="c">%</span>
</div><div id="l3052" class="code_block"><span class="nb">Where {</span><span class="nv">\tt</span><span class="nb"> Dict} is a list of the form {</span><span class="nv">\tt</span><span class="nb"> A </span><span class="o">=</span><span class="nb"> V} where {</span><span class="nv">\tt</span><span class="nb"> V} is a</span>
</div><div id="l3053" class="code_block"><span class="nb">variable in {</span><span class="nv">\tt</span><span class="nb"> Clause} and {</span><span class="nv">\tt</span><span class="nb"> A} is the string to be used to</span>
</div><div id="l3054" class="code_block"><span class="nb">denote the variable </span><span class="nv">\footnote</span><span class="nb">{Thus the list of variable names returned</span>
</div><div id="l3055" class="code_block"><span class="nb">by {</span><span class="nv">\tt</span><span class="nb"> read</span><span class="nv">\_</span><span class="nb">term</span><span class="o">/</span><span class="nv">\{</span><span class="m">2</span><span class="nb">,</span><span class="m">3</span><span class="nv">\}</span><span class="nb">} can be used directly in {</span><span class="nv">\tt</span><span class="nb"> Dict}.}.</span>
</div><div id="l3056" class="code_block">
</div><div id="l3057" class="code_block"><span class="nb">By default, {</span><span class="nv">\tt</span><span class="nb"> pretty</span><span class="nv">\_</span><span class="nb">print</span><span class="o">/</span><span class="m">1</span><span class="nb">} outputs atomic terms using {</span><span class="nv">\tt</span>
</div><div id="l3058" class="code_block"><span class="nb">writeq</span><span class="o">/</span><span class="m">1</span><span class="nb">}, but specialized output can be configured via asserting in</span>
</div><div id="l3059" class="code_block"><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> usermod} a term of the form</span>
</div><div id="l3060" class="code_block"><span class="c">%</span>
</div><div id="l3061" class="code_block"><span class="nv">\begin</span><span class="nb">{center}</span>
</div><div id="l3062" class="code_block"><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> user</span><span class="nv">\_</span><span class="nb">replacement</span><span class="nv">\_</span><span class="nb">hook</span><span class="o">(</span><span class="nb">Term,Call</span><span class="o">)</span><span class="nb">}</span>
</div><div id="l3063" class="code_block"><span class="nv">\end</span><span class="nb">{center}</span>
</div><div id="l3064" class="code_block"><span class="c">%</span>
</div><div id="l3065" class="code_block"><span class="nb">which will use Call to output an atomic literal </span><span class="s">$</span>A<span class="s">$</span><span class="nb"> whenever </span><span class="s">$</span>A<span class="s">$</span>
</div><div id="l3066" class="code_block"><span class="nb">unifies with {</span><span class="nv">\tt</span><span class="nb"> Term}.  For example, pretty printing weight</span>
</div><div id="l3067" class="code_block"><span class="nb">constraints in XSB&#39;s {</span><span class="nv">\tt</span><span class="nb"> XASP} package is done via the hook</span>
</div><div id="l3068" class="code_block"><span class="c">%</span>
</div><div id="l3069" class="code_block"><span class="nv">\begin</span><span class="nb">{center}</span>
</div><div id="l3070" class="code_block"><span class="nb">{</span><span class="nv">\tt</span><span class="nb"> user</span><span class="nv">\_</span><span class="nb">replacement</span><span class="nv">\_</span><span class="nb">hook</span><span class="o">(</span><span class="nb">weight</span><span class="nv">\_</span><span class="nb">constr</span><span class="o">(</span><span class="nb">Term</span><span class="o">)</span><span class="nb">,output</span><span class="nv">\_</span><span class="nb">weight</span><span class="nv">\_</span><span class="nb">constr</span><span class="o">(</span><span class="nb">Term</span><span class="o">))</span><span class="nb">}</span>
</div><div id="l3071" class="code_block"><span class="nv">\end</span><span class="nb">{center}</span>
</div><div id="l3072" class="code_block"><span class="c">%</span>
</div><div id="l3073" class="code_block"><span class="nb">which outputs a weight constraint in a </span><span class="o">(</span><span class="nb">non</span><span class="o">-</span><span class="nb">Prolog</span><span class="o">)</span><span class="nb"> syntax that is </span>
</div><div id="l3074" class="code_block"><span class="nb">used by several ASP systems.</span>
</div><div id="l3075" class="code_block">
</div><div id="l3076" class="code_block"><span class="nv">\end</span><span class="nb">{description}</span>
</div><div id="l3077" class="code_block">
</div><div id="l3078" class="code_block"><span class="nv">\section</span><span class="nb">{Other Libraries}</span>
</div><div id="l3079" class="code_block"><span class="c">%================================</span>
</div><div id="l3080" class="code_block">
</div><div id="l3081" class="code_block"><span class="nb">Not all XSB libraries are fully documented.  We provide brief</span>
</div><div id="l3082" class="code_block"><span class="nb">summaries of some of these other libraries.</span>
</div><div id="l3083" class="code_block">
</div><div id="l3084" class="code_block"><span class="nv">\subsection</span><span class="nb">{Justification}</span>
</div><div id="l3085" class="code_block"><span class="c">%</span>
</div><div id="l3086" class="code_block"><span class="nv">\index</span><span class="nb">{Code authors</span><span class="o">!</span><span class="nb">Guo, Hai</span><span class="o">-</span><span class="nb">Feng}</span>
</div><div id="l3087" class="code_block"><span class="nb">By Hai</span><span class="o">-</span><span class="nb">Feng Guo</span>
</div><div id="l3088" class="code_block">
</div><div id="l3089" class="code_block"><span class="nb">Most Prolog debuggers, including XSB&#39;s, are based on a mechanism that</span>
</div><div id="l3090" class="code_block"><span class="nb">allows a user to trace the evaluation of a goal by interrupting the</span>
</div><div id="l3091" class="code_block"><span class="nb">evaluation at call, success, retry, or failure of various subgoals.</span>
</div><div id="l3092" class="code_block"><span class="nb">While this has proved an excellent mechanism for evaluating SLD</span><span class="o">(</span><span class="nb">NF</span><span class="o">)</span>
</div><div id="l3093" class="code_block"><span class="nb">executions, it is difficult at best to use such a mechanism during a</span>
</div><div id="l3094" class="code_block"><span class="nb">tabled evaluation.  This is because, unlike with SLD</span><span class="o">(</span><span class="nb">NF</span><span class="o">)</span><span class="nb">, SLG requires</span>
</div><div id="l3095" class="code_block"><span class="nb">answers to be returned to tabled subgoals at various times </span><span class="o">(</span><span class="nb">depending</span>
</div><div id="l3096" class="code_block"><span class="nb">on whether batched or local evaluation is used</span><span class="o">)</span><span class="nb">, negative subgoals to</span>
</div><div id="l3097" class="code_block"><span class="nb">be sometimes be delayed and</span><span class="o">/</span><span class="nb">or simplified, etc.</span>
</div><div id="l3098" class="code_block">
</div><div id="l3099" class="code_block"><span class="nb">One approach to understanding tabled evaluation better is to abstract</span>
</div><div id="l3100" class="code_block"><span class="nb">away the procedural aspects of debugging and to use the tables</span>
</div><div id="l3101" class="code_block"><span class="nb">produced by an evaluation to construct a {</span><span class="nv">\em</span><span class="nb"> justification} after the</span>
</div><div id="l3102" class="code_block"><span class="nb">evaluation has finished.  The justification library does just this</span>
</div><div id="l3103" class="code_block"><span class="nb">using algorithms described in </span><span class="nv">\cite</span><span class="nb">{GuRR</span><span class="m">01</span><span class="nb">}.</span>
</div><div id="l3104" class="code_block">
</div><div id="l3105" class="code_block"><span class="nv">\subsection</span><span class="nb">{AVL Trees}</span>
</div><div id="l3106" class="code_block"><span class="nv">\index</span><span class="nb">{Code authors</span><span class="o">!</span><span class="nb">Carlsson, Mats}</span>
</div><div id="l3107" class="code_block">
</div><div id="l3108" class="code_block"><span class="nb">By Mats Carlsson</span>
</div><div id="l3109" class="code_block">
</div><div id="l3110" class="code_block"><span class="nb">AVL trees provide a mechanism to maintain key value pairs so that loop</span>
</div><div id="l3111" class="code_block"><span class="nb">up, insertion, and deletion all have complexity </span><span class="s">$</span><span class="nb">{</span><span class="k">\cal</span> O<span class="nb">}</span>(<span class="k">\log</span> n)<span class="s">$</span><span class="nb">.  This</span>
</div><div id="l3112" class="code_block"><span class="nb">library contains predicates to transform a sorted list to an AVL tree</span>
</div><div id="l3113" class="code_block"><span class="nb">and back, along with predicates to manipulate the AVL trees. </span>
</div><div id="l3114" class="code_block">
</div><div id="l3115" class="code_block"><span class="c">% Generic justifier for XSB programs; allows justification of T/F/U values</span>
</div><div id="l3116" class="code_block"><span class="c">% NOTE : Any program predicate that depends recursively </span>
</div><div id="l3117" class="code_block"><span class="c">%        on itself through negation must be tabled.</span>
</div><div id="l3118" class="code_block"><span class="c">%        This ensures that the delay list of any undefined </span>
</div><div id="l3119" class="code_block"><span class="c">%        atom can be accessed (say via get_residual/2).</span>
</div><div id="l3120" class="code_block">
</div><div id="l3121" class="code_block">
</div><div id="l3122" class="code_block"><span class="nv">\subsection</span><span class="nb">{Ordered Sets: {</span><span class="nv">\tt</span><span class="nb"> ordsets.P}}</span>
</div><div id="l3123" class="code_block"><span class="nv">\index</span><span class="nb">{Code authors</span><span class="o">!</span><span class="nb">O&#39;Keefe, Richard}</span>
</div><div id="l3124" class="code_block"><span class="nb">By Richard O&#39;Keefe</span>
</div><div id="l3125" class="code_block">
</div><div id="l3126" class="code_block"><span class="c">%</span>
</div><div id="l3127" class="code_block"><span class="o">(</span><span class="nb">Summary from code documentation</span><span class="o">)</span><span class="nb"> {</span><span class="nv">\tt</span><span class="nb"> ordset.P} provides an XSB port</span>
</div><div id="l3128" class="code_block"><span class="nb">  of the widely used ordset library, whose summary we paraphrase here.</span>
</div><div id="l3129" class="code_block"><span class="nb">  In the ordset library, sets are represented by ordered lists with no</span>
</div><div id="l3130" class="code_block"><span class="nb">  duplicates.  Thus {</span><span class="nv">\em</span><span class="nb"> </span><span class="nv">\{</span><span class="nb">c,r,a,f,t</span><span class="nv">\}</span><span class="nb">} is represented as {</span><span class="nv">\tt</span>
</div><div id="l3131" class="code_block"><span class="nb">    </span><span class="o">[</span><span class="nb">a,c,f,r,t</span><span class="o">]</span><span class="nb">}.  The ordering is defined by the </span><span class="nv">\verb</span><span class="nb">|@&lt;| family of</span>
</div><div id="l3132" class="code_block"><span class="nb">  term comparison predicates, which is the ordering used by {</span><span class="nv">\tt</span>
</div><div id="l3133" class="code_block"><span class="nb">    sort</span><span class="o">/</span><span class="m">2</span><span class="nb">} and {</span><span class="nv">\tt</span><span class="nb"> setof</span><span class="o">/</span><span class="m">3</span><span class="nb">}.  The benefit of the ordered</span>
</div><div id="l3134" class="code_block"><span class="nb">  representation is that the elementary set operations can be done in</span>
</div><div id="l3135" class="code_block"><span class="nb">  time proportional to the sum of the argument sizes rather than their</span>
</div><div id="l3136" class="code_block"><span class="nb">  product.  Some of the unordered set routines, such as {</span><span class="nv">\tt</span>
</div><div id="l3137" class="code_block"><span class="nb">    member</span><span class="o">/</span><span class="m">2</span><span class="nb">}, {</span><span class="nv">\tt</span><span class="nb"> length</span><span class="o">/</span><span class="m">2</span><span class="nb">}, or {</span><span class="nv">\tt</span><span class="nb"> select</span><span class="o">/</span><span class="m">3</span><span class="nb">} can be used</span>
</div><div id="l3138" class="code_block"><span class="nb">  unchanged.</span>
</div><div id="l3139" class="code_block">
</div><div id="l3140" class="code_block"><span class="nv">\subsection</span><span class="nb">{Unweighted Graphs: {</span><span class="nv">\tt</span><span class="nb"> ugraphs.P}}</span>
</div><div id="l3141" class="code_block"><span class="nv">\index</span><span class="nb">{Code authors</span><span class="o">!</span><span class="nb">Carlsson, Mats}</span>
</div><div id="l3142" class="code_block">
</div><div id="l3143" class="code_block"><span class="nb">By Mats Carlsson</span>
</div><div id="l3144" class="code_block">
</div><div id="l3145" class="code_block"><span class="c">%</span>
</div><div id="l3146" class="code_block"><span class="nb">XSB also includes a library for unweighted graphs.  This library</span>
</div><div id="l3147" class="code_block"><span class="nb">allows for the representation and manipulation of directed and</span>
</div><div id="l3148" class="code_block"><span class="nb">non</span><span class="o">-</span><span class="nb">directed unlabelled graphs, including predicates to find the</span>
</div><div id="l3149" class="code_block"><span class="nb">transitive closure of a graph, maximal paths, minimal paths, and other</span>
</div><div id="l3150" class="code_block"><span class="nb">features.  This library represents graphs as an ordered set of their</span>
</div><div id="l3151" class="code_block"><span class="nb">edges and does not use tabling.  As a result, it may be slower for</span>
</div><div id="l3152" class="code_block"><span class="nb">large graphs than similar predicates based on a datalog representatoin</span>
</div><div id="l3153" class="code_block"><span class="nb">of edges.</span>
</div><div id="l3154" class="code_block">
</div><div id="l3155" class="code_block"><span class="nv">\subsection</span><span class="nb">{Heaps: {</span><span class="nv">\tt</span><span class="nb"> heaps.P}}</span>
</div><div id="l3156" class="code_block"><span class="nv">\index</span><span class="nb">{Code authors</span><span class="o">!</span><span class="nb">O&#39;Keefe, Richard}</span>
</div><div id="l3157" class="code_block">
</div><div id="l3158" class="code_block"><span class="nb">By Richard O&#39;Keefe</span>
</div><div id="l3159" class="code_block">
</div><div id="l3160" class="code_block"><span class="o">(</span><span class="nb">Summary from code documentation</span><span class="o">)</span><span class="nb">.  A heap is a labelled binary tree</span>
</div><div id="l3161" class="code_block"><span class="nb">where the key of each node is less than or equal to the keys of its</span>
</div><div id="l3162" class="code_block"><span class="nb">sons.  The point of a heap is that we can keep on adding new elements</span>
</div><div id="l3163" class="code_block"><span class="nb">to the heap and we can keep on taking out the minimum element.  If</span>
</div><div id="l3164" class="code_block"><span class="nb">there are </span><span class="s">$</span>N<span class="s">$</span><span class="nb"> elements total, the total time is </span><span class="s">$</span><span class="k">\cO</span> (Nlg(N))<span class="s">$</span><span class="nb">.  If</span>
</div><div id="l3165" class="code_block"><span class="nb">you know all the elements in advance, you are better off doing a</span>
</div><div id="l3166" class="code_block"><span class="nb">merge</span><span class="o">-</span><span class="nb">sort, but this file is for when you want to do say a best</span><span class="o">-</span><span class="nb">first</span>
</div><div id="l3167" class="code_block"><span class="nb">search, and have no idea when you start how many elements there will</span>
</div><div id="l3168" class="code_block"><span class="nb">be, let alone what they are.</span>
</div><div id="l3169" class="code_block">
</div><div id="l3170" class="code_block"><span class="nb">A heap is represented as a triple {</span><span class="nv">\tt</span><span class="nb"> t</span><span class="o">(</span><span class="nb">N, Free, Tree</span><span class="o">)</span><span class="nb">} where {</span><span class="nv">\tt</span><span class="nb"> N}</span>
</div><div id="l3171" class="code_block"><span class="nb">is the number of elements in the tree, {</span><span class="nv">\tt</span><span class="nb"> Free} is a list of</span>
</div><div id="l3172" class="code_block"><span class="nb">integers which specifies unused positions in the tree, and {</span><span class="nv">\tt</span><span class="nb"> Tree}</span>
</div><div id="l3173" class="code_block"><span class="nb">is a tree made of t terms for empty subtrees and {</span><span class="nv">\tt</span>
</div><div id="l3174" class="code_block"><span class="nb">  t</span><span class="o">(</span><span class="nb">Key,Datum,Lson,Rson</span><span class="o">)</span><span class="nb">} terms for the rest The nodes of the tree are</span>
</div><div id="l3175" class="code_block"><span class="nb">notionally numbered like this:</span>
</div><div id="l3176" class="code_block"><span class="c">%</span>
</div><div id="l3177" class="code_block"><span class="nv">\begin</span><span class="nb">{verbatim}</span>
</div><div id="l3178" class="code_block"><span class="nb">                                    </span><span class="m">1</span>
</div><div id="l3179" class="code_block"><span class="nb">                    </span><span class="m">2</span><span class="nb">                               </span><span class="m">3</span>
</div><div id="l3180" class="code_block"><span class="nb">             </span><span class="m">4</span><span class="nb">               </span><span class="m">6</span><span class="nb">               </span><span class="m">5</span><span class="nb">               </span><span class="m">7</span>
</div><div id="l3181" class="code_block"><span class="nb">         </span><span class="m">8</span><span class="nb">      </span><span class="m">12</span><span class="nb">      </span><span class="m">10</span><span class="nb">     </span><span class="m">14</span><span class="nb">       </span><span class="m">9</span><span class="nb">       </span><span class="m">13</span><span class="nb">      </span><span class="m">11</span><span class="nb">     </span><span class="m">15</span>
</div><div id="l3182" class="code_block"><span class="nb">      ..  ..  ..  ..  ..  ..  ..  ..  ..  ..  ..  ..  ..  ..  ..  ..</span>
</div><div id="l3183" class="code_block"><span class="nv">\end</span><span class="nb">{verbatim}</span>
</div><div id="l3184" class="code_block">
</div><div id="l3185" class="code_block"><span class="nb">The idea is that if the maximum number of elements that have been in</span>
</div><div id="l3186" class="code_block"><span class="nb">the heap so far is </span><span class="s">$</span>M<span class="s">$</span><span class="nb">, and the tree currently has </span><span class="s">$</span>K<span class="s">$</span><span class="nb"> elements, the</span>
</div><div id="l3187" class="code_block"><span class="nb">tree is some subtreee of the tree of this form having exactly </span><span class="s">$</span>M<span class="s">$</span>
</div><div id="l3188" class="code_block"><span class="nb">elements, and the Free list is a list of </span><span class="s">$</span>K-M<span class="s">$</span><span class="nb"> integers saying which</span>
</div><div id="l3189" class="code_block"><span class="nb">of the positions in the </span><span class="s">$</span>M<span class="s">$</span><span class="o">-</span><span class="nb">element tree are currently unoccupied.</span>
</div><div id="l3190" class="code_block"><span class="nb">This free list is needed to ensure that the cost of passing N elements</span>
</div><div id="l3191" class="code_block"><span class="nb">through the heap is </span><span class="s">$</span><span class="k">\cO</span>(Nlg(M))<span class="s">$</span><span class="nb"> instead of </span><span class="s">$</span><span class="k">\cO</span> (NlgN)<span class="s">$</span><span class="nb">.  For </span><span class="s">$</span>M<span class="s">$</span><span class="nb"> say</span>
</div><div id="l3192" class="code_block"><span class="s">$</span>100<span class="s">$</span><span class="nb"> and </span><span class="s">$</span>N<span class="s">$</span><span class="nb"> say </span><span class="s">$</span>10<span class="nb">^</span>4<span class="s">$</span><span class="nb"> this means a factor of two.</span>
</div><div id="l3193" class="code_block"><span class="c">%</span>
</div><div id="l3194" class="code_block"><span class="nv">\comment</span><span class="nb">{ The cost of the free list is slight.  The storage cost of a</span>
</div><div id="l3195" class="code_block"><span class="nb">  heap in a copying Prolog </span><span class="o">(</span><span class="nb">which Dec</span><span class="o">-</span><span class="m">10</span><span class="nb"> Prolog is not</span><span class="o">)</span><span class="nb"> is </span><span class="m">2</span><span class="nb">K</span><span class="o">+</span><span class="m">3</span><span class="nb">M</span>
</div><div id="l3196" class="code_block"><span class="nb">  words.}</span>
</div><div id="l3197" class="code_block">
</div><div id="l3198" class="code_block"><span class="c">%%% Local Variables:</span>
</div><div id="l3199" class="code_block"><span class="c">%%% mode: latex</span>
</div><div id="l3200" class="code_block"><span class="c">%%% TeX-master: &quot;manual2&quot;</span>
</div><div id="l3201" class="code_block"><span class="c">%%% End:</span>
</div></pre></div></td></tr></table></div>

      
    </div>
  

                    </div>
                    
                    
                </div>
            



        </div>
    </section>
      

    <footer class="sandiego">
    <div class="as-row">
        <div class="footer-wrapper">
            <nav aria-label="Site Links" role="navigation">
                <section>
                    <div class="as-h2">SourceForge</div>
                    <ul>
                    
                        <li><a href="/create/" title="Create a Project">Create a Project</a></li>
                    
                        <li><a href="/directory/" title="Open Source Software Directory">Open Source Software</a></li>
                        <li><a href="/software/" title="Business Software Directory">Business Software</a></li>
                        
                            
                            <li><a href="/top" title="Top Open Source Projects">Top Downloaded Projects</a></li>
                        

                    </ul>
                </section>
            </nav>
            <nav aria-label="Company Links" role="navigation">
                <section>
                    <div class="as-h2">Company</div>
                    <ul>
                        <li><a href="/about">About</a></li>
                        <li><a href="/about/leadership" title="Open Source Software Directory">Team</a></li>
                        <li class="h-card">
                            <address>
                                <span class="p-name p-org">SourceForge Headquarters</span><br>
                                <span class="p-street-address">225 Broadway Suite 1600</span><br>
                                <span class="p-locality">San Diego, CA <span class="p-postal-code">92101</span></span><br>
                                <span class="p-tel">+1 (858) 422-6466</span><br>
                            </address>
                        </li>
                        <li id="social">
                            
<span></span>
<a href="https://twitter.com/sourceforge" class="twitter" rel="nofollow" target="_blank" title="SourceForge on X">


<svg  class="vertical-icon-fix" data-name="twitter" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1684 408q-67 98-162 167 1 14 1 42 0 130-38 259.5t-115.5 248.5-184.5 210.5-258 146-323 54.5q-271 0-496-145 35 4 78 4 225 0 401-138-105-2-188-64.5t-114-159.5q33 5 61 5 43 0 85-11-112-23-185.5-111.5t-73.5-205.5v-4q68 38 146 41-66-44-105-115t-39-154q0-88 44-163 121 149 294.5 238.5t371.5 99.5q-8-38-8-74 0-134 94.5-228.5t228.5-94.5q140 0 236 102 109-21 205-78-37 115-142 178 93-10 186-50z"/></svg></a>
<a href="https://fosstodon.org/@sourceforge" rel="me nofollow" target="_blank" title="SourceForge on Mastodon">


<svg  class="vertical-icon-fix" data-name="mastodon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M433 179.11c0-97.2-63.71-125.7-63.71-125.7-62.52-28.7-228.56-28.4-290.48 0 0 0-63.72 28.5-63.72 125.7 0 115.7-6.6 259.4 105.63 289.1 40.51 10.7 75.32 13 103.33 11.4 50.81-2.8 79.32-18.1 79.32-18.1l-1.7-36.9s-36.31 11.4-77.12 10.1c-40.41-1.4-83-4.4-89.63-54a102.54 102.54 0 0 1-.9-13.9c85.63 20.9 158.65 9.1 178.75 6.7 56.12-6.7 105-41.3 111.23-72.9 9.8-49.8 9-121.5 9-121.5zm-75.12 125.2h-46.63v-114.2c0-49.7-64-51.6-64 6.9v62.5h-46.33V197c0-58.5-64-56.6-64-6.9v114.2H90.19c0-122.1-5.2-147.9 18.41-175 25.9-28.9 79.82-30.8 103.83 6.1l11.6 19.5 11.6-19.5c24.11-37.1 78.12-34.8 103.83-6.1 23.71 27.3 18.4 53 18.4 175z"/></svg></a>
<a href="https://www.facebook.com/sourceforgenet/" class="facebook" rel="nofollow" target="_blank" title="SourceForge on Facebook">


<svg  data-name="facebook" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1343 12v264h-157q-86 0-116 36t-30 108v189h293l-39 296h-254v759h-306v-759h-255v-296h255v-218q0-186 104-288.5t277-102.5q147 0 228 12z"/></svg></a>
<a href="https://www.linkedin.com/company/sourceforge.net" class="linkedin" rel="nofollow" target="_blank" title="SourceForge on LinkedIn">


<svg  data-name="linkedin" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M477 625v991h-330v-991h330zm21-306q1 73-50.5 122t-135.5 49h-2q-82 0-132-49t-50-122q0-74 51.5-122.5t134.5-48.5 133 48.5 51 122.5zm1166 729v568h-329v-530q0-105-40.5-164.5t-126.5-59.5q-63 0-105.5 34.5t-63.5 85.5q-11 30-11 81v553h-329q2-399 2-647t-1-296l-1-48h329v144h-2q20-32 41-56t56.5-52 87-43.5 114.5-15.5q171 0 275 113.5t104 332.5z"/></svg></a>

<a href="/user/newsletters" rel=nofollow class="newsletter" title="Subscribe to our newsletter">


<svg  class="vertical-icon-fix" data-name="mmSF_11mail" xmlns="http://www.w3.org/2000/svg" x="0px" y="0px" viewBox="0 0 42 42" enable-background="new 0 0 42 42" xml:space="preserve"><path fill="#FFFFFF" d="M0,6v30h42V6H0z M24.2,21.2c-0.8,0.8-2.3,2-3.2,2c-0.9,0-2.4-1.2-3.2-2L5.8,9.7h30.3L24.2,21.2z M13.7,21l-9.9,9.4V11.6L13.7,21z M15.7,23L15.7,23c0.5,0.5,2.9,2.9,5.3,2.9c2.4,0,4.8-2.4,5.2-2.8l0.1-0.1l9.8,9.4H5.8L15.7,23z M28.3,21l9.9-9.5v18.9L28.3,21z"/></svg></a>

<span></span>
                        </li>
                    </ul>
                </section>
            </nav>
             <nav aria-label="Resources Links" role="navigation">
                <section>
                    <div class="as-h2">Resources</div>
                    <ul>
                        
                            <li><a href="/support" title="Support Section">Support</a></li>
                            <li><a href="/p/forge/documentation/Docs%20Home/" title="Site Documentation">Site Documentation</a></li>
                        
                        <li><a href="https://fosstodon.org/@sourceforgestatus" title="Site Status" rel="me nofollow">Site Status</a></li>
                        <li><a href="/reviews" title="Reviews" rel="me nofollow">SourceForge Reviews</a></li>

                    </ul>
                </section>
            </nav>
            <section class="footer-logo">
                <a href="/" title="Home" class="sf-logo">
                    
    
    <img src="https://a.fsdn.com/con/images/sandiego/sf-logo-full.svg"  alt="SourceForge logo" class="sf-logo-full"/>
                </a>
            </section>
        </div>
    </div>
    <section class="l-nav-bottom">
        <nav class="row">
            
                
            
        
    <div class="columns small-12 large-6 copyright-notice">
        &copy; 2025 Slashdot Media. All Rights Reserved.
    </div>
    <div class="columns large-6 links links-right">
        

    
    

    <a href="https://slashdotmedia.com/terms-of-use" target="_blank" title="Terms" rel="nofollow">Terms</a>
    <a href="https://slashdotmedia.com/privacy-statement/" target="_blank" title="Privacy" rel="nofollow">Privacy</a>

    
    
    

    
        <a href="https://slashdotmedia.com/opt-out-choices/" target="_blank" title="Opt Out" rel="nofollow">Opt Out</a>
    

    
        <a href="https://slashdotmedia.com/contact/" target="_blank" title="Advertise" rel="nofollow">Advertise</a>
    
    </div>
        </nav>
    </section>

    </footer>
    





    
    
    <div id="newsletter-floating" class="sandiego newsletter-floating-new">
        <a class="close-button btn-closer" data-close aria-label="Close modal">
            <span aria-hidden="true">&times;</span>
        </a>
        <div class="as-h2">Want the latest updates on software, tech news, and AI?</div>
        <div class="row">
            <div class="column small-2 medium-2 large-2" style="padding-left: 0px; padding-right: 0px;"><img src="/images/sandiego/sf_email_icon.svg"  alt="" /></div>
            <div class="as-h3 column small-10 medium-10 large-10">Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.</div>
        </div>
        <form action="/user/newsletters/" method="post">
            <div class="row">
              <input class="newsletter-input" type="email" placeholder="Enter your email address" autocomplete="off" name="newsletter_email"
                     value="">
              <input type="hidden" name="source" value="floating">
              <button type="submit" class="button blue newsletter-button">Submit</button>
            </div>
        </form>
    </div>
    






</div>


<div id="messages">
    
</div>


    <!-- ew:body_js -->


    <script type="text/javascript" src="https://a.fsdn.com/allura/nf/1753722141/_ew_/_slim/js?href=allura%2Fjs%2Fjquery.notify.js%3Ballura%2Fjs%2Fjquery.tooltipster.js%3Ballura%2Fjs%2Fallura-base.js%3Ballura%2Fjs%2Fchecklist.js%3Ballura%2Fjs%2Fadmin_modal.js%3Bjs%2Fjquery.lightbox_me.js%3Ballura%2Fjs%2Fmemorable.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fshared.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fsticky.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fsandiego%2Fchrome.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fsandiego%2Futilities.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fvendor%2Ffoundation6%2Fplugins%2Ffoundation.core.min.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fvendor%2Ffoundation6%2Fplugins%2Ffoundation.util.mediaQuery.min.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fvendor%2Ffoundation6%2Fplugins%2Ffoundation.util.keyboard.min.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fvendor%2Ffoundation6%2Fplugins%2Ffoundation.util.box.min.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fvendor%2Ffoundation6%2Fplugins%2Ffoundation.util.nest.min.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fvendor%2Ffoundation6%2Fplugins%2Ffoundation.dropdownMenu.min.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fvendor%2Ffoundation6%2Fplugins%2Ffoundation.offcanvas.min.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fvendor%2Ffoundation6%2Fplugins%2Ffoundation.toggler.min.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fsandiego%2Fproject.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fvendor%2Fjquery.typeahead.min.js%3Ballura%2Fjs%2Fmaximize-content.js"></script>

    
<!-- /ew:body_js -->



    <!-- ew:body_js_tail -->


    <script type="text/javascript" src="https://a.fsdn.com/allura/nf/1753722141/_ew_/_slim/js?href=theme%2Fsftheme%2Fjs%2Fsftheme%2Fvendor%2Ffoundation6%2Fplugins%2Ffoundation.util.triggers.min.js%3Btheme%2Fsftheme%2Fjs%2Fsftheme%2Fvendor%2Ffoundation6%2Fplugins%2Ffoundation.reveal.min.js"></script>

    
<!-- /ew:body_js_tail -->




<script type="text/javascript">(function() {
  $('#access_urls .btn').click(function(evt){
    evt.preventDefault();
    var parent = $(this).parents('.btn-bar');
    var checkout_cmd = $(this).attr('data-url');
    $(parent).find('input').val(checkout_cmd);
    $(parent).find('span').text($(this).attr('title')+' access');
    $(this).parent().children('.btn').removeClass('active');
    $(this).addClass('active');
    if (checkout_cmd.indexOf(' http://') !== -1 || checkout_cmd.indexOf(' https://') !== -1 ) {
      $('#http-2fa-msg').show();
    } else {
      $('#http-2fa-msg').hide();
    }
  });
  $('#access_urls .btn').first().click();

  
  var repo_status = document.getElementById('repo_status');
  // The repo_status div will only be present if repo.status != 'ready'
  if (repo_status) {
    $('.spinner').show()
    var delay = 500;
    function check_status() {
        $.get('/p/xsb/src/status', function(data) {
            if (data.status === 'ready') {
                $('.spinner').hide()
                $('#repo_status h2').html('Repo status: ready. <a href="." rel="nofollow">Click here to refresh this page.</a>');
            }
            else {
                $('#repo_status h2 span').html(data.status);
                if (delay < 60000){
                    delay = delay * 2;
                }
                window.setTimeout(check_status, delay);
            }
        });
    }
    var status_checker = window.setTimeout(check_status, delay);
    
  }
}());
</script>

<script type="text/javascript">(function() {
  $(window).on('hashchange', function(e) {
    var hash = window.location.hash.substring(1);
    if ('originalEvent' in e && 'oldURL' in e.originalEvent) {
      $('#' + e.originalEvent.oldURL.split('#')[1]).css('background-color', 'transparent');
    }
    if (hash !== '' && hash.substring(0, 1) === 'l' && !isNaN(hash.substring(1))) {
      $('#' + hash).css('background-color', '#ffff99');
    }
  }).trigger('hashchange');

  var clicks = 0;
  $('.code_block').each(function(index, element) {
    $(element).on('click', function() {
      // Trick to ignore double and triple clicks
      clicks++;
      if (clicks === 1) {
        setTimeout(function() {
          if (clicks === 1) {
            var hash = window.location.hash.substring(1);
            if (hash !== '' && hash.substring(0, 1) === 'l' && !isNaN(hash.substring(1))) {
              $('#' + hash).css('background-color', 'transparent');
            }
            $(element).css('background-color', '#ffff99');
            window.history.pushState({}, document.title, window.location.pathname + window.location.search + '#' + $(element).attr('id'));
          }
          clicks = 0;
        }, 500);
      }
    });
  });
}());
</script>


    


    
    
    <noscript><p><img src="https://analytics.slashdotmedia.com/index.php?idsite=39" style="border:0;position:absolute;top:0;" alt="" /></p></noscript>
    
    <script>
        $(document).foundation();
    </script>
    








    

<script>
    (function () {
        function load_bombora() {
            /*global _ml:true, window */
            _ml = window._ml || {};
            
            _ml.eid = '771';
            _ml.fp = '4a069542-71c8-4d9a-a4e6-2bb5405af62a';  
            var s = document.getElementsByTagName('script')[0], cd = new Date(), mltag = document.createElement('script');
            mltag.type = 'text/javascript';
            mltag.async = true;
            mltag.defer = true;
            mltag.src = '//ml314.com/tag.aspx?' + cd.getDate() + cd.getMonth() + cd.getFullYear();
            s.parentNode.insertBefore(mltag, s);
        }
        bizx.cmp.ifConsent({ purposes: 'all', vendors: 'bombora'}, load_bombora);
    })();
</script>




<script>
    $(document).ready(function () {
        $(".tooltip, .m-tooltip").each(function(){
            let $el = $(this);
            $el.tooltipster({
                animation: 'fade',
                delay: 200,
                theme: 'tooltipster-light',
                trigger: 'hover',
                position: $el.data('position') || 'right',
                iconCloning: false,
                maxWidth: 300,
                contentAsHTML: true,
                interactive: true
            }).focus(function () {
                $(this).tooltipster('show');
            }).blur(function () {
                $(this).tooltipster('hide');
            });
        });
    });
</script>

    



<script type="text/javascript">
    bizx.cmp.ifConsent({ purposes: ['storage', 'measurement'], vendors: 'google-analytics'}, function () {
        /* jshint ignore:start */
        (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
                (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
            m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
        })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
        /* jshint ignore:end */

        window.dataLayer = window.dataLayer || [];
        function gtag(){ window.dataLayer.push(arguments); }
        window.gtag = window.gtag || gtag;
        bizx.cmp.embedScript("https://www.googletagmanager.com/gtag/js");
        gtag('js', new Date());
        gtag('set', {
            'page_location': 'https://sourceforge.net/p/xsb/src/6869/tree/trunk/XSB/docs/userman/library.tex',
        });
    });
</script>










<script>
        function gam(id){
            bizx.cmp.ifConsent({ purposes: 'all' }, function () {
                bizx.cmp.embedScript(`https://pagead2.googlesyndication.com/pagead/js/pcd.js?${id}`,
                    true,  // async
                    'head', // location
                    null, // callback
                    false, // defer
                    {id: `google-pcd-tag-${id}`, 'data-audience-pixel': 'dc_iu=/41014381/DFPAudiencePixel;dc_seg=' + id});
            });
        }

        
            gam("8901705213");gam("8901712041");</script>

<script type="text/javascript">
    /*global ga, gtag */

    
        
        bizx.cmp.ifConsent({ purposes: ['storage', 'measurement'], vendors: 'google-analytics'}, function () {
            gtag('config', 'G-1H226E4E4L', {
                
                send_page_view: false,
                'SF_Page_Type': '', 
                user_properties: {
                    'SF_Logged_in': 'Logged Out', 
                },
                'devicePixelRatio': SF.devicePixelRatio, 
            });
            gtag('event', 'page_view', { send_to: 'G-1H226E4E4L' });
        });
    
    
    
        
</script>

</body>
</html>