Add comprehensive README

README.md

@@ -0,0 +1,114 @@
+# Pork Project
+
+## Overview
+
+Pork is a Python-based toolkit for manipulation and compilation of Java bytecodes and class files. It includes various utilities for handling byte-level operations, class file parsing, bytecode compiling, error handling, and running unit tests.
+
+## Features
+
+- **Byte-level Packing:** Functions to pack numbers into bytes for class file format using `struct` module.
+- **Class File Handling:** Define and manipulate Java class files including magic numbers, versions, and access flags.
+- **Compiling Tools:** Compile Java bytecode with custom operations and logging support.
+- **Java Opcode Representation:** Classes representing Java bytecode operations.
+- **Unit Testing:** Extensive set of unit tests for various aspects of Java class handling and compilation.
+- **Error Handling:** Custom exceptions for handling argument errors during compilation.
+
+## Installation Instructions
+
+### Prerequisites
+- Python 3.x
+- Java Development Kit (JDK)
+
+### Steps:
+1. Clone the repository:
+    ```bash
+    git clone https://github.com/Yuriy/pork.git
+    ```
+
+2. Navigate into the project directory:
+    ```bash
+    cd pork
+    ```
+
+3. Install the required Python packages:
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+4. If not already installed, download and configure `antlr`:
+    ```bash
+    wget https://github.com/antlr/antlr3/releases/download/3.5.2/antlr-3.5.2-complete.jar
+    export CLASSPATH=".:/path/to/antlr-3.5.2-complete.jar:$CLASSPATH"
+    ```
+
+## Usage Examples
+
+### Example 1: Byte Packing
+```python
+from bytes import u1, u2, u4
+
+print(u1(255))  # Output: b'\xff'
+print(u2(65535))  # Output: b'\xff\xff'
+print(u4(4294967295))  # Output: b'\xff\xff\xff\xff'
+```
+
+### Example 2: Class File Magic Number Check
+```python
+from classfile import MAGIC
+
+if classfile_header == MAGIC:
+    print("Valid Java class file")
+else:
+    print("Invalid class file")
+```
+
+### Example 3: Compiling Java Bytecode
+```python
+from classfile import Code_attribute, ExceptionTableEntry
+from compiler import log, ArgumentException
+
+try:
+    # Some bytecode compiling operation
+except ArgumentException as e:
+    log.error(f"Argument error: {e.mess}")
+```
+
+## Code Summary
+
+### Key Files:
+
+1. **bytes.py**: Contains utility functions to handle byte-level operations using the `struct` module.
+2. **classfile.py**: Provides definitions and utilities to parse and manipulate Java class files including magic number, version, and access flags.
+3. **compiler.py**: Implements the main functionalities for compiling Java bytecode with logging and custom exceptions.
+4. **jopcode.py**: Represents Java opcode operations and manages opcode-related functionalities.
+5. **pjc.py**: Main entry point to the Pork compiler that processes Java files using lexer and parser.
+6. **test/java/...**: Java unit test files ensuring the compiler's correctness for various bug fixes and features.
+7. **test/python/...**: Python unit test files verifying different aspects of class file handling and compilation.
+
+## Contributing Guidelines
+
+We welcome contributions from the community. Below are some guidelines for contributing:
+
+1. **Fork the repository** on GitHub.
+2. **Clone your forked repository** to your local machine.
+    ```bash
+    git clone https://github.com/your-username/pork.git
+    cd pork
+    ```
+3. Create a new branch from the main branch for your feature or bug fix:
+    ```bash
+    git checkout -b feature-name
+    ```
+4. **Commit your changes** with descriptive commit messages.
+    ```bash
+    git commit -m "Description of the feature or bug fix"
+    ```
+5. **Push your changes** to your forked repository.
+    ```bash
+    git push origin feature-name
+    ```
+6. **Create a pull request** from your fork to the main repository.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.