1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166 | package Torello.Browser.JsonAST;
import static Torello.Java.C.*;
import Torello.Java.Additional.Ret2;
import Torello.Java.EXCC;
import Torello.Java.FileRW;
import Torello.Java.StrPrint;
import Torello.Java.StorageWriter;
import java.io.IOException;
import java.io.File;
/**
* <B>AST Build Driver</B>.
*
* <BR /><BR />This top-level builder orchestrates the end-to-end pipeline for transforming the
* Chrome DevTools Protocol (CDP) schema JSON files into the Java-HTML abstract syntax tree (AST)
* representation and derived outputs.
*
* <BR /><BR />The build process follows a <I>compiler-style</I> sequence of phases:
*
* <BR /><BR /><UL CLASS=JDUL>
* <LI> <B>Constructors:</B> Parse raw JSON into untyped AST node tuples with no side effects.</LI>
*
* <LI> <B>LinkTypes:</B> Wire parents, resolve <CODE>ref4</CODE> references, and set cross-links.
* </LI>
*
* <LI> <B>SimplifyTypes:</B> Normalize and simplify types (collapse aliases, lift unions, etc.).
* </LI>
*
* <LI> <B>ToHTML:</B> Emit human-readable documentation pages for both
* <CODE>browser_protocol.json</CODE> and <CODE>js_protocol.json</CODE>.
* </LI>
*
* <LI><B>ToString:</B> Provide summaries suitable for debugging, logs, and diffs.</LI>
* </UL>
*
* <BR />All semantic violations are reported via {@link javax.json.JsonException} with contextual
* notes. This avoids unchecked {@link ClassCastException} and ensures validation through explicit
* {@link javax.json.JsonValue.ValueType} gates.
*
* <BR /><BR />This class is intended for use by build tools and advanced users who need to
* regenerate the API documentation or validate schema changes. It is not part of the runtime API.
*/
@Torello.JavaDoc.Annotations.StaticFunctional
@Torello.JavaDoc.Annotations.JDHeaderBackgroundImg(EmbedTagFileID="SERIALIZER_JDHBI")
public class AST_BUILD
{
private AST_BUILD() { }
private static final String FS = File.separator;
/**
* Command line variant of the generate method which uses the Java-HTML Default File &
* Directory Names.
*/
public static void main(String[] args) throws IOException
{
generate(
"Torello" + FS + "Browser" + FS + "doc-files" + FS + "protocol_as_html" + FS,
"Torello" + FS + "Browser" + FS + "JsonAST" + FS + "data-files" + FS,
"Torello" + FS + "Browser" + FS + "doc-files" + FS + "protocol_as_json" + FS
);
}
/**
* Executes the full JSONāAST build pipeline for the Chrome DevTools Protocol schema.
*
* <BR /><BR />This method reads the canonical CDP specification files
* (<CODE>browser_protocol.json</CODE> and <CODE>js_protocol.json</CODE>) from the given
* <CODE>dataFileDir</CODE>, parses them into {@link API} instances, runs the linker and
* simplification phases, and finally writes the generated HTML documentation into the provided
* <CODE>htmlFileOutputDir</CODE>.
*
* @param htmlFileOutputDir Directory where the generated HTML protocol documentation
* will be written.
*
* @param dataFileOutputDir Target location for writing two '.dat' files
*
* @param jsonFileSourceDir Directory containing the JSON schema input files:
* <B><CODE><A HREF='../doc-files/protocol_as_json/browser_protocol.json'>
* browser_protocol.json</A></CODE></B> and
* <B><CODE><A HREF='../doc-files/protocol_as_json/js_protocol.json'>
* js_protocol.json</A></CODE></B>.
*
* @throws IOException if the schema files cannot be read or the HTML output cannot be written.
*/
public static void generate(
final String htmlFileOutputDir,
final String dataFileOutputDir,
final String jsonFileSourceDir
)
throws IOException
{
final StorageWriter sw = new StorageWriter();
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
printPhaseToTerminal(sw, "Parsign Raw JSON Files ");
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
final String browserAPI_Filename = jsonFileSourceDir + "browser_protocol.json";
final String jsAPI_Filename = jsonFileSourceDir + "js_protocol.json";
final API browser = new API(sw, browserAPI_Filename, "BrowserAPI");
final API js = new API(sw, jsAPI_Filename, "JavaScriptAPI");
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
printPhaseToTerminal(sw, "Running the Linker");
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
Linker.run(sw, browser, js);
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
printPhaseToTerminal(sw, "Writing Data Files");
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
//
// return new Ret2<>(browserData, jsData);
// Don't confuse which one is which. Save these to explicitly named variables
final Ret2<InfoData, InfoData> extraData = ExtraData.run(sw, browser, js);
final InfoData browserData = extraData.a;
final InfoData jsData = extraData.b;
// Container Data-Class "SERIALIZED_AST" just keeps these four types together
final String fName = dataFileOutputDir + SERIALIZED_AST.FILE_NAME_JAR;
final SERIALIZED_AST dat = new SERIALIZED_AST(browser, js, browserData, jsData);
try
{
sw.println("Writing File: " + BYELLOW + fName + RESET);
FileRW.writeObjectToFileNOCNFE(dat, fName, true);
}
catch (IOException ioe)
{
sw.println(EXCC.toString(ioe) + "\nExiting...");
System.exit(0);
}
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
printPhaseToTerminal(sw, "Writing HTML Files");
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
WriteBothHTMLFiles.write(htmlFileOutputDir, browser, js);
sw.println();
}
static void printPhaseToTerminal(final StorageWriter sw, final String phaseName)
{
sw.println(
"\n\n" +
BBLUE +
"*****************************************************************************\n" +
RESET +
" " + BRED_BKGND + ' ' + phaseName + ' ' + RESET + "\n" +
BBLUE +
"*****************************************************************************\n" +
RESET
);
}
}
|