Add Describable interface for human-readable source descriptions#39
Draft
robertvansteen wants to merge 4 commits into0.xfrom
Draft
Add Describable interface for human-readable source descriptions#39robertvansteen wants to merge 4 commits into0.xfrom
robertvansteen wants to merge 4 commits into0.xfrom
Conversation
Introduces a new optional Describable interface with a describe(): string method that produces human-readable descriptions of Source trees. All five core Sources implement it: StaticSource, SymbolSource, TypeDefinition, InfixExpression, and UnaryExpression. Composite sources recursively describe their children, falling back to the class short name for non-Describable sources. https://claude.ai/code/session_011wv1MvWN6N2u8bYZZz8QA8
- Replace preg_replace with str_ends_with/substr in TypeDefinition to avoid PHPStan error from preg_replace's nullable return type - Add UsesClass attributes for Type classes used in DescribableTest - Add tests for non-Describable fallback branches in TypeDefinition, InfixExpression (both left and right), and UnaryExpression https://claude.ai/code/session_011wv1MvWN6N2u8bYZZz8QA8
Rework all Describable implementations to produce human-readable natural language descriptions instead of terse structured notation: - StaticSource: "the value 42" - SymbolSource: "the symbol 'price'" - TypeDefinition: "the symbol 'price' as a number" - InfixExpression: "the value 1 plus the value 2" with operator word mappings and parenthetical grouping for nested expressions - UnaryExpression: "the negation of the symbol 'active'" https://claude.ai/code/session_011wv1MvWN6N2u8bYZZz8QA8
Use raw values and operator symbols instead of verbose natural language: - StaticSource: 42, 'hello', null - SymbolSource: price, math.pi - TypeDefinition: price (as number) - InfixExpression: price * quantity, with parens for nesting - UnaryExpression: !active, -5 Complex example: price (as number) * (1 - rates.discount (as number)) https://claude.ai/code/session_011wv1MvWN6N2u8bYZZz8QA8
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR introduces a new
Describableinterface that enables source objects to provide human-readable descriptions of themselves. This is useful for textualizing the source tree for AI consumption and debugging purposes.The implementation adds the
describe()method to all expression and source classes, allowing them to recursively describe their structure in a readable format.Type of Change
Changes Made
Describableinterface insrc/Describable.phpwith adescribe(): stringmethodDescribableinStaticSourceto describe literal values (e.g.,"static value 'hello'")DescribableinSymbolSourceto describe symbol references with optional namespaces (e.g.,"symbol 'math.pi'")DescribableinTypeDefinitionto describe typed sources (e.g.,"number(symbol 'price')")DescribableinInfixExpressionto describe binary operations (e.g.,"(static value 1 + static value 2)")DescribableinUnaryExpressionto describe unary operations (e.g.,"(!symbol 'active')")DescribableTest) with 14 test cases covering all source types and nested expressionsTesting
DescribableTest.php)StaticSource,SymbolSource,TypeDefinition,InfixExpression,UnaryExpressionCode Quality Checklist
Breaking Changes
N/A - This is a new feature that doesn't affect existing functionality.
Additional Notes
The implementation uses reflection as a fallback for sources that don't implement
Describable, ensuring graceful degradation when working with custom source implementations. TheStaticSourceclass usesSebastianBergmann\Exporterfor consistent value formatting.https://claude.ai/code/session_011wv1MvWN6N2u8bYZZz8QA8