vcs-to-changelog: Rename vcs_to_changelog.py to use hyphens.

This was needed earlier because modules had to import the main script,
but that is no longer true.  Rename the script so that it is
consistent with all other scripts in gnulib and uses hyphens.

* build-aux/vcs_to_changelog.py: Rename to...
* build-aux/vcs-to-changelog.py: ... this.
* doc/vcs-to-changelog.texi (VCS To ChangeLog): Update reference.
* modules/vcs-to-changelog: Likewise.

1 files changed, 133 insertions, 0 deletions

diff --git a/build-aux/vcs-to-changelog.py b/build-aux/vcs-to-changelog.py
new file mode 100755
index 0000000000..bf4bc7cf64
--- /dev/null
+++ b/build-aux/vcs-to-changelog.py
@@ -0,0 +1,133 @@
+#!/usr/bin/python3
+# Main VCSToChangeLog script.
+# Copyright (C) 2019-2020 Free Software Foundation, Inc.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+''' Generate a ChangeLog style output based on a VCS log.
+
+This script takes two revisions as input and generates a ChangeLog style output
+for all revisions between the two revisions.
+
+This script is intended to be executed from the project parent directory.
+
+The vcstocl directory has a file vcstocl_quirks.py that defines a
+function called get_project_quirks that returns a object of class type
+ProjectQuirks or a subclass of the same.  The definition of the ProjectQuirks
+class is below and it specifies the properties that the project must set to
+ensure correct parsing of its contents.
+
+Among other things, ProjectQurks specifies the VCS to read from; the default is
+assumed to be git.  The script then studies the VCS log and for each change,
+list out the nature of changes in the constituent files.
+
+Each file type may have parser frontends that can read files and construct
+objects that may be compared to determine the minimal changes that occured in
+each revision.  For files that do not have parsers, we may only know the nature
+of changes at the top level depending on the information that the VCS stores.
+
+The parser frontend must have a compare() method that takes the old and new
+files as arrays of strings and prints the output in ChangeLog format.
+
+Currently implemented VCS:
+
+    git
+
+Currently implemented frontends:
+
+    C
+'''
+import sys
+import os
+import re
+import argparse
+from vcstocl.misc_util import *
+from vcstocl import frontend_c
+from vcstocl.vcs_git import *
+
+debug = DebugUtil(False)
+
+class ProjectQuirks:
+    # This is a list of regex substitutions for C/C++ macros that are known to
+    # break parsing of the C programs.  Each member of this list is a dict with
+    # the key 'orig' having the regex and 'sub' having the substitution of the
+    # regex.
+    MACRO_QUIRKS = []
+
+    # This is a list of macro definitions that are extensively used and are
+    # known to break parsing due to some characteristic, mainly the lack of a
+    # semicolon at the end.
+    C_MACROS = []
+
+    # The repo type, defaults to git.
+    repo = 'git'
+
+    # List of files to ignore either because they are not needed (such as the
+    # ChangeLog) or because they are non-parseable.  For example, glibc has a
+    # header file that is only assembly code, which breaks the C parser.
+    IGNORE_LIST = ['ChangeLog']
+
+sys.path.append('/'.join([os.path.dirname(os.path.realpath(__file__)),
+                'vcstocl']))
+
+def main(repo, frontends, refs):
+    ''' ChangeLog Generator Entry Point.
+    '''
+    commits = repo.list_commits(args.refs)
+    for commit in commits:
+        repo.list_changes(commit, frontends)
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument('refs', metavar='ref', type=str, nargs=2,
+                     help='Refs to print ChangeLog entries between')
+
+    parser.add_argument('-d', '--debug', required=False, action='store_true',
+                     help='Run the file parser debugger.')
+
+    parser.add_argument('-q', '--quirks', required=False, type=str,
+                     help='Load a quirks file.')
+
+    args = parser.parse_args()
+
+    debug.debug = args.debug
+
+    if len(args.refs) < 2:
+        debug.eprint('Two refs needed to get a ChangeLog.')
+        sys.exit(os.EX_USAGE)
+
+    # Load quirks file.  We assume that the script is run from the top level source
+    # directory.
+    if args.quirks:
+        import importlib.util
+        spec = importlib.util.spec_from_file_location("vcstocl_quirks", args.quirks)
+        vcstocl_quirks = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(vcstocl_quirks)
+        project_quirks = vcstocl_quirks.get_project_quirks(debug)
+    else:
+        try:
+            from vcstocl_quirks import *
+            project_quirks = get_project_quirks(debug)
+        except:
+            project_quirks = ProjectQuirks()
+
+    REPO = {'git': GitRepo(project_quirks.IGNORE_LIST, debug)}
+
+    fe_c = frontend_c.Frontend(project_quirks, debug)
+    FRONTENDS = {'.c': fe_c,
+                 '.h': fe_c}
+
+    main(REPO[project_quirks.repo], FRONTENDS, args.refs)