Extensions for Code Scrawl
Working with Regex
If your extension deals with any regex, you should use the Regex Matching Utility to make things way cleaner & easier
Extensions Api
The Gist:
- To expose something to
@import(CustomKey)
, calladdOutput('key', 'CustomKey', 'The string to import')
- To create a file, call
addOutput('file', 'rel/path.ext', 'This is the file content')
- To write an extension, extend
\Tlf\Scrawl\Extension
, add it to thescrawl.ext
config (see example), & override one or more of the extension Methods (bottom of page)
Extensions
For working with the set of available extensions (and adding to it)
-
addExtension($group, $extension)
: Add an extension to a group.- if
$group=='default'
,$extension
shouldextends \Tlf\Scrawl\Extension
orimplements \Tlf\Scrawl\ExtensionInterface
- if
$group=='docblock'
,$extension
should be a$callable
accepting(\Tlf\Scrawl\DocBlock $docBlock)
- else, it depends completely upon the code that calls the extension.
- if
-
getExtensions($group)
: Get an array of extensions for the given group -
extCall($group, $methodName, ...$arg)
: Loops over$getExtensions($group)
& calls$ext->$meethodName
on each one - Config
scrawl.ext
: Automatically callsaddExtension
. See the sample extension below. cli:scrawl -scrawl.ext group:class
Outputs
For pieces of information to share with other extensions
-
addOutput($group, $key, $content)
:-
@import(Something)
gets the$content
where$group=='key'
and$key=='Something'
- throws if
$group, $key
is already set - Any value can be set for
$content
, but$group
s may have expectations.$group=='key'
requires$content
be a string
-
-
setOutput($group, $key, $content)
: Same asaddOutput
, but does not throw if$group, $key
already set -
getOutput($group, $key)
: Get$content
for$group, $key
. -
getOutputs($group=null)
: Get akey=>value
array of the group specified OR of all groups ifnull
is given
Existing Output Groups:
-
$group=='key', $key='SomeThing'
is used to@import(SomeThing)
into markdown -
$group=='file', $key='Some/Path.ext'
is used to write$content
toPROJECT_ROOT/DOCS_DIR/Some/Path.ext
- @TODO programattically generate a list of all groups.
Sample Extensions
Extensions are currently written in PHP. (@TODO enable extensions in other languages)
1. Configure
Add to your .config/scrawl.json
(or use another config option):
{
"autoload": {
"classmap":["src"]
},
"scrawl.ext": {
"\\Your\\Space\\MyCoolExtension": "default"
}
}
2. Simple Extension class
Create src/MyCoolExtension.php
<?php
namespace Your\Space;
class MyCoolExtension extends \Tlf\Scrawl\Extension {
public function onSourceFileFound($srcFile){
$fileList = $this->scrawl->getOutput('key', 'AllFiles');
$fileList .= "\n- $srcFile->relPath";
$this->scrawl->setOutput('key','AllFiles', $fileList);
}
}
3. Import your new setting
Create docs-src/AllFiles.src.md
# All Source Files
@import(AllFiles)
4. Run Scrawl
You should have already followed the initial guide.
cd
to your project directory and execute scrawl
. docs/AllFiles.md
should now contain a list of all your source files.
@TODO Move this sample extension into a test & use @import()
s