Code example support proposal

3 replies [Last post]
shaffer
shaffer's picture
Offline
White BeltYellow BeltGreen BeltRed BeltBlack Belt
Joined: 2009-05-28
Posts:
Points: 2009

 I am looking for feedback on the following proposal. (Thanks to Tom for the initial idea on markup of displayed code snippets within a bigger code file!)

 

The goal is to manage the code base for example code in such a way that it can be compiled and tested on its own. We wish to support code written in Python, Processing, or JavaScript (since these three languages can all be executed directly within a browser, they can all be supported with reasonable ease).

 

This code should integrate with:

* display of code snippets within the eTextbook

* support for programming exercises

* support for "pseudocode" display within an AV

 

The basic idea is to take normal code files in the language, and annotate them with markup (within the framework of standard comments in that language). Various processors can then extract the marked code sections for use elsewhere.

 

 

Code Annotations

–––––-

 

In Processing and JavaScript, annotationed code will be contained with comment lines that look as follows:

 

To start a block, have on a separate line a comment with the following format:

 

/* *** ODSATag: MyTag *** */

 

MyTag can be whatever alphanumeric string you want (including underscores and hyphens) but must not include spaces or the * symbol. This is the reference used by, for example, the ReST directive that gets out the code snippet.

 

To end the block, have on a separate line a comment with the following format: 

 

/* *** ODSAendTag *** */

 

It is not intended that this system support nesting of code snippets.

 

Python format: Python comments have a different format from that of Procesing and JavaScript. So we need a different format, as follows:

 

To start the annotation block include a line like:

# *** ODSATag: MyTag ***

 

To end the annotation block include a line like:

# *** ODSAendTag ***

 

 

ReST Support

––––

 

Code snippets will be extracted from the specified files and embedded into a eTextbook module under the control of the following ReST directive.

 

.. ODSAcode:: <URL>

   :tag: <MyTag>

 

Here the <URL> for the code file can be relative. <MyTag> is the tag used in the code annotation. Note that this means that a given code file can contain multiple annotated sections, each enclosed in annotation lines. Only the code lines that appear between the annotated tag and its end line will be displayed.

 

If specified as shown above, the code will be embedded in a standard ReST code block. An optional argument :live: can be included, which will result in the code being embedded in a "live code" block. See http://thinkcspy.appspot.com/build/introduction.html for examples. Brad Miller’s live code extension can probably can be used as a starting point for implementing this, but it will need to be extended to support Processing and JavaScript.

 

 

Programming Exercises

–––––––

 

Further down the line, we should be able to use this mechanism to support coding exercises, such as: Write a function (using the binary tree API) that counts the number of nodes in a binary tree. In that case, the user can be given a blank editing panel in which to enter the desired function. That function can then be put into the assessment test harness in place of the model code specified in the code file. Test cases can then be run on both the student’s code and the model code, and compared. The details for this need to be worked out.

 

 

JSAV pseudocode display support

––––––––––-

 

JSAV pseudocode initialization function should be able to process a code file containing the annotation in a similar way, extracting the annotated section for use in its usual way.

 

shaffer
shaffer's picture
Offline
White BeltYellow BeltGreen BeltRed BeltBlack Belt
Joined: 2009-05-28
Posts:
Points: 2009
Re: Code example support proposal

I found this really useful directive in ReST: http://docutils.sourceforge.net/docs/ref/rst/directives.html#include

Basically this gives me pretty much everything already for extracting some lines of code out of the source file. I did a quick example in the Shellsort RST module. I was able to get just what I wanted by adding these lines:

.. literalinclude:: ../../SourceCode/Processing/Shellsort.pde

   :start-after: /* *** ODSATag: Shellsort *** */

   :end-before: /* *** ODSAendTag: Shellsort *** */

 

This requires me to make a slight modification to the syntax desribed above in that I need to put the tag string into the ODSAendTag line (for handling the case where we have multiple blocks in a file). But that is fine, because a module developer does not need to see that. All we need to do now is wrap this up in a new directive to be a little more user-friendly, something like:

.. codeinclude:: <relative path>

   :tag: <my tag>

where :tag: can be left out when including the entire file contents.

I hope to have a complete working implementation for this next week.

 

 

ville
ville's picture
Offline
White BeltYellow BeltGreen BeltRed BeltBlack Belt
Joined: 2009-05-28
Posts:
Points: 559
Re: Code example support proposal

JSAV could implement the ReST directive options. So pseudocode could be initialized with

jsav.code({url: 'mypseudo.pde', 
           startAfter: '/* *** ODSATag: Shellsort *** */', 
           endBefore: '/* *** ODSAendTag: Shellsort *** */'
          })

Should be simple to add.

Ville Karavirta, Aalto University, http://villekaravirta.com/

shaffer
shaffer's picture
Offline
White BeltYellow BeltGreen BeltRed BeltBlack Belt
Joined: 2009-05-28
Posts:
Points: 2009
Re: Code example support proposal

Thanks! That would be a big help.

I now have a version of the Insertion Sort module working with the included code and psuedocode support in the AV.

http://algoviz.org/OpenDSA/dev/OpenDSA/RST/build/html/InsertionSort.html