robotfindskitten - C2Rust Manual

This section details the refactoring script used to transform the initial Rust translation of robotfindskitten, as generated by c2rust transpile, into a safe Rust program. We divide the refactoring process into several major steps:

ncurses macro cleanup: The ncurses library implements parts of its API using C preprocessor macros, and a few of those macros expand to relatively complex code. We replace these expanded macro bodies with calls to equivalent functions, which are easier to recognize and refactor.
String formatting: robotfindskitten calls several printf-style string-formatting functions. We replace these unsafe variable-argument function calls with safe wrappers using Rust's format family of macros. Aside from improving memory safety, this also allows the Rust compiler to more accurately typecheck the format arguments, which is helpful for later type-directed refactoring passes.
Static string constants: robotfindskitten has two global variables containing string constants, which are translated to Rust as static mut definitions containing C-style *const c_char pointers. We refactor to remove both sources of unsafety, replacing raw pointers with checked &'static str references and converting the mutable statics to immutable ones.
Heap allocations: robotfindskitten uses a heap allocated array to track the objects in the game world. This array is represented as a raw pointer, and the underlying storage is managed explicitly with malloc and free. We replace the array with a memory-safe collection type, avoiding unsafe FFI calls and preventing out-of-bounds memory accesses.
Using the pancurses library: Calling ncurses library functions directly through the Rust FFI requires unsafe code at every call site. We replace unsafe ncurses function calls with calls to the safe wrappers provided by the pancurses crate.
Moving global state to the stack: robotfindskitten uses mutable global variables to store the game state, which turn into unsafe static mut definitions in Rust. We collect all such variables into a single stack-allocated struct, which can be mutated without unsafety.
libc calls: We replace calls to miscellaneous libc functions, such as sleep and rand, with calls to safe Rust equivalents.
Function argument types: Two remaining functions in robotfindskitten take raw pointers as arguments. We change each function's signature to use only safe Rust types, and update their callers to match.
String conversion cleanup: Several of the previous refactoring passes insert conversions between Rust and C string types. In several places, these conversions form cycles, such as &str -> *const c_char -> &str, which are both redundant and a source of unsafe code. We remove such conversion cycles to avoid unnecessary raw pointer manipulation.
Final cleanup: At this point, we have removed all the unsafe code we can. Only a few cleanup steps remain, such as removing unused unsafe qualifiers and deleting unused extern "C" definitions. In the end, we are left with a correct Rust translation of robotfindskitten that contains only a single line of unsafe code.

robotfindskitten uses a variety of macros provided by the ncurses library. Since c2rust transpile runs the C preprocessor before translating to Rust, the expansions of those macros effectively get inlined in the Rust code at each call site. In many cases, this is harmless: for example, move(y, x) expands to wmove(stdscr, y, x), which is not much harder to refactor than the original. However, the attr_get and attrset macros are more complex: they expand to multiple lines of code involving several conditionals and complex expressions. In this step, we convert the expanded code into simple function calls, which are easier to manipulate in later refactoring passes.

Fortunately, the ncurses library provides functions implementing the same operations as the troublesome macros, and we can call those functions through Rust's FFI. We begin by providing Rust declarations for these foreign functions. For ease of reading, we put the new declarations just after the existing extern "C" block:

select target 'crate; child(foreign_mod); last;' ;
create_item
    '
        extern "C" {
            fn wattr_get(win: *mut WINDOW, attrs: *mut attr_t,
                pair: *mut libc::c_short, opts: *mut libc::c_void) -> libc::c_int;
            fn wattrset(win: *mut WINDOW, attrs: libc::c_int) -> libc::c_int;
        }
    '
    after ;

Diff #1

Now we can use rewrite_expr to find Rust code that comes from the expansions of the wattrset macro and replace it with calls to the wattrset function:

rewrite_expr
    '
        if !(__win as *const libc::c_void).is_null() {
            (*__win)._attrs = __attrs
        } else {
        }
    '
    'wattrset(__win, __attrs as libc::c_int)' ;

Diff #2

The __win and __attrs metavariables in the pattern correspond to the arguments of the original C macro, and are used in the replacement to construct the equivalent Rust function call.

Next, we do the same thing for the more complicated wattr_get macro:

rewrite_expr
    '
        if !(__win as *const libc::c_void).is_null() {
            if !(&mut __attrs as *mut attr_t as *const libc::c_void).is_null() {
                __attrs = (*__win)._attrs
            } else {
            };
            if !(&mut __pair as *mut libc::c_short as *const libc::c_void).is_null() {
                __pair = (((*__win)._attrs as libc::c_ulong
                    & ((1u32 << 8i32).wrapping_sub(1u32) << 0i32 + 8i32) as libc::c_ulong)
                    >> 8i32) as libc::c_int as libc::c_short
            } else {
            };
        } else {
        }
    '
    'wattr_get(__win, &mut __attrs, &mut __pair, ::std::ptr::null_mut())' ;

Finally, we are done with this bit of cleanup, so we write the changes to disk before continuing on:

commit ;

Diff #4

robotfindskitten calls several printf-style variable-argument functions to perform string formatting. Since variable-argument function calls are considered unsafe in Rust, we must replace these with Rust-style string formatting using format! and related macros. Specifically, for each string formatting function such as printf, we will create a safe wrapper fmt_printf that takes a Rust fmt::Arguments object, and replace printf(...) calls with fmt_printf(format_args!(...)). This approach isolates all the unsafety into the fmt_printf wrapper, where it can be eliminated by later passes.

