Taeluf.com

AST Templates

AST Templates are displayed via @\ast(ast_path, ast/TEMPLATE_NAME)

Also See: Templates

Docs

  • AST Paths
  • Available Templates
  • Sample usage and output
  • Create AST Templates

AST Paths

AST Paths point to parsed pieces of code.

Tip: Use @\ast(ast_path, ast/debug) to print an AST to help you figure out child paths.

  • Class: class.Tlf\Scrawl
  • File: file.src/Scrawl.php
  • Docblock description: class.Tlf\Scrawl.docblock.description (docblock returns array, docblock.description returns string)
  • Named Method: class.Tlf\Scrawl.methods.get_template
    • methods is an array of methods. get_template is the name of one of those methods, so method.get_template retrieves that method's array AST.
    • docblock.attributes.ATTR_NAME also works like methods.
  • Unnamed array path: class.Tlf\Scrawl.comments.0
    • There are multiple comments in the Tlf\Scrawl class, but comments are not named, so you use the array index instead.
    • Note: not all // or # comments are captured due to limits in the Lexer

Available Templates

Available Templates: ast/default, ast/class_methods, ast/method, ast/class, ast/function_list, ast/debug

ast/default

Print a string AST value. This is the default and is used when you do not specify a template name.

Usage: @\ast(class.\Tlf\Scrawl.docblock.description)

Output: The string value pointed to by the AST key.

ast/class_methods

Print a list of methods on a class

Usage: @\ast(class.Tlf\Scrawl\Extension\Notes, ast/class_methods)

Output: simple markdown list of methods on the given class

ast/method

Print information about a single method

Usage: @\ast(class.Tlf\Scrawl.methods.get_ast, ast/method)

Output: method name and docblock description.

ast/class

Print detailed class information.

Usage: @\ast(class.Tlf\Scrawl\Extension\Notes, ast/class)

Output: extensive documentation on a class - constants, properties, methods, etc.

ast/function_list

Print a list of functions within a file

Usage: @\ast(file.docsrc/test/functions.php, ast/function_list)

Output: simple markdown list of function names with their docblock descriptions

ast/debug

Print an ast array for debugging purposes, to help you figure out what AST keys to use with non-debug templates

Usage: @\ast(class.Tlf\Scrawl\Extension\Notes.methods.scan_file_processed.docblock, ast/debug) - Any AST key for the first param is valid, such as class.CLASS_NAME only

Output: array of the AST pointed to by the given key.

Sample usage and output

default

Example: (Display the description of the docblock on Tlf\Scrawl)

@\ast(class.Tlf\Scrawl.docblock.description)

Output:

Central class for running scrawl.

debug

Example: (Print the AST array of the docblock of Notes::scan_file_processed())

@\ast(class.Tlf\Scrawl\Extension\Notes.methods.scan_file_processed.docblock, ast/debug)

Output:

  
Key:class.Tlf\Scrawl\Extension\Notes.methods.scan_file_processed.docblock  
AST Value:   
Array  
(  
    [type] => docblock  
    [description] => Record each @NOTE line with it's file path & line number information  
  
Called when an individual file is finished being processed  
  
    [attribute] => Array  
        (  
            [0] => Array  
                (  
                    [type] => attribute  
                    [name] => param  
                    [description] => $path absolute path to the file  
                )  
  
            [1] => Array  
                (  
                    [type] => attribute  
                    [name] => param  
                    [description] => $relPath relative path to the file  
                )  
  
            [2] => Array  
                (  
                    [type] => attribute  
                    [name] => param  
                    [description] => $file_content the content of the file  
                )  
  
            [3] => Array  
                (  
                    [type] => attribute  
                    [name] => param  
                    [description] => $file_exports array of all items exported from just this file  
                )  
  
        )  
  
)

class

Example: (Print extensive class information on Tlf\Scrawl\Extension\Notes)

@\ast(class.Tlf\Scrawl\Extension\Notes, ast/class)

Output:

# class Tlf\Scrawl\Extension\Notes  
Creates `Notes.md` documentation file listing all @\NOTE lines in scanned directories.  
See source code at [/src/Ext/Notes.php](/src/Ext/Notes.php)  
  
## Constants  
  
## Properties  
- `protected array $notes = [];` notes: <string rel_file_path, array notes_within_file>  
notes_within_file: <int index, array note>  
note: ['file'=>string, 'line_num'=>int, 'line'=>string]. line is trimmed  
  
## Methods   
- `public function scan_file_processed(string $path, string $relPath, string $file_content, array $file_exports)` Record each @NOTE line with it's file path & line number information  
  
Called when an individual file is finished being processed  
  
- `public function scan_filelist_processed(array $code_files, array $all_exports)` Write the Notes.md file  
  
Called when all files are finished being processed

class_methods

Example: (Print a list of methods on class Tlf\Scrawl\Extension\Notes)

@\ast(class.Tlf\Scrawl\Extension\Notes, ast/class_methods)

Output:

- `$notes->scan_file_processed(string $path, string $relPath, string $file_content, array $file_exports)`: Record each @NOTE line with it's file path & line number information  
      
    Called when an individual file is finished being processed  
- `$notes->scan_filelist_processed(array $code_files, array $all_exports)`: Write the Notes.md file  
      
    Called when all files are finished being processed

function_list

Example: (Print a list of functions in file docsrc/test/functions.php)

@\ast(file.docsrc/test/functions.php, ast/function_list)

Output:

# File docsrc/test/functions.php  
## Functions  
- `one`: Return one book.  
- `many`: Return many books

method

Example: (Print method information for method Tlf\Scrawl::get_ast())

@\ast(class.Tlf\Scrawl.methods.get_ast, ast/method)

Output:

# Scrawl::get_ast    
Get an array AST from a PHP file

Testing un-named array

Example: (Print comments in class Tlf\Scrawl)

First Comment:  
@\ast(class.Tlf\Scrawl.comments.0, ast/debug)  
  
  
Comments Array:  
@\ast(class.Tlf\Scrawl.comments, ast/debug)

Output:

First Comment:  
  
Key:class.Tlf\Scrawl.comments.0  
AST Value:   
public function call_extensions($hook){  
  
  
Comments Array:  
  
Key:class.Tlf\Scrawl.comments  
AST Value:   
Array  
(  
    [0] => public function call_extensions($hook){  
    [1] =>   
    [2] => }  
)

Create AST Templates

  1. Create a .md.php template file, as described in Templates
  2. Code your AST Template. $args array is passed to it.
    • @\ast(class.Tlf\Scrawl, your/ast_class_template) will load your/ast_class_template.md.php in one of the template directories.
    • $this is the Tlf\Scrawl instance. (See Extensions for 'Useful Scrawl Methods')
    • $args[0] is the AST path, like class.Tlf\Scrawl
    • $args[1] is the AST array or value returned from that path (array in this example)
    • $args[2] is the Tlf\Scrawl\Ext\MdVerb\Ast instance