cnotes/README.md

# cnotes

A simple command-line logging and note-taking system written in strict C89/ANSI C for maximum portability.

## Overview

cnotes provides quick, one-line note capture from the terminal. Notes are stored in a simple CSV format and can be displayed, sorted, and filtered. 
The intent is to behave mostly like an immutable log, however entry deletion is enabled through an 'archiving' mechanism. 

Comprehensive explanatory documentation of the internals of these tools cna be found in [INTERNALS](INTERNALS.md). In essence, the design philosophy
is the same as the old unix bromide "do one thing, and do it well". In addition, I have made minor modifications to enable composition through 
shell scripting. I will not be overly customizing the CLI interface, for precisely this reason. 


## Supported Platforms

- Linux/Unix (GCC)
- macOS (GCC/Clang)
- Windows (Turbo C++ 3.0, MinGW)
- DOS 6.22 (Turbo C++ 3.0)

## Building

### Linux/Unix/macOS

```bash
make
```

Binaries are placed in the `build/` directory.

### DOS/Windows (Turbo C++ 3.0)

```batch
make -f MAKEFILE.TC
```

Or use the batch file if `make` is unavailable:

```batch
BUILD.BAT
```

### Installation (Unix-like systems)

```bash
sudo make install    # installs to /usr/local/bin
sudo make uninstall  # removes from /usr/local/bin
```

## Commands

### cnadd

Add a new timestamped note entry.

```bash
cnadd "Remember to call Bob"
cnadd -c Work "Meeting at 3pm"
cnadd -c Personal "Buy groceries"
```

Options:
- `-c CATEGORY` - Specify category (max 10 chars, default: "General")

### cndump

Display all notes in a formatted table. Output width adapts to terminal size automatically.

```bash
cndump              # display all notes (boxed table)
cndump -s           # simple output (no box borders)
cndump -d           # sort by date (newest first)
cndump -c           # sort by category
cndump -r           # reverse sort order
cndump -d -r        # sort by date, oldest first
cndump -a           # display archived entries
```

Options:
- `-d, --date` - Sort by date/time
- `-c, --category` - Sort by category
- `-r, --reverse` - Reverse sort order
- `-a, --archive` - Show archived entries instead of active
- `-s, --simple` - Simple output without box borders

### cncount

Display note statistics.

```bash
cncount             # total entry count
cncount -c          # count by category
cncount -d          # count by date
cncount -a          # count archived entries
cncount -a -c       # count archived entries by category
```

Options:
- `-c, --category` - Show counts per category
- `-d, --date` - Show counts per date
- `-a, --archive` - Count archived entries instead of active

### cndel

Archive note entries. Entries are moved to `cnotes.arc` rather than permanently deleted.

```bash
cndel -n 5          # archive entry at line 5
cndel -l            # archive the last (most recent) entry
cndel -d 2025-01-30 # archive all entries from a specific date
cndel -n 5 -y       # archive without confirmation prompt
```

Options:
- `-n LINE_NUMBER` - Archive entry at specified line number
- `-d DATE` - Archive all entries matching DATE (YYYY-MM-DD)
- `-l` - Archive the last (most recent) entry
- `-y` - Skip confirmation prompt

Archived entries can be viewed using `cndump -a`, searched with `cnfind -a`, or counted with `cncount -a`.

### cnfind

Search notes by text, category, or date.

```bash
cnfind meeting              # search for 'meeting' in text (case-insensitive)
cnfind -c Work              # show all entries in Work category
cnfind -d 2025-01-30        # show all entries from a specific date
cnfind -c Work meeting      # search 'meeting' in Work category only
cnfind -i meeting           # case-sensitive search
cnfind -n meeting           # show only match count
cnfind -a meeting           # search in archived entries
```

Options:
- `-c CATEGORY` - Filter by category (case-insensitive)
- `-d DATE` - Filter by date (YYYY-MM-DD)
- `-i` - Case-sensitive search (default is case-insensitive)
- `-n` - Show only count of matches
- `-a, --archive` - Search archived entries instead of active

The output includes line numbers for use with `cndel -n`.

### cnhelp

Quick reference for all cnotes commands.

```bash
cnhelp              # show command overview
cnhelp cnadd        # help for cnadd
cnhelp dump         # help for cndump (short form)
```

## Configuration

### Notes Location

By default, notes are stored in:

| Platform | Active Notes | Archived Notes |
|----------|--------------|----------------|
| Unix/Linux | `~/.local/share/cnotes/cnotes.csv` | `~/.local/share/cnotes/cnotes.arc` |
| Windows | `%USERPROFILE%\.cnotes\cnotes.csv` | `%USERPROFILE%\.cnotes\cnotes.arc` |
| DOS | `cnotes.csv` | `cnotes.arc` |

### Environment Variables

- `CNOTES_PATH` - Override the notes directory location (highest priority)
- On DOS, set `CNOTES_HOME` if `HOME` is not available

Example:
```bash
export CNOTES_PATH=/custom/path/to/notes
```

### Compile-time Configuration

Override defaults by defining at compile time:

```bash
gcc -DCNOTES_DIR=\".mynotes\" -DMAX_ENTRIES=1000 ...
```

## Data Format

Notes are stored in CSV format:

```
DATE,TIME,CATEGORY  ,"MESSAGE"
2025-01-30,14:30,Work      ,"Meeting with team"
2025-01-30,09:15,Personal  ,"Buy groceries"
```

Fields:
- Date: `YYYY-MM-DD` (10 chars)
- Time: `HH:MM` (5 chars)
- Category: padded to 10 chars
- Message: quoted, max 125 chars

### Archive

cnotes follows an immutable-log philosophy. When entries are "deleted" using `cndel`, they are moved to an archive file (`cnotes.arc`) rather than permanently removed. This provides:

- **Recoverability** - Archived entries can be reviewed or manually restored
- **Audit trail** - A complete history of all notes is preserved
- **Data safety** - Accidental deletions are never permanent

Use the `-a` flag with `cndump`, `cnfind`, or `cncount` to work with archived entries.

## TODO

Future commands to implement:

- [ ] **cntail** - Show last N entries (quick view)
  ```
  cntail                  # last 5 entries
  cntail -n 10            # last 10 entries
  ```

- [ ] **cncat** - List unique categories
  ```
  cncat                   # list categories
  cncat -c                # with counts
  ```

- [ ] **cnexport** - Export to other formats
  ```
  cnexport > notes.txt    # plain text
  cnexport -t > notes.tsv # tab-separated
  ```

## License

This project is dedicated to the public domain under the [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) license. See [LICENSE](LICENSE) for details.

## Author

Greg Gauthier (gmgauthier@protonmail.com)