Set Def File Syntax

[goehle]

Its time for a change to how problems are included in .def files. The reason is that the current syntax has the problem data presented as an unlabeled, comma separated list. However, showMeAnother and the Just-In-Time stuff have added 3 new fields to the problem record and requires problem_id to actually be saved. These fields may or may not be present depending on settings and its getting hard/impossible to parse the unlabeled list correctly.

On my Just-in-Time branch I've changed Homework Sets Editor 2 so that it now supports problemListV2 which adds labels to problem fields using the same syntax that we use for the set parameters. So a problem in the problemListV2 would look like

 problem_start
 source_file = Library/myDefFile.def
 value = 1
 max_attempts = 2
 showMeAnother = -1
 problem_id = 2
 counts_parent_grade = 0
 att_to_open_children = 0
 problem_end

Homework Sets Editor 2 still supports the old style for imports (it looks for problemList vs problemListV2) but it exports everything using this. I think the labelled list makes it easier to work with the def files (because you can see what parameters are what, they don't have to be in a particular order, and some can be missing.) I wanted to put this issue up because it is a change to how something has been done for a while. Also, I don't know how Peter is using .def files, but this may impact WeBWorK3.

[mgage]

Seems like something like this needs to be done at this point. Two other possibilities are to use XML notation or to use JSON notation. They would have even more flexibility if we need it in the future. It's not clear that we will. These other formulas are not quite as easy to understand as the format you propose although JSON is not far off.

Just something to think about.

--Mike.

Sent from my iPad

On Jun 6, 2014, at 9:32 AM, "Geoff Goehle" notifications@github.com<mailto:notifications@github.com> wrote:

Its time for a change to how problems are included in .def files. The reason is that the current syntax has the problem data presented as an unlabeled, comma separated list. However, showMeAnother and the Just-In-Time stuff have added 3 new fields to the problem record and requires problem_id to actually be saved. These fields may or may not be present depending on settings and its getting hard/impossible to parse the unlabeled list correctly.

On my Just-in-Time branch I've changed Homework Sets Editor 2 so that it now supports problemListV2 which adds labels to problem fields using the same syntax that we use for the set parameters. So a problem in the problemListV2 would look like

problem_start = souce_file = Library/myDefFile.def value = 1 max_attempts = 2 showMeAnother = -1 problem_id = 2 counts_parent_grade = 0 att_to_open_children = 0 problem_end =

(The extra = on problem_start and problem_end are a result of how the set def reader pulls in lines. They don't have to be there but they don't hurt much either.)

Homework Sets Editor 2 still supports the old style but it exports everything using this. I think the labelled list makes it easier to work with the def files (because you can see what parameters are what, they don't have to be in a particular order, and some can be missing.) I wanted to put this issue up because it is a change to how something has been done for a while. Also, I don't know how Peter is using .def files, but this may impact WeBWorK3.

Reply to this email directly or view it on GitHub[github.com]https://urldefense.proofpoint.com/v1/url?u=https://github.com/openwebwork/webwork2/issues/427&k=p4Ly7qpEBiYPBVenR9G2iQ%3D%3D%0A&r=enN3K%2BCUdz1bRKB01s3PUtIX0B0zjgWTYpo9pUAD9Ek%3D%0A&m=oSIs2ff3hep23Awda18%2FmeEkBz0ePILiAZwV4YrGUBY%3D%0A&s=66b7ba2d099a2c848202f4df6ccc82409c5f386a68b9ee6278bc016a567df547.

[goehle]

I agree, although if we moved to an entirely different syntax I would be for changing the file time from .def to something else to reflect that.

[pstaabp]

I would argue for doing a .json format and actually creating/reading the file is very simple. In ww3, this is the way that all objects are passed from the server to the client and back. For example,

{
   "enable_reduced_scoring" : false,
   "version_time_limit" : "",
   "set_header" : "defaultHeader",
   "restricted_status" : "1",
   "restrict_ip" : "No",
   "hardcopy_header" : "defaultHeader",
   "version_creation_time" : "",
   "open_date" : "1392958740",
   "hide_work" : "",
   "hide_score" : "",
   "relax_restrict_ip" : "No",
   "problems" : [
      {
         "problem_id" : "1",
         "flags" : "",
         "value" : "1",
         "max_attempts" : "-1",
         "showMeAnother" : "-1",
         "source_file" : "Library/WHFreeman/Rogawski_Calculus_Early_Transcendentals_Second_Edition/1_Precalculus_Review/1.3_The_Basic_Classes_of_Functions/1.3.5.pg",
         "set_id" : "HW4",
         "showMeAnotherCount" : ""
      },
      {
         "problem_id" : "2",
         "flags" : "",
         "value" : "1",
         "max_attempts" : "-1",
         "showMeAnother" : "-1",
         "source_file" : "Volumes/WW_test/opt/webwork/courses/maa101/templates/Library/270/setDerivatives1/ur_dr_1_5.pg",
         "set_id" : "HW4",
         "showMeAnotherCount" : ""
      }
   ],
   "problem_randorder" : "",
   "hide_hint" : "0",
   "version_last_attempt_time" : "",
   "versions_per_interval" : "0",
   "visible" : true,
   "time_interval" : "",
   "restricted_release" : "",
   "set_id" : "HW4",
   "description" : "",
   "reduced_scoring_date" : "1401681540",
   "problems_per_page" : "0",
   "due_date" : "1402545540",
   "assignment_type" : "default",
   "answer_date" : "1403609520",
   "time_limit_cap" : "",
   "attempts_per_version" : "",
   "hide_score_by_problem" : "",
   "restricted_login_proctor" : "No"
}

Although it looks like the files in the problem sets are system dependent. (I'll have to fix that).

I’ve been thinking about making configuration (global/site/course) as well as set definition files all json. I haven’t taken this on in that we need to do this both for ww2 and ww3 at the same time and build tools to convert them as needed.

Maybe we can figure out a plan for doing this.

[goehle]

I guess I don't see the advantage to moving to a new .def format, except that JSON is a popular programming thing. Both of them specify things by a variable name, a separating symbol, and a value. For people familiar with JSON, I agree a .json def file would be great. However, my guess is that more of our users are familiar with .def files than JSON. We would have to support backwards compatibility anyway so its not like it would actually make our lives easier.

I think there is room for both, if we want. If we move to a completely new format we should change the extension name, just for our own sanity if nothing else, and it still seems worthwhile to upgrade .def so that it supports new features.

In general I would warn against changing config file formats unless we have to. They aren't centrally maintained by git which means that backwards compatibility is going to be a problem, easily negating any benefit we get from using a slick new format. I could be sold on changing the global/site/course config files, though because I feel like .json files are probably safer since reading them doesn't involve running perl code. That would involve mucking around with CourseEnvirotnment though, which may or may not be easy.

[pstaabp]

There's a few nice things about JSON. First, it's a standard format for data storage/transfer and very lightweight. This means that there are packages and tools to deal with them. Trying to get a simple.conf working well in ww3 was harder than it needed to be (I can remember why I didn't just use the one in ww2), where as a to_json call and then write to file is a single line of code and very easy to maintain.

Secondly, as we move to ww3, dancer is constantly handling the json conversions and it will be easy to handle.

I agree that we need to think about backwards compatibility, but in terms of people understanding the current .def format, I'm guessing that there aren't many writing their own, instead, letting ww export in this format and that anyone actually use .def can handle switching to a .json format.

In terms of set definition files, if we are searching for those in the browser or via an import/export, it should look and handle both and we could probably have a simple conversion tool to convert as well.

About the other configuration files, the global config files I think it's a distant project, but the course one should be a simple change. I haven't looked at the CourseEnvironment.pm file, but hear that it's a bit of a beast. A couple of reasons that I've argued for a change is that 1) it will make the configuration files themselves more coherent. Right now, in defaults.config the default value for something may be hundreds of lines away from the description of it. A .json file would put all of that in the same place and easier to read. And 2) the code will get cleaned up and I think that always helps with fewer bugs. The read/write to/from .json files is pretty trivial and in many ways will force us to think about all the course configurations and how to actually store them.

[goehle]

I think this has diverged into two discussions a bit. I agree that course/site/global configuration should eventually move to json. Its more robust for what we want it to do, and its more secure. You are right, though, that's a big project and can go on the list.

I think the def files are different.

• They are a lot more distributed than the conf files. A given server will have one global conf and one site conf, and I don't think converting course confs will be that bad since there is one per course and its always kept in the same place. However there may be many many def files stored in lots of places. Def files are kept in old courses, peoples hard drives from when they exported a course they liked, and so on. A given user might be expected to have a def file lying around somewhere, but not a conf file.
• They perform a different role. Conf files need to be read every time a server does something and passed around from thing to thing. The portability of JSON makes a big impact here. Def files are parsed once to make a set and then never used again by the server. If we do it right they really only need to be parsed and dealt with in one helper function, as well.
• I also think you are underestimating how many people work directly with the .def files. I know Alina does because she was mentioning that she wanted to build JITAR sets directly from the def file. She is not into programming though and switching to JSON would be an issue. I bet a surprising number of long time users think editing the def files directly is easier than using the GUI. (Especially anyone from the WeBWorK 1 days.)

[pstaabp]

What are you suggesting we do with the set definition files? It sounds like you're advocating for continuing along the standard format.

Another argument for JSON is that that it should handle the JITAR sets well if I remember correctly. The JITAR sets are trees or arrays of trees and that is handled easier by JSON.

As for editing JSON files, there are editors that exist that help to some extent (especially with nested structures), but once the format is known, it's not that hard to do. In fact the simple problem set definition files would replace the = with a : and throw into a few "" around strings. The example that I presented above was dumped from my browser with everything included, but we can fill in missing fields with defaults.

[goehle]

I'm proposing for .def files that we allow users to use an additional format to specify problems. The old format will still work (mostly, but not for jitar) and even the new problemListV2 format is very similar to the existing def file syntax.

The tree structure of jitar sets is handled by the problem numbers. (E.g. 1.2.1 vs 1.2 vs 1). This is how it works at the database level so having it work this way in the def file is fine.

If it were just a choice between json and some homebrew format then json would win. But its a choice between json and a format that people have been using for a decade. Most of the arguments for switching def files seem to be "its easier to program", and I'm not excited about making my life easier at the cost of the users.

On Sat, Jun 7, 2014 at 5:26 AM, Peter Staab notifications@github.com wrote:

What are you suggesting we do with the set definition files? It sounds like you're advocating for continuing along the standard format.

Another argument for JSON is that that it should handle the JITAR sets well if I remember correctly. The JITAR sets are trees or arrays of trees and that is handled easier by JSON.

As for editing JSON files, there are editors that exist that help to some extent (especially with nested structures), but once the format is known, it's not that hard to do. In fact the simple problem set definition files would replace the = with a : and throw into a few "" around strings. The example that I presented above was dumped from my browser with everything included, but we can fill in missing fields with defaults.

— Reply to this email directly or view it on GitHub https://github.com/openwebwork/webwork2/issues/427#issuecomment-45406699 .

[pstaabp]

We could start to develop a new file type. I think we could have two types for problem sets. Much like there are multiply types for ms word files.

[goehle]

Yes, because that as a feature of word files that I've enjoyed so much over the years ;)

Maybe a better time to revisit this would be when we start redoing some of the db stuff. The actual data that is stored is going to change pretty radically and that would be a good reason to start a new format. This new format is for the new set version and the old format is for the old set version, kind of thing.

On Sat, Jun 7, 2014 at 11:22 AM, Peter Staab notifications@github.com wrote:

We could start to develop a new file type. I think we could have two types for problem sets. Much like there are multiply types for ms word files.

— Reply to this email directly or view it on GitHub https://github.com/openwebwork/webwork2/issues/427#issuecomment-45414254 .

[pstaabp]

If you're happy with your current set Definition style, then I agree, let's wait until the DB is redone.