Created 6 October 2005, last updated 31 August 2021

An older version of this document is also available in Russian.

These are changes to Cog over time.

Version 3.3.0, November 19 2021

• Added the --check option to check whether files would change if run again, for use in continuous integration scenarios.

Version 3.2.0, November 7 2021

• Added the -P option to use print() instead of cog.outl() for code output.

Version 3.1.0, August 31 2021

• Fix a problem with Python 3.8.10 and 3.9.5 that require absolute paths in sys.path (issue #16).
• Python 3.9 and 3.10 are supported.

Version 3.0.0, April 2 2019

• Dropped support for Pythons 2.6, 3.3, and 3.4.
• Errors occurring during content generation now print accurate tracebacks, showing the correct filename, line number, and source line.
• Cog can now (again?) be run as just “cog” on the command line.
• The -p PROLOGUE option was added to specify Python text to prepend to embedded code. Thanks, Anders Hovmöller.
• Wildcards in command line arguments will be expanded by cog to help on Windows. Thanks, Hugh Perkins.
• When using implicitly imported “cog”, a new module is made for each run. This is important when using the cog API multi-threaded. Thanks, Daniel Murdin.
• Moved development to GitHub.

Version 2.5.1, October 19 2016

• Corrected a long-standing oversight: added a LICENSE.txt file.

Version 2.5, February 13 2016

• When specifying an output file with -o, directories will be created as needed to write the file. Thanks, Jean-François Giraud.

Version 2.4, January 11 2015

• A --markers option lets you control the three markers that separate the cog code and result from the rest of the file. Thanks, Doug Hellmann.
• A -n=ENCODING option that lets you specify the encoding for the input and output files. Thanks, Petr Gladkiy.
• A --verbose option that lets you control how much chatter is in the output while cogging.

Version 2.3, February 27 2012

• Python 3 is now supported. Older Pythons (2.5 and below) no longer are.
• Added the cog.previous attribute to get the output from the last time cog was run.
• An input file name of “-” will read input from standard in.
• Cog can now be run with “python -m cogapp [args]”.
• All files are assumed to be encoded with UTF-8.

Version 2.2, June 25 2009

• Jython 2.5 is now supported.
• Removed a warning about using the no-longer-recommended md5 module.
• Removed handyxml: most Cog users don’t need it.

Version 2.1, May 22 2008

• Added the -U switch to create Unix newlines on Windows.
• Improved argument validation: -d can be used with stdout-destined output, and switches are validated for every line of an @file, to prevent bad interactions.

Version 2.0, October 6 2005

Incompatible changes:

• Python 2.2 is no longer supported.
• In 1.4, you could put some generator code on the [[[cog line and some on the ]]] line, to make the generators more compact. Unfortunately, this also made it more difficult to seamlessly embed those markers in source files of all kinds. Now code is only allowed on marker lines when the entire generator is single-line.
• In 1.x, you could leave out the [[[end]]] marker, and it would be assumed at the end of the file. Now that behavior must be enabled with a -z switch. Without the switch, omitting the end marker is an error.

Beneficial changes:

• The new -d switch removes all the generator code from the output file while running it to generate output (thanks, Blake).
• The new -D switch lets you define global string values for the generators.
• The new -s switch lets you mark generated output lines with a suffix.
• @-files now can have command line switches in addition to file names.
• Cog error messages now print without a traceback, and use a format similar to compiler error messages, so that clicking the message will likely bring you to the spot in your code (thanks, Mike).
• New cog method #1: cog.error(msg) will raise an error and end processing without creating a scary Python traceback (thanks, Alexander).
• New cog method #2: cog.msg(msg) will print the msg to stdout. This is better than print because it allows for all cog output to be managed through Cog.
• The sequence of Cog marker lines is much stricter. This helps to ensure that Cog isn’t eating up your precious source code (thanks, Kevin).

Version 1.4, February 25 2005

• Added the -x switch to excise generated output.
• Added the -c switch to checksum the generated output.

Version 1.3, December 30 2004

• All of the generators in a single file are now run with a common globals dictionary, so that state may be carried from one to the next.

Version 1.2, December 29 2004

• Added module attributes cog.inFile, cog.outFile, and cog.firstLineNum.
• Made the sOut argument optional in cog.out and cog.outl.
• Added the compact one-line form of cog markers.
• Some warning messages weren’t properly printing the file name.

Version 1.12, June 21 2004

• Changed all the line endings in the source to the more-portable LF from the Windows-only CRLF.

Version 1.11, June 5 2004

Just bug fixes:

• Cog’s whitespace handling deals correctly with a completely blank line (no whitespace at all) in a chunk of Cog code.
• Elements returned by handyxml can now have attributes assigned to them after parsing.

Version 1.1, March 21 2004

• Now if the cog marker lines and all the lines they contain have the same prefix characters, then the prefix is removed from each line. This allows cog to be used with languages that don’t support multi-line comments.
• Ensure the last line of the output ends with a newline, or it will merge with the end marker, ruining cog’s idempotency.
• Add the -v command line option, to print the version.
• Running cog with no options prints the usage help.

Version 1.0, February 10 2004

First version.