From 2846cf83f0901b024b3d0f06ae9440e53394cede Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Fri, 19 Sep 2025 23:51:58 -0400 Subject: [PATCH] feat(doc): comprehensive documentation on missing things --- doc/cp.txt | 242 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 216 insertions(+), 26 deletions(-) diff --git a/doc/cp.txt b/doc/cp.txt index 693077f..e2111b1 100644 --- a/doc/cp.txt +++ b/doc/cp.txt @@ -72,9 +72,47 @@ COMMANDS *cp-commands* :CP next Navigate to next problem in current contest. Stops at last problem (no wrapping). + Navigation Commands ~ :CP prev Navigate to previous problem in current contest. Stops at first problem (no wrapping). +Command Flags ~ + *cp-flags* + Flags can be used with setup and action commands: + + --lang={language} Specify language for the problem. + --lang {language} Alternative syntax for language specification. + Supported languages: cpp, python + Example: > + :CP atcoder abc324 a --lang=python + :CP b --lang cpp +< + --debug Enable debug compilation with additional flags. + Uses the `debug` command template instead of + `compile`. Typically includes debug symbols and + sanitizers for memory error detection. + Example: > + :CP run --debug +< + Note: Debug compilation may be slower but provides + better error reporting for runtime issues. + +Template Variables ~ + *cp-template-vars* + Command templates support variable substitution using `{variable}` syntax: + + • {source} Source file path (e.g. "abc324a.cpp") + • {binary} Output binary path (e.g. "build/abc324a.run") + • {version} Language version when specified in config + • {contest} Contest identifier (e.g. "abc324", "1933") + • {problem} Problem identifier (e.g. "a", "b") + + Example template: > + compile = { 'g++', '{source}', '-o', '{binary}', '-std=c++{version}' } +< Would expand to: > + g++ abc324a.cpp -o build/abc324a.run -std=c++17 +< + ============================================================================== CONFIGURATION *cp-config* @@ -171,7 +209,17 @@ Here's an example configuration with lazy.nvim: >lua *cp.DiffConfig* Fields: ~ - {git} (|DiffGitConfig|) Git diff backend configuration. + {git} (|cp.DiffGitConfig|) Git diff backend configuration. + + *cp.DiffGitConfig* + Fields: ~ + {args} (string[]) Command-line arguments for git diff. + Default: { 'diff', '--no-index', '--word-diff=plain', + '--word-diff-regex=.', '--no-prefix' } + • --no-index: Compare files outside git repository + • --word-diff=plain: Character-level diff markers + • --word-diff-regex=.: Split on every character + • --no-prefix: Remove a/ b/ prefixes from output *cp.Hooks* Fields: ~ @@ -184,6 +232,8 @@ Here's an example configuration with lazy.nvim: >lua function(ctx: ProblemContext) *ProblemContext* + Context object passed to hook functions containing problem information. + Fields: ~ {contest} (string) Platform name (e.g. "atcoder", "codeforces") {contest_id} (string) Contest ID (e.g. "abc123", "1933") @@ -195,6 +245,15 @@ Here's an example configuration with lazy.nvim: >lua {expected_file} (string) Expected output path (e.g. "io/abc123a.expected") {problem_name} (string) Display name (e.g. "abc123a") + Example usage in hook: >lua + hooks = { + setup_code = function(ctx) + print("Setting up " .. ctx.problem_name) + print("Source file: " .. ctx.source_file) + end + } +< + ============================================================================== WORKFLOW *cp-workflow* @@ -209,26 +268,49 @@ AtCoder ~ *cp-atcoder* URL format: https://atcoder.jp/contests/abc123/tasks/abc123_a +AtCoder contests use consistent naming patterns where contest ID and problem +ID are combined to form the task name. + +Platform characteristics: +• Contest types: ABC (Beginner), ARC (Regular), AGC (Grand), etc. +• Problem naming: Contest ID + problem letter (e.g. "abc324_a") +• Multi-test problems: Handled with conditional compilation directives +• Template features: Includes fast I/O and common competitive programming + headers + In terms of cp.nvim, this corresponds to: - Platform: atcoder -- Contest ID: abc123 -- Problem ID: a +- Contest ID: abc123 (from URL path segment) +- Problem ID: a (single letter, extracted from task name) Usage examples: > - :CP atcoder abc123 a " Full setup: problem A from contest ABC123 - :CP atcoder abc123 " Contest setup: load contest metadata only + :CP atcoder abc324 a " Full setup: problem A from contest ABC324 + :CP atcoder abc324 " Contest setup: load contest metadata only :CP b " Switch to problem B (if contest loaded) :CP next " Navigate to next problem in contest < + Note: AtCoder template includes optimizations + for multi-test case problems commonly found + in contests. Codeforces ~ *cp-codeforces* URL format: https://codeforces.com/contest/1234/problem/A +Codeforces uses numeric contest IDs with letter-based problem identifiers. +Educational rounds, gym contests, and regular contests all follow this pattern. + +Platform characteristics: +• Contest types: Regular, Educational, Div. 1/2/3, Global rounds +• Problem naming: Numeric contest + problem letter +• Multi-test support: Template includes test case loop structure +• Interactive problems: Supported with flush handling +• Time/memory limits: Typically 1-2 seconds, 256 MB + In terms of cp.nvim, this corresponds to: - Platform: codeforces -- Contest ID: 1234 -- Problem ID: a (lowercase) +- Contest ID: 1234 (numeric, from URL) +- Problem ID: a (lowercase letter, normalized from URL) Usage examples: > :CP codeforces 1934 a " Full setup: problem A from contest 1934 @@ -236,24 +318,35 @@ Usage examples: > :CP c " Switch to problem C (if contest loaded) :CP prev " Navigate to previous problem in contest < + Note: Problem IDs are automatically converted + to lowercase for consistency. CSES ~ *cp-cses* URL format: https://cses.fi/problemset/task/1068 -CSES is organized by categories rather than contests. Currently all problems -are grouped under "CSES Problem Set" category. +CSES (Code Submission Evaluation System) is organized by problem categories +rather than traditional contests. All problems are accessible individually. + +Platform characteristics: +• Organization: Category-based (Introductory, Sorting, Dynamic Programming) +• Problem numbering: Sequential numeric IDs (1001, 1068, etc.) +• Difficulty progression: Problems increase in complexity within categories +• No time pressure: Educational focus rather than contest environment +• Cache expiry: 30 days (problems may be updated periodically) In terms of cp.nvim, this corresponds to: - Platform: cses -- Contest ID: "CSES Problem Set" (category) -- Problem ID: 1068 (numeric) +- Contest ID: Problem ID (1068) - used as both contest and problem identifier +- Problem ID: nil (not applicable for CSES structure) Usage examples: > :CP cses 1068 " Set up problem 1068 from CSES - :CP 1070 " Switch to problem 1070 (if CSES loaded) - :CP next " Navigate to next problem in CSES + :CP 1070 " Switch to problem 1070 (if CSES context loaded) + :CP next " Navigate to next problem in CSES sequence < + Note: CSES problems are treated as individual + entities rather than contest problems. ============================================================================== COMPLETE WORKFLOW EXAMPLE *cp-example* @@ -312,20 +405,26 @@ Activation ~ Interface ~ -The run panel uses a professional table layout with precise column alignment: > +The run panel uses the following table layout: > - ┌──┬────────┬────────┬───────────┐ ┌─ Expected vs Actual ─────────┐ - │# │ Status │ Time │ Exit Code │ │ 45.70ms │ Exit: 0 │ - ├──┼────────┼────────┼───────────┤ ├───────────────────────────────┤ - │1 │ AC │12.00ms │ 0 │ │ │ - │>2│ WA │45.70ms │ 1 │ │ 4[-2-]{+3+} │ - ├──┴────────┴────────┴───────────┤ │ 100 │ - │5 3 │ │ hello w[-o-]r{+o+}ld │ - ├──┬────────┬────────┬───────────┤ │ │ - │3 │ AC │ 9.00ms │ 0 │ └───────────────────────────────┘ - │4 │ RTE │ 0.00ms │139 (SIGUSR2)│ - └──┴────────┴────────┴───────────┘ -< + ┌─────┬────────┬──────────────┬───────────┬──────────┬─────────────┐ + │ # │ Status │ Runtime (ms) │ Time (ms) │ Mem (MB) │ Exit Code │ + ├─────┼────────┼──────────────┼───────────┼──────────┼─────────────┤ + │ 1 │ AC │ 12.0 │ 2000 │ 256 │ 0 │ + │> 2 │ WA │ 45.70 │ 2000 │ 256 │ 1 │ + ├─────┴────────┴──────────────┴───────────┴──────────┴─────────────┤ + │Input: │ + │5 3 │ + ├─────┬────────┬──────────────┬───────────┬──────────┬─────────────┤ + │ 3 │ AC │ 9.0 │ 2000 │ 256 │ 0 │ + │ 4 │ RTE │ 0.0 │ 2000 │ 256 │139 (SIGUSR2)│ + └─────┴────────┴──────────────┴───────────┴──────────┴─────────────┘ + ┌──────────────────────────────────────────────────────────────────┐ + │Expected vs Actual │ + │4[-2-]{+3+} │ + │100 │ + │hello w[-o-]r{+o+}ld │ + └──────────────────────────────────────────────────────────────────┘ Status Indicators ~ @@ -396,6 +495,97 @@ cp.nvim creates the following file structure upon problem setup: > The plugin automatically manages this structure and navigation between problems maintains proper file associations. +============================================================================== +CACHING SYSTEM *cp-caching* + +cp.nvim maintains a persistent cache to improve performance and enable offline +functionality. The cache stores contest metadata, problem lists, test cases, +and file-to-context mappings. + +Cache Location ~ + *cp-cache-location* +Cache is stored at: > + vim.fn.stdpath('data') .. '/cp-nvim.json' +< +Typically resolves to: +• Linux/macOS: `~/.local/share/nvim/cp-nvim.json` +• Windows: `%LOCALAPPDATA%\nvim-data\cp-nvim.json` + +Cache Structure ~ + *cp-cache-structure* +The cache contains four main sections: + +contest_data Contest metadata and problem lists +• Indexed by: `platform:contest_id` +• Contains: Problem names, IDs, URLs, constraints +• Expiry: Platform-dependent (see |cp-cache-expiry|) + +test_cases Scraped test case input/output pairs +• Indexed by: `platform:contest_id:problem_id` +• Contains: Input data, expected output, test case count +• Expiry: Never (local test data persists) + +file_states File-to-context mapping +• Indexed by: Absolute file path +• Contains: Platform, contest_id, problem_id, language +• Purpose: Enables context restoration with `:CP` + +timestamps Last update times for cache validation +• Tracks: When each cache entry was last refreshed +• Used for: Expiry checking and incremental updates + +Cache Expiry Policy ~ + *cp-cache-expiry* +Different data types have different expiry policies: + +AtCoder/Codeforces contest data Never expires (contests are immutable) +CSES problem data 30 days (problems may be updated) +Test cases Never expires (local test data) +File states Never expires (tracks user workspace) + +Manual Cache Management ~ + *cp-cache-management* +While cache management is automatic, you can manually intervene: + +Clear specific contest cache: > + :lua require('cp.cache').clear_contest('atcoder', 'abc324') +< +Clear all cache data: > + :lua require('cp.cache').clear_all() +< +Force refresh contest metadata: > + :lua require('cp.cache').refresh_contest('codeforces', '1934') +< +View cache statistics: > + :lua print(vim.inspect(require('cp.cache').get_stats())) +< + Note: Manual cache operations require Lua + knowledge and are primarily for debugging. + +Offline Functionality ~ + *cp-cache-offline* +The cache enables limited offline functionality: + +✓ Restore context from cached file states +✓ Navigate between cached problems in a contest +✓ Access cached test cases for local development +✓ Use cached templates and configuration + +✗ Scrape new problems without internet connection +✗ Download new contest metadata +✗ Update problem constraints or test cases + +Performance Considerations ~ + *cp-cache-performance* +The cache provides several performance benefits: + +• Instant context restoration: No network requests needed +• Fast problem navigation: Problem lists loaded from cache +• Reduced scraping: Test cases cached after first download +• Batch operations: Multiple problems can be set up quickly + +Cache size typically remains under 1MB even with extensive usage. + ============================================================================== SNIPPETS *cp-snippets*