title	order
Basic Tutorial	1

The basic flow of one code conversion

The above diagram outlines the four processes of a single code conversion, and our next tutorials will follow these four steps in sequence.

Parse the code into an abstract syntax tree (AST)
Find the code we want to change
Change it to what we want it to look like
Generate the code back into string form

Parsing Code with GoGoCode

First we install and introduce GoGoCode

npm install gogocode --save

import $ from 'gogocode';
// or for commonjs
const $ = require('gogocode');

We borrowed jQuery's $ naming to make the code easier to write!

To parse different types of code using GoGoCode.

// source is the string of the code to be parsed

// parse JavaScript/TypScript files
const ast = $(source);

// parsing html files requires the language to be specified in the parseOptions passed in
const ast = $(source, { parseOptions: { language: 'html' } });

// Parse the Vue file
const ast = $(source, { parseOptions: { language: 'vue' } });

Tips: The code snippets in this tutorial you can try right now in GoGoCode PlayGround!

You can switch the code type in the drop-down box as shown, and the corresponding sample code will be provided on the right side.

Selecting code by code selector

After parsing the code from a string into an AST, we move to the second step, finding the exact AST node we want to modify from an entire section of code.

ast.find Code Selector

Unlike other code conversion tools that match syntax tree nodes by AST type, GoGoCode provides a more intuitive way to "find code with code".

Suppose you want to pick the function named log in the following code.

function log(a) {
  console.log(a);
}

function alert(a) {
  alert(a);
}

Simply use the find method as follows.

const ast = $(source);
const test1 = ast.find('function log() {}');

GoGoCode will automatically match the function node named log based on function log() {} and return the child node that meets the matching criteria.

Use `generate` to output nodes as code strings

Just call .generate on the AST node you found, and you'll get the code string for that node.

const ast = $(source);
const test1 = ast.find('function log() {}');

const code = test1.generate()
// code is the following string.
// function log(a) {
// console.log(a);
// }

Playgroud Online Demo

$_$ Wildcard

Suppose you want to pick out the declaration and initialization statements for the variable a in the following code.

const a = 123;

As previously described, we can simply write it like the following.

const aDef = ast.find('const a = 123');

But this only matches to const a = 123, not to const a = 456. In real code matching, we are often not sure of the whole code, so GoGoCode supports fuzzy matching using wildcards:

const aDef = ast.find('const a = $_$0');

Replacing the original 123 with $_$0 will help you match all statements that initialize const a:

// each of the following statements will be matched
const a = 123;
const a = b;
const a = () => 1;
// ......

The node at position $_$0 can be obtained by using the match property of the query result.

const aDef = ast.find('const a = $_$');
const match = aDef.match;

As shown below, match is a dictionary structure, the number after $_$ is the index of match, and the collection of ASTs matched by $_$0 position can be retrieved by match[0].

This collection has only one element, corresponding to 123 in const a = 123, and you can get the original AST node corresponding to it via node, or the fragment of this node in the code directly via value.

Tip: Using the debugger more often to see the intermediate results is a good way to write code conversions

Playgroud Online Demo

Collection operations

Going back to this example.

function log(a) {
  console.log(a);
}

function alert(a) {
  alert(a);
}

If we use wildcards, we can match all function definitions by name, so the result of the .find query could be a collection

// fns is a result set containing all function definitions by name
const fns = ast.find(`function $_$0() {}`);

This result set fns has the same type as ast and has exactly the same member methods; if there are multiple elements in the set, using the methods directly on them will only work on the first AST node.

We provide the each method to iterate through this result collection, and the following example collects the function names that are matched into an array named names.

const fns = ast.find(`function $_$0() {}`);
const names = [];
fns.each((fnNode) => {
  const fnName = fnNode.match[0][0].value;
  names.push(fnName);
});

Files

basic.en.md

Latest commit

History

basic.en.md

File metadata and controls

The basic flow of one code conversion

Parsing Code with GoGoCode

Selecting code by code selector

ast.find Code Selector

Use generate to output nodes as code strings

$_$ Wildcard

Collection operations

Using multiple wildcards

Match multiple nodes of the same kind

ast.has

Replace the code

The almighty replace

Function renaming

Enumeration list property renaming

JSX tag attribute replacement

More complex substitution with functions

replaceBy

Insert code

Inserting code with replace

Add some lines to a function with append, prepend

Inserting code with before and after

Remove code

Deleting code with replace

Remove code with remove

Use `generate` to output nodes as code strings