This repository contains the "peml" ruby gem, a parser for PEML.
The Programming Exercise Markup Language (PEML) (feedback on name choice is welcome!) is intended to be a simple, easy format for CS and IT instructors of all kinds (college, community college, high school, whatever) to describe programming assignments and activities. We want it to be so easy (and obvious) to use that instructors won't see it as a technological or notational barrier to expressing their assignments.
We intend for this format to be something that authors of automated grading tools can adopt, so they can provide a very easy, low-energy onboarding path for existing instructors to get programming activities into such tools. As a result, this notation leans heavily on supporting authors and streamlining common cases, even if this may require more work on the part of tool developers--the goal is to make it super easy for authors of programming activities, not to fit into a specific auto-grader or simplify tasks for tool writers.
For full details on PEML, see:
https://CSSPLICE.github.io/peml/
You can try out PEML in your browser using our live, interactive parser here:
https://discovery.cs.vt.edu/peml-live
If you are working on an application and want to make use of PEML, but do not want to use the Ruby parser implementation in this gem or you prefer to use a different programming language, you can use the parser via our REST API from the PEML Live! website. Documentation is available at:
https://discovery.cs.vt.edu/peml-live/api
Add this line to your application's Gemfile:
gem 'peml', :github => 'CSSPLICE/peml'And then execute:
$ bundle
Or install it using the gem command (may require you to clone the repository and build your own local copy of the gem to install).
require 'peml'
Peml.parse(peml: "string containing a PEML description")
Peml.parse(filename: "file_name.peml")
The result returned by the parse() function is a hash
containing two key/value pairs, where value is the
parsed result of the PEML input in nested hash form, and
diagnostics contains an array of any diagnostic messages
(errors or other validation messages) produced.
The following additional arguments can be provided as named parameters:
result_only (boolean)
Indicate whether to return just the parse result (true), or (the default) a
hash of the form { value: <parse_result>, diagnostics: [<messages>] }.
interpolate (boolean) (not yet implemented)
Indicate whether or not to interpolate variables embedded in
PEML field values.
render_to_html (boolean) (not yet implemented)
Indicate whether PEML fields containing markdown/markup values
should be rendered to HTML in the result.
inline (boolean) (not yet implemented)
Indicate whether to inline field contents in the PEML description when the
value is specified as a URL.
format (string)
This parameter indicates the format requested for the response, which is
one of (json, yaml, xml). This can be specified as an explicit parameter
named "format" passed in the request, or can be specified directly in the
request URL as a file name extension (e.g., requesting
from https://discovery.cs.vt.edu/peml-live/api/parse.yaml?...).
If not explicitly provided, it will be inferred through the "Accept:"
headers provided in the request, or defaults to json if not specified
anywhere else.
See the grape
gem's discussion
of API formats for more details about how the format of the
response is determined.
Eventually, we'll also add support for:
require 'peml'
Peml.to_peml(some_nested_hash)
=> string containing exercise rendered in PEML format
my_exercise.to_peml
=> string containing exercise rendered in PEML format
... but these don't work yet.
Bug reports and pull requests are welcome on GitHub at https://github.com/CSSPLICE/peml.