julienne 0.1.0

Juli Comment Markers

When using juli, you have one copy of your code in its final state. You mark sections of your code with comments to indicate that a line or block only participates in certain versions. Each version is called a chapter. When you run the juli command it will create a directory for each chapter found in your code.

# This is a sample file

a = "In all chapters"   # inline comment
b = "In chapters 1-3"   #:1-3 comment on conditional
c = "In chapters 1-2"   #:-2
d = "In chapters 2 on"  #:2-

#::3-4
#>e = "In chapters 3 to 4"  # inline comment
#>f = "  as a block"

for x in range(10):
    #::1-2 block header with comment
    #>g= "In chapters 1 and 2"
    h = "In all chapters"

The juli parser supports three conditional comment markers:

• #: – is for marking a single line with a range of chapters

• #:: – is for marking the start of a conditional block

• #> – is for marking a line participating in a block

The #: and #:: markers expect a range that indicates what chapters a line or block participates within. Ranges can indicate a single chapter, a range of chapters, up-to-and-including a chapter, and including-and-after a chapter. For example:

• #:3 – this line only shows up in chapter 3

• #::2-4 – the following block shows up in chapters 2, 3, and 4

• #:-2 – this line is in chapters 1 and 2

• #::4- – the following block shows up in chapter 4 and any chapters after

The markers support trailing comments. Generated code will insert a comment without the juli marker containing whatever comes after your marker.

The sample code above will generate four chapters. Chapter one would contain:

# This is a sample file

a = "In all chapters"   # inline comment
b = "In chapters 1-3"   # comment on conditional
c = "In chapters 1-2"


for x in range(10):
    g= "In chapters 1 and 2"
    h = "In all chapters"

Chapter four would contain:

# This is a sample file

a = "In all chapters"   # inline comment
d = "In chapters 2 on"

e = "In chapters 3 to 4"  # inline comment
f = "  as a block"

for x in range(10):
    h = "In all chapters"

Note that files that contain only conditional lines will not be included if they aren’t in chapter range.

Configuring Your Project

The juli uses a TOML file for configuration. The file must contain two key/value pairs that indicate the source and output directories for the parser.

output_dir = 'last_output'
src_dir = 'code'

The above will cause juli to look for a directory named code relative to the configuration file. The source found in that directory will be parsed. The generated chapters will be put in a directory named last_output. If your source specified two chapters, running juli will result in the creation of two directories: last_output/ch1/code and last_output/ch2/code.

Both the output_dir and src_dir values can be absolute paths or relative to the TOML configuration file.

Additional, optional configuration values are:

• chapter_prefix – Specify what the prefix part of a chapter directory is named. If not specified, defaults to “ch”

• python_globs – A glob pattern that indicates which files participate in the parsing. Files that don’t match will be copied without processing. If not specified it defaults to **/*.py, meaning all files ending in “*.py”

• [chapter_map] – Chapter numbers are integers, but you may not always want that in your output structure. This map allows you to change the suffix part of a chapter directory name. Keys in the map are the chapter numbers while values are what should be used in the chapter suffix.

• [subdir.XYZ] – Whole directories can be marked as conditional using this TOML map. This map must specify range and src_dir attributes. The range attribute indicates what chapters this directory participates in, and the src_dir points to the conditional chapter. The XYZ portion of the nested map is ignored, it is there so you can have multiple conditional directories.

Here is a full example of a configuration file:

output_dir = 'last_output'
src_dir = 'code'

chapter_prefix = "chap"

[chapter_map]
4 = 'Four'
5 = '5.0'

[subdir.foo]
range = '2-4'
src_dir = 'code/between24'

[subdir.bar]
range = '4-'
src_dir = 'code/after4'

If your code directory contained:

code/script.py
code/readme.txt
code/between24/two_to_four.py
code/after4/later_on.txt

Then running juli with the sample configuration would result in the following:

last_output/chap1/code/script.py
last_output/chap1/code/readme.txt

last_output/chap2/code/script.py
last_output/chap2/code/readme.txt
last_output/chap2/code/between24/two_to_four.py

last_output/chap3/code/script.py
last_output/chap3/code/readme.txt
last_output/chap3/code/between24/two_to_four.py

last_output/chapFour/code/script.py
last_output/chapFour/code/readme.txt
last_output/chapFour/code/between24/two_to_four.py
last_output/chapFour/code/after4/later_on.txt

last_output/chap5.0/code/script.py
last_output/chap5.0/code/readme.txt
last_output/chap5.0/code/after4/later_on.txt

The script.py and two_to_four.py files will be processed for conditional content. The readme.txt and later_on.txt files will be straight copies as they aren’t covered by the Python glob.