[Commit-gnuradio] [gnuradio] 03/04: runtime: adds a gr.tag_utils.python_to_tag to convert formatted dicts/lists/tuples to tag_t objects.

[git]

This is an automated email from the git hooks/post-receive script.

trondeau pushed a commit to branch master
in repository gnuradio.

commit ed7d84afba825aaabe7d940b135286c801234538
Author: Tom Rondeau <address@hidden>
Date:   Sun Feb 23 13:58:46 2014 -0500

    runtime: adds a gr.tag_utils.python_to_tag to convert formatted 
dicts/lists/tuples to tag_t objects.
    
    blocks: adds documentation to vector_source block on how to use the 
python_to_tag to emit tags with the data stream.
---
 .../python/gnuradio/gr/qa_tag_utils.py             | 30 ++++++++++
 gnuradio-runtime/python/gnuradio/gr/tag_utils.py   | 66 ++++++++++++++++++++++
 .../include/gnuradio/blocks/vector_source_X.h.t    | 19 ++++++-
 3 files changed, 114 insertions(+), 1 deletion(-)

diff --git a/gnuradio-runtime/python/gnuradio/gr/qa_tag_utils.py 
b/gnuradio-runtime/python/gnuradio/gr/qa_tag_utils.py
index 56797a4..1a08ac5 100755
--- a/gnuradio-runtime/python/gnuradio/gr/qa_tag_utils.py
+++ b/gnuradio-runtime/python/gnuradio/gr/qa_tag_utils.py
@@ -47,6 +47,36 @@ class test_tag_utils (gr_unittest.TestCase):
         self.assertEqual(pt.value, 23)
         self.assertEqual(pt.offset, 10)
 
+    def test_002(self):
+        offset = 10
+        key = pmt.string_to_symbol('key')
+        value = pmt.from_long(23)
+        srcid = pmt.from_bool(False)
+
+        format_dict = {'offset': offset,
+                       'key': key,
+                       'value': value,
+                       'srcid': srcid}
+        format_list = [offset, key, value, srcid]
+        format_tuple = (offset, key, value, srcid)
+
+        t_dict = gr.python_to_tag(format_dict)
+        t_list = gr.python_to_tag(format_list)
+        t_tuple = gr.python_to_tag(format_tuple)
+
+        self.assertTrue(pmt.equal(t_dict.key, key))
+        self.assertTrue(pmt.equal(t_dict.value, value))
+        self.assertEqual(t_dict.offset, offset)
+
+        self.assertTrue(pmt.equal(t_list.key, key))
+        self.assertTrue(pmt.equal(t_list.value, value))
+        self.assertEqual(t_list.offset, offset)
+
+        self.assertTrue(pmt.equal(t_tuple.key, key))
+        self.assertTrue(pmt.equal(t_tuple.value, value))
+        self.assertEqual(t_tuple.offset, offset)
+
+
 
 if __name__ == '__main__':
     print 'hi'
diff --git a/gnuradio-runtime/python/gnuradio/gr/tag_utils.py 
b/gnuradio-runtime/python/gnuradio/gr/tag_utils.py
index ad80bff..cbca9d4 100644
--- a/gnuradio-runtime/python/gnuradio/gr/tag_utils.py
+++ b/gnuradio-runtime/python/gnuradio/gr/tag_utils.py
@@ -28,4 +28,70 @@ def tag_to_pmt(tag):
     newtag.srcid = pmt.from_python(tag.srcid)
     return newtag
 
