PySgrep - Python Wrappers for Sgrep

Contents:

What is PySgrep?
Building and Installing PySgrep
Calling PySgrep
Receiving Results From PySgrep
Interface to sgreplib

What is PySgrep?

PySgrep is a Python extension module that enables Python code to call and control the functionality in Sgrep. You can learn more about Sgrep and obtain the original sgrep source at the sgrep home page.

Building and Installing PySgrep

To build PySgrep, do the following:

Unroll the original sgrep source code:
```
    tar xvzf sgrep-1.92a.tar.gz
```
Change to the sgrep directory and unzip pysgrep.zip:
```
    cd sgrep-1.92a
    unzip pysgrep.zip
```
Configure sgrep:
```
    ./configure
```
Build pysgrep:
```
    python setup.py build
```
To install PySgrep, do the following:
```
    python setup.py install
```

Calling PySgrep

In order to use PySgrep, do the following:

Import the module:
```
        import sgreplib
```

Set the call-back object (see below). For example:


        callBackObject = MyCallBackObject()
        sgreplib.set_callback_object(callBackObject)

Clear previous options (if necessary) and set options for the query. For example:


        sgreplib.clear_options()
        options = ('-x', 'test1.idx', '-o', '%f(%i) %r\n')
        for opt in options:
            sgreplib.add_option(opt)

Execute the query. For example:


        query = 'word("Queen")'
        sgreplib.execute_query(query)

Rational for this style of interaction with PySgrep -- The option passing style was chosen for the following reasons: (1) It was easy to implement; it required the least amount of alteration to sgrep code. (2) Once you have learned sgrep options, you have learned the options needed to use PySgrep.

Receiving Results From PySgrep

PySgrep passes results back to the caller through a call-back object. A PySgrep call-back object is an instance of any class that implements a method named write which takes a single argument (the text returned). Here are some simple examples of PySgrep call-back classes:


        class Collector:
            def __init__(self):
                pass
            def write(self, msg):
                print '(Collector.write)', msg

        class ListCollector:
            def __init__(self):
                self.collection = []
            def write(self, msg):
                self.collection.append(msg)
            def getCount(self):
                return len(self.collection)
            def getCollection(self):
                return self.collection

During the execution of a query, the write method in the call-back object will be called whenever there is a carriage return in the result stream. Hint: You can exercise some control over when the write method is called by inserting carriage returns in the result stream with the "-o" option. For example, the following options would cause the write method to be called for each region found:


        -o '%r\n'

And, the following options would cause the write method to be called twice for each region found:


        -o '%f(%i)\n%r\n'

Interface to sgreplib

set_callback_object(object)

Set the object which will receive the query results. The object should be an instance of a class that implements a write method that takes a single argument, the result string. The write method will be called whenever there is a carriage return in the result stream.

set_error_callback_object(object)

Set the object which will receive the error messages. The object should be an instance of a class that implements a write method that takes a single argument, the error message string. The write method will be called whenever there is a carriage return in the error message stream.

clear_options()

Clear any previously set options.

add_option

Add an option. Options should be added in the same sequence that they would have been listed on the sgrep command line.

execute_query(query)

Execute the query. query is a string that obeys the sgrep rules for queries.

execute_query_no_opt()

Execute the query. This method assumes that the query is the last option added.

Last update: 3/18/02