The replacement itself happens in two steps. First, we convert printf calls from printf(<C format args...>) to printf(format_args!(<Rust format args...>)). Note that the code does not typecheck in this intermediate state: C's printf function cannot accept the std::fmt::Arguments produced by the format_args! macro. The second step then replaces the printf call with a call to the fmt_printf wrapper, which does accept std::fmt::Arguments.

We run a few commands to mark the nodes involved in string formatting, before finally running the convert_format_args command to perform the actual transformation.

First, we use select and mark_arg_uses to mark the first argument of every printf call as targets:

select target 'item(printf);' ;
mark_arg_uses 0 target ;

Diff #5

convert_format_args will treat the target argument at each call site as a printf-style format string, and will treat all later arguments as format args.

Next, we mark the format string literal with fmt_str, which tells convert_format_args the exact string literal it should use as the format string. This usually is not the same as the target argument, since c2rust-transpile inserts several casts to turn a Rust string literal into a *const libc::c_char.

select fmt_str 'marked(target); desc(expr && !match_expr(__e as __t));' ;

Diff #6

With both target and fmt_str marks in place, we can apply the actual transformation:

convert_format_args ;

Diff #7

Finally, we clean up from this step by clearing all the marks.

clear_marks ;

commit would also clear the marks, but we don't want to commit these changes until we've fixed the type errors introduced in this step.

As a reminder, we currently have code that looks like this:

printf(format_args!("Hello, {}!\n", "world"))

printf itself can't accept the std::fmt::Arguments returned by format_args!, so we will define a wrapper that does accept std::fmt::Arguments and then rewrite these printf calls to call the wrapper instead.

First, we insert the wrapper:

select target 'crate; child(foreign_mod); last;' ;
create_item
    '
        fn fmt_printf(args: ::std::fmt::Arguments) -> libc::c_int {
            print!("{}", args);
            0
        }
    '
    after ;

Diff #9

Since Rust provides a print! macro with similar functionality to printf, our "wrapper" actually just calls print! directly, avoiding the string conversions necessary to call the actual C printf. (See the next subsection for an example of a "real" wrapper function.)

With the wrapper in place, we can now update the call sites:

rewrite_expr 'printf' 'fmt_printf' ;

Diff #10

Now that we've finished this step and the crate typechecks again, we can safely commit the changes:

commit ;

Diff #11

Aside from printf, robotfindskitten also uses the ncurses printw and mvprintw string-formatting functions. The refactoring script for printw is similar to the previous two steps combined:

select target 'item(printw);' ;
mark_arg_uses 0 target ;
select fmt_str 'marked(target); desc(expr && !match_expr(__e as __t));' ;

convert_format_args ;

clear_marks ;

select target 'crate; child(foreign_mod); last;' ;
create_item
    '
        fn fmt_printw(args: ::std::fmt::Arguments) -> libc::c_int {
            unsafe {
                ::printw(b"%s\0" as *const u8 as *const libc::c_char,
                         ::std::ffi::CString::new(format!("{}", args))
                             .unwrap().as_ptr())
            }
        }
    '
    after ;
rewrite_expr 'printw' 'fmt_printw' ;
commit ;

Diff #12

Aside from replacing the name printf with printw, the other notable difference from the printf script is the body of fmt_printw. There is no convenient replacement for printw in the Rust standard library, so instead we call the original printw function, passing in the result of Rust string formatting (converted to a C string) as an argument.

The mvprintw replacement is also similar, just with a few extra arguments:

select target 'item(mvprintw);' ;
mark_arg_uses 2 target ;
select fmt_str 'marked(target); desc(expr && !match_expr(__e as __t));' ;

convert_format_args ;

clear_marks ;

select target 'crate; child(foreign_mod); last;' ;
create_item
    '
        fn fmt_mvprintw(y: libc::c_int, x: libc::c_int,
                        args: ::std::fmt::Arguments) -> libc::c_int {
            unsafe {
                ::mvprintw(y, x, b"%s\0" as *const u8 as *const libc::c_char,
                         ::std::ffi::CString::new(format!("{}", args))
                             .unwrap().as_ptr())
            }
        }
    '
    after ;
rewrite_expr 'mvprintw' 'fmt_mvprintw' ;
commit ;

Diff #13

robotfindskitten defines a static string constant, ver, to store the game's version. Using ver is currently unsafe, first because its Rust type is a raw pointer (*mut c_char), and second because it's mutable. To make ver usage safe, we first change its type to &'static str (and fix up the resulting type errors), and then we change it from a static mut to an ordinary immutable static. Note that we must change the type first because Rust does not allow raw pointers to be stored in safe (non-mut) statics.

We change the type using rewrite_ty:

select target 'item(ver); child(ty);' ;
rewrite_ty 'marked!(*mut libc::c_char)' "&'static str" ;
delete_marks target ;

Diff #14

The combination of select and the marked! matching form ensures that only ver's type annotation is modified. We delete the mark afterward, since it's no longer needed.

Simply replacing *mut c_char with &str introduces type errors throughout the crate. The initializer for ver still has type *mut c_char, and all uses of ver are still expecting a *mut c_char.

Fixing the ver initializer is straightforward: we simply remove all the casts, then convert the binary string (&[u8]) literal to an ordinary string literal. For the casts, we mark all cast expressions in ver's definition, then replace each one with its subexpression:

select target 'item(ver); desc(match_expr(__e as __t));' ;
rewrite_expr 'marked!(__e as __t)' '__e' ;
delete_marks target ;

