GIPSPIN DOCUMENTATION (in-development)

Getting Started
 Overview

GIPSpin is a graphical interface programming system designed to provide the user with true visual programming. The user can see the flow of their code. Many additions for which graphical aids make sence to aid programming will be added as GIPSpin evolves and is enhanced.
GIPSpin can output code in standard C++ format, and automatically "graphicalize" simple C code.

 
Tutorials

These samples can be found in “C:\Program Files\GIPSpin\examples” on Windows, and /usr/local/GIPSpin/examples on Linux. The tutorials are written with the Windows version in mind, but should be easy to follow on the Linux version as well. In the Linux version, to bring up a “New Library” you go the the “Edit” menu on top instead of the “Window” menu.

    
"Hello World"

On the top menu, select "Window"->"New Library". This should bring up a Library to allow you to select coding "Units"

Let's make a "main" function now. Click on the "FUNCTION" Unit. Clicking on the name of the Unit is a good approach. This should have put a FUNCTION Unit in the upper left of your main window. Click to give focus to the top text entry (top white box in the Unit), and write "int" without the quotes. In the text entry below that write "main".

Going back to the Library window change the top selection bar from "Function/Loops" to "Variables/Data". Click on the "PRINT" Unit.
Move the "PRINT" Unit by clicking and holding the left mouse button down to give it some distance from the "FUNCTION" Unit.
In the text entry of the "PRINT" Unit, enter with quotes "Hello World!".

Now in the Library window go back to "Function/Loops" and select "END_FUNC" to indicate an end of function. Move "END_FUNC" to somewhere after the "PRINT" Unit.

Now we link together the pieces. From the left option bar, select "Link". With the mouse, head towards the right side (output arrow) of the "FUNCTION" Unit. When it highlights, click the left mouse button. Now head towards the left side of the "Print" Unit. It should highlight when you get close to it. Press the left mouse button. You should now see a visual line linking the "FUNCTION" Unit to the "PRINT" Unit. Following a similar procedure, link together the "PRINT" Unit to the "END_FUNC" Unit.

Now's a good time to save your work. In the top menu, select "File"->"Save to GIP". Save it to a file name of your choice. I recommend you give it the extension ".gip", but it is not enforced.

If you installed MinGW, you can press "Run" from the left option bar, and in the DOS output window see your Hello World! Program run.

You can also save you program to C++ and compile it the compiler of your choice. From the top menu, select "File"->"Save to C++" and save it with any name you choose.


 
   Simple Thread


 Customization

Select “File”->”Options” from the top menu. You can add Compiler Options and set your favorite editor for “Data” Units. To set your editor you enter the executable in the “Editor” field. It will call that program whenever you Edit a “Data” Unit. (See Menu Details->Prefs for more details.)

 
Gotchas/Defects

1) No anonymous structs in "Data" Units. Always typedef structs:
typedef struct {
        int i;
} mystructtype;

Why? Because gcc does not allow pointers to anonymous structs which cause it to be very hard to pass data to a pthread-function when a user tries to do threading.

2) The "Print" Unit currently uses g++ "cout <<" functionality. If the variable is not one it recognizes it will not handle it correctly.

3) "Data" Unit can currently only handle C code.

Why? Need to enhance my additions to GCC to handle parsing of C++ code.

4) You must close the Editor on “Data” Units for the changes to take effect.

Why? The closing of the Editor is what triggers the re-read. This might be enhanced in the future so you do not have to do it if you use the default edit box. But if you use a custom editor, it will probably always be like that, since it is harder to interface with.

5)Core Dumps and functionality is still limited.

Why? Sorry, GIPSpin is still a pre-alpha prototype. It will get better with time.

Menu Details

 File
    Open File
Supports the opening of GIP, C2XML, and simple C code files.
GIP files are GIPSpin XML files created with "Save to GIP" and are the complete representation of the work represented in the GUI environment.
C2XML files are XML files created using the c2xml program. This is automatically turned into a graphical representation.
C is turned into XML format using C2XML and then handled as described above.

   
 Save to C++
Turns the current active window into C++ code.

   
 Save to GIP
Saves the complete representation of the work represented in the GUI environment.
      
  
  Prefs
      Compiler Options
These are the compiler options sent to mingw-gcc to compile and error check the code in GIPSpin.

     
 Editor
You can set this to the binary of a custom editor for use with "DATA" Units. Example:
Setting this to C:\emacs\emacs.exe  will use emacs for editing code within "DATA" Units (assuming you have emacs at C:\emacs\emacs.exe).  NOTE: You must close the editor after making your code changes in order for GIPSpin to know to pick up the changes.

   
 Quit
