# JSGF Grammar Tools
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A Python library for parsing and generating strings from JSGF (Java Speech Grammar Format) grammars. This modernized version supports Python 3.7+ and includes comprehensive testing.
## Features
- **Parser**: Convert JSGF grammar files into abstract syntax trees
- **Deterministic Generator**: Generate all possible strings from non-recursive grammars
- **Probabilistic Generator**: Generate random strings using weights and probabilities
- **Modern Python**: Full Python 3.7+ support with type hints and proper packaging
- **Comprehensive Testing**: Full test suite with pytest
## Installation
### From Source
```bash
git clone https://github.com/syntactic/JSGFTools.git
cd JSGFTools
pip install -e .
```
### Development Setup
```bash
git clone https://github.com/syntactic/JSGFTools.git
cd JSGFTools
pip install -r requirements-dev.txt
```
## Quick Start
### Command Line Usage
Generate all possible strings from a non-recursive grammar:
```bash
python DeterministicGenerator.py IdeasNonRecursive.gram
```
Generate 20 random strings from a grammar (supports recursive rules):
```bash
python ProbabilisticGenerator.py Ideas.gram 20
```
### Python API Usage
```python
import JSGFParser as parser
import DeterministicGenerator as det_gen
import ProbabilisticGenerator as prob_gen
from io import StringIO
# Parse a grammar
grammar_text = """
public <greeting> = hello | hi;
public <target> = world | there;
public <start> = <greeting> <target>;
"""
with StringIO(grammar_text) as f:
grammar = parser.getGrammarObject(f)
# Generate all possibilities (deterministic)
det_gen.grammar = grammar
rule = grammar.publicRules[2] # <start> rule
all_strings = det_gen.processRHS(rule.rhs)
print("All possible strings:", all_strings)
# Generate random string (probabilistic)
prob_gen.grammar = grammar
random_string = prob_gen.processRHS(rule.rhs)
print("Random string:", random_string)
```
## Grammar Format
JSGFTools supports most of the JSGF specification:
```jsgf
// Comments are supported
public <start> = <greeting> <target>;
// Alternatives with optional weights
<greeting> = /5/ hello | /1/ hi | hey;
// Optional elements
<polite> = [ please ];
// Nonterminal references
<target> = world | there;
// Recursive rules (use with ProbabilisticGenerator only)
<recursive> = base | <recursive> more;
```
### Supported Features
- Rule definitions and nonterminal references
- Alternatives (|) with optional weights (/weight/)
- Optional elements ([...])
- Grouping with parentheses
- Comments (// and /* */)
- Public and private rules
### Not Yet Supported
- Kleene operators (* and +)
- Import statements
- Tags
## Important Notes
### Recursive vs Non-Recursive Grammars
- **DeterministicGenerator**: Only use with non-recursive grammars to avoid infinite loops
- **ProbabilisticGenerator**: Can safely handle recursive grammars through probabilistic termination
**Example of recursive rule:**
```jsgf
<sentence> = <noun> <verb> | <sentence> and <sentence>;
```
## Testing
Run the test suite:
```bash
pytest test_jsgf_tools.py -v
```
Run specific test categories:
```bash
pytest test_jsgf_tools.py::TestJSGFParser -v # Parser tests
pytest test_jsgf_tools.py::TestIntegration -v # Integration tests
```
## Documentation
For detailed API documentation, build the Sphinx docs:
```bash
cd docs
make html
```
Then open `docs/_build/html/index.html` in your browser.
## Example Files
- `Ideas.gram`: Recursive grammar example (use with ProbabilisticGenerator)
- `IdeasNonRecursive.gram`: Non-recursive grammar example (use with DeterministicGenerator)
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite: `pytest`
6. Submit a pull request
## License
MIT License. See [LICENSE](LICENSE) file for details.
## Version History
- **2.0.0**: Complete Python 3 modernization, added test suite, improved packaging
- **1.x**: Original Python 2.7 version
Raw data
{
"_id": null,
"home_page": "https://github.com/syntactic/JSGFTools",
"name": "jsgf-tools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "jsgf, grammar, speech recognition, nlp, parsing, generation, unicode, testing",
"author": "Past\u00e8que Ho",
"author_email": "Past\u00e8que Ho <timothyakho@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4a/7f/34931cd5fd8ad4173e06053ad88dc0a64cbcd6c0611c78d18e84a8ef7177/jsgf_tools-2.1.0.tar.gz",
"platform": null,
"description": "# JSGF Grammar Tools\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA Python library for parsing and generating strings from JSGF (Java Speech Grammar Format) grammars. This modernized version supports Python 3.7+ and includes comprehensive testing.\n\n## Features\n\n- **Parser**: Convert JSGF grammar files into abstract syntax trees\n- **Deterministic Generator**: Generate all possible strings from non-recursive grammars\n- **Probabilistic Generator**: Generate random strings using weights and probabilities\n- **Modern Python**: Full Python 3.7+ support with type hints and proper packaging\n- **Comprehensive Testing**: Full test suite with pytest\n\n## Installation\n\n### From Source\n```bash\ngit clone https://github.com/syntactic/JSGFTools.git\ncd JSGFTools\npip install -e .\n```\n\n### Development Setup\n```bash\ngit clone https://github.com/syntactic/JSGFTools.git\ncd JSGFTools\npip install -r requirements-dev.txt\n```\n\n## Quick Start\n\n### Command Line Usage\n\nGenerate all possible strings from a non-recursive grammar:\n```bash\npython DeterministicGenerator.py IdeasNonRecursive.gram\n```\n\nGenerate 20 random strings from a grammar (supports recursive rules):\n```bash\npython ProbabilisticGenerator.py Ideas.gram 20\n```\n\n### Python API Usage\n\n```python\nimport JSGFParser as parser\nimport DeterministicGenerator as det_gen\nimport ProbabilisticGenerator as prob_gen\nfrom io import StringIO\n\n# Parse a grammar\ngrammar_text = \"\"\"\npublic <greeting> = hello | hi;\npublic <target> = world | there;\npublic <start> = <greeting> <target>;\n\"\"\"\n\nwith StringIO(grammar_text) as f:\n grammar = parser.getGrammarObject(f)\n\n# Generate all possibilities (deterministic)\ndet_gen.grammar = grammar\nrule = grammar.publicRules[2] # <start> rule\nall_strings = det_gen.processRHS(rule.rhs)\nprint(\"All possible strings:\", all_strings)\n\n# Generate random string (probabilistic)\nprob_gen.grammar = grammar\nrandom_string = prob_gen.processRHS(rule.rhs)\nprint(\"Random string:\", random_string)\n```\n\n## Grammar Format\n\nJSGFTools supports most of the JSGF specification:\n\n```jsgf\n// Comments are supported\npublic <start> = <greeting> <target>;\n\n// Alternatives with optional weights\n<greeting> = /5/ hello | /1/ hi | hey;\n\n// Optional elements\n<polite> = [ please ];\n\n// Nonterminal references\n<target> = world | there;\n\n// Recursive rules (use with ProbabilisticGenerator only)\n<recursive> = base | <recursive> more;\n```\n\n### Supported Features\n- Rule definitions and nonterminal references\n- Alternatives (|) with optional weights (/weight/)\n- Optional elements ([...])\n- Grouping with parentheses\n- Comments (// and /* */)\n- Public and private rules\n\n### Not Yet Supported\n- Kleene operators (* and +)\n- Import statements\n- Tags\n\n## Important Notes\n\n### Recursive vs Non-Recursive Grammars\n\n- **DeterministicGenerator**: Only use with non-recursive grammars to avoid infinite loops\n- **ProbabilisticGenerator**: Can safely handle recursive grammars through probabilistic termination\n\n**Example of recursive rule:**\n```jsgf\n<sentence> = <noun> <verb> | <sentence> and <sentence>;\n```\n\n## Testing\n\nRun the test suite:\n```bash\npytest test_jsgf_tools.py -v\n```\n\nRun specific test categories:\n```bash\npytest test_jsgf_tools.py::TestJSGFParser -v # Parser tests\npytest test_jsgf_tools.py::TestIntegration -v # Integration tests\n```\n\n## Documentation\n\nFor detailed API documentation, build the Sphinx docs:\n```bash\ncd docs\nmake html\n```\n\nThen open `docs/_build/html/index.html` in your browser.\n\n## Example Files\n\n- `Ideas.gram`: Recursive grammar example (use with ProbabilisticGenerator)\n- `IdeasNonRecursive.gram`: Non-recursive grammar example (use with DeterministicGenerator)\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite: `pytest`\n6. Submit a pull request\n\n## License\n\nMIT License. See [LICENSE](LICENSE) file for details.\n\n## Version History\n\n- **2.0.0**: Complete Python 3 modernization, added test suite, improved packaging\n- **1.x**: Original Python 2.7 version\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Complete JSGF toolkit: parse, generate, and test speech grammars with Unicode support",
"version": "2.1.0",
"project_urls": {
"Documentation": "https://github.com/syntactic/JSGFTools#readme",
"Homepage": "https://github.com/syntactic/JSGFTools",
"Issues": "https://github.com/syntactic/JSGFTools/issues",
"Repository": "https://github.com/syntactic/JSGFTools"
},
"split_keywords": [
"jsgf",
" grammar",
" speech recognition",
" nlp",
" parsing",
" generation",
" unicode",
" testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e1ce43f1fb72fb9c996899946020ccb2048b8be7cde38453e80d33d3201279f2",
"md5": "63b3c8b49d932e0b559b500ab0d29a7b",
"sha256": "44753857a3169edb24a6db9af15157bf81cc4faf8a25622c9d0c0a5af09378a5"
},
"downloads": -1,
"filename": "jsgf_tools-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "63b3c8b49d932e0b559b500ab0d29a7b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 28092,
"upload_time": "2025-10-06T03:23:22",
"upload_time_iso_8601": "2025-10-06T03:23:22.996257Z",
"url": "https://files.pythonhosted.org/packages/e1/ce/43f1fb72fb9c996899946020ccb2048b8be7cde38453e80d33d3201279f2/jsgf_tools-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4a7f34931cd5fd8ad4173e06053ad88dc0a64cbcd6c0611c78d18e84a8ef7177",
"md5": "76718c6960a50b5e863046d340df00a0",
"sha256": "3e716d3d7f888ab6bdb22bcf6643a1a902307e516d235b2b5cfeb0e2768479db"
},
"downloads": -1,
"filename": "jsgf_tools-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "76718c6960a50b5e863046d340df00a0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 25773,
"upload_time": "2025-10-06T03:23:24",
"upload_time_iso_8601": "2025-10-06T03:23:24.447957Z",
"url": "https://files.pythonhosted.org/packages/4a/7f/34931cd5fd8ad4173e06053ad88dc0a64cbcd6c0611c78d18e84a8ef7177/jsgf_tools-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 03:23:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "syntactic",
"github_project": "JSGFTools",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "jsgf-tools"
}
JSON
