
<!DOCTYPE html>


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Functions &#8212; puddletag</title>
    
    <link rel="stylesheet" href="../_static/basic.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootstrap.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootswatch-3.3.6/flatly/bootstrap.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootstrap-sphinx.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '0.10.3',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/js/jquery-1.11.0.min.js"></script>
    <script type="text/javascript" src="../_static/js/jquery-fix.js"></script>
    <script type="text/javascript" src="../_static/bootstrap-3.3.6/js/bootstrap.min.js"></script>
    <script type="text/javascript" src="../_static/bootstrap-sphinx.js"></script>
    <link rel="author" title="About these documents" href="../about.html" />
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="top" title="puddletag" href="../index.html" />
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">

  </head>
  <body role="document">

  <div id="navbar" class="navbar navbar-default navbar-fixed-top">
    <div class="container">
      <div class="navbar-header">
        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand" href="../index.html">puddletag</a>
      </div>

        <div class="collapse navbar-collapse nav-collapse">
          <ul class="nav navbar-nav">
            <li class="divider-vertical"></li>
            
                <li><a href="../index.html">Home</a></li>
                <li><a href="../download.html">Download</a></li>
                <li><a href="../news.html">News</a></li>
                <li><a href="../docs.html">Documentation</a></li>
                <li><a href="https://github.com/puddletag/puddletag/issues">Issue Tracker</a></li>
                <li><a href="../screenshots.html">Screenshots</a></li>
                <li><a href="../about.html">About</a></li>
            
            
              
              
            
            
            
            
            
          </ul>

          
            
<form class="navbar-form navbar-right" action="../search.html" method="get">
 <div class="form-group">
  <input type="text" name="q" class="form-control" placeholder="Search" />
 </div>
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </div>
    </div>
  </div>

<div class="container">
  <div class="row">
      <div class="col-md-3">
        <div id="sidebar" class="bs-sidenav" role="complementary"><ul>
<li><a class="reference internal" href="#">Functions</a><ul>
<li><a class="reference internal" href="#autonumbering">Autonumbering</a></li>
<li><a class="reference internal" href="#case-conversion">Case Conversion</a></li>
<li><a class="reference internal" href="#convert-from-non-standard-encoding">Convert from non-standard encoding</a></li>
<li><a class="reference internal" href="#export-artwork-to-file">Export artwork to file</a></li>
<li><a class="reference internal" href="#filename-to-tag">Filename to Tag</a></li>
<li><a class="reference internal" href="#format-value">Format value</a></li>
<li><a class="reference internal" href="#import-text-file">Import text file</a></li>
<li><a class="reference internal" href="#load-artwork">Load artwork</a></li>
<li><a class="reference internal" href="#merge-field">Merge Field</a></li>
<li><a class="reference internal" href="#remove-fields">Remove Fields</a></li>
<li><a class="reference internal" href="#remove-all-fields-except">Remove all fields except</a></li>
<li><a class="reference internal" href="#remove-duplicate-values">Remove duplicate values</a></li>
<li><a class="reference internal" href="#replace">Replace</a></li>
<li><a class="reference internal" href="#replace-with-regexp">Replace with RegExp</a></li>
<li><a class="reference internal" href="#sort-values">Sort values</a></li>
<li><a class="reference internal" href="#split-field-using-separator">Split field using separator</a></li>
<li><a class="reference internal" href="#tag-to-dir">Tag to Dir</a></li>
<li><a class="reference internal" href="#tag-to-filename">Tag to filename</a></li>
<li><a class="reference internal" href="#text-to-tag">Text To Tag</a></li>
<li><a class="reference internal" href="#trim-whitespace">Trim Whitespace</a></li>
<li><a class="reference internal" href="#update-from-tag">Update From Tag</a></li>
</ul>
</li>
</ul>


<hr style='width:80%'>


        </div>
      </div>
    <div class="col-md-9 content">
      
  <div class="section" id="functions">
