Skip to content

Commit b5b7ef3

Browse files
orangekame3orangekame3
committed
docs: improve table formatting in README.md for better readability
1 parent 8f6d4e6 commit b5b7ef3

File tree

2 files changed

+195
-27
lines changed

2 files changed

+195
-27
lines changed

‎README.md‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -43,23 +43,23 @@ qasmfmt [OPTIONS] [PATH]...
4343

4444
#### Modes (mutually exclusive)
4545

46-
| Option | Description |
47-
|--------|-------------|
48-
| `-w, --write` | Write formatted output back to files (in-place) |
49-
| `--check` | Check if files are formatted (exit 1 if not) |
50-
| `--diff` | Show unified diff of formatting changes (exit 1 if diff exists) |
46+
| Option | Description |
47+
| ------------- | --------------------------------------------------------------- |
48+
| `-w, --write` | Write formatted output back to files (in-place) |
49+
| `--check` | Check if files are formatted (exit 1 if not) |
50+
| `--diff` | Show unified diff of formatting changes (exit 1 if diff exists) |
5151

5252
#### Options
5353

54-
| Option | Description |
55-
|--------|-------------|
56-
| `-i, --indent <N>` | Indentation size in spaces (default: 4) |
57-
| `--max-width <N>` | Maximum line width (default: 100) |
58-
| `--stdin-filename <PATH>` | Virtual filename for stdin input |
59-
| `--config <PATH>` | Path to configuration file |
60-
| `--no-config` | Disable automatic configuration file discovery |
61-
| `-V, --version` | Print version |
62-
| `-h, --help` | Print help |
54+
| Option | Description |
55+
| ------------------------- | ---------------------------------------------- |
56+
| `-i, --indent <N>` | Indentation size in spaces (default: 4) |
57+
| `--max-width <N>` | Maximum line width (default: 100) |
58+
| `--stdin-filename <PATH>` | Virtual filename for stdin input |
59+
| `--config <PATH>` | Path to configuration file |
60+
| `--no-config` | Disable automatic configuration file discovery |
61+
| `-V, --version` | Print version |
62+
| `-h, --help` | Print help |
6363

6464
#### Examples
6565

@@ -178,11 +178,11 @@ c = measure q;
178178

179179
## Exit Codes
180180

181-
| Code | Description |
182-
|------|-------------|
183-
| 0 | Success |
184-
| 1 | Error or formatting differences found (`--check`, `--diff`) |
185-
| 2 | Usage error (e.g., mutually exclusive options, stdin with `--write`) |
181+
| Code | Description |
182+
| ---- | -------------------------------------------------------------------- |
183+
| 0 | Success |
184+
| 1 | Error or formatting differences found (`--check`, `--diff`) |
185+
| 2 | Usage error (e.g., mutually exclusive options, stdin with `--write`) |
186186

187187
## CI Integration
188188

‎docs/src/README.md‎

Lines changed: 176 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,159 @@
11
# qasmfmt
22

3-
**qasmfmt** is a formatter for OpenQASM 3.0 quantum circuit files.
3+
**qasmfmt** is a fast formatter for OpenQASM 3.0 quantum circuit files, written in Rust.
44

55
## Features
66

7-
- Automatic formatting of OpenQASM 3.0 code
8-
- Comment preservation
7+
- Fast formatting powered by Rust
8+
- Available as both Rust and Python package
99
- CLI and library interfaces
10+
- stdin/stdout support for pipeline usage
11+
- Configuration file support (`qasmfmt.toml`)
12+
- Directory recursive processing
1013

11-
## Quick Start
14+
## Installation
15+
16+
### Using pip (recommended)
17+
18+
```bash
19+
pip install qasmfmt
20+
```
21+
22+
### Using Cargo
1223

1324
```bash
14-
# Install
1525
cargo install qasmfmt
26+
```
27+
28+
### From source
29+
30+
```bash
31+
git clone https://github.com/orangekame3/qasmfmt
32+
cd qasmfmt
33+
cargo install --path .
34+
```
35+
36+
## Usage
37+
38+
### CLI
39+
40+
```bash
41+
qasmfmt [OPTIONS] [PATH]...
42+
```
1643

