<?xml version="1.0" encoding="utf-8" ?>
<page title='Cog Change History'>
<history>
<what when='20051006T222500'>Split out from the main page.</what>
<what when='20080521T090400'>2.1: -U flag</what>
<what when='20080522T065300'>More 2.1 stuff</what>
<what when='20080524T095147'>Add a pointer to the Russian.</what>
<what when='20090520T061826'>Started the 2.2 list.</what>
<what when='20090625T211136'>2.2</what>
<what when='20120205T162700'>2.3</what>
<what when='20150111T202900'>2.4</what>
<what when='20161019T192100'>2.5.1</what>
<what when='20190402T063900'>3.0.0</what>
<what when='20210831T172000'>3.1.0</what>
</history>

<docinfo>An older version of this document is also available in
<a href='code/cog/changes_ru.html'>Russian</a>.
</docinfo>

<p>These are changes to Cog over time.</p>

<h2>Version 3.3.0, November 19 2021</h2>

<ul>
    <li>Added the <b>--check</b> option to check whether files would change if
        run again, for use in continuous integration scenarios.</li>
</ul>


<h2>Version 3.2.0, November 7 2021</h2>

<ul>
    <li>Added the <b>-P</b> option to use print() instead of cog.outl() for code
        output.</li>
</ul>


<h2>Version 3.1.0, August 31 2021</h2>

<ul>
    <li>Fix a problem with Python 3.8.10 and 3.9.5 that require absolute
        paths in sys.path
        (<a href="https://github.com/nedbat/cog/issues/16">issue #16</a>).</li>

    <li>Python 3.9 and 3.10 are supported.</li>
</ul>


<h2>Version 3.0.0, April 2 2019</h2>

<ul>
    <li>Dropped support for Pythons 2.6, 3.3, and 3.4.</li>

    <li>Errors occurring during content generation now print accurate
        tracebacks, showing the correct filename, line number, and source
        line.</li>

    <li>Cog can now (again?) be run as just "cog" on the command line.</li>

    <li>The -p PROLOGUE option was added to specify Python text to prepend to
        embedded code. Thanks, Anders Hovmöller.</li>

    <li>Wildcards in command line arguments will be expanded by cog to help on
        Windows.  Thanks, Hugh Perkins.</li>

    <li>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.</li>

    <li>Moved development to GitHub.</li>
</ul>


<h2>Version 2.5.1, October 19 2016</h2>

<ul>
    <li>Corrected a long-standing oversight: added a LICENSE.txt file.</li>
</ul>

<h2>Version 2.5, February 13 2016</h2>

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

<h2>Version 2.4, January 11 2015</h2>

<ul>
    <li>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.</li>

    <li>A -n=ENCODING option that lets you specify the encoding for the input
        and output files. Thanks, Petr Gladkiy.</li>

    <li>A --verbose option that lets you control how much chatter is in the
        output while cogging.</li>
</ul>

<h2>Version 2.3, February 27 2012</h2>

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


<h2>Version 2.2, June 25 2009</h2>

<ul>
<li>Jython 2.5 is now supported.</li>
<li>Removed a warning about using the no-longer-recommended md5 module.</li>
<li>Removed handyxml: most Cog users don't need it.</li>
</ul>


<h2>Version 2.1, May 22 2008</h2>

<ul>
<li>Added the -U switch to create Unix newlines on Windows.</li>
<li>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.</li>
</ul>


<h2>Version 2.0, October 6 2005</h2>

<p><em>Incompatible changes:</em></p>

<ul>
<li>Python 2.2 is no longer supported.</li>
<li>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.</li>
<li>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.</li>
</ul>

<p>Beneficial changes:</p>

<ul>
<li>The new -d switch removes all the generator code from the output file
while running it to generate output (thanks, Blake).</li>

<li>The new -D switch lets you define global string values for the generators.</li>

<li>The new -s switch lets you mark generated output lines with a suffix.</li>

<li>@-files now can have command line switches in addition to file names.</li>

<li>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).</li>

