Skip to content

Latest commit

 

History

History
49 lines (30 loc) · 3.29 KB

overview.adoc

File metadata and controls

49 lines (30 loc) · 3.29 KB
Raw

Tutorial Overview

The aim of this tutorial is to familiarize the reader with the Parsley specification and toolchain, through a series of short lessons, each of which involve capturing a real-world specification within Parsley.

What is Parsley?

Parsley is a data format definition language. That is, Parsley allows for the creation of precise specifications for file formats. The Parsley compiler provides a specification checker and an interpreter. An overview of the first iteration of the language, its goals, and its initial design choices can be found in the initial Parsley research report. This tutorial and the Parsley documentation are actively being updated to reflect the status of the latest stable release of Parsley.

Installation

To install the Parsley compiler:

  1. Install opam, the OCaml package manager (https://opam.ocaml.org/doc/Install.html).

  2. Install the dependencies specified in the README using opam.

  3. Clone the repository containing the Parsley type checker, examples, and other documentation: git clone [email protected]:SRI-CSL/parsley-lang.git and then type cd parsley-lang.

  4. Run make in this directory. You should now see an executable, parsleyc.exe, in the directory. This executable is the Parsley compiler.

Running the Specification Checker and Interpreter

The Parsley specification checker takes a single command-line argument, a relative file path, and it checks whether the file specified by that path conforms to the Parsley specification. You can test this by running:

./parsleyc.exe check ./test/lang/examples.ply

The type checker will either approve of the file or specify where things went wrong.

PLACEHOLDER - add example for interpreter

Learning by Example

This tutorial is organized as a series of short lessons, which are designed to be completed in short sittings (~30 minutes). Each lesson focuses on creating a Parsley specification that corresponds to either part or all of a real-world specification. The examples corresponding to the lessons in this tutorial can be found in ./tutorial/examples/.

Tutorial Layout

Lesson 1: The User Datagram Protocol: The User Datagram Protocol is an important protocol in the IP suite that is used in conjunction with IPv4 to deliver data over the internet with minimal overhead.

Lesson 2: The Internet Protocol (version 4): The Internet Protocol (version 4) is another important protocol in the IP suite that is used for the transmission of packets over the internet.

Lesson 3: The Portable Bitmap Format: The Portable Bitmap format is a simple bitmap-based image format.

Lesson 4: Checking the Checksum: In this fourth lesson, we do checksum validation for UDP and IPv4.