java2ib
Version:
TypeScript library that converts Java code into IB Computer Science pseudocode format
667 lines (522 loc) • 16.8 kB
Markdown
# java2ib
A TypeScript library that converts Java code into IB Computer Science pseudocode format according to the official IB specification. This library is designed for educational purposes, enabling teachers and students to automatically convert Java code examples into the standardized pseudocode format used in the IB Computer Science curriculum.
## Features
- **Complete Java Syntax Support**: Variables, control structures, methods, arrays, and object-oriented constructs
- **Advanced Java Constructs**: Switch statements, enhanced for loops, array initialization, break/continue
- **IB Specification Compliance**: Follows official IB pseudocode rules and formatting
- **Intelligent Transformations**: Converts Java naming conventions, operators, and syntax to IB format
- **Performance Optimized**: Efficient processing for large Java files with caching and pooling
- **Comprehensive Error Handling**: Enhanced error messages with context and suggestions
- **TypeScript Support**: Full type definitions for enhanced development experience
- **Educational Focus**: Designed specifically for IB Computer Science curriculum needs
## Installation
### Node.js Environment
```bash
npm install java2ib
```
### Browser Environment
For browser usage, you can use the pre-built browser bundle or run the development server:
#### Option 1: Development Server
```bash
# Clone the repository
git clone https://github.com/fairy-pitta/java2ib.git
cd java2ib
# Install dependencies
npm install
# Start the development server
python3 -m http.server 8080
# Open http://localhost:8080 in your browser
```
#### Option 2: Direct Browser Usage
Include the browser bundle in your HTML:
```html
<!DOCTYPE html>
<html>
<head>
<title>Java to IB Converter</title>
</head>
<body>
<textarea id="javaInput" placeholder="Enter Java code here..."></textarea>
<button onclick="convertCode()">Convert</button>
<pre id="output"></pre>
<script type="module">
import * as Java2IB from './dist/browser/java2ib.es.js';
window.converter = new Java2IB.JavaToIBConverter();
window.convertCode = function() {
const input = document.getElementById('javaInput').value;
const result = window.converter.convert(input);
document.getElementById('output').textContent = result.pseudocode;
};
</script>
</body>
</html>
```
## Quick Start
### Node.js Usage
```typescript
import { JavaToIBConverter } from 'java2ib';
const converter = new JavaToIBConverter();
// Simple variable conversion
const result = converter.convert('int x = 5;');
console.log(result.pseudocode); // Output: X = 5
// Method conversion
const methodResult = converter.convert(`
public int add(int a, int b) {
return a + b;
}
`);
console.log(methodResult.pseudocode);
// Output:
// FUNCTION ADD(A, B) RETURNS value
// return A + B
// end FUNCTION
// Complex program conversion
const complexResult = converter.convert(`
public class Calculator {
public static void main(String[] args) {
int[] numbers = {10, 20, 30, 40, 50};
int sum = 0;
for (int num : numbers) {
sum += num;
}
switch (sum) {
case 150:
System.out.println("Perfect sum!");
break;
default:
System.out.println("Sum is: " + sum);
}
}
}
`);
console.log(complexResult.pseudocode);
// Output:
// NUMBERS = [10, 20, 30, 40, 50]
// SUM = 0
// loop NUM in NUMBERS
// SUM = SUM + NUM
// end loop
// case SUM of
// 150:
// output "Perfect sum!"
// default:
// output "Sum is: " + SUM
// end case
```
### Browser Usage
For browser environments, you can use the web interface:
```javascript
// The converter is already initialized in the browser
// Simply enter Java code in the textarea and click "Convert"
// Or use it programmatically:
const javaCode = `
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
`;
const result = window.converter.convert(javaCode);
console.log(result.pseudocode);
// Output: output "Hello, World!"
```
## Conversion Examples
### Variables and Assignments
**Java:**
```java
int count = 0;
String name = "Alice";
boolean isValid = true;
```
**IB Pseudocode:**
```
COUNT = 0
NAME = "Alice"
ISVALID = true
```
### Control Structures
**Java:**
```java
if (x > 5) {
System.out.println("Greater than 5");
} else {
System.out.println("Less than or equal to 5");
}
```
**IB Pseudocode:**
```
if X > 5 then
output "Greater than 5"
else
output "Less than or equal to 5"
end if
```
### Loops
**Java:**
```java
// Traditional for loop
for (int i = 0; i < 10; i++) {
System.out.println(i);
}
// Enhanced for loop (for-each)
for (String name : names) {
System.out.println(name);
}
// While loop
while (count < 100) {
count++;
}
```
**IB Pseudocode:**
```
loop I from 0 to 9
output I
end loop
loop NAME in NAMES
output NAME
end loop
loop while COUNT < 100
COUNT = COUNT + 1
end loop
```
### Methods and Functions
**Java:**
```java
public void greet(String name) {
System.out.println("Hello " + name);
}
public int multiply(int a, int b) {
return a * b;
}
```
**IB Pseudocode:**
```
PROCEDURE greet(NAME)
output "Hello " + NAME
end PROCEDURE
FUNCTION multiply(A, B) RETURNS value
return A * B
end FUNCTION
```
### Arrays
**Java:**
```java
// Array declaration and initialization
int[] numbers = new int[10];
int[] values = {1, 2, 3, 4, 5};
String[] colors = {"red", "green", "blue"};
// Array access and operations
numbers[0] = 42;
int length = numbers.length;
```
**IB Pseudocode:**
```
NUMBERS = new array[10]
VALUES = [1, 2, 3, 4, 5]
COLORS = ["red", "green", "blue"]
NUMBERS[0] = 42
LENGTH = SIZE(NUMBERS)
```
### Switch Statements
**Java:**
```java
switch (grade) {
case 'A':
System.out.println("Excellent");
break;
case 'B':
System.out.println("Good");
break;
default:
System.out.println("Try harder");
}
```
**IB Pseudocode:**
```
case GRADE of
'A':
output "Excellent"
'B':
output "Good"
default:
output "Try harder"
end case
```
### Break and Continue Statements
**Java:**
```java
for (int i = 0; i < 10; i++) {
if (i == 5) {
break;
}
if (i % 2 == 0) {
continue;
}
System.out.println(i);
}
```
**IB Pseudocode:**
```
loop I from 0 to 9
if I = 5 then
// break statement (exit loop)
end if
if I mod 2 = 0 then
// continue statement (skip to next iteration)
end if
output I
end loop
```
## API Reference
### JavaToIBConverter
The main converter class that handles Java to IB pseudocode conversion.
#### Constructor
```typescript
const converter = new JavaToIBConverter();
```
#### Methods
##### convert(javaCode: string, options?: ConversionOptions): ConversionResult
Converts Java source code to IB pseudocode format.
**Parameters:**
- `javaCode` (string): The Java source code to convert
- `options` (ConversionOptions, optional): Conversion configuration options
**Returns:** `ConversionResult` - The conversion result with pseudocode and metadata
### ConversionOptions
Configuration options for the conversion process.
```typescript
interface ConversionOptions {
preserveComments?: boolean; // Whether to preserve comments (default: true)
strictMode?: boolean; // Enable strict conversion mode (default: false)
indentSize?: number; // Number of spaces for indentation (default: 4)
}
```
### ConversionResult
The result of a conversion operation.
```typescript
interface ConversionResult {
pseudocode: string; // The converted pseudocode
success: boolean; // Whether conversion was successful
errors: ConversionError[]; // Any errors encountered
warnings: ConversionWarning[]; // Any warnings generated
metadata: ConversionMetadata; // Conversion metadata
}
```
### Error Handling
The library provides comprehensive error reporting with detailed messages and location information.
```typescript
// Example error handling
const result = converter.convert(javaCode);
if (!result.success) {
result.errors.forEach(error => {
console.error(`${error.type} at line ${error.location.line}: ${error.message}`);
});
}
// Handle warnings
result.warnings.forEach(warning => {
console.warn(`Warning: ${warning.message}`);
});
```
## Conversion Rules
The library follows the official IB Computer Science pseudocode specification:
### Variable Names
- Java camelCase → IB UPPERCASE
- `userName` → `USERNAME`
- `itemCount` → `ITEMCOUNT`
### Operators
- `==` → `=`
- `!=` → `≠`
- `&&` → `AND`
- `||` → `OR`
- `!` → `NOT`
- `%` → `mod`
### Control Structures
- `if-else` → `if...then...else...end if`
- `while` → `loop while...end loop`
- `for` → `loop I from X to Y...end loop`
- `for-each` → `loop ITEM in COLLECTION...end loop`
- `switch-case` → `case VARIABLE of...end case`
- `break/continue` → Comments indicating control flow
### Methods
- `void` methods → `PROCEDURE...end PROCEDURE`
- Non-void methods → `FUNCTION...RETURNS value...end FUNCTION`
### Input/Output
- `System.out.println()` → `output`
- `System.out.print()` → `output`
- `Scanner.nextInt()` → `INPUT`
- `Scanner.nextLine()` → `INPUT`
- `Scanner.nextDouble()` → `INPUT`
### Arrays and Collections
- `array.length` → `SIZE(ARRAY)`
- `{1, 2, 3}` → `[1, 2, 3]`
- `new int[size]` → `new array[SIZE]`
For complete conversion rules, see the [IB Rules Documentation](docs/ib-rules.md).
## Educational Use Cases
This library is particularly useful for:
- **Teachers**: Convert Java examples to IB pseudocode for curriculum materials
- **Students**: Understand the relationship between Java and IB pseudocode
- **Curriculum Development**: Create consistent pseudocode examples from Java code
- **Assessment Preparation**: Practice converting between Java and pseudocode formats
## Advanced Usage
### Batch Conversion
```typescript
const converter = new JavaToIBConverter();
const javaFiles = ['example1.java', 'example2.java'];
javaFiles.forEach(file => {
const javaCode = fs.readFileSync(file, 'utf8');
const result = converter.convert(javaCode);
if (result.success) {
fs.writeFileSync(file.replace('.java', '.pseudo'), result.pseudocode);
}
});
```
### Custom Options
```typescript
const options: ConversionOptions = {
preserveComments: true,
strictMode: false,
indentSize: 2
};
const result = converter.convert(javaCode, options);
```
### Performance Monitoring
The library provides detailed performance metrics for optimization:
```typescript
const result = converter.convert(javaCode);
console.log('Processing time:', result.metadata.processingTime, 'ms');
console.log('Performance breakdown:', result.metadata.performanceBreakdown);
console.log('Statistics:', result.metadata.statistics);
// Example output:
// Processing time: 15.2 ms
// Performance breakdown: {
// lexingTime: 3.1,
// parsingTime: 5.8,
// transformationTime: 4.2,
// codeGenerationTime: 2.1
// }
// Statistics: {
// tokenCount: 156,
// astNodeCount: 89,
// inputSize: 1024,
// outputSize: 892
// }
```
### Large File Handling
The library is optimized for large Java files with built-in performance enhancements:
- **Lexer Pooling**: Reuses lexer instances to reduce object creation overhead
- **Generator Caching**: Caches pseudocode generators for repeated conversions
- **Memory Management**: Efficient memory usage with size limits and cleanup
- **Early Exit**: Handles files larger than 1MB with appropriate error messages
```typescript
// The converter automatically handles large files efficiently
const largeJavaCode = fs.readFileSync('large-program.java', 'utf8');
const result = converter.convert(largeJavaCode);
if (result.success) {
console.log(`Converted ${result.metadata.originalLines} lines in ${result.metadata.processingTime}ms`);
}
```
## Development
### Setup
```bash
# Clone the repository
git clone https://github.com/fairy-pitta/java2ib.git
cd java2ib
# Install dependencies
npm install
# Run tests
npm test
# Build the library
npm run build
# Build browser version
npm run build:browser
# Start development server for browser testing
python3 -m http.server 8080
# Generate documentation
npm run docs
```
### Testing
The library includes comprehensive test suites:
```bash
# Run all tests
npm test
# Run tests with coverage
npm run test:coverage
# Run tests in watch mode
npm run test:watch
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
## Supported Java Features
### ✅ Fully Supported
- **Variables**: All primitive types, arrays, strings
- **Control Structures**: if/else, while, for, enhanced for, switch/case
- **Methods**: Functions, procedures, parameters, return values
- **Arrays**: Declaration, initialization, access, length operations
- **Operators**: Arithmetic, comparison, logical, assignment
- **I/O Operations**: System.out.print/println, Scanner input methods
- **Object-Oriented**: Classes, methods, fields, inheritance basics
- **Advanced Constructs**: Break/continue, array initialization, nested structures
### ⚠️ Partially Supported
- **Complex OOP**: Advanced inheritance patterns may need manual review
- **Exception Handling**: Try-catch blocks are parsed but simplified
- **Generics**: Type parameters are simplified in pseudocode output
- **Lambda Expressions**: Basic lambdas supported, complex ones may need review
### ❌ Not Supported
- **Java 8+ Streams**: Stream API calls are not converted
- **Annotations**: Annotation syntax is ignored
- **Reflection**: Dynamic code execution features
- **External Libraries**: Only standard Java and Scanner are supported
## Limitations
- **File Size**: Maximum input file size is 1MB for performance reasons
- **Memory Usage**: Large files with deeply nested structures may require more memory
- **Custom Classes**: User-defined class types are supported in enhanced for loops
- **Error Recovery**: Parser attempts to recover from syntax errors but may skip sections
## Support
For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/fairy-pitta/java2ib).
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Changelog
### Version 1.1.0 (Latest)
- ✅ **New Features**:
- Complete browser compatibility with interactive web interface
- Vite-based build system for optimized browser bundles
- File upload functionality for browser version
- Responsive design for mobile and desktop usage
- ✅ **Quality Improvements**:
- Comprehensive E2E testing with Playwright across all major browsers
- Cross-browser compatibility (Chrome, Firefox, Safari, Mobile browsers)
- Enhanced documentation with browser usage examples
- Improved development workflow with browser testing
### Version 1.0.0
- ✅ **New Features**:
- Switch statement conversion (`switch-case` → `case...of...end case`)
- Enhanced for loop support (`for (Type item : collection)` → `loop ITEM in COLLECTION`)
- Array initialization syntax (`{1, 2, 3}` → `[1, 2, 3]`)
- Break and continue statement handling with explanatory comments
- Custom class type support in enhanced for loops
- **Browser support**: Web-based converter with interactive interface
- **Browser bundle**: Pre-built ES modules for direct browser usage
- ✅ **Performance Improvements**:
- Lexer object pooling for better memory efficiency
- Generator caching system for repeated conversions
- Optimized line counting and string processing
- Enhanced error messages with context and suggestions
- ✅ **Quality Improvements**:
- 308 comprehensive test cases covering all features
- Detailed performance monitoring and metrics
- Improved error handling with recovery mechanisms
- Enhanced TypeScript type definitions
- **Browser testing**: Playwright-based browser test suite
### Version 0.9.0
- Initial release with basic Java to IB pseudocode conversion
- Support for variables, control structures, methods, and arrays
- Basic error handling and TypeScript support
## Acknowledgments
- Based on the official IB Computer Science pseudocode specification
- Designed for educational use in IB Computer Science programs
- Inspired by the need for consistent pseudocode formatting in curriculum materials
- Developed with performance and reliability in mind for classroom use