Skip to content

Commit 7e1ef15

Browse files
Copilothzhangxyz
andcommitted
Simplify documentation per feedback: condense Support Packages section and remove API Reference, Examples, Testing, and Development sections
Co-authored-by: hzhangxyz <[email protected]>
1 parent 1b7ac6c commit 7e1ef15

File tree

2 files changed

+1
-215
lines changed

2 files changed

+1
-215
lines changed

README.md

Lines changed: 1 addition & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -346,42 +346,7 @@ Each example demonstrates logical inference using propositional logic axioms.
346346

347347
## Support Packages
348348

349-
The DS project includes additional support packages that extend functionality:
350-
351-
### BNF Conversion Library
352-
353-
Located in the `/bnf` directory, this package provides bidirectional conversion between DS syntax formats:
354-
355-
- **apyds-bnf** (Python): [PyPI](https://pypi.org/project/apyds-bnf/)
356-
- **atsds-bnf** (JavaScript): [npm](https://www.npmjs.com/package/atsds-bnf)
357-
358-
The BNF library converts between:
359-
- **Ds format**: S-expression (lisp-like) syntax used internally by DS
360-
- **Dsp format**: Traditional, human-readable syntax with infix operators
361-
362-
This makes it easier to write logical rules in a natural mathematical notation and convert them to/from the DS internal format.
363-
364-
**Installation:**
365-
```bash
366-
# Python
367-
pip install apyds-bnf
368-
369-
# JavaScript
370-
npm install atsds-bnf
371-
```
372-
373-
**Quick example:**
374-
```python
375-
from apyds_bnf import parse, unparse
376-
377-
# Convert readable syntax to DS format
378-
parse("a, b -> c") # Returns: "a\nb\n----\nc"
379-
380-
# Convert DS format to readable syntax
381-
unparse("a\nb\n----\nc") # Returns: "a, b -> c"
382-
```
383-
384-
For more details, see the [BNF package README](/bnf/README.md).
349+
- **BNF Conversion Library** ([apyds-bnf](https://pypi.org/project/apyds-bnf/), [atsds-bnf](https://www.npmjs.com/package/atsds-bnf)): Bidirectional conversion between DS syntax formats. See [/bnf](/bnf) for details.
385350

386351
## Development
387352

bnf/README.md

Lines changed: 0 additions & 179 deletions
Original file line numberDiff line numberDiff line change
@@ -125,130 +125,6 @@ For structured terms:
125125
| Unary operator (unparse output) | `(~ a) -> b` | `(unary ~ a)\n-----------\nb` |
126126
| Complex expression | `((a + b) * c), d[i] -> f(g, h)` | `(binary * (binary + a b) c)\n(subscript d i)\n---------------------------\n(function f g h)` |
127127

128-
## API Reference
129-
130-
### Python
131-
132-
#### `parse(dsp_text: str) -> str`
133-
134-
Converts Dsp syntax to Ds syntax.
135-
136-
**Parameters:**
137-
- `dsp_text`: String in Dsp format (human-readable syntax)
138-
139-
**Returns:**
140-
- String in Ds format (S-expression syntax)
141-
142-
**Example:**
143-
```python
144-
from apyds_bnf import parse
145-
146-
result = parse("a, b -> c")
147-
# Returns: "a\nb\n----\nc"
148-
```
149-
150-
#### `unparse(ds_text: str) -> str`
151-
152-
Converts Ds syntax to Dsp syntax.
153-
154-
**Parameters:**
155-
- `ds_text`: String in Ds format (S-expression syntax)
156-
157-
**Returns:**
158-
- String in Dsp format (human-readable syntax)
159-
160-
**Example:**
161-
```python
162-
from apyds_bnf import unparse
163-
164-
result = unparse("a\nb\n----\nc")
165-
# Returns: "a, b -> c"
166-
```
167-
168-
### JavaScript
169-
170-
#### `parse(dspText: string): string`
171-
172-
Converts Dsp syntax to Ds syntax.
173-
174-
**Parameters:**
175-
- `dspText`: String in Dsp format (human-readable syntax)
176-
177-
**Returns:**
178-
- String in Ds format (S-expression syntax)
179-
180-
**Example:**
181-
```javascript
182-
import { parse } from "atsds-bnf";
183-
184-
const result = parse("a, b -> c");
185-
// Returns: "a\nb\n----\nc"
186-
```
187-
188-
#### `unparse(dsText: string): string`
189-
190-
Converts Ds syntax to Dsp syntax.
191-
192-
**Parameters:**
193-
- `dsText`: String in Ds format (S-expression syntax)
194-
195-
**Returns:**
196-
- String in Dsp format (human-readable syntax)
197-
198-
**Example:**
199-
```javascript
200-
import { unparse } from "atsds-bnf";
201-
202-
const result = unparse("a\nb\n----\nc");
203-
// Returns: "a, b -> c"
204-
```
205-
206-
## Examples
207-
208-
### Parsing Complex Expressions
209-
210-
```python
211-
from apyds_bnf import parse
212-
213-
# Parse a complex expression with nested operators
214-
dsp = "(a + b) * c, d[i] -> f(g, h)"
215-
ds = parse(dsp)
216-
print(ds)
217-
# Output:
218-
# (binary * (binary + a b) c)
219-
# (subscript d i)
220-
# ---------------------------
221-
# (function f g h)
222-
```
223-
224-
### Unparsing Multiple Rules
225-
226-
```python
227-
from apyds_bnf import unparse
228-
229-
# Unparse multiple rules
230-
ds = "a\n----\nb\n\nc\n----\nd"
231-
dsp = unparse(ds)
232-
print(dsp)
233-
# Output: a -> b
234-
# c -> d
235-
```
236-
237-
### Round-trip Conversion
238-
239-
```python
240-
from apyds_bnf import parse, unparse
241-
242-
# Original Dsp format
243-
original = "a, b -> c"
244-
245-
# Convert to Ds and back to Dsp
246-
ds_format = parse(original)
247-
result = unparse(ds_format)
248-
249-
assert result == original # True
250-
```
251-
252128
## Building from Source
253129

254130
### Prerequisites
@@ -292,40 +168,6 @@ npm run build
292168
npm test
293169
```
294170

295-
## Testing
296-
297-
The package includes comprehensive tests for both Python and JavaScript implementations.
298-
299-
### Python Tests
300-
301-
Located in `tests/test_parse_unparse.py`:
302-
303-
```bash
304-
cd bnf
305-
pytest
306-
```
307-
308-
Tests cover:
309-
- Simple rules with premises and conclusions
310-
- Axioms (rules with no premises)
311-
- Function calls
312-
- Subscript notation
313-
- Binary and unary operators
314-
- Multiple rules
315-
- Complex nested expressions
316-
- Round-trip conversions
317-
318-
### JavaScript Tests
319-
320-
Located in `tests/test_parse_unparse.mjs`:
321-
322-
```bash
323-
cd bnf
324-
npm test
325-
```
326-
327-
Same test coverage as Python implementation.
328-
329171
## Grammar Files
330172

331173
The conversion is based on ANTLR grammars:
@@ -335,27 +177,6 @@ The conversion is based on ANTLR grammars:
335177

336178
These grammars are used to generate parsers for both Python and JavaScript.
337179

338-
## Development
339-
340-
### Generating ANTLR Parsers
341-
342-
For Python:
343-
```bash
344-
java -jar antlr-4.13.2-complete.jar -Dlanguage=Python3 Ds.g4 -visitor -no-listener -o apyds_bnf
345-
java -jar antlr-4.13.2-complete.jar -Dlanguage=Python3 Dsp.g4 -visitor -no-listener -o apyds_bnf
346-
```
347-
348-
For JavaScript:
349-
```bash
350-
antlr4 -Dlanguage=JavaScript Ds.g4 -visitor -no-listener -o atsds_bnf
351-
antlr4 -Dlanguage=JavaScript Dsp.g4 -visitor -no-listener -o atsds_bnf
352-
```
353-
354-
### Code Formatting
355-
356-
- Python: Uses `ruff` for linting and formatting (configured in `pyproject.toml`)
357-
- JavaScript: Standard npm formatting tools
358-
359180
## License
360181

361182
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

0 commit comments

Comments
 (0)