Diff #15

Only the binary string literal remains, so we mark it and change it to an ordinary str:

select target 'item(ver); child(expr);' ;
bytestr_to_str ;
delete_marks target ;

Diff #16

ver's initializer is now well-typed, but its uses are still expecting a *mut c_char instead of a &str. To fix these up, we use the type_fix_rules command, which rewrites expressions anywhere a type error occurs:

type_fix_rules '*, &str, *const __t => __old.as_ptr()' ;

Diff #17

Here we run type_fix_rules with only one rule: in any position (*), if an expression has type &str but is expected to have a raw pointer type (*const __t), then wrap the original expression in a call to .as_ptr(). This turns out to be enough to fix all the errors at uses of ver.

Now that all type errors have been corrected, we can finish our refactoring of ver. We make it immutable, then commit the changes.

select target 'item(ver);' ;
set_mutability imm ;

commit ;

Diff #18

Static string array - `messages`

Aside from ver, robotfindskitten contains a static array of strings, called messages. Like ver, accessing messages is unsafe because each element is a raw *mut c_char pointer and because messages itself is a static mut.

We rewrite the type and initializer of messages using the same strategy as for ver:

select target 'item(messages); child(ty); desc(ty);' ;
rewrite_ty 'marked!(*mut libc::c_char)' "&'static str" ;
delete_marks target ;
select target 'item(messages); child(expr); desc(expr);' ;
rewrite_expr 'marked!(__e as __t)' '__e' ;
bytestr_to_str ;
delete_marks target ;

Diff #19

We use type_fix_rules to fix up the uses of messages, as we did for ver:

type_fix_rules
    '*, &str, *const __t => __old.as_ptr()'
    '*, &str, *mut __t => __old.as_ptr() as *mut __t' ;

Diff #20

Here we needed a second rule for *mut pointers, similar to the one for *const, because robotfindskitten mistakenly declares messages as an array of char* instead of const char*.

With all type errors fixed, we can make messages immutable and commit the changes:

select target 'item(messages);' ;
set_mutability imm ;

commit ;

Diff #21

The screen variable stores a heap-allocated two-dimensional array, represented in C as an int**. In Rust, this becomes *mut *mut c_int, which is unsafe to access. We replace it with CArray<CArray<c_int>>, where CArray is a memory-safe collection type provided by the c2rust_runtime library. CArray is convenient for this purpose because it supports C-style initialization and access patterns (including pointer arithmetic) while still guaranteeing memory safety.

We actually perform the conversion from *mut to CArray in two steps. First, we replace *mut with the simpler CBlockPtr type, also defined in c2rust_runtime. CBlockPtr provides some limited bounds checking, but otherwise functions much like a raw pointer. It serves as a useful intermediate step, letting us fix up the differences between the raw-pointer and CArray APIs in two stages instead of attempting to do it all at once. Once screen has been fully converted to CBlockPtr<CBlockPtr<c_int>>, we finish the conversion to CArray in the second step.

As a preliminary, we need to add an import of the c2rust_runtime library:

select target 'crate;' ;
create_item 'extern crate c2rust_runtime;' inside ;

Diff #22

Now we can proceed with the actual refactoring.

We further break down the transition from *mut *mut c_int to CBlockPtr<CBlockPtr<c_int>> into two steps, first converting the inner pointer (leaving the overall type as *mut CBlockPtr<c_int>) and then the outer. We change the type annotation first, as we did for var and messages:

select target 'item(screen); child(ty);' ;
rewrite_ty 'marked!(*mut *mut __t)'
    '*mut ::c2rust_runtime::CBlockPtr<__t>' ;

Diff #23

This introduces type errors, letting us easily find (and fix) related expressions using type_fix_rules:

type_fix_rules
    'rval, *mut __t, ::c2rust_runtime::CBlockPtr<__u> =>
        unsafe { ::c2rust_runtime::CBlockPtr::from_ptr(__old) }'
    'rval, *mut __t, *mut __u => __old as *mut __u'
    ;

Diff #24

The first rule provided here handles the later part of screen's initialization, where the program allocates a *mut c_int array (now CBlockPtr<c_int>) for each row of the screen. The second rule handles the earlier part, where it allocates the top-level *mut *mut c_int (now *mut CBlockPtr<c_int>). Both allocations now need a cast, since the type of the rows has changed.

One category of type errors remains: the initialization code tries to dereference the result of offsetting the array pointer, which is not possible directly with the CBlockPtr API. We add the necessary method call using rewrite_expr:

rewrite_expr
    '*typed!(__e, ::c2rust_runtime::block_ptr::CBlockOffset<__t>)'
    '*__e.as_mut()' ;

Diff #25

Here, the pattern filters for dereferences of CBlockOffset expressions, which result from calling offset on a CBlockPtr, and adds a call to as_mut() before the dereference.

The conversion of screen to *mut CBlockPtr<c_int> is now complete. The conversion to CBlockPtr<CBlockPtr<c_int>> uses a similar refactoring script:

select target 'crate; item(screen); child(ty);' ;
rewrite_ty 'marked!(*mut __t)'
    '::c2rust_runtime::CBlockPtr<__t>' ;
type_fix_rules
    'rval, *mut __t, ::c2rust_runtime::CBlockPtr<__u> =>
        unsafe { ::c2rust_runtime::CBlockPtr::from_ptr(__old) }'
    'rval, *mut __t, *mut __u => __old as *mut __u'
    ;
