This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/daffodil-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 33e7a61 Publishing from 89a90dcf09985a93188ae4c838f44887610ad024
33e7a61 is described below
commit 33e7a61acac0f864ea7698f689896dacbee7a1e6
Author: Apache Daffodil Site Autobuild <[email protected]>
AuthorDate: Tue Apr 25 17:43:40 2023 +0000
Publishing from 89a90dcf09985a93188ae4c838f44887610ad024
---
...dil-Extension-for-Visual-Studio-Code-1.3.0.docx | Bin 0 -> 41022519 bytes
...dil-Extension-for-Visual-Studio-Code-1.3.0.html | 746 +++++++++++++++++++++
2 files changed, 746 insertions(+)
diff --git
a/content/docs/vscode/1.3.0/Apache-Daffodil-Extension-for-Visual-Studio-Code-1.3.0.docx
b/content/docs/vscode/1.3.0/Apache-Daffodil-Extension-for-Visual-Studio-Code-1.3.0.docx
new file mode 100644
index 0000000..87ad866
Binary files /dev/null and
b/content/docs/vscode/1.3.0/Apache-Daffodil-Extension-for-Visual-Studio-Code-1.3.0.docx
differ
diff --git
a/content/docs/vscode/1.3.0/Apache-Daffodil-Extension-for-Visual-Studio-Code-1.3.0.html
b/content/docs/vscode/1.3.0/Apache-Daffodil-Extension-for-Visual-Studio-Code-1.3.0.html
new file mode 100644
index 0000000..92f004d
--- /dev/null
+++
b/content/docs/vscode/1.3.0/Apache-Daffodil-Extension-for-Visual-Studio-Code-1.3.0.html
@@ -0,0 +1,746 @@
+<p><img src="images/asf-daffodil-logo.svg" /></p>
+<h1 id="apache-daffodil-extension-for-visual-studio-code-development">Apache
Daffodil™ Extension for Visual Studio Code: Development</h1>
+<h2 id="build-status">Build Status</h2>
+<p><a
href="https://github.com/apache/daffodil-vscode/actions/workflows/CI.yml";><img
src="https://github.com/apache/daffodil-vscode/actions/workflows/CI.yml/badge.svg";
alt="CI" /></a> <a
href="https://github.com/apache/daffodil-vscode/actions/workflows/nightly.yml";><img
src="https://github.com/apache/daffodil-vscode/actions/workflows/nightly.yml/badge.svg";
alt="nightly tests" /></a></p>
+<h2 id="prerequisites">Prerequisites</h2>
+<h2 id="requirements">Requirements</h2>
+<p>For <em>development</em>, there are some additional prerequisites that are
required for building the Apache Daffodil™ Extension for Visual Studio Code:</p>
+<ul>
+<li><a href="https://www.scala-sbt.org/1.x/docs/Setup.html";>Install SBT 0.13.8
or higher</a></li>
+<li><a href="https://nodejs.org/en/download/";>Install Node 10 or
higher</a></li>
+<li><a href="https://yarnpkg.com/getting-started/install";>Install Yarn</a></li>
+<li><a href="https://pandoc.org/installing.html";>Install pandoc</a></li>
+</ul>
+<h2 id="suggestions">Suggestions</h2>
+<ol type="1">
+<li>To automatically recompile code when it changes, run:</li>
+</ol>
+<pre class="shell"><code>yarn watch</code></pre>
+<p>As <code>watch</code> runs, fix any problems that arise in the
<code>Problems tab</code>.</p>
+<ol start="2" type="1">
+<li>Run the Apache Daffodil™ Extension for Visual Studio Code in debug
mode.</li>
+</ol>
+<figure>
+<img
src="https://user-images.githubusercontent.com/98881959/152995881-982a321a-6926-460f-aa37-e4c3a5fa7dff.gif";
alt="StartDebugMode" /><figcaption
aria-hidden="true">StartDebugMode</figcaption>
+</figure>
+<h2
id="build-the-apache-daffodil-extension-for-visual-studio-code-and-run-it-as-a-developer">Build
the Apache Daffodil™ Extension for Visual Studio Code and Run It as a
Developer</h2>
+<ul>
+<li>Clone the project <a
href="https://github.com/apache/daffodil-vscode.git";>https://github.com/apache/daffodil-vscode.git</a></li>
+<li>Open the project folder in VS Code.</li>
+<li>Run <code>yarn</code> to update the local dependencies.</li>
+<li>Press <code>F5</code> (or launch “Extension” under the “Run and Debug”
pane) to build and launch the extension in another VS Code window.</li>
+<li>In that newly loaded window, named “sampleWorkspace”, you can then debug
schema files using the local version of the extension.</li>
+</ul>
+<p>The local Apache Daffodil™ Extension for Visual Studio Code downloads and
caches the Apache Daffodil™ Debugger corresponding to the latest extension
release. If you want to test a <em>local</em> version of the Apache Daffodil
Debugger, you need to: * add <code>"useExistingServer": true</code> to the
configuration in your <code>launch.json</code> in the sample workspace; *
launch the backend debugger locally, using a launch configuration like below:
<code>json { "type": "scal [...]
+<h2 id="running-the-automated-test-suite">Running the Automated Test Suite</h2>
+<p>The Apache Daffodil VS Code Extension comes with an automated test suite.
Run it as follows:</p>
+<pre class="shell"><code>yarn test</code></pre>
+<h3 id="testing-against-a-specific-version-of-vs-code">Testing Against a
Specific Version of VS Code</h3>
+<p>By default, the test suite will use the earliest supported release of VS
Code. To test against any <em>specific</em> version of VS Code (in this
example, VS Code version 1.74.3), execute the test suite as follows, setting
<code>DAFFODIL_TEST_VSCODE_VERSION</code> to the desired version:</p>
+<pre class="shell"><code>DAFFODIL_TEST_VSCODE_VERSION=1.74.3 yarn
test</code></pre>
+<p>Set <code>DAFFODIL_TEST_VSCODE_VERSION</code> to <code>stable</code> to use
the latest stable release, or to <code>insiders</code> to use the latest
(nightly) insiders build.</p>
+<h3 id="tls-certificate-issues">TLS Certificate Issues</h3>
+<p>HTTPS TLS certificates are verified by default. When running the test suite
in certain environments (e.g., company VPN that uses endpoint protection), TLS
certificate verifications may fail with a self-signed certificate error. If
this is the case, either have node trust the endpoint protection certificate,
or use one of these workarounds to disable the certificate verification:</p>
+<pre class="shell"><code>NODE_TLS_REJECT_UNAUTHORIZED=0 yarn test</code></pre>
+<p>or</p>
+<pre class="shell"><code>node ./out/tests/runTest.js
--disable_cert_verification</code></pre>
+<p><strong>WARNING:</strong> Do not <code>export
NODE_TLS_REJECT_UNAUTHORIZED=0</code> into your environment as it will disable
TLS certificate verification on <em>all</em> node HTTPS connections done in
that shell session.</p>
+<h2 id="building-the-documentation">Building the Documentation</h2>
+<p>To build <code>docx</code> (Word formatted) documentation, from the top of
the cloned repository, run:</p>
+<pre class="shell"><code>cd docs && make all</code></pre>
+<h2 id="reviewing-and-verifying-dependency-bot-updates">Reviewing and
Verifying Dependency Bot Updates</h2>
+<p>For GitHub CI action updates (pull requests that start with <strong>Bump
actions/…</strong>), make sure the affected workflows still operate as expected
(they are automatically CI tested). GitHub CI actions update workflow YAML
files, and are part of the CI infrastructure and not a code dependency. These
should be relatively quick and easy to assess compared to code dependencies.</p>
+<p>If the updates are not GitHub CI action updates, then additional scrutiny
is required. When reviewing and verifying dependency bot updates that are part
the software supply chain being distributed, please use the following
checklist:</p>
+<ul class="task-list">
+<li><input type="checkbox" disabled="" />
+<strong>Do all automated continuous integration checks pass?</strong></li>
+<li><input type="checkbox" disabled="" />
+<strong>Is the update a patch, minor, or major update?</strong></li>
+<li><input type="checkbox" disabled="" />
+<strong>Is the license still compatible with ASF License Policy?</strong></li>
+<li><input type="checkbox" disabled="" />
+<strong>Have any changes been made to LICENSE/NOTICE files that need to be
incorporated?</strong></li>
+<li><input type="checkbox" disabled="" />
+<strong>Have any transitive dependencies been added or changed?</strong></li>
+</ul>
+<hr />
+<p><img src="images/asf-daffodil-logo.svg" /></p>
+<h1 id="apache-daffodil-extension-for-visual-studio-code-roadmap">Apache
Daffodil™ Extension for Visual Studio Code: Roadmap</h1>
+<p>Now that the Apache Daffodil™ Extension for Visual Studio Code version
1.0.0 has been released and published on the <a
href="https://marketplace.visualstudio.com/vscode";>Microsoft® VS Code
Marketplace</a>, it is time to consider features and improvements for the next
major releases.</p>
+<hr />
+<h2
id="important-ideas-on-the-future-of-the-apache-daffodil-extension-for-visual-studio-code">Important
Ideas on the Future of the Apache Daffodil™ Extension for Visual Studio
Code</h2>
+<p>While version 1.0.0 of the Apache Daffodil™ Extension for Visual Studio
Code focused on the schema and the infoset, the theme of the next version will
place additional emphasis on the input data. The input data could be any kind
of file, with different byte sizes, byte ordering, and alignments, so having
robust hex editing capabilities is important.</p>
+<p>It is also important to have the ability to set breakpoints not only in the
schema, but also <em>in the data</em>, and allow for manipulating the data and
watch it affect the parse outcome. In other words, what happens to the parse
when the data changes in some way. While stepping through the debugger, the
schema, the infoset, and the data views need to be kept in sync.</p>
+<hr />
+<h2 id="desired-features-of-the-input-data-editor">Desired Features of the
Input Data Editor</h2>
+<p>For organizational purposes, the desired features for the Apache Daffodil™
Extension for Visual Studio Code are broken down into eight functional
areas.</p>
+<h3 id="file-type-support-fts">1. File Type Support (FTS)</h3>
+<p><strong>1.1 The data editor needs to support any fixed length
(non-streaming) file Daffodil is capable of opening.</strong> Generally, any
file type can be opened and displayed by a hex editor. The file type and
extension do not influence the rendering of the file in hex or binary
formats.</p>
+<h3 id="user-interface-ui">2. User Interface (UI)</h3>
+<p><strong>2.1 The data editor needs to be responsive and provide a good VS
Code User Experience.</strong> Existing third-party VS Code hex editors will
decrease in responsiveness while rendering medium to large size files. The
editor will handle file sizes common to Daffodil without impacting overall
usability.</p>
+<p><strong>2.2 The data editor needs to be designed as a composition of
display panels that allow for multiple data representations to be rendered on
the same screen.</strong> A data file may be segmented into multiple
representations of data, from differing on byte boundaries to endianness. The
editor will render differing representations within the same user interface.</p>
+<p><strong>2.3 The data editor needs to allow individual display panels to
maintain their own position in the data to allow viewing different segments of
data in different display panels.</strong> The editor will manage each
composable view as a separate Viewport capable of displaying a view into the
data at a specified offset and capacity.</p>
+<p><strong>2.4 The data editor viewports need to be interactive to allow mouse
and keyboard interactions such as scrolling and context menus.</strong> User
interaction will drive the function of the editor as such the ability to
interpret keyboard and mouse actions on individual and block data selections
are critical.</p>
+<p><strong>2.5 The data editor needs to include a Properties View
component.</strong> The property view will provide a static region on the
display to place file and selection metadata. The property view is not
associated to a specific region in the file, so it is not a viewport component.
It is tied to events such as selection events and is updated based on
notification of events occurring.</p>
+<p><strong>2.6 The data editor needs to include a property display mode for a
single unit selection.</strong> The Properties View will allow multiple
representations for a single unit, eg byte, to be displayed simultaneously.</p>
+<p><strong>2.7 The data editor needs to include a property display mode for
multiple unit selection.</strong> Selecting up to some limit of bytes, for
example four, could still be rendered in the Properties View. For example,
selecting four bytes could render a 32-bit integer value.</p>
+<h3 id="persisting-edits-per">3. Persisting Edits (PER)</h3>
+<p><strong>3.1 The data editor needs to allow edits to be saved as a new
file.</strong> The editor will not attempt to write the file that is held open
by Daffodil. Instead, a copy of the file will be written to disk.</p>
+<p><strong>3.2 The data editor needs to provide an auto-incremented file
revision number to save without prompting the user.</strong> When saving edits
to a file it may be preferrable for the save-as-new-file to be transparent to
the user. In this case the user will not be prompted for a file name but
instead use an autogenerated name.</p>
+<p><strong>3.3 The data editor needs to provide a save-as option to name a new
file.</strong> When saving edits to a file the user may want to specify where
the edited file will be saved. In this case a file picker dialog or something
similar can be used to allow the user to specify the location for the save
file.</p>
+<p><strong>3.4 The data editor will provide a convenient way of restarting the
Daffodil debugger with the specified edits.</strong> After saving the edits to
a file the debugger can be restarted and automatically set to use the new files
path as the input. This convenience allows the user to avoid editing their
launch profile to point to the new file.</p>
+<h3 id="data-representations-datarep">4. Data Representations (DATAREP)</h3>
+<p>Hex and binary representations for both viewing and editing.</p>
+<p><strong>4.1 The data editor needs to implement support for multiple data
representations.</strong> The editor will use the viewport component design to
deliver a composable multiple representation rendering capability.</p>
+<p><strong>4.2 The data editor needs to provide a viewport for viewing byte
delimited data.</strong> The viewport will display hex bytes similar to the
common hex editor displayed.</p>
+<p><strong>4.3 The data editor needs to provide a viewport for viewing data as
individual bits.</strong> The viewport will render binary 1-0 display. The
details of the rendering such as unit length can be modified using properties
associated with the viewport.</p>
+<p><strong>4.4 The data editor needs to provide configurable rendering
properties for any given representation.</strong> The UI will allow the user to
view and edit viewport properties</p>
+<p><strong>4.5 The data editor needs to provide configurable endianness
properties for viewport rendering.</strong> Configuring big or little endian
for a viewport.</p>
+<h3 id="editing-edt">5. Editing (EDT)</h3>
+<p><strong>5.1 The data editor needs to implement inline editing within a
viewport.</strong> The viewport will support mouse and keyboard interaction to
initiate editing a value.</p>
+<p><strong>5.2 The data editor needs to default to editing in the same
representation as the view.</strong> The editor will allow editing using the
same viewport rendering as the representation, e.g., hex from hex, binary from
binary can be represented using the native rendering logic of the viewport.</p>
+<p><strong>5.3 The data editor needs to provide undo / redo capability related
to edits.</strong> A common expectation of editors such as this would be to
provide commands to undo and redo edits that have been made.</p>
+<p><strong>5.4 The data editor needs to provide editing in differing
representations as the view.</strong> The editor could provide something
similar to a pop-out component that allows editing a value in a format that
differs from the viewport representation, e.g., editing binary from the hex
view.</p>
+<h3 id="debugger-integration-dbg">6. Debugger integration (DBG)</h3>
+<p><strong>6.1 The debugger needs to provide extension points which allow
executing debug commands from the editor.</strong> There are certain
non-standard operations such as setting breakpoints on data locations that are
to be supported. This will require the debugger to provide extension points
that allow the editor to pass instructions that augment the debugger flow.</p>
+<p><strong>6.2 The debugger will support breakpoints to be set at data
positions in the input file.</strong> Setting breakpoints on data locations
indicates to the debugger that when the input stream reaches a specified point
in the file it will break execution as if it hit a code breakpoint.</p>
+<p><strong>6.3 The data editor will allow breakpoints to be set at data
positions in the input file.</strong> The data editor will allow creation of
and then render data breakpoints in a similar way to how code breakpoints are
set and rendered.</p>
+<p><strong>6.4 The data editor will support starting debug from a specified
position.</strong> The editor provides a function via a context menu that
indicates a starting point in the file for the input stream. This will drop all
bytes prior to this location when starting the debug.</p>
+<p><strong>6.5 The data editor will support stopping debug at a specified
position.</strong> The editor provides a function via a context menu that
indicates the stopping point in the input stream. All data after this point
will be ignored by the input stream, ending the debug at the specified
point.</p>
+<p><strong>6.6 The debugger will support the latest version of Apache
Daffodil™ released.</strong> The extension will be kept up to date with the
latest version of Apache Daffodil™.</p>
+<h3 id="editing-commands-cmd">7. Editing Commands (CMD)</h3>
+<p>In this section a “block” is defined as a range that has been selected by
the user.</p>
+<p><strong>7.1 The data editor needs to support adding individual
bytes.</strong> The editor will provide a function to insert a single byte at a
position in the file.</p>
+<p><strong>7.2 The data editor needs to support adding blocks of
bytes.</strong> The editor will provide a function to insert multiple bytes
starting at a position in the file.</p>
+<p><strong>7.3 The data editor needs to support deleting individual
bytes.</strong> The editor will provide a function to delete a single byte from
the file.</p>
+<p><strong>7.4 The data editor needs to support deleting blocks of
bytes.</strong> The editor will provide a function to delete blocks of bytes
from the file.</p>
+<p><strong>7.5 The data editor needs to support modifying the value of an
individual byte.</strong> The editor will provide a function to overwrite the
value of a byte in the file.</p>
+<p><strong>7.6 The data editor needs to support modifying the value of a block
of bytes.</strong> The editor will provide a function to overwrite the value of
a block of bytes in the file.</p>
+<p><strong>7.7 The data editor needs to support copying byte(s).</strong> The
editor will provide the ability to select and copy a range of bytes to the
clipboard for convenience and interoperability. The size of bytes that can be
copied will need an upper limit depending on the file size and system memory
availability.</p>
+<p><strong>7.8 The data editor needs to support pasting byte(s).</strong> The
editor will provide the ability to past bytes from the system clipboard into
the file at a specified position for convenience and interoperability.</p>
+<p><strong>7.9 The data editor needs to support searching for
patterns</strong>. The editor will provide a search function similar to a text
editor find text using literal text. This pattern would literally be searched
for in each given representation.</p>
+<p><strong>7.10 The data editor needs to support replacing search results with
new patterns.</strong> The editor will provide a search function similar to a
text editor find text using literal text and replace the found text with
alternate text. This pattern would literally be searched for in each given
representation and replaced using text that is valid within said
representation.</p>
+<p><strong>7.11 The data editor needs to use the native clipboard provided by
the operating system for interoperability with other applications.</strong> The
editor will use the operating system clipboard for copy and paste operations to
improve interoperability with other applications.</p>
+<p><strong>7.12 The data editor needs to support applying a bit mask to an
individual byte.</strong> The editor will provide function to apply a mask to a
byte at a position in the file.</p>
+<p><strong>7.13 The data editor needs to support applying a bit mask to a
block of bytes.</strong> The editor will provide a function to apply a mask to
a selection of bytes in the file.</p>
+<h3 id="test-data-markup-language-integration-tdml">8. Test Data Markup
Language integration (TDML)</h3>
+<p><strong>8.1 All external files needed by the TDML file will be incorporated
as relative paths into the TDML file.</strong></p>
+<p><strong>8.2 TDML features need to be as modular as possible.</strong>
Modularization allows for the future removal of TDML from the repository of the
DFDL extension and addition to a library that can be shared by the DFDL
repository.</p>
+<p><strong>8.3 TDML features need to be written in Scala and will read/write
XML by using XML bindings (e.g., Jaxb/scalaxb).</strong></p>
+<p><strong>8.4 The extension needs to provide an item in the command palette
(ctrl + shift + p) for ‘Generate TDML File’.</strong></p>
+<p>Selecting this command will display menus allowing the user to select the
following:</p>
+<ul>
+<li>TDML File Name</li>
+<li>Name for the test case</li>
+<li>Description for the test case</li>
+<li>DFDL Schema</li>
+<li>Data Document</li>
+</ul>
+<p>This selection will work in the same way as the DFDL debugger. If the user
selects the command from a DFDL Schema, it will automatically use that in place
of a selection.</p>
+<ul>
+<li>The TDML File will be created in the workspace directory.</li>
+<li>The DFDL Schema and Document files will be file names only.</li>
+<li>These file names will be relative to the workspace directory. It will be
the responsibility of the user to organize everything when creating a TDML file
and to package the files up for distribution.</li>
+<li>The name of the TDML file will be the name of the DFDL schema used with
‘.tdml’ appended to the end.</li>
+</ul>
+<p><strong>8.5 The extension needs to provide an item in the command palette
(ctrl + shift + p) for ‘Add Test Case to TDML File’.</strong></p>
+<p>Selecting this command will display menus allowing the user to select the
following:</p>
+<ul>
+<li>TDML File Name</li>
+<li>Name for the test case</li>
+<li>Description for the test case</li>
+<li>DFDL Schema</li>
+<li>Data Document</li>
+</ul>
+<p>This selection will work in the same way as the DFDL debugger. If the user
selects the command from a DFDL Schema, it will automatically use that in place
of a selection.</p>
+<p><strong>8.6 The extension needs to provide an item in the command palette
(ctrl + shift + p) for ‘Run Test Case in TDML File’.</strong></p>
+<p>Selecting this command will display menus allowing the user to select the
following:</p>
+<ul>
+<li>TDML File Name</li>
+<li>Test Case to run (this list will be populated with data in the selected
TDML File)</li>
+</ul>
+<p>This command will start the Daffodil process in run mode. This command will
provide an option to start the Daffodil process in debug mode. The location of
the DFDL Schema is expected to be relative to the location of the TDML File. It
will be the responsibility of the user who created the TDML file to ensure that
packaging of their TDML file is correct.</p>
+<h3 id="intellisense-auto-completion-int">IntelliSense Auto Completion
(INT)</h3>
+<p><strong>9.1 The extension needs to provide context sensitive auto
completion suggestion (IntelliSense) based on the DFDL language.</strong></p>
+<p><strong>9.2 The IntelliSense suggestions for attributes needs to supply an
appropriate list of choices where applicable.</strong></p>
+<p><strong>9.3 The IntelliSense for element tags needs to supply attribute
appropriate for that specific tag.</strong></p>
+<p><strong>9.4 The IntelliSense for element tags needs to supply attribute
suggestions for newly insert tags as well as editing existing tags.</strong></p>
+<p><strong>9.5 The IntelliSense needs to supply suggestions based on the
contextual cursor position.</strong></p>
+<p><strong>9.6 The IntelliSense suggestions need to work when multiple tags
are on a single line as well as when each tag is on a single line.</strong></p>
+<p><strong>9.7 IntelliSense needs to supply a closing tag when a closing tag
is missing.</strong></p>
+<h3 id="dfdl-schema-syntax-colorization-syn">DFDL Schema Syntax Colorization
(SYN)</h3>
+<p><strong>10.1 Provide DFDL syntax colorization.</strong></p>
+<p><strong>10.2 Matching tags within the dfdl schema need to be
highlighted.</strong></p>
+<hr />
+<h2 id="release-plan-proposed">Release Plan (Proposed)</h2>
+<p>The goal is to have these Apache Daffodil VS Code Extension capabilities
released, and published to the Marketplace, optimistically by 2Q2023.</p>
+<p>The following table will be updated as new releases are published, or the
themes/emphasis of a release change.</p>
+<p>However, this is all highly subject to change based on the needs of the
user community, and on what community developers choose to work.</p>
+<p>The release numbering is also subject to change.</p>
+<table>
+<colgroup>
+<col style="width: 14%" />
+<col style="width: 51%" />
+<col style="width: 22%" />
+<col style="width: 12%" />
+</colgroup>
+<thead>
+<tr class="header">
+<th style="text-align: left;">Release</th>
+<th style="text-align: left;">Published to Marketplace?</th>
+<th style="text-align: left;">Description</th>
+<th style="text-align: left;">Issues</th>
+</tr>
+</thead>
+<tbody>
+<tr class="odd">
+<td style="text-align: left;">1.1.0 <br /> Target: July, 2022</td>
+<td style="text-align: left;">✅ Yes</td>
+<td style="text-align: left;">UI wireframes showing a vision of the data
editor has been posted for discussion and feedback. The main editing viewport
now has support for the delete and insert editing primitives in addition to
overwrite. Support for multiple viewports, being able to undo and redo changes,
cut and paste, and file saving are implemented.</td>
+<td style="text-align: left;"><a
href="https://github.com/apache/daffodil-vscode/issues?q=+is%3Aissue+milestone%3A1.1.0+";>Issues</a></td>
+</tr>
+<tr class="even">
+<td style="text-align: left;">1.2.0 <br /> Target: December, 2022</td>
+<td style="text-align: left;">✅ Yes</td>
+<td style="text-align: left;">Search and replace is implemented. Full-stack
testing is in place.</td>
+<td style="text-align: left;"><a
href="https://github.com/apache/daffodil-vscode/issues?q=+is%3Aissue+milestone%3A1.2.0+";>Issues</a></td>
+</tr>
+<tr class="odd">
+<td style="text-align: left;">1.3.0 <br /> Target: April, 2023</td>
+<td style="text-align: left;">❌ Not yet</td>
+<td style="text-align: left;">Improvements to DFDL auto-completion (aka,
“Intellisense”). Basic support for TDML. Editing is permitted in any of several
viewports. Each viewport can display data in different formats (e.g, binary,
hex, ascii, big and little endian integers).</td>
+<td style="text-align: left;"><a
href="https://github.com/apache/daffodil-vscode/issues?q=+is%3Aissue+milestone%3A1.3.0+";>Issues</a></td>
+</tr>
+<tr class="even">
+<td style="text-align: left;">1.3.1 <br /> Target: June, 2023</td>
+<td style="text-align: left;">❌ Not yet</td>
+<td style="text-align: left;">Large file support, mode simplification,
incremental search and replace.</td>
+<td style="text-align: left;">-</td>
+</tr>
+<tr class="odd">
+<td style="text-align: left;">1.4.0 <br /> Target: September, 2023</td>
+<td style="text-align: left;">❌ Not yet</td>
+<td style="text-align: left;">Breakpoints can be set at data offsets and
debugging can start and stop at specified offsets. Test coverage, dependencies,
user testing, packaging, documentation updates, CI release process, 2.0.0
release candidates, voting, approval, release, publication, and
advertising.</td>
+<td style="text-align: left;">-</td>
+</tr>
+</tbody>
+</table>
+<h2 id="beyond-2.0.0">Beyond 2.0.0:</h2>
+<p>Support for:</p>
+<ul>
+<li>A <code>Properties View</code> component.</li>
+<li>Automated checkpoints.</li>
+<li>Transformations of a byte range (with checkpoints allowing undo/redo).</li>
+<li>Additional encodings in the data editor.</li>
+</ul>
+<p>More to come…</p>
+<hr />
+<p><img src="images/asf-daffodil-logo.svg" /></p>
+<h1 id="apache-daffodil-extension-for-visual-studio-code">Apache Daffodil™
Extension for Visual Studio Code</h1>
+<p>The Apache Daffodil™ Extension for Visual Studio Code is an extension to
the Microsoft® Visual Studio Code (VS Code) editor which enables Data Format
Description Language (DFDL) syntax highlighting, code completion, and the
interactive debugging of DFDL Schema parsing operations using <a
href="https://daffodil.apache.org/";>Apache Daffodil™</a>.</p>
+<p>DFDL is a data modeling language used to describe file formats. The DFDL
language is a subset of eXtensible Markup Language (XML) Schema Definition
(XSD). Just as file formats are rich and complex, so is the modeling language
to describe them. Developing DFDL Schemas can be challenging, requiring a lot
of iterative development, and testing.</p>
+<p>The purpose of Apache Daffodil™ Extension for Visual Studio Code is to ease
the burden on DFDL Schema developers, enabling them to develop high quality,
DFDL Schemas, in less time. VS Code is free, open source, cross-platform,
well-maintained, extensible, and ubiquitous in the developer community. These
attributes align well with the Apache Daffodil™ project and the Apache
Daffodil™ Extension for Visual Studio Code.</p>
+<h2
id="bundled-tools-in-the-apache-daffodil-extension-for-visual-studio-code">Bundled
Tools in the Apache Daffodil™ Extension for Visual Studio Code</h2>
+<h3 id="dfdl-syntax-highlighting">DFDL Syntax Highlighting</h3>
+<p>DFDL is rich and complex. Developers using modern code editors expect some
degree of built-in language support for the language in which they are
developing, and DFDL should be no different. The Apache Daffodil™ Extension for
Visual Studio Code provides syntax highlighting to improve the readability and
context of the text. In addition, the syntax highlighting provides feedback to
the developer indicating the structure and code appear syntactically
correct.</p>
+<h3 id="dfdl-schema-code-completion">DFDL Schema Code Completion</h3>
+<p>The Apache Daffodil™ Extension for Visual Studio Code provides code
completion, also known as “Intellisense”, offering context-aware code segment
predictions that can dramatically speed up DFDL Schema development by reducing
keyboard input, memorization by the developer, and typos.</p>
+<h3 id="daffodil-data-parse-debugger">Daffodil Data Parse Debugger</h3>
+<p>The Apache Daffodil™ Extension for Visual Studio Code provides a Daffodil
Data Parse Debugger which enables the developer to carefully control the
execution of Apache Daffodil™ parse operations. Given a DFDL Schema and a
target data file, the developer can step through the execution of a parse line
by line, or until the parse reaches some developer-defined location, known as a
break point, in the DFDL Schema. What is particularly helpful is that the
developer can watch the parsed outp [...]
+<h3 id="data-editor">Data Editor</h3>
+<p>The Apache Daffodil™ Extension for Visual Studio Code provides an
integrated data editor as a new <em>experimental</em> feature that is currently
under development. It is akin to a hex editor, but tuned specifically for
challenging Daffodil use cases. It is designed to support virtually any sized
file, well beyond the limits of the standard text editor in VS Code, and it can
handle non-text data just as well as text data. It has support for setting
Daffodil debugger breakpoints on off [...]
+<h1 id="prerequisites-1">Prerequisites</h1>
+<p>This guide assumes VS Code and a Java Runtime Environment (Java 8 or
greater) are installed.</p>
+<ul>
+<li><a href="https://code.visualstudio.com/download";>Install VS Code</a></li>
+<li><a
href="https://docs.oracle.com/goldengate/1212/gg-winux/GDRAD/java.htm#BGBFJHAB";>Install
Java Runtime 8 or greater</a></li>
+<li>On Linux, glibc 2.31 or greater is required</li>
+</ul>
+<h1
id="installing-the-apache-daffodil-extension-for-visual-studio-code">Installing
the Apache Daffodil™ Extension for Visual Studio Code</h1>
+<p>The Apache Daffodil™ Extension for Visual Studio Code can be installed
using one of two methods.</p>
+<h2
id="option-1-install-the-apache-daffodil-extension-for-visual-studio-code-from-the-visual-studio-code-extension-marketplace">Option
1: Install the Apache Daffodil™ Extension for Visual Studio Code From the
Visual Studio Code Extension Marketplace</h2>
+<p>The Apache Daffodil™ Extension for Visual Studio Code is available in the
<a href="https://marketplace.visualstudio.com/vscode";>Visual Studio Code
Extension Marketplace</a>.</p>
+<h2
id="option-2-install-the-latest-.vsix-file-from-the-apache-daffodil-extension-for-visual-studio-code-release-page">Option
2: Install the Latest .Vsix File From the Apache Daffodil™ Extension for
Visual Studio Code Release Page</h2>
+<p>The latest <code>.vsix</code> (the file extension used for VS Code
extensions) file can also be downloaded from the Apache Daffodil™ Extension for
Visual Studio Code <a
href="https://github.com/apache/daffodil-vscode/releases";>releases page</a> and
installed by either:</p>
+<ul>
+<li>Using the command-line via <code>code --install-extension
<path-to-downloaded-vsix-file></code>; or</li>
+<li>Using the “Extensions: Install from VSIX” command from within VS Code by
opening the Command Palette (Mac = Command+Shift+P, Windows/Linux =
Ctrl+Shift+P), and typing <code>vsix</code> to bring up the command and
pointing it at the downloaded <code>.vsix</code> file, as demonstrated in the
following animation.</li>
+</ul>
+<p><img
src="https://user-images.githubusercontent.com/1545372/130599778-03228007-df80-4593-8504-e1bf69943c68.gif";
/></p>
+<h1 id="dfdl-schema-authoring-using-code-completion">DFDL Schema Authoring
Using Code Completion</h1>
+<h2 id="set-the-editor-to-dfdl-mode">Set the Editor to “dfdl” mode</h2>
+<p>Since DFDL Schema files end with <code>.xsd</code> (XML Schema Definition
or XSD), the editor needs to be informed specifically that DFDL mode is desired
over the more general XML mode, the following animation demonstrates how to set
the desired mode for DFDL.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/152995118-e2da5835-027e-4ff7-90f9-baf36a7e04bb.gif";
/></p>
+<h2 id="dfdl-schema-authoring-features">DFDL Schema Authoring Features</h2>
+<p>Auto suggest is triggered using control space or typing the beginning
characters of an item, as demonstrated in the following animation.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/152995218-65d5b5b6-b610-495d-af31-69dd81be58c1.gif";
/></p>
+<p>📝 <strong>NOTE:</strong> Intellisense is <em>context aware</em>, so there
is no need to begin a block with <code><</code>, just start typing the tag
name and code completion will automatically handle it as appropriate.</p>
+<p>Typing one or more unique characters will further limit the results, as
demonstrated in the following animation.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/152995254-1de6d39e-a482-4cb5-b7f3-7444932d056f.gif";
/></p>
+<p>Code completion can be used to add the schema block, with just a couple of
keystrokes, as demonstrated in the following animation.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/152995294-7d70b7c6-186b-41e1-8a48-81ebfc3e04bc.gif";
/></p>
+<p>Code completion can make short work out of completing a DFDL Format Block,
offering context-sensitive suggestions for the format attribute values, as
demonstrated in the following animation.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/152995321-ef0b2d45-32e6-4e3a-b5aa-859aa937cc3a.gif";
/></p>
+<p>The <code>></code> or <code>/</code> characters are used to close XML
tags. Use <code>tab</code> to select an item from the drop down and to exit
double quotes, as demonstrated in the following animation.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/152995446-77a33620-7277-4d9a-8dd7-f88349299ec9.gif";
/></p>
+<p>Code completion supports creating self-defined
<code>dfdl:complextypes</code> and <code>dfdl:simpleTypes</code>, as
demonstrated in the following animation.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/152995652-e56bc55d-78ba-46f6-a26c-6d7bd4440e96.gif";
/></p>
+<p>The <code>tab</code> key can be used to complete an auto-complete item
within an XML tag. After auto-complete is triggered, typing the initial
character or characters will limit the suggestion results. Inside an XML tag a
<code>space</code> or <code>carriage return</code> will trigger a list of
context sensitive attribute suggestions, as demonstrated in the following
animation.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/152995682-466be4bb-7f3f-4dcc-84bc-09792bc26adc.gif";
/></p>
+<p>The following animation demonstrates how code completion can be used to
efficiently help create self-defined types.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/152995737-2f31e4e8-525d-4cb5-a5d7-a0413a087a54.gif";
/></p>
+<p>The following animation demonstrates how code completion can be use to
efficiently create <code>xs:choice</code>s and
<code>dfdl:discriminator</code>s.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/152995769-b6afda2b-dd77-4f7a-ad18-b3e1f28087f6.gif";
/></p>
+<p>The following animation demonstrates how code completion can help authors
use hidden references and <code>dfdl:inputValueCalc</code>.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/153010643-9d1c8361-b55d-45e4-a7a4-907ec876de76.gif";
/></p>
+<p>The following animation demonstrates how code completion can help with
creating elements using <code>dfdl:outputValueCalc</code>.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/153051326-2b9d03ce-3e3a-420a-abba-408b25a2c3d2.gif";
/></p>
+<p>The following animation demonstrates examples of code completion assisting
in the creation of more user-defined types.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/153051453-e76250e2-96f6-4f07-8e9a-0a77f9ece5fe.gif";
/></p>
+<p>XPath expressions can be code completed. The following animation
demonstrates how the Path expressions are completed when calculating
<code>dfdl:Length</code> values.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/153051544-78372145-98aa-4b56-84f4-8b3a3bca4d9f.gif";
/></p>
+<p>The following animation demonstrates how code completion can be used to
help create <code>dfdl:assert</code> blocks.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/153051732-fb948f86-3485-4606-9e92-8325f1d5052d.gif";
/></p>
+<p>The following animation demonstrates another couple of examples of
<code>dfdl:assert</code> block creation using code completion.</p>
+<p><img
src="https://user-images.githubusercontent.com/98881959/153051821-abc47704-878f-4c01-8a29-c0d3911940d0.gif";
/></p>
+<h2 id="known-issues-with-code-completion">Known Issues With Code
Completion</h2>
+<ol type="1">
+<li>The Apache Daffodil™ Extension for Visual Studio Code uses a clunky method
to auto complete curly braces within quotes. It is anticipated that this will
be better addressed in the future. The auto complete method blocks suggestions
while typing between the beginning quote, opening curly brace and the closing
curly brace, ending quote.</li>
+</ol>
+<h1
id="debugging-a-dfdl-schema-using-the-apache-daffodil-extension-for-visual-studio-codes-bundled-daffodil-data-parse-debugger">Debugging
a DFDL Schema Using the Apache Daffodil™ Extension for Visual Studio Code’s
Bundled Daffodil Data Parse Debugger</h1>
+<h2 id="debug-configuration">Debug Configuration</h2>
+<p>Debugging a DFDL Schema needs both the DFDL Schema to use and a data file
to parse. Instead of having to select the DFDL Schema and the data file each
time from a file picker, a “launch configuration” can be created, which is a
JSON description of the debugging session.</p>
+<p><img
src="https://user-images.githubusercontent.com/1545372/130598508-ed4ac8df-ec93-4f45-8ef8-d2668234aff6.gif";
/></p>
+<p>To create the launch profile:</p>
+<ol type="1">
+<li><p>Select <code>Run -> Open Configurations</code> from the VS Code
menubar. This will load a <code>launch.json</code> file into the editor. There
may be existing <code>configurations</code>, or it may be empty.</p></li>
+<li><p>Press <code>Add Configuration...</code> and select the <code>Daffodil
Debug - Launch</code> option.</p></li>
+</ol>
+<p>Once the <code>launch.json</code> file has been created it will look
something like this</p>
+<div class="sourceCode" id="cb7"><pre class="sourceCode json"><code
class="sourceCode json"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true"
tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"type"</span><span class="fu">:</span> <span
class="st">"dfdl"</span><span class="fu">,</span></span>
+<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"request"</span><span class="fu">:</span> <span
class="st">"launch"</span><span class="fu">,</span></span>
+<span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"name"</span><span class="fu">:</span> <span
class="st">"Ask for file name"</span><span class="fu">,</span></span>
+<span id="cb7-5"><a href="#cb7-5" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"program"</span><span class="fu">:</span> <span
class="st">"${command:AskForProgramName}"</span><span
class="fu">,</span></span>
+<span id="cb7-6"><a href="#cb7-6" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"stopOnEntry"</span><span class="fu">:</span> <span
class="kw">true</span><span class="fu">,</span></span>
+<span id="cb7-7"><a href="#cb7-7" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"data"</span><span class="fu">:</span> <span
class="st">"${command:AskForDataName}"</span><span
class="fu">,</span></span>
+<span id="cb7-8"><a href="#cb7-8" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"infosetOutput"</span><span class="fu">:</span> <span
class="fu">{</span></span>
+<span id="cb7-9"><a href="#cb7-9" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"type"</span><span class="fu">:</span> <span
class="st">"file"</span><span class="fu">,</span></span>
+<span id="cb7-10"><a href="#cb7-10" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"path"</span><span class="fu">:</span> <span
class="st">"${workspaceFolder}/infoset.xml"</span></span>
+<span id="cb7-11"><a href="#cb7-11" aria-hidden="true" tabindex="-1"></a>
<span class="fu">},</span></span>
+<span id="cb7-12"><a href="#cb7-12" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"debugServer"</span><span class="fu">:</span> <span
class="dv">4711</span></span>
+<span id="cb7-13"><a href="#cb7-13" aria-hidden="true" tabindex="-1"></a><span
class="fu">}</span></span></code></pre></div>
+<p>This default configuration will prompt the user to select the DFDL Schema
and data files. If desired, the “program” and “data” elements can be mapped
specifically to the user’s files to avoid being prompted each time.</p>
+<p>📝 Note: Use <code>${workspaceFolder}</code> for files in the VS Code
workspace and use absolute paths for files outside of the workspace.</p>
+<div class="sourceCode" id="cb8"><pre class="sourceCode json"><code
class="sourceCode json"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true"
tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"type"</span><span class="fu">:</span> <span
class="st">"dfdl"</span><span class="fu">,</span></span>
+<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"request"</span><span class="fu">:</span> <span
class="st">"launch"</span><span class="fu">,</span></span>
+<span id="cb8-4"><a href="#cb8-4" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"name"</span><span class="fu">:</span> <span
class="st">"DFDL parse: My Data"</span><span
class="fu">,</span></span>
+<span id="cb8-5"><a href="#cb8-5" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"program"</span><span class="fu">:</span> <span
class="st">"${workspaceFolder}/schema.dfdl.xsd"</span><span
class="fu">,</span></span>
+<span id="cb8-6"><a href="#cb8-6" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"stopOnEntry"</span><span class="fu">:</span> <span
class="kw">true</span><span class="fu">,</span></span>
+<span id="cb8-7"><a href="#cb8-7" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"data"</span><span class="fu">:</span> <span
class="st">"/path/to/my/data"</span><span class="fu">,</span></span>
+<span id="cb8-8"><a href="#cb8-8" aria-hidden="true" tabindex="-1"></a> <span
class="dt">"infosetOutput"</span><span class="fu">:</span> <span
class="fu">{</span></span>
+<span id="cb8-9"><a href="#cb8-9" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"type"</span><span class="fu">:</span> <span
class="st">"file"</span><span class="fu">,</span></span>
+<span id="cb8-10"><a href="#cb8-10" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"path"</span><span class="fu">:</span> <span
class="st">"${workspaceFolder}/infoset.xml"</span></span>
+<span id="cb8-11"><a href="#cb8-11" aria-hidden="true" tabindex="-1"></a>
<span class="fu">},</span></span>
+<span id="cb8-12"><a href="#cb8-12" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"debugServer"</span><span class="fu">:</span> <span
class="dv">4711</span></span>
+<span id="cb8-13"><a href="#cb8-13" aria-hidden="true" tabindex="-1"></a><span
class="fu">}</span></span></code></pre></div>
+<h2 id="launch-a-dfdl-parse-debugging-session">Launch a DFDL Parse Debugging
Session</h2>
+<p>Using the launch profile above a <code>DFDL parse: My Data</code> menu item
at the top of the <code>Run and Debug</code> pane (Command-Shift-D) will
display. Then press the <code>play</code> button to start the debugging
session.</p>
+<p><img
src="https://user-images.githubusercontent.com/1545372/130599643-cb4b7aba-7dda-46de-8166-762c79336d58.gif";
/></p>
+<p>In the Terminal, log output from the DFDL debugger backend service will
display. If something is not working as expected, check the output in this
Terminal window for hints.</p>
+<p>The DFDL Schema file will also be loaded in VS Code and there should be a
visible marking at the beginning where the debugger has paused upon entry to
the debugging session. Control the debugger using the available VS Code
debugger controls such as <code>setting breakpoints</code>, <code>removing
breakpoints</code>, <code>continue</code>, <code>step over</code>, <code>step
into</code>, and <code>step out</code>.</p>
+<h2 id="other-options-for-launching-a-dfdl-parse-debugging-session">Other
Options for Launching a DFDL Parse Debugging Session</h2>
+<ul>
+<li><strong>Option 1:</strong>
+<ul>
+<li>Open the DFDL Schema file to debug</li>
+<li>From inside the file open the Command Palette (Mac = Command+Shift+P,
Windows/Linux = Ctrl+Shift+P)</li>
+<li>Once the command Palette is opened start typing <code>Daffodil
Debug:</code>
+<ul>
+<li>Option 1 = <code>Daffodil Debug: Debug File</code> - This will allow for
the user to fully step through the DFDL Schema. Once fully completed, it will
produce an infoset to a file named <code>SCHEMA-infoset.xml</code> which it
then opens as well.</li>
+<li>Option 2 = <code>Daffodil Debug: Run File</code> - This will run the DFDL
Schema, producing the infoset to a file named
<code>SCHEMA-infoset.xml</code>.</li>
+</ul></li>
+</ul></li>
+<li><strong>Option 2:</strong>
+<ul>
+<li>Open the schema file to debug</li>
+<li>Click the play button in the top right, two options will be provided:
+<ul>
+<li>Option 1 = <code>Debug File</code> - This will allow for the user to fully
step through the schema (WIP). Once fully completed, it will produce a infoset
to a file named <code>SCHEMA-infoset.xml</code> which it then opens as
well.</li>
+<li>Option 2 = <code>Run File</code> - This will run the DFDL Schema,
producing the infoset to a file named <code>SCHEMA-infoset.xml</code> which it
then opens as well.</li>
+</ul></li>
+</ul></li>
+</ul>
+<h2 id="custom-dfdl-debugger-views">Custom DFDL Debugger Views</h2>
+<h3 id="infoset-tools">Infoset Tools</h3>
+<p>Find the infoset tools from the command menu (Mac = Command+Shift+P,
Windows/Linux = Ctrl+Shift+P)</p>
+<p><img
src="https://user-images.githubusercontent.com/1545372/130602144-29df81f1-b397-48be-be01-dc7eeaf1eccc.gif";
/></p>
+<h3 id="inputstream-hex-viewer">Inputstream Hex Viewer</h3>
+<p>Find the hex view from the command menu (Mac = Command+Shift+P,
Windows/Linux = Ctrl+Shift+P)</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/1545372/130602743-14b9a29e-6c1e-44d9-b1d6-80ccacaca6e3.gif";
alt="hex-view" /><figcaption aria-hidden="true">hex-view</figcaption>
+</figure>
+<h1
id="enable-experimental-features-in-the-apache-daffodil-extension-for-visual-studio-code">Enable
Experimental Features in the Apache Daffodil™ Extension for Visual Studio
Code</h1>
+<p>To enable the Apache Daffodil™ Extension for Visual Studio Code
experimental features, from the command menu start typing ‘daffodil’, then
select <code>Daffodil Debug: Enable Experimental Features</code>, then select
<code>Yes</code>.</p>
+<p><img
src="https://user-images.githubusercontent.com/2205472/203111897-241aa221-91f7-41e2-951c-6006a5e82815.gif";
/></p>
+<h2 id="data-editor-1">Data Editor</h2>
+<p>🧪 <strong>Warning:</strong> This is currently an experimental feature in
development.</p>
+<p>Ωedit is being integrated as the experimental data editor in the Apache
Daffodil™ Extension for Visual Studio Code. Once experimental features are
enabled, find the Data Editor in the command menu by typing ‘omega’, then
select <code>OmegaEdit: Data Editor</code>.</p>
+<p><img
src="https://user-images.githubusercontent.com/2205472/203114858-a256a21e-0400-414f-b2ad-9fe9bf6580e5.png";
/></p>
+<p>After selecting a file to edit, a Data Editor tab will appear.</p>
+<p><img
src="https://user-images.githubusercontent.com/2205472/203124466-f8fa1772-e915-482b-b0a2-6d621da15334.png";
/></p>
+<p>As of v1.2.0, this experimental feature is far from functional, but will be
improving over time.</p>
+<h1 id="common-errors-and-solutions">Common Errors and Solutions</h1>
+<ol type="1">
+<li>Wrong Java Development Kit (JDK). Be sure Java 11+ is running.</li>
+</ol>
+<p>On MacOS, using Homebrew:</p>
+<pre class="shell"><code># Install Java 11 from a macOS terminal
+brew install java11</code></pre>
+<p>Add change <code>JAVA_HOME</code> in the ~/.zshrc file (or equivalent):</p>
+<pre class="shell"><code># Java 11
+export JAVA_HOME=/usr/local/Cellar/openjdk@11/11.0.12</code></pre>
+<p>Be sure <code>code</code> is in the <code>PATH</code> by following the
instructions <a
href="https://code.visualstudio.com/docs/setup/mac";>here</a>.</p>
+<p>With <code>JAVA_HOME</code> set to the Java 11 install, run
<code>code</code> in the terminal.</p>
+<h1 id="reporting-problems-and-requesting-new-features">Reporting Problems and
Requesting New Features</h1>
+<p>If problems are encountered or new features are desired, create tickets <a
href="https://github.com/apache/daffodil-vscode/issues";>here</a>.</p>
+<h1 id="getting-help">Getting Help</h1>
+<p>If additional help or guidance on using Daffodil and its tooling is needed,
please engage with the community on <a
href="https://daffodil.apache.org/community/";>mailing lists</a> and/or review
the <a
href="https://lists.apache.org/[email protected]";>archives</a>.</p>
+<h1 id="additional-resources">Additional Resources</h1>
+<ul>
+<li><a href="https://github.com/apache/daffodil-vscode/wiki";>Apache Daffodil™
Extension for Visual Studio Code Wiki</a></li>
+<li><a href="https://github.com/apache/daffodil";>Apache Daffodil
Repository</a></li>
+</ul>
+<hr />
+<p><img src="images/asf-daffodil-logo.svg" /></p>
+<h1 id="apache-daffodil-extension-for-visual-studio-code-1">Apache Daffodil™
Extension for Visual Studio Code</h1>
+<p>The Apache Daffodil™ Extension for Visual Studio Code is an extension to
the Microsoft® Visual Studio Code (VS Code) editor which enables Data Format
Description Language (DFDL) syntax highlighting, code completion, and the
interactive debugging of DFDL Schema parsing operations using <a
href="https://daffodil.apache.org/";>Apache Daffodil™</a>.</p>
+<p>DFDL is a data modeling language used to describe file formats. The DFDL
language is a subset of eXtensible Markup Language (XML) Schema Definition
(XSD). Just as file formats are rich and complex, so is the modeling language
to describe them. Developing DFDL Schemas can be challenging, requiring a lot
of iterative development, and testing.</p>
+<p>The purpose of Apache Daffodil™ Extension for Visual Studio Code is to ease
the burden on DFDL Schema developers, enabling them to develop high quality,
DFDL Schemas, in less time. VS Code is free, open source, cross-platform,
well-maintained, extensible, and ubiquitous in the developer community. These
attributes align well with the Apache Daffodil™ project and the Apache
Daffodil™ Extension for Visual Studio Code.</p>
+<h2
id="bundled-tools-in-the-apache-daffodil-extension-for-visual-studio-code-1">Bundled
Tools in the Apache Daffodil™ Extension for Visual Studio Code</h2>
+<h3 id="dfdl-syntax-highlighting-1">DFDL Syntax Highlighting</h3>
+<p>DFDL is rich and complex. Developers using modern code editors expect some
degree of built-in language support for the language in which they are
developing, and DFDL should be no different. The Apache Daffodil™ Extension for
Visual Studio Code provides syntax highlighting to improve the readability and
context of the text. In addition, the syntax highlighting provides feedback to
the developer indicating the structure and code appear syntactically
correct.</p>
+<h3 id="dfdl-schema-code-completion-1">DFDL Schema Code Completion</h3>
+<p>The Apache Daffodil™ Extension for Visual Studio Code provides code
completion, also known as “Intellisense”, offering context-aware code segment
predictions that can dramatically speed up DFDL Schema development by reducing
keyboard input, memorization by the developer, and typos.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233675278-db394389-30b3-4925-aa70-3167fdcb6826.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Install the Apache Daffodil VS Code Extension from the VS Code
Marketplace.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233675615-96ff35d2-16a3-487d-9c31-4d2dc50f31cb.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Open a schema file in the editor and set the language mode located in the
bottom right corner to dfdl.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233675776-91f00665-c274-45d6-b280-534dbf6df80c.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Click the language in the bottom right of the status bar or type
Ctrl+Shift+p and enter ‘language mode’, then select dfdl from the list of
available languages.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233676375-931f82ee-3ec3-4bac-8563-f6aa09d077d2.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Press ctrl+space in the empty editor window. The XML version declaration
should appear as the only choice. Select that choice by pressing the enter
key.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233676482-7fc8bb0d-b214-4697-910a-a67143c602d8.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Press ctrl+space again and the schema choice will show. Press enter to
accept the schema choice.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233676701-aec092f3-34ed-42c9-bb4b-38f336d2f87e.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Select nul, or one of the other choices in the choice list. If you select
nul for no namespace, you will need to backspace over the null character to
remove it. If you want to type in a different namespace choice, remove null and
type in your namespace choice followed by a colon ‘:’. If you select a
namespace option here, it will be used throughout the schema as a namespace
prefix to standard XML elements. The dfdl namespace prefix will automatically
be added to dfdl elements. After s [...]
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233676809-d4ca872e-ab47-4279-b90d-080d84f19493.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>At the end of the schema tag block, you can type ‘>’ to auto-end the
schema block. Intellisense will place the end tag character on the schema open
tag block, create the schema closing tag, and position the cursor between the
tags.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233676930-901b8369-5b06-42e3-a163-b409b43371c3.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Press ctrl+space to get a list of element type choices available within the
schema tags. Select a choice and press enter.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233677182-d04a34aa-d767-4f5e-8aac-e9dac8bcafc3.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Attributes can be supplied in the sequence open tag. To get a list of
attribute choices press space at the cursor position. Intellisense will open a
menu that allows a selection of an attribute. If the attribute has
predetermined choices a list of those will appear after the attribute is
selected.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233677268-9a3cdd48-f34c-4f9c-9398-a19ae58e610f.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>The separator attribute doesn’t have a specific list of choices. The comma
was manually entered to provide a value to the field. Press tab to exit the
double quotes. The cursor will be positioned immediately after the ending
double quote.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233677348-25dd34e1-5dad-4598-ac64-be2a00ece488.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Type space again to choose another attribute, or type / to create a
self-closing tag. After typing a slash to close the tag, the cursor will be
positioned at the end of the tag. Press enter to continue on the next line.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233677447-16fdd7c2-e219-4e4f-b2f4-1d73c93f2a5b.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Press ctrtl+space to get a list of element choices.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233677530-0dcb823e-00e5-4faa-b46e-d3aecd63daf0.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>A tag can also be closed by typing ‘>’ at the cursor position after the
tag.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233677621-7165170c-b519-4c5d-a863-4c46311a9b14.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Closing a tag with a ‘>’ will normally result in a closing tag on a new
line and the cursor positioned between the two tags. (If an open tag is split
over multiple lines, the closing tag is not moved to the next line. This
behavior can be changed based on community input).</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233677700-6a991a1c-cdcc-4e49-b858-fd4050b8d6e1.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Press ctrl+space on the empty line to get a list of element choices
available between tags.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233677788-b2b4a70a-9a21-4325-ab54-d3d03d7bcbec.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Select a choice by pressing enter. In this example the element tag with the
attribute name was selected and a value for name entered. Press tab to exit the
double quotes after entering a name value. The name attribute doesn’t have a
specific list of choices.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233677861-355ba812-13e0-4fc9-b69b-2ddc9174ad34.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Type ctrl+space to get a list of attribute choices for the element tag.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233677953-c18457ca-fabd-4db5-9a3f-7939dcb20fc6.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Selecting an attribute that has predetermined choices will supply a list of
those choice. Select an item from the list and press enter. End the tag with
‘>’ to get a closing tag on a new line with the cursor positioned between
the tags.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233678044-36d10937-190c-4a18-89b6-e3f324478ba0.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>On the new line press ctrl+space to get a list of element choices for the
element tag.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233678136-d666f8f1-1144-4bfa-ae1d-f66cc364a5c9.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Select a choice and press ctrl+space to get list of choices for the
selected annotation tag set.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233678219-84bfd78f-807e-42d4-8c18-e7a38437f86d.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Select a choice and press ctrl+space to supply a list of choices available
in the appinfo tag set.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233678327-a3187b07-40cc-4d5d-97ec-3d467595f611.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Select a choice by pressing enter.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233678437-c70f43d6-3c6b-49d1-a42f-a3571353555a.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>The discriminator test dfdl attribute doesn’t have a specific list of
choices. Press tab to exit the double quotes. The cursor will be positioned
immediately after the ending double quote.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233679069-cc5973d3-06cd-4a41-994a-2c8ccb3a7a3f.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>To add additional attributes to an existing element tag, position the
cursor within the opening tag, press ctrl+space, or space to get a list of
attribute choices for that tag.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233679162-37b78d10-10dc-4316-86d1-1460d760e58d.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>Adding a new line anywhere in the schema and pressing ctrl+space will
provide a list of choices available between the tags at the current
position.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233679238-443cc4d2-c0a6-45df-87b3-8ed5db3b185a.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>If a closing tag is deleted or missing, type ‘>’ to re-add the closing
tag at the cursor position.</p>
+<figure>
+<img
src="https://user-images.githubusercontent.com/72815523/233679358-b873ebde-b8f4-4715-a259-481dbbeea175.png";
alt="image" /><figcaption aria-hidden="true">image</figcaption>
+</figure>
+<p>The closing tag will be re-added and cursor will be placed at the end of
the line.</p>
+<h3 id="daffodil-data-parse-debugger-1">Daffodil Data Parse Debugger</h3>
+<p>The Apache Daffodil™ Extension for Visual Studio Code provides a Daffodil
Data Parse Debugger which enables the developer to carefully control the
execution of Apache Daffodil™ parse operations. Given a DFDL Schema and a
target data file, the developer can step through the execution of a parse line
by line, or until the parse reaches some developer-defined location, known as a
break point, in the DFDL Schema. What is particularly helpful is that the
developer can watch the parsed outp [...]
+<h3 id="data-editor-2">Data Editor</h3>
+<p><img width="800" src="images/DE-brief.png" alt="Data Editor"></p>
+<p>The Apache Daffodil™ Extension for Visual Studio Code provides an
integrated data editor. It is akin to a hex editor, but tuned specifically for
challenging Daffodil use cases. As an editor designed for Daffodil developers
by Daffodil developers, features of the tool will evolve quickly to address the
specific needs of the Daffodil community.</p>
+<h1 id="prerequisites-2">Prerequisites</h1>
+<p>This guide assumes VS Code and a Java Runtime Environment (Java 8 or
greater) are installed.</p>
+<ul>
+<li><a href="https://code.visualstudio.com/download";>Install VS Code</a></li>
+<li><a
href="https://docs.oracle.com/goldengate/1212/gg-winux/GDRAD/java.htm#BGBFJHAB";>Install
Java Runtime 8 or greater</a></li>
+<li>On Linux, glibc 2.31 or greater is required</li>
+</ul>
+<h1
id="installing-the-apache-daffodil-extension-for-visual-studio-code-1">Installing
the Apache Daffodil™ Extension for Visual Studio Code</h1>
+<p>The Apache Daffodil™ Extension for Visual Studio Code can be installed
using one of two methods.</p>
+<h2
id="option-1-install-the-apache-daffodil-extension-for-visual-studio-code-from-the-visual-studio-code-extension-marketplace-1">Option
1: Install the Apache Daffodil™ Extension for Visual Studio Code From the
Visual Studio Code Extension Marketplace</h2>
+<p>The Apache Daffodil™ Extension for Visual Studio Code is available in the
<a href="https://marketplace.visualstudio.com/vscode";>Visual Studio Code
Extension Marketplace</a>.</p>
+<h2
id="option-2-install-the-latest-.vsix-file-from-the-apache-daffodil-extension-for-visual-studio-code-release-page-1">Option
2: Install the Latest .Vsix File From the Apache Daffodil™ Extension for
Visual Studio Code Release Page</h2>
+<p>The latest <code>.vsix</code> (the file extension used for VS Code
extensions) file can also be downloaded from the Apache Daffodil™ Extension for
Visual Studio Code <a
href="https://github.com/apache/daffodil-vscode/releases";>releases page</a> and
installed by either:</p>
+<ul>
+<li>Using the command-line via <code>code --install-extension
<path-to-downloaded-vsix-file></code>; or</li>
+<li>Using the “Extensions: Install from VSIX” command from within VS Code by
opening the Command Palette (Mac = Command+Shift+P, Windows/Linux =
Ctrl+Shift+P), and typing <code>vsix</code> to bring up the command and
pointing it at the downloaded <code>.vsix</code> file.</li>
+</ul>
+<h1 id="dfdl-schema-authoring-using-code-completion-1">DFDL Schema Authoring
Using Code Completion</h1>
+<h2 id="set-the-editor-to-dfdl-mode-1">Set the Editor to “dfdl” mode</h2>
+<p>Since DFDL Schema files end with <code>.xsd</code> (XML Schema Definition
or XSD), the editor needs to be informed specifically that DFDL mode is desired
over the more general XML mode. The mode is selected in the status bar at the
bottom of the editor window.</p>
+<h2 id="dfdl-schema-authoring-features-1">DFDL Schema Authoring Features</h2>
+<p>Auto suggest is triggered using <code>control space</code> or typing the
beginning characters of an item. Typing one or more unique characters will
further limit the results.</p>
+<p>📝 <strong>NOTE:</strong> Intellisense is <em>context aware</em>, so there
is no need to begin a block with <code><</code>, just start typing the tag
name and code completion will automatically handle it as appropriate.</p>
+<p>Code completion can be used to add a schema block, with just a couple of
keystrokes. Code completion can make short work out of completing a DFDL Format
Block, offering context-sensitive suggestions attribute values.</p>
+<p>The <code>></code> or <code>/</code> characters are used to close XML
tags. Use <code>tab</code> to select an item from the drop down and to exit
double quotes.</p>
+<p>Code completion supports creating self-defined
<code>dfdl:complextypes</code> and <code>dfdl:simpleTypes</code>.</p>
+<p>The <code>tab</code> key can be used to complete an auto-complete item
within an XML tag. After auto-complete is triggered, typing the initial
character or characters will limit the suggestion results. Inside an XML tag a
<code>space</code> or <code>carriage return</code> will trigger a list of
context sensitive attribute suggestions.</p>
+<p>XPath expressions can be code completed.</p>
+<h2 id="known-issues-with-code-completion-1">Known Issues With Code
Completion</h2>
+<ol type="1">
+<li>The Apache Daffodil™ Extension for Visual Studio Code uses a clunky method
to auto complete curly braces within quotes. It is anticipated that this will
be better addressed in the future. The auto complete method blocks suggestions
while typing between the beginning quote, opening curly brace and the closing
curly brace, ending quote.</li>
+</ol>
+<h1
id="debugging-a-dfdl-schema-using-the-apache-daffodil-extension-for-visual-studio-codes-bundled-daffodil-data-parse-debugger-1">Debugging
a DFDL Schema Using the Apache Daffodil™ Extension for Visual Studio Code’s
Bundled Daffodil Data Parse Debugger</h1>
+<h2 id="debug-configuration-1">Debug Configuration</h2>
+<p>Debugging a DFDL Schema needs both the DFDL Schema to use and a data file
to parse. Instead of having to select the DFDL Schema and the data file each
time from a file picker, a “launch configuration” can be created, which is a
JSON description of the debugging session.</p>
+<p>To create the launch profile:</p>
+<ol type="1">
+<li><p>Select <code>Run -> Open Configurations</code> from the VS Code
menubar. This will load a <code>launch.json</code> file into the editor. There
may be existing <code>configurations</code>, or it may be empty.</p></li>
+<li><p>Press <code>Add Configuration...</code> and select the <code>Daffodil
Debug - Launch</code> option.</p></li>
+</ol>
+<p>Once the <code>launch.json</code> file has been created it will look
something like this</p>
+<div class="sourceCode" id="cb11"><pre class="sourceCode json"><code
class="sourceCode json"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true"
tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"type"</span><span class="fu">:</span> <span
class="st">"dfdl"</span><span class="fu">,</span></span>
+<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"request"</span><span class="fu">:</span> <span
class="st">"launch"</span><span class="fu">,</span></span>
+<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"name"</span><span class="fu">:</span> <span
class="st">"Ask for file name"</span><span class="fu">,</span></span>
+<span id="cb11-5"><a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"program"</span><span class="fu">:</span> <span
class="st">"${command:AskForProgramName}"</span><span
class="fu">,</span></span>
+<span id="cb11-6"><a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"stopOnEntry"</span><span class="fu">:</span> <span
class="kw">true</span><span class="fu">,</span></span>
+<span id="cb11-7"><a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"data"</span><span class="fu">:</span> <span
class="st">"${command:AskForDataName}"</span><span
class="fu">,</span></span>
+<span id="cb11-8"><a href="#cb11-8" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"infosetOutput"</span><span class="fu">:</span>
<span class="fu">{</span></span>
+<span id="cb11-9"><a href="#cb11-9" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"type"</span><span class="fu">:</span> <span
class="st">"file"</span><span class="fu">,</span></span>
+<span id="cb11-10"><a href="#cb11-10" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"path"</span><span class="fu">:</span> <span
class="st">"${workspaceFolder}/infoset.xml"</span></span>
+<span id="cb11-11"><a href="#cb11-11" aria-hidden="true" tabindex="-1"></a>
<span class="fu">},</span></span>
+<span id="cb11-12"><a href="#cb11-12" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"debugServer"</span><span class="fu">:</span> <span
class="dv">4711</span></span>
+<span id="cb11-13"><a href="#cb11-13" aria-hidden="true"
tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<p>This default configuration will prompt the user to select the DFDL Schema
and data files. If desired, the “program” and “data” elements can be mapped
specifically to the user’s files to avoid being prompted each time.</p>
+<p>📝 Note: Use <code>${workspaceFolder}</code> for files in the VS Code
workspace, and use absolute paths for files outside of the workspace.</p>
+<div class="sourceCode" id="cb12"><pre class="sourceCode json"><code
class="sourceCode json"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true"
tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"type"</span><span class="fu">:</span> <span
class="st">"dfdl"</span><span class="fu">,</span></span>
+<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"request"</span><span class="fu">:</span> <span
class="st">"launch"</span><span class="fu">,</span></span>
+<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"name"</span><span class="fu">:</span> <span
class="st">"DFDL parse: My Data"</span><span
class="fu">,</span></span>
+<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"program"</span><span class="fu">:</span> <span
class="st">"${workspaceFolder}/schema.dfdl.xsd"</span><span
class="fu">,</span></span>
+<span id="cb12-6"><a href="#cb12-6" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"stopOnEntry"</span><span class="fu">:</span> <span
class="kw">true</span><span class="fu">,</span></span>
+<span id="cb12-7"><a href="#cb12-7" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"data"</span><span class="fu">:</span> <span
class="st">"/path/to/my/data"</span><span class="fu">,</span></span>
+<span id="cb12-8"><a href="#cb12-8" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"infosetOutput"</span><span class="fu">:</span>
<span class="fu">{</span></span>
+<span id="cb12-9"><a href="#cb12-9" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"type"</span><span class="fu">:</span> <span
class="st">"file"</span><span class="fu">,</span></span>
+<span id="cb12-10"><a href="#cb12-10" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"path"</span><span class="fu">:</span> <span
class="st">"${workspaceFolder}/infoset.xml"</span></span>
+<span id="cb12-11"><a href="#cb12-11" aria-hidden="true" tabindex="-1"></a>
<span class="fu">},</span></span>
+<span id="cb12-12"><a href="#cb12-12" aria-hidden="true" tabindex="-1"></a>
<span class="dt">"debugServer"</span><span class="fu">:</span> <span
class="dv">4711</span></span>
+<span id="cb12-13"><a href="#cb12-13" aria-hidden="true"
tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<h2 id="launch-a-dfdl-parse-debugging-session-1">Launch a DFDL Parse Debugging
Session</h2>
+<p>Using the launch profile above a <code>DFDL parse: My Data</code> menu item
at the top of the <code>Run and Debug</code> pane (Command-Shift-D) will
display. Then press the <code>play</code> button to start the debugging
session.</p>
+<p>In the Terminal, log output from the DFDL debugger backend service will
display. If something is not working as expected, check the output in this
Terminal window for hints.</p>
+<p>The DFDL Schema file will also be loaded in VS Code and there should be a
visible marking at the beginning where the debugger has paused upon entry to
the debugging session. Control the debugger using the available VS Code
debugger controls such as <code>setting breakpoints</code>, <code>removing
breakpoints</code>, <code>continue</code>, <code>step over</code>, <code>step
into</code>, and <code>step out</code>.</p>
+<h2 id="other-options-for-launching-a-dfdl-parse-debugging-session-1">Other
Options for Launching a DFDL Parse Debugging Session</h2>
+<ul>
+<li><strong>Option 1:</strong>
+<ul>
+<li>Open the DFDL Schema file to debug</li>
+<li>From inside the file open the Command Palette (Mac = Command+Shift+P,
Windows/Linux = Ctrl+Shift+P)</li>
+<li>Once the command Palette is opened start typing <code>Daffodil
Debug:</code>
+<ul>
+<li>Option 1 = <code>Daffodil Debug: Debug File</code> - This will allow for
the user to fully step through the DFDL Schema. Once fully completed, it will
produce an infoset to a file named <code>SCHEMA-infoset.xml</code> which it
then opens as well.</li>
+<li>Option 2 = <code>Daffodil Debug: Run File</code> - This will run the DFDL
Schema, producing the infoset to a file named
<code>SCHEMA-infoset.xml</code>.</li>
+</ul></li>
+</ul></li>
+<li><strong>Option 2:</strong>
+<ul>
+<li>Open the schema file to debug</li>
+<li>Click the play button in the top right, two options will be provided:
+<ul>
+<li>Option 1 = <code>Debug File</code> - This will allow for the user to fully
step through the schema (WIP). Once fully completed, it will produce a infoset
to a file named <code>SCHEMA-infoset.xml</code> which it then opens as
well.</li>
+<li>Option 2 = <code>Run File</code> - This will run the DFDL Schema,
producing the infoset to a file named <code>SCHEMA-infoset.xml</code> which it
then opens as well.</li>
+</ul></li>
+</ul></li>
+</ul>
+<h2 id="custom-dfdl-debugger-views-1">Custom DFDL Debugger Views</h2>
+<h3 id="infoset-tools-1">Infoset Tools</h3>
+<p>Find the infoset tools from the command menu (Mac = Command+Shift+P,
Windows/Linux = Ctrl+Shift+P)</p>
+<h3 id="inputstream-hex-viewer-1">Inputstream Hex Viewer</h3>
+<p>Find the hex view from the command menu (Mac = Command+Shift+P,
Windows/Linux = Ctrl+Shift+P)</p>
+<h1 id="tdml-support">TDML Support</h1>
+<p>When uploading files to the mailing list, it may be easier to upload a zip
file containing a TDML file, the DFDL Schema file, the input data file, and,
optionally, the infoset file. Sending this file to the mailing list will allow
other users to unpack your zip file and run your test case. It becomes even
easier if you have multiple test cases.</p>
+<p>To Generate a TDML file, use similar steps for Launching a DFDL Parse
Debugging Session: * Open the DFDL Schema file * From inside the file, open the
Command Palette (Mac = Command+Shift+P, Windows/Linux = Ctrl+Shift+P) * Once
the Command Palette is opened, select the <code>Daffodil Debug: Generate
TDML</code> command * From there, you will be asked to provide the input data
file, the TDML test case name, the TDML test case description, and the
location/name for the TDML file.</p>
+<p>Once the Daffodil Parse has finished, an infoset and a TDML file will be
created. The TDML file contains relative paths to the DFDL Schema file, input
data file, and infoset file. When creating an archive for these files, preserve
the directory structure in the archive.</p>
+<p>To Append a new test case to an existing TDML file, use similar steps for
Generating a TDML file: * Open the DFDL Schema file * From inside the file,
open the Command Palette (Mac = Command+Shift+P, Windows/Linux = Ctrl+Shift+P)
* Once the Command Palette is opened, select the <code>Daffodil Debug: Append
TDML</code> command * From there, you will be asked to provide the input data
file, the TDML test case name, the TDML test case description, and the TDML
file</p>
+<p>Once the Daffodil Parse has finished, an infoset will be created, and a
test case will be added to the existing TDML file. The TDML test case name OR
description can be shared between test cases, but no two test cases should
share TDML test case names and descriptions. To create an archive for a TDML
file with multiple test cases, the same guidelines for creating an archive from
a TDML file created from a ‘Generate TDML’ operation should be followed. All
DFDL schema files, input data [...]
+<p>When running a zip archive created from another user, extract the archive
into your workspace folder. If there is an infoset in the zip archive that you
wish to compare with your infoset, make sure that the infoset from the zip
archive is not located at the same place as the default infoset for the
Daffodil Parse that will be run when executing a test case from the TDML file.
This is because the Daffodil Parse run by executing the TDML test case uses the
default location for its infos [...]
+<p>To Execute a test case from a TDML file, use the following steps: * Open a
DFDL Schema file * From inside the file, open the Command Palette (Mac =
Command+Shift+P, Windows/Linux = Ctrl+Shift+P) * Once the Command Palette is
opened, select the <code>Daffodil Debug: Execute TDML</code> command * From
there, you will be asked to provide the TDML file, TDML test case name, and
TDML test case description</p>
+<p>A Daffodil Parse will then be launched. The DFDL Schema file and input data
file to be used is determined by the selected test case in the TDML file. The
infoset that is generated from this parse can optionally be compared to an
infoset included in the zip archive the TDML file was extracted from.</p>
+<h2 id="sample-tdml-file">Sample TDML File</h2>
+<p>A TDML file is comprised of Test Cases. Each test case describes a DFDL
parse operation and points to the inputs and outputs of the DFDL parse
operation. Inputs - DFDL Schema file and input data file Outputs - Infoset
file</p>
+<p>Additionally, each Test Case should be uniquely identified by the
combination of its name and description. Currently, this is not enforced, and
any duplications will never be selectable by the TDML Execute operation.</p>
+<p>Below is a Sample TDML file with a single Test Case along with XPath
expressions describing where each item can be found inside of a Test Case.</p>
+<div class="sourceCode" id="cb13"><pre class="sourceCode xml"><code
class="sourceCode xml"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true"
tabindex="-1"></a><span class="fu"><?xml</span><span class="ot">
version=</span><span class="st">"1.0"</span><span class="ot">
encoding=</span><span class="st">"UTF-8"</span><span class="ot">
standalone=</span><span class="st">"yes"</span><span
class="fu">?></span></span>
+<span id="cb13-2"><a href="#cb13-2" aria-hidden="true"
tabindex="-1"></a><<span class="kw">ns1:testSuite</span><span class="ot">
xmlns:ns1=</span><span
class="st">"http://www.ibm.com/xmlns/dfdl/testData"</span><span
class="ot"> xmlns:ns2=</span><span
class="st">"http://www.ogf.org/dfdl/dfdl-1.0/"</span><span
class="ot"> xmlns:ns3=</span><span
class="st">"urn:ogf:dfdl:2013:imp:daffodil.apache.org:2018:ext"</span><span
class="ot"> xmlns:ns4=</span><span cla [...]
+<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a>
<<span class="kw">ns1:parserTestCase</span><span class="ot">
name=</span><span class="st">"Default Test Case"</span><span
class="ot"> root=</span><span class="st">"file"</span><span
class="ot"> model=</span><span class="st">"png.dfdl.xsd"</span><span
class="ot"> roundTrip=</span><span class="st">"onePass"</span><span
class="ot"> description=</span><span class="st">"G [...]
+<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a>
<<span class="kw">ns1:document</span>></span>
+<span id="cb13-5"><a href="#cb13-5" aria-hidden="true" tabindex="-1"></a>
<<span class="kw">ns1:documentPart</span><span class="ot"> type=</span><span
class="st">"file"</span>>di4zg8Kie.png</<span
class="kw">ns1:documentPart</span>></span>
+<span id="cb13-6"><a href="#cb13-6" aria-hidden="true" tabindex="-1"></a>
</<span class="kw">ns1:document</span>></span>
+<span id="cb13-7"><a href="#cb13-7" aria-hidden="true" tabindex="-1"></a>
<<span class="kw">ns1:infoset</span>></span>
+<span id="cb13-8"><a href="#cb13-8" aria-hidden="true" tabindex="-1"></a>
<<span class="kw">ns1:dfdlInfoset</span><span class="ot"> type=</span><span
class="st">"file"</span>>png-infoset.xml</<span
class="kw">ns1:dfdlInfoset</span>></span>
+<span id="cb13-9"><a href="#cb13-9" aria-hidden="true" tabindex="-1"></a>
</<span class="kw">ns1:infoset</span>></span>
+<span id="cb13-10"><a href="#cb13-10" aria-hidden="true" tabindex="-1"></a>
</<span class="kw">ns1:parserTestCase</span>></span>
+<span id="cb13-11"><a href="#cb13-11" aria-hidden="true"
tabindex="-1"></a></<span
class="kw">ns1:testSuite</span>></span></code></pre></div>
+<p><code>/ns1:testSuite/ns1:parserTestCase/@model</code> contains the relative
path to the DFDL Schema file. This path is relative to the location of the TDML
file<br />
+<code>/ns1:testSuite/ns1:parserTestCase/@name</code> contains the name of the
Test Case<br />
+<code>/ns1:testSuite/ns1:parserTestCase/@description</code> contains a
description of the Test Case<br />
+<code>/ns1:testSuite/ns1:parserTestCase/ns1:document/ns1:documentPart/text()</code>
contains the relative path to the input data file. This path is relative to
the location of the TDML file<br />
+<code>/ns1:testSuite/ns1:parserTestCase/ns1:infoset/ns1:dfdlInfoset/text()</code>
contains the relative path to the infoset file created with the parameters of
this test case. This path is relative to the location of the TDML file</p>
+<h2 id="data-editor-3">Data Editor</h2>
+<p>This version of the Apache Daffodil™ Extension for Visual Studio Code
includes a new Data Editor. To use the Data Editor, open the VS Code command
palette and select <code>Daffodil Debug: Data Editor</code>.</p>
+<p><img width="800" src="images/DE-cmd-palette.png"/></p>
+<p>A notification message will appear that informs where the Data Editor will
write its logs to. If problems happen, check this log file for clues.</p>
+<p><img width="400" src="images/DE-log-notification.png"/></p>
+<p>Once the extension is connected to the server, the bottom left corner of
the Data Editor shows the version of the Ωedit server powering the editor, and
the port its connected to. Hovering over the filled circle shows the CPU load
average, the memory usage of the server in bytes, the server session count, the
server uptime measured in seconds, and the round trip latency measured in
milli-seconds.</p>
+<p><img width="800" src="images/DE-heartbeat.png"/></p>
+<p>After selecting a file to edit, there will be a table with controls at the
top of the Data Editor.</p>
+<p><img width="800" src="images/DE-top-controls.png"/></p>
+<p>The first section of the table is called <code>File Metrics</code> and it
contains the path of the file being edited, its initial size in bytes, and the
size as the file is being edited. When changes are committed, the
<code>Save</code> button will become enabled, allowing the changes to be saved
to file.</p>
+<p><img width="400" src="images/DE-filemetrics.png"/></p>
+<p>The second section of the table is called <code>Search</code>, and it
allows for Searching of byte sequences in the given <code>Edit Encoding</code>.
If the <code>Edit Encoding</code> can be case-insensitive, a <code>Case
Insensitive</code> checkbox will be displayed allowing for that option to be
enabled. The found sequences can be examined using the <code>Prev</code> and
<code>Next</code> buttons found in this section. Found sequences can also be
replaced in the given <code>Edit Enc [...]
+<p><img width="800" src="images/DE-search.png"/> <br/> <img width="800"
src="images/DE-replace.png"/></p>
+<p>The third section of the table is called <code>Settings</code>, and it
allows for toggling the <code>Byte Edit Mode</code> from <code>Single</code> to
<code>Multiple</code>.</p>
+<p>In <code>Single</code> byte edit mode, individual bytes may be
<em>deleted</em>, <em>inserted</em> (to the left or to the right of the
selected byte), and <em>overwritten</em> in the <code>Ephemeral Edit
Window</code> that appears when a byte in the <code>Physical</code> or
<code>Logical</code> viewports is clicked. Mouseover the buttons of the
<code>Ephemeral Edit Window</code> to determine what each button does.
Mouseover the <code>Input Box</code> and it will show the byte offset p [...]
+<p><img width="800" src="images/DE-SBM.png"/></p>
+<p>In <code>Multiple</code> byte edit mode, a segment of bytes is selected
from either the <code>Physical</code> or <code>Logical</code> viewports, then
the selected segment of bytes is edited in the <code>Edit</code> viewport using
the selected <code>Edit Encoding</code>. Once editing of the selected segment
is completed, the <code>Commit</code> button is pressed, and the edited segment
replaces the selected segment</p>
+<p><img width="800" src="images/DE-MBM.png"/></p>
+<p>Byte addresses can be expressed in hexadecimal, decimal, or octal. The
selected <code>Address Radix</code> is also what is used entering an offset
into the <code>Offset</code> input. If an offset was entered in the
<code>Offset</code> input and the <code>Address Radix</code> is changed, the
offset will automatically be converted into the selected radix.</p>
+<p><img width="800" src="images/DE-offset-hex.png"/> <br/> <img width="800"
src="images/DE-offset-dec.png"/></p>
+<p>In <code>Single</code> byte edit mode, byte editing can be done in the
<code>Physical</code> viewport, or the <code>Logical</code> viewport. The
<code>Physical</code> viewport shows the bytes as they are stored in the file
and can be represented in <code>Hexadecimal</code>, <code>Decimal</code>,
<code>Octal</code>, or <code>Binary</code> depending on the <code>Byte Display
Radix</code>. The <code>Logical</code> viewport always shows the bytes as
<code>Latin-1</code>. The <code>Data Vi [...]
+<p><img width="800" src="images/DE-SBM-oct.png"/> <img width="800"
src="images/DE-SBM-bin.png"/></p>
+<p>In <code>Multiple</code> byte edit mode, byte editing can only be done in
the <code>Edit</code> viewport using a selection of bytes from the
<code>Physical</code> or <code>Logical</code> viewports. The <code>Edit</code>
viewport shows the bytes represented in <code>Hexadecimal</code>,
<code>Binary</code>, <code>ASCII</code>, <code>Latin-1</code>,
<code>UTF-8</code>, or <code>UTF-16LE</code> (UTF-16 Little Endian), depending
on the <code>Edit Encoding</code>. Once the editing of that s [...]
+<p>Regardless of the <code>Byte Edit Mode</code>, changes can be Undoed and
Redone using the <code>Undo</code> and <code>Redo</code> buttons. The
<code>Revert All</code> button will revert all changes made to the file since
it was opened in the Data Editor.</p>
+<p><img width="200" src="images/DE-EditEncoding.png"/> <img width="800"
src="images/DE-MBM-UTF-8.png"/></p>
+<p>The Data Editor supports light and dark modes. The mode is determined by
the VSCode theme. If the VSCode theme is set to a light theme, the Data Editor
will be in light mode. If the VSCode theme is set to a dark theme, the Data
Editor will be in dark mode.</p>
+<p><img width="800" src="images/Theme-selection.png"/> <img width="800"
src="images/DE-light-theme.png"/></p>
+<h3 id="data-editor-limitations-in-v1.3.0">Data Editor Limitations in
v1.3.0</h3>
+<ol type="1">
+<li><p>The current editing limit is 1,000,000 bytes. This is due to the amount
of memory it takes to encode and display all the bytes in the
viewports.</p></li>
+<li><p>Only one Data Editor instance can be opened at one time.</p></li>
+<li><p>Viewport selections do not persist when they lose focus. This is a
limitation of implementing the display viewports using textarea
elements.</p></li>
+<li><p>Currently Replace will replace <em>all instances</em> of the given
search pattern with the replacement pattern.</p></li>
+</ol>
+<p>As of v1.3.0, this feature is <em>minimally viable</em> and will be
improving over time. Expect these limitations to be removed in the next
release.</p>
+<p>📝 Note: The non-printable font being used (░) may appear different on
different platforms and OS/font configurations.</p>
+<h1 id="reporting-problems-and-requesting-new-features-1">Reporting Problems
and Requesting New Features</h1>
+<p>If problems are encountered or new features are desired, create tickets <a
href="https://github.com/apache/daffodil-vscode/issues";>here</a>.</p>
+<h1 id="getting-help-1">Getting Help</h1>
+<p>If additional help or guidance on using Daffodil and its tooling is needed,
please engage with the community on <a
href="https://daffodil.apache.org/community/";>mailing lists</a> and/or review
the <a
href="https://lists.apache.org/[email protected]";>archives</a>.</p>
+<h1 id="additional-resources-1">Additional Resources</h1>
+<ul>
+<li><a href="https://github.com/apache/daffodil-vscode/wiki";>Apache Daffodil™
Extension for Visual Studio Code Wiki</a></li>
+<li><a href="https://github.com/apache/daffodil";>Apache Daffodil
Repository</a></li>
+</ul>
+<hr />
+<p><img src="images/asf-daffodil-logo.svg" /></p>
+<h1 id="apache-daffodil-extension-for-visual-studio-code-brief">Apache
Daffodil™ Extension for Visual Studio Code: Brief</h1>
+<p>The Apache Daffodil™ Extension for Visual Studio Code is an extension to
the Microsoft® Visual Studio Code (VS Code) editor, designed for Data Format
Description Language<sup><a href="#footnotes">1</a></sup> (DFDL) Schema
developers. The purpose of the Apache Daffodil™ Extension for Visual Studio
Code is to ease the burden on DFDL Schema developers by enabling rapid
development of high-quality DFDL Schemas, with syntax highlighting, code
completion, data file editing, and debugging of [...]
+<h2 id="dfdl-schema-development">DFDL Schema Development</h2>
+<p><img width="800" src="images/schema-dev.png"/></p>
+<p>The Apache Daffodil™ Extension for Visual Studio Code provides syntax
highlighting to improve the readability and context of the text and provide
instant feedback to the developer indicating the structure and code are
syntactically correct.</p>
+<p>The Apache Daffodil™ Extension for Visual Studio Code provides code
completion offering context-aware code segment predictions that can
dramatically speed up DFDL Schema development by reducing keyboard input,
memorization by the developer, and typos.</p>
+<h2 id="daffodil-data-parse-debugger-2">Daffodil Data Parse Debugger</h2>
+<p><img width="800" src="images/data-parse-debugger.png"/></p>
+<p>The Apache Daffodil™ Extension for Visual Studio provides a Daffodil parse
debugger enabling the developer to control the execution of Daffodil parse
operations. Given a DFDL Schema and a target data file, the developer can step
through the execution of parse operations line by line, or until the parse
reaches some developer-defined location, known as a breakpoint, in the DFDL
Schema or the data being parsed. What is particularly helpful is that the
developer can watch the parsed outp [...]
+<h2 id="data-editor-4">Data Editor</h2>
+<p>The Apache Daffodil™ Extension for Visual Studio Code provides an
integrated data editor that is tuned specifically for challenging Daffodil use
cases. It is designed to support large files, of any type, that are well beyond
the limits of the standard text editor in VS Code. The Data Editor allows for
setting Data Parse Debugger breakpoints on offset positions in the data file.
The Data Editor handles non-standard byte sizes, non-aligned bytes, and byte
ordering where the Least Signif [...]
+<h1 id="getting-help-2">Getting Help</h1>
+<p>If additional help or guidance on using Apache Daffodil™, Apache Daffodil™
Extension for Visual Studio Code, or DFDL development in general is needed,
please engage with the Daffodil user and developer communities on <a
href="https://daffodil.apache.org/community/";>mailing lists</a>
(https://daffodil.apache.org/community/) and/or review the <a
href="https://lists.apache.org/[email protected]";>list
archives</a> (https://lists.apache.org/[email protected] [...]
+<h1 id="community-feedback">Community Feedback</h1>
+<p><a href="https://www.apache.org";><img width="200"
src="images/asf_logo_url.svg"/></a></p>
+<p>Apache Daffodil™ and the Apache Daffodil™ Extension for Visual Studio Code
are Apache Software Foundation (ASF) projects, are free open-source software,
and under active development. Feedback and contributions are welcome.</p>
+<h1 id="additional-resources-2">Additional Resources</h1>
+<ul>
+<li><a href="https://daffodil.apache.org";>Apache Daffodil™ Home Page</a>
(https://daffodil.apache.org)</li>
+<li><a href="https://github.com/apache/daffodil-vscode";>Apache Daffodil™
Extension for Visual Studio Code Repository</a>
(https://github.com/apache/daffodil-vscode)</li>
+<li><a href="https://github.com/apache/daffodil-vscode/wiki";>Apache Daffodil™
Extension for Visual Studio Code Wiki</a>
(https://github.com/apache/daffodil-vscode/wiki)</li>
+<li><a href="https://github.com/apache/daffodil";>Apache Daffodil™ Library
Repository</a> (https://github.com/apache/daffodil)</li>
+</ul>
+<h1 id="legal">Legal</h1>
+<p>Apache, Apache Feather Logo, Apache Daffodil, Daffodil, and the Apache
Daffodil logo are trademarks of The Apache Software Foundation. Visual Studio
Code, and VS Code are trademarks of Microsoft® Corporation. All rights
reserved.</p>
+<h4 id="footnotes">Footnotes</h4>
+<p><sup>1</sup> Data Format Description Language (DFDL) is a standard from the
Open Grid Forum (www.ogf.org), available <a
href="https://ogf.org/documents/GFD.240.pdf";>here</a>
(https://ogf.org/documents/GFD.240.pdf).</p>
+<p>Copyright © 2023 <a href="https://www.apache.org/";>The Apache Software
Foundation</a>. Licensed under the <a
href="https://www.apache.org/licenses/LICENSE-2.0";>Apache License, Version
2.0</a>. <br/> Apache, Apache Daffodil, Daffodil, and the Apache Daffodil logo
are trademarks of The Apache Software Foundation.</p>
+<p><a href="https://github.com/apache/daffodil-vscode/wiki/Home";>Brief</a></p>
+<p>User Documentation * <a
href="https://github.com/apache/daffodil-vscode/wiki/Apache-Daffodil%E2%84%A2-Extension-for-Visual-Studio-Code:-v1.3.0";>1.3.0
- latest</a> * <a
href="https://github.com/apache/daffodil-vscode/wiki/Apache-Daffodil%E2%84%A2-Extension-for-Visual-Studio-Code:-v1.2.0";>1.2.0</a></p>
+<p><a
href="https://github.com/apache/daffodil-vscode/wiki/Apache-Daffodil%E2%84%A2-Extension-for-Visual-Studio-Code:-Roadmap";>Roadmap</a></p>
+<p><a
href="https://github.com/apache/daffodil-vscode/wiki/Apache-Daffodil%E2%84%A2-Extension-for-Visual-Studio-Code:-Development";>Development</a></p>
![https://github.com/apache/daffodil-vscode/actions/workflows/CI.yml/badge.svg"](https://github.com/apache/daffodil-vscode/actions/workflows/CI.yml/badge.svg"){kind=link}
![https://github.com/apache/daffodil-vscode/actions/workflows/nightly.yml/badge.svg"](https://github.com/apache/daffodil-vscode/actions/workflows/nightly.yml/badge.svg"){kind=link}
![https://user-images.githubusercontent.com/98881959/152995881-982a321a-6926-460f-aa37-e4c3a5fa7dff.gif"](https://user-images.githubusercontent.com/98881959/152995881-982a321a-6926-460f-aa37-e4c3a5fa7dff.gif"){kind=link}
![https://user-images.githubusercontent.com/1545372/130599778-03228007-df80-4593-8504-e1bf69943c68.gif"](https://user-images.githubusercontent.com/1545372/130599778-03228007-df80-4593-8504-e1bf69943c68.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/152995118-e2da5835-027e-4ff7-90f9-baf36a7e04bb.gif"](https://user-images.githubusercontent.com/98881959/152995118-e2da5835-027e-4ff7-90f9-baf36a7e04bb.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/152995218-65d5b5b6-b610-495d-af31-69dd81be58c1.gif"](https://user-images.githubusercontent.com/98881959/152995218-65d5b5b6-b610-495d-af31-69dd81be58c1.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/152995254-1de6d39e-a482-4cb5-b7f3-7444932d056f.gif"](https://user-images.githubusercontent.com/98881959/152995254-1de6d39e-a482-4cb5-b7f3-7444932d056f.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/152995294-7d70b7c6-186b-41e1-8a48-81ebfc3e04bc.gif"](https://user-images.githubusercontent.com/98881959/152995294-7d70b7c6-186b-41e1-8a48-81ebfc3e04bc.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/152995321-ef0b2d45-32e6-4e3a-b5aa-859aa937cc3a.gif"](https://user-images.githubusercontent.com/98881959/152995321-ef0b2d45-32e6-4e3a-b5aa-859aa937cc3a.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/152995446-77a33620-7277-4d9a-8dd7-f88349299ec9.gif"](https://user-images.githubusercontent.com/98881959/152995446-77a33620-7277-4d9a-8dd7-f88349299ec9.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/152995652-e56bc55d-78ba-46f6-a26c-6d7bd4440e96.gif"](https://user-images.githubusercontent.com/98881959/152995652-e56bc55d-78ba-46f6-a26c-6d7bd4440e96.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/152995682-466be4bb-7f3f-4dcc-84bc-09792bc26adc.gif"](https://user-images.githubusercontent.com/98881959/152995682-466be4bb-7f3f-4dcc-84bc-09792bc26adc.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/152995737-2f31e4e8-525d-4cb5-a5d7-a0413a087a54.gif"](https://user-images.githubusercontent.com/98881959/152995737-2f31e4e8-525d-4cb5-a5d7-a0413a087a54.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/152995769-b6afda2b-dd77-4f7a-ad18-b3e1f28087f6.gif"](https://user-images.githubusercontent.com/98881959/152995769-b6afda2b-dd77-4f7a-ad18-b3e1f28087f6.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/153010643-9d1c8361-b55d-45e4-a7a4-907ec876de76.gif"](https://user-images.githubusercontent.com/98881959/153010643-9d1c8361-b55d-45e4-a7a4-907ec876de76.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/153051326-2b9d03ce-3e3a-420a-abba-408b25a2c3d2.gif"](https://user-images.githubusercontent.com/98881959/153051326-2b9d03ce-3e3a-420a-abba-408b25a2c3d2.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/153051453-e76250e2-96f6-4f07-8e9a-0a77f9ece5fe.gif"](https://user-images.githubusercontent.com/98881959/153051453-e76250e2-96f6-4f07-8e9a-0a77f9ece5fe.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/153051544-78372145-98aa-4b56-84f4-8b3a3bca4d9f.gif"](https://user-images.githubusercontent.com/98881959/153051544-78372145-98aa-4b56-84f4-8b3a3bca4d9f.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/153051732-fb948f86-3485-4606-9e92-8325f1d5052d.gif"](https://user-images.githubusercontent.com/98881959/153051732-fb948f86-3485-4606-9e92-8325f1d5052d.gif"){kind=link}
![https://user-images.githubusercontent.com/98881959/153051821-abc47704-878f-4c01-8a29-c0d3911940d0.gif"](https://user-images.githubusercontent.com/98881959/153051821-abc47704-878f-4c01-8a29-c0d3911940d0.gif"){kind=link}
![https://user-images.githubusercontent.com/1545372/130598508-ed4ac8df-ec93-4f45-8ef8-d2668234aff6.gif"](https://user-images.githubusercontent.com/1545372/130598508-ed4ac8df-ec93-4f45-8ef8-d2668234aff6.gif"){kind=link}
![https://user-images.githubusercontent.com/1545372/130599643-cb4b7aba-7dda-46de-8166-762c79336d58.gif"](https://user-images.githubusercontent.com/1545372/130599643-cb4b7aba-7dda-46de-8166-762c79336d58.gif"){kind=link}
![https://user-images.githubusercontent.com/1545372/130602144-29df81f1-b397-48be-be01-dc7eeaf1eccc.gif"](https://user-images.githubusercontent.com/1545372/130602144-29df81f1-b397-48be-be01-dc7eeaf1eccc.gif"){kind=link}
![https://user-images.githubusercontent.com/1545372/130602743-14b9a29e-6c1e-44d9-b1d6-80ccacaca6e3.gif"](https://user-images.githubusercontent.com/1545372/130602743-14b9a29e-6c1e-44d9-b1d6-80ccacaca6e3.gif"){kind=link}
![https://user-images.githubusercontent.com/2205472/203111897-241aa221-91f7-41e2-951c-6006a5e82815.gif"](https://user-images.githubusercontent.com/2205472/203111897-241aa221-91f7-41e2-951c-6006a5e82815.gif"){kind=link}
![https://user-images.githubusercontent.com/2205472/203114858-a256a21e-0400-414f-b2ad-9fe9bf6580e5.png"](https://user-images.githubusercontent.com/2205472/203114858-a256a21e-0400-414f-b2ad-9fe9bf6580e5.png"){kind=link}
![https://user-images.githubusercontent.com/2205472/203124466-f8fa1772-e915-482b-b0a2-6d621da15334.png"](https://user-images.githubusercontent.com/2205472/203124466-f8fa1772-e915-482b-b0a2-6d621da15334.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233675278-db394389-30b3-4925-aa70-3167fdcb6826.png"](https://user-images.githubusercontent.com/72815523/233675278-db394389-30b3-4925-aa70-3167fdcb6826.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233675615-96ff35d2-16a3-487d-9c31-4d2dc50f31cb.png"](https://user-images.githubusercontent.com/72815523/233675615-96ff35d2-16a3-487d-9c31-4d2dc50f31cb.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233675776-91f00665-c274-45d6-b280-534dbf6df80c.png"](https://user-images.githubusercontent.com/72815523/233675776-91f00665-c274-45d6-b280-534dbf6df80c.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233676375-931f82ee-3ec3-4bac-8563-f6aa09d077d2.png"](https://user-images.githubusercontent.com/72815523/233676375-931f82ee-3ec3-4bac-8563-f6aa09d077d2.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233676482-7fc8bb0d-b214-4697-910a-a67143c602d8.png"](https://user-images.githubusercontent.com/72815523/233676482-7fc8bb0d-b214-4697-910a-a67143c602d8.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233676701-aec092f3-34ed-42c9-bb4b-38f336d2f87e.png"](https://user-images.githubusercontent.com/72815523/233676701-aec092f3-34ed-42c9-bb4b-38f336d2f87e.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233676809-d4ca872e-ab47-4279-b90d-080d84f19493.png"](https://user-images.githubusercontent.com/72815523/233676809-d4ca872e-ab47-4279-b90d-080d84f19493.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233676930-901b8369-5b06-42e3-a163-b409b43371c3.png"](https://user-images.githubusercontent.com/72815523/233676930-901b8369-5b06-42e3-a163-b409b43371c3.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233677182-d04a34aa-d767-4f5e-8aac-e9dac8bcafc3.png"](https://user-images.githubusercontent.com/72815523/233677182-d04a34aa-d767-4f5e-8aac-e9dac8bcafc3.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233677268-9a3cdd48-f34c-4f9c-9398-a19ae58e610f.png"](https://user-images.githubusercontent.com/72815523/233677268-9a3cdd48-f34c-4f9c-9398-a19ae58e610f.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233677348-25dd34e1-5dad-4598-ac64-be2a00ece488.png"](https://user-images.githubusercontent.com/72815523/233677348-25dd34e1-5dad-4598-ac64-be2a00ece488.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233677447-16fdd7c2-e219-4e4f-b2f4-1d73c93f2a5b.png"](https://user-images.githubusercontent.com/72815523/233677447-16fdd7c2-e219-4e4f-b2f4-1d73c93f2a5b.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233677530-0dcb823e-00e5-4faa-b46e-d3aecd63daf0.png"](https://user-images.githubusercontent.com/72815523/233677530-0dcb823e-00e5-4faa-b46e-d3aecd63daf0.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233677621-7165170c-b519-4c5d-a863-4c46311a9b14.png"](https://user-images.githubusercontent.com/72815523/233677621-7165170c-b519-4c5d-a863-4c46311a9b14.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233677700-6a991a1c-cdcc-4e49-b858-fd4050b8d6e1.png"](https://user-images.githubusercontent.com/72815523/233677700-6a991a1c-cdcc-4e49-b858-fd4050b8d6e1.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233677788-b2b4a70a-9a21-4325-ab54-d3d03d7bcbec.png"](https://user-images.githubusercontent.com/72815523/233677788-b2b4a70a-9a21-4325-ab54-d3d03d7bcbec.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233677861-355ba812-13e0-4fc9-b69b-2ddc9174ad34.png"](https://user-images.githubusercontent.com/72815523/233677861-355ba812-13e0-4fc9-b69b-2ddc9174ad34.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233677953-c18457ca-fabd-4db5-9a3f-7939dcb20fc6.png"](https://user-images.githubusercontent.com/72815523/233677953-c18457ca-fabd-4db5-9a3f-7939dcb20fc6.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233678044-36d10937-190c-4a18-89b6-e3f324478ba0.png"](https://user-images.githubusercontent.com/72815523/233678044-36d10937-190c-4a18-89b6-e3f324478ba0.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233678136-d666f8f1-1144-4bfa-ae1d-f66cc364a5c9.png"](https://user-images.githubusercontent.com/72815523/233678136-d666f8f1-1144-4bfa-ae1d-f66cc364a5c9.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233678219-84bfd78f-807e-42d4-8c18-e7a38437f86d.png"](https://user-images.githubusercontent.com/72815523/233678219-84bfd78f-807e-42d4-8c18-e7a38437f86d.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233678327-a3187b07-40cc-4d5d-97ec-3d467595f611.png"](https://user-images.githubusercontent.com/72815523/233678327-a3187b07-40cc-4d5d-97ec-3d467595f611.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233678437-c70f43d6-3c6b-49d1-a42f-a3571353555a.png"](https://user-images.githubusercontent.com/72815523/233678437-c70f43d6-3c6b-49d1-a42f-a3571353555a.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233679069-cc5973d3-06cd-4a41-994a-2c8ccb3a7a3f.png"](https://user-images.githubusercontent.com/72815523/233679069-cc5973d3-06cd-4a41-994a-2c8ccb3a7a3f.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233679162-37b78d10-10dc-4316-86d1-1460d760e58d.png"](https://user-images.githubusercontent.com/72815523/233679162-37b78d10-10dc-4316-86d1-1460d760e58d.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233679238-443cc4d2-c0a6-45df-87b3-8ed5db3b185a.png"](https://user-images.githubusercontent.com/72815523/233679238-443cc4d2-c0a6-45df-87b3-8ed5db3b185a.png"){kind=link}
![https://user-images.githubusercontent.com/72815523/233679358-b873ebde-b8f4-4715-a259-481dbbeea175.png"](https://user-images.githubusercontent.com/72815523/233679358-b873ebde-b8f4-4715-a259-481dbbeea175.png"){kind=link}