<li>New cog method #1: cog.error(msg) will raise an error
and end processing without creating a scary Python traceback (thanks, Alexander).</li>

<li>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.</li>

<li>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).</li>
</ul>



<h2>Version 1.4, February 25 2005</h2>

<ul>
<li>Added the -x switch to excise generated output.</li>
<li>Added the -c switch to checksum the generated output.</li>
</ul>



<h2>Version 1.3, December 30 2004</h2>

<ul>
<li>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.</li>
</ul>



<h2>Version 1.2, December 29 2004</h2>

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



<h2>Version 1.12, June 21 2004</h2>

<ul>
<li>Changed all the line endings in the source to the more-portable LF from
the Windows-only CRLF.</li>
</ul>



<h2>Version 1.11, June 5 2004</h2>

<p>Just bug fixes:</p>

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



<h2>Version 1.1, March 21 2004</h2>

<ul>
<li>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.</li>
<li>Ensure the last line of the output ends with a newline, or it will merge
with the end marker, ruining cog's idempotency.</li>
<li>Add the -v command line option, to print the version.</li>
<li>Running cog with no options prints the usage help.</li>
</ul>



<h2>Version 1.0, February 10 2004</h2>

<p>First version.</p>

<!--
# History moved from cogapp.py:
# 20040210: First public version.
# 20040220: Text preceding the start and end marker are removed from Python lines.
#           -v option on the command line shows the version.
# 20040311: Make sure the last line of output is properly ended with a newline.
# 20040605: Fixed some blank line handling in cog.
#           Fixed problems with assigning to xml elements in handyxml.
# 20040621: Changed all line-ends to LF from CRLF.
# 20041002: Refactor some option handling to simplify unittesting the options.
# 20041118: cog.out and cog.outl have optional string arguments.
# 20041119: File names weren't being properly passed around for warnings, etc.
# 20041122: Added cog.firstLineNum: a property with the line number of the [[[cog line.
#           Added cog.inFile and cog.outFile: the names of the input and output file.
# 20041218: Single-line cog generators, with start marker and end marker on
#           the same line.
# 20041230: Keep a single globals dict for all the code fragments in a single
#           file so they can share state.
# 20050206: Added the -x switch to remove all generated output.
# 20050218: Now code can be on the marker lines as well.
# 20050219: Added -c switch to checksum the output so that edits can be
#           detected before they are obliterated.
# 20050521: Added cog.error, contributed by Alexander Belchenko.
# 20050720: Added code deletion and settable globals contributed by Blake Winton.
# 20050724: Many tweaks to improve code coverage.
# 20050726: Error messages are now printed with no traceback.
#           Code can no longer appear on the marker lines,
#               except for single-line style.
#           -z allows omission of the [[[end]]] marker, and it will be assumed
#               at the end of the file.
# 20050729: Refactor option parsing into a separate class, in preparation for
#               future features.
# 20050805: The cogmodule.path wasn't being properly maintained.
# 20050808: Added the -D option to define a global value.
# 20050810: The %s in the -w command is dealt with more robustly.
#           Added the -s option to suffix output lines with a marker.
# 20050817: Now @files can have arguments on each line to change the cog's
#               behavior for that line.
# 20051006: Version 2.0
# 20080521: -U options lets you create Unix newlines on Windows.  Thanks,
#               Alexander Belchenko.
# 20080522: It's now ok to have -d with output to stdout, and now we validate
#               the args after each line of an @file.
# 20090520: Use hashlib where it's available, to avoid a warning.
#           Use the builtin compile() instead of compiler, for Jython.
#           Explicitly close files we opened, Jython likes this.
# 20120205: Port to Python 3.  Lowest supported version is 2.6.
# 20150104: -markers option added by Doug Hellmann.
# 20150104: -n ENCODING option added by Petr Gladkiy.
# 20150107: Added -verbose to control what files get listed.
# 20150111: Version 2.4
# 20160213: v2.5: -o makes needed directories, thanks Jean-François Giraud.
# 20161019: Added a LICENSE.txt file.
-->

<pagecomments/>

</page>
