{"id":16686562,"url":"https://github.com/petli/cobol-sharp","last_synced_at":"2025-04-10T00:16:35.824Z","repository":{"id":62563212,"uuid":"69556560","full_name":"petli/cobol-sharp","owner":"petli","description":"Cobol code revisualiser","archived":false,"fork":false,"pushed_at":"2017-12-27T18:57:17.000Z","size":2705,"stargazers_count":10,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T02:02:59.374Z","etag":null,"topics":["cobol","code-analysis","refactoring"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/petli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-09-29T10:18:53.000Z","updated_at":"2023-10-15T18:55:18.000Z","dependencies_parsed_at":"2022-11-03T15:45:24.934Z","dependency_job_id":null,"html_url":"https://github.com/petli/cobol-sharp","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petli%2Fcobol-sharp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petli%2Fcobol-sharp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petli%2Fcobol-sharp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petli%2Fcobol-sharp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/petli","download_url":"https://codeload.github.com/petli/cobol-sharp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247785942,"owners_count":20995644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cobol","code-analysis","refactoring"],"created_at":"2024-10-12T15:06:15.089Z","updated_at":"2025-04-10T00:16:35.810Z","avatar_url":"https://github.com/petli.png","language":"Python","readme":"# CobolSharp\n\nThis is a tool to extract code structure from COBOL written according\nto mid-80's best practices and revisualize it as more modern code\nstructures.  The purpose is to make it easier to analyze legacy code\nto understand what it does, extract the core business logic, and then\nreimplement it in modern languages.\n\nBut it is not a tool to translate Cobol code fully into a modern\nlanguage, since it only considers the code, not the data.  Even though\nthe output code might look like it could be run if the tool could just\ntranslate the expressions and data structures too, the result would\njust be COBOL code in fancy dress.  The COBOL data model is so far\nremoved from what you'd use in C# or Python that the translated code\nwould not be much less messy to maintain than the original code.\n\nFuture extensions to this tool could usefully start looking at the\ndata, though.  Perhaps not to translate COBOL fully into another\nlanguage, but to show which sections share working storage and move\nlocal variables into functions or even inner scopes.\n\n\n## Example output\n\n\u003ca href=\"https://raw.githubusercontent.com/petli/cobol-sharp/master/doc/example.png\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/petli/cobol-sharp/master/doc/example.png\" width=\"600\"\u003e\n\u003c/a\u003e\n\n(This fragment shows a bit of the first example here:\nhttp://docs.oracle.com/cd/A57673_01/DOC/api/doc/OCI73/apb.htm\nIt was necessary to change `ORA-ERROR` into a section for CobolSharp\nto process it.)\n\n\n## Background\n\nIn COBOL-74 an `if` block was best limited to a few simple\nstatements, avoiding any nested `if` since that would likely end up\nassociating an `else` block with the wrong `if`.  There where no\nsyntax for loops except for performing another section or paragraph\nrepeatedly.  On top of this the layout of each code line had\nrestrictions that discouraged or even disallowed using indentation\nto indicate code structure.\n\nAs a result, what is today implemented with nested, indented code\nblocks was implemented with gotos, typically enforcing a paragraph\nnaming scheme to help get some idea of the code structure.\n\nCOBOL-85 added proper code scope terminators (i.e.  `if ... end-if.`,\nthe switch statement `evaluate` and inline `perform` loops, but much\ncode continued to be written in mostly a COBOL-74 way.\n\n\n# Installation\n\nCobolSharp requires Python 3, and a Java runtime installed in `$PATH`.\nIt has been tested on Linux and Windows, and should work fine on any\nUnix-like system too.  Graphviz is needed to plot code graphs, but not\nfor generating code.\n\nCobolSharp can be installed systemwide from PyPi:\n\n    pip3 install cobolsharp\n\nOr for your own user, to avoid installing as root:\n\n    pip3 install --user cobolsharp\n\nAn executable script (or binary on Windows) called `cobolsharp` is\ninstalled.  If you install with `--user` it may not be in `$PATH`, but in\n`~/.local/bin/cobolsharp`.\n\n\n## From code\n\nYou can also clone the repository at\nhttps://github.com/petli/cobol-sharp and install from the code:\n\n    python3 setup.py install\n\nFor development setup it is recommended to use a `virtualenv`, e.g.:\n\n    virtualenv --python=python3 ~/test/cobolsharp\n    ~/test/cobolsharp/bin/python setup.py develop\n    ~/test/cobolsharp/bin/cobolsharp --help\n\n\n## Unit tests\n\nThere's a small test suite:\n\n    ~/test/cobolsharp/bin/python setup.py test\n\n\n# Usage\n\nRun `cobolsharp --help` to see detailed help on all command line\nflags.\n\nCobolSharp can produce a number of output formats, chosen with the\n`-f` flag:\n\n* `html`: COBOL code and translated code in a web page (default\n  format)\n\n* `code`: translated code written to a source file\n\n* `full_stmt_graph`: A graph of all COBOL statements\n\n* `stmt_graph`: A graph of all reachable COBOL statements\n\n* `cobol_graph`: Cobol code structure graph\n\n* `acyclic_graph`: Code structure graph with loops identified and\n  broken up\n\n* `scope_graph`: Code scope graph where each loop scope and exit nodes\n  have been identified\n\n* `xml`: Koopa XML parse tree, mainly useful during CobolSharp\n  development\n\n\n## Cross-referencing code\n\nThe `html` format (the default) creates a standalone web page with\nboth the original COBOL code and the translated code side-by-side.\n\nClicking a line in either of the code columns will scroll to and\nhighlight the corresponding line in the other one (if there is one).\n\nLarger code blocks (currently five lines or more) in the translated\nsource can be folded and unfolded.  There's a set of buttons to\nfold/unfold everything or all function levels.\n\n`perform` and `goto` statements in the translated source have a small\nlink button in the margin, which navigates to the definition of the\nreferenced section or label.  Browser navigation can be used to go\nback and forward between visited sections of the code.\n\nThe indentation level in the translated code is colour-coded, and the\ncorresponding line in the COBOL code has the same colour.  This can be\nturned off with checkboxes.\n\nLine numbers and navigation buttons can be turned off to make it easy\nto cut-and-paste code from the page into a separate file.\n\n\n## Plotting graphs\n\nThe graph formats produce `.dot` files.  They can be plotted into PNGs\n(and many other formats) with graphviz, e.g.:\n\n    dot -Tpng -O *.dot\n\n\n## Limitations\n\nThis tool will only work well for code that follows best practices on\nwriting structured COBOL.  Mainly:\n\n* There are no cross-section `go to` jumps.\n\n* `perform` is only used to pass control to a single section, not a\n  suite of them or of individual paragraphs.  I.e. a section\n  must behave as function.\n\nIn addition the tool only understands the COBOL supported by the Koopa\nparser, and may not handle all statements correctly even if they are\nparsed well.  See the project issue list for current outstanding\nissues, and log a new issue, preferably with example code, if you find\nsomething more.\n\n\n# Translation process\n\nThe COBOL code is parsed by Koopa into an XML parse tree, which is\ntranslated into a graph of statements.  This is refined in several\nsteps to identify structured code.  For details on this, see the\ndocumentation strings and comments in `CobolSharp/graph.py`.\n\nThe final graph is then flattened into linear code.  Several\nstrategies are used to decide which representation to use, a trade-off\nbetween avoiding code jumps but also not producing very deeply nested\ncode.  For details on these strategies see the code comments in\n`CobolSharp/analyze.py`.  The weightings used in these decisions can\nno doubt be tuned to produce better output, and any improvements on\nthem are most welcome.\n\nThe code is flattened for a local optimization, without attempting to\nfind the optimal representation for a larger section of the code\ngraph.  This can also be an area for improvements.\n\nThe `--debug` command line flag will insert comments into the\ntranslated source (overwriting any comments in the same place in the\noriginal source) explaining the decisions taken at each loop and\nbranch statement.\n\n\n## But the translated code still contains gotos!\n\nYes, unfortunately it often will.  There are pathological cases which\ncannot be resolved in a structured way (see\ne.g. `test/crossedbranches.cbl`), but the the trade-off mentioned\nabove will also keep some gotos in more complex code, and maybe even\nadd labels that aren't in the original COBOL code.  This is another\nreason why this is mainly a tool to better understand COBOL code, not\na tool to translate it fully.\n\n\n# License\n\nCopyright (C) 2017 Peter Liljenberg \u003cpeter.liljenberg@gmail.com\u003e\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n\n## Koopa\n\nThe Koopa parser generator is distributed under a BSD license.  See\nhttp://koopa.sourceforge.net/ for more information.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetli%2Fcobol-sharp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpetli%2Fcobol-sharp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetli%2Fcobol-sharp/lists"}