Quits GIPSpin. NOTE: There is no warning/prompt to save work.

 
Edit
    New Editor
Opens up a new Editor window.

    
Open Library
Opens up a new Library allowing the selection of components.

    
Cut
Remove to the clipboard the banded selection.

    
Copy
Copy to the clipboard the banded selection.

    
Paste
Take the contents of the clipboard and paste it into the current active editor.

    
Undo
Undo the last operation. NOTE: Not all operations are supported yet. Most graphical operations are supported. No text changes are supported yet.

    
Group
Turn the banded selection into a Group Unit.

 
View
    Errors
Opens up the code error window for the current active editor.


 Help
    About

    Manual

Flow Details
 Assembly/Analysis of Code
The assembly of code is done in three stages- a pre-threading pass, followed by code analysis, followed by a final assembly.  If there are no "THREAD" Units, the system is very simple and only the first step is performed.
Internally in the code there is support for every Unit to create a C++ code representation by either adding to the beginning of the C++ file, append to the file as the Unit is visited, or adding to the end of the C++ file.
     
 Pre-threading (Flat) pass
The starting point is the first found Unit with zero inputs. Then based on a simple traversal algorithm heavily dependent on the number of inputs/outputs of the Units, all the Units are visited. The "PRINT" Unit is an example of a Unit which causes "#include <iostream>" to be added to the beginning of the C++ file while at the same time adding "cout << var;" to the C++ file as it is visited. The "SWITCH" Unit is an example of a Unit which when it's "END_SWITCH" is visited, it traverses back to the "SWITCH" Unit to find the next "case" to traverse. The pass is called the "Pre-threading" pass since "THREAD" units are treated in a flat manner. The code between the "THREAD" and "END_THREAD" units are not encapsulated into pthreads; they are just laid out flat with markers in the C++ code for further code analysis.
     
 Code analysis
To enable the encapsulation of code between the "THREAD" and "END_THREAD" units and for future enhancements to GIPSpin, a code analysis stage is needed. The "Flat pass" code is converted into an XML representation by C2XML. It is then analysed for variables between the "THREAD" and "END_THREAD" units. A data structure is created to hold this data for the Final assembly stage.
     
 Final assembly
The variables between each "THREAD-END_THREAD" stage are passed to a custom made function which will be passed to pthread_create. The variables are passed as one C struct which contains pointers to each variable used. Within the custom made function, the pointer variables are de-referenced using C++ references and therefore code between the "THREAD-END_THREAD"  can simply be inserted into the custom made function without needing further manipulation.

Library Details
 Overview
      The Library contains pre-made Units for coding. Most of them are very familiar constructs recognizable to programmers. The creation of User defined and custom Units is in development.

 Components
    Function/Loops
       FUNCTION
           END_FUNC
       
       CALL
       
       FOR
       END_FOR
       
       WHILE
       END_WHILE
       
       DOWHILE
       END_DOWHILE
    
    Branch/Flow
       IF
       END_IF

       SWITCH
       END_SWITCH

    Variables/Data
       VARIABLE

       DATA

       PRINT

       INCLUDE
    
    Threads/Misc
        THREAD
Allows code between "THREAD" and "END_THREAD" Units to be threaded through the use of pthreads.
Line 1: Unique name for the "THREAD" Unit.  NOTE: User must provide a unique name.
Line 2...N:  Unique name for each thread being created. NOTE: User must provide a unique name for each thread (within the context of this "THREAD" Unit).
        
END_THREAD
Unit to indicate the end of  the "THREAD" unit.

   
 Custom1          
       Still not implemented. As you can imagine, the idea is to make your own boxes using either just Grouping of existing boxes or from code directly. This can be used to make pre-packaged algorithms.


Development Status:
We are at a Pre-Alpha stage. Basic functionality is implemented, but a lot of work
remains to be done in bulletproofing the code, eliminating known defects/quick-fixes,
and enhancements. Here's a list of known issues and TO-DO list:
- Graphics cleanup
Auto-refresh needs to be enhanced
Unexpected events in multi-window support leading to crashes
B-splice curves instead of lines
- Code support
Complex C structure support is limited leading to crashes
C++ support
Better support for complex projects (multiple files)
Data-linkage support (variable/function finders)
- Threading support
More advanced algorithms to help users do special tasks
- API
An API interface to allow independent tools to make use of components
- Command-Line programs
Turn code dealing with XML<->C translation into separate command-line program