Taeluf.com

AST Templates

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

Also See: @see_files(docs/Templates.md; 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: @template(Scrawl/ShortAstTemplatesList)

@template(Scrawl/AstTemplates)

Sample usage and output

default

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

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

Output:

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

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:

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

class

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

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

Output:

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

class_methods

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

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

Output:

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

function_list

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

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

Output:

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

method

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

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

Output:

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

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:
@ast(class.Tlf\Scrawl.comments.0, ast/debug)


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

Create AST Templates

  1. Create a .md.php template file, as described in @see(docs/Templates.md, 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 @see(docs/Extensions.md, 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