rewrite_expr
    '*typed!(__e, ::c2rust_runtime::block_ptr::CBlockOffset<__t>)'
    '*__e.as_mut()' ;

Diff #26

The only change is in the rewrite_ty step.

There's one last bit of cleanup to perform: now that screen has the desired CBlockPtr<CBlockPtr<c_int>> type, we can rewrite the allocations that initialize it. At this point the allocations use the unsafe malloc function followed by the unsafe CBlockPtr::from_ptr, but we can change that to use the safe CBlockPtr::alloc method instead:

rewrite_expr 'malloc(__e) as *mut __t as *mut __u' 'malloc(__e) as *mut __u' ;
rewrite_expr
    '::c2rust_runtime::CBlockPtr::from_ptr(malloc(__e) as *mut __t)'
    '::c2rust_runtime::CBlockPtr::alloc(
        __e as usize / ::std::mem::size_of::<__t>())'
    ;

Diff #27

This doesn't remove the unsafe blocks wrapping each allocation - we leave those until the end of our refactoring, when we remove unnecessary unsafe blocks throughout the entire crate at once.

At this point, the refactoring of screen to is done, and we can commit the changes:

commit ;

Diff #28

The CArray and CBlockPtr APIs are deliberately quite similar, which makes this part of the screen refactoring fairly straightforward.

First, we replace all uses of CBlockPtr with CArray, both in types and in function calls:

rewrite_ty '::c2rust_runtime::CBlockPtr<__t>' '::c2rust_runtime::CArray<__t>' ;
rewrite_expr
    '::c2rust_runtime::CBlockPtr::from_ptr'
    '::c2rust_runtime::CArray::from_ptr' ;
rewrite_expr
    '::c2rust_runtime::CBlockPtr::alloc'
    '::c2rust_runtime::CArray::alloc' ;

Diff #29

Next, we fix up calls to offset. Unlike CBlockPtr (and raw pointers in general), CArray distinguishes between mutable and immutable offset pointers. We handle this by simply replacing all offset calls with offset_mut:

rewrite_expr
    'typed!(__e, ::c2rust_runtime::CArray<__t>).offset(__f)'
    '__e.offset_mut(__f)' ;

Diff #30

This works fine for robotfindskitten, though in other codebases it may be necessary to properly distinguish mutable and immutable uses of offset.

With this change, the code typechecks with screens new memory-safe type, so we could stop here. However, unlike CBlockPtr, CArray supports array indexing - ptr[i] - in place of the convoluted *arr.offset(i).as_mut() syntax. So we perform a simple rewrite to make the code a little easier to read:

rewrite_expr
    'typed!(__e, ::c2rust_runtime::CArray<__t>).offset_mut(__f).as_mut()'
    '&mut __e[__f as usize]' ;
rewrite_expr '*&mut __e' '__e' ;

Diff #31

Finally, we remove unsafety from screen's static initializer. It currently calls CArray::from_ptr(0 as *mut _), which is unsafe because CArray::from_ptr requires its pointer argument to must satisfy certain properties. But CArray also provides a safe method specifically for initializing a CArray to null, which we can use instead:

rewrite_expr
    '::c2rust_runtime::CArray::from_ptr(cast!(0))'
    '::c2rust_runtime::CArray::empty()' ;

Diff #32

This completes the refactoring of screen, as all raw pointer manipulations have been replaced with safe CArray method calls. The only remaining unsafety arises from the fact that screen is a static mut, which we address in a later refactoring step.

commit ;

The pancurses library provides safe wrappers around ncurses APIs. Since the pancurses and ncurses APIs are so similar, we can automatically convert the unsafe ncurses FFI calls in robotfindskitten to safe pancurses calls, avoiding the need to maintain safe wrappers in robotfindskitten itself.

There are two preliminary steps before we do the actual conversion. First, we must import the pancurses library:

select target 'crate;' ;
create_item 'extern crate pancurses;' inside ;

Diff #33

And second, we must create a global variable to store the main pancurses Window:

select target 'crate;' ;
create_item 'static mut win: Option<::pancurses::Window> = None;' inside ;

Diff #34

pancurses doesn't have an equivalent of the global stdscr window that ncurses provides. Instead, the pancurses initialization function creates an initial Window object that must be passed around to each function that updates the display. We store that initial Window in the global win variable so that it's accessible everywhere that stdscr is used.

Note that making win a static mut makes it unsafe to access. However, a later refactoring pass will gather up all static muts, including win, and collect them into a stack-allocated struct, at which point accessing win will no longer be unsafe.

We convert ncurses library calls to pancurses ones in a few stages.

First, for functions that don't require a window object, we simply replace each ncurses function with its equivalent in the pancurses library:

rewrite_expr 'nonl' '::pancurses::nonl' ;
rewrite_expr 'noecho' '::pancurses::noecho' ;
rewrite_expr 'cbreak' '::pancurses::cbreak' ;
rewrite_expr 'has_colors' '::pancurses::has_colors' ;
rewrite_expr 'start_color' '::pancurses::start_color' ;
rewrite_expr 'endwin' '::pancurses::endwin' ;
rewrite_expr 'init_pair' '::pancurses::init_pair' ;

Diff #35

Next, functions taking a window are replaced with method calls on the static win variable we defined earlier:

