phrs 0.1.0

A tabular data shell tool compatible with ph
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

# phrs — the tabular data shell tool

`phrs` is a Rust command-line tool for manipulating CSV data in Unix pipelines. It is inspired by [ph](https://github.com/pgdr/ph) and uses [Polars](https://pola.rs/) for tabular operations.

## Install

```bash
cargo install phrs
```

## Getting started

Suppose `a.csv` contains:

```csv
x,y
3,8
4,9
5,10
6,11
7,12
8,13
```

Commands usually read CSV from standard input and write CSV to standard output, so they can be chained:

```bash
cat a.csv | phrs columns y x | phrs head 3
```

```csv
y,x
8,3
9,4
10,5
```

To display a human-readable table, use `show`:

```bash
cat a.csv | phrs show
```

```text
      x    y
--  ---  ---
 0    3    8
 1    4    9
 2    5   10
 3    6   11
 4    7   12
 5    8   13
```

`show` produces terminal output rather than CSV; it is normally the last command in a pipeline.

## Commands

### Inspect and select columns

```bash
cat a.csv | phrs columns          # List column names
cat a.csv | phrs columns y x      # Select and reorder columns
cat a.csv | phrs shape            # Output row and column counts as CSV
```

### Select and order rows

```bash
cat a.csv | phrs head             # First 10 rows (default)
cat a.csv | phrs head 3
cat a.csv | phrs tail             # Last 10 rows (default)
cat a.csv | phrs tail 3
cat a.csv | phrs sort x           # Sort by column x
```

### Rename and clean columns

```bash
cat a.csv | phrs rename x number  # Rename column x to number
cat a.csv | phrs slugify          # Normalize column names
cat a.csv | phrs strip            # Trim whitespace in string columns
cat a.csv | phrs strip x          # Trim a specified column
```

### Filter rows with `query`

`query` supports simple column-to-value comparisons (`==`, `!=`, `<`, `<=`, `>`, `>=`):

```bash
cat a.csv | phrs query 'x>5'
cat a.csv | phrs query 'y <= 10'
```

### Compute columns with `eval`

`eval` supports arithmetic expressions, assignments, numeric constants, parentheses, and exponentiation:

```bash
cat a.csv | phrs eval 'z = x + y'
cat a.csv | phrs eval 'z = x**2 + y'
cat a.csv | phrs eval 'z = (x + y) / 2'
cat a.csv | phrs eval 'x**2'       # Output only the computed column
```

### Display a table

```bash
cat a.csv | phrs show
cat a.csv | phrs show --no-index  # Omit the generated row index
```

### Concatenate CSV files

Unlike most commands, `cat` takes filenames. With no filenames, it reads standard input.

```bash
phrs cat a.csv b.csv
phrs cat a.csv b.csv --axis=index
phrs cat a.csv b.csv --axis=columns
cat a.csv | phrs cat
```

### Merge CSV files

`merge` reads two named CSV files and joins their rows. The default join type is `inner`; supported types are `inner`, `left`, `right`, and `outer`.

```bash
phrs merge left.csv right.csv
phrs merge left.csv right.csv --how=outer
phrs merge left.csv right.csv --on=key
phrs merge left.csv right.csv --left=left_key --right=right_key
```

When no join key is provided, common column names are used as join keys.

## Pipelines

```bash
cat a.csv \
  | phrs query 'x>4' \
  | phrs eval 'z = x * y' \
  | phrs columns x z \
  | phrs sort x \
  | phrs show
```

## Development

```bash
cargo test
cargo build --release
```

The optimized executable is written to `target/release/phrs`.

`phrs` aims to reproduce the behavior of the Python [`ph`](https://github.com/pgdr/ph) tool for its implemented commands, but does not yet support every `ph` operation. Differences are tracked using differential tests against the Python implementation.

## License

MIT.