ALTO CodeSlicer

Extract immutable source-code slices by line, text, or language structure while preserving exact byte ranges and line numbers.

         

CodeSlicer loads a complete source and progressively narrows an immutable CodeSlice. Every slice keeps its language, source name, and original line numbers.

use Alto\Code\Slicer\CodeSource;

$slice = CodeSource::fromFile('src/Command/BuildCommand.php')
    ->slice()
    ->method('execute');

echo $slice->content();
echo $slice->startLine();

Selection stops before presentation. CodeSlicer returns source ranges and leaves syntax tokens, annotations, highlighting, and rendering to downstream consumers.

Installation

Install ALTO CodeSlicer with Composer:

composer require alto/code-slicer

CodeSlicer requires PHP 8.4 or later, the tokenizer extension, and alto/language.

Quick Start

Select a PHP method from an in-memory source:

use Alto\Code\Slicer\CodeSource;

$source = CodeSource::fromString(
    <<<'PHP'
final class Checkout
{
    public function complete(): void
    {
        // ...
    }
}
PHP,
    'php',
    'Checkout.php',
);

$slice = $source
    ->slice()
    ->method('complete');

echo $slice->content();

Every selection returns a new CodeSlice; the source and previous slices remain unchanged.

Creating sources

fromFile() reads a local file and resolves its language through alto/language:

$source = CodeSource::fromFile('assets/checkout_controller.js');

$source->language()?->slug; // javascript
$source->name();            // assets/checkout_controller.js
$source->lineCount();

For in-memory code, pass an optional language explicitly. The optional name is metadata and does not imply that a file exists:

use Alto\Code\Slicer\CodeSource;

$source = CodeSource::fromString($code, 'php', 'Example.php');

Unknown and unnamed sources carry null as their language. Text and line selectors still work; structural selectors fail explicitly.

Selecting code

Line numbers are one-based, inclusive, and always refer to the complete source:

$slice = $source->lines(20, 42);
$narrower = $slice->lines(24, 30);

Text selectors are exact, case-sensitive, and limited to the current slice:

$slice = $source->slice()
    ->after('// example:start')
    ->before('// example:end');

Missing boundaries and attempts to expand a slice throw explicit exceptions rather than returning an approximate result.

Structural selectors

The available selectors follow each language's own vocabulary:

Language	Selectors
PHP	class(), method(), beforeNextClass(), beforeNextMethod(), beforeMethod(), afterMethod()
JavaScript and TypeScript	PHP selectors plus function()
CSS	rule(), atRule()
Twig	block(), macro()

Selectors compose to resolve scope and ambiguity:

$slice = $source->slice()
    ->class('CheckoutController')
    ->method('connect');

CSS at-rules can optionally include their prelude:

$slice = $source->slice()->atRule('media', '(width >= 48rem)');

Projection

source() and range() expose the complete source and the selected half-open byte range:

$source = $slice->source();
$range = $slice->range();

$source->content(); // complete source
$range->start;      // inclusive
$range->end;        // exclusive

This lets a downstream adapter parse or highlight the complete source first, then project its text and annotations onto the selected range. content() remains the exact, unmodified source region.

Package boundary

CodeSlice is the raw result of source extraction. Its complete source and byte range let a consumer analyze the full context before projecting the selected region into its own model.

CodeSlicer deliberately provides no HTML, SVG, Markdown, syntax tokens, themes, remote loaders, or source rewriting.

See the documentation for installation, a guided example, and the public API.

Contributing

Contributions of all kinds are welcome. Visit the project on GitHub to report a bug, suggest a feature, or open a pull request. Before submitting code, run:

# Runs PHP CS Fixer, PHPStan, and PHPUnit
composer qa

Changes to public behavior should include tests and documentation.

Support

ALTO CodeSlicer is open source. You can support its continued development through GitHub Sponsors.

Sharing this package with others or starring it on GitHub is also much appreciated.

License

ALTO CodeSlicer is released by ALTO PHP under the MIT License.