<h1>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h1>
<div class="section" id="autonumbering">
<span id="id1"></span><h2>Autonumbering<a class="headerlink" href="#autonumbering" title="Permalink to this headline">¶</a></h2>
<div class="section" id="arguments">
<h3>Arguments<a class="headerlink" href="#arguments" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Start</li>
<li>Max Length After Padding</li>
<li>Restart Numbering</li>
</ol>
</div>
<div class="section" id="description">
<h3>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h3>
<p>Numbers tracks sequentially beginning with <strong>Start</strong>.</p>
<p>The number you enter in <strong>Max Length After Padding</strong> will pad the track with extra zeroes until it&#8217;s of the same length. Eg. if a file has track number &#8216;12&#8217;, having a padding of 3 will return the number &#8216;012&#8217;, while a padding of 1 will leave the number unchanged since it&#8217;s length is already greater than the Max Length.</p>
<p>Restart Numbering at each directory will restart the numbering from <strong>Start</strong> for each directory encountered. A separate count will be kept for each directory.</p>
</div>
</div>
<div class="section" id="case-conversion">
<span id="id2"></span><h2>Case Conversion<a class="headerlink" href="#case-conversion" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id3">
<h3>Arguments<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Type</li>
<li>Word Delimiter</li>
</ol>
</div>
<div class="section" id="id4">
<h3>Description<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3>
<p>There are three types of case conversion: <strong>UPPER CASE</strong>,** lower case** and** Mixed Case**. Upper and lower are self-explanatory. Mixed case capitalises each word starting after the characters you specify and converts the rest to lower case.</p>
<p>For instance, using Mixed Case with &#8220;<strong>.</strong>&#8221; as a delineator on <em>&#8220;this is my name. and my surname. with a dot.here and there.&#8221;</em> will return <em>&#8216;This Is My Name. And My Surname. With A Dot.Here And There.&#8217;</em></p>
</div>
</div>
<div class="section" id="convert-from-non-standard-encoding">
<span id="id5"></span><h2>Convert from non-standard encoding<a class="headerlink" href="#convert-from-non-standard-encoding" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id6">
<h3>Arguments<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Encoding</li>
</ol>
</div>
<div class="section" id="id7">
<h3>Description<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h3>
<p>If your files were written using non-standard encoding (eg cp1251 on Windows) you can use this Function to fix &#8216;em.</p>
</div>
</div>
<div class="section" id="export-artwork-to-file">
<span id="id8"></span><h2>Export artwork to file<a class="headerlink" href="#export-artwork-to-file" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id9">
<h3>Arguments<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Pattern</li>
</ol>
</div>
<div class="section" id="id10">
<h3>Description<a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h3>
<p>Saves all artwork found in an audio file using the desired <strong>Pattern</strong>. Extensions are added automatically.</p>
<p>If a picture file already exists &#8216;_1&#8217; will be appended to the filename (before the extension). If that file already exists &#8216;_2&#8217; will be appended and so on. This will not be done for cases where two or more files contain <em>exactly</em> the same picture data and are to be written to the same filename.</p>
<p>Usage of the following fields are allowed:</p>
<dl class="describe">
<dt>
<code class="descname">img_desc</code></dt>
<dd><p>The description of the current image.</p>
</dd></dl>

<dl class="describe">
<dt>
<code class="descname">img_count</code></dt>
<dd><p>The number of images contained in the file.</p>
</dd></dl>

<dl class="describe">
<dt>
<code class="descname">img_counter</code></dt>
<dd><p>The number current image being processed.</p>
</dd></dl>

<dl class="describe">
<dt>
<code class="descname">img_mime</code></dt>
<dd><p>The mimetype of the current image.</p>
</dd></dl>

<dl class="describe">
<dt>
<code class="descname">img_type</code></dt>
<dd><p>The image type, eg. <em>Cover (Front)</em>.</p>
</dd></dl>

