C2Rust helps you migrate C99-compliant code to Rust. It provides:

• a C to Rust translator
• a Rust code refactoring tool
• tools to cross-check execution of the C code against the new Rust code

The translator (or transpiler), produces unsafe Rust code that closely mirrors the input C code. The primary goal of the translator is to produce code that is functionally identical to the input C code. Generating safe or idomatic Rust is not a goal for the translator. Rather, we think the best approach is to gradually rewrite the translated Rust code using dedicated refactoring tools. To this end, we are building a refactoring tool that rewrites unsafe auto-translated Rust into safer idioms.

Some refactoring will have to be done by hand which may introduce errors. We provide plugins for clang and rustc so you can compile and run two binaries and check that they behave identically (at the level of function calls). For details on cross-checking see the cross-checks directory and the cross checking tutorial.

Here's the big picture:

To learn more, check out our RustConf'18 talk on YouTube and try the C2Rust translator online at www.c2rust.com.

C2Rust requires LLVM 6 or 7 and its corresponding libraries and clang compiler. Python 3.4 or later, CMake 3.4.3 or later, and openssl (1.0) are also required. These prerequisites may be installed with the following commands, depending on your platform:

• Ubuntu 16.04, 18.04 & 18.10:

    apt install build-essential llvm-6.0 clang-6.0 libclang-6.0-dev cmake libssl-dev pkg-config
  

• Arch Linux:

    pacman -S base-devel llvm clang cmake openssl
  

• OS X: XCode command-line tools and recent LLVM (we recommend the Homebrew version) are required.

    xcode-select --install
    brew install llvm python3 cmake openssl
  

Finally, a rust installation with Rustup is required on all platforms. You will also need to install rustfmt:

    rustup component add rustfmt-preview

cargo build --release

This builds the c2rust tool in the target/release/ directory.

On OS X with Homebrew LLVM, you need to point the build system at the LLVM installation as follows:

LLVM_CONFIG_PATH=/usr/local/opt/llvm/bin/llvm-config cargo build

If you have trouble with cargo build, the developer docs provide more details on the build system.

To translate C files specified in compile_commands.json (see below), run the c2rust tool with the transpile subcommand:

c2rust transpile compile_commands.json

(The c2rust refactor tool is also available for refactoring Rust code, see refactoring).

The translator requires the exact compiler commands used to build the C code. To provide this information, you will need a standard compile_commands.json file. Many build systems can automatically generate this file, as it is used by many other tools, but see below for recommendations on how to generate this file for common build processes.

Once you have a compile_commands.json file describing the C build, translate the C code to Rust with the following command:

c2rust transpile path/to/compile_commands.json

To generate a Cargo.toml template for a Rust library, add the -e option:

c2rust transpile --emit-build-files path/to/compile_commands.json

To generate a Cargo.toml template for a Rust binary, do this:

c2rust transpile --main myprog path/to/compile_commands.json

Where --main myprog tells the transpiler to use the main method from myprog.rs as the entry point.

The translated Rust files will not depend directly on each other like normal Rust modules. They will export and import functions through the C API. These modules can be compiled together into a single static Rust library or binary.

There are several known limitations in this translator. The translator will emit a warning and attempt to skip function definitions that cannot be translated.

The compile_commands.json file can be automatically created using either cmake, intercept-build, or bear.

It may be a good idea to remove optimizations(-OX) from the compile commands file, as there are optimization builtins which we do not support translating.

When creating the initial build directory with cmake specify -DCMAKE_EXPORT_COMPILE_COMMANDS=1. This only works on projects configured to be built by cmake. This works on Linux and MacOS.

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 ...

intercept-build (part of the scan-build tool) is recommended for non-cmake projects. intercept-build is bundled with clang under tools/scan-build-py but a standalone version can be easily installed via PIP with:

pip install scan-build

Usage:

intercept-build <build command>

You can also use intercept-build to generate a compilation database for compiling a single C file, for example:

intercept-build sh -c "cc program.c"

If you have bear installed, it can be used similarly to intercept-build:

bear <build command>

The transpiler module is invoked using the transpile sub-command of c2rust:

c2rust transpile [args] compile_commands.json [-- extra-clang-args]

The following arguments control the basic transpiler behavior:

• --emit-modules - Emit each translated Rust file as a module (the default is to make each file its own crate).
• --fail-on-error - Fail instead of warning if a source file cannot be fully translated.
• --reduce-type-annotations - Do not emit explicit type annotations when unnecessary.
• --translate-asm - Translate C inline assembly into corresponding Rust inline assembly. The translated assembly is unlikely to work as-is due to differences between GCC and LLVM (used in Rust) inline assembly styles, but it can provide a starting point for manual translation.
• -f <regex>, --filter <regex> - Only translate files based on the regular expression used.

The transpiler can create skeleton cargo build files for the translated Rust sources, controlled by the following options:

• -e, --emit-build-files - Emit cargo build files to build the translated Rust code as a library. Build files are emitted in the directory specified by --output-dir, or if not specified, the directory containing compile_commands.json. This will not overwrite existing files, so remove these build files before re-creating build files. (implies --emit-modules)
• -m <main_module>, --main <main_module> - Emit cargo build files to build the translated Rust code as a binary. The main function must be found in the specified module (C source file) <main_module>. <main_module> should be the bare module name, not including the .rs extension. Build files are emitted in the directory specified by --output-dir, or if not specified, the directory containing compile_commands.json. This will not overwrite existing files, so remove this build file directory before re-creating build files. (implies --emit-build-files)

The transpiler can instrument the transpiled Rust code for cross-checking. The following options control this instrumentation:

• -x, --cross-checks - Add macros and build files for cross-checking.
• --use-fakechecks - Link against the fakechecks library for cross-checking instead of using the default online checks.
• -X <config>, --cross-check-config <config> - Use the given config file as the cross-checking config.

The c2rust-transpile library uses the c2rust-ast-exporter library to translate C code to Rust. The ast-exporter library links against the native clang compiler front end to parse C code and exports the AST for use in the transpiler, which is then implemented purely in Rust.

This document tracks things that we know the translator can't handle, as well as things it probably won't ever handle.

• variadic function definitions (blocking Rust issue)
• preserving comments (work in progress)
• long double and _Complex types (partially blocked by Rust language)
• Non x86/64 SIMD function/types and x86/64 SIMD function/types which have no rust equivalent