rewrite_expr 'wrefresh(stdscr)' 'win.refresh()' ;
rewrite_expr 'wrefresh(curscr)' 'win.refresh()' ;
rewrite_expr 'keypad(stdscr, __bf)' 'win.keypad(__bf)' ;
rewrite_expr 'wmove(stdscr, __my, __mx)' 'win.mv(__my, __mx)' ;
rewrite_expr 'wclear(stdscr)' 'win.clear()' ;
rewrite_expr 'wclrtoeol(stdscr)' 'win.clrtoeol()' ;
rewrite_expr 'waddch(stdscr, __ch)' 'win.addch(__ch)' ;

rewrite_expr
    'wattr_get(stdscr, __attrs, __pair, __e)'
    '{
        let tmp = win.attrget();
        *__attrs = tmp.0;
        *__pair = tmp.1;
        0
    }' ;
rewrite_expr
    'wattrset(stdscr, __attrs)'
    'win.attrset(__attrs as ::pancurses::chtype)' ;

Diff #36

For simplicity, we write win.f(...) in the rewrite_expr replacement arguments, even though win is actually an Option<Window>, not a Window. Later, we replace win with win.as_ref().unwrap() throughout the crate to correct the resulting type errors.

We next replace some ncurses global variables with calls to corresponding pancurses functions:

rewrite_expr 'LINES' 'win.get_max_y()' ;
rewrite_expr 'COLS' 'win.get_max_x()' ;

Diff #37

Finally, we handle a few special cases.

waddnstr takes a string argument, which in general could be any *const c_char. However, robotfindskitten calls it only on string literals, which lets us perform a more specialized rewrite that avoids unsafe C string conversions:

rewrite_expr
    'waddnstr(stdscr, __str as *const u8 as *const libc::c_char, __n)'
    "win.addnstr(::std::str::from_utf8(__str).unwrap().trim_end_matches('\0'),
                 __n as usize)" ;

Diff #38

intrflush has no pancurses equivalent, so we replace it with a no-op of the same type:

rewrite_expr 'intrflush(__e, __f)' '0' ;

Diff #39

That covers all of the "ordinary" ncurses functions used in robotfindskitten. The remaining subsections cover the more complex cases.

We previously replaced calls to the ncurses printw and mvprintw string-formatting functions with code using Rust's safe string formatting macros. This removes unsafety from the call site, but uses wrapper functions (fmt_printw and fmt_mvprintw) that call unsafe code internally. But now that we are using the pancurses library, we can replace those wrappers with safer equivalents.

select target 'item(fmt_printw);' ;
create_item '
    fn fmt_printw(args: ::std::fmt::Arguments) -> libc::c_int {
        unsafe {
            win.printw(&format!("{}", args))
        }
    }
' after ;
delete_items ;
clear_marks ;

select target 'item(fmt_mvprintw);' ;
create_item '
    fn fmt_mvprintw(y: libc::c_int, x: libc::c_int,
                    args: ::std::fmt::Arguments) -> libc::c_int {
        unsafe {
            win.mvprintw(y, x, &format!("{}", args))
        }
    }
' after ;
delete_items ;
clear_marks ;

Diff #40

The wrappers still use unsafe code to access win, a static mut, but no longer make FFI calls or manipulate raw C strings. When we later remove all static muts from the program, these functions will become entirely safe.

Adapting ncurses-based input handling to use pancurses requires some extra care. The pancurses getch function returns a Rust enum, while the ncurses version simply returns an integer. robotfindskitten matches those integers against various ncurses keycode constants, which, after macro expansion, become integer literals in the Rust code.

The more idiomatic approach would be to replace each integer literal with the matching pancurses::Input enum variant when switching from ncurses getch to the pancurses version. However, we instead take the easier approach of converting pancurses::Input values back to ncurses integer keycodes, so the existing robotfindskitten input handling code can remain unchanged.

First, we inject a translation function from pancurses to ncurses keycodes:

select target 'item(initialize_ncurses);' ;
create_item '
    fn encode_input(inp: Option<::pancurses::Input>) -> libc::c_int {
        use ::pancurses::Input::*;
        let inp = match inp {
            Some(x) => x,
            None => return -1,
        };
        match inp {
            // TODO: unicode inputs in the range 256 .. 512 can
            // collide with ncurses special keycodes
            Character(c) => c as u32 as libc::c_int,
            Unknown(i) => i,
            special => {
                let idx = ::pancurses::SPECIAL_KEY_CODES.iter()
                    .position(|&k| k == special).unwrap();
                let code = idx as i32 + ::pancurses::KEY_OFFSET;
                if code > ::pancurses::KEY_F15 {
                    code + 48
                } else {
                    code
                }
            },
        }
    }
' after ;

Diff #41

Then, we translate ncurses wgetch calls to use the pancurses getch method, wrapping the result in encode_input to keep the results unchanged.

rewrite_expr 'wgetch(stdscr)' '::encode_input(win.getch())' ;

Diff #42

As mentioned previously, we use win to obtain the current window object throughout the ncurses refactoring process, even though win is actually an Option<Window>, not a Window. Now that we are done with all the rewrites, we can update thote uses to access the Window properly:

rewrite_expr 'win' 'win.as_ref().unwrap()' ;

Diff #43

The final step is to initialize win. This corresponds to the call to the ncurses initscr initialization function:

rewrite_expr 'initscr()' 'win = Some(::pancurses::initscr())' ;

Diff #44

We save this for last only so that the win to win.as_ref().unwrap() rewrite doesn't produce an erroneous assignment win.as_ref().unwrap() = ....

At this point, we are done with the current refactoring step: robotfindskitten has been fully adapted to use the safe pancurses API in place of raw ncurses FFI calls.

commit

Diff #45

