Touch Develop retirement postponed until June 22, 2019. Sign-in and access to cloud assets to be removed on May 23, 2018.Learn More..


move to library

The move to library refactoring in TouchDevelop allows you to easily identify and move elements from a script into an existing or new library.

Getting started

Start by selecting an action, global variable, or any other top-level element in a TouchDevelop script (some elements cannot be moved, as we’ll describe later). For example, in this script, select the action
private function
increment
()
 x :=  x + 1
end function
then click on first line to bring up its property pane. Click on the move to library button. You first will be asked to identify a target library to which you want to move the element. Do this by selecting an existing library referenced by the current script or creating a new library (most likely, you'll be creating a new library):

Compilable set of elements

Simply put, if your script S compiles successfully then a compilable subset E of elements from S is one that will compile successfully when moved to a separate script. This means that if E contains an action A from S, it also contains all actions B from S where A directly calls B. There are similar “closure” rules for all elements in the TouchDevelop language. Essentially if element A directly accesses element B, then B must be moved along with A in order for A to compile successfully (all elements transitively accessed from A must be moved). In our example, the action increment directly accesses the global variable x, so we are prompted to move x with increment:

Selecting other related elements to move

Once you have picked an element to move and approved moving the elements it transitively accesses, all these elements are marked as “move pending”. It’s likely that you’ll want to add other elements to the pending set. TouchDevelop gives you assistance in identifying likely candidates to move.
In our running example, we have added action increment and the global variable x to the ‘move pending’ set. Now, action decrement directly accesses x and no other program elements:
private function
decrement
()
 x :=  x - 1
end function
The action example calls both increment and decrement, as well as setting the global variable x, calling the init function, and posting x to the wall
private function
exxample
()
 x := 0
 init
 increment
 decrement
 x → post to wall
end function

Move to library (pending) Dialog

The dialog below shows that increment and x are pending to move. Additionally, it lists the elements that only directly access elements in the pending set (in this case, the action decrement) as well as elements that directly access some elements in the pending set and some elements outside the pending set (in this case, the action `example'):

Advance selected to pending

You can select more elements to move to the library by clicking on them (click again to deselect). Under each element A is a list of the elements that A transitively accesses. Those colored blue are either pending to move or are transitively accessed by an element you already have selected.
Once you have selected a number of elements, click the Advance selected to pending button to move these (and the elements they transitively access) to the pending set. The display will refresh and may now show you some new program elements to consider moving.

Make the move

Once you are satisfied with the set of elements you want to move, press the Make the move button to move these elements to the target script. This refactoring also will rewrite the actions that remain in the script in order to properly access the elements moved to the target script (see section below on libraries and abstraction). Below, we show the rewritten action example:
.
IMPORTANT: the effect of this move/rewriting is not undoable in the editor; you can, however, use the script history to revert back to an earlier version of your script - the best choice is to make sure to publish your script before you perform a major refactoring such as this.
TouchDevelop guarantees that if your original script had no errors, then the resulting two scripts should have no errors and their combined behavior should be the same as the original script. If you find an example, where this is not the case, please file a bug!

Discard pending

If you want to start over again identifying a target library and the set of elements to move, press the Discard pending button, which will discard your current progress and return you to the editor.

Exit to editor

Sometimes you'll want to return to the editor to examine code more closely. Press the Exit to editor button to do this - TouchDevelop will remember the target library pending to move set. You can return to the move to library dialog by using the move to library button (for example, on an element you've already selected to move). You can also select other elements to add to the pending set this way, as you did to get started.

Libraries, abstraction and field/property accessors

An interesting wrinkle to TouchDevelop is the strong abstraction facility provided by libraries. When you move a user-defined variable or type (like an object, table, or index) into a library, the data is hidden unless you create an action in the library to access that data. The 'make the move' process determines which data your script accesses from the library, creates accessor actions in the library to provide access to that data, and rewrites the remaining elements in your application to uses these accessor actions.

Moving more elements to a library

After you've move elements to a target library, you are free move more elements, including ones that reference the target library! The refactoring will take care of eliminating any library references. However, the refactoring will not eliminate any calls to accessor actions.

Limitations and known issues

  • Event actions cannot be moved into a library (also, they are being deprecated in favor of event handlers, which can call regular actions that can be moved to libraries).
  • You cannot directly move a library reference into the target library. However, if you move an element that depends on another library L, the refactoring will introduce a reference to library L in the target library.