{
    "info": {
        "author": "Renata Hodovan, Akos Kiss",
        "author_email": "hodovan@inf.u-szeged.hu, akiss@inf.u-szeged.hu",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "=============\nGrammarinator\n=============\n*ANTLRv4 grammar-based test generator*\n\n.. image:: https://badge.fury.io/py/grammarinator.svg\n   :target: https://badge.fury.io/py/grammarinator\n.. image:: https://travis-ci.org/renatahodovan/grammarinator.svg?branch=master\n   :target: https://travis-ci.org/renatahodovan/grammarinator\n.. image:: https://ci.appveyor.com/api/projects/status/0f1vm5x9j9j31hpo/branch/master?svg=true\n   :target: https://ci.appveyor.com/project/renatahodovan/grammarinator/branch/master\n.. image:: https://coveralls.io/repos/github/renatahodovan/grammarinator/badge.svg\n   :target: https://coveralls.io/github/renatahodovan/grammarinator\n\n*Grammarinator* is a random test generator / fuzzer that creates test cases\naccording to an input ANTLR_ v4 grammar. The motivation behind this\ngrammar-based approach is to leverage the large variety of publicly\navailable `ANTLR v4 grammars`_.\n\n.. _`ANTLR v4 grammars`: https://github.com/antlr/grammars-v4\n\n\nRequirements\n============\n\n* Python_ >= 3.4\n* pip_ and setuptools Python packages (the latter is automatically installed by\n  pip).\n* ANTLR_ v4\n\n.. _Python: https://www.python.org\n.. _pip: https://pip.pypa.io\n.. _ANTLR: http://www.antlr.org\n\n\nInstall\n=======\n\nThe quick way::\n\n    pip3 install grammarinator\n\nOr clone the project and run setuptools::\n\n    python3 setup.py install\n\n\nUsage\n=====\n\nAs a first step, *grammarinator* takes an `ANTLR v4`_ grammar and creates a test\ngenerator script in Python3. Such a generator can be subclassed later to\ncustomize it further if needed.\n\nExample usage to create a test generator::\n\n    grammarinator-process <grammar-file(s)> -o <output-directory> --no-actions\n\n.. _`ANTLR v4`: https://github.com/antlr/grammars-v4\n\n**Notes**\n\nGrammarinator uses the `ANTLR v4`_ grammar format as its input, which makes\nexisting grammars (lexer and parser rules) easily reusable. However, because\nof the inherently different goals of a fuzzer and a parser, inlined code\n(actions and conditions, header and member blocks) are most probably not\nreusable, or even preventing proper execution. For first experiments with\nexisting grammar files, ``grammarinator-process`` supports the command-line\noption ``--no-actions``, which skips all such code blocks during fuzzer\ngeneration. Once inlined code is tuned for fuzzing, that option may be omitted.\n\nAfter having generated and optionally customized a fuzzer, it can be executed\neither by the ``grammarinator-generate`` script or by instantiating it\nmanually.\n\nExample usage of ``grammarinator-generate``::\n\n    grammarinator-generate -l <unlexer> -p <unparser> -r <start-rule> -d <max-depth> \\\n    -o <output-pattern> -n <number-of-tests> \\\n    -t <one-or-more-transformer>\n\n**Notes**\n\nReal-life grammars often use recursive rules to express certain patterns.\nHowever, when using such rule(s) for generation, we can easily end up in an\nunexpectedly deep call stack. With the ``--max-depth`` or ``-d`` options, this\ndepth - and also the size of the generated test cases - can be controlled.\n\nAnother speciality of the ANTLR grammars is that they support the so-called\nhidden tokens. These rules typically describe such elements of the target\nlanguage that can be placed basically anywhere without breaking the syntax. The\nmost common examples are comments or whitespaces. However, when using these\ngrammars - which don't define explicitly where whitespace may or may not appear\nin rules - to generate test cases, we have to insert the missing spaces\nmanually. This can be done by applying various transformers (with the ``-t``\noption) to the tree representation of the output tests. A simple transformer -\nthat inserts a space after every unparser rule - is provided by grammarinator\n(``grammarinator.runtime.simple_space_transformer``).\n\nAs a final thought, one must not forget that the original purpose of grammars\nis the syntax-wise validation of various inputs. As a consequence, these\ngrammars encode syntactic expectations only, and not semantic rules. If we\nstill want to add semantic knowledge into the generated test, then we can\ninherit custom fuzzers from the generated ones and redefine methods\ncorresponding to lexer or parser rules in ways that encode the required\nknowledge (e.g.: HTMLCustomUnparser_).\n\n.. _HTMLCustomUnparser: examples/fuzzer/HTMLCustomUnparser.py\n\nWorking Example\n===============\n\nThe repository contains a minimal example_ to generate HTML files. To give it\na try, run the processor first::\n\n    grammarinator-process examples/grammars/HTMLLexer.g4 \\\n    examples/grammars/HTMLParser.g4 -o examples/fuzzer/\n\n\nThen, use the generator to produce test cases::\n\n    grammarinator-generate -l examples/fuzzer/HTMLCustomUnlexer.py \\\n    -p examples/fuzzer/HTMLCustomUnparser.py -r htmlDocument \\\n    -o examples/tests/test_%d.html -t HTMLUnparser.html_space_transformer -n 100 -d 20\n\n.. _example: examples/\n\n\nCompatibility\n=============\n\n*grammarinator* was tested on:\n\n* Linux (Ubuntu 16.04 / 18.04)\n* Mac OS X (Sierra 10.12 / High Sierra 10.13 / Mojave 10.14)\n\n\nCitations\n=========\n\nBackground on *grammarinator* is published in (R. Hodovan, A. Kiss, T. Gyimothy:\n\"Grammarinator: A Grammar-Based Open Source Fuzzer\", A-TEST 2018).\n\n\nCopyright and Licensing\n=======================\n\nLicensed under the BSD 3-Clause License_.\n\n.. _LICENSE: LICENSE.rst",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/renatahodovan/grammarinator",
        "keywords": "",
        "license": "BSD",
        "maintainer": "",
        "maintainer_email": "",
        "name": "grammarinator",
        "package_url": "https://pypi.org/project/grammarinator/",
        "platform": "",
        "project_url": "https://pypi.org/project/grammarinator/",
        "project_urls": {
            "Homepage": "https://github.com/renatahodovan/grammarinator"
        },
        "release_url": "https://pypi.org/project/grammarinator/19.3/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Grammarinator: Grammar-based Random Test Generator",
        "version": "19.3"
    },
    "last_serial": 5007255,
    "releases": {
        "17.5": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "73648669e4d431ef623517f56b421cf9",
                    "sha256": "b2d333a2459d11709a657bc35dc43de0e38be8bc301bebd3fc95dd3f505eb05e"
                },
                "downloads": -1,
                "filename": "grammarinator-17.5.tar.gz",
                "has_sig": false,
                "md5_digest": "73648669e4d431ef623517f56b421cf9",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20980,
                "upload_time": "2017-05-15T14:20:54",
                "url": "https://files.pythonhosted.org/packages/8b/0d/260470cb25d1a37c01c876cfe8cc595bb390a3661eea5549b28bedf9ba39/grammarinator-17.5.tar.gz"
            }
        ],
        "17.7": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "bced081f232f3fe4912338d882ebbda3",
                    "sha256": "8a202ed34a539491fd5b1eaf9dba0dd058151f240b06ec521ff2b3b7ba64a46a"
                },
                "downloads": -1,
                "filename": "grammarinator-17.7.tar.gz",
                "has_sig": false,
                "md5_digest": "bced081f232f3fe4912338d882ebbda3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 25384,
                "upload_time": "2017-07-26T22:42:38",
                "url": "https://files.pythonhosted.org/packages/84/3c/20930a93bed87a4c07a2cd7d6dc039515ba60d550b5b94405ad572588552/grammarinator-17.7.tar.gz"
            }
        ],
        "18.10": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "e3d0502779a3b9151d832ae41a07dc81",
                    "sha256": "6d383f9ab1a77759401ede2672cb80897c2ca6a0b433fa167fb691656ba7cc73"
                },
                "downloads": -1,
                "filename": "grammarinator-18.10.tar.gz",
                "has_sig": false,
                "md5_digest": "e3d0502779a3b9151d832ae41a07dc81",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 31618,
                "upload_time": "2018-10-31T18:10:15",
                "url": "https://files.pythonhosted.org/packages/57/90/b127232790796ec5c9117ff0aad822c5af72a895ce6e2e7c92922fbcaf18/grammarinator-18.10.tar.gz"
            }
        ],
        "19.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "7323fcd1742f8cb8591b05fc5cf7f229",
                    "sha256": "d9c0490c07612d0393090cda9b697c3395f52cc1a7c76acfb91fc6bafb7390ce"
                },
                "downloads": -1,
                "filename": "grammarinator-19.3.tar.gz",
                "has_sig": false,
                "md5_digest": "7323fcd1742f8cb8591b05fc5cf7f229",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 34172,
                "upload_time": "2019-03-30T14:45:33",
                "url": "https://files.pythonhosted.org/packages/b0/77/d50d5ddc09c86354363f7c1f32ef87f55ed9b025c4cc127b6f6305bf6531/grammarinator-19.3.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "7323fcd1742f8cb8591b05fc5cf7f229",
                "sha256": "d9c0490c07612d0393090cda9b697c3395f52cc1a7c76acfb91fc6bafb7390ce"
            },
            "downloads": -1,
            "filename": "grammarinator-19.3.tar.gz",
            "has_sig": false,
            "md5_digest": "7323fcd1742f8cb8591b05fc5cf7f229",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 34172,
            "upload_time": "2019-03-30T14:45:33",
            "url": "https://files.pythonhosted.org/packages/b0/77/d50d5ddc09c86354363f7c1f32ef87f55ed9b025c4cc127b6f6305bf6531/grammarinator-19.3.tar.gz"
        }
    ]
}