CodeFlow IDE Quick Reference

This quick reference of the CodeFlow IDE is an essential reading when you get started with CodeFlow. You can also read it as a guided tour of the CodeFlow IDE.

CodeFlow project window overview

CodeFlow project window

Project Files list

The CodeFlow Project Files List is divided in 3 sections:

  • Source Files: the Lua source files and various resources of your CodeFlow project (running in one Lua Context),

  • External Libs: the bindings libraries making the link between your Lua code and native libraries and frameworks linked with your application. Opening a bindings library in the list displays the Lua interface files for this library.

  • Loaded Items: the list of all Lua source files and resources loaded on the connected target, in reverse chronological order (i.e. the most recent first).

CodeFlow project files list

Source Files hierarchy

Source files can be organized in Files Groups.

Files groups shall be included in the dot-separated item path when you require a Lua module or when you get a resource with getResource. For example, in the program presented above, you could write:

local TableCellClass = require("CheckerTableCell")

getResource("DetailViewNib", 'nib', self, "detailViewNib")
getResource("assets.tableItems", "plist", self, "model")
getResource("", "public.image", self, "fruitImage")

Note: when requiring a Lua module from an external library, you can omit the library name from the path.

-- For example, you can write:
local UiView = require "UIKit.UIView"
-- or if you prefer:
local UiView = require "iOS.UIKit.UIView"

Files Indicators