17-
# Format a file (in-place)
44+
#### Modes (mutually exclusive)
45+
46+
| Option | Description |
47+
| ------------- | --------------------------------------------------------------- |
48+
| `-w, --write` | Write formatted output back to files (in-place) |
49+
| `--check` | Check if files are formatted (exit 1 if not) |
50+
| `--diff` | Show unified diff of formatting changes (exit 1 if diff exists) |
51+
52+
#### Options
53+
54+
| Option | Description |
55+
| ------------------------- | ---------------------------------------------- |
56+
| `-i, --indent <N>` | Indentation size in spaces (default: 4) |
57+
| `--max-width <N>` | Maximum line width (default: 100) |
58+
| `--stdin-filename <PATH>` | Virtual filename for stdin input |
59+
| `--config <PATH>` | Path to configuration file |
60+
| `--no-config` | Disable automatic configuration file discovery |
61+
| `-V, --version` | Print version |
62+
| `-h, --help` | Print help |
63+
64+
#### Examples
65+
66+
```bash
67+
# Format file (print to stdout)
1868
qasmfmt input.qasm
1969

20-
# Check formatting
70+
# Format file in-place
71+
qasmfmt -w input.qasm
72+
73+
# Check if file is formatted (for CI)
2174
qasmfmt --check input.qasm
75+
76+
# Show diff
77+
qasmfmt --diff input.qasm
78+
79+
# Format from stdin
80+
echo 'OPENQASM 3.0;qubit[2]q;' | qasmfmt
81+
echo 'OPENQASM 3.0;qubit[2]q;' | qasmfmt -
82+
83+
# Format from stdin with virtual filename
84+
echo 'OPENQASM 3.0;qubit[2]q;' | qasmfmt --stdin-filename circuit.qasm -
85+
86+
# Custom indent size
87+
qasmfmt -i 2 input.qasm
88+
89+
# Format all .qasm files in a directory (recursive)
90+
qasmfmt -w ./circuits/
91+
92+
# Check all .qasm files in a directory
93+
qasmfmt --check ./src/
94+
95+
# Use specific config file
96+
qasmfmt --config ./qasmfmt.toml input.qasm
97+
98+
# Disable config file auto-discovery
99+
qasmfmt --no-config input.qasm
100+
```
101+
102+
### Configuration File
103+
104+
qasmfmt automatically searches for `qasmfmt.toml` from the input file's directory upward.
105+
106+
```toml
107+
# qasmfmt.toml
108+
indent_size = 2
109+
max_width = 80
110+
indent_style = "spaces" # or "tabs"
111+
trailing_newline = true
112+
```
113+
114+
CLI options override configuration file settings.
115+
116+
### Python Library
117+
118+
```python
119+
import qasmfmt
120+
121+
# Format string
122+
source = "OPENQASM 3.0;qubit[2]q;h q[0];"
123+
formatted = qasmfmt.format_str(source)
124+
print(formatted)
125+
# OPENQASM 3.0;
126+
# qubit[2] q;
127+
# h q[0];
128+
129+
# Format with options
130+
formatted = qasmfmt.format_str(source, indent_size=2, max_width=80)
131+
132+
# Format file
133+
formatted = qasmfmt.format_file("circuit.qasm")
134+
135+
# Check if file is formatted
136+
is_formatted = qasmfmt.check_file("circuit.qasm")
137+
```
138+
139+
### Rust Library
140+
141+
```rust
142+
use qasmfmt::{format, format_with_config, FormatConfig};
143+
144+
fn main() {
145+
let source = "OPENQASM 3.0;qubit[2]q;";
146+
147+
// Format with default config
148+
let formatted = format(source).unwrap();
149+
150+
// Format with custom config
151+
let config = FormatConfig {
152+
indent_size: 2,
153+
..Default::default()
154+
};
155+
let formatted = format_with_config(source, config).unwrap();
156+
}
22157
```
23158

24159
## Example
@@ -34,14 +169,47 @@ After:
34169
```qasm
35170
OPENQASM 3.0;
36171
include "stdgates.inc";
37-
38172
qubit[2] q;
39173
bit[2] c;
40174
h q[0];
41175
cx q[0], q[1];
42176
c = measure q;
43177
```
44178

179+
## Exit Codes
180+
181+
| Code | Description |
182+
| ---- | -------------------------------------------------------------------- |
183+
| 0 | Success |
184+
| 1 | Error or formatting differences found (`--check`, `--diff`) |
185+
| 2 | Usage error (e.g., mutually exclusive options, stdin with `--write`) |
186+
187+
## CI Integration
188+
189+
### GitHub Actions
190+
191+
```yaml
192+
- name: Check OpenQASM formatting
193+
run: |
194+
pip install qasmfmt
195+
qasmfmt --check .
196+
```
197+
198+
### pre-commit
199+
200+
```yaml
201+
# .pre-commit-config.yaml
202+
repos:
203+
- repo: local
204+
hooks:
205+
- id: qasmfmt
206+
name: qasmfmt
207+
entry: qasmfmt --check
208+
language: python
209+
additional_dependencies: [qasmfmt]
210+
files: \.qasm$
211+
```
212+
45213
## License
46214
47215
MIT License

0 commit comments

Comments
 (0)