</div>
<div class="section" id="examples">
<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
<p>Consider a file <em>/mnt/music/Thebe/Ungawa Kum.mp3</em> containing four images. The first two PNG images and the last two JPEG. Descriptions are &#8216;one&#8217;, &#8216;two&#8217;, etc. for each image.</p>
<ul class="simple">
<li>The pattern <em>folder_%img_counter%</em> will create four images in <em>/mnt/music/Thebe</em>: <strong>folder_1.png, folder_2.png, folder_3.jpg</strong> and <strong>folder_4.jpg</strong>.</li>
<li><em>%img_desc%</em> will create four images in <em>/mnt/music/Thebe</em>: <strong>one.png, two.png, three.jpg</strong> and <strong>four.jpg</strong>.</li>
<li><em>/home/user/Desktop/%artist%</em> will create four images in <em>/home/user/Desktop</em>: <strong>Thebe_1.png, Thebe_2.png, Thebe_3.jpg</strong> and <strong>Thebe_4.jpg</strong>.</li>
</ul>
</div>
</div>
<div class="section" id="filename-to-tag">
<span id="id11"></span><h2>Filename to Tag<a class="headerlink" href="#filename-to-tag" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id12">
<h3>Arguments<a class="headerlink" href="#id12" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Pattern</li>
</ol>
</div>
<div class="section" id="id13">
<h3>Description<a class="headerlink" href="#id13" title="Permalink to this headline">¶</a></h3>
<p>See <a class="reference internal" href="menus.html#menus-file-to-tag"><span class="std std-ref">File-&gt;Tag (Ctrl+T)</span></a>.</p>
</div>
</div>
<div class="section" id="format-value">
<span id="id14"></span><h2>Format value<a class="headerlink" href="#format-value" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id15">
<h3>Arguments<a class="headerlink" href="#id15" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Format string (also referred to as a Pattern)</li>
</ol>
</div>
<div class="section" id="id16">
<h3>Description<a class="headerlink" href="#id16" title="Permalink to this headline">¶</a></h3>
<p>Formats whatever is passed to it using the Format string.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Extensions are <em>not</em> added if you modify filename related fields using this Function.</p>
</div>
</div>
<div class="section" id="id17">
<h3>Examples<a class="headerlink" href="#id17" title="Permalink to this headline">¶</a></h3>
<p>A Format string can be (almost) any string. Eg. for a file with the tag, <em>artist=A Guy</em>, <em>album=Screeching</em>, <em>title=Excessively Emo</em>, <em>track=2</em></p>
<ul class="simple">
<li>Using &#8216;I wanna write my own.&#8217; as a Format string will return &#8216;I wanna write my own.&#8217; and write it to the fields you choose.</li>
<li>Individual fields can be referenced by placing them inbetween percent characters (%). So <strong>%artist%</strong> will return &#8216;A Guy&#8217;, <strong>%album%</strong>, &#8216;Screeching&#8217; and so on for the others. Using <strong>%genre%</strong> would return nothing, because there ain&#8217;t no genre field in the tag.</li>
<li>You can combine fields with any combination of letters as in <strong>I don&#8217;t like an %title% %artist%...%album%</strong>. Returning, &#8216;I don&#8217;t like an Excessively Emo A Guy...Screeching&#8217;</li>
<li>More editing power is available via the scripting functions. They have the format <strong>$name(arguments)</strong>. See the <a class="reference internal" href="scripting.html"><span class="doc">scripting functions page</span></a> for a listing. They can be simple eg. <strong>$upper(value)</strong> will return &#8216;VALUE&#8217;, <strong>$lower(%artist%)</strong> will return &#8216;a guy&#8217;. You can even combine/nest them to get what you want as in <strong>I don&#8217;t like an $lower(%title% $mid(%artist%,2,10)) $lower(%album%).</strong> giving &#8220;I don&#8217;t like an excessively emo guy screeching.&#8221;</li>
</ul>
</div>
</div>
<div class="section" id="import-text-file">
<span id="id18"></span><h2>Import text file<a class="headerlink" href="#import-text-file" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id19">
<h3>Arguments<a class="headerlink" href="#id19" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Pattern</li>
</ol>
</div>
<div class="section" id="id20">
<h3>Description<a class="headerlink" href="#id20" title="Permalink to this headline">¶</a></h3>
<p>Loads the filename described by the Pattern into the field specified. Note that the files complete text is loaded into that field.</p>
</div>
<div class="section" id="id21">
<h3>Examples<a class="headerlink" href="#id21" title="Permalink to this headline">¶</a></h3>
<p>For the file with path <strong>/mnt/Music/artist/album/filename.mp3</strong> and with the tag, <strong>artist=Black Eyed Peas, album=END</strong></p>
<ul class="simple">
<li>lyrics.txt will load the text file from /mnt/Music/artist/album/lyrics.txt</li>
<li>../lyrics.txt will load the file at /mnt/Music/artist/lyrics.txt</li>
<li>%album% will load the file at /mnt/Music/artist/album/<strong>END</strong>. No extensions will be added.</li>
<li>/mnt/textfiles/lyrics.txt will load from the file at /mnt/textfiles/lyrics.txt</li>
</ul>
</div>
</div>
<div class="section" id="load-artwork">
<span id="id22"></span><h2>Load artwork<a class="headerlink" href="#load-artwork" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id23">
<h3>Arguments<a class="headerlink" href="#id23" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Filenames</li>
<li>Default description</li>
<li>Match Case</li>
</ol>
</div>
<div class="section" id="id24">
<h3>Description<a class="headerlink" href="#id24" title="Permalink to this headline">¶</a></h3>
<p>Loads the artwork in filenames to the specified file.</p>
<p>Filenames are a colon-separated list of shell-style wildcards, eg. <strong>*.jpg;*.png</strong>. Or just something like <strong>folder.jpg</strong>. The files will be loaded in order and the images.</p>
<p>Default description can be any pattern, eg. <strong>%artist%</strong>.</p>
<p>Match Case is pretty self-explanatory.</p>
<p>Be aware that for now that the directory that&#8217;ll be searched will be polled every single time this Function is called, so don&#8217;t use it on large directories.</p>
</div>
</div>
<div class="section" id="merge-field">
<span id="id25"></span><h2>Merge Field<a class="headerlink" href="#merge-field" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id26">
<h3>Arguments<a class="headerlink" href="#id26" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Separator</li>
</ol>
</div>
<div class="section" id="id27">
<h3>Description<a class="headerlink" href="#id27" title="Permalink to this headline">¶</a></h3>
<p>Merges the values of a multiple-valued field into a single string, separated by <strong>Separator</strong>.</p>
<p>eg. Say the genre field contained <strong>Rock, Rap and Reggae</strong> as distinct values. Merging them using the separator <strong>;</strong> (semi-colon) will replace whichever field you specify with the single value <strong>Rock;Rap;Reggae</strong>.</p>
</div>
</div>
<div class="section" id="remove-fields">
<span id="id28"></span><h2>Remove Fields<a class="headerlink" href="#remove-fields" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id29">
<h3>Description<a class="headerlink" href="#id29" title="Permalink to this headline">¶</a></h3>
<p>Removes the fields you specify [separated by a comma &#8220;<strong>,</strong>&#8220;].</p>
</div>
</div>
<div class="section" id="remove-all-fields-except">
<span id="id30"></span><h2>Remove all fields except<a class="headerlink" href="#remove-all-fields-except" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id31">
<h3>Arguments<a class="headerlink" href="#id31" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Field list</li>
</ol>
</div>
<div class="section" id="id32">
<h3>Description<a class="headerlink" href="#id32" title="Permalink to this headline">¶</a></h3>
<p>Removes all the fields in the file (including cover art) except the ones you specify. The list of fields you specify are separated by a semi-colon (<strong>;</strong>). Any spaces around the field names are trimmed, so <strong>artist;title</strong> and ** artist; title ** are equivalent.</p>
</div>
</div>
<div class="section" id="remove-duplicate-values">
<span id="id33"></span><h2>Remove duplicate values<a class="headerlink" href="#remove-duplicate-values" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id34">
<h3>Arguments<a class="headerlink" href="#id34" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Match case</li>
</ol>
</div>
<div class="section" id="id35">
<h3>Description<a class="headerlink" href="#id35" title="Permalink to this headline">¶</a></h3>
<p>Removes all duplicate values in a multiple-valued field. Case sensitively or not.</p>
<p>Eg. if a field has the following values <strong>Rap, Rock and rap</strong>. Using this function on it (without case-sensitivity) will leave <strong>Rap</strong> and <strong>Rock</strong> as the only values.</p>
</div>
</div>
<div class="section" id="replace">
<span id="id36"></span><h2>Replace<a class="headerlink" href="#replace" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id37">
<h3>Arguments<a class="headerlink" href="#id37" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Text to replace</li>
<li>Text to replace with</li>
<li>Match Case</li>
<li>Only as whole word</li>
</ol>
</div>
<div class="section" id="id38">
<h3>Description<a class="headerlink" href="#id38" title="Permalink to this headline">¶</a></h3>
<p>It works just as you&#8217;d expect from any text editor. The only caveat is that words are designated by these <strong>,.() !</strong> characters.</p>
</div>
</div>
<div class="section" id="replace-with-regexp">
<span id="id39"></span><h2>Replace with RegExp<a class="headerlink" href="#replace-with-regexp" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id40">
<h3>Arguments<a class="headerlink" href="#id40" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>The regular expression</li>
<li>Replacement string</li>
</ol>
</div>
<div class="section" id="id41">
<h3>Description<a class="headerlink" href="#id41" title="Permalink to this headline">¶</a></h3>
<p>Matches a regular expression. Groups can then be retrieved using $group_number (counting starts from one) eg $2.</p>
</div>
<div class="section" id="id42">
<h3>Examples<a class="headerlink" href="#id42" title="Permalink to this headline">¶</a></h3>
<p>Some examples for the text, &#8216;concentricpuddle writes this&#8217;.</p>
<ul class="simple">
<li>regexp=(concentricpuddle) and repl=$upper($1) =&gt; &#8216;CONCENTRICPUDDLE&#8217;</li>
<li>regexp=&#8217;(concentricpuddle) writes (this)&#8217;, repl=&#8217;$upper($1) wrote $2&#8217; =&gt; &#8216;CONCENTRICPUDDLE wrote this&#8217;</li>
<li>regexp=&#8217;(concentricpuddle) writes (this)&#8217;, repl=&#8217;$upper($1) wrote $3&#8217; =&gt; &#8216;CONCENTRICPUDDLE wrote $3&#8217;, because $3 wasn&#8217;t found.</li>
<li>regexp=&#8217;(c.*puddle)&#8217;, repl=&#8217;name=$1&#8217; =&gt; &#8216;name=concentricpuddle&#8217;</li>
</ul>
</div>
</div>
<div class="section" id="sort-values">
<span id="id43"></span><h2>Sort values<a class="headerlink" href="#sort-values" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id44">
<h3>Arguments<a class="headerlink" href="#id44" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Sort Order</li>
<li>Match Case</li>
</ol>
</div>
<div class="section" id="id45">
<h3>Description<a class="headerlink" href="#id45" title="Permalink to this headline">¶</a></h3>
<p>Sorts the values in a multiple-valued field using either Ascending or Descending order. Arguments are pretty self-explanatory.</p>
</div>
</div>
<div class="section" id="split-field-using-separator">
<span id="id46"></span><h2>Split field using separator<a class="headerlink" href="#split-field-using-separator" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id47">
<h3>Arguments<a class="headerlink" href="#id47" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Separator</li>
</ol>
</div>
<div class="section" id="id48">
<h3>Description<a class="headerlink" href="#id48" title="Permalink to this headline">¶</a></h3>
<p>Splits the strings found into multiple values using <strong>Separator</strong>.</p>
</div>
<div class="section" id="id49">
<h3>Examples<a class="headerlink" href="#id49" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>If genre=&#8221;Rap;Rock;Dubstep&#8221; splitting it with &#8220;<strong>;</strong>&#8221; as the separator will result in genre (provided you&#8217;re writing to the genre field) having multiple values: <strong>Rap, Rock and Dubstep</strong></li>
<li>If genre were a multiple-valued field with &#8216;Rock;Rap&#8217; and &#8216;Classical;Guitar Solo&#8217; it&#8217;s distinct values. Splitting them with <strong>;</strong> as the separator will split each value and combine them into the multiple-valued field. In this case we get <strong>Rock, Rap, Classical</strong> and <strong>Guitar Solo</strong> as the distinct values.</li>
</ul>
</div>
</div>
<div class="section" id="tag-to-dir">
<span id="id50"></span><h2>Tag to Dir<a class="headerlink" href="#tag-to-dir" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id51">
<h3>Arguments<a class="headerlink" href="#id51" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Pattern</li>
</ol>
</div>
<div class="section" id="id52">
<h3>Description<a class="headerlink" href="#id52" title="Permalink to this headline">¶</a></h3>
<p>Works as Tag To Filename (below), but renames/moves directories instead. Directories will only be moved if the destination dir resides on the same filesystem as the source.</p>
</div>
</div>
<div class="section" id="tag-to-filename">
<span id="id53"></span><h2>Tag to filename<a class="headerlink" href="#tag-to-filename" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id54">
<h3>Arguments<a class="headerlink" href="#id54" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>The text. Can be any pattern.</li>
</ol>
</div>
<div class="section" id="id55">
<h3>Description<a class="headerlink" href="#id55" title="Permalink to this headline">¶</a></h3>
<p>Converts a tag to filename using the pattern (see above description for Format value).</p>
<p>If the filename contains any of the characters, <strong>\*?;&#8221;|:/</strong>, then they will be removed.</p>
<p>Files can also be moved, by specifying &#8216;/&#8217; as a directory delimeter. Any forward slashes found in the fields used in constructing the pattern are ommitted (if the artist is AC/DC, it will not create an AC directory, rather the slash will be removed and ACDC will be used).</p>
<p>Intermediate directories will be created if they don&#8217;t exist.</p>
</div>
<div class="section" id="id56">
<h3>Examples<a class="headerlink" href="#id56" title="Permalink to this headline">¶</a></h3>
<p>Say you had a file named &#8216;track.mp3&#8217; with the following tag, <strong>artist=Before The Fame, album=The Vinyl LP, title=Sounds Better Than Anything After, track=10</strong> and invoked this function.</p>
<ul class="simple">
<li><em>%artist% - %album% - %track%</em> in the pattern combo will rename it to &#8216;Before The Fame - The Vinyl LP - Sounds Better Than Anything After.mp3&#8217;</li>
<li><em>%artist% - $num(%track%, 3) - %title%</em> will rename it to &#8216;Before The Fame - 010 - Sounds Better Than Anything After.mp3&#8217;</li>
<li><em>%title%_$upper(%album%)-%track%-%artist%</em> will give the filename &#8216;Sounds Better Than Anything After_THE VINYL LP-10-Before The Fame.mp3&#8217;</li>
</ul>
<p>For a file with the tag, <strong>artist=Relatively Unknown, title=Horrible for everyone else, album=Fans like it, track=5</strong> with path, /home/concentricpuddle/multimedia/music/Indie/unsorted/unknown.mp3</p>
<ul class="simple">
<li>%album%/%artist% - %title% will move the file to /home/concentricpuddle/multimedia/music/Indie/<strong>Fans like it/Relatively Unknown - Horrible for everyone else.mp3</strong>.</li>
<li>For every slash, the file is moved up one directory. %artist%/%album%/%title% will move the file to /home/concentricpuddle/multimedia/music/<strong>Relatively Unknown/Fans like it/Horrible for everyone else.mp3</strong></li>
<li>If you want you can also have an absolute path, by starting the pattern with a slash, eg. the pattern /mnt/library/%album%/%track% will move the file to /mnt/library/Fans like it/5.mp3</li>
</ul>
</div>
</div>
<div class="section" id="text-to-tag">
<span id="id57"></span><h2>Text To Tag<a class="headerlink" href="#text-to-tag" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id58">
<h3>Arguments<a class="headerlink" href="#id58" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>The text. Can be any pattern.</li>
<li>The pattern to match the text against. Works like Tag-&gt;Filename except that instead of using fields like %artist% you use tokens denoted by %number like <strong>%1, %3</strong>.</li>
<li>What to output the text as, can be any pattern can be used including tokens delimited by %number.</li>
</ol>
</div>
<div class="section" id="id59">
<h3>Description<a class="headerlink" href="#id59" title="Permalink to this headline">¶</a></h3>
<p>Converts any text from any text to any other text. It&#8217;s better explained by using:</p>
</div>
<div class="section" id="id60">
<h3>Examples<a class="headerlink" href="#id60" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>Say you had the text, &#8216;First Second&#8217;. Using the pattern <em>%1 %2</em> you can reverse the text by using &#8216;%2 %1&#8217; as the output, returning &#8216;Second First&#8217;.</li>
<li>You can use any valid pattern as the text. Say artist=&#8217;Eminem/Recovery&#8217;. Using the pattern <strong>%1/%2</strong> and having %2 in the output means that you can retrieve the album name (Recovery). %1 would return Just &#8216;Eminem&#8217;.</li>
<li>:doc:&#8217;Scripting &lt;scripting&gt;` functions are allowed in the output. Eg. for text=&#8217;Jimmy-01/Rebellious Angel&#8217; and a pattern=&#8217;%1-%2/%3&#8217;, the <strong>$num(%2, 1)</strong> as the output will be evaluated as normal returning just &#8216;1&#8217;.</li>
</ul>
</div>
</div>
<div class="section" id="trim-whitespace">
<span id="id61"></span><h2>Trim Whitespace<a class="headerlink" href="#trim-whitespace" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id62">
<h3>Description<a class="headerlink" href="#id62" title="Permalink to this headline">¶</a></h3>
<p>Removes any whitespace before and after text. Using it on <em>&#8221; there&#8217;s a space before and one after &#8220;</em> will return <em>&#8220;there&#8217;s a space before and one after&#8221;</em></p>
</div>
</div>
<div class="section" id="update-from-tag">
<span id="id63"></span><h2>Update From Tag<a class="headerlink" href="#update-from-tag" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id64">
<h3>Arguments<a class="headerlink" href="#id64" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Field list (;-separated). Start the list with the tilde (~) character to update all the fields except the ones in the list.</li>
<li>Tag type</li>
</ol>
</div>
<div class="section" id="id65">
<h3>Description<a class="headerlink" href="#id65" title="Permalink to this headline">¶</a></h3>
<p>Updates the fields specified with the values found in Tag type.</p>
<p>If your FLAC file has an ID3 tag, puddletag will read/write only the VorbisComment tag. However sometimes you want to update the FLAC tag with the ID3 tag&#8217;s contents. Specify the <strong>Field List</strong>, select the <strong>Tag Type</strong> (ID3 or APEv2).</p>
<p>After invocation, the current file&#8217;s tag will then be updated using the ID3/APEv2 tag&#8217;s fields.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The tag will be not be changed in any manner.</p>
</div>
</div>
</div>
</div>


    </div>
      
  </div>
</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right">
      <a href="#">Back to top</a>
      
    </p>
    <p>
      This page and associated images are licensed under <a rel="license" href="http://www.apache.org/licenses/LICENSE-2.0">Apache Version 2.0</a>
	Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.4.8.<br/>
    </p>
  </div>
</footer>
  </body>
</html>