Metadata-Version: 2.1
Name: map-content-tool
Version: 1.1.1
Summary: A tool to map directory contents and save output as TXT or JSON.
Home-page: https://github.com/HousamKak/map-content-tool
Author: Housam Kak
Author-email: housam.kak20@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.6
Description-Content-Type: text/markdown

# **Documentation for mapContentTool.py**

## **Overview**
`mapContentTool.py` is a command-line tool for mapping the structure of a directory, selecting files and folders interactively, and exporting the directory structure with selected file contents. The output can be saved as a `.txt` (default) or `.json` file. Additionally, the tool can be installed as a Python library to provide the `map-content` command for direct usage.

---

## **Features**
- **Interactive Selection**:
  - Navigate directory structures.
  - Select or deselect files and folders interactively.
- **Recursive Handling**:
  - Selecting a folder includes all its files and subfolders.
  - Deselecting a folder removes all its files and subfolders from the selection.
- **File Content Embedding**:
  - Embeds the content of selected files directly into the output structure.
- **Output Options**:
  - **Default**: `.txt` format.
  - **Optional**: `.json` format with a detailed structure.
- **Exclusion Capabilities**:
  - Exclude specific directories (e.g., `node_modules`, `.git`).
- **Convenient Command**:
  - Install as a Python library to use the `map-content` command directly.
- **Comprehensive Logging**:
  - Logs all actions and errors for debugging and tracking.

---

## **Installation**
You can install `mapContentTool.py` as a Python package via pip:
```bash
pip install map-content-tool
```

---

## **Usage**

### **Command-Line Options**
```bash
python mapContentTool.py [directory] [options]
```
Or, after installation, use the standalone command:
```bash
map-content [directory] [options]
```

### **Options**
| Option              | Description                                                                                     | Default                |
|---------------------|-------------------------------------------------------------------------------------------------|------------------------|
| `[directory]`       | Root directory to scan. If not provided, the current directory is used.                        | Current directory      |
| `-o, --output`      | Specify the output file. Supports `.txt` (default) and `.json`.                                | `output.txt`           |
| `-e, --exclude`     | Space-separated list of directories to exclude from scanning.                                  | `node_modules`, `.git` |

---

### **Examples**

#### **Using Python Script**
1. **Basic Usage**:
   ```bash
   python mapContentTool.py
   ```
   - Scans the current directory.
   - Outputs the structure to `output.txt`.

2. **Specify an Output File**:
   ```bash
   python mapContentTool.py -o my_directory.json
   ```
   - Outputs the directory structure to `my_directory.json`.

3. **Exclude Specific Directories**:
   ```bash
   python mapContentTool.py -e dist build
   ```
   - Excludes the `dist` and `build` directories from the scan.

4. **Scan a Custom Directory**:
   ```bash
   python mapContentTool.py /path/to/directory
   ```
   - Scans the `/path/to/directory` and outputs the structure to `output.txt`.

---

#### **Using the `map-content` Command**
1. **Basic Usage**:
   ```bash
   map-content
   ```
   - Scans the current directory.
   - Outputs the structure to `output.txt`.

2. **Custom Directory**:
   ```bash
   map-content /path/to/directory
   ```

3. **Exclude Specific Directories**:
   ```bash
   map-content -e dist build
   ```

4. **Output as JSON**:
   ```bash
   map-content -o output.json
   ```

---

## **Output Format**

### **Default `.txt` Format**
- The `.txt` format retains the JSON-like structure for readability.

### **Optional `.json` Format**
- Example:
```json
{
  "name": "root_folder",
  "path": "/path/to/root_folder",
  "type": "directory",
  "items": [
    {
      "name": "subfolder1",
      "path": "/path/to/root_folder/subfolder1",
      "type": "directory",
      "items": [
        {
          "name": "file1.txt",
          "path": "/path/to/root_folder/subfolder1/file1.txt",
          "type": "file",
          "contents": "This is the content of file1.txt."
        }
      ]
    }
  ]
}
```

---

## **Interactive UI**

### **Navigation**
- **Arrow keys**: Move through the directory tree.
- **Space**: Select or deselect files and folders.
- **Enter**: Confirm selection and generate output.
- **Q**: Quit without saving.

---

## **Logs**
- Logs are written to `file_selector.log`.
- Tracks:
  - Errors
  - Directory scanning progress
  - File content embedding
  - User interactions

---

## **Error Handling**
- Handles missing directories and permission errors gracefully.
- If any uncaught exception occurs, it logs the error and exits with a message to check the logs.

---

## **Dependencies**
- Python 3.x
- Modules:
  - `os`
  - `json`
  - `urwid`
  - `logging`
  - `sys`
  - `argparse`
  - `setuptools`

---

## **Changelog**
### **Latest Updates**
- Made `.txt` the default output format.
- Added `.json` as an optional output format.
- Restored the functionality of showing selected files inside a folder.
- Improved folder selection and deselection logic to include all nested items.
- Updated logging and documentation.
- Enabled the use of the `map-content` standalone command via setuptools.

---

## **Known Issues**
- None at the moment.

For feature requests or bug reports, please contact the developer or create an issue in the repository.
