diff --git a/README.md b/README.md index b1e53eb..5147b43 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# ALTO CodeKit +# ALTO Code Kit Compose source slicing and semantic highlighting into immutable annotated code snippets. @@ -8,7 +8,7 @@ Compose source slicing and semantic highlighting into immutable annotated code s   ![License](https://img.shields.io/github/license/altophp/code-kit?label=License&labelColor=050608&color=00B7FF)   [![GitHub Sponsors](https://img.shields.io/github/sponsors/smnandre?logo=githubsponsors&logoColor=00B7FF&label=%20Sponsor&labelColor=050608&color=00B7FF)](https://github.com/sponsors/smnandre) -CodeKit connects CodeSlicer, CodeHighlight, and CodeSnippet. It selects source code, derives semantic +Code Kit connects Code Slicer, Code Highlight, and Code Snippet. It selects source code, derives semantic syntax annotations, and returns a renderer-independent snippet while preserving source context. ```php @@ -32,11 +32,11 @@ Install ALTO CodeKit with Composer: composer require alto/code-kit ``` -CodeKit requires PHP 8.4 or later. It installs CodeSlicer, CodeHighlight, and CodeSnippet. +Code Kit requires PHP 8.4 or later. It installs Code Slicer, Code Highlight, and Code Snippet. ## Complete-source parsing -CodeKit parses the complete source before projecting the selected range. Context-sensitive syntax +Code Kit parses the complete source before projecting the selected range. Context-sensitive syntax therefore remains correct when a slice starts inside a docblock, string, heredoc, or embedded language. @@ -74,11 +74,12 @@ unannotated. ## Package boundary -CodeKit owns orchestration only. CodeSlicer locates source ranges, CodeHighlight parses syntax, and -CodeSnippet carries the immutable result. Rendering to HTML, SVG, PNG, terminals, or slides belongs +Code Kit owns orchestration only. Code Slicer locates source ranges, Code Highlight parses syntax, and +Code Snippet carries the immutable result. Rendering to HTML, SVG, PNG, terminals, or slides belongs to consumers. -See the [documentation](docs/index.md) for installation, a guided example, and the public API. +Read the [documentation](docs/index.md), then continue with +[Installation](docs/installation.md) and [Getting started](docs/getting-started.md). ## Contributing diff --git a/docs/getting-started.md b/docs/getting-started.md index 6cd2fc6..6953efb 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,35 +1,85 @@ # Getting started -Select a source region, then turn it into an annotated snippet: +After [installation](installation.md), save this as `snippet.php` beside +`vendor/` and run `php snippet.php`. The input is included, so the example does +not depend on an external source file. ```php +slice() - ->method('execute'); +$code = <<<'PHP' +snippet($slice) - ->dedent(); -``` +$source = CodeSource::fromString($code, 'php', 'checkout.php'); +$snippet = (new CodeKit())->snippet($source->lines(2, 2)); -CodeKit parses the complete source before projecting the selected range. Context-sensitive syntax -therefore remains correct when a slice starts inside a docblock, string, heredoc, or embedded -language. +printf("%s:%d\n", $snippet->sourceName(), $snippet->startLine()); +echo $snippet->code(), "\n"; -Use `annotate()` when a `CodeSnippet` already exists: +foreach ($snippet->annotations() as $annotation) { + printf( + "%s => %s/%s\n", + substr($snippet->code(), $annotation->offset, $annotation->length), + $annotation->data['scope'], + $annotation->data['tokenType'], + ); +} +``` -```php -$annotated = (new CodeKit())->annotate($snippet); +The script prints: + +```text +checkout.php:2 +$total = 42; +$total => variable/unknown += => operator/unknown +42 => number/unknown +; => punctuation/unknown ``` -Pass a language slug directly and use the same start and end line to return one line without -adjacent context: +The result retains the source name and original line number. Its annotations +carry semantic scope and token type data; they do not contain rendered HTML. + +## Create a snippet + +`CodeKit::snippet()` accepts a `CodeSlice`. It parses the complete source, +creates syntax annotations, and then projects the selected byte range into a +`CodeSnippet`. Complete-source parsing preserves context when a slice starts +inside a docblock, string, heredoc, or embedded language. ```php -$line = (new CodeKit())->snippet( +$snippet = (new CodeKit())->snippet( CodeSource::fromString($code, 'php')->lines(24, 24), ); ``` + +The source language controls parsing. When it is absent or unsupported, consult +the Code Highlight language documentation before changing the selected range. + +## Annotate a snippet + +Use `annotate()` when a `CodeSnippet` already exists: + +```php +use Alto\Code\Snippet\CodeSnippet; + +$snippet = CodeSnippet::fromCode('$total = array_sum($prices);', 'php'); +$annotated = (new CodeKit())->annotate($snippet); +``` + +The method parses the snippet code and returns a new value containing `syntax` +annotations. Existing metadata, selections, and annotations remain available. +Each syntax annotation contains the semantic `scope` and `tokenType` supplied +by Code Highlight; whitespace is left unannotated. + +Unlike `snippet()`, `annotate()` only has the snippet content as parsing +context. Use `snippet()` with a source slice when the selected code begins +inside context established earlier in the file. diff --git a/docs/index.md b/docs/index.md index e54d461..5ee7eb2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,10 +1,29 @@ -# CodeKit +# Alto Code Kit -CodeKit composes source selection, semantic parsing, and immutable annotated snippets. +ALTO Code Kit combines source selection, semantic parsing, and immutable +snippet data. It parses a complete source before projecting the selected range, +so a slice retains the context required to recognize comments, strings, +heredocs, and embedded languages. -- [Installation](installation.md) -- [Getting started](getting-started.md) -- [Public API](public-api.md) +```php +use Alto\Code\Kit\CodeKit; +use Alto\Code\Slicer\CodeSource; -The package is the integration boundary between CodeSlicer, CodeHighlight, and CodeSnippet. It does -not define source selectors, syntax parsers, snippet values, or renderers. +$source = CodeSource::fromString("snippet($source->lines(2, 2)); +echo $snippet->code(); +``` + +The example prints `return 42;` and the returned `CodeSnippet` carries syntax +annotations for its tokens. + +## Documentation + +- [Installation](installation.md): install Code Kit and its three component packages. +- [Getting started](getting-started.md): create or annotate a portable code snippet. + +## Boundaries + +Code Slicer owns source selection, Code Highlight owns syntax parsing, and Code +Snippet owns the immutable result. Code Kit composes them. Rendering to HTML, +SVG, PNG, terminals, or slides remains the responsibility of consumers. diff --git a/docs/installation.md b/docs/installation.md index d08bf41..5e9d773 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,10 +1,10 @@ # Installation -Install CodeKit with Composer: +Install ALTO Code Kit with Composer: ```bash composer require alto/code-kit ``` -CodeKit requires PHP 8.4 or later. It installs CodeSlicer, CodeHighlight, and CodeSnippet as runtime -dependencies. +ALTO Code Kit requires PHP 8.4 or later. It installs ALTO Code Slicer, Code +Highlight, and Code Snippet as runtime dependencies. diff --git a/docs/public-api.md b/docs/public-api.md deleted file mode 100644 index e307944..0000000 --- a/docs/public-api.md +++ /dev/null @@ -1,18 +0,0 @@ -# Public API - -## `CodeKit` - -`CodeKit` accepts an optional `CodeParser` in its constructor. - -### `snippet(CodeSlice $slice): CodeSnippet` - -Parses the complete source, creates syntax annotations, then projects the selected byte range into -a `CodeSnippet`. - -### `annotate(CodeSnippet $snippet): CodeSnippet` - -Parses the snippet code and returns a new value containing `syntax` annotations. Existing snippet -metadata, selections, and annotations remain available. - -Syntax annotation data contains the semantic `scope` and `tokenType` supplied by CodeHighlight. -Whitespace tokens are not annotated.