Indicator Description
File Loaded indicator
the source file has been loaded on the connected target (on a group, means that at least one item of this group has been loaded.
File Auto-reload indicator
indicate that the Lua module will be automatically reloaded as soon as it changes.
File Error indicator
indicates a syntax error in a Lua Module, or an error in the preprocessing of a resource file.
File needs reload indicator
Needs reload
the Lua module has changed since last loaded on the target (and is not in auto-reload mode).
File linked indicator
Linked file
this file (resource or Lua module is linked to an external file, and any change to this external file will be propagated to the application.
File read-only indicator
the file can not be edited (usually set on Lua modules in an external lib, and on loaded items).

Files actions

Action How
Create a Lua Module use the Add Source toolbar button, or do menu command New Lua File in contextual menu or Program menu.
Create a Files Group use the Add Source toolbar button, or do menu command New Group in contextual menu or Program menu.
Rename a source file select the file in the list and click on its name in the source file list or press Enter.
Add a resource file drag and drop the corresponding data or URL from the Finder or any other application. Or choose Add File... from the contextual menu.
Delete source file(s) select the files to delete and press the Backspace key or choose Delete Selected Items in the Program menu.
Edit/View a file in CodeFlow internal source editor select the file in the list
Edit/View a file in the default external editor double-click on the file in the list or select the file and press return.
Note: you can define a default external editor for Lua source files in CodeFlow preferences.
Edit/View a file in a specific external editor use the contextual menu command Open with and select the external editor from the list.
Link a source file to an external file right-click on the source file and use the contextual menu Link to File
Remove the link to an external file right-click on the source file and use the contextual menu Link to File
Reorder / move source files inside the SOURCE FILES group use drag and drop.
Use a loaded item as a source file drag the loaded item into the SOURCE FILES group.
Set the content of a source file to mach a loaded item drag this loaded item over the source file.

Files list contextual menu

Source Files contextual menu

Source Files Contextual Menu

External Libs contextual menu

External Libs Contextual Menu

This menu permits to select the iOS or OS X SDK bindings library used by the CodeFlow project. You can only have one platform SDK bindings library set for a given project; therefore selecting a different SDK version replaces the current one.

When you change the iOS SDK bindings library used by a CodeFlow project, you need to save it so that the associated Xcode project can be updated and use the correct libraries for this SDK. Then rebuild and relaunch your application from Xcode to make it consistent with your COdeFlow project.

Loaded Items contextual menu

Loaded Items Contextual Menu
Action Description
View Original Source File selects the original file for this loaded item in the SOURCE FILES group.
Revert Original Source File sets the content of the loaded item's original source file to the loaded item's content

About linked source files

By default, when you drag a file to your CodeFlow project, CodeFlow keeps a link to this file's location in the file system and monitor this location, so that any change to the original file will be visible in the CodeFlow project and propagated to the target application, if a target application is connected. In CodeFlow files list, a source file with such a link to an external file location is represented with a linked file indicator on top of the file's icon.

A source file with no linked file indicator is local to the CodeFlow project, meaning that it is stored inside the corresponding CodeFlow project document. Editing a local source file with an external editor is of course possible, and won't have any side effects on other files in your file system.

Choosing to work more with local or with linked source files in CodeFlow is a matter of personal preferences for your workflow. And you can change the linked-file-status of a source file in CodeFlow at any time with the Link to File contextual menu commands, or create a new link by dragging a file from the Finder onto an existing source file of your CodeFlow project.

Link to File command Description
Existing File... Links the CodeFlow source file to the selected type-compatible file location. The CodeFlow source file is set with the content of the external file.
New File... Saves the content of the CodeFlow source file into the selected location and keeps the link to this location.
Remove Link Removes the currently existing link and turns the CodeFlow source file into a project-local file.

Using loaded items history

When your CodeFlow project is connected to a target application, you can view in the LOADED ITEMS group the whole loaded-items history since this target application started. This history contains both loaded Lua modules and loaded resources. It is ordered chronologically, with the oldest loaded item at the bottom of the list and the most recently loaded at the top.

You can not edit a loaded item, but could can visualize it by selecting it in the list. The contextual menu on a loaded item allows you to jump to the original source file from which this items was loaded (if it still exists in the current SOURCE FILES group) and to restore the original source file with the content of the loaded item.

Loaded Items Contextual Menu
Action Description
View Original Source File selects the original file for this loaded item in the SOURCE FILES group.
Revert Original Source File sets the content of the loaded item's original source file to the loaded item's content

On the other side, in the SOURCE FILES group, if a project source file has its loaded indicator displayed, you have a direct access from its contextual menu to all loaded as versions of this source file, since the target application started. The Revert to Loaded Version submenu shows the preview and loading time of all loaded versions for the source file and enables you to restore any of them.

Revert to Loaded Version Contextual Menu

Lua code editor

CodeFlow includes a simple Lua code editor supporting Lua syntax highlighting, on-the-fly syntax errors detection, auto-completion and auto-indentation.

CodeFlow Lua code editor

Lua-syntax-related features

Feature Description
Syntax highlighting The Lua code editor implements advanced syntax highlighting capable of detecting the precise role of any syntax element in a Lua source file. For example, local variables, global variables and upvalues are presented with different colors, to help you detect typing errors at first sight.
The syntax font and colors can be customized in CodeFlow preferences.
Syntax-aware selection Triple-click selects the Lua statement at the click location; if you maintain the mouse button pressed and move the mouse, the selection is extended so as to include entire statements and/or syntax blocks.
Variable usage visualization Double click on a variable highlights all uses of this variable, in accordance with Lua scoping rules. Read and write accesses to the variable are highlighted with separate colors, so the variable value changes can be easily detected.
You can navigate between occurrences of a variable by pressing cmd alt L. CodeFlow Lua code editor - variable usage
Smart commenting Comment the selection by pressing cmd shift - (or with the Comment Selection in the Syntax menu.
If the selection empty, the line at the insertion point is commented. If the selection includes a comment, Lua nested comments syntax is used, so that the old comment is included in the new one.
If the selection only include comments or is inside a comment, the command becomes Uncomment Selection and the outermost comment is removed.
Automatic indentation Indentation is updated as you type the code. Press tab for indenting the current selection.
Syntax errors detection Syntax errors are detected in real-time as you enter the code. An error is signaled by a red triangle error in front of the line where the error has been detected.
Note: currently the Lua parser can only detect a single error at a time. CodeFlow Lua code editor - error detection


The CodeFlow Lua editor supports auto-completion of many elements in the source code: auto-completion can be used on variable names, table and objects fields, methods, and also on Lua module names and resource names! Auto-completion is Objective-C-aware and supports completion of Objective-C methods and properties defined in the IOS SDK.

The auto-completion menu at the current insert position is shown when pressing the esc key on the keyboard.

Some examples may bring a better vision of scope of code completion in CodeFlow:

Completed entity Example
Variable name CodeFlow code completion: variable
Object property CodeFlow code completion: property
Lua module name/path CodeFlow code completion: module name
Resource name/path CodeFlow code completion: resource path

The Lua code editor toolbar

CodeFlow Lua code editor toolbar
Toolbar element Description
Navigation arrows Use them to browse quickly your source files navigation history.
Alternatively you can use horizontal swipe gestures on your trackpad or magic mouse for more natural source files history browsing.
Source File path and type Informative. Display the source file logical path (i.e. the path that you would use in require or getResource) and type of the currently displayed source file. Present for all types of source files.
Functions menu A menu listing all functions and methods defined in the current Lua module. Select a function to jump to its definition.
Note: anonymous Lua functions are also referenced in this menu.
Globals menu A menu listing all Lua global variables used by the current Lua module.
This menu helps you to quickly identify the globals that your module reads or overwrites, and to check that you haven't by mistake referenced/created a new Lua global by misspelling a variable in your module.
Dependencies menu A menu listing recursively all Lua modules required by the current Lua source file. Use the menu to jump to a required module; use the navigation arrows or the swipe gesture to come back to the current module.
Reload module button Use this button to reload the current Lua module in the target application. Most of the time, this is equivalent to selecting the Load Source File command in the Execute menu.
However if the current Lua module hasn't changed since the last loaded version, the reload button can force a reload, where the Load Source File command is simply disabled.

Image and Quicklook viewers

The image viewer in CodeFlow provide a simple view of an image resource and an easy access to the available editors through the Edit menu in the viewer toolbar. In addition, it include a simple gesture-based zooming feature and display size and type information about the image.

CodeFlow Image viewer

The Quicklook viewer is similar and is used for non-image resources. It presents a Quicklook view of the resource nd an easy access to the available editors through the Edit menu in the viewer toolbar. As it uses Quicklook, its display can depend of the Quicklook plugins that you have installed in your system.

Target selector

Target connection state

The Target button in a CodeFlow project window toolbar indicate the state of the connection of the CodeFlow project with an target application running on a device or in the iOS simulator (or more precisely of the connection with a Lua Context in an Application).

The CodeFlow project can be in one of 3 states regarding its target connection:

State Description
Target state not connected
Not connected
The CodeFlow project is not connected to any Lua Context.
Target state connected
The CodeFlow project is successfully connected to a remote Lua Context executed in an application running on a device or in the simulator.
Target state local Lua context
Local Lua Context
The CodeFlow project is connected to a local Lua context, that can be used for running / live-coding Lua programs not using the iOS SDK or other application-specific classes. It can be considered as a Lua playground for experimenting with the language.

Target selection

Target selection is done via the target popover. The target popover lists every available target connected to the same local network as the machine running CodeFlow, plus a Local Lua Context that can be used for local Lua execution.

If the CodeFlow project tries to reconnect to a previously connected target, this target appears grayed out in the popover list, with a spinner besides it.

Target popover not connected

When the CodeFlow project is connected with a target Lua Context, this connected target is checked in the list.

Target popover connected

The following actions are possible in the target selector popover:

Action Description
Connect to an available target Click on this target in the list.
If the project was already connected to an other target, this target is released before the new connection is established. Once connected, the code and resources on the new target are updated to match the current state of the CodeFlow project.
Release the connected target Click on the connected target in the list.
After disconnection, the target becomes available for connection in CodeFlow projects.
Stop waiting for the previously connected target Click on the pending target to forget this target. It then disappears from the list.
Restart the local Lua Context If connected to the local Lua Context, pressing the Restart button resets the Lua context, clearing this Context from all existing data and internal Lua state.

Execution control

CodeFlow execution control tools are located in the project window toolbar.

CodeFlow execution tools
Tool Description
Debug tools The classic debugger commands: pause/continue, step over, step into, step out and abort execution.
Abort execution exits all functions in the stack of the current Lua thread and returns nil to the native caller.
Breakpoints control Activate / deactivates breakpoints in the connected target.
Halt on error control Activate / deactivates halt on error in the connected target.
When halt on error is deactivated, errors are only signaled by a printed message in the Lua console; otherwise the execution stops on the instruction causing the error.
Activity indicator  Blinks green when Lua code is executed in the target Lua Context; turns blue when execution is interrupted on a breakpoint or on an error.

Variables Inspector

The variable inspector in CodeFlow let you inspect the whole state of your Lua program in the connected target: this includes global variables as well as Lua threads with their stack frames and associated local variables.

CodeFlow variables inspector

The variables inspector provides visual symbols to make the variables inspection easier. These symbols provide immediate information about the roles and types of the presented variables or values, as listed in the table below:

CodeFlow variables inspector type icons
Possible Actions Description
Display the source code corresponding to a Lua function call Click on this function call in the call stack.
View the fields of a table, struct or object unfold the table / struct / object structure by clicking on the corresponding triangle.
Inspect global variables Open the Globals group located below Lua threads in the inspector
Inspect Lua standard libraries Open the Standard Libraries group.
Change the value of a variable Click on the value and enter the new value. Editing a value can be done on number, strings and boolean values. It will not change the type of the value.
Change the value of a table or object field Same as for changing the value of a variable: Click on the value and enter the new value. Editing a value can be done on number, strings and boolean values. It will not change the type of the value.
View the code of a Lua function value Click on the Lua function value.
View a variable in the code Click on the name of a function parameter or local variable or up-value in the variable inspector, and you this variable will be highlighted in the code.

Note: Global variables and Standard Libraries can be inspected while the program is running; threads callstacks can only be inspected when the program is paused.

Lua Console

With the Lua Console, you can execute commands (i.e. Lua code) on the Lua context while it is running or paused.

CodeFlow Lua Console

The command editor let you enter multilines Lua code snippets that have access to the Target's global variables. You run a command by pressing cmd return or by clicking on the run command button. You can recall previous commands with the command history stepper.

The command output area displays the textual output of Lua print functions and error messages issued by the Target Lua Context.

Associated Xcode Project

CodeFlow can automatically configure and update an associated Xcode project containing the application that runs the Lua Context for your CodeFlow project.

You select the associated Xcode project with the Program menu command: Select Associated Xcode Project...

Associated Xcode project selection

This displays a standard file selection dialog in which you select an Xcode project and an application target in this project. The Keep Xcode project updated checkbox tells CodeFlow to memorize the association with the Xcode project and to keep updating this project when needed in the future.

An associated Xcode project can be updated for various reasons, the most frequent one being when a change in your Lua source code makes it require a not-used-yet SDK framework. In this case, you see a notification appear in the CodeFlow project:

Associated Xcode project updated message

You need then to rebuild and restart the target application, to ensure that every class or symbol used by the CodeFlow project is available in the target application.

CodeFlow Menus reference

Program menu

CodeFlow Program menu
Command Description
New Lua File Create a new Lua file in the project.
New Group Create a new Group in the project files list.
Add File Item... Add an existing file to the project, keeping the link to the selected file.
Add External Library Adds a Lua bindings library to the project, eventually replacing an external library with the same name.
Delete Selected Items Remove the selected items in the project files list from the project, leaving any externally linked file untouched.
Select Associated Xcode Project... Display the associated Xcode project selection dialog.
Open Xcode Project Open the associated Xcode project in Xcode.
Update Xcode Project Force an immediate update of the associated Xcode project to make it match the current CodeFlow project state.
Show Xcode Project In Finder Shows the associated Xcode project file in a Finder window.
Clear Association with Xcode Project Forget the currently associated Xcode project and don't update it anymore in the future.
Export Program... Create a .luapkg file containing every Lua source files and resources in the CodeFlow project for embedding in an application bundle. If an associated Xcode project is defined, the .luapkg file is added to the corresponding Xcode application target.

Syntax menu

CodeFlow Syntax menu
Command Description
Indent Selection Re-indent the selected Lua code in the currently edited Lua module.
Comment Line / Selection Comment the Lua code at the current line / the currently selected Lua code.
Uncomment Selection / Line Uncomment the enclosing comment of the current selection or insertion point.
Protect Selection Wraps the selected code in a call to Lua standard pcall function. Then if a Lua error occurs in the protected code block, the execution will simply jump out of the protected block.
Select Next Variable Reference When you have highlighted all references to a Lua variable by double-clicking on it, this command navigates to the next reference to this variable in the current Lua file.

Execute menu

CodeFlow Execute menu
Command Description
Load Source File When a Lua source file has been modified since the last loaded version on the connected target and is not auto-reload mode, this command loads the current version of the Lua file on the connected target.
Reload Source File On Update Toggle the auto-reload mode for the current Lua source file.

Post a Comment