+def python_to_tag(tag_struct):
+    """
+    Convert a Python list/tuple/dictionary to a stream tag.
+
+    When using a list or tuple format, this function expects the format:
+      tag_struct[0] --> tag's offset (as an integer)
+      tag_struct[1] --> tag's key (as a PMT)
+      tag_struct[2] --> tag's value (as a PMT)
+      tag_struct[3] --> tag's srcid (as a PMT)
+
+    When using a dictionary, we specify the dictionary keys using:
+      tag_struct['offset'] --> tag's offset (as an integer)
+      tag_struct['key'] --> tag's key (as a PMT)
+      tag_struct['value'] --> tag's value (as a PMT)
+      tag_struct['srcid'] --> tag's srcid (as a PMT)
+
+    If the function can take the Python object and successfully
+    construct a tag, it will return the tag. Otherwise, it will return
+    None.
+    """
+    good = False
+    tag = gr.tag_t()
+    if(type(tag_struct) == dict):
+        if(tag_struct.has_key('offset')):
+            if(isinstance(tag_struct['offset'], (int,long))):
+                tag.offset = tag_struct['offset']
+                good = True
+
+        if(tag_struct.has_key('key')):
+            if(isinstance(tag_struct['key'], pmt.pmt_swig.swig_int_ptr)):
+                tag.key = tag_struct['key']
+                good = True
+
+        if(tag_struct.has_key('value')):
+            if(isinstance(tag_struct['value'], pmt.pmt_swig.swig_int_ptr)):
+                tag.value = tag_struct['value']
+                good = True
+
+        if(tag_struct.has_key('srcid')):
+            if(isinstance(tag_struct['srcid'], pmt.pmt_swig.swig_int_ptr)):
+                tag.srcid = tag_struct['srcid']
+                good = True
+
+    elif(type(tag_struct) == list or type(tag_struct) == tuple):
+        if(len(tag_struct) == 4):
+            if(isinstance(tag_struct[0], (int,long))):
+                tag.offset = tag_struct[0]
+                good = True
+
+            if(isinstance(tag_struct[1], pmt.pmt_swig.swig_int_ptr)):
+                tag.key = tag_struct[1]
+                good = True
+
+            if(isinstance(tag_struct[2], pmt.pmt_swig.swig_int_ptr)):
+                tag.value = tag_struct[2]
+                good = True
+
+            if(isinstance(tag_struct[3], pmt.pmt_swig.swig_int_ptr)):
+                tag.srcid = tag_struct[3]
+                good = True
+
+    if(good):
+        return tag
+    else:
+        return None
+
 
diff --git a/gr-blocks/include/gnuradio/blocks/vector_source_X.h.t 
b/gr-blocks/include/gnuradio/blocks/vector_source_X.h.t
index 9751514..d5298e8 100644
--- a/gr-blocks/include/gnuradio/blocks/vector_source_X.h.t
+++ b/gr-blocks/include/gnuradio/blocks/vector_source_X.h.t
@@ -32,7 +32,7 @@ namespace gr {
   namespace blocks {
 
     /*!
-     * \brief Source that streams @TYPE@ items based on the input \data vector.
+     * \brief Source that streams @TYPE@ items based on the input \p data 
vector.
      * \ingroup misc_blk
      *
      * \details
@@ -45,6 +45,23 @@ namespace gr {
      * The vector source can also produce stream tags with the
      * data. Pass in a vector of gr::tag_t objects and they will be
      * emitted based on the specified offset of the tag.
+     *
+     * GNU Radio provides a utility Python module in gr.tag_utils to
+     * convert between tags and Python objects:
+     * gr.tag_utils.python_to_tag.
+     *
+     * We can create tags as Python lists (or tuples) using the list
+     * structure [int offset, pmt key, pmt value, pmt srcid]. It is
+     * important to define the list/tuple with the values in the
+     * correct order and with the correct data type. A python
+     * dictionary can also be used using the keys: "offset", "key",
+     * "value", and "srcid" with the same data types as for the lists.
+     *
+     * When given a list of tags, the vector source will emit the tags
+     * repeatedly by updating the offset relative to the vector stream
+     * length. That is, if the vector has 500 items and a tag has an
+     * offset of 0, that tag will be placed on item 0, 500, 1000,
+     * 1500, etc.
      */
     class BLOCKS_API @NAME@ : virtual public sync_block
     {