robotfindskitten uses global variables - static muts in Rust - to store the game state. Accessing these globals is unsafe, due to the difficulty of preventing simultaneous borrowing and mutation. In this refactoring step, we move the global state onto the stack and pass it by reference to every function that needs it, which allows the borrow checker to analyze its usage and ensure safety.

Most of the work in this step is handled by the static_to_local_ref refactoring command. This command identifies all functions that use a given static, and modifies those functions to access the global through a reference (passed as an argument to the function) instead of accessing it directly. (See the static_to_local_ref command documentation for examples.)

However, running static_to_local_ref separately on each of robotfindskitten's seven global variables would add up to seven new arguments to many of robotfindskitten's functions, making their signatures difficult to read. Instead, we proceed in two steps. First, we gather up all the global variables into a single global struct. Then, we run static_to_local_ref on just the struct, achieving safety while adding only a single new argument to each affected function.

We collect the statics into a struct using static_collect_to_struct:

select target 'crate; child(static && mut);' ;
static_collect_to_struct State S

Diff #46

Then we run static_to_local_ref to pass a reference to the new State object everywhere it is used:

select target 'crate; child(static && name("S"));' ;
select user 'crate; desc(fn && !name("main|main_0"));' ;
static_to_local_ref ;

Diff #47

 )]
 #![feature(const_raw_ptr_to_usize_cast, extern_types, libc)]
 extern crate libc;
-extern "C" {
+▶extern "C" {
     pub type ldat;
     #[no_mangle]
     fn printf(_: *const libc::c_char, ...) -> libc::c_int;
     #[no_mangle]
-    fn cbreak() -> libc::c_int;
+    fn cbreak() -> libc::c_int;◀
-    #[no_mangle]
+▶   #[no_mangle]
     fn time(__timer: *mut time_t) -> time_t;
     #[no_mangle]
     fn sleep(__seconds: libc::c_uint) -> libc::c_uint;
-}
+}◀
+▶extern "C" {
+    fn wattr_get(
+        win: *mut WINDOW,
+        attrs: *mut attr_t,
+        pair: *mut libc::c_short,
+        opts: *mut libc::c_void,
+    ) -> libc::c_int;
+    fn wattrset(win: *mut WINDOW, attrs: libc::c_int) -> libc::c_int;
+}◀
 pub type __time_t = libc::c_long;
 pub type chtype = libc::c_ulong;
+#[repr(C)]
 #[derive(Copy, Clone)]
-#[repr(C)]
 pub struct _win_st {
     pub _cury: libc::c_short,
     pub _curx: libc::c_short,
     pub _maxy: libc::c_short,
     pub _maxx: libc::c_short,
     pub _pary: libc::c_int,
     pub _parent: *mut WINDOW,
     pub _pad: pdat,
     pub _yoffset: libc::c_short,
 }
+#[repr(C)]
 #[derive(Copy, Clone)]
-#[repr(C)]
 pub struct pdat {
     pub _pad_y: libc::c_short,
     pub _pad_x: libc::c_short,
     pub _pad_top: libc::c_short,
     pub _pad_left: libc::c_short,
 /*Screen dimensions.*/
 /*Macros for generating numbers in different ranges*/
 /*Row constants for the animation*/
 /*This struct contains all the information we need to display an object
 on the screen*/
+#[repr(C)]
 #[derive(Copy, Clone)]
-#[repr(C)]
 pub struct screen_object {
     pub x: libc::c_int,
     pub y: libc::c_int,
     pub color: libc::c_int,
     pub bold: bool,

         new |= 1u64 << 14i32 + 8i32
     }
     if o.bold {
         new |= 1u64 << 13i32 + 8i32
     }
-    if !(stdscr as *const libc::c_void).is_null() {
+    wattrset(stdscr, new as libc::c_int);
-        (*stdscr)._attrs = new
-    } else {
-    };
     if in_place {
         printw(
             b"%c\x00" as *const u8 as *const libc::c_char,
             o.character as libc::c_int,
         );
             b"%c\x00" as *const u8 as *const libc::c_char,
             o.character as libc::c_int,
         );
         wmove(stdscr, o.y, o.x);
     }