• GNU packed structs (Rust has #[repr(packed)] compatible with #[repr(C)])
• inline functions (Rust has #[inline])
• restrict pointers (Rust has references)
• inline assembly
• macros

• longjmp/setjmp Although there are LLVM intrinsics for these, it is unclear how these interact with Rust (esp. idiomatic Rust).
• jumps into and out of statement expressions We support GNU C statement expressions, but we can not handle jumping into or out of these. Both entry and exit into the expression have to be through the usual fall-through evaluation of the expression.

C2Rust-Bitfields enables you to write structs containing bitfields. It has three primary goals:

• Byte compatibility with equivalent C bitfield structs
• The ability to take references/pointers to non bitfield fields
• Provide methods to read from and write to bitfields

We currently provides a single custom derive, BitfieldStruct, as well as a dependent field attribute bitfield.

• Rust 1.30+
• Rust Stable, Beta, or Nightly
• Little Endian Architecture

Suppose you want to write a super compact date struct which only takes up three bytes. In C this would look like this:

struct date {
    unsigned char day: 5;
    unsigned char month: 4;
    unsigned short year: 15;
} __attribute__((packed));

Clang helpfully provides us with this information:

*** Dumping AST Record Layout
         0 | struct date
     0:0-4 |   unsigned char day
     0:5-8 |   unsigned char month
    1:1-15 |   unsigned short year
           | [sizeof=3, align=1]

And this is enough to build our rust struct:

extern crate libc;

#[repr(C, align(1))]
#[derive(BitfieldStruct)]
struct Date {
    #[bitfield(name = "day", ty = "libc::c_uchar", bits = "0..=4")]
    #[bitfield(name = "month", ty = "libc::c_uchar", bits = "5..=8")]
    #[bitfield(name = "year", ty = "libc::c_ushort", bits = "9..=23")]
    day_month_year: [u8; 3]
}

fn main() {
    let mut date = Date {
        day_month_year: [0; 3]
    };

    date.set_day(18);
    date.set_month(7);
    date.set_year(2000);

    assert_eq!(date.day(), 18);
    assert_eq!(date.month(), 7);
    assert_eq!(date.year(), 2000);
}

Furthermore, C bitfield rules for overflow and signed integers are taken into account.

This crate can generate no_std compatible code when the no_std feature flag is provided.

Since rust doesn't support a build.rs exclusively for tests, you must manually compile the c test code and link it in.

$ clang tests/bitfields.c -c -fPIC -o tests/bitfields.o
$ ar -rc tests/libtest.a tests/bitfields.o
$ RUSTFLAGS="-L `pwd`/tests" cargo test

This crate is inspired by the rust-bitfield, packed_struct, and bindgen crates.

This is a refactoring tool for Rust programs, aimed at removing unsafety from automatically-generated Rust code.

c2rust refactor command line usage is as follows:

c2rust refactor [flags] <command> [command args] -- <input file> [rustc flags]

Flags for c2rust refactor are described by c2rust refactor --help.

See the command documentation for a list of commands, including complete usage and descriptions. Multiple commands can be separated by an argument consisting of a single semicolon, as in c2rust refactor cmd1 arg1 \; cmd2 arg2. (Note the semicolon needs to be escaped to prevent it from being interpreted by the shell.)

c2rust refactor requires rustc command line arguments for the program to be refactored, so that it can use rustc to load and typecheck the source code. For projects built with cargo, pass the --cargo flag to c2rust refactor and it will obtain the right arguments from cargo automatically. Otherwise, you must provide the rustc arguments on the c2rust refactor command line, after a -- separator.

Some commands require the user to "mark" some AST nodes for it to operate on. For example, the rename_struct command requires that the user mark the declaration of the struct that should be renamed.

Each mark associates a "label" with a specific AST node (identified by its NodeId). Labels are used to distinguish different types of marks, and a single node can have any number of marks with distinct labels. For example, when running the func_to_method command, which turns functions into methods in an inherent impl, the user must mark the functions to move with the target label and must mark the destination impl with the dest label. Nodes marked with other labels will be ignored. The set of labels recognized by a command is described in the command's documentation; by default, most commands that use marks operate on target.

The most flexible way of marking nodes is by using the select command. See the command documentation and src/select/mod.rs for details. Note that marks are not preserved across c2rust refactor invocations, so you usually want to run select followed by the command of interest using the ; separator mentioned above.

• abstract
• autoretype
• bitcast_retype
• bytestr_to_str
• canonicalize_externs
• canonicalize_structs
• char_literals
• clear_marks
• commit
• convert_cast_as_ptr
• convert_format_args
• convert_printfs
• copy_marks
• create_item
• delete_items
• delete_marks
• fix_unused_unsafe
• fold_let_assign
• func_to_method
• generalize_items
• ionize
• let_x_uninitialized
• link_funcs
• link_incomplete_types
• mark_arg_uses
• mark_callers
• mark_field_uses
• mark_pub_in_mod
• mark_related_types
• mark_uses
• ownership_annotate
• ownership_mark_pointers
• ownership_split_variants
• pick_node
• print_marks
• print_spans
• reconstruct_for_range
• reconstruct_while
• remove_null_terminator
• remove_redundant_casts
• remove_redundant_let_types
• remove_unused_labels
• rename_items_regex
• rename_marks
• rename_struct
• rename_unnamed
• reoganize_definitions
• replace_items
• retype_argument
• retype_return
• retype_static
• rewrite_expr
• rewrite_stmts
• rewrite_ty
• select
• select_phase2
• set_mutability
• set_visibility
• sink_lets
• sink_unsafe
• static_collect_to_struct
• static_to_local
• static_to_local_ref
• struct_assign_to_update
• struct_merge_updates
• test_analysis_ownership
• test_analysis_type_eq
• test_debug_callees
• test_f_plus_one
• test_insert_remove_args
• test_one_plus_one
• test_reflect
• test_replace_stmts
• test_typeck_loop
• type_fix_rules
• uninit_to_default
• wrap_api
• wrap_extern
• wrapping_arith_to_normal

Usage: abstract SIG PAT [BODY]

Replace all instances of pat with calls to a new function whose name and signature is given by sig. Example:

Input:

 1 + 2

After running abstract 'add(x: u32, y: u32) -> u32' 'x + y':

 add(1, 2)

 // Elsewhere:
 fn add(x: u32, y: u32) -> u32 { x + y }

All type and value parameter names in sig act as bindings when matching pat. The captured exprs and types are passed as parameters when building the new call expression. The body of the function is body, if provided, otherwise pat itself.

Non-ident patterns in sig are not supported. It is also an error for any type parameter's name to collide with any value parameter.

If matching with pat fails to capture expressions for any of the value parameters of sig, it is an error. If it fails to capture for a type parameter, the parameter is filled in with _ (infer).

Usage: autoretype 'A: T'...

Marks: A... (specified in command)

Change the type of nodes with mark A to the new type T, propagating changes and inserting casts when possible to satisfy type checking. Multiple simultaneous retypings can be specified in this command as separate arguments. Each argument should be of the form: label: type where label is a mark label and type can be parsed as a valid rust type.

Usage: bitcast_retype PAT REPL

Marks: may read marks depending on PAT

For every type in the crate matching PAT, change the type to REPL. PAT and REPL are types, and can use placeholders in the manner of rewrite_ty. For each definitions whose type has changed, it also inserts mem::transmute calls at each use of the definition to fix discrepancies between the old and new types. (This implies that the original type and its replacement must be transmutable to each other.)

Usage: bytestr_to_str

Marks: target

Convert bytestring literal expressions marked target to string literal expressions.

Note the mark must be placed on the expression, as it is currently difficult to mark a literal node.

Usage: canonicalize_externs MOD_PATH

Marks: target

Replace foreign items ("externs") with references to externs in a different crate or module.

For each foreign fn or static marked target, if a foreign item with the same symbol exists in the module at MOD_PATH (which can be part of an external crate), it deletes the marked foreign item and replaces all its uses with uses of the matching foreign item in MOD_PATH. If a replacement item has a different type than the original, it also inserts the necessary casts at each use of the item.

Usage: canonicalize_structs

Marks: target

For each type definition marked target, delete all other type definitions with the same name, and replace their uses with uses of the target type.

This only works when all the identically-named types have the same definition, such as when all are generated from #includes of the same C header.

Example:

 mod a {
     pub struct Foo { ... }  // Foo: target
 }

 mod b {
     struct Foo { ... }  // same as ::a::Foo

     unsafe fn use_foo(x: &Foo) { ... }
 }

After running canonicalize_structs:

 mod a {
     pub struct Foo { ... }
 }

 mod b {
     // 1. `struct Foo` has been deleted
     // 2. `use_foo` now references `::a::Foo` directly
     unsafe fn use_foo(x: &::a::Foo) { ... }
 }

Note that this transform does not check or adjust item visibility. If the target type is not visible throughout the crate, this may introduce compile errors.

Obsolete - the translator now does this automatically.

Usage: char_literals

Replace integer literals cast to libc::c_char with actual char literals. For example, replaces 65 as libc::c_char with 'A' as libc::c_char.

Usage: clear_marks

Marks: clears all marks

Remove all marks from all nodes.

Usage: commit

Write the current crate to disk (by rewriting the original source files), then read it back in, clearing all mark. This can be useful as a "checkpoint" between two sets of transformations, if applying both sets of changes at once proves to be too much for the rewriter.

This is only useful when the rewrite mode is inplace. Otherwise the "write" part of the operation won't actually change the original source files, and the "read" part will revert the crate to its original form.

Usage: convert_format_args

Marks: target

For each function call, if one of its argument expressions is marked target, then parse that argument as a printf format string, with the subsequent arguments as the format args. Replace both the format string and the args with an invocation of the Rust format_args! macro.

This transformation applies casts to the remaining arguments to account for differences in argument conversion behavior between C-style and Rust-style string formatting. However, it does not attempt to convert the format_args! output into something compatible with the original C function. This results in a type error, so this pass should usually be followed up by an additional rewrite to change the function being called.

Example:

 printf("hello %d\n", 123);

If the string "hello %d\n" is marked target, then running convert_format_string will replace this call with

 printf(format_args!("hello {:}\n", 123 as i32));

At this point, it would be wise to replace the printf expression with a function that accepts the std::fmt::Arguments produced by format_args!.

Usage: copy_marks OLD_MARK NEW_MARK

Marks: reads OLD_MARK; sets NEW_MARK

For every node bearing OLD_MARK, also apply NEW_MARK.

Usage: create_item ITEMS <inside/after> [MARK]

Marks: MARK/target

Parse ITEMS as item definitions, and insert the parsed items either inside (as the first child) or after (as a sibling) of the AST node bearing MARK (default: target). Supports adding items to both mods and blocks.

Note that other itemlikes, such as impl and trait items, are not handled by this command.

Usage: delete_items

Marks: target

Delete all items marked target from the AST. This handles items in both mods and blocks, but doesn't handle other itemlikes.

Usage: delete_marks MARK

Marks: clears MARK

Remove MARK from every node where it appears.

Usage: fix_unused_unsafe

Find unused unsafe blocks and turn them into ordinary blocks.

Usage: fold_let_assign

Fold together lets with no initializer or a trivial one, and subsequent assignments. For example, replace let x; x = 10; with let x = 10;.

Usage: func_to_method

Marks: target, dest

Turn functions marked target into static methods (no self) in the impl block marked dest. Turn functions that have an argument marked target into methods, replacing the named argument with self. Rewrite all uses of marked functions to call the new method versions.

Marked arguments of type T, &T, and &mut T (where T is the Self type of the dest impl) will be converted to self, &self, and &mut self respectively.

Usage: generalize_items VAR [TY]

Marks: target

Replace marked types with generic type parameters.

Specifically: add a new type parameter called VAR to each item marked target, replacing type annotations inside that item that are marked target with uses of the type parameter. Also update all uses of target items, passing TY as the new type argument when used inside a non-target item, and passing the type variable VAR when used inside a target item.

If TY is not provided, it defaults to a copy of the first type annotation that was replaced with VAR.

Example:

 struct Foo {    // Foo: target
     x: i32,     // i32: target
     y: i32,
 }

 fn f(foo: Foo) { ... }  // f: target

 fn main() {
     f(...);
 }

After running generalize_items T:

 // 1. Foo gains a new type parameter `T`
 struct Foo<T> {
     // 2. Marked type annotations become `T`
     x: T,
     y: i32,
 }

 // 3. `f` gains a new type parameter `T`, and passes
 // it through to uses of `Foo`
 fn f<T>(foo: Foo<T>) { ... }
 struct Bar<T> {
     foo: Foo<T>,
 }

 fn main() {
     // 4. Uses outside target items use `i32`, the
     // first type that was replaced with `T`.
     f::<i32>(...);
 }

Usage: ionize

Marks: target

Convert each union marked target to a type-safe Rust enum. The generated enums will have as_variant and as_variant_mut methods for each union field, which panic if the enum is not the named variant. Also updates assignments to union variables to assign one of the new enum variants, and updates uses of union fields to call the new methods instead.

Obsolete - the translator now does this automatically.

Usage: let_x_uninitialized

For each local variable that is uninitialized (let x;), add mem::uninitialized() as an initializer expression.

Usage: link_funcs

Link up function declarations and definitions with matching symbols across modules. For every foreign fn whose symbol matches a fn definition elsewhere in the program, it replaces all uses of the foreign fn with a direct call of the fn definition, and deletes the foreign fn.

Example:

 mod a {
     #[no_mangle]
     unsafe extern "C" fn foo() { ... }
 }

 mod b {
     extern "C" {
         // This resolves to `a::foo` during linking.
         fn foo();
     }

     unsafe fn use_foo() {
         foo();
     }
 }

After running link_funcs:

 mod a {
     #[no_mangle]
     unsafe extern "C" fn foo() { ... }
 }

 mod b {
     // 1. Foreign fn `foo` has been deleted
     unsafe fn use_foo() {
         // 2. `use_foo` now calls `foo` directly
         ::a::foo();
     }
 }

Usage: link_incomplete_types

Link up type declarations and definitions with matching names across modules. For every foreign type whose name matches a type definition elsewhere in the program, it replaces all uses of the foreign type with the type definition, and deletes the foreign type.

Example:

 mod a {
     struct Foo { ... }
 }

 mod b {
     extern "C" {
         type Foo;
     }

     unsafe fn use_foo(x: &Foo) { ... }
 }

After running link_incomplete_types:

 mod a {
     struct Foo { ... }
 }

 mod b {
     // 1. Foreign fn `Foo` has been deleted
     // 2. `use_foo` now references `Foo` directly
     unsafe fn use_foo(x: &::a::Foo) { ... }
 }

Usage: mark_arg_uses ARG_IDX MARK

Marks: reads MARK; sets/clears MARK

For every fn definition bearing MARK, apply MARK to expressions passed in as argument ARG_IDX in calls to that function. Removes MARK from the original function.

Usage: mark_callers MARK

Marks: reads MARK; sets/clears MARK

For every fn definition bearing MARK, apply MARK to call expressions that call that function. Removes MARK from the original function.

Obsolete - use select with match_expr!(typed!(::TheStruct).field) instead

Usage: mark_field_uses FIELD MARK

Marks: reads MARK; sets/clears MARK

For every struct definition bearing MARK, apply MARK to expressions that use FIELD of that struct. Removes MARK from the original struct.

Obsolete - use select instead.

Usage: mark_pub_in_mod MARK

Marks: reads MARK; sets MARK

In each mod bearing MARK, apply MARK to every public item in the module.

Usage: mark_related_types [MARK]

Marks: MARK/target

For each type annotation bearing MARK (default: target), apply MARK to all other type annotations that must be the same type according to (a simplified version of) Rust's typing rules.

For example, in this code:

 fn f(x: i32, y: i32) -> i32 {
     x
 }

The i32 annotations on x and the return type of f are related, because changing these annotations to two unequal types would produce a type error. But the i32 annotation on y is unrelated, and can be changed independently of the other two.

Usage: mark_uses MARK

Marks: reads MARK; sets/clears MARK

For every top-level definition bearing MARK, apply MARK to uses of that definition. Removes MARK from the original definitions.

Usage: ownership_annotate [MARK]

Marks: MARK/target

Run ownership analysis on functions bearing MARK (default: target), and add attributes to each function describing its inferred ownership properties. See analysis/ownership/README.md for details on ownership inference.

Usage: ownership_mark_pointers [MARK]

Marks: reads MARK/target; sets ref, mut, and box

Run ownership analysis on functions bearing MARK (default: target), then for pointer type appearing in their argument and return types, apply one of the marks ref, mut, or box, reflecting the results of the ownership analysis. See analysis/ownership/README.md for details on ownership inference.

Usage: ownership_split_variants [MARK]

Marks: MARK/target

Run ownership analysis on functions bearing MARK (default: target), and split each ownership-polymorphic functions into multiple monomorphic variants. See analysis/ownership/README.md for details on ownership inference.

Test command - not intended for general use.

Usage: pick_node KIND FILE LINE COL

Find a node of kind KIND at location FILE:LINE:COL. If successful, logs the node's ID and span at level info.

Test command - not intended for general use.

Usage: print_marks

Marks: reads all

Logs the ID and label of every mark, at level info.

Test command - not intended for general use.

Usage: print_spans

Print IDs, spans, and pretty-printed source for all exprs, pats, tys, stmts, and items.

Usage: reconstruct_for_range

Replaces i = start; while i < end { ...; i += step; } with for i in (start .. end).step_by(step) { ...; }.

Obsolete - the translator now does this automatically.

Usage: reconstruct_while

Replaces all instances of loop { if !cond { break; } ... } with while loops.

Usage: remove_null_terminator

Marks: target

Remove a trailing \0 character from marked string and bytestring literal expressions.

Note the mark must be placed on the expression, as it is currently difficult to mark a literal node.

Usage: remove_unused_labels

Removes loop labels that are not used in a named break or continue.

Usage: rename_items_regex PAT REPL [FILTER]

Marks: reads FILTER

Replace PAT (a regular expression) with REPL in all item names. If FILTER is provided, only items bearing the FILTER mark will be renamed.

Usage: rename_marks OLD_MARK NEW_MARK

Marks: reads/clears OLD_MARK; sets NEW_MARK

For every node bearing OLD_MARK, remove OLD_MARK and apply NEW_MARK.

Obsolete - use rename_items_regex instead.

Usage: rename_struct NAME

Marks: target

Rename the struct marked target to NAME. Only supports renaming a single struct at a time.

Usage: rename_unnamed

Renames all Idents that have unnamed throughout the Crate, so the Crate can have a completely unique naming scheme for Anonymous Types. This command should be ran after transpiling using c2rust-transpile, and is also mainly to be used when doing the reorganize_definition pass; although this pass can run on any c2rust-transpiled project.

Example:

pub mod foo {
    pub struct unnamed {
        a: i32
    }
}

pub mod bar {
    pub struct unnamed {
        b: usize
    }
}

Becomes:

pub mod foo {
    pub struct unnamed {
        a: i32
    }
}

pub mod bar {
    pub struct unnamed_1 {
        b: usize
    }
}

Usage: replace_items

Marks: target, repl

Replace all uses of items marked target with reference to the item marked repl, then remove all target items.

Usage: retype_argument NEW_TY WRAP UNWRAP

Marks: target

For each argument marked target, change the type of the argument to NEW_TY, and use WRAP and UNWRAP to convert values to and from the original type of the argument at call sites and within the function body.

WRAP should contain an expression placeholder __old, and should convert __old from the argument's original type to NEW_TY. UNWRAP should contain an expression placeholder __new, and should perform the opposite conversion.

Usage: retype_return NEW_TY WRAP UNWRAP

Marks: target

For each function marked target, change the return type of the function to NEW_TY, and use WRAP and UNWRAP to convert values to and from the original type of the argument at call sites and within the function body.

WRAP should contain an expression placeholder __old, and should convert __old from the function's original return type to NEW_TY. UNWRAP should contain an expression placeholder __new, and should perform the opposite conversion.

Usage: retype_static NEW_TY REV_CONV_ASSIGN CONV_RVAL CONV_LVAL [CONV_LVAL_MUT]

Marks: target

For each static marked target, change the type of the static to NEW_TY, using the remaining arguments (which are all all expression templates) to convert between the old and new types at the definition and use sites.

The expression arguments are used as follows:

• REV_CONV_ASSIGN: In direct assignments to the static and in its initializer expression, the original assigned value is wrapped (as __old) in REV_CONV_ASSIGN to produce a value of type NEW_TY.
• CONV_RVAL: In rvalue contexts, the static is wrapped (as __new) in CONV_RVAL to produce a value of the static's old type.
• CONV_LVAL and CONV_LVAL_MUT are similar to CONV_RVAL, but for immutable and mutable lvalue contexts respectively. Especially for CONV_LVAL_MUT, the result of wrapping should be an lvalue expression (such as a dereference or field access), not a temporary, as otherwise updates to the static could be lost. CONV_LVAL_MUT is not required for immutable statics, which cannot appear in mutable lvalue contexts.

Usage: rewrite_expr PAT REPL [FILTER]

Marks: reads FILTER, if set; may read other marks depending on PAT

For every expression in the crate matching PAT, replace it with REPL. PAT and REPL are both Rust expressions. PAT can use placeholders to capture nodes from the matched AST, and REPL can refer to those same placeholders to substitute in the captured nodes. See the matcher module for details on AST pattern matching.

If FILTER is provided, only expressions marked FILTER will be rewritten. This usage is obsolete - change PAT to marked!(PAT, FILTER) to get the same behavior.

Example:

 fn double(x: i32) -> i32 {
     x * 2
 }

After running rewrite_expr '$e * 2' '$e + $e':

 fn double(x: i32) -> i32 {
     x + x
 }

Here $e * 2 matches x * 2, capturing x as $e. Then x is substituted for $e in $e + $e, producing the final expression x + x.

Usage: rewrite_ty PAT REPL [FILTER]

Marks: reads FILTER, if set; may read other marks depending on PAT

For every type in the crate matching PAT, replace it with REPL. PAT and REPL are both Rust types. PAT can use placeholders to capture nodes from the matched AST, and REPL can refer to those same placeholders to substitute in the captured nodes. See the matcher module for details on AST pattern matching.

If FILTER is provided, only expressions marked FILTER will be rewritten. This usage is obsolete - change PAT to marked!(PAT, FILTER) to get the same behavior.

See the documentation for rewrite_expr for an example of this style of rewriting.

Usage: select MARK SCRIPT

Marks: sets MARK; may set/clear other marks depending on SCRIPT

Run node-selection script SCRIPT, and apply MARK to the nodes it selects. See select::SelectOp, select::Filter, and select::parser for details on select script syntax.

Usage: select_phase2 MARK SCRIPT

Marks: sets MARK; may set/clear other marks depending on SCRIPT

Works like select, but stops the compiler's analyses before typechecking happens. This means type information will not available, and script commands that refer to it will fail.

Usage: set_mutability MUT

Marks: target

Set the mutability of all items marked target to MUT. MUT is either imm or mut. This command only affects static items (including extern statics).

Usage: set_visibility VIS

Marks: target

Set the visibility of all items marked target to VIS. VIS is a Rust visibility qualifier such as pub, pub(crate), or the empty string.

Doesn't handle struct field visibility, for now.

Usage: sink_lets

For each local variable with a trivial initializer, move the local's declaration to the innermost block containing all its uses.

"Trivial" is currently defined as no initializer (let x;) or an initializer without any side effects. This transform requires trivial assignments to avoid reordering side effects.

Usage: sink_unsafe

Marks: target

For functions marked target, convert unsafe fn f() { ... } into fn () { unsafe { ... } }. Useful once unsafe argument handling has been eliminated from the function.

Usage: static_collect_to_struct STRUCT VAR

Marks: target

Collect marked statics into a single static struct.

Specifically:

1. Find all statics marked target. For each one, record its name, type, and initializer expression, then delete it.
2. Generate a new struct definition named STRUCT. For each marked static, include a field of STRUCT with the same name and type as the static.
3. Generate a new static mut named VAR whose type is STRUCT. Initialize it using the initializer expressions for the marked statics.
4. For each marked static foo, replace uses of foo with VAR.foo.

Example:

 static mut FOO: i32 = 100;
 static mut BAR: bool = true;

 unsafe fn f() -> i32 {
     FOO
 }

After running static_collect_to_struct Globals G, with both statics marked:

 struct Globals {
     FOO: i32,
     BAR: bool,
 }

 static mut G: Globals = Globals {
     FOO: 100,
     BAR: true,
 };

 unsafe fn f() -> i32 {
     G.FOO
 }

Usage: static_to_local

Marks: target

Delete each static marked target. For each function that uses a marked static, insert a new local variable definition replicating the marked static.

Example:

 static mut FOO: i32 = 100;  // FOO: target

 unsafe fn f() -> i32 {
     FOO
 }

 unsafe fn g() -> i32 {
     FOO + 1
 }

After running static_to_local:

 // `FOO` deleted

 // `f` gains a new local, replicating `FOO`.
 unsafe fn f() -> i32 {
     let FOO: i32 = 100;
     FOO
 }

 // If multiple functions use `FOO`, each one gets its own copy.
 unsafe fn g() -> i32 {
     let FOO: i32 = 100;
     FOO + 1
 }

Usage: static_to_local_ref

Marks: target, user

For each function marked user, replace uses of statics marked target with uses of newly-introduced reference arguments. Afterward, no user function directly accesses any target static. At call sites of user functions, a reference to the original static is passed in for each new argument if the caller is not itself a user function; otherwise, the caller's own reference argument is passed through. Note this sometimes results in functions gaining arguments corresponding to statics that the function itself does not use, but that its callees do.

Example:

 static mut FOO: i32 = 100;  // FOO: target

 unsafe fn f() -> i32 {  // f: user
     FOO
 }

 unsafe fn g() -> i32 {  // g: user
     f()
 }

 unsafe fn h() -> i32 {
     g()
 }

After running static_to_local_ref:

 static mut FOO: i32 = 100;

 // `f` is a `user` that references `FOO`, so it
 // gains a new argument `FOO_`.
 unsafe fn f(FOO_: &mut i32) -> i32 {
     // References to `FOO` are replaced with `*FOO_`
     *FOO_
 }

 // `g` is a `user` that references `FOO` indirectly,
 // via fellow `user` `f`.
 unsafe fn g(FOO_: &mut i32) -> i32 {
     // `g` passes through its own `FOO_` reference
     // when calling `f`.
     f(FOO_)
 }

 // `h` is not a `user`, so its signature is unchanged.
 unsafe fn h() -> i32 {
     // `h` passes in a reference to the original
     // static `FOO`.
     g(&mut FOO)
 }

Usage: struct_assign_to_update

Replace all struct field assignments with functional update expressions.

Example:

 let mut x: S = ...;
 x.f = 1;
 x.g = 2;

After running struct_assign_to_update:

 let mut x: S = ...;
 x = S { f: 1, ..x };
 x = S { g: 2, ..x };

Usage: struct_merge_updates

Merge consecutive struct updates into a single update.

Example:

 let mut x: S = ...;
 x = S { f: 1, ..x };
 x = S { g: 2, ..x };

After running struct_assign_to_update:

 let mut x: S = ...;
 x = S { f: 1, g: 2, ..x };

Test command - not intended for general use.

Usage: test_analysis_ownership

Runs the ownership analysis and dumps the results to stderr.

Test command - not intended for general use.

Usage: test_analysis_type_eq

Runs the type_eq analysis and logs the result (at level info).

Test command - not intended for general use.

Usage: test_debug_callees

Inspect the details of each Call expression. Used to debug RefactorCtxt::opt_callee_info.

Test command - not intended for general use.

Usage: test_f_plus_one

Replace the expression f(__x) with __x + 1 everywhere it appears.

Test command - not intended for general use.

Usage: test_insert_remove_args INS REM

In each function marked target, insert new arguments at each index listed in INS (a comma-separated list of integers), then delete the arguments whose original indices are listed in REM.

This is used for testing sequence rewriting of fn argument lists.

Test command - not intended for general use.

Usage: test_one_plus_one

Replace the expression 2 with 1 + 1 everywhere it appears.

Test command - not intended for general use.

Usage: test_reflect

Applies path and ty reflection on every expr in the program.

Test command - not intended for general use.

Usage: test_replace_stmts OLD NEW

Replace statement(s) OLD with NEW everywhere it appears.

Test command - not intended for general use.

Usage: test_typeck_loop

Runs a no-op typechecking loop for three iterations. Used to test the typechecking loop and AST re-analysis code.

Usage: type_fix_rules RULE...

Attempts to fix type errors in the crate using the provided rules. Each rule has the form "ectx, actual_ty, expected_ty => cast_expr".

• ectx is one of rval, lval, lval_mut, or *, and determines in what kinds of expression contexts the rule applies.
• actual_ty is a pattern to be matched against the (reflected) actual expression type.
• expected_ty is a pattern to be matched against the (reflected) expected expression type.
• cast_expr is a template for generating a cast expression.

For expressions in context ectx, whose actual type matches actual_ty and whose expected type matches expected_ty (and where actual != expected), the expr is substituted into cast_expr to replace the original expr with one of the expected type. During substitution, cast_expr has access to variables captured from both actual_ty and expected_ty, as well as __old containing the original (ill-typed) expression.

Obsolete - works around translator problems that no longer exist.

Usage: uninit_to_default

In local variable initializers, replace mem::uninitialized() with an appropriate default value of the variable's type.

Usage: wrap_api

Marks: target

For each function foo marked target:

1. Reset the function's ABI to "Rust" (the default)
2. Remove any #[no_mangle] or #[export_name] attributes
3. Generate a new wrapper function called foo_wrapper with foo's old ABI and an #[export_name="foo"] attribute.

Calls to foo are left unchanged. The result is that callers from C use the wrapper function, while internal calls use foo directly, and the signature of foo can be changed freely without affecting external callers.

Usage: wrap_extern

Marks: target, dest

For each foreign function marked target, generate a wrapper function in the module marked dest, and rewrite all uses of the function to call the wrapper instead.

Example:

 extern "C" {
     fn foo(x: i32) -> i32;
 }

 mod wrappers {
     // empty
 }

 fn main() {
     let x = unsafe { foo(123) };
 }

After transformation, with fn foo marked target and mod wrappers marked dest:

 extern "C" {
     fn foo(x: i32) -> i32;
 }

 mod wrappers {
     unsafe fn foo(x: i32) -> i32 {
         ::foo(x)
     }
 }

 fn main() {
     let x = unsafe { ::wrappers::foo(123) };
 }

Note that this also replaces the function in expressions that take its address, which may cause problem as the wrapper function has a different type that the original (it lacks the extern "C" ABI qualifier).

Usage: wrapping_arith_to_normal

Replace all uses of wrapping arithmetic methods with ordinary arithmetic operators. For example, replace x.wrapping_add(y) with x + y.

<h2 class="section-header "><a name="Tables"></a>Tables</h2>

<dl class="function">
<dt>
<a name = "Stmt"></a>
<strong>Stmt</strong>
</dt>
<dd>
AST Stmt


<h3>Fields:</h3>
<ul>
    <li><span class="parameter">type</span>
     "Stmt"
    </li>
    <li><span class="parameter">kind</span>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>
     <code>StmtKind</code> of this statement</p>

<h3>Fields:</h3>
<ul>
    <li><span class="parameter">type</span>
     "Expr"
    </li>
    <li><span class="parameter">kind</span>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>
     <code>ExprKind</code> of this expression</p>

<dl class="function">
<dt>
<a name = "refactor"></a>
<strong>refactor</strong>
</dt>
<dd>
Global refactoring state


<ul>
    <li><span class="parameter">refactor</span>
     RefactorState object
    </li>
</ul>

      <div class="section-description">
      Refactoring context
      </div>
<dl class="function">
<dt>
<a name = "RefactorState:run_command"></a>
<strong>RefactorState:run_command (name, args)</strong>
</dt>
<dd>
Run a builtin refactoring command


<h3>Parameters:</h3>
<ul>
    <li><span class="parameter">name</span>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>
     Command to run
    </li>
    <li><span class="parameter">args</span>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">{string,...}</a></span>
     List of arguments for the command
    </li>
</ul>

<h3>Parameters:</h3>
<ul>
    <li><span class="parameter">callback</span>
        <span class="types"><span class="type">function(TransformCtxt,AstNode)</span></span>
     Transformation function called with a fresh <a href="scripting_api.html#TransformCtxt">TransformCtxt</a> and the crate to be transformed.
    </li>
</ul>

      <div class="section-description">
      A match context
      </div>
<dl class="function">
<dt>
<a name = "MatchCtxt:parse_stmts"></a>
<strong>MatchCtxt:parse_stmts (pat)</strong>
</dt>
<dd>
Parse statements and add them to this MatchCtxt


<h3>Parameters:</h3>
<ul>
    <li><span class="parameter">pat</span>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>
     Pattern to parse
    </li>
</ul>

<h3>Returns:</h3>
<ol>

       <span class="types"><a class="type" href="scripting_api.html#AstNode">AstNode</a></span>
    The parsed statements
</ol>

<h3>Parameters:</h3>
<ul>
    <li><span class="parameter">pat</span>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>
     Pattern to parse
    </li>
</ul>

<h3>Returns:</h3>
<ol>

       <span class="types"><a class="type" href="scripting_api.html#AstNode">AstNode</a></span>
    The parsed expression
</ol>

<h3>Parameters:</h3>
<ul>
    <li><span class="parameter">needle</span>
        <span class="types"><a class="type" href="scripting_api.html#AstNode">AstNode</a></span>
     Pattern to search for
    </li>
    <li><span class="parameter">crate</span>
        <span class="types"><a class="type" href="scripting_api.html#AstNode">AstNode</a></span>
     Crate to fold over
    </li>
    <li><span class="parameter">callback</span>
        <span class="types"><span class="type">function(AstNode,MatchCtxt)</span></span>
     Function called for each match. Takes the matching node and a new <a href="scripting_api.html#MatchCtxt">MatchCtxt</a> for that match.
    </li>
</ul>

<h3>Parameters:</h3>
<ul>
    <li><span class="parameter">Expression</span>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>
     variable pattern
    </li>
</ul>

<h3>Returns:</h3>
<ol>

       <span class="types"><a class="type" href="scripting_api.html#AstNode">AstNode</a></span>
    Expression matched by this binding
</ol>

<h3>Parameters:</h3>
<ul>
    <li><span class="parameter">Statement</span>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>
     variable pattern
    </li>
</ul>

<h3>Returns:</h3>
<ol>

       <span class="types"><a class="type" href="scripting_api.html#AstNode">AstNode</a></span>
    Statement matched by this binding
</ol>

<h3>Parameters:</h3>
<ul>
    <li><span class="parameter">pat</span>
        <span class="types"><a class="type" href="scripting_api.html#AstNode">AstNode</a></span>
     AST (potentially with variable bindings) to match with
    </li>
    <li><span class="parameter">target</span>
        <span class="types"><a class="type" href="scripting_api.html#AstNode">AstNode</a></span>
     AST to match against
    </li>
</ul>

<h3>Returns:</h3>
<ol>

       <span class="types"><span class="type">bool</span></span>
    true if match was successful
</ol>

<h3>Parameters:</h3>
<ul>
    <li><span class="parameter">replacement</span>
        <span class="types"><a class="type" href="scripting_api.html#AstNode">AstNode</a></span>
     New AST node to replace the currently matched AST. May include variable bindings if these bindings were matched by the search pattern.
    </li>
</ul>

<h3>Returns:</h3>
<ol>

       <span class="types"><a class="type" href="scripting_api.html#AstNode">AstNode</a></span>
    New AST node with variable bindings replaced by their matched values
</ol>

      <div class="section-description">
      Transformation context
      </div>
<dl class="function">
<dt>
<a name = "TransformCtxt:replace_stmts_with"></a>
<strong>TransformCtxt:replace_stmts_with (needle, callback)</strong>
</dt>
<dd>
Replace matching statements using given callback


<h3>Parameters:</h3>
<ul>
    <li><span class="parameter">needle</span>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>
     Statements pattern to search for, may include variable bindings
    </li>
    <li><span class="parameter">callback</span>
        <span class="types"><span class="type">function(AstNode,MatchCtxt)</span></span>
     Function called for each match. Takes the matching node and a new <a href="scripting_api.html#MatchCtxt">MatchCtxt</a> for that match. See <a href="scripting_api.html#MatchCtxt:fold_with">MatchCtxt:fold_with</a>
    </li>
</ul>

<h3>Parameters:</h3>
<ul>
    <li><span class="parameter">needle</span>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>
     Expression pattern to search for, may include variable bindings
    </li>
    <li><span class="parameter">callback</span>
        <span class="types"><span class="type">function(AstNode,MatchCtxt)</span></span>
     Function called for each match. Takes the matching node and a new <a href="scripting_api.html#MatchCtxt">MatchCtxt</a> for that match. See <a href="scripting_api.html#MatchCtxt:fold_with">MatchCtxt:fold_with</a>
    </li>
</ul>

<h3>Returns:</h3>
<ol>

       <span class="types"><a class="type" href="scripting_api.html#MatchCtxt">MatchCtxt</a></span>
    New match context
</ol>

<h3>Parameters:</h3>
<ul>
    <li><span class="parameter">node</span>
        <span class="types"><a class="type" href="scripting_api.html#AstNode">AstNode</a></span>
     AST node handle
    </li>
</ul>

<h3>Returns:</h3>
<ol>

    Struct representation of this AST node. Valid return types are <a href="scripting_api.html#Stmt">Stmt</a>, and <a href="scripting_api.html#Expr">Expr</a>.
</ol>

c2rust refactor provides a general-purpose rewriting command, rewrite_expr, for transforming expressions. In its most basic form, rewrite_expr replaces one expression with another, everywhere in the crate:

rewrite_expr '1+1' '2'

fn main() {

fn main() {

    println!("{}", 1 + 1);

    println!("{}", 2);

    println!("{}", 1 + /*comment*/ 1);

    println!("{}", 2);

    println!("{}", 1 + 11);

    println!("{}", 1 + 11);

}

}

Here, all instances of the expression 1+1 (the "pattern") are replaced with 2 (the "replacement").

rewrite_expr parses both the pattern and the replacement as Rust expressions, and compares the structure of the expression instead of its raw text when looking for occurrences of the pattern. This lets it recognize that 1 + 1 and 1 + /* comment */ both match the pattern 1+1 (despite being textually distinct), while 1+11 does not (despite being textually similar).

In rewrite_expr's expression pattern, any name beginning with double underscores is a metavariable. Just as a variable in an ordinary Rust match expression will match any value (and bind it for later use), a metavariable in an expression pattern will match any Rust code. For example, the expression pattern __x + 1 will match any expression that adds 1 to something:

rewrite_expr '__x + 1' '11'

fn f() -> i32 {

fn f() -> i32 {

    123

    123

}

}

fn main() {

fn main() {

    println!("a = {}", 1 + 1);

    println!("a = {}", 11);

    println!("b = {}", 2 * 3 + 1);

    println!("b = {}", 11);

    println!("c = {}", 4 + 5 + 1);

    println!("c = {}", 11);

    println!("d = {}", f() + 1);

    println!("d = {}", 11);

}

}

In these examples, the __x metavariable matches the expressions 1, 2 * 3, and f().

When a metavariable matches against some piece of code, the code it matches is bound to the variable for later use. Specifically, rewrite_expr's replacement argument can refer back to those metavariables to substitute in the matched code:

rewrite_expr '__x + 1' '11 * __x'

fn f() -> i32 {

fn f() -> i32 {

    123

    123

}

}

fn main() {

fn main() {

    println!("a = {}", 1 + 1);

    println!("a = {}", 11 * 1);

    println!("b = {}", 2 * 3 + 1);

    println!("b = {}", 11 * (2 * 3));

    println!("c = {}", 4 + 5 + 1);

    println!("c = {}", 11 * (4 + 5));

    println!("d = {}", f() + 1);

    println!("d = {}", 11 * f());

}

}

In each case, the expression bound to the __x metavariable is substituted into the right-hand side of the multiplication in the replacement.

Finally, the same metavariable can appear multiple times in the pattern. In that case, the pattern matches only if each occurence of the metavariable matches the same expression. For example:

rewrite_expr '__x + __x' '2 * __x'

fn f() -> i32 {

fn f() -> i32 {

    123

    123

}

}

fn main() {

fn main() {

    let a = 2;

    let a = 2;

    println!("{}", 1 + 1);

    println!("{}", 2 * 1);

    println!("{}", a + a);

    println!("{}", 2 * a);

    println!("{}", f() + f());

    println!("{}", 2 * f());

    println!("{}", f() + 1);

    println!("{}", f() + 1);

}

}

Here a + a and f() + f() are both replaced, but f() + 1 is not because __x cannot match both f() and 1 at the same time.

Suppose we wish to add an argument to an existing function. All current callers of the function should pass a default value of 0 for this new argument. We can update the existing calls like this:

rewrite_expr 'my_func(__x, __y)' 'my_func(__x, __y, 0)'

fn my_func(x: i32, y: i32) {

fn my_func(x: i32, y: i32) {

    /* ... */

    /* ... */

}

}

fn main() {

fn main() {

    my_func(1, 2);

    my_func(1, 2, 0);

    let x = 123;

    let x = 123;

    my_func(x, x);

    my_func(x, x, 0);

    my_func(0, {

    my_func(

        0,

        {

        let y = x;

            let y = x;

        y + y

            y + y

        },

        0,

    });

    );

}

}

Every call to my_func now passes a third argument, and we can update the definition of my_func to match.

rewrite_expr supports several special matching forms that can appear in patterns to add extra restrictions to matching.

A pattern such as def!(::foo::f) matches any ident or path expression that resolves to the function whose absolute path is ::foo::f. For example, to replace all expressions referencing the function foo::f with ones referencing foo::g:

rewrite_expr 'def!(::foo::f)' '::foo::g'

mod foo {

mod foo {

    fn f() {

    fn f() {

        /* ... */

        /* ... */

    }

    }

    fn g() {

    fn g() {

        /* ... */

        /* ... */

    }

    }

}

}

fn main() {

fn main() {

    use self::foo::f;

    use self::foo::f;

    // All these calls get rewritten

    // All these calls get rewritten

    f();

    f();

    foo::f();

    ::foo::f();

    ::foo::g();

    ::foo::g();

}

}

mod bar {

mod bar {

    fn f() {}

    fn f() {}

    fn f_caller() {

    fn f_caller() {

        // This call does not...

        // This call does not...

        f();

        f();

        // But this one still does

        // But this one still does

        super::foo::f();

        ::foo::g();

    }

    }

}

}

This works for all direct references to f, whether by relative path (foo::f), absolute path (::foo::f), or imported identifier (just f, with use foo::f in scope). It can even handle imports under a different name (f2 with use foo::f as f2 in scope), since it checks only the path of the referenced definition, not the syntax used to reference it.

When rewrite_expr attempts to match def!(path) against some expression e, it actually completely ignores the content of e itself. Instead, it performs these steps:

1. Check rustc's name resolution results to find the definition d that e resolves to. (If e doesn't resolve to a definition, then the matching fails.)
2. Construct an absolute path dpath referring to d. For definitions in the current crate, this path looks like ::mod1::def1. For definitions in other crates, it looks like ::crate1::mod1::def1.
3. Match dpath against the path pattern provided as the argument of def!. Then e matches def!(path) if dpath matches path, and fails to match otherwise.

Matching with def! can sometimes fail in surprising ways, since the user-provided path is matched against a generated path that may not appear explicitly anywhere in the source code. For example, this attempt to match HashMap::new does not succeed:

rewrite_expr
    'def!(::std::collections::hash_map::HashMap::new)()'
    '::std::collections::hash_map::HashMap::with_capacity(10)'

use std::collections::hash_map::HashMap;

use std::collections::hash_map::HashMap;

fn main() {

fn main() {

    let m: HashMap<i32, i32> = HashMap::new();

    let m: HashMap<i32, i32> = HashMap::new();

}

}

The debug_match_expr command exists to diagnose such problems. It takes only a pattern, and prints information about attempts to match it at various points in the crate:

debug_match_expr 'def!(::std::collections::hash_map::HashMap::new)()'

Here, its output includes this line:

def!(): trying to match pattern path(::std::collections::hash_map::HashMap::new) against AST path(::std::collections::HashMap::new)

Which reveals the problem: the absolute path def! generates for HashMap::new uses the reexport at std::collections::HashMap, not the canonical definition at std::collections::hash_map::HashMap. Updating the previous rewrite_expr command allows it to succeed:

rewrite_expr
    'def!(::std::collections::HashMap::new)()'
    '::std::collections::HashMap::with_capacity(10)'

use std::collections::hash_map::HashMap;

use std::collections::hash_map::HashMap;

fn main() {

fn main() {

    let m: HashMap<i32, i32> = HashMap::new();

    let m: HashMap<i32, i32> = ::std::collections::HashMap::with_capacity(10);

}

}

The argument to def! is a path pattern, which can contain metavariables just like the overall expression pattern. For instance, we can rewrite all calls to functions from the foo module:

rewrite_expr 'def!(::foo::__name)()' '123'

mod foo {

mod foo {

    fn f() {

    fn f() {

        /* ... */

        /* ... */

    }

    }

    fn g() {

    fn g() {

        /* ... */

        /* ... */

    }

    }

}

}

mod bar {

mod bar {

    fn f() {

    fn f() {

        /* ... */

        /* ... */

    }

    }

    fn g() {

    fn g() {

        /* ... */

        /* ... */

    }

    }

}

}

fn main() {

fn main() {

    foo::f();

    123;

    foo::g();

    123;

}

}

Since every definition in the foo module has an absolute path of the form ::foo::(something), they all match the expression pattern def!(::foo::__name).

Like any other metavariable, the ones in a def! path pattern can be used in the replacement expression to substitute in the captured name. For example, we can replace all references to items in the foo module with references to the same-named items in the bar module:

rewrite_expr 'def!(::foo::__name)' '::bar::__name'

mod foo {

mod foo {

    fn f() {

    fn f() {

        /* ... */

        /* ... */

    }

    }

    fn g() {

    fn g() {

        /* ... */

        /* ... */

    }

    }

}

}

mod bar {

mod bar {

    fn f() {

    fn f() {

        /* ... */

        /* ... */

    }

    }

    fn g() {

    fn g() {

        /* ... */

        /* ... */

    }

    }

}

}

fn main() {

fn main() {

    foo::f();

    ::bar::f();

    foo::g();

    ::bar::g();

}

}

Note, however, that each metavariable in a path pattern can match only a single ident. This means foo::__name will not match the path to an item in a submodule, such as foo::one::two. Handling these would require an additional rewrite step, such as rewrite_expr 'def!(::foo::__name1::__name2)' '::bar::__name1::__name2'.

A pattern of the form typed!(e, ty) matches any expression that matches the pattern e, but only if the type of that expression matches the pattern ty. For example, we can perform a rewrite that only affects i32s:

rewrite_expr 'typed!(__e, i32)' '0'

fn main() {

fn main() {

    let x = 100_i32;

    let x = 0;

    let z = x + y;

    let z = 0;

    let a = "hello";

    let a = "hello";

    let b = format!("{}, {}", a, "world");

    let b = format!("{}, {}", a, "world");

}

}

Every expression matches the metavariable __e, but only the i32s (whether literals or variables of type i32) are affected by the rewrite.

Internally, typed! works much like def!. To match an expression e against typed!(e_pat, ty_pat), rewrite_expr follows these steps:

1. Consult rustc's typechecking results to get the type of e. Call that type rustc_ty.
2. rustc_ty is an internal, abstract representation of the type, which is not suitable for matching. Construct a concrete representation of rustc_ty, and call it ty.
3. Match e against e_pat and ty against ty_pat. Then e matches typed!(e_pat, ty_pat) if both matches succeed, and fails to match otherwise.

When matching fails unexpectedly, debug_match_expr is once again useful for understanding the problem. For example, this rewriting command has no effect:

rewrite_expr "typed!(__e, &'static str)" '"hello"'

fn main() {

fn main() {

    let a = "hello";

    let a = "hello";

    let b = format!("{}, {}", a, "world");

    let b = format!("{}, {}", a, "world");

}

}

Passing the same pattern to debug_match_expr produces output that includes the following:

typed!(): trying to match pattern type(&'static str) against AST type(&str)

Now the problem is clear: the concrete type representation constructed for matching omits lifetimes. Replacing &'static str with &str in the pattern causes the rewrite to succeed:

rewrite_expr 'typed!(__e, &str)' '"hello"'

fn main() {

fn main() {

    let a = "hello";

    let a = "hello";

    let b = format!("{}, {}", a, "world");

    let b = format!("{}, {}", "hello", "hello");

}

}

The expression pattern and type pattern arguments of typed!(e, ty) are handled using the normal rewrite_expr matching engine, which means they can contain metavariables and other special matching forms. For example, metavariables can capture both parts of the expression and parts of its type for use in the replacement:

rewrite_expr
    'typed!(Vec::with_capacity(__n), ::std::vec::Vec<__ty>)'
    '::std::iter::repeat(<__ty>::default())
        .take(__n)
        .collect::<Vec<__ty>>()'

fn main() {

fn main() {

    let v: Vec<&'static str> = Vec::with_capacity(20);

    let v: Vec<&'static str> = ::std::iter::repeat(<&str>::default())

        .take(20)

        .collect::<Vec<&str>>();

    let v: Vec<_> = Vec::with_capacity(10);

    let v: Vec<_> = ::std::iter::repeat(<i32>::default())

        .take(10)

        .collect::<Vec<i32>>();

    // Allow `v`'s element type to be inferred

    // Allow `v`'s element type to be inferred

    let x: i32 = v[0];

    let x: i32 = v[0];

}

}

Notice that the rewritten code has the correct element type in the call to default, even in cases where the type is not written explicitly in the original expression! The matching of typed! obtains the inferred type information from rustc, and those inferred types are captured by metavariables in the type pattern.

This example demonstrates usage of def! and typed!.

Suppose we have some unsafe code that uses transmute to convert a raw pointer that may be null (*const T) into an optional reference (Option<&T>). This conversion is better expressed using the as_ref method of *const T, and we'd like to apply this transformation automatically.

Here is a basic first attempt:

rewrite_expr 'transmute(__e)' '__e.as_ref()'

use std::mem;

use std::mem;

unsafe fn foo(ptr: *const u32) {

unsafe fn foo(ptr: *const u32) {

    let r: &u32 = mem::transmute::<*const u32, Option<&u32>>(ptr).unwrap();

    let r: &u32 = mem::transmute::<*const u32, Option<&u32>>(ptr).unwrap();

    let opt_r2: Option<&u32> = mem::transmute(ptr);

    let opt_r2: Option<&u32> = mem::transmute(ptr);

    let r2 = opt_r2.unwrap();

    let r2 = opt_r2.unwrap();

    let ptr2: *const u32 = mem::transmute(r2);

    let ptr2: *const u32 = mem::transmute(r2);

    {

    {

        use std::mem::transmute;

        use std::mem::transmute;

        let opt_r3: Option<&u32> = transmute(ptr);

        let opt_r3: Option<&u32> = ptr.as_ref();

        let r3 = opt_r2.unwrap();

        let r3 = opt_r2.unwrap();

    }

    }

    /* ... */

    /* ... */

}

}

This has two major shortcomings, which we will address in order:

1. It works only on code that calls exactly transmute(foo). The instances that import std::mem and call mem::transmute(foo) do not get rewritten.
2. It rewrites transmutes between any types, not just *const T to Option<&T>. Only transmutes between those types should be replaced with as_ref.

We want to rewrite calls to std::mem::transmute, regardless of how those calls are written. This is a perfect use case for def!:

rewrite_expr 'def!(::std::intrinsics::transmute)(__e)' '__e.as_ref()'

use std::mem;

use std::mem;

unsafe fn foo(ptr: *const u32) {

unsafe fn foo(ptr: *const u32) {

    let r: &u32 = mem::transmute::<*const u32, Option<&u32>>(ptr).unwrap();

    let r: &u32 = ptr.as_ref().unwrap();

    let opt_r2: Option<&u32> = mem::transmute(ptr);

    let opt_r2: Option<&u32> = ptr.as_ref();

    let r2 = opt_r2.unwrap();

    let r2 = opt_r2.unwrap();

    let ptr2: *const u32 = mem::transmute(r2);

    let ptr2: *const u32 = r2.as_ref();

    {

    {

        use std::mem::transmute;

        use std::mem::transmute;

        let opt_r3: Option<&u32> = transmute(ptr);

        let opt_r3: Option<&u32> = ptr.as_ref();

        let r3 = opt_r2.unwrap();

        let r3 = opt_r2.unwrap();

    }

    }

    /* ... */

    /* ... */

}

}

Now our rewrite catches all uses of transmute, whether they're written as transmute(foo), mem::transmute(foo), or even ::std::mem::transmute(foo).

Notice that we refer to transmute as std::intrinsics::transmute: this is the location of its original definition, which is re-exported in std::mem. See the "def!: debugging match failures" section for an explanation of how we discovered this.

We now have a command for rewriting all transmute calls, but we'd like it to rewrite only transmutes from *const T to Option<&T>. We can achieve this by filtering the input and output types with typed!:

rewrite_expr '
    typed!(
        def!(::std::intrinsics::transmute)(
            typed!(__e, *const __ty)
        ),
        ::std::option::Option<&__ty>
    )
' '__e.as_ref()'

use std::mem;

use std::mem;

unsafe fn foo(ptr: *const u32) {

unsafe fn foo(ptr: *const u32) {

    let r: &u32 = mem::transmute::<*const u32, Option<&u32>>(ptr).unwrap();

    let r: &u32 = ptr.as_ref().unwrap();

    let opt_r2: Option<&u32> = mem::transmute(ptr);

    let opt_r2: Option<&u32> = ptr.as_ref();

    let r2 = opt_r2.unwrap();

    let r2 = opt_r2.unwrap();

    let ptr2: *const u32 = mem::transmute(r2);

    let ptr2: *const u32 = mem::transmute(r2);

    {

    {

        use std::mem::transmute;

        use std::mem::transmute;

        let opt_r3: Option<&u32> = transmute(ptr);

        let opt_r3: Option<&u32> = ptr.as_ref();

        let r3 = opt_r2.unwrap();

        let r3 = opt_r2.unwrap();

    }

    }

    /* ... */

    /* ... */

}

}

Now only those transmutes that turn *const T into Option<&T> are affected by the rewrite. And because typed! has access to the results of type inference, this works even on transmute calls that are not fully annotated (transmute(foo), not just transmute::<*const T, Option<&T>>(foo)).

The marked! form is simple: marked!(e, label) matches an expression only if e matches the expression and the expression is marked with the given label. See the documentation on marks and select for more information.

Several other refactoring commands use the same pattern-matching engine as rewrite_expr:

• rewrite_ty PAT REPL (docs) works like rewrite_expr, except it matches and replaces type annotations instead of expressions.
• abstract SIG PAT (docs) replaces expressions matching a pattern with calls to a newly-created function.
• type_fix_rules (docs) uses type patterns to find the appropriate rule to fix each type error.
• select's match_expr (docs) and similar filters use syntax patterns to identify nodes to mark.

Many refactoring commands in c2rust refactor are designed to work only on selected portions of the crate, rather than affecting the entire crate uniformly. To support this, c2rust refactor has a mark system, which allows marking AST nodes (such as functions, expressions, or type annotations) with simple string labels. Certain commands add or remove marks, while others check the existing marks to identify nodes to transform.

For example, in a program containing several byte string literals, you can use select to mark a specific one:

select target 'item(B2); desc(expr);'

static B1: &'static [u8] = b"123";

static B1: &'static [u8] = b"123";

static B2: &'static [u8] = b"abc";

static B2: &'static [u8] = ▶b"abc"◀;

static B3: &'static [u8] = b"!!!";

static B3: &'static [u8] = b"!!!";

Then, you can use bytestr_to_str to change only the marked byte string to an ordinary string literal, leaving the others unaffected:

bytestr_to_str

static B1: &'static [u8] = b"123";

static B1: &'static [u8] = b"123";

static B2: &'static [u8] = ▶b"abc"◀;

static B2: &'static [u8] = ▶"abc"◀;

static B3: &'static [u8] = b"!!!";

static B3: &'static [u8] = b"!!!";

This ability to limit transformations to specific parts of the program is useful for refactoring a large codebase incrementally, on a module-by-module or function-by-function basis.

The remainder of this tutorial describes select and related mark-manipulation commands. For details of how marks affect various transformation commands, see the command documentation or read about the marked! pattern for rewrite_expr and other pattern-matching commands.

A "mark" is a short string label that is associated with a node in the AST. Marks can be applied to nodes of most kinds, including items, expressions, patterns, type annotations, and so on. The mark string can be any valid Rust identifier, though most commands that process marks use short words such as target, dest, or new. It's possible to apply multiple distinct marks to the same node, and it's also possible to mark children of marked nodes separately from their parents (for example, to mark an expression and one of its subexpressions).

Here are some examples.

select target 'crate; desc(match_expr(2 + 2));'

fn f() -> Option<i32> {

fn f() -> Option<i32> {

    Some(2 + 2)

    Some(▶2 + 2◀)

}

}

fn g() -> i32 {

fn g() -> i32 {

    match f() {

    match f() {

        Some(x) => x,

        Some(x) => x,

        None => 0,

        None => 0,

    }

    }

}

}

The ▶ ... ◀ indicators in the diff show that the expression 2 + 2 has been marked. Hover over the indicators for more details, such as the label of the added mark.

As mentioned above, most kinds of nodes can be marked, not only expressions. Here we mark a function, a pattern, and a type annotation:

select a 'item(f);' ;
select b 'item(g); desc(match_ty(i32));' ;
select c 'item(g); desc(match_pat(Some(x)));' ;

fn f() -> Option<i32> {

▶fn f() -> Option<i32> {

    Some(2 + 2)

    Some(2 + 2)

}

}◀

fn g() -> i32 {

fn g() -> ▶i32◀ {

    match f() {

    match f() {

        Some(x) => x,

        ▶Some(x)◀ => x,

        None => 0,

        None => 0,

    }

    }

}

}

As mentioned above, it's possible to mark the same node twice with different labels. (Marking it twice with the same label is no different from marking it once.) Here's an example of marking a function multiple times:

select a 'item(f);' ;
select a 'item(f);' ;
select b 'item(f);' ;

fn f() -> Option<i32> {

▶fn f() -> Option<i32> {

    Some(2 + 2)

    Some(2 + 2)

}

}◀

fn g() -> i32 {

fn g() -> i32 {

    match f() {

    match f() {

        Some(x) => x,

        Some(x) => x,

        None => 0,

        None => 0,

    }

    }

}

}

As you can see by hovering over the indicators, labels a and b were both added to the function f.

Marks on a node have no connection to marks on its parent or child nodes. We can, for example, mark an expression like 2 + 2, then separately mark its subexpressions with either the same or different labels:

select a 'item(f); desc(match_expr(2 + 2));' ;
select a 'item(f); desc(match_expr(2)); first;' ;
select b 'item(f); desc(match_expr(2)); last;' ;

fn f() -> Option<i32> {

fn f() -> Option<i32> {

    Some(2 + 2)

    Some(▶▶2◀ + ▶2◀◀)

}

}

fn g() -> i32 {

fn g() -> i32 {

    match f() {

    match f() {

        Some(x) => x,

        Some(x) => x,

        None => 0,

        None => 0,

    }

    }

}

}

Hovering over the mark indicators shows precisely what has happened: we marked both 2 + 2 and the first 2 with the label a, and marked the second 2 with the label b.

The select command provides a simple scripting language for applying marks to specific nodes. The basic syntax of the command is:

select LABEL SCRIPT

select runs a SCRIPT (written in the language described below) to obtain a set of AST nodes, then marks every node in the set with LABEL, which should be a single identifier such as target.

More concretely, when running the script, select maintains a "current selection", which is a set of AST nodes. Script operations (described below) can extend or modify the current selection. At the end of the script, select marks every node in the current selection with LABEL.

We next describe a few common select script patterns, followed by details on the available operations and filters.

For items such as functions, type declarations, or traits, the item(path) operation selects the item by its path:

select target 'item(f);' ;
select target 'item(T);' ;
select target 'item(S);' ;
select target 'item(m::g);' ;

fn f() {}

▶fn f() {}◀

trait T {}

▶trait T {}◀

struct S {}

▶struct S {}◀

mod m {

mod m {

    fn g() {}

    ▶fn g() {}◀

}

}

Note that this only works for the kinds of items that can be imported via use. It doesn't handle other kinds of item-like nodes, such as impl methods, which cannot be imported directly.

The operations crate; desc(filter); together select all nodes (or, equivalently, all descendants of the crate) that match a filter. For example, we can select all expressions matching the pattern 2 + 2 using a match_expr filter:

select target 'crate; desc(match_expr(2 + 2));'

fn f() -> i32 {

fn f() -> i32 {

    2 + 2

    ▶2 + 2◀

}

}

const FOUR: i32 = 2 + 2;

const FOUR: i32 = ▶2 + 2◀;

static ARRAY: [u8; 2 + 2] = [1, 2, 3, 4];

static ARRAY: [u8; ▶2 + 2◀] = [1, 2, 3, 4];

Here we see that crate; desc(filter); can find matching items anywhere in the crate: inside function bodies, constant declarations, and even inside the length expression of an array type annotation.

In the previous example, crate; desc(filter); is made up of two separate script operations. crate selects the entire crate:

select target 'crate;'

fn f() -> i32 {

▶fn f() -> i32 {

    2 + 2

    2 + 2

}

}

const FOUR: i32 = 2 + 2;

const FOUR: i32 = 2 + 2;

static ARRAY: [u8; 2 + 2] = [1, 2, 3, 4];

static ARRAY: [u8; 2 + 2] = [1, 2, 3, 4];◀

Then desc(filter) looks for descendants of selected nodes that match filter, and replaces the current selection with the nodes it finds:

clear_marks ;
select target 'crate; desc(match_expr(2 + 2));'

▶fn f() -> i32 {

fn f() -> i32 {

    2 + 2

    ▶2 + 2◀

}

}

const FOUR: i32 = 2 + 2;

const FOUR: i32 = ▶2 + 2◀;

static ARRAY: [u8; 2 + 2] = [1, 2, 3, 4];◀

static ARRAY: [u8; ▶2 + 2◀] = [1, 2, 3, 4];

(Note: we use clear_marks here only for illustration purposes, to make the diff clearly show the changes between the old and new versions of our select command.)

Combining desc with operations other than crate allows selecting descendants of only specific nodes. For example, we can find expressions matching 2 + 2, but only within the function f:

select target 'item(f); desc(match_expr(2 + 2));'

fn f() -> i32 {

fn f() -> i32 {

    2 + 2

    ▶2 + 2◀

}

}

const FOUR: i32 = 2 + 2;

const FOUR: i32 = 2 + 2;

static ARRAY: [u8; 2 + 2] = [1, 2, 3, 4];

static ARRAY: [u8; 2 + 2] = [1, 2, 3, 4];

In a more complex example, we can use multiple desc calls to target an expression inside of a specific method (recall that methods can't be selected directly with item(path)). We first select the module containing the impl:

select target 'item(m);'

fn f() -> i32 {

fn f() -> i32 {

    2 + 2

    2 + 2

}

}

mod m {

▶mod m {

    struct S;

    struct S;

    impl S {

    impl S {

        fn f(&self) -> i32 {

        fn f(&self) -> i32 {

            2 + 2

            2 + 2

        }

        }

    }

    }

}

}◀

Then we select the method of interest, using the name filter (described below):

clear_marks ;
select target 'item(m); desc(name("f"));'

fn f() -> i32 {

fn f() -> i32 {

    2 + 2

    2 + 2

}

}

▶mod m {

mod m {

    struct S;

    struct S;

    impl S {

    impl S {

        fn f(&self) -> i32 {

        ▶fn f(&self) -> i32 {

            2 + 2

            2 + 2

        }

        }◀

    }

    }

}◀

}

And finally, we select the expression inside the method:

clear_marks ;
select target 'item(m); desc(name("f")); desc(match_expr(2 + 2));'

fn f() -> i32 {

fn f() -> i32 {

    2 + 2

    2 + 2

}

}

mod m {

mod m {

    struct S;

    struct S;

    impl S {

    impl S {

        ▶fn f(&self) -> i32 {

        fn f(&self) -> i32 {

            2 + 2

            ▶2 + 2◀

        }◀

        }

    }

    }

}

}

Combined with some additional filters described below, this approach is quite effective for marking nodes that can't be named with an ordinary import path, such as impl methods or items nested inside functions.

A select script can consist of any number of operations, which will be run in order to completion. (There is no control flow in select scripts.) Each operation ends with a semicolon, much like Rust statements.

The remainder of this section documents each script operation.

crate (which takes no arguments) adds the root node of the entire crate to the current selection. All functions, modules, and other declarations are descendants of this single root node.

Example:

select target 'crate;'

fn f() -> i32 {

▶fn f() -> i32 {

    123

    123

}

}

mod m {

mod m {

    static S: i32 = 0;

    static S: i32 = 0;

}

}◀

item(p) adds the item identified by the path p to the current selection. The provided path is handled like in Rust's use declarations (except that only plain paths are supported, not wildcards or curly-braced blocks).

select target 'item(m::S);'

fn f() -> i32 {

fn f() -> i32 {

    123

    123

}

}

mod m {

mod m {

    static S: i32 = 0;

    ▶static S: i32 = 0;◀

}

}

Because the item operation only adds to the current selection (as opposed to replacing the current selection with a set containing only the identified item), we can run item multiple times to select several different items at once:

select target 'item(f); item(m::S); item(m);'

fn f() -> i32 {

▶fn f() -> i32 {

    123

    123

}

}◀

mod m {

▶mod m {

    static S: i32 = 0;

    ▶static S: i32 = 0;◀

}

}◀

child(f) checks each child of each currently selected node against the filter f, and replaces the current selection with the set of matching children.

This can be used, for example, to select a static's type annotation without selecting type annotations that appear inside its initializer:

select target 'item(S); child(kind(ty));'

static S: i32 = 123_u8 as i32;

static S: ▶i32◀ = 123_u8 as i32;

const C: u32 = 0;

const C: u32 = 0;

To illustrate how this works, here is the AST for the static S item:

• item static S
  • identifier S (the name of the static)
  • type i32 (the type annotation of the static)
  • expression 123_u8 as i32 (the initializer of the static)
    • expression 123_u8 (the input of the cast expression)
    • type i32 (the target type of the cast expression)

The static's type annotation is a direct child of the static (and has kind ty, matching the kind(ty) filter), so the type annotation is selected by the example command above. The target type for the cast is not a direct child of the static - rather, it's a child of the initializer expression, which is a child of the static - so it is ignored.

desc(f) ("descendant") checks each descendant of each currently selected node against the filter f, and replaces the current selection with the set of matching descendants. This is similar to child, but checks for matching descendants at any depth, not only matching direct children.

Using the same example as for child, we see that desc selects more nodes:

select target 'item(S); desc(kind(ty));'

static S: i32 = 123_u8 as i32;

static S: ▶i32◀ = 123_u8 as ▶i32◀;

const C: u32 = 0;

const C: u32 = 0;

Specifically, it selects both the type annotation of the static and the target type of the cast expression, as both are descendants of the static (though at different depths). Of course, it still does not select the type annotation of the const C, which is not a descendant of static S at any depth.

Note that desc only considers the strict descendants of marked nodes - that is, it does not consider a node to be a "depth-zero" descendant of itself. So, for example, the following command selects nothing:

select target 'item(S); desc(item_kind(static));'

static S: i32 = 123_u8 as i32;

static S: i32 = 123_u8 as i32;

const C: u32 = 0;

const C: u32 = 0;

S itself is a static, but contains no additional statics inside of it, and desc does not consider S itself when looking for item_kind(static) descendants.

filter(f) checks each currently selected node against the filter f, and replaces the current selection with the set of matching nodes. Equivalently, filter(f) removes from the current selection any nodes that don't match f.

Most uses of the filter operation can be replaced by passing a more appropriate filter expression to desc or child, so the examples in this section are somewhat contrived. (filter can still be useful in combination with marked, described below, or in more complex select scripts.)

Here is a slightly roundabout way to select all items named f. First, we select all items:

select target 'crate; desc(kind(item));'

fn f() {}

▶fn f() {}◀

fn g() {}

▶fn g() {}◀

mod m {

▶mod m {

    fn f() {}

    ▶fn f() {}◀

}

}◀

Then, we use filter to keep only items named f:

clear_marks ;
select target 'crate; desc(kind(item)); filter(name("f"));'

▶fn f() {}◀

▶fn f() {}◀

▶fn g() {}◀

fn g() {}

▶mod m {

mod m {

    ▶fn f() {}◀

    ▶fn f() {}◀

}◀

}

With this command, only descendants of crate matching both filters kind(item) and name("f") are selected. (This could be written more simply as crate; desc(kind(item) && name("f"));.)

first replaces the current selection with a set containing only the first selected node. last does the same with the last selected node. "First" and "last" are determined by a postorder traversal of the AST, so sibling nodes are ordered as expected, and a parent node come "after" all of its children.

The first and last operations are most useful for finding places to insert new nodes (such as with the create_item command) while ignoring details such as the specific names or kinds of the nodes around the insertion point. For example, we can use last to easily select the last item in a module. First, we select all the module's items:

select target 'item(m); child(kind(item));'

mod m {

mod m {

    fn f() {}

    ▶fn f() {}◀

    static S: i32 = 0;

    ▶static S: i32 = 0;◀

    const C: i32 = 1;

    ▶const C: i32 = 1;◀

}

}

Then we use last to select only the last such child:

clear_marks ;
select target 'item(m); child(kind(item)); last;'

mod m {

mod m {

    ▶fn f() {}◀

    fn f() {}

    ▶static S: i32 = 0;◀

    static S: i32 = 0;

    ▶const C: i32 = 1;◀

    ▶const C: i32 = 1;◀

}

}

Now we could use create_item to insert a new item after the last existing one.

marked(l) adds all nodes marked with label l to the current selection. This is useful for more complex marking operations, since (together with the delete_marks command) it allows using temporary marks to manipulate multiple sets of nodes simultaneously.

For example, suppose we wish to select both the first and the last item in a module. Normally, this would require duplicating the select command, since both first and last replace the entire current selection with the single first or last item. This would be undesirable if the operations for setting up the initial set of items were fairly complex. But with marked, we can save the selection before running first and restore it afterward.

We begin by selecting all items in the module and saving that selection by marking it with the tmp_all_items label:

select tmp_all_items 'item(m); child(kind(item));'

mod m {

mod m {

    fn f() {}

    ▶fn f() {}◀

    static S: i32 = 0;

    ▶static S: i32 = 0;◀

    const C: i32 = 1;

    ▶const C: i32 = 1;◀

}

}

Next, we use marked to retrieve the tmp_all_items set and take the first item from it. This reduces the current selection to only a single item, but the tmp_all_items marks remain intact for later use.

select target 'marked(tmp_all_items); first;'

mod m {

mod m {

    ▶fn f() {}◀

    ▶fn f() {}◀

    ▶static S: i32 = 0;◀

    ▶static S: i32 = 0;◀

    ▶const C: i32 = 1;◀

    ▶const C: i32 = 1;◀

}

}

We do the same to mark the last item with target:

select target 'marked(tmp_all_items); last;'

mod m {

mod m {

    ▶fn f() {}◀

    ▶fn f() {}◀

    ▶static S: i32 = 0;◀

    ▶static S: i32 = 0;◀

    ▶const C: i32 = 1;◀

    ▶const C: i32 = 1;◀

}

}

Finally, we clean up, removing the tmp_all_items marks using the delete_marks command:

delete_marks tmp_all_items

mod m {

mod m {

    ▶fn f() {}◀

    ▶fn f() {}◀

    ▶static S: i32 = 0;◀

    static S: i32 = 0;

    ▶const C: i32 = 1;◀

    ▶const C: i32 = 1;◀

}

}

Now the only marks remaining are the target marks on the first and last items of the module, as we originally intended.

reset clears the set of marked nodes. This is only useful in combination with mark and unmark, as otherwise the operations before a reset have no effect.

These operations allow select scripts to manipulate marks directly, rather than relying solely on the automatic marking of selected nodes at the end of the script. mark(l) marks all nodes in the current selection with label l (immediately, rather than waiting until the select command is finished), and unmark(l) removes label l from all selected nodes.

mark, unmark, and reset can be used to effectively combine multiple select commands in a single script. Here's the "first and last" example from the marked section, using only a single select command:

select _dummy '
    item(m); child(kind(item)); mark(tmp_all_items); reset;
    marked(tmp_all_items); first; mark(target); reset;
    marked(tmp_all_items); last; mark(target); reset;
    marked(tmp_all_items); unmark(tmp_all_items); reset;
'

mod m {

mod m {

    fn f() {}

    ▶fn f() {}◀

    static S: i32 = 0;

    static S: i32 = 0;

    const C: i32 = 1;

    ▶const C: i32 = 1;◀

}

}

Note that we pass _dummy as the LABEL argument of select, since the desired target marks are applied using the mark operation, rather than relying on the implicit marking done by select.

unmark is also useful in combination with marked to interface with non-select mark manipulation commands. For example, suppose we want to mark all occurrences of 2 + 2 that are passed as arguments to a function f. One option is to do this using the mark_arg_uses command, with additional processing by select before and after. Here we start by marking the function f:

select target 'item(f);'

fn f(x: i32) {

▶fn f(x: i32) {

    // ...

    // ...

}

}◀

fn g(x: i32) {

fn g(x: i32) {

    // ...

    // ...

}

}

fn main() {

fn main() {

    f(1);

    f(1);

    f(2 + 2);

    f(2 + 2);

    g(2 + 2);

    g(2 + 2);

    let x = 2 + 2;

    let x = 2 + 2;

}

}

Next, we run mark_arg_uses to replace the mark on f with a mark on each argument expression passed to f:

mark_arg_uses 0 target

▶fn f(x: i32) {

fn f(x: i32) {

    // ...

    // ...

}◀

}

fn g(x: i32) {

fn g(x: i32) {

    // ...

    // ...

}

}

fn main() {

fn main() {

    f(1);

    f(▶1◀);

    f(2 + 2);

    f(▶2 + 2◀);

    g(2 + 2);

    g(2 + 2);

    let x = 2 + 2;

    let x = 2 + 2;

}

}

And finally, we use select again to mark only those arguments that match 2 + 2:

select target 'marked(target); unmark(target); filter(match_expr(2 + 2));'

fn f(x: i32) {

fn f(x: i32) {

    // ...

    // ...

}

}

fn g(x: i32) {

fn g(x: i32) {

    // ...

    // ...

}

}

fn main() {

fn main() {

    f(▶1◀);

    f(1);

    f(▶2 + 2◀);

    f(▶2 + 2◀);

    g(2 + 2);

    g(2 + 2);

    let x = 2 + 2;

    let x = 2 + 2;

}

}

Beginning the script with marked(target); unmark(target); copies the set of target-marked nodes into the current selection, then removes the existing marks. The remainder of the script can then operate as usual, manipulating only the current selection with no need to worry about additional marks being already present.

Filter expressions can be combined using the boolean operators &&, ||, and !. A node matches the filter f1 && f2 only if it matches f1 and also matches f2, and so on.

kind(k) matches AST nodes whose node kind is k. The supported node kinds are:

• item - a top-level item, as in struct Foo { ... } or fn foo() { ... }. Includes both items in modules and items defined inside functions or other blocks, but does not include "item-like" nodes inside traits, impls, or extern blocks.
• trait_item - an item inside a trait definition, such as a method or associated type declaration
• impl_item - an item inside an impl block, such as a method or associated type definition
• foreign_item - an item inside an extern block ("foreign module"), such as a C function or static declaration
• stmt
• expr
• pat - a pattern, including single-ident patterns like foo in let foo = ...;
• ty - a type annotation, such as Foo in let x: Foo = ...;
• arg - a function or method argument declaration
• field - a struct, enum variant, or union field declaration
• itemlike - matches nodes whose kind is any of item, trait_item, impl_item, or foreign_item
• any - matches any node

The node kind k can be used alone as shorthand for kind(k). For example, the operation desc(item); is the same as desc(kind(item));.

item_kind(k) matches itemlike AST nodes whose subkind is k. The itemlike subkinds are:

• extern_crate
• use
• static
• const
• fn
• mod
• foreign_mod
• global_asm
• ty - type alias definition, as in type Foo = Bar;
• existential - existential type definition, as in existential type Foo: Bar;. Note that existential types are currently an unstable language feature.
• enum
• struct
• union
• trait - ordinary trait Foo { ... } definition, including unsafe trait
• trait_alias - trait alias definition, as in trait Foo = Bar; Note that trait aliases are currently an unstable language feature.
• impl - including both trait and inherent impls
• mac - macro invocation. Note that select works on the macro-expanded AST, so macro invocations are never present under normal circumstances.
• macro_def - 2.0/decl_macro-style macro definition, as in macro foo(...) { ... }. Note that 2.0-style macro definitions are currently an unstable language feature.

Note that a single item_kind filter can match multiple distinct node kinds, as long as the subkind is correct. for example, item_kind(fn) will match fn items, method trait_items and impl_items, and fn declarations inside extern blocks (foreign_items). similarly, item_kind(ty) matches ordinary type alias definitions, associated type declarations (in traits) and definitions (in impls), and foreign type declarations inside extern blocks.

item_kind filters match only those nodes that also match kind(itemlike), as other node kinds have no itemlike subkind.

The itemlike subkind k can be used alone as shorthand for item_kind(k). For example, the operation desc(fn); is the same as desc(item_kind(fn));.

pub matches any item, impl item, or foreign item whose visibility is pub. It currently does not support struct fields, even though they can also be declared pub.

mut matches static mut items, static mut foreign item declarations, and mutable binding patterns such as the mut foo in let mut foo = ...;.

name(re) matches itemlikes, arguments, and fields whose name matches the regular expression re. For example, name("[fF].*") matches fn f() { ... } and struct Foo { ... }, but not trait Bar { ... }. It currently does not support general binding patterns, aside from those in function arguments.

path(p) matches itemlikes and enum variants whose absolute path is p.

path_prefix(n, p) is similar to path(p), but drops the last n segments of the node's path before comparing to p.

has_attr(a) matches itemlikes, exprs, and field declarations that have an attribute named a.

match_expr(e) uses rewrite_expr-style AST matching to compare exprs to e, and matches any node where AST matching succeeds. For example, match_expr(__e + 1) matches the expressions 1 + 1, x + 1, and f() + 1, but not 2 + 2.

match_pat, match_ty, and match_stmt are similar, but operate on pat, ty, and stmt nodes respectively.

marked(l) matches nodes that are marked with the label l.

any_child(f) matches nodes that have a child that matches f. all_child(f) matches nodes where all children of the node match f.

any_desc and all_desc are similar, but consider all descendants instead of only direct children.

In addition to select, c2rust refactor contains a number of other mark-manipulation commands. A few of these can be replicated with appropriate select scripts (though using the command is typically easier), but some are more complex.