Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Auto-generate human-readable version of Gutenberg block grammar #6116

Merged
merged 6 commits into from
May 26, 2018
Merged

Docs: Auto-generate human-readable version of Gutenberg block grammar #6116

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ce82948
Grammar: Add proof-of-concept rule display name for Block_Attributes
mcsf Apr 11, 2018
544c68f
Add PEG.js grammar to parse Gutenberg block grammar
mcsf Apr 11, 2018
e7a770e
Docs: Grammar: Add autogenerated doc on Gutenberg block grammar
mcsf Apr 11, 2018
d690b56
Docs: Grammar: Add bin/generate-public-grammar.js, reusing pegjs inte…
mcsf Apr 28, 2018
0530cf7
Docs: Grammar: Render as HTML
mcsf Apr 28, 2018
d8d7be5
Docs: Grammar: Remove shell-based docgen helper
mcsf Apr 28, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Docs: Grammar: Render as HTML
  • Loading branch information
@mcsf
mcsf committed Apr 28, 2018
commit 0530cf75d0c7fb50b4b4a5ce825a84a04e43df61
37 changes: 28 additions & 9 deletions bin/generate-public-grammar.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,17 @@
#!/usr/bin/env node
const parser = require( '../node_modules/pegjs/lib/parser.js' );
const fs = require( 'fs' );
const path = require( 'path' );
const grammarSource = fs.readFileSync( './blocks/api/post.pegjs', 'utf8' );
const grammar = parser.parse( grammarSource );

function escape( text ) {
return text
.replace( /\t/g, '\\t' )
.replace( /\r/g, '\\r' )
.replace( /\n/g, '\\n' );
.replace( /\n/g, '\\n' )
.replace( /\&/g, '&' )
.replace( /</g, '&lt;' );
}

function isGroup( expression ) {
Expand Down Expand Up @@ -55,13 +58,6 @@ function flatten( expression ) {
return '!' + flattenUnary( expression.expression );

// Other groups
case 'grammar':
return expression.rules.map( flatten ).join( '\n\n' );
case 'rule':
expression.expression.isRuleTop = true;
const prefix = expression.expression.type === 'named' ?
'# ' + expression.expression.name + '\n' : '';
return prefix + expression.name + '\n = ' + flatten( expression.expression );
case 'sequence':
return expression.elements.map( flatten ).join( ' ' );
case 'choice':
Expand All @@ -79,9 +75,32 @@ function flatten( expression ) {
case 'named':
return flatten( expression.expression );

// Top-level formatting
case 'grammar':
return `<dl>${ expression.rules.map( flatten ).join( '' ) }</dl>`;
case 'rule':
expression.expression.isRuleTop = true;
const displayName = expression.expression.type === 'named' ?
expression.expression.name : '';
return `<dt>${ displayName }</dt>` +
`<dd><pre><header>${ expression.name }</header> = ` +
`${ flatten( expression.expression ) }</pre></dd>`;

default:
throw new Error( JSON.stringify( expression ) );
}
}

console.log( flatten( grammar ) );
fs.writeFileSync(
path.join( __dirname, '..', 'docs', 'grammar.md' ), `
# The Gutenberg block grammar

<style>
dl { display: flex; flex-wrap: wrap; font-size: 110%; }
dt, dd { flex: 40%; margin-bottom: 1em; }
dt { text-align: right; font-style: italic; font-size: 105%; }
dd header { font-weight: bold; }
pre { margin: 0; }
</style>
${ flatten( grammar ) }
` );
9 changes: 4 additions & 5 deletions docs/grammar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@

# The Gutenberg block grammar

<style>
Expand All @@ -7,8 +8,6 @@
dd header { font-weight: bold; }
pre { margin: 0; }
</style>
<dl><dt></dt><dd><pre><header>Block_List</header> = $(!Block .)*
(Block $((!Block .)*) )*
$(.*)</pre></dd><dt></dt><dd><pre><header>Block</header> = Block_Empty
/ Block_Balanced</pre></dd><dt></dt><dd><pre><header>Block_Empty</header> = "&lt;!--" __ "wp:" Block_Name __ (Block_Attributes __ )? "/-->"</pre></dd><dt></dt><dd><pre><header>Block_Balanced</header> = Block_Start (Block / $(!Block_End .))* Block_End</pre></dd><dt></dt><dd><pre><header>Block_Start</header> = "&lt;!--" __ "wp:" Block_Name __ (Block_Attributes __ )? "-->"</pre></dd><dt></dt><dd><pre><header>Block_End</header> = "&lt;!--" __ "/wp:" Block_Name __ "-->"</pre></dd><dt></dt><dd><pre><header>Block_Name</header> = Namespaced_Block_Name
/ Core_Block_Name</pre></dd><dt></dt><dd><pre><header>Namespaced_Block_Name</header> = $( Block_Name_Part "/" Block_Name_Part )</pre></dd><dt></dt><dd><pre><header>Core_Block_Name</header> = $( Block_Name_Part )</pre></dd><dt></dt><dd><pre><header>Block_Name_Part</header> = $( [a-z][a-z0-9_-]* )</pre></dd><dt>JSON-encoded attributes embedded in a block's opening comment</dt><dd><pre><header>Block_Attributes</header> = $("{" (!("}" __ """/"? "-->") .)* "}")</pre></dd><dt></dt><dd><pre><header>__</header> = [ \t\r\n]+</pre></dd></dl>
<dl><dt></dt><dd><pre><header>Block_List</header> = $(!Block .)* (Block $(!Block .)*)* $(.*)</pre></dd><dt></dt><dd><pre><header>Block</header> = Block_Void
/ Block_Balanced</pre></dd><dt></dt><dd><pre><header>Block_Void</header> = "&lt;!--" __ "wp:" Block_Name __ (Block_Attributes __)? "/-->"</pre></dd><dt></dt><dd><pre><header>Block_Balanced</header> = Block_Start (Block / $(!Block_End .))* Block_End</pre></dd><dt></dt><dd><pre><header>Block_Start</header> = "&lt;!--" __ "wp:" Block_Name __ (Block_Attributes __)? "-->"</pre></dd><dt></dt><dd><pre><header>Block_End</header> = "&lt;!--" __ "/wp:" Block_Name __ "-->"</pre></dd><dt></dt><dd><pre><header>Block_Name</header> = Namespaced_Block_Name
/ Core_Block_Name</pre></dd><dt></dt><dd><pre><header>Namespaced_Block_Name</header> = $(Block_Name_Part "/" Block_Name_Part)</pre></dd><dt></dt><dd><pre><header>Core_Block_Name</header> = $(Block_Name_Part)</pre></dd><dt></dt><dd><pre><header>Block_Name_Part</header> = $([a-z] [a-z0-9_-]*)</pre></dd><dt>JSON-encoded attributes embedded in a block's opening comment</dt><dd><pre><header>Block_Attributes</header> = $("{" (!("}" __ "" "/"? "-->") .)* "}")</pre></dd><dt></dt><dd><pre><header>__</header> = [ \t\r\n]+</pre></dd></dl>