-    if !(stdscr as *const libc::c_void).is_null() {
+    wattrset(stdscr, old as libc::c_int);
-        (*stdscr)._attrs = old
-    } else {
-    };
 }
 #[no_mangle]
 pub unsafe extern "C" fn instructions() {
     let mut dummy: libc::c_char = 0;
     mvprintw(

src/robotfindskitten.rs
8	)]	8	)]
9	#![feature(const_raw_ptr_to_usize_cast, extern_types, libc)]	9	#![feature(const_raw_ptr_to_usize_cast, extern_types, libc)]
10	extern crate libc;	10	extern crate libc;
11	▶extern "C" {	11	extern "C" {
12	pub type ldat;	12	pub type ldat;
13	#[no_mangle]	13	#[no_mangle]
14	fn printf(_: *const libc::c_char, ...) -> libc::c_int;	14	fn printf(_: *const libc::c_char, ...) -> libc::c_int;
15	#[no_mangle]	15	#[no_mangle]
16	fn cbreak() -> libc::c_int;◀	16	fn cbreak() -> libc::c_int;

79	▶ #[no_mangle]	79	#[no_mangle]
80	fn sleep(__seconds: libc::c_uint) -> libc::c_uint;	80	fn sleep(__seconds: libc::c_uint) -> libc::c_uint;
81	}◀	81	}
82	▶extern "C" {	82	extern "C" {
83	fn wattr_get(	83	fn wattr_get(
84	win: *mut WINDOW,	84	win: *mut WINDOW,
85	attrs: *mut attr_t,	85	attrs: *mut attr_t,
86	pair: *mut libc::c_short,	86	pair: *mut libc::c_short,
87	opts: *mut libc::c_void,◀	87	opts: *mut libc::c_void,

src/robotfindskitten.rs
977	unsafe extern "C" fn finish(mut sig: libc::c_int) {	977	unsafe extern "C" fn finish(mut sig: libc::c_int) {
978	endwin();	978	endwin();
979	printf(	979	printf(
980	b"%c%c%c\x00" as const u8 as const libc::c_char,	980	▶b"%c%c%c\x00" as const u8 as const libc::c_char◀,
981	27i32,	981	27i32,
982	'(' as i32,	982	'(' as i32,
983	'B' as i32,	983	'B' as i32,
984	);	984	);
985	exit(0i32);	985	exit(0i32);

1419	.wrapping_div(::std::mem::size_of::<*mut libc::c_char>() as libc::c_ulong)	1419	.wrapping_div(::std::mem::size_of::<*mut libc::c_char>() as libc::c_ulong)
1420	{	1420	{
1421	printf(	1421	printf(
1422	b"Run-time parameter must be between 0 and %d.\n\x00" as *const u8	1422	▶b"Run-time parameter must be between 0 and %d.\n\x00" as *const u8◀
1423	as *const libc::c_char,	1423	as *const libc::c_char,
1424	(::std::mem::size_of::<[*mut libc::c_char; 406]>() as libc::c_ulong)	1424	(::std::mem::size_of::<[*mut libc::c_char; 406]>() as libc::c_ulong)
1425	.wrapping_div(::std::mem::size_of::<*mut libc::c_char>() as libc::c_ulong),	1425	.wrapping_div(::std::mem::size_of::<*mut libc::c_char>() as libc::c_ulong),
1426	);	1426	);
1427	exit(0i32);	1427	exit(0i32);

1429	}	1429	}
1430	srand(time(0 as *mut time_t) as libc::c_uint);	1430	srand(time(0 as *mut time_t) as libc::c_uint);
1431	printf(	1431	printf(
1432	b"%c%c%c\x00" as const u8 as const libc::c_char,	1432	▶b"%c%c%c\x00" as const u8 as const libc::c_char◀,
1433	27i32,	1433	27i32,
1434	'(' as i32,	1434	'(' as i32,
1435	'U' as i32,	1435	'U' as i32,
1436	);	1436	);
1437	initialize_ncurses();	1437	initialize_ncurses();

src/robotfindskitten.rs
977	unsafe extern "C" fn finish(mut sig: libc::c_int) {	977	unsafe extern "C" fn finish(mut sig: libc::c_int) {
978	endwin();	978	endwin();
979	printf(	979	printf(
980	▶b"%c%c%c\x00" as const u8 as const libc::c_char◀,	980	▶▶b"%c%c%c\x00"◀ as const u8 as const libc::c_char◀,
981	27i32,	981	27i32,
982	'(' as i32,	982	'(' as i32,
983	'B' as i32,	983	'B' as i32,
984	);	984	);
985	exit(0i32);	985	exit(0i32);

1419	.wrapping_div(::std::mem::size_of::<*mut libc::c_char>() as libc::c_ulong)	1419	.wrapping_div(::std::mem::size_of::<*mut libc::c_char>() as libc::c_ulong)
1420	{	1420	{
1421	printf(	1421	printf(
1422	▶b"Run-time parameter must be between 0 and %d.\n\x00" as *const u8◀	1422	▶▶b"Run-time parameter must be between 0 and %d.\n\x00"◀ as *const u8◀
1423	as *const libc::c_char,	1423	as *const libc::c_char,
1424	(::std::mem::size_of::<[*mut libc::c_char; 406]>() as libc::c_ulong)	1424	(::std::mem::size_of::<[*mut libc::c_char; 406]>() as libc::c_ulong)
1425	.wrapping_div(::std::mem::size_of::<*mut libc::c_char>() as libc::c_ulong),	1425	.wrapping_div(::std::mem::size_of::<*mut libc::c_char>() as libc::c_ulong),
1426	);	1426	);
1427	exit(0i32);	1427	exit(0i32);

1429	}	1429	}
1430	srand(time(0 as *mut time_t) as libc::c_uint);	1430	srand(time(0 as *mut time_t) as libc::c_uint);
1431	printf(	1431	printf(
1432	▶b"%c%c%c\x00" as const u8 as const libc::c_char◀,	1432	▶▶b"%c%c%c\x00"◀ as const u8 as const libc::c_char◀,
1433	27i32,	1433	27i32,
1434	'(' as i32,	1434	'(' as i32,
1435	'U' as i32,	1435	'U' as i32,
1436	);	1436	);
1437	initialize_ncurses();	1437	initialize_ncurses();

C2Rust Manual

Refactoring `robotfindskitten`

`ncurses` macro cleanup

String formatting

`printf` format argument conversion

Creating a `printf` wrapper

Other string formatting functions

Static string constant - `ver`

Fixing `ver`'s initializer

Fixing `ver`'s uses

Making `ver` immutable

Static string array - `messages`

Heap allocations

Converting to `CBlockPtr`

Converting to `CArray`

Using the `pancurses` library

General library calls

String formatting

Input handling

Final steps

Moving global state to the stack

src/robotfindskitten.rs
203	pub y: libc::c_int,	203	pub y: libc::c_int,
204	pub color: libc::c_int,	204	pub color: libc::c_int,
205	pub bold: bool,	205	pub bold: bool,
206	pub character: libc::c_char,	206	pub character: libc::c_char,
207	}	207	}
208	static mut ver: &'static str = b"1.7320508.406\x00";	208	static mut ver: &'static str = "1.7320508.406\u{0}";
209	#[inline]	209	#[inline]
210	unsafe extern "C" fn atoi(mut __nptr: *const libc::c_char) -> libc::c_int {	210	unsafe extern "C" fn atoi(mut __nptr: *const libc::c_char) -> libc::c_int {
211	return strtol(	211	return strtol(
212	__nptr,	212	__nptr,
213	0 as mut libc::c_void as mut *mut libc::c_char,	213	0 as mut libc::c_void as mut *mut libc::c_char,

src/robotfindskitten.rs
1178	let mut counter: libc::c_int = 0;	1178	let mut counter: libc::c_int = 0;
1179	fmt_mvprintw(	1179	fmt_mvprintw(
1180	0i32,	1180	0i32,
1181	0i32,	1181	0i32,
1182	format_args!("robotfindskitten v{:}\n\n", unsafe {	1182	format_args!("robotfindskitten v{:}\n\n", unsafe {
1183	::std::ffi::CStr::from_ptr(ver as *const libc::c_char)	1183	::std::ffi::CStr::from_ptr(ver.as_ptr() as *const libc::c_char)
1184	.to_str()	1184	.to_str()
1185	.unwrap()	1185	.unwrap()
1186	}),	1186	}),
1187	);	1187	);
1188	counter = 0i32;	1188	counter = 0i32;

1251	let mut dummy: libc::c_char = 0;	1251	let mut dummy: libc::c_char = 0;
1252	fmt_mvprintw(	1252	fmt_mvprintw(
1253	0i32,	1253	0i32,
1254	0i32,	1254	0i32,
1255	format_args!("robotfindskitten v{:}\n", unsafe {	1255	format_args!("robotfindskitten v{:}\n", unsafe {
1256	::std::ffi::CStr::from_ptr(ver as *const libc::c_char)	1256	::std::ffi::CStr::from_ptr(ver.as_ptr() as *const libc::c_char)
1257	.to_str()	1257	.to_str()
1258	.unwrap()	1258	.unwrap()
1259	}),	1259	}),
1260	);	1260	);
1261	fmt_printw(format_args!(	1261	fmt_printw(format_args!(

src/robotfindskitten.rs
203	pub y: libc::c_int,	203	pub y: libc::c_int,
204	pub color: libc::c_int,	204	pub color: libc::c_int,
205	pub bold: bool,	205	pub bold: bool,
206	pub character: libc::c_char,	206	pub character: libc::c_char,
207	}	207	}
208	static mut ver: &'static str = "1.7320508.406\u{0}";	208	static ver: &'static str = "1.7320508.406\u{0}";
209	#[inline]	209	#[inline]
210	unsafe extern "C" fn atoi(mut __nptr: *const libc::c_char) -> libc::c_int {	210	unsafe extern "C" fn atoi(mut __nptr: *const libc::c_char) -> libc::c_int {
211	return strtol(	211	return strtol(
212	__nptr,	212	__nptr,
213	0 as mut libc::c_void as mut *mut libc::c_char,	213	0 as mut libc::c_void as mut *mut libc::c_char,

src/robotfindskitten.rs
218	will happen.*/	218	will happen.*/
219	/*Also, take note that robotfindskitten.c and configure.in	219	/*Also, take note that robotfindskitten.c and configure.in
220	currently have the version number hardcoded into them, and they	220	currently have the version number hardcoded into them, and they
221	should reflect MESSAGES. */	221	should reflect MESSAGES. */
222	/* Watch out for fenceposts.*/	222	/* Watch out for fenceposts.*/
223	static mut messages: [&'static str; 406] = [	223	static messages: [&'static str; 406] = [
224	"\"I pity the fool who mistakes me for kitten!\", sez Mr. T.\u{0}",	224	"\"I pity the fool who mistakes me for kitten!\", sez Mr. T.\u{0}",
225	"That\'s just an old tin can.\u{0}",	225	"That\'s just an old tin can.\u{0}",
226	"It\'s an altar to the horse god.\u{0}",	226	"It\'s an altar to the horse god.\u{0}",
227	"A box of dancing mechanical pencils. They dance! They sing!\u{0}",	227	"A box of dancing mechanical pencils. They dance! They sing!\u{0}",
228	"It\'s an old Duke Ellington record.\u{0}",	228	"It\'s an old Duke Ellington record.\u{0}",

C2Rust Manual

Refactoring robotfindskitten

ncurses macro cleanup

String formatting

printf format argument conversion

Creating a printf wrapper

Other string formatting functions

Static string constant - ver

Fixing ver's initializer

Fixing ver's uses

Making ver immutable

Static string array - messages

Heap allocations

Converting to CBlockPtr

Converting to CArray

Using the pancurses library

General library calls

String formatting

Input handling

Final steps

Moving global state to the stack

Refactoring `robotfindskitten`

`ncurses` macro cleanup

`printf` format argument conversion

Creating a `printf` wrapper

Static string constant - `ver`

Fixing `ver`'s initializer

Fixing `ver`'s uses

Making `ver` immutable

Static string array - `messages`

Converting to `CBlockPtr`

Converting to `CArray`

Using the `pancurses` library