{"owner":"nissl-lab","repo":"npoi","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI agents and new contributors working in this codebase.\n\n## Project Overview\n\nNPOI is a .NET port of [Apache POI](https://poi.apache.org/) for reading and\nwriting Microsoft Office file formats without requiring COM or an Office\ninstallation. Targets net472, netstandard2.0, netstandard2.1, and net8.0.\n\n## Code Style\n\n- Use 4 spaces for indentation (default for .NET projects)\n- No comments unless explaining non-obvious business logic\n- Prefer `var` for local variables when type is clear from right-hand side\n- Follow existing patterns for nullable reference types (`string?` vs `string`)\n- Use XML documentation (`/// <summary>`) for public APIs only\n\n## Directory → Project Map\n\n| Directory         | Project                      | Purpose                                                        |\n|-------------------|------------------------------|----------------------------------------------------------------|\n| `main/`           | NPOI.Core                    | HSSF (.xls), HPSF (doc properties), SS model, DDF, utilities  |\n| `ooxml/`          | NPOI.OOXML                   | XSSF (.xlsx), SXSSF (streaming), XWPF (.docx), XSLF (.pptx)  |\n| `OpenXmlFormats/` | NPOI.OpenXmlFormats          | C# classes mapping to OOXML XML schemas (data-only, no logic)  |\n| `openxml4Net/`    | NPOI.OpenXml4Net             | OPC packaging: zip I/O, content types, part relationships      |\n| `scratchpad/`     | (various)                    | HWPF (.doc binary), HSLF (.ppt binary), other legacy formats   |\n| `testcases/`      | Test project                 | Mirrors source structure; test data in `testcases/test-data/`  |\n| `build/`          | _build (Nuke)                | Build automation                                               |\n| `benchmarks/`     | NPOI.Benchmarks              | BenchmarkDotNet performance tests                              |\n| `solution/`       | Solution/packaging files     | `.sln` files and NuGet pack project                            |\n\n## Format Acronyms\n\nThese names come from Apache POI and appear throughout the codebase:\n\n- **HSSF** — Horrible SpreadSheet Format (binary `.xls`)\n- **XSSF** — XML SpreadSheet Format (`.xlsx`)\n- **SXSSF** — Streaming XSSF (write-only sliding window over XSSF)\n- **HWPF** — Horrible Word Processor Format (binary `.doc`)\n- **XWPF** — XML Word Processor Format (`.docx`)\n- **HSLF** — Horrible SLide Format (binary `.ppt`)\n- **XSLF** — XML SLide Format (`.pptx`)\n- **HPSF** — Horrible Property Set Format (document metadata)\n- **SS** — Common spreadsheet interfaces (`ISheet`, `IRow`, `ICell`) shared by HSSF and XSSF\n- **DDF** — Dreadful Drawing Format (shapes/drawing records in binary formats)\n\n## Format Selection Guide\n\n| Format | Use When | Memory | Limitations |\n|--------|----------|--------|-------------|\n| **HSSF** | Reading/writing `.xls` (Excel 97-2003) | Medium | 65,536 row limit |\n| **XSSF** | Reading/writing `.xlsx`, full features needed | High | Memory scales with file size |\n| **SXSSF** | Writing large `.xlsx` files (>100K rows) | Low (constant) | Write-only, limited random access |\n\n## Key Architecture Patterns\n\n- **SS.UserModel interfaces** (`IWorkbook`, `ISheet`, `IRow`, `ICell`) abstract\n  over both HSSF and XSSF. Prefer these when writing format-agnostic code.\n\n- **SXSSF streaming layer** — classes in `ooxml/XSSF/Streaming/` wrap the\n  corresponding XSSF classes with a configurable row window for low-memory\n  streaming writes.\n\n- **OpenXmlFormats are POCOs** — the classes in `OpenXmlFormats/` map directly\n  to the ECMA-376 (OOXML) XML schemas. Business logic that operates on these\n  types lives in `ooxml/` or `main/`, not alongside the schema classes.\n\n- **OPC packaging** (`openxml4Net/`) handles the zip container structure shared\n  by `.xlsx`, `.docx`, and `.pptx` files. Format-specific layers read and write\n  individual XML parts through this packaging layer.\n\n- **Design patterns** — NPOI uses:\n  - **Strategy**: format-specific implementations behind interfaces\n  - **Factory**: `CreateSheet()`, `CreateRow()`, `CreateCell()` maintain parent-child consistency\n  - **Decorator**: SXSSF wraps XSSF, intercepting writes for streaming\n  - **Flyweight**: `StylesTable` and `SharedStringsTable` deduplicate formatting and strings\n  - **Template Method**: interface methods with HSSF/XSSF format-specific implementations\n\n- **HSSF uses records** — `InternalWorkbook`/`InternalSheet` aggregate BIFF8 records\n  (`SSTRecord`, `ExtendedFormatRecord`, `RowRecord`, etc.)\n\n- **XSSF uses XML beans** — OpenXmlFormats classes (`CT_Workbook`, `CT_Worksheet`,\n  `CT_Row`, `CT_Cell`) map to OOXML XML elements\n\n## Building and Testing\n\n```bash\n# Build\ndotnet build solution/NPOI.Core.sln\n\n# Run tests\ndotnet test solution/NPOI.Core.Test.sln\n\n# Run benchmarks\ndotnet run -c Release --project benchmarks/NPOI.Benchmarks/\n```\n\n## Code Verification\n\nAfter making changes:\n1. Build the solution to catch compilation errors\n2. Run relevant tests to verify functionality\n3. Check for style violations if present (look for editorconfig or style guidelines)\n\n## Common Tasks\n\n### Adding a new format/feature\n1. Check existing implementations in `main/` or `ooxml/` for patterns\n2. Add tests in `testcases/` with sample files in `testcases/test-data/`\n3. Follow the SS.UserModel interface pattern for format-agnostic features\n\n### Working with OOXML formats\n1. Schema classes live in `OpenXmlFormats/` (do not add logic here)\n2. Business logic goes in `ooxml/` using the schema classes\n3. Use the OPC packaging layer (`openxml4Net/`) for zip operations\n\n## Test Data\n\nTest fixture files (`.xls`, `.xlsx`, `.docx`, etc.) live under\n`testcases/test-data/` organized by format. Tests reference these files via\nrelative paths from the test project root.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI agents and new contributors working in this codebase.\n\n## Project Overview\n\nNPOI is a .NET port of [Apache POI](https://poi.apache.org/) for reading and\nwriting Microsoft Office file formats without requiring COM or an Office\ninstallation. Targets net472, netstandard2.0, netstandard2.1, and net8.0.\n\n## Code Style\n\n- Use 4 spaces for indentation (default for .NET projects)\n- No comments unless explaining non-obvious business logic\n- Prefer `var` for local variables when type is clear from right-hand side\n- Follow existing patterns for nullable reference types (`string?` vs `string`)\n- Use XML documentation (`/// <summary>`) for public APIs only\n\n## Directory → Project Map\n\n| Directory         | Project                      | Purpose                                                        |\n|-------------------|------------------------------|----------------------------------------------------------------|\n| `main/`           | NPOI.Core                    | HSSF (.xls), HPSF (doc properties), SS model, DDF, utilities  |\n| `ooxml/`          | NPOI.OOXML                   | XSSF (.xlsx), SXSSF (streaming), XWPF (.docx), XSLF (.pptx)  |\n| `OpenXmlFormats/` | NPOI.OpenXmlFormats          | C# classes mapping to OOXML XML schemas (data-only, no logic)  |\n| `openxml4Net/`    | NPOI.OpenXml4Net             | OPC packaging: zip I/O, content types, part relationships      |\n| `scratchpad/`     | (various)                    | HWPF (.doc binary), HSLF (.ppt binary), other legacy formats   |\n| `testcases/`      | Test project                 | Mirrors source structure; test data in `testcases/test-data/`  |\n| `build/`          | _build (Nuke)                | Build automation                                               |\n| `benchmarks/`     | NPOI.Benchmarks              | BenchmarkDotNet performance tests                              |\n| `solution/`       | Solution/packaging files     | `.sln` files and NuGet pack project                            |\n\n## Format Acronyms\n\nThese names come from Apache POI and appear throughout the codebase:\n\n- **HSSF** — Horrible SpreadSheet Format (binary `.xls`)\n- **XSSF** — XML SpreadSheet Format (`.xlsx`)\n- **SXSSF** — Streaming XSSF (write-only sliding window over XSSF)\n- **HWPF** — Horrible Word Processor Format (binary `.doc`)\n- **XWPF** — XML Word Processor Format (`.docx`)\n- **HSLF** — Horrible SLide Format (binary `.ppt`)\n- **XSLF** — XML SLide Format (`.pptx`)\n- **HPSF** — Horrible Property Set Format (document metadata)\n- **SS** — Common spreadsheet interfaces (`ISheet`, `IRow`, `ICell`) shared by HSSF and XSSF\n- **DDF** — Dreadful Drawing Format (shapes/drawing records in binary formats)\n\n## Format Selection Guide\n\n| Format | Use When | Memory | Limitations |\n|--------|----------|--------|-------------|\n| **HSSF** | Reading/writing `.xls` (Excel 97-2003) | Medium | 65,536 row limit |\n| **XSSF** | Reading/writing `.xlsx`, full features needed | High | Memory scales with file size |\n| **SXSSF** | Writing large `.xlsx` files (>100K rows) | Low (constant) | Write-only, limited random access |\n\n## Key Architecture Patterns\n\n- **SS.UserModel interfaces** (`IWorkbook`, `ISheet`, `IRow`, `ICell`) abstract\n  over both HSSF and XSSF. Prefer these when writing format-agnostic code.\n\n- **SXSSF streaming layer** — classes in `ooxml/XSSF/Streaming/` wrap the\n  corresponding XSSF classes with a configurable row window for low-memory\n  streaming writes.\n\n- **OpenXmlFormats are POCOs** — the classes in `OpenXmlFormats/` map directly\n  to the ECMA-376 (OOXML) XML schemas. Business logic that operates on these\n  types lives in `ooxml/` or `main/`, not alongside the schema classes.\n\n- **OPC packaging** (`openxml4Net/`) handles the zip container structure shared\n  by `.xlsx`, `.docx`, and `.pptx` files. Format-specific layers read and write\n  individual XML parts through this packaging layer.\n\n- **Design patterns** — NPOI uses:\n  - **Strategy**: format-specific implementations behind interfaces\n  - **Factory**: `CreateSheet()`, `CreateRow()`, `CreateCell()` maintain parent-child consistency\n  - **Decorator**: SXSSF wraps XSSF, intercepting writes for streaming\n  - **Flyweight**: `StylesTable` and `SharedStringsTable` deduplicate formatting and strings\n  - **Template Method**: interface methods with HSSF/XSSF format-specific implementations\n\n- **HSSF uses records** — `InternalWorkbook`/`InternalSheet` aggregate BIFF8 records\n  (`SSTRecord`, `ExtendedFormatRecord`, `RowRecord`, etc.)\n\n- **XSSF uses XML beans** — OpenXmlFormats classes (`CT_Workbook`, `CT_Worksheet`,\n  `CT_Row`, `CT_Cell`) map to OOXML XML elements\n\n## Building and Testing\n\n```bash\n# Build\ndotnet build solution/NPOI.Core.sln\n\n# Run tests\ndotnet test solution/NPOI.Core.Test.sln\n\n# Run benchmarks\ndotnet run -c Release --project benchmarks/NPOI.Benchmarks/\n```\n\n## Code Verification\n\nAfter making changes:\n1. Build the solution to catch compilation errors\n2. Run relevant tests to verify functionality\n3. Check for style violations if present (look for editorconfig or style guidelines)\n\n## Common Tasks\n\n### Adding a new format/feature\n1. Check existing implementations in `main/` or `ooxml/` for patterns\n2. Add tests in `testcases/` with sample files in `testcases/test-data/`\n3. Follow the SS.UserModel interface pattern for format-agnostic features\n\n### Working with OOXML formats\n1. Schema classes live in `OpenXmlFormats/` (do not add logic here)\n2. Business logic goes in `ooxml/` using the schema classes\n3. Use the OPC packaging layer (`openxml4Net/`) for zip operations\n\n## Test Data\n\nTest fixture files (`.xls`, `.xlsx`, `.docx`, etc.) live under\n`testcases/test-data/` organized by format. Tests reference these files via\nrelative paths from the test project root.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nGuidance for AI agents and new contributors working in this codebase.\n\n## Project Overview\n\nNPOI is a .NET port of [Apache POI](https://poi.apache.org/) for reading and\nwriting Microsoft Office file formats without requiring COM or an Office\ninstallation. Targets net472, netstandard2.0, netstandard2.1, and net8.0.\n\n## Code Style\n\n- Use 4 spaces for indentation (default for .NET projects)\n- No comments unless explaining non-obvious business logic\n- Prefer `var` for local variables when type is clear from right-hand side\n- Follow existing patterns for nullable reference types (`string?` vs `string`)\n- Use XML documentation (`/// <summary>`) for public APIs only\n\n## Directory → Project Map\n\n| Directory         | Project                      | Purpose                                                        |\n|-------------------|------------------------------|----------------------------------------------------------------|\n| `main/`           | NPOI.Core                    | HSSF (.xls), HPSF (doc properties), SS model, DDF, utilities  |\n| `ooxml/`          | NPOI.OOXML                   | XSSF (.xlsx), SXSSF (streaming), XWPF (.docx), XSLF (.pptx)  |\n| `OpenXmlFormats/` | NPOI.OpenXmlFormats          | C# classes mapping to OOXML XML schemas (data-only, no logic)  |\n| `openxml4Net/`    | NPOI.OpenXml4Net             | OPC packaging: zip I/O, content types, part relationships      |\n| `scratchpad/`     | (various)                    | HWPF (.doc binary), HSLF (.ppt binary), other legacy formats   |\n| `testcases/`      | Test project                 | Mirrors source structure; test data in `testcases/test-data/`  |\n| `build/`          | _build (Nuke)                | Build automation                                               |\n| `benchmarks/`     | NPOI.Benchmarks              | BenchmarkDotNet performance tests                              |\n| `solution/`       | Solution/packaging files     | `.sln` files and NuGet pack project                            |\n\n## Format Acronyms\n\nThese names come from Apache POI and appear throughout the codebase:\n\n- **HSSF** — Horrible SpreadSheet Format (binary `.xls`)\n- **XSSF** — XML SpreadSheet Format (`.xlsx`)\n- **SXSSF** — Streaming XSSF (write-only sliding window over XSSF)\n- **HWPF** — Horrible Word Processor Format (binary `.doc`)\n- **XWPF** — XML Word Processor Format (`.docx`)\n- **HSLF** — Horrible SLide Format (binary `.ppt`)\n- **XSLF** — XML SLide Format (`.pptx`)\n- **HPSF** — Horrible Property Set Format (document metadata)\n- **SS** — Common spreadsheet interfaces (`ISheet`, `IRow`, `ICell`) shared by HSSF and XSSF\n- **DDF** — Dreadful Drawing Format (shapes/drawing records in binary formats)\n\n## Format Selection Guide\n\n| Format | Use When | Memory | Limitations |\n|--------|----------|--------|-------------|\n| **HSSF** | Reading/writing `.xls` (Excel 97-2003) | Medium | 65,536 row limit |\n| **XSSF** | Reading/writing `.xlsx`, full features needed | High | Memory scales with file size |\n| **SXSSF** | Writing large `.xlsx` files (>100K rows) | Low (constant) | Write-only, limited random access |\n\n## Key Architecture Patterns\n\n- **SS.UserModel interfaces** (`IWorkbook`, `ISheet`, `IRow`, `ICell`) abstract\n  over both HSSF and XSSF. Prefer these when writing format-agnostic code.\n\n- **SXSSF streaming layer** — classes in `ooxml/XSSF/Streaming/` wrap the\n  corresponding XSSF classes with a configurable row window for low-memory\n  streaming writes.\n\n- **OpenXmlFormats are POCOs** — the classes in `OpenXmlFormats/` map directly\n  to the ECMA-376 (OOXML) XML schemas. Business logic that operates on these\n  types lives in `ooxml/` or `main/`, not alongside the schema classes.\n\n- **OPC packaging** (`openxml4Net/`) handles the zip container structure shared\n  by `.xlsx`, `.docx`, and `.pptx` files. Format-specific layers read and write\n  individual XML parts through this packaging layer.\n\n- **Design patterns** — NPOI uses:\n  - **Strategy**: format-specific implementations behind interfaces\n  - **Factory**: `CreateSheet()`, `CreateRow()`, `CreateCell()` maintain parent-child consistency\n  - **Decorator**: SXSSF wraps XSSF, intercepting writes for streaming\n  - **Flyweight**: `StylesTable` and `SharedStringsTable` deduplicate formatting and strings\n  - **Template Method**: interface methods with HSSF/XSSF format-specific implementations\n\n- **HSSF uses records** — `InternalWorkbook`/`InternalSheet` aggregate BIFF8 records\n  (`SSTRecord`, `ExtendedFormatRecord`, `RowRecord`, etc.)\n\n- **XSSF uses XML beans** — OpenXmlFormats classes (`CT_Workbook`, `CT_Worksheet`,\n  `CT_Row`, `CT_Cell`) map to OOXML XML elements\n\n## Building and Testing\n\n```bash\n# Build\ndotnet build solution/NPOI.Core.sln\n\n# Run tests\ndotnet test solution/NPOI.Core.Test.sln\n\n# Run benchmarks\ndotnet run -c Release --project benchmarks/NPOI.Benchmarks/\n```\n\n## Code Verification\n\nAfter making changes:\n1. Build the solution to catch compilation errors\n2. Run relevant tests to verify functionality\n3. Check for style violations if present (look for editorconfig or style guidelines)\n\n## Common Tasks\n\n### Adding a new format/feature\n1. Check existing implementations in `main/` or `ooxml/` for patterns\n2. Add tests in `testcases/` with sample files in `testcases/test-data/`\n3. Follow the SS.UserModel interface pattern for format-agnostic features\n\n### Working with OOXML formats\n1. Schema classes live in `OpenXmlFormats/` (do not add logic here)\n2. Business logic goes in `ooxml/` using the schema classes\n3. Use the OPC packaging layer (`openxml4Net/`) for zip operations\n\n## Test Data\n\nTest fixture files (`.xls`, `.xlsx`, `.docx`, etc.) live under\n`testcases/test-data/` organized by format. Tests reference these files via\nrelative paths from the test project root.\n","category":"root","tokens":1443}]}