English

Control Flow Parser

Overview

Control flow parser is a Python 2 extension module. It takes a file with a python code (or a character buffer), parses it and provides a hierarchical representation of the code in terms of fragments. Each fragment describes a portion of the input content: a start point (line, column and absolute position) plus an end point (line, column and absolute position).

Comments are preserved too.

The parser is developed within the Codimension IDE project however could be used in any other project. The parser source code is located on GitHub and named cdm-flowparser.

Codimension IDE uses the parser to generate a flowchart like diagrams for an arbitrary Python code as the user types it. Basically a pause in typing is detected and the diagram is regenerated. The parser provides the necessery input for the further stages of laying out, rendering and drawing stages.

Visualizing Parser Output

Suppose there is the following file ~/my-file.py with the following content:

#!/usr/bin/python
import sys

# I like comments
a = 154
for x in xrange( a ):
    print "x = " + str( x )

sys.exit( 0 )

Then you can run a test utility:

$ ~/cdm-flowparser/utils/run.py ~/my-file.py

The output will be the following:

$ ~/cdm-flowparser/utils/run.py ~/my-file.py
Running control flow parser version: trunk
Module location: /home/swift/.local/lib/python2.7/site-packages/cdmcf.so
<ControlFlow [0:119] (1,1) (9,13)
 Body: [18:119] (2,1) (9,13)
 LeadingComment: None
 SideComment: None
 LeadingCMLComments: n/a
 SideCMLComments: n/a
 isOK: true
 Errors: n/a
 Warnings: n/a
 BangLine: [0:16] (1,1) (1,17)
 EncodingLine: None
 Docstring: None
 Suite: <Import [18:27] (2,1) (2,10)
         Body: [18:27] (2,1) (2,10)
         LeadingComment: None
         SideComment: None
         LeadingCMLComments: n/a
         SideCMLComments: n/a
         FromPart: None
         WhatPart: [25:27] (2,8) (2,10)
        >
        <CodeBlock [30:54] (4,1) (5,7)
         Body: [48:54] (5,1) (5,7)
         LeadingComment: <Comment [30:46] (4,1) (4,17)
                          Parts: <Fragment [30:46] (4,1) (4,17)
                                 >
                         >
         SideComment: None
         LeadingCMLComments: n/a
         SideCMLComments: n/a
        >
        <For [56:104] (6,1) (7,27)
         Body: [56:76] (6,1) (6,21)
         LeadingComment: None
         SideComment: None
         LeadingCMLComments: n/a
         SideCMLComments: n/a
         Iteration: [60:75] (6,5) (6,20)
         Suite: <CodeBlock [82:104] (7,5) (7,27)
                 Body: [82:104] (7,5) (7,27)
                 LeadingComment: None
                 SideComment: None
                 LeadingCMLComments: n/a
                 SideCMLComments: n/a
                >
         ElsePart: None
        >
        <SysExit [107:119] (9,1) (9,13)
         Body: [107:119] (9,1) (9,13)
         LeadingComment: None
         SideComment: None
         LeadingCMLComments: n/a
         SideCMLComments: n/a
         Argument: [117:117] (9,11) (9,11)
        >
>

Usage

Basically the run.py utility has the following essential lines:

from cdmcf import getControlFlowFromFile
controlFlow = getControlFlowFromFile( "my-file.py" )

# Serializes nicely the controlFlow object
# See the run.py for the details of how it is done

See the run.py utility source code for details.

Installation

The control flow parser package is build for a few platforms. Please refer to the instructions located on the Linux Download page. The page describes how to install all the packages Codimension IDE needs but if you need the control flow parser only please follow the steps for one package: cdmflowparser-x.x.x

Building From Git Clone

Building from git clone provides you the most up to date code with a risk of instability. Please use it on your own risk.

$ cd
$ git clone https://github.com/SergeySatskiy/cdm-flowparser.git
$ cd ~/cdm-flowparser
$ make
$ make localinstall
$ make check

Links