ts-simple-ast
Version:
TypeScript compiler wrapper for AST navigation and code generation.
294 lines (218 loc) • 19 kB
HTML
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<title>ts-simple-ast - Source Files</title>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.6/css/bootstrap.min.css" integrity="sha384-rwoIResjU2yc3z8GV/NPeZWAv56rSmLldC3R/AZzGRnGxQQKnKkoFVhFQhNUwEyJ" crossorigin="anonymous">
<link rel="stylesheet" href="/assets/css/style.css?v=502728dc7b09041e36b06c50f79a13adbfb6f1b2">
<!--
<link rel="stylesheet" href="/assets/css/style.css?v=502728dc7b09041e36b06c50f79a13adbfb6f1b2">
<link rel="stylesheet" href="/assets/css/custom-style.css?v=502728dc7b09041e36b06c50f79a13adbfb6f1b2">
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<script src="/assets/js/main.js"></script>-->
</head>
<body>
<div class="main">
<header class="container">
<div class="row">
<h1 onclick="document.location.href = '/'" class="headerLink">ts-simple-ast</h1>
<!--<p class="subText">Simple way to navigate and manipulate the TypeScript AST.</p>-->
</div>
</header>
<div class="container">
<div class="row">
<div class="col-md-3">
<button class="navbar-toggler navbar-toggler-right" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<nav class="sidebar-nav" id="navbarSupportedContent">
<ul class="navbar-nav navbar-default">
<li class="nav-item">
<a class="nav-link" href="/">Overview</a>
</li>
<li class="nav-item">
<a class="nav-link" href="/setup">Setup</a>
</li>
<li class="nav-item">
<a class="nav-link" href="/navigation">Navigation</a>
</li>
<li class="nav-item">
<a class="nav-link" href="/manipulation">Manipulation</a>
</li>
<li class="nav-item">
<a class="nav-link" href="/emitting">Emitting</a>
</li>
<li class="">
<a class="nav-link" href="/details/index">Details</a>
<ul>
<li class="active"><a href="/details/source-files">Source Files</a></li>
<li class=""><a href="/details/classes">Classes</a></li>
<li class=""><a href="/details/decorators">Decorators</a></li>
<li class=""><a href="/details/enums">Enums</a></li>
<li class=""><a href="/details/functions">Functions</a></li>
<li class=""><a href="/details/imports">Imports</a></li>
<li class=""><a href="/details/interfaces">Interfaces</a></li>
<li class=""><a href="/details/namespaces">Namespaces</a></li>
<li class=""><a href="/details/parameters">Parameters</a></li>
<li class=""><a href="/details/type-aliases">Type Aliases</a></li>
<li class=""><a href="/details/variables">Variables</a></li>
<li>--</li>
<li class=""><a href="/details/types">Types</a></li>
<li class=""><a href="/details/signatures">Signatures</a></li>
<li>--</li>
<li class=""><a href="/details/expressions">Expressions</a></li>
<li class=""><a href="/details/object-literal-expressions">Object Literal Expressions</a></li>
<li class=""><a href="/details/identifiers">Identifiers</a></li>
<li class=""><a href="/details/ambient">Ambient</a></li>
<li class=""><a href="/details/async">Async</a></li>
<li class=""><a href="/details/exports">Exports</a></li>
<li class=""><a href="/details/generators">Generators</a></li>
<li class=""><a href="/details/initializers">Initializers</a></li>
<li class=""><a href="/details/documentation">JS Docs</a></li>
<li class=""><a href="/details/literals">Literals</a></li>
<li class=""><a href="/details/modifiers">Modifiers</a></li>
</ul>
</li>
<li class="nav-item">
<a class="nav-link" href="/utilities">Utilities</a>
</li>
<li class="nav-item">
<a class="nav-link" href="http://github.com/dsherret/ts-simple-ast">View on GitHub</a>
</li>
</ul>
</nav>
</div>
<section class="container-fluid col-md-9">
<h2 id="source-files">Source Files</h2>
<p>Source files are the root nodes of the AST.</p>
<h3 id="file-path-and-name">File path and name</h3>
<p>Use:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="c1">// returns the file path (ex. /home/david/file.ts)</span>
<span class="nx">sourceFile</span><span class="p">.</span><span class="nx">getFilePath</span><span class="p">();</span>
<span class="c1">// returns only the file name (ex. file.ts)</span>
<span class="nx">sourceFile</span><span class="p">.</span><span class="nx">getBaseName</span><span class="p">();</span>
</code></pre>
</div>
<h3 id="check-if-declaration-file">Check if declaration file</h3>
<p>Use:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="nx">sourceFile</span><span class="p">.</span><span class="nx">isDeclarationFile</span><span class="p">();</span> <span class="c1">// returns: boolean</span>
</code></pre>
</div>
<h3 id="save">Save</h3>
<p>Save a source file to the file system using one of the following commands:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="k">await</span> <span class="nx">sourceFile</span><span class="p">.</span><span class="nx">save</span><span class="p">();</span>
<span class="nx">sourceFile</span><span class="p">.</span><span class="nx">saveSync</span><span class="p">();</span>
</code></pre>
</div>
<h3 id="unsaved-files">Unsaved files</h3>
<p>There is a <code class="highlighter-rouge">sourceFile.isSaved()</code> method that will tell you if the file is saved or not, but it might be easier
to call one of the following methods on the main AST object in order to save unsaved source files:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="nx">ast</span><span class="p">.</span><span class="nx">saveUnsavedSourceFiles</span><span class="p">();</span> <span class="c1">// returns: Promise</span>
<span class="nx">ast</span><span class="p">.</span><span class="nx">saveUnsavedSourceFilesSync</span><span class="p">();</span> <span class="c1">// could potentially be very slow if there are a lot of files to save</span>
</code></pre>
</div>
<h3 id="delete">Delete</h3>
<p>Delete a source file from the file system using one of the following commands:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="k">await</span> <span class="nx">sourceFile</span><span class="p">.</span><span class="k">delete</span><span class="p">();</span> <span class="c1">// or deleteSync()</span>
</code></pre>
</div>
<h3 id="copy">Copy</h3>
<p>Copy a source file to a new file by specifying a new relative or absolute path:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="kd">const</span> <span class="nx">newSourceFile</span> <span class="o">=</span> <span class="nx">sourceFile</span><span class="p">.</span><span class="nx">copy</span><span class="p">(</span><span class="s2">"newFileName.ts"</span><span class="p">);</span>
<span class="c1">// this won't throw if a file exists at the specified path</span>
<span class="kd">const</span> <span class="nx">otherSourceFile</span> <span class="o">=</span> <span class="nx">sourceFile</span><span class="p">.</span><span class="nx">copy</span><span class="p">(</span><span class="s2">"other.ts"</span><span class="p">,</span> <span class="p">{</span> <span class="na">overwrite</span><span class="p">:</span> <span class="kc">true</span> <span class="p">});</span>
</code></pre>
</div>
<p>Note that the file, in both these cases, won’t be written to the file system unless you save it.</p>
<h3 id="move">Move</h3>
<p>TODO: Not yet supported.</p>
<h3 id="refresh-from-file-system">Refresh from file system</h3>
<p>Refresh the source file from the file system:</p>
<div class="language-ts highlighter-rouge"><pre class="highlight"><code><span class="k">import</span> <span class="p">{</span><span class="nx">FileSystemRefreshResult</span><span class="p">}</span> <span class="k">from</span> <span class="s2">"ts-simple-ast"</span><span class="p">;</span>
<span class="c1">// returns: FileSystemRefreshResult (NoChange, Updated, Deleted)</span>
<span class="kd">const</span> <span class="nx">result</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">sourceFile</span><span class="p">.</span><span class="nx">refreshFromFileSystem</span><span class="p">();</span> <span class="c1">// or refreshFromFileSystemSync()</span>
</code></pre>
</div>
<p>This is useful when you are using a file system watcher and want to refresh a source file from the file system based on changes.</p>
<p>If the file was <em>updated</em>: All the child nodes of the source file will be forgotten and you will have to renavigate the file.
If the file was <em>deleted</em>: The source file will be removed and all its nodes forgotten.</p>
<h3 id="remove">Remove</h3>
<p>Remove a source file from the AST by calling:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="nx">ast</span><span class="p">.</span><span class="nx">removeSourceFile</span><span class="p">(</span><span class="nx">sourceFile</span><span class="p">);</span> <span class="c1">// returns: boolean (if was removed)</span>
</code></pre>
</div>
<p>Note: This does not delete the file from the file system. To do delete it, call <code class="highlighter-rouge">.delete()</code>.</p>
<h3 id="referenced-files">Referenced files</h3>
<p>This returns any files that are referenced via <code class="highlighter-rouge">/// <reference path="..." /></code> statements:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="kd">const</span> <span class="nx">referencedFiles</span> <span class="o">=</span> <span class="nx">sourceFile</span><span class="p">.</span><span class="nx">getReferencedFiles</span><span class="p">();</span>
</code></pre>
</div>
<h3 id="type-reference-directives">Type reference directives</h3>
<p>This returns any files that are referenced via <code class="highlighter-rouge">/// <reference types="..." /></code> statements:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="kd">const</span> <span class="nx">typeReferenceDirectives</span> <span class="o">=</span> <span class="nx">sourceFile</span><span class="p">.</span><span class="nx">getTypeReferenceDirectives</span><span class="p">();</span>
</code></pre>
</div>
<h3 id="get-default-export-symbol">Get default export symbol</h3>
<p>If it exists, the default export symbol can be retrieved:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="kd">const</span> <span class="nx">defaultExportSymbol</span> <span class="o">=</span> <span class="nx">sourceFile</span><span class="p">.</span><span class="nx">getDefaultExportSymbol</span><span class="p">();</span> <span class="c1">// returns: Symbol | undefined</span>
</code></pre>
</div>
<h3 id="remove-default-export">Remove default export</h3>
<p>Use:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="nx">sourceFile</span><span class="p">.</span><span class="nx">removeDefaultExport</span><span class="p">();</span>
</code></pre>
</div>
<p>Note: This is safe to call even when there is no default export.</p>
<h3 id="import-declarations">Import Declarations</h3>
<p>See <a href="imports">Import Declarations</a>.</p>
<h3 id="export-declarations">Export Declarations</h3>
<p>See <a href="exports">Export Declarations</a>.</p>
<h3 id="indenting--unindenting">Indenting / Unindenting</h3>
<p>Call the <code class="highlighter-rouge">.indent</code> or <code class="highlighter-rouge">.unindent</code> methods.</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="nx">sourceFile</span><span class="p">.</span><span class="nx">indent</span><span class="p">(</span><span class="mi">5</span><span class="p">);</span> <span class="c1">// indent line containing position 5</span>
<span class="nx">sourceFile</span><span class="p">.</span><span class="nx">indent</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">]);</span> <span class="c1">// indent line or lines within position range [5-10]</span>
<span class="nx">sourceFile</span><span class="p">.</span><span class="nx">indent</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">3</span><span class="p">);</span> <span class="c1">// indent line containing position 10, 3 times</span>
<span class="nx">sourceFile</span><span class="p">.</span><span class="nx">unindent</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span> <span class="c1">// unindent line containing position 10</span>
<span class="nx">sourceFile</span><span class="p">.</span><span class="nx">indent</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">);</span> <span class="c1">// unindent line containing position 10 (specify negative times)</span>
<span class="nx">sourceFile</span><span class="p">.</span><span class="nx">unindent</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">);</span> <span class="c1">// indent line containing position 10 (specify negative times)</span>
</code></pre>
</div>
<p>This will indent and unindent based on your <a href="../manipulation/settings">manipulation settings</a>.</p>
<h3 id="formatting-text">Formatting Text</h3>
<p>Sometimes you might encounter code that looks terrible. For example:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="c1">// BadlyFormattedFile.ts</span>
<span class="kd">var</span> <span class="nx">myVariable</span> <span class="err">:</span> <span class="kr">string</span> <span class="o">|</span> <span class="kr">number</span><span class="p">;</span>
<span class="kd">function</span> <span class="nx">myFunction</span><span class="p">(</span><span class="nx">param</span> <span class="err">:</span> <span class="nx">MyClass</span><span class="p">){</span>
<span class="k">return</span> <span class="s2">""</span><span class="p">;</span>
<span class="p">}</span>
</code></pre>
</div>
<p>Automatically format the text of this file by calling format text on it:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="nx">sourceFile</span><span class="p">.</span><span class="nx">formatText</span><span class="p">();</span>
<span class="c1">// or provide optional formatting settings</span>
<span class="nx">sourceFile</span><span class="p">.</span><span class="nx">formatText</span><span class="p">({</span>
<span class="na">placeOpenBraceOnNewLineForFunctions</span><span class="p">:</span> <span class="kc">true</span>
<span class="p">});</span>
</code></pre>
</div>
<p>This will run the source file’s text through the TypeScript compiler’s formatting API, which will change the source file to contain the following text:</p>
<div class="language-typescript highlighter-rouge"><pre class="highlight"><code><span class="c1">// BadlyFormattedFile.ts (not anymore!)</span>
<span class="kd">var</span> <span class="nx">myVariable</span><span class="err">:</span> <span class="kr">string</span> <span class="o">|</span> <span class="kr">number</span><span class="p">;</span>
<span class="kd">function</span> <span class="nx">myFunction</span><span class="p">(</span><span class="nx">param</span><span class="err">:</span> <span class="nx">MyClass</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="s2">""</span><span class="p">;</span>
<span class="p">}</span>
</code></pre>
</div>
</section>
</div>
</div>
<footer>
</footer>
</div>
<script src="https://code.jquery.com/jquery-3.1.1.slim.min.js" integrity="sha384-A7FZj7v+d/sdmMqp/nOQwliLvUsJfDHW+k9Omg/a/EheAdgtzNs3hpfag6Ed950n" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/tether/1.4.0/js/tether.min.js" integrity="sha384-DztdAPBWPRXSA/3eYEEUWrWCy7G5KFbe8fFjk5JAIxUYHKkDx6Qin1DkWx51bBrb" crossorigin="anonymous"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.6/js/bootstrap.min.js" integrity="sha384-vBWWzlZJ8ea9aCX4pEW3rVHjgjt7zpkNpZk+02D9phzyeVkE+jo0ieGizqPLForn" crossorigin="anonymous"></script>
<!--[if !IE]><script>fixScale(document);</script><![endif]-->
</body>
</html>