Metadata-Version: 2.4
Name: sillystrings
Version: 0.1.0
Summary: A Python reimplementation of the Unix strings utility
Keywords: strings,binary,reverse engineering,cli
Author: Kyle O'Malley
Author-email: Kyle O'Malley <j.kyle.omalley@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/jkomalley/sillystrings
Project-URL: Repository, https://github.com/jkomalley/sillystrings
Project-URL: Issues, https://github.com/jkomalley/sillystrings/issues
Project-URL: Changelog, https://github.com/jkomalley/sillystrings/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# sillystrings

A Python reimplementation of the Unix `strings` utility. Extracts printable character sequences from binary files with support for multiple encodings, offset display, and standard CLI conventions.

Pure Python, zero dependencies, comprehensive test coverage.

## Installation

Requires Python 3.11+.

Install from source using [uv](https://docs.astral.sh/uv/):

```
git clone https://github.com/jkomalley/sillystrings.git
cd sillystrings
uv sync
```

## Usage

```
sillystrings [OPTIONS] [FILE ...]
```

With no file arguments, reads from stdin.

### Options

| Flag | Description |
|------|-------------|
| `-n NUM` | Minimum string length (default: 4) |
| `-e {s,S,l,b}` | Character encoding: `s` = 7-bit ASCII (default), `S` = 8-bit, `l` = UTF-16 LE, `b` = UTF-16 BE |
| `-t {d,o,x}` | Print byte offset before each string in decimal, octal, or hex |
| `-w` | Include all whitespace characters (newlines, carriage returns) in strings |
| `-f` | Print the filename before each string |
| `-v` | Show version and exit |

### Examples

Scan a binary for readable strings:

```
sillystrings /usr/bin/ls
```

Show hex offsets with 8-bit encoding:

```
sillystrings -t x -e S firmware.bin
```

Read from stdin:

```
cat firmware.bin | sillystrings -
```

Find wide (UTF-16 LE) strings with a minimum length of 8:

```
sillystrings -e l -n 8 program.exe
```

## Architecture

The project is organized into three layers:

- **encodings** -- character-level printability checks for ASCII and UTF-16
- **scanner** -- accumulates printable runs into strings, tracks byte offsets
- **cli** -- argument parsing, file I/O, output formatting

## Development

```
just install    # or: uv sync && uv run pre-commit install
just check      # format, lint, type check, and the test suite
```

Tests cover all encoding modes, offset calculations, CLI flags, edge cases, and integration via subprocess.

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project layout, and the conventions this repo follows.

## License

MIT
