diff --git a/src/checkstyle.xml b/checkstyle.xml similarity index 97% rename from src/checkstyle.xml rename to checkstyle.xml index 4794625..a1cadb7 100644 --- a/src/checkstyle.xml +++ b/checkstyle.xml @@ -1,495 +1,492 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/java-src/net/sf/webcat/plugins/javatddplugin/ValidationMessageFormatter.java b/java-src/net/sf/webcat/plugins/javatddplugin/ValidationMessageFormatter.java new file mode 100644 index 0000000..87649eb --- /dev/null +++ b/java-src/net/sf/webcat/plugins/javatddplugin/ValidationMessageFormatter.java @@ -0,0 +1,76 @@ +package net.sf.webcat.plugins.javatddplugin; + +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +public class ValidationMessageFormatter { + + public static String formatMessage(Throwable error) { + if (error == null) { + return null; + } + + if (error instanceof NoSuchMethodError) { + return "Your test has called a method that does not exist in the interface. " + + "The reference implementation is not guaranteed to implement this method " + + "and as such cannot validate this test case. " + + "The method is: " + error.getMessage(); + } + else if (error instanceof AssertionError) { + String original = error.getMessage(); + String msg; + + if (original != null) { + Pattern p1 = Pattern.compile( + ".*expected:]*)>? but was:]*)>?"); + Matcher m1 = p1.matcher(original); + if (m1.matches()) { + String expected = m1.group(1).trim(); + String actual = m1.group(2).trim(); + msg = "Your test expected: <" + expected + "> " + + "while the reference implementation returned: <" + + actual + ">"; + } + else if (original.contains("expected null, but was:")) { + Pattern p2 = Pattern.compile( + ".*expected null, but was:]*)>?"); + Matcher m2 = p2.matcher(original); + if (m2.matches()) { + String actual = m2.group(1).trim(); + msg = "Your test expected: " + + "while the reference implementation returned: <" + + actual + ">"; + } + else { + msg = original; + } + } + else if (original.contains("expected same:")) { + Pattern p3 = Pattern.compile( + ".*expected same:]*)>? was not:]*)>?"); + Matcher m3 = p3.matcher(original); + if (m3.matches()) { + String expected = m3.group(1).trim(); + String actual = m3.group(2).trim(); + msg = "Your test expected the *same* object: <" + + expected + "> " + + "while the reference implementation returned a different object: <" + + actual + ">"; + } + else { + msg = original; + } + } + else { + msg = original; + } + } + else { + msg = original; + } + return msg; + } + + return null; + } +} diff --git a/java-src/net/sf/webcat/plugins/javatddplugin/ValidationPlistJUnitResultFormatter.java b/java-src/net/sf/webcat/plugins/javatddplugin/ValidationPlistJUnitResultFormatter.java new file mode 100644 index 0000000..dd43649 --- /dev/null +++ b/java-src/net/sf/webcat/plugins/javatddplugin/ValidationPlistJUnitResultFormatter.java @@ -0,0 +1,22 @@ +package net.sf.webcat.plugins.javatddplugin; + +import junit.framework.Test; + +public class ValidationPlistJUnitResultFormatter + extends PlistJUnitResultFormatter { + @Override + protected TestResultDescriptor describe(Test test, Throwable error) { + String customMsg = ValidationMessageFormatter.formatMessage(error); + + if (customMsg != null) { + int code = codeOf(error); + int level = levelOf(code); + String stackTrace = stackTraceMessage(error, false); + return new TestResultDescriptor(currentSuite, test, error, code, + level, customMsg, stackTrace); + } + else { + return super.describe(test, error); + } + } +} diff --git a/java-src/net/sf/webcat/plugins/javatddplugin/ValidationTextJUnitResultFormatter.java b/java-src/net/sf/webcat/plugins/javatddplugin/ValidationTextJUnitResultFormatter.java new file mode 100644 index 0000000..4863c5d --- /dev/null +++ b/java-src/net/sf/webcat/plugins/javatddplugin/ValidationTextJUnitResultFormatter.java @@ -0,0 +1,61 @@ +package net.sf.webcat.plugins.javatddplugin; + +import junit.framework.Test; +import junit.framework.AssertionFailedError; + +public class ValidationTextJUnitResultFormatter + extends BasicJUnitResultFormatter { + + private static class FormattedThrowable extends Throwable { + private static final long serialVersionUID = 1L; + private final Throwable original; + private final String message; + + public FormattedThrowable(String message, Throwable original) { + super(message, original); + this.message = message; + this.original = original; + this.setStackTrace(original.getStackTrace()); + } + + + @Override + public String toString() { + return original.getClass().getName() + ": " + message; + } + } + + @Override + public void addError(Test test, Throwable error) { + String msg = formatMessage(error); + Throwable newError = new FormattedThrowable(msg, error); + super.addError(test, newError); + } + + + @Override + public void addFailure(Test test, AssertionFailedError error) { + String msg = formatMessage(error); + Throwable newFailure = new FormattedThrowable(msg, error); + super.addFailure(test, newFailure); + } + + + private String formatMessage(Throwable error) { + String customMsg = ValidationMessageFormatter.formatMessage(error); + + if (customMsg != null) { + return customMsg; + } + + if (error != null) { + if (error.getMessage() != null) { + return error.getMessage(); + } + else { + return error.toString(); + } + } + return ""; + } +} diff --git a/src/build.xml b/src/build.xml index 5451e39..bcb7e22 100644 --- a/src/build.xml +++ b/src/build.xml @@ -9,6 +9,8 @@ + + @@ -54,6 +56,16 @@ --> + + + + + + + + + + @@ -117,11 +129,46 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -179,6 +226,8 @@ PATH = ${printable.path} timeout = ${exec.timeout} (for each of two test runs) assignmentClassFiles = ${assignmentClassFiles} assignmentClassDir = ${assignmentClassDir} +referenceImplementationClassFiles = ${referenceImplementationClassFiles} +referenceImplementationClassDir = ${referenceImplementationClassDir} instructorClassFiles = ${instructorClassFiles} instructorClassDir = ${instructorClassDir} testCasePath = ${testCasePath} @@ -199,8 +248,9 @@ staticAnalysisSrcExclusionPattern = ${staticAnalysisSrcExclusionPattern} - + + @@ -244,6 +294,18 @@ staticAnalysisSrcExclusionPattern = ${staticAnalysisSrcExclusionPattern} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -446,7 +608,6 @@ staticAnalysisSrcExclusionPattern = ${staticAnalysisSrcExclusionPattern} - --> - @@ -613,8 +773,7 @@ staticAnalysisSrcExclusionPattern = ${staticAnalysisSrcExclusionPattern} failonerror="false" failOnRuleViolation="false" > - - + + + + + @@ -817,7 +980,7 @@ staticAnalysisSrcExclusionPattern = ${staticAnalysisSrcExclusionPattern} The main target ============================================================ --> - + diff --git a/src/checkstyle/README.md b/src/checkstyle/README.md index 4b47311..efa0d38 100644 --- a/src/checkstyle/README.md +++ b/src/checkstyle/README.md @@ -3,6 +3,6 @@ Jars in this folder are used to provide the current version of checkstyle used by the plugin. -The current version used is: 8.35 +The current version used is: 10.7.0 -https://github.com/checkstyle/checkstyle/releases/download/checkstyle-8.35/checkstyle-8.35-all.jar +http://github.com/checkstyle/checkstyle/releases/download/checkstyle-10.7.0/checkstyle-10.7.0-all.jar diff --git a/src/config.plist b/src/config.plist index 8c1cb99..77829d9 100644 --- a/src/config.plist +++ b/src/config.plist @@ -1,874 +1,1163 @@ -{ - name = "JavaTddPlugin"; - version.major = 4; - version.minor = 1; - version.revision = 3; - version.date = 20240916; - autoPublish = true; - requires = ( ANTForPlugins, PerlForPlugins, - PMDForPlugins, CheckstyleForPlugins ); - provider = "Virginia Tech Computer Science"; - provider.url = "http://web-cat.org/updates"; - license = "GNU Affero General Public License v.3"; - license.url = "http://www.gnu.org/licenses/agpl.html"; - copyright = - "(c) 2006-2025 Virginia Tech Department of Computer Science"; - info.url = "http://wiki.web-cat.org/WCWiki/JavaTddPlugin"; - history.url = - "http://wiki.web-cat.org/WCWiki/JavaTddPlugin/ChangeHistory"; - executable = execute.pl; - interpreter.prefix = "${PerlForPlugins.perl.exe}"; - author = "Stephen Edwards (edwards@cs.vt.edu)"; - authorUid = edwards; - languages = ( { name = Java; version = 1.14; } ); - description = "This \"all-in-one\" plug-in is designed to provide full - processing and feedback generation for Java assignments where - students write their own JUnit test cases. - It includes ANT-based compilation, JUnit processing of student-written - tests, support for instructor-written reference tests, PMD and - Checkstyle analysis, and Clover-based tracking of code coverage - during student testing."; - timeoutMultiplier = 2; - timeoutInternalPadding = 400; - assignmentOptions = ( - { - property = testCases; - type = fileOrDir; - fileTypes = ( java ); - name = "Hidden JUnit Reference Test Class(es)"; - description = - "A Java source file (or directory of source files) containing JUnit tests - to run against student code to assess completeness of problem coverage. - Test outcomes are not directly visible to students, an students only see - hints about what may be incorrect. - If you select a single Java file, it must contain a JUnit test class - declared in the default package. If you select a directory, it should - contain JUnit test classes arranged in subdirectories according to their - Java package declarations. If you make no selection, an empty set of - instructor reference tests will be used instead."; - }, -/* { - property = visibleTestCases; - type = fileOrDir; - fileTypes = ( java ); - name = "Visible JUnit Reference Test Class(es)"; - description = - "A Java source file (or directory of source files) containing JUnit tests - to run against student code to assess completeness of problem coverage. - \"Visible\" here means pass/fail information for every test is shown (not - limited by hint controls). - If you select a single Java file, it must contain a JUnit test class - declared in the default package. If you select a directory, it should - contain JUnit test classes arranged in subdirectories according to their - Java package declarations. If you make no selection, an empty set of - instructor reference tests will be used instead."; - }, -*/ { - property = assignmentJar; - type = fileOrDir; - fileTypes = ( jar ); - name = "Supplemental Classes for Assignment"; - description = - "A jar file (or a directory of class files in subdirs reflecting their - package structure, or a directory of multiple jar files) containing - precompiled classes to add to the classpath when compiling and running - submissions for this assignment. If you want to apply the same - jar settings to many assignments, use the \"Supplemental Classes\" setting - in the \"Reusable Configuration Options\" section instead. If you have - multiple jars to provide, place them all in the same directory in your - Web-CAT file space and then select the whole directory."; - }, - { - property = localFiles; - type = fileOrDir; - name = "Data Files for Student"; - description = - "A file (or a directory of files) to place in the student's current working - directory when running his/her tests and when running reference tests. The - file you select (or the entire contents of the directory you select) will be - copied into the current working directory during grading so that - student-written and instructor-written test cases can read and/or write to - the file(s). The default is to copy no files."; - } - ); - optionCategories = ( - "Basic Settings", - "Advanced Settings", - "Experimental Settings", - "Developer Settings" - ); - options = ( - { - property = useAssertions; - type = boolean; - default = true; - name = "Use Java Assertions"; - category = "Basic Settings"; - description = - "Enable Java assertions during execution. When set to false, assertions - in student or instructor-provided code will be treated as non-executable - (no-op's)."; - }, - { - property = useDefaultJar; - type = boolean; - default = true; - name = "Use Built-in Jars"; - category = "Basic Settings"; - description = - "Set to true to have a set of built-in jars containing Virginia Tech - CS 1/CS 2 classes placed on the classpath for assignments. Set to - false to omit these jars from the classpath."; - }, - { - property = classpathJar; - type = fileOrDir; - fileTypes = ( jar ); - name = "Predefined Classes"; - category = "Basic Settings"; - description = - "A jar file (or a directory of class files in subdirs reflecting their - package structure, or a directory of multiple jar files) containing - precompiled classes to add to the classpath when compiling and running - submissions. Use this setting if you'd like to share the same jar(s) - across several assignments. If you have multiple jars to provide, - place them all in the same directory in your Web-CAT file space and - then select the whole directory."; - }, - { - property = useXvfb; - type = boolean; - default = false; - name = "Enable Xvfb During Test Execution"; - category = "Advanced Settings"; - description = - "This option is necessary for running GUI software tests on Linux servers. - It uses an instance of Xvfb, the X virtual frame buffer server, to run - unit tests so that GUI tests can render to a live X server. Note that - enabling this option will slow down test execution, since it takes time to - start up an X server, but it is required for GUI testing on a linux - server. Also, this option requires that Xvfb is already installed on - the server."; - }, - { - property = policyFile; - advanced = true; - type = file; - fileTypes = ( policy ); - name = "Java Security Policy"; - category = "Advanced Settings"; - description = - "A Java security policy file used to limit actions on student programs at - run-time. Leave unset to use the built-in default, which plugs most - security holes and prevents any file system access outside the subtree - rooted at the program's working directory."; - }, - { - property = remote.post.url; - advanced = true; - type = shortText; - size = 40; - name = "Remotely Post Submissions"; - category = "Advanced Settings"; - description = - "A URL to which submissions will be posted as they are processed, to - allow for external tools to receive student submissions. If a URL is - specified an HTML POST request will be sent to the given URL, with the - student's user name provided in the parameter 'user', and the student's - submission file provided in the parameter 'uploadedfile'."; - }, - { - property = "grader.partnerExcludePatterns"; - advanced = true; - type = shortText; - size = 40; - name = "Partner Name Exclude Patterns"; - category = "Basic Settings"; - description = - "The plug-in will automatically scan @author tags in source code - to try to identify the user names of partners when partners are allowed - on an assignment. Here, you can provide a comma-separated list of names - to exclude from consideration (e.g., the names of instructors, if some - instructor names are listed in @author lines in pre-provided code). - Full Perl-style regular expressions can be used if desired."; - }, - { - property = allStudentTestsMustPass; - type = boolean; - default = false; - name = "All Student Tests Must Pass"; - category = "Basic Settings"; - description = - "If you are truly following test-driven development practices, then no code - is ever released until all of its unit tests pass. If this option is set to - true, students will not receive a non-zero score or receive further - assessment feedback unless all student tests pass. If this option is not - set, then students may continue to proceed even if some student-written - tests fail The student's correctness/testing score is multiplied by the - proportion of their tests that pass."; - }, - { - property = studentsMustSubmitTests; - type = boolean; - default = true; - name = "Students Must Submit Tests"; - category = "Basic Settings"; - description = - "When set, this option requires all students to submit test cases for their - own code. Submissions without test cases will received feedback to that - effect (and no more), as well as a zero score. If you unset this option, - then student submissions will not be required to include - student-written test cases, and only the reference test pass rate - will be used for scoring (i.e., student code coverage and student test pass - rate will not be included in scoring)."; - }, - { - property = includeStudentTestsInGrading; - type = boolean; - default = true; - name = "Include Student Test Results in Grading"; - category = "Basic Settings"; - description = - "When set, if students are required to submit tests, they are also included - in the scoring formula. When false, student test pass/fail ressults are - not included in the score calculation."; - }, - { - property = coverageMetric; - advanced = true; - type = radioChoice; - name = "Test Coverage Metric"; - category = "Basic Settings"; - default = 0; - description = "Choose the criterion used to measure how thoroughly - a student's tests cover the corresponding code."; - choices = ( { label = "Methods executed"; value = 0; }, - { label = "Lines executed"; value = 1; }, - { label = "Methods + conditions executed"; - value = 2; }, - { label = "Lines + conditions executed"; - value = 3; }, - { label = "Methods + lines + conditions executed"; - value = 4; } - ); - }, - { - property = coverageGoal; - type = double; - name = "Test Coverage Goal"; - category = "Basic Settings"; - description = - "If students are required to submit tests, this value is the target test - coverage threshold that must be achieved in order for students to receive - full credit. It should be a number between 0.0-100.0 representing the - minimum percent coverage required for full credit. The default is 100.0, - but a lower value may be used to allow students some slack in test coverage - when JaCoCo test coverage measures make achieving 100% too challenging."; - }, - { - property = includeTestSuitesInCoverage; - type = boolean; - default = false; - name = "Include Student Test Code in Coverage Measures"; - category = "Basic Settings"; - description = - "Normally, this plug-in excludes student-written tests from all coverage - calculations, since the goal of the testing is to test the solution, not - to execute more tests. When this option is set, student-written tests - will be included in code coverage measures for the purposes of scoring, - meaning that students will have to execute all of the code in their - test classes."; - }, - { - property = requireSimpleExceptionCoverage; - type = boolean; - default = false; - name = "Require Coverage of Simple Catch Blocks"; - category = "Basic Settings"; - description = - "When set, this option requires students to test all catch blocks, including - simple try/catch statements that are provided purely for compiler compliance - and that simply print a stack trace or re-throw the exception. If unchecked, - catch blocks that contain only a statement to print the stack trace or - re-throw a wrapped version of the exception are not counted in - coverage measurements, and do not result in point deductions."; - }, - { - property = requireSimpleGetterSetterCoverage; - type = boolean; - default = false; - name = "Require Coverage of Simple Getters and Setters"; - category = "Basic Settings"; - description = - "When set, this option requires students to test all simple getter and - setter methods. A simple getter is a method whose name starts with - \"get\", and whose body simply returns a field value. A simple setter is - a void method whose name starts with \"set\" accepting one parameter, and - whose body simply assigns that parameter to a field. If unchecked, - simple getters and setters are not counted in coverage measurements, and - do not result in point deductions."; - }, -/* - { - property = "clover.includes"; - type = shortText; - size = 40; - default = "**"; - name = "Classes to Include in Coverage Measures"; - category = "Basic Settings"; - description = - "Specify the Java file names that should be included in Clover coverage - analysis. Only student class files with names that match the patterns you - list here will be processed by Clover. Patterns are - case-insensitive. Use * as a wildcard character (ANT-style pattern - matching is used)."; - }, - { - property = "clover.excludes"; - type = shortText; - size = 40; - default = "none"; - name = "Classes to Exclude from Coverage Measures"; - category = "Basic Settings"; - description = - "Specify Java file names that should not be processed by - Clover. Any classes that match the \"Classes to Include in Coverage - Measures\" above and also match the patterns you list here - will not be processed by Clover. Patterns are - case-insensitive. Use * as a wildcard character (ANT-style pattern - matching is used). Use \"none\" if you do not wish to use any - exclusion patterns."; - }, -*/ - { - property = studentTestInclude; - type = shortText; - size = 40; - default = "*test *tests"; - name = "Students Test Class Patterns"; - category = "Basic Settings"; - description = - "Specify the Java class names that should be treated as JUnit-style - test cases. Only student classes with names that match the patterns you - list here will be executed as test cases. Patterns are case-insensitive. - Use * as a wildcard character (ANT-style pattern matching is used)."; - }, - { - property = studentTestExclude; - type = shortText; - size = 40; - default = "abstract* *$*"; - name = "Students Test Class Exclusion Patterns"; - category = "Basic Settings"; - description = - "Specify Java class names that should not be treated as JUnit-style - test cases. Any classes that match the \"Student Test Class Patterns\" - above and also match the patterns you list here - will not be treated as executable test cases. Patterns are - case-insensitive. Use * as a wildcard character (ANT-style pattern matching - is used). Use \"none\" if you do not wish to use any exclusion patterns."; - }, - { - property = refTestInclude; - type = shortText; - size = 40; - default = "*"; - name = "Reference Test Class Patterns"; - category = "Basic Settings"; - description = - "Specify the Java class names that should be treated as JUnit-style - test cases when selected as reference tests by an instructor. This - setting is only relevant when an instructor selects an entire directory - or folder of Java classes. In that case, only instructor reference classes - with names that match the patterns you list here will be executed as test - cases. Patterns are case-insensitive. Use * as a wildcard character - (ANT-style pattern matching is used)."; - }, - { - property = refTestExclude; - type = shortText; - size = 40; - default = "abstract* *$*"; - name = "Reference Test Class Exclusion Patterns"; - category = "Basic Settings"; - description = - "Specify Java class names that should not be treated as JUnit-style - test cases when selected as reference tests by an instructor. This - setting is only relevant when an instructor selects an entire directory or - folder of Java classes. In that case, any classes that match the - \"Reference Test Class Patterns\" above and also match the - patterns you list here will not be treated as executable test cases. - Patterns are case-insensitive. Use * as a wildcard character (ANT-style - pattern matching is used)."; - }, - { - property = student.testingsupport.junit4.AdaptiveTimeout.ceiling; - advanced = true; - type = integer; - name = "Default Test Case Time Limit (in ms)"; - category = "Basic Settings"; - description = - "This plug-in provides built-in adaptive detection and termination of - infinite loops that occur within individual test methods. This setting - controls the default timeout before a single test case method is judged as - \"taking too long\", although this amount will be gradually increased up - to a higher maximum value if test methods terminate but come close to - this limit. The default if unset is ten seconds (10000 ms)."; - }, - { - property = student.testingsupport.junit4.AdaptiveTimeout.maximum; - advanced = true; - type = integer; - name = "Default Test Case Maximum Time (in ms)"; - category = "Basic Settings"; - description = - "This plug-in provides built-in adaptive detection and termination of - infinite loops that occur within individual test methods. This setting - controls the maximum allowable timeout before a single test case is judged - as \"taking too long\". The default if unset is twenty seconds (20000 ms)."; - }, - { - property = disableCheckstyle; - type = antBoolean; - name = "Turn Checkstyle Off"; - category = "Basic Settings"; - description = - "Disable Checkstyle for static analysis entirely (no need to upload a - separate configuration file to turn it off)."; - }, - { - property = checkstyleConfig; - advanced = true; - type = file; - fileTypes = ( xml ); - name = "Checkstyle Configuration"; - category = "Basic Settings"; - description = - "An XML file containing a Checkstyle rule configuration (see the - Checksyle - documentation). This plug-in uses Checkstyle v5.6. If you would - like to turn off all Checkstyle checks entirely, use the \"Turn - Checkstyle Off\" option instead."; - }, - { - property = disablePmd; - type = antBoolean; - name = "Turn PMD Off"; - category = "Basic Settings"; - description = - "Disable PMD for static analysis entirely (no need to upload a - separate configuration file to turn it off)."; - }, - { - property = pmdConfig; - advanced = true; - type = file; - fileTypes = ( xml ); - name = "PMD Configuration"; - category = "Basic Settings"; - description = - "An XML file containing a set of PMD rules (see the - PMD - documentation). This plug-in uses PMD v5.0.5. If you owuld like to - turn off all PMD checks entirely, use the \"Turn PMD Off\" options instead."; - }, - { - property = use.comtor; - type = antBoolean; - name = "Run COMTOR Comment Analyzer"; - category = "Experimental Settings"; - description = - "Set to true to run the COMTOR Comment Analyzer and include the results - as part of the overall feedback report."; - }, - { - property = staticAnalysisInclude; - type = shortText; - size = 40; - default = "*"; - name = "Classes to Analyze"; - category = "Basic Settings"; - description = - "Specify the Java class names that should be included in Checkstyle and - PMD analysis. Only student classes with names that match the patterns you - list here will be processed by Checkstyle and PMD. Patterns are - case-insensitive. Use * as a wildcard character (ANT-style pattern - matching is used)."; - }, - { - property = staticAnalysisExclude; - type = shortText; - size = 40; - default = "none"; - name = "Classes to Exclude from Analysis"; - category = "Basic Settings"; - description = - "Specify Java class names that should not be processed by - Checkstyle or PMD. Any classes that match the \"Classes to Analyze\" - above and also match the patterns you list here - will not be processed by Checkstyle or PMD. Patterns are - case-insensitive. Use * as a wildcard character (ANT-style pattern - matching is used). Use \"none\" if you do not wish to use any - exclusion patterns."; - }, - { - property = markupProperties; - advanced = true; - type = file; - fileTypes = ( properties ); - name = "Static Analysis Scoring Scheme"; - category = "Advanced Settings"; - description = - "A Java properties file containing the point deductions and limits to - use for messages generated by Checkstyle or PMD. The point deductions - are specified in a fairly generic way so they can be used for many - assignments. Deductions in the default scheme are typically 1, 2, or 5 - 'points', which are really simply relative weights. Specify a scaling - factor below to adjust how these weights are translated into point - deductions for a student."; - }, - { - property = toolDeductionScaleFactor; - advanced = true; - type = double; - name = "Static Analysis Deduction Scaling Factor"; - category = "Advanced Settings"; - description = - "The Static Analysis Scoring Scheme above defines the point deductions - and limits to use for messages generated by Checkstyle or PMD in a generic - way, with most deductions in the default scheme being 1, 2, or 5 points. - Deductions in the static analysis scoring scheme are multiplied by this - factor to translate them into actual 'point deductions' shown to the - student."; - }, - { - property = hintsLimit; - type = integer; - default = 3; - name = "Hints Limit"; - category = "Basic Settings"; - description = - "Maximum number of hints the student will receive from failed reference - tests."; - }, - { - property = minCoverageLevel; - type = double; - name = "Minimum Test Coverage for Hints"; - category = "Basic Settings"; - description = - "If students are required to submit tests, this value is a minimum test - coverage threshold that must be achieved in order for any hints to be - given. It should be a number between 0.0-100.0 representing the minimum - percent coverage required to see hints."; - }, - { - property = junitErrorsHideHints; - type = boolean; - default = false; - name = "Clean JUnit Tests Required for Hints"; - category = "Basic Settings"; - description = - "If students are required to submit tests, this option requires all test - case classes to be free of PMD-based JUnit style errors, such as failing - to include at least one test method in each test case class, failing - to include assert*() calls in each test case method, or using \"bogus\" - assertions such as assertEquals(1, 1)."; - }, - { - property = hideHintsWithin; - advanced = true; - type = integer; - default = 0; - name = "Hide Hints X Days Before Deadline"; - category = "Advanced Settings"; - description = - "Suppress all hints from failed reference tests for submissions within this - many days of the deadline (set to zero for hints to always be visible). - This setting allows the instructor to \"hide\" hints close to the assignment - deadline in an attempt to encourage students to start working earlier."; - }, - { - property = showHintsWithin; - advanced = true; - type = integer; - default = 0; - name = "Show Hints X Days Before Deadline"; - category = "Advanced Settings"; - description = - "Show hints (up to the Hints Limit) from failed reference tests for - submissions within this many days of the deadline (only useful when Hide - Hints X Days Before Deadline is non-zero, to restore hints as the - deadline approaches)."; - }, - { - property = wantPDF; - type = boolean; - default = false; - name = "Generate PDF Printouts"; - category = "Basic Settings"; - description = - "Set to true if you wish for a single PDF file containing a pretty-printed - source code printout to be generated from the student's code. The printout - will be downloadable by students, and accessible by TAs during grading. - Note: This option uses both enscript and - ps2pdf as external commands, and requires these programs to - be correctly installed and configured."; - }, -/* - { - property = enscriptStyle; - type = shortText; - size = 15; - default = "msvc"; - name = "PDF Formatting Style (for Enscript)"; - category = "Basic Settings"; - description = - "If you are generating PDF printouts, you can specify the formatting style - used by enscript. This name will be passed to - enscript using its --style= parameter. See your - enscript documentation for more information about the styles that are - supported. Many enscript installations support the following styles: - a2ps, emacs, emacs-verbose, - ifh, and msvc. It is possible to add your - own custom formatting definitions to your enscript installation and then - use your own style name here as well."; - }, -*/ - { - property = wantClassDiagrams; - type = boolean; - default = true; - name = "Generate Class Diagrams"; - category = "Basic Settings"; - description = - "Set to true if you wish to generate class diagrams from students' code. - The diagrams will be viewable by students, and accessible by TAs during - grading. Note: This option uses both doxygen and - dot as external commands, and requires these programs to - be correctly installed and configured in the JavaTddPlugin's global - configuration options."; - }, - { - property = debug; - type = integer; - advanced = true; - default = 0; - name = "Debug Level"; - category = "Developer Settings"; - description = - "Set to a non-zero value for the script to produce debugging output (the - larger the number, the greater the detail, up to about 5). Debugging output - on each grading script run will be e-mailed to the instructor."; - }, - { - property = doNotDelete; - type = antBoolean; - advanced = true; - name = "Preserve Derived Files"; - category = "Developer Settings"; - description = - "Set to true to prevent the plug-in from deleting the derived files it - creates during the build/test process for each submission. Normally, these - files are deleted when a given submission has been completely processed. - This setting is provided for debugging purposes, when one wishes to - inspect the intermediate test driver source code or other derived files."; - }, - { - property = generateHeatmaps; - type = antBoolean; - advanced = true; - name = "Generate Bug Heatmaps"; - category = "Experimental Settings"; - description = - "Set to true to generate GZoltar-based defect heatmaps. This option is - experimental and for research use only. Using it will slow down - generation of student feedback."; - }, - { - property = useEnhancedFeedback; - type = boolean; - advanced = true; - default = false; - name = "Use Enhanced Feedback (Experimental)"; - category = "Experimental Settings"; - description = - "Set to true to use the new (experimental) enhanced feedback layout."; - }, - { - property = useIndicatorFeedback; - type = boolean; - advanced = true; - default = false; - name = "Use Growth Mindset Feedback (Experimental)"; - category = "Experimental Settings"; - description = - "Set to true to use the new (experimental) growth mindset progress feedback."; - }, - { - property = useMaria; - type = boolean; - advanced = true; - default = false; - name = "Use Maria (Experimental)"; - category = "Experimental Settings"; - description = - "Set to true to show Maria (experimental), the virtual teaching assistant - chatbot."; - }, - { - property = useMariaExplanations; - type = boolean; - advanced = true; - default = false; - name = "Use Maria Explanations (Experimental)"; - category = "Experimental Settings"; - description = - "Set to true to show \"Explain...\" links (experimental) by error messages."; - }, - { - property = useDailyMissions; - type = boolean; - advanced = true; - default = false; - name = "Use Daily Missions (Experimental)"; - category = "Experimental Settings"; - description = - "Set to true to give students daily mission challenges (experimental)."; - }, - { - property = showAllTestOutcomes; - type = boolean; - advanced = true; - default = false; - name = "Show All Test Outcomes (Experimental)"; - category = "Experimental Settings"; - description = - "Set to true to use the new (experimental) feature to show all test outcomes - instead of limited hints. Students still need to meet the coverage - requirements and other requirements to see test outcomes, but will see - the full table of tests instead of limited hints."; - }, - { - property = useFindBugs; - type = boolean; - advanced = true; - default = false; - name = "Use FindBugs (Experimental)"; - category = "Experimental Settings"; - description = - "Set to true to add FindBugs analysis to the static analysis scoring of - the assignment. This will cause FindBugs to be run on student submissions, - and the results will be used to give feedback to students. Not all FindBugs - warnings/errors will be shown--the specific list used is research-driven. - There currently are no controls for changing the scoring scheme or enabling - or disabling specific FindBugs checks."; - }, - { - property = usePit; - type = antBoolean; - advanced = true; - default = false; - name = "Use PIT Mutation Analysis (Experimental)"; - category = "Experimental Settings"; - description = - "Set to true to turn on mutation analysis for evaluating student-written - test suites. This is highly experimental and not advised for production - use except in research settings."; - }, - { - property = useEMRN; - type = antBoolean; - advanced = true; - default = false; - name = "Use EMRN Grading (Experimental)"; - category = "Experimental Settings"; - description = - "Set to true to turn on EMRN grading scale support instead of points."; - }, - { - property = useEMRNManual; - type = antBoolean; - advanced = true; - default = false; - name = "Use EMRN with Manual Grading (Experimental)"; - category = "Experimental Settings"; - description = - "Set to true when using EMRN to save the EMR distinctions for manual - grading, or leave false for EMRN with full auto-grading."; - }, - { - property = emrnExcellent; - type = integer; - advanced = true; - default = 100; - name = "EMRN Point Value - Excellent (Experimental)"; - category = "Experimental Settings"; - description = - "Set to the value to use for EMRN (E) scores (points, not percentage) - when not using manual grading."; - }, - { - property = emrnMeetsExpectations; - type = integer; - advanced = true; - default = 100; - name = "EMRN Point Value - Meets Expectations (Experimental)"; - category = "Experimental Settings"; - description = - "Set to the value to use for EMRN (M) scores (points, not percentage) - when not using manual grading."; - }, - { - property = emrnRevisionNeeded; - type = integer; - advanced = true; - default = 10; - name = "EMRN Point Value - Revision Needed (Experimental)"; - category = "Experimental Settings"; - description = - "Set to the value to use for EMRN (R) scores (points, not percentage) - when not using manual grading."; - }, - { - property = useJdk11; - type = boolean; - advanced = true; - default = false; - name = "Use Java 11 (Experimental)"; - category = "Experimental Settings"; - description = - "Set to true to switch to Java 11."; - } - ); - globalOptions = ( - { - property = doxygenDir; - type = shortText; - size = 40; - name = "Doxygen Directory"; - description = - "The directory on the local server that contains the Doxygen executable. - Doxygen (and Dot, below) are used to generate class diagrams for the code - that students submit; if you do not have a copy of Doxygen or wish to - disable diagram generation across all assignments, you can leave this - field blank. If you are not the user administering this Web-CAT server, - you will need to have your system administrator install this tool and set - this path if you wish to use it."; - }, - { - property = dotDir; - type = shortText; - size = 40; - name = "Dot Directory"; - description = - "The directory on the local server that contains the Dot executable (from - the Graphviz package). Dot (and Doxygen, above) are used to generate - class diagrams for the code that students submit; if you do not have a copy - of Dot or wish to disable diagram generation across all assignments, you can - leave this field blank. If you are not the user administering this Web-CAT - server, you will need to have your system administrator install this tool - and set this path if you wish to use it."; - } - ); -} +{ + name = "JavaTddPlugin"; + version.major = 4; + version.minor = 2; + version.revision = 0; + version.date = 20260526; + autoPublish = true; + requires = ( ANTForPlugins, PerlForPlugins, + PMDForPlugins, CheckstyleForPlugins ); + provider = "Virginia Tech Computer Science"; + provider.url = "http://web-cat.org/updates"; + license = "GNU Affero General Public License v.3"; + license.url = "http://www.gnu.org/licenses/agpl.html"; + copyright = + "(c) 2006-2026 Virginia Tech Department of Computer Science"; + info.url = "http://wiki.web-cat.org/WCWiki/JavaTddPlugin"; + history.url = + "http://wiki.web-cat.org/WCWiki/JavaTddPlugin/ChangeHistory"; + executable = execute.pl; + interpreter.prefix = "${PerlForPlugins.perl.exe}"; + author = "Stephen Edwards (edwards@cs.vt.edu)"; + authorUid = edwards; + languages = ( { name = Java; version = 1.14; } ); + description = "This \"all-in-one\" plug-in is designed to provide full + processing and feedback generation for Java assignments where + students write their own JUnit test cases. + It includes ANT-based compilation, JUnit processing of student-written + tests, support for instructor-written reference tests, PMD and + Checkstyle analysis, and Clover-based tracking of code coverage + during student testing."; + timeoutMultiplier = 2; + timeoutInternalPadding = 400; + assignmentOptions = ( + { + property = testCases; + type = fileOrDir; + fileTypes = ( java ); + name = "Hidden JUnit Reference Test Class(es)"; + description = + "A Java source file (or directory of source files) containing JUnit tests + to run against student code to assess completeness of problem coverage. + Test outcomes are not directly visible to students, an students only see + hints about what may be incorrect. + If you select a single Java file, it must contain a JUnit test class + declared in the default package. If you select a directory, it should + contain JUnit test classes arranged in subdirectories according to their + Java package declarations. If you make no selection, an empty set of + instructor reference tests will be used instead."; + }, +/* { + property = visibleTestCases; + type = fileOrDir; + fileTypes = ( java ); + name = "Visible JUnit Reference Test Class(es)"; + description = + "A Java source file (or directory of source files) containing JUnit tests + to run against student code to assess completeness of problem coverage. + \"Visible\" here means pass/fail information for every test is shown (not + limited by hint controls). + If you select a single Java file, it must contain a JUnit test class + declared in the default package. If you select a directory, it should + contain JUnit test classes arranged in subdirectories according to their + Java package declarations. If you make no selection, an empty set of + instructor reference tests will be used instead."; + }, +*/ { + property = assignmentJar; + type = fileOrDir; + fileTypes = ( jar ); + name = "Supplemental Classes for Assignment"; + description = + "A jar file (or a directory of class files in subdirs reflecting their + package structure, or a directory of multiple jar files) containing + precompiled classes to add to the classpath when compiling and running + submissions for this assignment. If you want to apply the same + jar settings to many assignments, use the \"Supplemental Classes\" setting + in the \"Reusable Configuration Options\" section instead. If you have + multiple jars to provide, place them all in the same directory in your + Web-CAT file space and then select the whole directory."; + }, + { + property = localFiles; + type = fileOrDir; + name = "Data Files for Student"; + description = + "A file (or a directory of files) to place in the student's current working + directory when running his/her tests and when running reference tests. The + file you select (or the entire contents of the directory you select) will be + copied into the current working directory during grading so that + student-written and instructor-written test cases can read and/or write to + the file(s). The default is to copy no files."; + }, + { + property = referenceImplementationJar; + type = fileOrDir; + fileTypes = ( jar ); + name = "Reference Implementation Jar File"; + description = + "A jar file containing a precompiled reference implementation for the + project to run against student tests to assess completeness of testing + coverage. Test outcomes are directly visible to students. This solution + is for this assignment only. If you have multiple jars to provide, + place them all in the same directory in your Web-CAT file space and then + select the whole directory."; + }, + { + property = testCaseValidationFileName; + type = shortText; + size = 40; + default = "ProblemSpecTest"; + name = "Test Case Validation File Name"; + description = + "Specify the java class name to use for test case validation."; + }, + { + property = coverageGoal; + type = double; + name = "Test Coverage Goal"; + category = "Basic Settings"; + description = + "If students are required to submit tests, this value is the target test + coverage threshold that must be achieved in order for students to receive + full credit. It should be a number between 0.0-100.0 representing the + minimum percent coverage required for full credit. The default is 100.0, + but a lower value may be used to allow students some slack in test coverage + when JaCoCo test coverage measures make achieving 100% too challenging."; + } + ); + optionCategories = ( + "Basic Settings", + "Advanced Settings", + "Experimental Settings", + "Developer Settings", + "Milestone Settings" + ); + options = ( + { + property = useAssertions; + type = boolean; + default = true; + name = "Use Java Assertions"; + category = "Basic Settings"; + description = + "Enable Java assertions during execution. When set to false, assertions + in student or instructor-provided code will be treated as non-executable + (no-op's)."; + }, + { + property = useDefaultJar; + type = boolean; + default = true; + name = "Use Built-in Jars"; + category = "Basic Settings"; + description = + "Set to true to have a set of built-in jars containing Virginia Tech + CS 1/CS 2 classes placed on the classpath for assignments. Set to + false to omit these jars from the classpath."; + }, + { + property = classpathJar; + type = fileOrDir; + fileTypes = ( jar ); + name = "Predefined Classes"; + category = "Basic Settings"; + description = + "A jar file (or a directory of class files in subdirs reflecting their + package structure, or a directory of multiple jar files) containing + precompiled classes to add to the classpath when compiling and running + submissions. Use this setting if you'd like to share the same jar(s) + across several assignments. If you have multiple jars to provide, + place them all in the same directory in your Web-CAT file space and + then select the whole directory."; + }, + { + property = useXvfb; + type = boolean; + default = false; + name = "Enable Xvfb During Test Execution"; + category = "Advanced Settings"; + description = + "This option is necessary for running GUI software tests on Linux servers. + It uses an instance of Xvfb, the X virtual frame buffer server, to run + unit tests so that GUI tests can render to a live X server. Note that + enabling this option will slow down test execution, since it takes time to + start up an X server, but it is required for GUI testing on a linux + server. Also, this option requires that Xvfb is already installed on + the server."; + }, + { + property = policyFile; + advanced = true; + type = file; + fileTypes = ( policy ); + name = "Java Security Policy"; + category = "Advanced Settings"; + description = + "A Java security policy file used to limit actions on student programs at + run-time. Leave unset to use the built-in default, which plugs most + security holes and prevents any file system access outside the subtree + rooted at the program's working directory."; + }, + { + property = remote.post.url; + advanced = true; + type = shortText; + size = 40; + name = "Remotely Post Submissions"; + category = "Advanced Settings"; + description = + "A URL to which submissions will be posted as they are processed, to + allow for external tools to receive student submissions. If a URL is + specified an HTML POST request will be sent to the given URL, with the + student's user name provided in the parameter 'user', and the student's + submission file provided in the parameter 'uploadedfile'."; + }, + { + property = "grader.partnerExcludePatterns"; + advanced = true; + type = shortText; + size = 40; + name = "Partner Name Exclude Patterns"; + category = "Basic Settings"; + description = + "The plug-in will automatically scan @author tags in source code + to try to identify the user names of partners when partners are allowed + on an assignment. Here, you can provide a comma-separated list of names + to exclude from consideration (e.g., the names of instructors, if some + instructor names are listed in @author lines in pre-provided code). + Full Perl-style regular expressions can be used if desired."; + }, + { + property = allStudentTestsMustPass; + type = boolean; + default = false; + name = "All Student Tests Must Pass"; + category = "Basic Settings"; + description = + "If you are truly following test-driven development practices, then no code + is ever released until all of its unit tests pass. If this option is set to + true, students will not receive a non-zero score or receive further + assessment feedback unless all student tests pass. If this option is not + set, then students may continue to proceed even if some student-written + tests fail The student's correctness/testing score is multiplied by the + proportion of their tests that pass."; + }, + { + property = studentsMustSubmitTests; + type = boolean; + default = true; + name = "Students Must Submit Tests"; + category = "Basic Settings"; + description = + "When set, this option requires all students to submit test cases for their + own code. Submissions without test cases will received feedback to that + effect (and no more), as well as a zero score. If you unset this option, + then student submissions will not be required to include + student-written test cases, and only the reference test pass rate + will be used for scoring (i.e., student code coverage and student test pass + rate will not be included in scoring)."; + }, + { + property = includeStudentTestsInGrading; + type = boolean; + default = true; + name = "Include Student Test Results in Grading"; + category = "Basic Settings"; + description = + "When set, if students are required to submit tests, they are also included + in the scoring formula. When false, student test pass/fail ressults are + not included in the score calculation."; + }, + { + property = coverageMetric; + advanced = true; + type = radioChoice; + name = "Test Coverage Metric"; + category = "Basic Settings"; + default = 0; + description = "Choose the criterion used to measure how thoroughly + a student's tests cover the corresponding code."; + choices = ( { label = "Methods executed"; value = 0; }, + { label = "Lines executed"; value = 1; }, + { label = "Methods + conditions executed"; + value = 2; }, + { label = "Lines + conditions executed"; + value = 3; }, + { label = "Methods + lines + conditions executed"; + value = 4; } + ); + }, + { + property = includeTestSuitesInCoverage; + type = boolean; + default = false; + name = "Include Student Test Code in Coverage Measures"; + category = "Basic Settings"; + description = + "Normally, this plug-in excludes student-written tests from all coverage + calculations, since the goal of the testing is to test the solution, not + to execute more tests. When this option is set, student-written tests + will be included in code coverage measures for the purposes of scoring, + meaning that students will have to execute all of the code in their + test classes."; + }, + { + property = requireSimpleExceptionCoverage; + type = boolean; + default = false; + name = "Require Coverage of Simple Catch Blocks"; + category = "Basic Settings"; + description = + "When set, this option requires students to test all catch blocks, including + simple try/catch statements that are provided purely for compiler compliance + and that simply print a stack trace or re-throw the exception. If unchecked, + catch blocks that contain only a statement to print the stack trace or + re-throw a wrapped version of the exception are not counted in + coverage measurements, and do not result in point deductions."; + }, + { + property = requireSimpleGetterSetterCoverage; + type = boolean; + default = false; + name = "Require Coverage of Simple Getters and Setters"; + category = "Basic Settings"; + description = + "When set, this option requires students to test all simple getter and + setter methods. A simple getter is a method whose name starts with + \"get\", and whose body simply returns a field value. A simple setter is + a void method whose name starts with \"set\" accepting one parameter, and + whose body simply assigns that parameter to a field. If unchecked, + simple getters and setters are not counted in coverage measurements, and + do not result in point deductions."; + }, +/* + { + property = "clover.includes"; + type = shortText; + size = 40; + default = "**"; + name = "Classes to Include in Coverage Measures"; + category = "Basic Settings"; + description = + "Specify the Java file names that should be included in Clover coverage + analysis. Only student class files with names that match the patterns you + list here will be processed by Clover. Patterns are + case-insensitive. Use * as a wildcard character (ANT-style pattern + matching is used)."; + }, + { + property = "clover.excludes"; + type = shortText; + size = 40; + default = "none"; + name = "Classes to Exclude from Coverage Measures"; + category = "Basic Settings"; + description = + "Specify Java file names that should not be processed by + Clover. Any classes that match the \"Classes to Include in Coverage + Measures\" above and also match the patterns you list here + will not be processed by Clover. Patterns are + case-insensitive. Use * as a wildcard character (ANT-style pattern + matching is used). Use \"none\" if you do not wish to use any + exclusion patterns."; + }, +*/ + { + property = studentTestInclude; + type = shortText; + size = 40; + default = "*test *tests"; + name = "Students Test Class Patterns"; + category = "Basic Settings"; + description = + "Specify the Java class names that should be treated as JUnit-style + test cases. Only student classes with names that match the patterns you + list here will be executed as test cases. Patterns are case-insensitive. + Use * as a wildcard character (ANT-style pattern matching is used)."; + }, + { + property = studentTestExclude; + type = shortText; + size = 40; + default = "abstract* *$*"; + name = "Students Test Class Exclusion Patterns"; + category = "Basic Settings"; + description = + "Specify Java class names that should not be treated as JUnit-style + test cases. Any classes that match the \"Student Test Class Patterns\" + above and also match the patterns you list here + will not be treated as executable test cases. Patterns are + case-insensitive. Use * as a wildcard character (ANT-style pattern matching + is used). Use \"none\" if you do not wish to use any exclusion patterns."; + }, + { + property = refTestInclude; + type = shortText; + size = 40; + default = "*"; + name = "Reference Test Class Patterns"; + category = "Basic Settings"; + description = + "Specify the Java class names that should be treated as JUnit-style + test cases when selected as reference tests by an instructor. This + setting is only relevant when an instructor selects an entire directory + or folder of Java classes. In that case, only instructor reference classes + with names that match the patterns you list here will be executed as test + cases. Patterns are case-insensitive. Use * as a wildcard character + (ANT-style pattern matching is used)."; + }, + { + property = refTestExclude; + type = shortText; + size = 40; + default = "abstract* *$*"; + name = "Reference Test Class Exclusion Patterns"; + category = "Basic Settings"; + description = + "Specify Java class names that should not be treated as JUnit-style + test cases when selected as reference tests by an instructor. This + setting is only relevant when an instructor selects an entire directory or + folder of Java classes. In that case, any classes that match the + \"Reference Test Class Patterns\" above and also match the + patterns you list here will not be treated as executable test cases. + Patterns are case-insensitive. Use * as a wildcard character (ANT-style + pattern matching is used)."; + }, + { + property = student.testingsupport.junit4.AdaptiveTimeout.ceiling; + advanced = true; + type = integer; + name = "Default Test Case Time Limit (in ms)"; + category = "Basic Settings"; + description = + "This plug-in provides built-in adaptive detection and termination of + infinite loops that occur within individual test methods. This setting + controls the default timeout before a single test case method is judged as + \"taking too long\", although this amount will be gradually increased up + to a higher maximum value if test methods terminate but come close to + this limit. The default if unset is ten seconds (10000 ms)."; + }, + { + property = student.testingsupport.junit4.AdaptiveTimeout.maximum; + advanced = true; + type = integer; + name = "Default Test Case Maximum Time (in ms)"; + category = "Basic Settings"; + description = + "This plug-in provides built-in adaptive detection and termination of + infinite loops that occur within individual test methods. This setting + controls the maximum allowable timeout before a single test case is judged + as \"taking too long\". The default if unset is twenty seconds (20000 ms)."; + }, + { + property = disableCheckstyle; + type = antBoolean; + name = "Turn Checkstyle Off"; + category = "Basic Settings"; + description = + "Disable Checkstyle for static analysis entirely (no need to upload a + separate configuration file to turn it off)."; + }, + { + property = checkstyleConfig; + advanced = true; + type = file; + fileTypes = ( xml ); + name = "Checkstyle Configuration"; + category = "Basic Settings"; + description = + "An XML file containing a Checkstyle rule configuration (see the + Checksyle + documentation). This plug-in uses Checkstyle v5.6. If you would + like to turn off all Checkstyle checks entirely, use the \"Turn + Checkstyle Off\" option instead."; + }, + { + property = disablePmd; + type = antBoolean; + name = "Turn PMD Off"; + category = "Basic Settings"; + description = + "Disable PMD for static analysis entirely (no need to upload a + separate configuration file to turn it off)."; + }, + { + property = pmdConfig; + advanced = true; + type = file; + fileTypes = ( xml ); + name = "PMD Configuration"; + category = "Basic Settings"; + description = + "An XML file containing a set of PMD rules (see the + PMD + documentation). This plug-in uses PMD v5.0.5. If you owuld like to + turn off all PMD checks entirely, use the \"Turn PMD Off\" options instead."; + }, + { + property = use.comtor; + type = antBoolean; + name = "Run COMTOR Comment Analyzer"; + category = "Experimental Settings"; + description = + "Set to true to run the COMTOR Comment Analyzer and include the results + as part of the overall feedback report."; + }, + { + property = staticAnalysisInclude; + type = shortText; + size = 40; + default = "*"; + name = "Classes to Analyze"; + category = "Basic Settings"; + description = + "Specify the Java class names that should be included in Checkstyle and + PMD analysis. Only student classes with names that match the patterns you + list here will be processed by Checkstyle and PMD. Patterns are + case-insensitive. Use * as a wildcard character (ANT-style pattern + matching is used)."; + }, + { + property = staticAnalysisExclude; + type = shortText; + size = 40; + default = "none"; + name = "Classes to Exclude from Analysis"; + category = "Basic Settings"; + description = + "Specify Java class names that should not be processed by + Checkstyle or PMD. Any classes that match the \"Classes to Analyze\" + above and also match the patterns you list here + will not be processed by Checkstyle or PMD. Patterns are + case-insensitive. Use * as a wildcard character (ANT-style pattern + matching is used). Use \"none\" if you do not wish to use any + exclusion patterns."; + }, + { + property = markupProperties; + advanced = true; + type = file; + fileTypes = ( properties ); + name = "Static Analysis Scoring Scheme"; + category = "Advanced Settings"; + description = + "A Java properties file containing the point deductions and limits to + use for messages generated by Checkstyle or PMD. The point deductions + are specified in a fairly generic way so they can be used for many + assignments. Deductions in the default scheme are typically 1, 2, or 5 + 'points', which are really simply relative weights. Specify a scaling + factor below to adjust how these weights are translated into point + deductions for a student."; + }, + { + property = toolDeductionScaleFactor; + advanced = true; + type = double; + name = "Static Analysis Deduction Scaling Factor"; + category = "Advanced Settings"; + description = + "The Static Analysis Scoring Scheme above defines the point deductions + and limits to use for messages generated by Checkstyle or PMD in a generic + way, with most deductions in the default scheme being 1, 2, or 5 points. + Deductions in the static analysis scoring scheme are multiplied by this + factor to translate them into actual 'point deductions' shown to the + student."; + }, + { + property = hintsLimit; + type = integer; + default = 3; + name = "Hints Limit"; + category = "Basic Settings"; + description = + "Maximum number of hints the student will receive from failed reference + tests."; + }, + { + property = minCoverageLevel; + type = double; + name = "Minimum Test Coverage for Hints"; + category = "Basic Settings"; + description = + "If students are required to submit tests, this value is a minimum test + coverage threshold that must be achieved in order for any hints to be + given. It should be a number between 0.0-100.0 representing the minimum + percent coverage required to see hints."; + }, + { + property = junitErrorsHideHints; + type = boolean; + default = false; + name = "Clean JUnit Tests Required for Hints"; + category = "Basic Settings"; + description = + "If students are required to submit tests, this option requires all test + case classes to be free of PMD-based JUnit style errors, such as failing + to include at least one test method in each test case class, failing + to include assert*() calls in each test case method, or using \"bogus\" + assertions such as assertEquals(1, 1)."; + }, + { + property = hideHintsWithin; + advanced = true; + type = integer; + default = 0; + name = "Hide Hints X Days Before Deadline"; + category = "Advanced Settings"; + description = + "Suppress all hints from failed reference tests for submissions within this + many days of the deadline (set to zero for hints to always be visible). + This setting allows the instructor to \"hide\" hints close to the assignment + deadline in an attempt to encourage students to start working earlier."; + }, + { + property = showHintsWithin; + advanced = true; + type = integer; + default = 0; + name = "Show Hints X Days Before Deadline"; + category = "Advanced Settings"; + description = + "Show hints (up to the Hints Limit) from failed reference tests for + submissions within this many days of the deadline (only useful when Hide + Hints X Days Before Deadline is non-zero, to restore hints as the + deadline approaches)."; + }, + { + property = wantPDF; + type = boolean; + default = false; + name = "Generate PDF Printouts"; + category = "Basic Settings"; + description = + "Set to true if you wish for a single PDF file containing a pretty-printed + source code printout to be generated from the student's code. The printout + will be downloadable by students, and accessible by TAs during grading. + Note: This option uses both enscript and + ps2pdf as external commands, and requires these programs to + be correctly installed and configured."; + }, +/* + { + property = enscriptStyle; + type = shortText; + size = 15; + default = "msvc"; + name = "PDF Formatting Style (for Enscript)"; + category = "Basic Settings"; + description = + "If you are generating PDF printouts, you can specify the formatting style + used by enscript. This name will be passed to + enscript using its --style= parameter. See your + enscript documentation for more information about the styles that are + supported. Many enscript installations support the following styles: + a2ps, emacs, emacs-verbose, + ifh, and msvc. It is possible to add your + own custom formatting definitions to your enscript installation and then + use your own style name here as well."; + }, +*/ + { + property = wantClassDiagrams; + type = boolean; + default = true; + name = "Generate Class Diagrams"; + category = "Basic Settings"; + description = + "Set to true if you wish to generate class diagrams from students' code. + The diagrams will be viewable by students, and accessible by TAs during + grading. Note: This option uses both doxygen and + dot as external commands, and requires these programs to + be correctly installed and configured in the JavaTddPlugin's global + configuration options."; + }, + { + property = debug; + type = integer; + advanced = true; + default = 0; + name = "Debug Level"; + category = "Developer Settings"; + description = + "Set to a non-zero value for the script to produce debugging output (the + larger the number, the greater the detail, up to about 5). Debugging output + on each grading script run will be e-mailed to the instructor."; + }, + { + property = doNotDelete; + type = antBoolean; + advanced = true; + name = "Preserve Derived Files"; + category = "Developer Settings"; + description = + "Set to true to prevent the plug-in from deleting the derived files it + creates during the build/test process for each submission. Normally, these + files are deleted when a given submission has been completely processed. + This setting is provided for debugging purposes, when one wishes to + inspect the intermediate test driver source code or other derived files."; + }, + { + property = generateHeatmaps; + type = antBoolean; + advanced = true; + name = "Generate Bug Heatmaps"; + category = "Experimental Settings"; + description = + "Set to true to generate GZoltar-based defect heatmaps. This option is + experimental and for research use only. Using it will slow down + generation of student feedback."; + }, + { + property = useEnhancedFeedback; + type = boolean; + advanced = true; + default = false; + name = "Use Enhanced Feedback (Experimental)"; + category = "Experimental Settings"; + description = + "Set to true to use the new (experimental) enhanced feedback layout."; + }, + { + property = useIndicatorFeedback; + type = boolean; + advanced = true; + default = false; + name = "Use Growth Mindset Feedback (Experimental)"; + category = "Experimental Settings"; + description = + "Set to true to use the new (experimental) growth mindset progress feedback."; + }, + { + property = useMaria; + type = boolean; + advanced = true; + default = false; + name = "Use Maria (Experimental)"; + category = "Experimental Settings"; + description = + "Set to true to show Maria (experimental), the virtual teaching assistant + chatbot."; + }, + { + property = useMariaExplanations; + type = boolean; + advanced = true; + default = false; + name = "Use Maria Explanations (Experimental)"; + category = "Experimental Settings"; + description = + "Set to true to show \"Explain...\" links (experimental) by error messages."; + }, + { + property = useDailyMissions; + type = boolean; + advanced = true; + default = false; + name = "Use Daily Missions (Experimental)"; + category = "Experimental Settings"; + description = + "Set to true to give students daily mission challenges (experimental)."; + }, + { + property = showAllTestOutcomes; + type = boolean; + advanced = true; + default = false; + name = "Show All Test Outcomes (Experimental)"; + category = "Experimental Settings"; + description = + "Set to true to use the new (experimental) feature to show all test outcomes + instead of limited hints. Students still need to meet the coverage + requirements and other requirements to see test outcomes, but will see + the full table of tests instead of limited hints."; + }, + { + property = useFindBugs; + type = boolean; + advanced = true; + default = false; + name = "Use FindBugs (Experimental)"; + category = "Experimental Settings"; + description = + "Set to true to add FindBugs analysis to the static analysis scoring of + the assignment. This will cause FindBugs to be run on student submissions, + and the results will be used to give feedback to students. Not all FindBugs + warnings/errors will be shown--the specific list used is research-driven. + There currently are no controls for changing the scoring scheme or enabling + or disabling specific FindBugs checks."; + }, + { + property = usePit; + type = antBoolean; + advanced = true; + default = false; + name = "Use PIT Mutation Analysis (Experimental)"; + category = "Experimental Settings"; + description = + "Set to true to turn on mutation analysis for evaluating student-written + test suites. This is highly experimental and not advised for production + use except in research settings."; + }, + { + property = useEMRN; + type = antBoolean; + advanced = true; + default = false; + name = "Use EMRN Grading (Experimental)"; + category = "Experimental Settings"; + description = + "Set to true to turn on EMRN grading scale support instead of points."; + }, + { + property = useEMRNManual; + type = antBoolean; + advanced = true; + default = false; + name = "Use EMRN with Manual Grading (Experimental)"; + category = "Experimental Settings"; + description = + "Set to true when using EMRN to save the EMR distinctions for manual + grading, or leave false for EMRN with full auto-grading."; + }, + { + property = emrnExcellent; + type = integer; + advanced = true; + default = 100; + name = "EMRN Point Value - Excellent (Experimental)"; + category = "Experimental Settings"; + description = + "Set to the value to use for EMRN (E) scores (points, not percentage) + when not using manual grading."; + }, + { + property = emrnMeetsExpectations; + type = integer; + advanced = true; + default = 100; + name = "EMRN Point Value - Meets Expectations (Experimental)"; + category = "Experimental Settings"; + description = + "Set to the value to use for EMRN (M) scores (points, not percentage) + when not using manual grading."; + }, + { + property = emrnRevisionNeeded; + type = integer; + advanced = true; + default = 10; + name = "EMRN Point Value - Revision Needed (Experimental)"; + category = "Experimental Settings"; + description = + "Set to the value to use for EMRN (R) scores (points, not percentage) + when not using manual grading."; + }, + { + property = useJdk11; + type = boolean; + advanced = true; + default = false; + name = "Use Java 11 (Experimental)"; + category = "Experimental Settings"; + description = + "Set to true to switch to Java 11."; + }, + { + property = useTestCaseValidation; + type = antBoolean; + advanced = true; + default = false; + name = "Run student test cases against reference implementation (Experimental)"; + category = "Developer Settings"; + description = + "Set to true to turn on test case validation for running student-written + test suites against reference implementations."; + }, + { + property = showTestCaseValidation; + type = antBoolean; + advanced = true; + default = false; + name = "Show students their test cases against the reference implementation (Experimental)"; + category = "Developer Settings"; + description = + "Set to true to show students test case validation for running student-written + test suites against reference implementations."; + }, + { + property = includeValidationInGrading; + type = antBoolean; + advanced = true; + default = false; + name = "Include Test Validation Results in Grading"; + category = "Developer Settings"; + description = + "When set, students grade for test case validation will be included in + the scoring formula. When false, student test validation results are + not included in the score calculation."; + }, + { + property = maxValidationPenalty; + type = integer; + advanced = true; + default = 10; + name = "Max Validation Penalty"; + category = "Developer Settings"; + description = + "Set the maximum penalty that can be applied for test case validation failures."; + }, + { + property = validationTestsRequired; + type = integer; + advanced = true; + default = 10; + name = "Test Cases Required for Validation"; + category = "Developer Settings"; + description = + "Set the minimum number of test cases that must be submitted for test case + validation."; + }, + { + property = validationFailuresAllowed; + type = integer; + advanced = true; + default = 0; + name = "Test Case Validation Failures Allowed"; + category = "Developer Settings"; + description = + "Set the maximum number of test case validation failures allowed."; + }, + { + property = milestonePassed.1; + type = boolean; + default = false; + name = "Milestone 1 Passed"; + category = "Milestone Settings"; + description = + "If milestone 1 had already been passed."; + }, + { + property = milestoneDueDate.1; + type = integer; + default = 0; + size = 40; + name = "Milestone 1 Due Date (YYYYMMDD)"; + category = "Milestone Settings"; + description = + "The milestone check automatically activates for submissions made before + this date. Use ISO format YYYYMMDD. Leave blank to disable milestone checks."; + }, + { + property = milestoneDueTime.1; + type = integer; + default = 0; + size = 40; + name = "Milestone 1 Time Due (HHMMSS)"; + category = "Milestone Settings"; + description = + "The milestone check automatically activates for submissions made before + this time. Use format HHMMSS."; + }, + { + property = milestoneMinStudentTests.1; + type = integer; + default = 0; + name = "Minimum Student Tests for Milestone"; + category = "Milestone Settings"; + description = + "Minimum number of student-written JUnit tests required before the milestone due date."; + }, + { + property = milestoneMinRefTests.1; + type = integer; + default = 0; + name = "Minimum Reference Tests for Milestone"; + category = "Milestone Settings"; + description = + "Minimum percentage of Reference tests required before the milestone due date."; + }, + { + property = milestoneStyleMin.1; + type = integer; + default = 0; + name = "Minimum Style Score for Milestone"; + category = "Milestone Settings"; + description = + "Minimum passing style score required before the milestone due date."; + }, + { + property = milestoneMinMutationCoverage.1; + type = integer; + default = 0; + name = "Minimum Mutation Coverage Student Tests for Milestone"; + category = "Milestone Settings"; + description = + "Minimum mutation coverage required before the milestone due date."; + }, + { + property = milestonePassed.2; + type = boolean; + default = false; + name = "Milestone 2 Passed"; + category = "Milestone Settings"; + description = + "If milestone 2 has been passed."; + }, + { + property = milestoneDueDate.2; + type = integer; + default = 0; + size = 40; + name = "Milestone 2 Due Date (YYYYMMDD)"; + category = "Milestone Settings"; + description = + "The milestone check automatically activates for submissions made before + this date. Use ISO format YYYYMMDD. Leave blank to disable milestone checks."; + }, + { + property = milestoneDueTime.2; + type = integer; + default = 0; + size = 40; + name = "Milestone 1 Time Due (HHMMSS)"; + category = "Milestone Settings"; + description = + "The milestone check automatically activates for submissions made before + this time. Use format HHMMSS."; + }, + { + property = milestoneMinStudentTests.2; + type = integer; + default = 0; + name = "Minimum Student Tests for Milestone"; + category = "Milestone Settings"; + description = + "Minimum number of student-written JUnit tests required before the milestone due date."; + }, + { + property = milestoneMinRefTests.2; + type = integer; + default = 0; + name = "Minimum Reference Tests for Milestone"; + category = "Milestone Settings"; + description = + "Minimum percentage of Reference tests required before the milestone due date."; + }, + { + property = milestoneStyleMin.2; + type = integer; + default = 0; + name = "Minimum Style Score for Milestone"; + category = "Milestone Settings"; + description = + "Minimum passing style score required before the milestone due date."; + }, + { + property = milestoneMinMutationCoverage.2; + type = integer; + default = 0; + name = "Minimum Mutation Coverage Student Tests for Milestone"; + category = "Milestone Settings"; + description = + "Minimum mutation coverage required before the milestone due date."; + }, + { + property = milestonePassed.3; + type = boolean; + default = false; + name = "Milestone 3 Passed"; + category = "Milestone Settings"; + description = + "If milestone 3 has been passed"; + }, + { + property = milestoneDueDate.3; + type = integer; + default = 0; + size = 40; + name = "Milestone 3 Due Date (YYYYMMDD)"; + category = "Milestone Settings"; + description = + "The milestone check automatically activates for submissions made before + this date. Use ISO format YYYYMMDD. Leave blank to disable milestone checks."; + }, + { + property = milestoneDueTime.3; + type = integer; + default = 0; + size = 40; + name = "Milestone 1 Time Due (HHMMSS)"; + category = "Milestone Settings"; + description = + "The milestone check automatically activates for submissions made before + this time. Use format HHMMSS."; + }, + { + property = milestoneMinStudentTests.3; + type = integer; + default = 0; + name = "Minimum Student Tests for Milestone"; + category = "Milestone Settings"; + description = + "Minimum number of student-written JUnit tests required before the milestone due date."; + }, + { + property = milestoneMinRefTests.3; + type = integer; + default = 0; + name = "Minimum Reference Tests for Milestone"; + category = "Milestone Settings"; + description = + "Minimum percentage of Reference tests required before the milestone due date."; + }, + { + property = milestoneStyleMin.3; + type = integer; + default = 0; + name = "Minimum Style Score for Milestone"; + category = "Milestone Settings"; + description = + "Minimum passing style score required before the milestone due date."; + }, + { + property = milestoneMinMutationCoverage.3; + type = integer; + default = 0; + name = "Minimum Mutation Coverage Student Tests for Milestone"; + category = "Milestone Settings"; + description = + "Minimum mutation coverage required before the milestone due date."; + } + ); + globalOptions = ( + { + property = doxygenDir; + type = shortText; + size = 40; + name = "Doxygen Directory"; + description = + "The directory on the local server that contains the Doxygen executable. + Doxygen (and Dot, below) are used to generate class diagrams for the code + that students submit; if you do not have a copy of Doxygen or wish to + disable diagram generation across all assignments, you can leave this + field blank. If you are not the user administering this Web-CAT server, + you will need to have your system administrator install this tool and set + this path if you wish to use it."; + }, + { + property = dotDir; + type = shortText; + size = 40; + name = "Dot Directory"; + description = + "The directory on the local server that contains the Dot executable (from + the Graphviz package). Dot (and Doxygen, above) are used to generate + class diagrams for the code that students submit; if you do not have a copy + of Dot or wish to disable diagram generation across all assignments, you can + leave this field blank. If you are not the user administering this Web-CAT + server, you will need to have your system administrator install this tool + and set this path if you wish to use it."; + } + ); +} diff --git a/src/execute.pl b/src/execute.pl index adbcced..a048f9c 100644 --- a/src/execute.pl +++ b/src/execute.pl @@ -23,6 +23,7 @@ use Web_CAT::JUnitResultsReader; use XML::Smart; use Data::Dump qw(dump); +use Time::Local; #============================================================================= @@ -87,6 +88,7 @@ my $pid = $cfg->getProperty('userName'); my $workingDir = $cfg->getProperty('workingDir'); my $resultDir = $cfg->getProperty('resultDir'); +my $solutionDir= $cfg->getProperty('solutionDir'); #Using ResultDir in ErrorMapper file and we set the value here setResultDir($resultDir); @@ -110,6 +112,20 @@ my $usePit = $cfg->getProperty('usePit', 0); $usePit = ($usePit =~ m/^(true|on|yes|y|1)$/i); if ($usePit) { $cfg->setProperty('enablePit', 'true'); } +my $useTestCaseValidation = $cfg->getProperty('useTestCaseValidation', 0); +$useTestCaseValidation = ($useTestCaseValidation =~ m/^(true|on|yes|y|1)$/i); +if ($useTestCaseValidation) { $cfg->setProperty('enableTestCaseValidation', 'true'); } +my $showTestCaseValidation = $cfg->getProperty('showTestCaseValidation', 0); +$showTestCaseValidation = ($showTestCaseValidation =~ m/^(true|on|yes|y|1)$/i); +if ($showTestCaseValidation) { $cfg->setProperty('showTestCaseValidation', 'true'); } +my $testCaseValidationFileName = $cfg->getProperty('testCaseValidationFileName', 'ProblemSpecTest'); +if ($useTestCaseValidation) { $cfg->setProperty('testCaseValidationFileName', $testCaseValidationFileName); } +my $maxValidationPenalty = $cfg->getProperty('maxValidationPenalty', 10); +if ($maxValidationPenalty) { $cfg->setProperty('maxValidationPenalty', $maxValidationPenalty); } +my $validationTestsRequired = $cfg->getProperty('validationTestsRequired', 0); +if ($validationTestsRequired) { $cfg->setProperty('validationTestsRequired', $validationTestsRequired); } +my $validationFailuresAllowed = $cfg->getProperty('validationFailuresAllowed', 0); +if ($validationFailuresAllowed) { $cfg->setProperty('validationFailuresAllowed', $validationFailuresAllowed); } my $useEMRN = $cfg->getProperty('useEMRN', 0); $useEMRN = ($useEMRN =~ m/^(true|on|yes|y|1)$/i); my $useEMRNManual = $cfg->getProperty('useEMRNManual', 0); @@ -137,6 +153,9 @@ #my $instructorCasesPassed = undef; my $instructorCasesPercent = 0; my $studentCasesPercent = 0; +my $validateCasesPercent = 0; +my $validationPenalty = 0; +my $printableValidationPenalty = 0; my $codeCoveragePercent = 0; #my $studentTestMsgs; my $hasJUnitErrors = 0; @@ -146,6 +165,7 @@ 'studentHasSrcs' => 0, 'studentTestResults' => undef, 'instrTestResults' => undef, + 'validateTestResults'=> undef, 'toolDeductions' => 0, 'compileMsgs' => "", 'compileErrs' => 0, @@ -179,6 +199,7 @@ 'whitespace' => 1, 'lineLength' => 1, 'other' => 1, + 'pointsGained' => 0, 'pointsGainedPercent' => 100 ); @@ -201,6 +222,8 @@ 'problemCoveragePercent' => 100 ); +my @milestoneResults; + # A limit for number of errors in a subcategory in the feedback. # Example: codingFlaws is a subcategory. my $maxErrorsPerSubcategory = 8; @@ -338,6 +361,117 @@ 'outOfMemoryErrors' => undef ); +#============================================================================= +# Multiple Milestone Settings +#============================================================================= + +my $MAX_MILESTONES = 3; # Maximum number of milestones to check for +my @milestoneDueDatesTimestamps = (); +my @milestoneMinStudentTests = (); +my @milestoneMinRefTests = (); +my @milestoneStyleMins = (); +my @milestoneMinMutationCoverages = (); +my @milestoneNumbers = (); +my $milestoneCount = 0; + +sub milestoneHasConfiguredRequirements +{ + my ($dueDateProp, $dueTimeProp, $studentTestsProp, $refTestsProp, + $styleProp, $coverageProp) = @_; + + return 1 if (defined $dueDateProp && $dueDateProp ne '' && $dueDateProp ne '0'); + return 1 if (defined $dueTimeProp && $dueTimeProp ne '' && $dueTimeProp ne '0'); + return 1 if (defined $studentTestsProp && $studentTestsProp ne '' && $studentTestsProp ne '0'); + return 1 if (defined $refTestsProp && $refTestsProp ne '' && $refTestsProp ne '0'); + return 1 if (defined $styleProp && $styleProp ne '' && $styleProp ne '0'); + return 1 if (defined $coverageProp && $coverageProp ne '' && $coverageProp ne '0'); + + return 0; +} + +sub formatTimestampForDisplay +{ + my ($timestampMillis) = @_; + + return 'Unknown' unless defined $timestampMillis && $timestampMillis ne ''; + return 'Unknown' unless $timestampMillis =~ /^\d+$/; + + my $timestampSeconds = int($timestampMillis / 1000); + my @timeParts = localtime($timestampSeconds); + return sprintf('%04d-%02d-%02d %02d:%02d:%02d', + $timeParts[5] + 1900, + $timeParts[4] + 1, + $timeParts[3], + $timeParts[2], + $timeParts[1], + $timeParts[0]); +} + +# Dynamically read properties for milestones +for (my $i = 1; $i <= $MAX_MILESTONES; $i++) +{ + my $dueDateProp = $cfg->getProperty("milestoneDueDate.$i"); + my $dueTimeProp = $cfg->getProperty("milestoneDueTime.$i"); + my $studentTestsProp = $cfg->getProperty("milestoneMinStudentTests.$i"); + my $refTestsProp = $cfg->getProperty("milestoneMinRefTests.$i"); + my $styleProp = $cfg->getProperty("milestoneStyleMin.$i"); + my $coverageProp = $cfg->getProperty("milestoneMinMutationCoverage.$i"); + + my $hasMilestone = milestoneHasConfiguredRequirements( + $dueDateProp, $dueTimeProp, $studentTestsProp, + $refTestsProp, $styleProp, $coverageProp); + next unless $hasMilestone; + + my $epochSeconds = 0; + my $rawIntDate = defined $dueDateProp ? $dueDateProp : 0; + if (defined $rawIntDate && $rawIntDate =~ m/^\d{8}$/) + { + my $year = int($rawIntDate / 10000); + my $month = int(($rawIntDate % 10000) / 100); + my $day = $rawIntDate % 100; + + # milestoneDueTime is HHMMSS; default to 23:59:59 when omitted/invalid. + my $rawDueTime = defined $dueTimeProp ? $dueTimeProp : 235959; + if (!defined($rawDueTime) || $rawDueTime !~ m/^\d{1,6}$/) + { + $rawDueTime = 235959; + } + $rawDueTime = sprintf("%06d", $rawDueTime); + my ($hour, $minute, $second) = $rawDueTime =~ m/^(\d{2})(\d{2})(\d{2})$/; + + $epochSeconds = eval { + timelocal($second, $minute, $hour, $day, $month - 1, $year - 1900); + }; + $epochSeconds = 0 if $@ || !defined($epochSeconds); + } + + # Store milestones densely at 0-based indices for consistent access. + my $idx = $milestoneCount; + $milestoneDueDatesTimestamps[$idx] = $epochSeconds * 1000; + $milestoneMinStudentTests[$idx] = defined $studentTestsProp ? $studentTestsProp : 0; + $milestoneMinRefTests[$idx] = defined $refTestsProp ? $refTestsProp : 0; + $milestoneStyleMins[$idx] = defined $styleProp ? $styleProp : 0; + $milestoneMinMutationCoverages[$idx] = defined $coverageProp ? $coverageProp : 0; + $milestoneNumbers[$idx] = $i; + + $milestoneCount++; +} + +# Check which milestones have been passed +my @milestoneAlreadyPassed = (); + +for (my $i = 0; $i < $milestoneCount; $i++) { + my $mNum = $milestoneNumbers[$i]; + + # Read property from config file + my $status = $cfg->getProperty("milestonePassed.$mNum", 'false'); + + if ($status =~ m/^(true|on|yes|y|1)$/i) { + $milestoneAlreadyPassed[$i] = 1; # Mark as passed in local array + } else { + $milestoneAlreadyPassed[$i] = 0; + } +} #------------------------------------------------------- # In addition, some local definitions within this script @@ -418,6 +552,10 @@ $cfg->getProperty('includeStudentTestsInGrading', 0); $includeStudentTestsInGrading = ($includeStudentTestsInGrading =~ m/^(true|on|yes|y|1)$/i); +my $includeValidationInGrading = + $cfg->getProperty('includeValidationInGrading', 0); +$includeValidationInGrading = + ($includeValidationInGrading =~ m/^(true|on|yes|y|1)$/i); my $studentsMustSubmitTests = $cfg->getProperty('studentsMustSubmitTests', 0); $studentsMustSubmitTests = @@ -745,6 +883,19 @@ sub setClassPatternIfNeeded } } +# referenceImplementationJar +{ + my $jarFileOrDir = $cfg->getProperty('referenceImplementationJar'); + if (defined $jarFileOrDir && $jarFileOrDir ne "") + { + my $path = confirmExists($scriptData, $jarFileOrDir); + $cfg->setProperty('referenceImplementationClassFiles', $path); + if (-d $path) + { + $cfg->setProperty('referenceImplementationClassDir', $path); + } + } +} # timeout my $timeoutForOneRun = $cfg->getProperty('timeoutForOneRun', 30); @@ -1284,6 +1435,8 @@ sub addCannotFindSymbolStruct new Web_CAT::JUnitResultsReader("$resultDir/student.inc"); $status{'instrTestResults'} = new Web_CAT::JUnitResultsReader("$resultDir/instr.inc"); + $status{'validateTestResults'} = + new Web_CAT::JUnitResultsReader("$resultDir/validate.inc"); foreach my $class ($status{'studentTestResults'}->suites) { @@ -1662,7 +1815,7 @@ sub trackMessageInstance print $msg; } } - + if ($group eq "suppress") { return; @@ -1998,7 +2151,7 @@ sub trackMessageInstance } $msg = htmlEscape($msg); - # highlight variable name, if there is one + # highlight variable name, if there is one my $v = $bug->{LocalVariable}{Message}; if (!$v->null) { @@ -2015,7 +2168,7 @@ sub trackMessageInstance } } - # highlight method name, if there is one + # highlight method name, if there is one my $method = $bug->{Method}{Message}; if (!$method->null) { @@ -2045,13 +2198,13 @@ sub trackMessageInstance } my $fileName = ''; - $bug->{beginline} = + $bug->{beginline} = $bug->{SourceLine}{start}->content || $bug->{Method}{SourceLine}{start}->content || $bug->{Field}{SourceLine}{start}->content || $bug->{Class}{SourceLine}{start}->content || 1; - $bug->{endline} = + $bug->{endline} = $bug->{SourceLine}{end}->content || $bug->{Method}{SourceLine}{end}->content || $bug->{Field}{SourceLine}{end}->content @@ -2178,11 +2331,14 @@ sub trackMessageInstance # set PointsGained in Style section color the radial bar if ($maxToolScore > 0) { + $styleSectionStatus{'pointsGained'} = + $maxToolScore - $status{'toolDeductions'}; $styleSectionStatus{'pointsGainedPercent'} = (($maxToolScore - $status{'toolDeductions'})/$maxToolScore) * 100; } else { + $styleSectionStatus{'pointsGained'} = 0; $styleSectionStatus{'pointsGainedPercent'} = 100; } @@ -2232,8 +2388,7 @@ sub trackMessageInstance } } $studentCasesPercent = - $status{'studentTestResults'}->testPassRate * 100.0; - # int($status{'studentTestResults'}->testPassRate * 100.0 + 0.5); + int($status{'studentTestResults'}->testPassRate * 100.0 * 10 + 0.5) / 10; if ($status{'studentTestResults'}->testsFailed > 0 && $studentCasesPercent == 100) { @@ -2851,7 +3006,7 @@ sub processStatementsUncovered $gradedElements = 1; $gradedElementsCovered = 1; } - + # set code markup properties $cfg->setProperty("statElementsLabel", "Mutants Detected"); my %fileDeductionProperties = (); @@ -3548,7 +3703,7 @@ sub processStatementsUncovered $codeCoveragePercent = int(($gradedElementsCovered * 1.0 / $gradedElements) # / $coverageGoal - * 100.0 + 0.5); + * 100.0 * 10 + 0.5) / 10; if ($codeCoveragePercent > 100) { $codeCoveragePercent = 100; } if (($gradedElementsCovered * 1.0 / $gradedElements) < $coverageGoal && $codeCoveragePercent == 100) @@ -3621,6 +3776,11 @@ sub processStatementsUncovered { $status{'instrTestResults'}->saveToCfg($cfg, 'instructor.test'); } +if (defined $status{'validateTestResults'} + && $status{'validateTestResults'}->hasResults) +{ + $status{'validateTestResults'}->saveToCfg($cfg, 'validate.test'); +} if (defined $messageStats) { my $staticResults = ''; @@ -3672,7 +3832,7 @@ sub processStatementsUncovered $cfg->setProperty('static.analysis.results', '(' . $staticResults . ')'); } $cfg->setProperty('outcomeProperties', - '("instructor.test.results", "student.test.results", ' + '("instructor.test.results", "student.test.results", "validate.test.results, ' . '"static.analysis.results")'); @@ -3734,7 +3894,7 @@ sub markCodingSectionUsingInstrResults else { $instructorCasesPercent = - int($status{'instrTestResults'}->testPassRate * 100.0 + 0.5); + int($status{'instrTestResults'}->testPassRate * 100.0 * 10 + 0.5) / 10; if ($instructorCasesPercent == 100) { # Don't show 100% if some cases failed @@ -4049,121 +4209,620 @@ sub markCodingSectionUsingInstrResults } } - #============================================================================= -# generate HTML versions of any other source files +# generate test validation results #============================================================================= - -if ($debug > 3) -{ -foreach my $ff (keys %codeMessages) +if (defined $status{'validateTestResults'} && $useTestCaseValidation) { - print "file $ff:\n"; - foreach my $line (keys %{$codeMessages{$ff}}) + my $sectionTitle = "Detailed Test Validation Results"; + if ($status{'validateTestResults'}->testsExecuted == 0 + || ($studentsMustSubmitTests + && !$status{'studentTestResults'}->hasResults)) { - print "file $ff: line $line:\n"; - if (defined $codeMessages{$ff}->{$line}{violations}) + $sectionTitle .= + "(Unknown!)"; + $validateCasesPercent = "unknown"; + } + elsif ($status{'validateTestResults'}->allTestsPass) + { + $sectionTitle .= "(100%)"; + $validateCasesPercent = 100; + } + else + { + $validateCasesPercent = + int($status{'validateTestResults'}->testPassRate * 100.0 * 10 + 0.5) / 10; + if ($validateCasesPercent == 100) { - my @comments = - sort { $b->{line}->content <=> $a->{line}->content } - @{ $codeMessages{$ff}->{$line}{violations} }; - print "file $ff: line $line: total comments = ", - $#comments + 1, "\n"; - foreach my $c (@comments) - { - my $message = $c->{message}->content; - if (!defined $message || $message eq '') - { - $message = $c->content; - } - # print "comment = ", $c->data(tree => $c), "\n"; - print 'group = ', $c->{group}->content, ', line = ', - $c->{line}->content, ', message = ', - $message, "\n"; - } + # Don't show 100% if some cases failed + $validateCasesPercent--; } + $sectionTitle .= "($validateCasesPercent%)"; } -} -} + if ($showTestCaseValidation) + { + $status{'feedback'}->startFeedbackSection( + $sectionTitle, ++$expSectionId, + $useEnhancedFeedback || ($validateCasesPercent >= 100)); + $status{'feedback'}->print("

Valid Test Percentage: "); + if ($validateCasesPercent == 100) + { + $status{'feedback'}->print("100%"); + } + else + { + $status{'feedback'}->print( + "$validateCasesPercent"); + if ($validateCasesPercent ne "unknown") + { + $status{'feedback'}->print("%"); + } + $status{'feedback'}->print(""); + } + $status{'feedback'}->print("

"); -# The extended error messages from config files which replace the builtin -# messages from Checkstyle and PMD are longer. -# Use those messages as 'enhancedMessage' and shorter messages as -# 'errorMessage'. -sub addShorterMessages -{ - my $struct = shift; - my $rule = shift; + if ($status{'compileErrs'}) # $validateCases == 0 + { + $status{'feedback'}->print(<Your Specification Tests failed to compile correctly against +the reference implementation.

+

This is most likely because you have not followed the correct format +for the specification tests (using only methods defined in the interface).

+

Failure to follow these constraints will prevent the proper assessment +of your solution and your tests.

+EOF + if ($status{'compileMsgs'} ne "") + { + $status{'feedback'}->print(<The following specific error(s) were discovered while compiling +your specification tests against the reference implementation:

+

+
+EOF
+            $status{'feedback'}->print($status{'compileMsgs'});
+            $status{'feedback'}->print("
\n"); + } + } + elsif ($studentsMustSubmitTests + && !$status{'studentTestResults'}->hasResults) + { + $status{'feedback'}->print(<You are required to write your own software tests +for this assignment. You must provide your own tests +to get further feedback.

+EOF + } + elsif ($status{'validateTestResults'}->allTestsFail) + { + $status{'feedback'}->print(<Your problem setup does not appear to be +consistent with the assignment.

+EOF + if ($studentsMustSubmitTests) + { + $status{'feedback'}->print(<For this assignment, your test cases are being assessed by running +your tests against the reference solution.

+EOF + } + $status{'feedback'}->print(<In this case, none of your specification tests pass on the reference +solution, which may mean that your specification tests make incorrect +assumptions about some aspect of the required behavior. This discrepancy prevented +Web-CAT from properly assessing the thoroughness of your test cases.

+

Double check that you have carefully followed all initial conditions +requested in the assignment in setting up your test cases.

+EOF - my $shortMessage = codingStyleMessageValue($rule); + } + elsif ($status{'validateTestResults'}->allTestsPass) + { + $status{'feedback'}->print(<Your tests appear to match the expectations for this assignment since none expect +outputs that conflict with the reference implementation.

+EOF + } + else + { + if ($studentsMustSubmitTests) + { + $status{'feedback'}->print(<For this assignment, your test cases are being assessed by running +your tests against the reference solution.

+

Some of your tests fail when run against the reference implementation.

+

This happens when your test cases embody misconceptions of the problem +spec by expecting different output from what the reference implementation +generates for this that test case. +

Your test cases contain misconceptions of the problem spec, so your +testing is incomplete.

+EOF + } + $status{'feedback'}->print(<Double check that you have carefully followed all requirements of the +assignment when setting up your tests.

+EOF + } + if ($hintsLimit != 0 && !$status{'compileErrs'}) + { + if ($studentsMustSubmitTests + && $hasJUnitErrors + && $junitErrorsHideHints) + { + $status{'feedback'}->print(<Your JUnit test classes contain problems that must be +fixed before you can receive any more specific feedback. Be sure that +all of your test classes contain test methods, and that all of your test +methods include appropriate assertions to check for expected behavior. +You must fix these problems with your own tests to get further feedback.

+EOF + } + } - if ($shortMessage) { - $struct = expandedMessage->new( - entityName => $struct->entityName, - lineNum => $struct->lineNum, - errorMessage => $shortMessage, - linesOfCode => $struct->linesOfCode, - enhancedMessage => $struct->errorMessage, + if ($codingSectionStatus{'compilerErrors'} == 1) + { + # Transform the plain text JUnit results into an interactive HTML + # view. + JavaTddPlugin::transformTestResults('validate_', + "$resultDir/validate-results.txt", + "$resultDir/validate-results.html" ); - } + } - return $struct; + if ($codingSectionStatus{'compilerErrors'} == 1) + { + open(VALIDATERESULTS, "$resultDir/validate-results.html"); + my @lines = ; + close(VALIDATERESULTS); + if ($#lines >= 0) + { + $status{'feedback'}->print(<The results of running your test cases are shown +below. Click on a failed test to see the reason for the failure and an +execution trace that shows where the error occurred.

+EOF + $status{'feedback'}->print(@lines); + } + unlink "$resultDir/validate-results.html"; + + @lines = linesFromFile("$resultDir/validate-out.txt", 75000, 4000); + if ($#lines >= 0) + { + $status{'feedback'}->startFeedbackSection( + "Output from your tests", ++$expSectionId, 1, 2, + "
", "
"); + $status{'feedback'}->print(@lines); + $status{'feedback'}->endFeedbackSection; + } + $status{'feedback'}->endFeedbackSection; + } + } + } } -sub processCodingStyleStruct +#============================================================================= +# generate milestone results +#============================================================================= +@milestoneResults = (); +for (my $i = 0; $i < $milestoneCount; $i++) { - my $group = shift; - my $rule = shift; - my $struct = shift; + my $mNum = defined($milestoneNumbers[$i]) ? $milestoneNumbers[$i] : ($i + 1); + my $dueDate = $milestoneDueDatesTimestamps[$i]; + my $reqStudentTests = $milestoneMinStudentTests[$i] // 0; + my $reqRefTests = $milestoneMinRefTests[$i] // 0; + my $reqCover = $milestoneMinMutationCoverages[$i] // 0; + my $reqStyle = $milestoneStyleMins[$i] // 0; - my $key = 'other'; + my $actualStudentTests = 0; + my $actualRefTests = 0; + my $actualCoverage = 0; + my $actualStyle = 0; + my @details = (); + my $met = 1; - if (lc($group) eq 'coding') + if (defined $status{'validateTestResults'}) { - $key = 'codingFlaws'; + $actualStudentTests = $status{'validateTestResults'}->testsExecuted + - $status{'validateTestResults'}->testsFailed; } - elsif (index(lc($group), 'testing') != -1) + + if (defined $status{'instrTestResults'}) { - $key = 'junitTests'; + $actualRefTests = $status{'instrTestResults'}->testsExecuted + - $status{'instrTestResults'}->testsFailed; } - elsif (index(lc($rule), 'javadoc') != -1) + + if (defined $testingSectionStatus{'codeCoveragePercent'}) { - $key = 'javadoc'; + $actualCoverage = $testingSectionStatus{'codeCoveragePercent'}; } - elsif (index(lc($rule), 'indentation') != -1) + + if (defined $styleSectionStatus{'pointsGainedPercent'}) { - $key = 'indentation'; + $actualStyle = defined $styleSectionStatus{'pointsGained'} + ? $styleSectionStatus{'pointsGained'} + : $styleSectionStatus{'pointsGainedPercent'}; } - elsif (index(lc($rule), 'whitespace') != -1) + + my $subTime = $cfg->getProperty('submissionTimestamp', 0); + my $dueMet = 1; + my $dueExpected = 'Not required'; + my $dueActual = 'No due date'; + + if (defined($dueDate) && $dueDate > 0) { - $key = 'whitespace'; + $dueExpected = formatTimestampForDisplay($dueDate); + $dueActual = formatTimestampForDisplay($subTime); + + if (defined $subTime && $subTime ne '' && $subTime =~ /^\d+$/ + && $subTime > $dueDate) + { + $dueMet = 0; + } } - elsif (index(lc($rule), 'linelength') != -1) + + push @details, { + name => 'Due Date', + met => $dueMet, + expected => $dueExpected, + actual => $dueActual + }; + $met = 0 unless $dueMet; + + my $studentMet = 1; + my $studentExpected = 'Not required'; + if ($reqStudentTests > 0) { - $key = 'lineLength'; + $studentExpected = ">= $reqStudentTests"; + $studentMet = ($actualStudentTests >= $reqStudentTests); + $met = 0 unless $studentMet; } + push @details, { + name => 'Student Tests', + met => $studentMet, + expected => $studentExpected, + actual => $actualStudentTests + }; - $struct = addShorterMessages($struct, $rule); + my $refMet = 1; + my $refExpected = 'Not required'; + if ($reqRefTests > 0) + { + $refExpected = ">= $reqRefTests"; + $refMet = ($actualRefTests >= $reqRefTests); + $met = 0 unless $refMet; + } + push @details, { + name => 'Reference Tests', + met => $refMet, + expected => $refExpected, + actual => $actualRefTests + }; - if (defined $perFileRuleStruct{$key}{'data'}{$rule}) + my $coverMet = 1; + my $coverExpected = 'Not required'; + my $coverActual = sprintf('%.1f%%', $actualCoverage); + if ($reqCover > 0) { - push @{$perFileRuleStruct{$key}{'data'}{$rule}}, $struct; - $perFileRuleStruct{$key}{'count'}{$rule}++; + $coverExpected = ">= $reqCover%"; + $coverMet = ($actualCoverage >= $reqCover); + $met = 0 unless $coverMet; } - else + push @details, { + name => 'Mutation Coverage', + met => $coverMet, + expected => $coverExpected, + actual => $coverActual + }; + + my $styleMet = 1; + my $styleExpected = 'Not required'; + my $styleActual = sprintf('%g', $actualStyle); + if ($reqStyle > 0) { - my @temp; - push @temp, $struct; - $perFileRuleStruct{$key}{'data'}{$rule} = [@temp]; - $perFileRuleStruct{$key}{'count'}{$rule} = 1; + $styleExpected = ">= $reqStyle"; + $styleMet = ($actualStyle >= $reqStyle); + $met = 0 unless $styleMet; } + push @details, { + name => 'Style Points', + met => $styleMet, + expected => $styleExpected, + actual => $styleActual + }; + + push @milestoneResults, { + id => "milestone$mNum", + name => "Milestone $mNum", + met => $met, + details => \@details + }; } -# Only Hints are used as error message; others aew undef -sub generateHintErrorStruct +if ($milestoneCount > 0) +{ + my $totalMilestones = scalar @milestoneResults; + my $milestonesPassed = 0; + + foreach my $milestoneResult (@milestoneResults) + { + $milestonesPassed++ if $milestoneResult->{met}; + } + + # Fallback to properties if detailed milestone results were not built. + if ($totalMilestones == 0) + { + for (my $i = 1; $i <= 20; $i++) + + { + my $passedProp = $cfg->getProperty("milestonePassed.$i"); + if (defined $passedProp) + { + $totalMilestones++; + if ($passedProp eq 'true' || $passedProp eq '1') + { + $milestonesPassed++; + } + } + } + } + + my $sectionTitle = "Milestone Progress"; + my $milestonePercent = 0; + my $milestonePercentKnown = 1; + + if ($totalMilestones == 0) + { + $sectionTitle .= " (Unknown!)"; + $milestonePercentKnown = 0; + } + elsif ($milestonesPassed >= $totalMilestones) + { + $sectionTitle .= " (100%)"; + $milestonePercent = 100; + } + else + { + $milestonePercent = + int(($milestonesPassed / $totalMilestones) * 100.0 * 10 + 0.5) / 10; + if ($milestonePercent == 100) + { + # Don't show 100% if some milestones failed + $milestonePercent--; + } + $sectionTitle .= " ($milestonePercent%)"; + } + + $status{'feedback'}->startFeedbackSection( + $sectionTitle, ++$expSectionId, + $useEnhancedFeedback + || ($milestonePercentKnown && $milestonePercent >= 100)); + $status{'feedback'}->print("

Milestones Met: "); + if ($totalMilestones == 0) + { + $status{'feedback'}->print("Unknown"); + } + elsif ($milestonePercent == 100) + { + $status{'feedback'}->print("$milestonesPassed/$totalMilestones"); + } + else + { + $status{'feedback'}->print( + "$milestonesPassed/$totalMilestones"); + $status{'feedback'}->print(""); + } + $status{'feedback'}->print("

"); + + if ($totalMilestones == 0) + { + $status{'feedback'}->print(<No milestone configuration was detected.

+

This assignment may not have milestones configured, or the milestone +properties could not be found.

+EOF + } + elsif ($milestonePercentKnown && $milestonePercent >= 100) + { + $status{'feedback'}->print(<Congratulations! You have met all $totalMilestones milestones for this assignment.

+EOF + } + else + { + $status{'feedback'}->print(<You have met $milestonesPassed out of $totalMilestones milestones. +Review the details below to see which requirements need to be addressed.

+EOF + } + + # Display detailed milestone information + if ($totalMilestones > 0) + { + $status{'feedback'}->print( + "

The following milestones are defined for this assignment:

\n"); + + if (@milestoneResults) + { + printMilestoneFeedbackDetails($status{'feedback'}, \@milestoneResults); + } + else + { + # Fallback when no detailed milestone results are available: show requirements only + $status{'feedback'}->print("
    \n"); + for (my $i = 1; $i <= $totalMilestones; $i++) + { + my $dueDateProp = $cfg->getProperty("milestoneDueDate.$i", '0'); + my $dueTimeProp = $cfg->getProperty("milestoneDueTime.$i", '0'); + my $passed = $cfg->getProperty("milestonePassed.$i", 'false'); + my $mutationCovMin = $cfg->getProperty("milestoneMinMutationCoverage.$i", '0'); + my $studentTestMin = $cfg->getProperty("milestoneMinStudentTests.$i", '0'); + my $refTestMin = $cfg->getProperty("milestoneMinRefTests.$i", '0'); + my $styleMin = $cfg->getProperty("milestoneStyleMin.$i", '0'); + + next unless milestoneHasConfiguredRequirements( + $dueDateProp, $dueTimeProp, $studentTestMin, + $refTestMin, $styleMin, $mutationCovMin); + + my $class = ($passed eq 'true' || $passed eq '1') ? 'complete' : 'incomplete'; + my $statusText = ($passed eq 'true' || $passed eq '1') ? 'Met' : 'Not Met'; + + $status{'feedback'}->print("
  • Milestone $i: $statusText"); + + if ($mutationCovMin > 0 + || $studentTestMin > 0 + || $refTestMin > 0 + || $styleMin > 0) + { + $status{'feedback'}->print("
      "); + if ($studentTestMin > 0) + { + $status{'feedback'}->print( + "
    • Minimum Student Tests: $studentTestMin
      • "); + } + if ($refTestMin > 0) + { + $status{'feedback'}->print( + "
    • Minimum Reference Tests: $refTestMin
      • "); + } + if ($mutationCovMin > 0) + { + $status{'feedback'}->print( + "
    • Minimum Mutation Coverage: $mutationCovMin%
      • "); + } + if ($styleMin > 0) + { + $status{'feedback'}->print( + "
    • Minimum Style Points: $styleMin
      • "); + } + $status{'feedback'}->print("
    "); + } + + $status{'feedback'}->print("
    • \n"); + } + $status{'feedback'}->print("
\n"); + } + } + $status{'feedback'}->endFeedbackSection; +} + + +#============================================================================= +# generate HTML versions of any other source files +#============================================================================= + +if ($debug > 3) +{ +foreach my $ff (keys %codeMessages) +{ + print "file $ff:\n"; + foreach my $line (keys %{$codeMessages{$ff}}) + { + print "file $ff: line $line:\n"; + if (defined $codeMessages{$ff}->{$line}{violations}) + { + my @comments = + sort { $b->{line}->content <=> $a->{line}->content } + @{ $codeMessages{$ff}->{$line}{violations} }; + print "file $ff: line $line: total comments = ", + $#comments + 1, "\n"; + foreach my $c (@comments) + { + my $message = $c->{message}->content; + if (!defined $message || $message eq '') + { + $message = $c->content; + } + # print "comment = ", $c->data(tree => $c), "\n"; + print 'group = ', $c->{group}->content, ', line = ', + $c->{line}->content, ', message = ', + $message, "\n"; + } + } + } +} +} + + +# The extended error messages from config files which replace the builtin +# messages from Checkstyle and PMD are longer. +# Use those messages as 'enhancedMessage' and shorter messages as +# 'errorMessage'. +sub addShorterMessages +{ + my $struct = shift; + my $rule = shift; + + my $shortMessage = codingStyleMessageValue($rule); + + if ($shortMessage) + { + $struct = expandedMessage->new( + entityName => $struct->entityName, + lineNum => $struct->lineNum, + errorMessage => $shortMessage, + linesOfCode => $struct->linesOfCode, + enhancedMessage => $struct->errorMessage, + ); + } + + return $struct; +} + + +sub processCodingStyleStruct +{ + my $group = shift; + my $rule = shift; + my $struct = shift; + + my $key = 'other'; + + if (lc($group) eq 'coding') + { + $key = 'codingFlaws'; + } + elsif (index(lc($group), 'testing') != -1) + { + $key = 'junitTests'; + } + elsif (index(lc($rule), 'javadoc') != -1) + { + $key = 'javadoc'; + } + elsif (index(lc($rule), 'indentation') != -1) + { + $key = 'indentation'; + } + elsif (index(lc($rule), 'whitespace') != -1) + { + $key = 'whitespace'; + } + elsif (index(lc($rule), 'linelength') != -1) + { + $key = 'lineLength'; + } + + $struct = addShorterMessages($struct, $rule); + + if (defined $perFileRuleStruct{$key}{'data'}{$rule}) + { + push @{$perFileRuleStruct{$key}{'data'}{$rule}}, $struct; + $perFileRuleStruct{$key}{'count'}{$rule}++; + } + else + { + my @temp; + push @temp, $struct; + $perFileRuleStruct{$key}{'data'}{$rule} = [@temp]; + $perFileRuleStruct{$key}{'count'}{$rule} = 1; + } +} + +# Only Hints are used as error message; others aew undef +sub generateHintErrorStruct { my $errorMessage = shift; @@ -4246,7 +4905,13 @@ sub generateCompleteErrorStruct { $lineNum = $c->{beginline}->content; } - + + if (!defined($lineNum) || $lineNum eq '' ) + { + print "no line number found in:\n", + $c->data_pointer(noheader => 1, nometagen => 1), "\n"; + } + if (!defined($lineNum) || $lineNum eq '' ) { print "no line number found in:\n", @@ -4429,52 +5094,237 @@ sub addLinesAboveAssertionFailure enhancedMessage => $assertionStruct->enhancedMessage, ); - return $assertionStruct; -} + return $assertionStruct; +} + + +# Suites from student.inc +sub computeTestingErrorFailureStructs +{ + my @studentSuites = $status{'studentTestResults'}->listOfHashes; + + for my $suite (@studentSuites) + { + # Implies this test passed + if ($suite->{'level'} == 1) + { + next; + } + + # Assertion Failures + if ($suite->{'level'} == 2) + { + my $fileName; + my $lineNum; + my $assertionStruct; + + ($fileName, $lineNum) = + extractFileNameFromStackTrace($suite->{'trace'}, 1); + + if (!defined $fileName || !defined $lineNum) + { + $assertionStruct = generateHintErrorStruct( + $suite->{'test'} . ': ' . $suite->{'message'}); + } + else + { + $assertionStruct = generateCompleteErrorStruct($fileName, + $lineNum, $suite->{'test'} . ': ' . $suite->{'message'}); + $assertionStruct = addLinesAboveAssertionFailure( + $assertionStruct, $suite->{'test'}); + } + + addErrorFailureStructToHash( + 'failures', 'failures', $assertionStruct); + next; + } + + # This is the case for errors + my $fileName; + my $lineNum; + my $errorStruct; + my $message = $suite->{'message'}; + + if (defined $suite->{'exception'}) + { + my $exName = $suite->{'exception'}; + $exName =~ s/^.*\.//o; + $message = $exName . ': ' . $message; + } + + if ($suite->{'level'} == 4 && $suite->{'code'} == 32) + { + $errorStruct = + generateStackOverflowErrorStruct($suite->{'trace'}); + + if (!defined $errorStruct) + { + $errorStruct = generateHintErrorStruct($message); + } + } + else + { + ($fileName, $lineNum) = + extractFileNameFromStackTrace($suite->{'trace'}, 1); + + if (!defined $fileName || !defined $lineNum) + { + $errorStruct = generateHintErrorStruct($message); + } + else + { + $errorStruct = generateCompleteErrorStruct( + $fileName, $lineNum, $message); + } + } + + if (!defined $suite->{'exception'}) + { + addErrorFailureStructToHash('errors', $message, $errorStruct); + } + else + { + addErrorFailureStructToHash( + 'errors', $suite->{'exception'}, $errorStruct); + } + } +} + +# We use this to ensure that duplicate messages (which imply the same) aren't +# displayed in the feedback. This is used for Signature Errors, Behavior Errors +# and Behavior Failures. For Signature Errors and Behavior Failures we store +# the message as the key. For Behavior Errors, we store message (which +# contains exception name and message from inc file) and line num as the key. +my %signatureErrorFailureMessages; + +# Suites from instr.inc +sub computeBehaviorSectionSignatureStructs +{ + my @instrSuites = $status{'instrTestResults'}->listOfHashes; + + for my $suite (@instrSuites) + { + # Implies this test passed + if ($suite->{'level'} == 1) + { + next; + } + + # Assertion Failures + if ($suite->{'level'} == 2) + { + if (defined $signatureErrorFailureMessages{$suite->{'message'}}) + { + next; + } + else + { + $signatureErrorFailureMessages{$suite->{'message'}} = 1; + } + + my $assertionStruct = generateHintErrorStruct($suite->{'message'}); + + # note that the key is 'behaviorFailures', so that there is no + # conflict with 'failures' which is key for testing + addErrorFailureStructToHash( + 'behaviorFailures', 'behaviorFailures', $assertionStruct); + next; + } + + # Signature Errors + if ($suite->{'level'} == 4 && $suite->{'code'} == 29) + { + if (defined $signatureErrorFailureMessages{$suite->{'message'}}) + { + next; + } + else + { + $signatureErrorFailureMessages{$suite->{'message'}} = 1; + } + + my $fileName; + my $lineNum; + my $signatureErrorStruct; + + ($fileName, $lineNum) = + extractFileNameFromStackTrace($suite->{'trace'}, 0); + + if (!defined $fileName || !defined $lineNum) + { + $signatureErrorStruct = + generateHintErrorStruct($suite->{'message'}); + } + else + { + $signatureErrorStruct = generateCompleteErrorStruct( + $fileName, $lineNum, $suite->{'message'}); + } + + addErrorFailureStructToHash('signatureErrors', 'signatureErrors', + $signatureErrorStruct); + next; + } + # StackOverflowError + if ($suite->{'level'} == 4 && $suite->{'code'} == 32) + { + my $stackOverflowErrorStruct; + $stackOverflowErrorStruct = + generateStackOverflowErrorStruct($suite->{'trace'}); -# Suites from student.inc -sub computeTestingErrorFailureStructs -{ - my @studentSuites = $status{'studentTestResults'}->listOfHashes; + if (!defined $stackOverflowErrorStruct) + { + $stackOverflowErrorStruct = + generateHintErrorStruct($suite->{'message'}); + } - for my $suite (@studentSuites) - { - # Implies this test passed - if ($suite->{'level'} == 1) - { + addErrorFailureStructToHash( + 'stackOverflowErrors', + 'stackOverflowErrors', + $stackOverflowErrorStruct); next; } - # Assertion Failures - if ($suite->{'level'} == 2) + # OutOfMemoryError + if ($suite->{'level'} == 4 && $suite->{'code'} == 31) { my $fileName; my $lineNum; - my $assertionStruct; + my $outOfMemoryStruct; - ($fileName, $lineNum) = - extractFileNameFromStackTrace($suite->{'trace'}, 1); + ($fileName, $lineNum) = + extractFileNameFromStackTrace($suite->{'trace'}, 1); if (!defined $fileName || !defined $lineNum) { - $assertionStruct = generateHintErrorStruct( - $suite->{'test'} . ': ' . $suite->{'message'}); + $outOfMemoryStruct = + generateHintErrorStruct($suite->{'message'}); } else { - $assertionStruct = generateCompleteErrorStruct($fileName, - $lineNum, $suite->{'test'} . ': ' . $suite->{'message'}); - $assertionStruct = addLinesAboveAssertionFailure( - $assertionStruct, $suite->{'test'}); + $outOfMemoryStruct = generateCompleteErrorStruct( + $fileName, $lineNum, $suite->{'message'}); } addErrorFailureStructToHash( - 'failures', 'failures', $assertionStruct); + 'outOfMemoryErrors', 'outOfMemoryErrors', $outOfMemoryStruct); + next; + } + + # Test Timedout + if ($suite->{'level'} == 5 + && index(lc($suite->{'trace'}), lc('TestTimedOutException')) + != -1) + { + my $testsTakeLongStruct = + generateHintErrorStruct($suite->{'message'}); + + addErrorFailureStructToHash( + 'testsTakeTooLong', 'testsTakeTooLong', $testsTakeLongStruct); next; } - # This is the case for errors my $fileName; my $lineNum; my $errorStruct; @@ -4487,57 +5337,63 @@ sub computeTestingErrorFailureStructs $message = $exName . ': ' . $message; } - if ($suite->{'level'} == 4 && $suite->{'code'} == 32) - { - $errorStruct = - generateStackOverflowErrorStruct($suite->{'trace'}); + ($fileName, $lineNum) = + extractFileNameFromStackTrace($suite->{'trace'}, 1); - if (!defined $errorStruct) + if (!defined $lineNum) + { + if (defined $signatureErrorFailureMessages{$message}) { - $errorStruct = generateHintErrorStruct($message); + next; + } + else + { + $signatureErrorFailureMessages{$message} = 1; } } else { - ($fileName, $lineNum) = - extractFileNameFromStackTrace($suite->{'trace'}, 1); - - if (!defined $fileName || !defined $lineNum) + if (defined $signatureErrorFailureMessages{$message.$lineNum}) { - $errorStruct = generateHintErrorStruct($message); + next; } else { - $errorStruct = generateCompleteErrorStruct( - $fileName, $lineNum, $message); + $signatureErrorFailureMessages{$message.$lineNum} = 1; } } + if (!defined $fileName || !defined $lineNum) + { + $errorStruct = generateHintErrorStruct($message); + } + else + { + $errorStruct = generateCompleteErrorStruct( + $fileName, $lineNum, $message); + } + + # note that the key is 'behaviorErrors', so that there is no conflict + # with 'errors' which is key for testing if (!defined $suite->{'exception'}) { - addErrorFailureStructToHash('errors', $message, $errorStruct); + addErrorFailureStructToHash( + 'behaviorErrors', $message, $errorStruct); } else { addErrorFailureStructToHash( - 'errors', $suite->{'exception'}, $errorStruct); + 'behaviorErrors', $suite->{'exception'}, $errorStruct); } } } -# We use this to ensure that duplicate messages (which imply the same) aren't -# displayed in the feedback. This is used for Signature Errors, Behavior Errors -# and Behavior Failures. For Signature Errors and Behavior Failures we store -# the message as the key. For Behavior Errors, we store message (which -# contains exception name and message from inc file) and line num as the key. -my %signatureErrorFailureMessages; - -# Suites from instr.inc -sub computeBehaviorSectionSignatureStructs +# Suites from validate.inc +sub computeBehaviorSectionSignatureStructsValidate { - my @instrSuites = $status{'instrTestResults'}->listOfHashes; + my @validateSuites = $status{'validateTestResults'}->listOfHashes; - for my $suite (@instrSuites) + for my $suite (@validateSuites) { # Implies this test passed if ($suite->{'level'} == 1) @@ -5204,6 +6060,24 @@ sub groupStructsByFileName print "score with coverage: $runtimeScore ($gradedElementsCovered " . "elements / $gradedElements covered)\n" if ($debug > 2); +if ($includeValidationInGrading) +{ + my $validationTestCount = $status{'validateTestResults'}->testsExecuted; + $validationPenalty = $maxValidationPenalty; + if ($validationTestCount >= $validationTestsRequired) + { + my $testsPassed = $status{'validateTestResults'}->testsExecuted - $status{'validateTestResults'}->testsFailed; + my $effectiveTests = $validationTestCount > $validationFailuresAllowed ? $validationTestCount - $validationFailuresAllowed : 0; + my $effectivePassRate = $effectiveTests > 0 ? $testsPassed / $effectiveTests : 1.0; + $validationPenalty = $maxValidationPenalty * (1 - ($effectivePassRate > 1.0 ? 1.0 : $effectivePassRate)); + + # $validationPenalty = $maxValidationPenalty * (1 - $status{'validateTestResults'}->testPassRate); + } + $runtimeScore -= $validationPenalty; + if ($runtimeScore < 0) { $runtimeScore = 0; } + $printableValidationPenalty = int($validationPenalty * 10 + 0.5) / 10; +} + # Total them up # my $rawScore = $can_proceed # ? ($staticScore + $runtimeScore) @@ -5309,11 +6183,27 @@ sub groupStructsByFileName $status{'feedback'}->print(<Coverage goal for full credit: $printableCoverageGoal% +EOF + } + if ($includeValidationInGrading) + { + $status{'feedback'}->print(<Results from test case validation +$validateCasesPercent% EOF } $status{'feedback'}->print(<Estimate of problem coverage: $instructorCasesPercent% +EOF + if ($includeValidationInGrading) + { + $status{'feedback'}->print(<Penalty from test validation +$printableValidationPenalty +EOF + } +$status{'feedback'}->print(<score = EOF if ($includeStudentTestsInGrading) @@ -5328,6 +6218,12 @@ sub groupStructsByFileName $status{'feedback'}->print(<print(" - $printableValidationPenalty "); + } +$status{'feedback'}->print(<

Full-precision (unrounded) percentages are used to calculate @@ -5492,6 +6388,271 @@ sub smartHtmlEscapeAndPeel return $msg; } +sub loadMilestoneConfigData +{ + my ($configPath) = @_; + + return [] unless defined $configPath && $configPath ne '' && -e $configPath; + + my $jsonText = ''; + if (open(my $fh, '<', $configPath)) + { + local $/; + $jsonText = <$fh>; + close($fh); + } + else + { + return []; + } + + return [] unless defined $jsonText && $jsonText ne ''; + + my $decoder; + if (eval { require JSON::PP; JSON::PP->can('decode_json') }) + { + $decoder = sub { JSON::PP::decode_json($_[0]) }; + } + elsif (eval { require JSON; JSON->can('decode_json') }) + { + $decoder = sub { JSON::decode_json($_[0]) }; + } + else + { + return []; + } + + my $data = eval { $decoder->($jsonText) }; + return [] if $@ || ref($data) ne 'HASH'; + return [] unless ref($data->{milestones}) eq 'ARRAY'; + + return $data->{milestones}; +} + +sub evaluateMilestoneInline +{ + my ($milestone, $cfg, $status, $codeCoveragePercent, $styleSectionStatus) = @_; + + my $reqs = (ref $milestone->{requirements} eq 'HASH') + ? $milestone->{requirements} + : {}; + my @details = (); + my $allMet = 1; + + if (defined $milestone->{dueDate}) + { + my $subTime = $cfg->getProperty('submissionTimestamp'); + my $met = 1; + my $actual = formatTimestampForDisplay($subTime); + + if (defined $subTime && $subTime ne '' + && $subTime =~ /^\d+$/ + && $milestone->{dueDate} =~ /^\d+$/ + && $subTime > $milestone->{dueDate}) + { + $met = 0; + } + + push @details, { + name => 'Due Date', + met => $met, + expected => formatTimestampForDisplay($milestone->{dueDate}), + actual => $actual + }; + $allMet = 0 unless $met; + } + + if (defined $reqs->{referenceTestsPassed}) + { + my $instrResults = $status->{instrTestResults}; + my $actualVal = 0; + if ($instrResults && $instrResults->testsExecuted > 0) + { + $actualVal = $instrResults->testPassRate * 100; + } + + my $target = $reqs->{referenceTestsPassed}; + my $met = ($actualVal >= $target - 0.001); + push @details, { + name => 'Reference Tests', + met => $met, + expected => ">= $target%", + actual => sprintf('%.1f%%', $actualVal) + }; + $allMet = 0 unless $met; + } + + if ($reqs->{validationTestsPassed}) + { + my $valResults = $status->{validateTestResults}; + my $met = 0; + my $actual = 'Failed'; + if ($valResults && $valResults->allTestsPass) + { + $met = 1; + $actual = 'Passed'; + } + + push @details, { + name => 'Validation Tests', + met => $met, + expected => 'All Pass', + actual => $actual + }; + $allMet = 0 unless $met; + } + + if (defined $reqs->{stylePoints}) + { + my $actualVal = defined $styleSectionStatus->{pointsGained} + ? $styleSectionStatus->{pointsGained} + : 0; + $actualVal = 0 unless defined $actualVal; + my $target = $reqs->{stylePoints}; + my $met = ($actualVal >= $target); + + push @details, { + name => 'Style Points', + met => $met, + expected => ">= $target", + actual => sprintf('%g', $actualVal) + }; + $allMet = 0 unless $met; + } + + if (defined $reqs->{mutationCoverage}) + { + my $actualVal = $codeCoveragePercent; + $actualVal = 0 unless defined $actualVal && $actualVal =~ /^\d+(?:\.\d+)?$/; + my $target = $reqs->{mutationCoverage}; + my $met = ($actualVal >= $target); + + push @details, { + name => 'Mutation Coverage', + met => $met, + expected => ">= $target%", + actual => sprintf('%.1f%%', $actualVal) + }; + $allMet = 0 unless $met; + } + + return ($allMet, \@details); +} + +sub printMilestoneFeedbackDetails +{ + my ($feedbackGenerator, $milestoneResults) = @_; + + return unless $feedbackGenerator; + return unless $milestoneResults && @$milestoneResults; + + $feedbackGenerator->print('

    '); + + foreach my $result (@$milestoneResults) + { + my $name = htmlEscape($result->{name} // 'Milestone'); + my $isMet = $result->{met} ? 1 : 0; + my $liClass = $isMet ? 'complete' : 'incomplete'; + my $statusText = $isMet ? 'Met' : 'Not Met'; + + $feedbackGenerator->print("
  • $name: $statusText"); + + if ($result->{details} && @{$result->{details}}) + { + $feedbackGenerator->print('
      '); + foreach my $det (@{$result->{details}}) + { + my $detClass = $det->{met} ? 'complete' : 'incomplete'; + my $detName = htmlEscape($det->{name} // 'Requirement'); + my $expected = htmlEscape($det->{expected} // ''); + my $actual = htmlEscape($det->{actual} // ''); + my $detStatus = $det->{met} ? 'Passed' : 'Failed'; + + $feedbackGenerator->print( + "
    • $detName: $detStatus " + . "Required: $expected — " + . "Yours: $actual
      • "); + } + $feedbackGenerator->print('
    '); + } + + $feedbackGenerator->print('
    • '); + } + + $feedbackGenerator->print('
'); +} + +sub generateMilestonePanelHtml +{ + my ($milestoneResults) = @_; + + return '' unless $milestoneResults && @$milestoneResults; + + my $totalMilestones = scalar @$milestoneResults; + my $metCount = 0; + foreach my $result (@$milestoneResults) + { + $metCount++ if $result->{met}; + } + + my $title = 'Milestones Met'; + my $titleSuffix = " ($metCount/$totalMilestones)"; + my $incomplete = ($metCount < $totalMilestones) ? ' incomplete' : ''; + + my $html = "
\n"; + $html .= "
\n"; + $html .= "
"; + + if ($metCount == $totalMilestones) + { + $html .= "

Milestones Met: $metCount/$totalMilestones

"; + $html .= '

Congratulations! You have met all milestones for this assignment.

'; + } + else + { + $html .= "

Milestones Met: $metCount/$totalMilestones

"; + $html .= "

You have met $metCount out of $totalMilestones milestones. "; + $html .= 'Review the details below to see which requirements need to be addressed.

'; + } + + $html .= '

The following milestones are defined for this assignment:

'; + $html .= '
    '; + + foreach my $result (@$milestoneResults) + { + my $name = htmlEscape($result->{name} // 'Milestone'); + my $isMet = $result->{met} ? 1 : 0; + my $class = $isMet ? 'complete' : 'incomplete'; + my $statusText = $isMet ? 'Met' : 'Not Met'; + + $html .= "
  • $name: $statusText"; + if ($result->{details} && @{$result->{details}}) + { + $html .= '
      '; + foreach my $det (@{$result->{details}}) + { + my $detClass = $det->{met} ? 'complete' : 'incomplete'; + my $detName = htmlEscape($det->{name} // 'Requirement'); + my $expected = htmlEscape($det->{expected} // ''); + my $actual = htmlEscape($det->{actual} // ''); + my $detStatus = $det->{met} ? 'Passed' : 'Failed'; + $html .= "
    • $detName: $detStatus Required: $expected — Yours: $actual
      • "; + } + $html .= '
    '; + } + $html .= '
    • '; + } + + $html .= '
'; + $html .= "
\n"; + $html .= "
\n"; + $html .= "
\n"; + $html .= "
\n"; + $html .= "
\n"; + + return $html; +} + # Student feedback # ----------- { @@ -5651,6 +6812,14 @@ sub computeExpandSectionId print IMPROVEDFEEDBACKFILE Web_CAT::Maria::chatbox(); } +# Milestones +if (@milestoneResults) +{ + print IMPROVEDFEEDBACKFILE "
\n"; + print IMPROVEDFEEDBACKFILE generateMilestonePanelHtml(\@milestoneResults); + print IMPROVEDFEEDBACKFILE "
\n"; +} + # Coding Section my $incomplete = ($expandSectionId == 1) ? ' incomplete' : ''; print IMPROVEDFEEDBACKFILE <testsExecuted == 0) { $showTesting = 0; @@ -6368,7 +7537,7 @@ sub computeExpandSectionId my $rawPct = $rawScore / $maxPossible; my $subTime = $cfg->getProperty('submissionTimestamp', 0); my $dueTime = $cfg->getProperty('dueDateTimestamp', $subTime); - + my $emrnCmt = ''; my $emrnCategory = 'Not Assessable'; # print <= 0.95 && $runtimeScore / $maxCorrectnessScore >= 0.95 @@ -6404,7 +7573,6 @@ sub computeExpandSectionId $emrnCmt = 'Your submission passes all auto-grader checks for this ' . 'assignment.'; } - $staticScore = $maxToolScore * 1.0 / ($maxToolScore + $maxCorrectnessScore) * $emrnExcellent; @@ -6517,6 +7685,110 @@ sub computeExpandSectionId } +my @milestone_results = (); + +for (my $i = 0; $i < $milestoneCount; $i++) { + my $mNum = defined($milestoneNumbers[$i]) ? $milestoneNumbers[$i] : ($i + 1); + my $dueDate = $milestoneDueDatesTimestamps[$i]; + my $status = "IN PROGRESS"; + + # Requirements + my $reqStudentTests = $milestoneMinStudentTests[$i] // 0; + my $reqRefTests = $milestoneMinRefTests[$i] //0; + my $reqCover = $milestoneMinMutationCoverages[$i] // 0; + my $reqStyle = $milestoneStyleMins[$i] // 0; + + next unless milestoneHasConfiguredRequirements( + $cfg->getProperty("milestoneDueDate.$mNum"), + $cfg->getProperty("milestoneDueTime.$mNum"), + $reqStudentTests, $reqRefTests, $reqStyle, $reqCover); + + my $actualStudentTests = 0; + my $actualRefTests = 0; + my $actualCoverage = 0; + my $actualStyle = 0; + + + + if ($milestoneAlreadyPassed[$i]) { + # SKIP THE CHECK: They already passed it! + $status = "ACHIEVED"; + + $actualStudentTests = $reqStudentTests; + $actualRefTests = $reqRefTests; + $actualCoverage = $reqCover; + $actualStyle = $reqStyle; + + } else { + # Actuals + $actualStudentTests = (defined $status{'validateTestResults'}) ? ($status{'validateTestResults'}->testsExecuted - $status{'validateTestResults'}->testsFailed) : 0; + $actualRefTests = + (defined $instructorCasesPercent + && $instructorCasesPercent =~ /^\d+(?:\.\d+)?$/) + ? $instructorCasesPercent + : 0; + $actualCoverage = $testingSectionStatus{'codeCoveragePercent'}; + $actualStyle = defined $styleSectionStatus{'pointsGained'} + ? $styleSectionStatus{'pointsGained'} + : $styleSectionStatus{'pointsGainedPercent'}; + + # Determine Status + my $met = ($actualStudentTests >= $reqStudentTests && $actualCoverage >= $reqCover && $actualStyle >= $reqStyle && $actualRefTests >= $reqRefTests) ? 1 : 0; + + if ($met) { + $status = "ACHIEVED"; + $cfg->setProperty("milestonePassed.$mNum", "true"); + } elsif (defined($dueDate) + && $dueDate > 0 + && $cfg->getProperty('submissionTimestamp', 0) > $dueDate) { + $status = "MISSED"; + } + } + + # 2. Build the json for this milestone + my %milestone_entry = ( + milestoneNumber => $mNum, + dueDate => (defined($dueDate) ? $dueDate : 0), + status => $status, + requirements => { + minStudentTests => int($reqStudentTests), + minRefTests => int($reqRefTests), + minCover => int($reqCover), + minStyle => int($reqStyle) + }, + actuals => { + studentTests => $actualStudentTests, + referenceTests => $actualRefTests, + cover => $actualCoverage, + style => $actualStyle + } + ); + + push @milestone_results, \%milestone_entry; +} + +# 3. Write to milestones.json +my $json_output = { + submissionDate => $cfg->getProperty('submissionTimestamp', 0), + milestones => \@milestone_results +}; + +# Encode and write +eval { + require JSON::PP; + my $json_text = JSON::PP->new->utf8->pretty->encode($json_output); + my $milestoneFilename = "$resultDir/milestones.json"; + + open(my $fh, '>', $milestoneFilename) or die "Could not open '$milestoneFilename' for writing: $!"; + print $fh $json_text; + close $fh; + print "Successfully wrote milestone data to $milestoneFilename\n" if $debug; +}; +if ($@) { + print "Error generating JSON: $@" if $debug; +} + + #============================================================================= # Script log #============================================================================= diff --git a/src/perllib/File/Slurp.pm b/src/perllib/File/Slurp.pm new file mode 100644 index 0000000..e5329b1 --- /dev/null +++ b/src/perllib/File/Slurp.pm @@ -0,0 +1,1128 @@ +package File::Slurp; + +use strict; +use warnings ; + +our $VERSION = '9999.32'; +$VERSION = eval $VERSION; + +use Carp ; +use Exporter qw(import); +use Fcntl qw( :DEFAULT ) ; +use File::Basename (); +use File::Spec; +use File::Temp qw(tempfile); +use IO::Handle (); +use POSIX qw( :fcntl_h ) ; +use Errno ; + +my @std_export = qw( + read_file + write_file + overwrite_file + append_file + read_dir +) ; + +my @edit_export = qw( + edit_file + edit_file_lines +) ; + +my @abbrev_export = qw( + rf + wf + ef + efl +) ; + +our @EXPORT_OK = ( + @edit_export, + @abbrev_export, + qw( + slurp + prepend_file + ), +) ; + +our %EXPORT_TAGS = ( + 'all' => [ @std_export, @edit_export, @abbrev_export, @EXPORT_OK ], + 'edit' => [ @edit_export ], + 'std' => [ @std_export ], + 'abr' => [ @abbrev_export ], +) ; + +our @EXPORT = @std_export ; + +my $max_fast_slurp_size = 1024 * 100 ; + +my $is_win32 = $^O =~ /win32/i ; + +*slurp = \&read_file ; +*rf = \&read_file ; + +sub read_file { + my $file_name = shift; + my $opts = (ref $_[0] eq 'HASH') ? shift : {@_}; + # options we care about: + # array_ref binmode blk_size buf_ref chomp err_mode scalar_ref + + # let's see if we have a stringified object before doing anything else + # We then only have to deal with when we are given a file handle/globref + if (ref($file_name)) { + my $ref_result = _check_ref($file_name, $opts); + if (ref($ref_result)) { + @_ = ($opts, $ref_result); + goto &_error; + } + $file_name = $ref_result if $ref_result; + # we have now stringified $file_name if possible. if it's still a ref + # then we probably have a file handle + } + + my $fh; + if (ref($file_name)) { + $fh = $file_name; + } + else { + # to keep with the old ways, read in :raw by default + unless (open $fh, "<:raw", $file_name) { + @_ = ($opts, "read_file '$file_name' - open: $!"); + goto &_error; + } + # even though we set raw, let binmode take place here (busted) + if (my $bm = $opts->{binmode}) { + binmode $fh, $bm; + } + } + + # we are now sure to have an open file handle. Let's slurp it in the same + # way that File::Slurper does. + my $buf; + my $buf_ref = $opts->{buf_ref} || \$buf; + ${$buf_ref} = ''; + my $blk_size = $opts->{blk_size} || 1024 * 1024; + if (my $size = -f $fh && -s _) { + $blk_size = $size if $size < $blk_size; + my ($pos, $read) = 0; + do { + unless(defined($read = read $fh, ${$buf_ref}, $blk_size, $pos)) { + @_ = ($opts, "read_file '$file_name' - read: $!"); + goto &_error; + } + $pos += $read; + } while ($read && $pos < $size); + } + else { + ${$buf_ref} = do { local $/; <$fh> }; + } + seek($fh, $opts->{_data_tell}, SEEK_SET) if $opts->{_is_data} && $opts->{_data_tell}; + + # line endings if we're on Windows + ${$buf_ref} =~ s/\015\012/\012/g if ${$buf_ref} && $is_win32 && !$opts->{binmode}; + + # we now have a buffer filled with the file content. Figure out how to + # return it to the user + my $want_array = wantarray; # let's only ask for this once + if ($want_array || $opts->{array_ref}) { + use re 'taint'; + my $sep = $/; + $sep = '\n\n+' if defined $sep && $sep eq ''; + # split the buffered content into lines + my @lines = length(${$buf_ref}) ? + ${$buf_ref} =~ /(.*?$sep|.+)/sg : (); + chomp @lines if $opts->{chomp}; + return \@lines if $opts->{array_ref}; + return @lines; + } + return $buf_ref if $opts->{scalar_ref}; + # if the function was called in scalar context, return the contents + return ${$buf_ref} if defined $want_array; + # if we were called in void context, return nothing + return; +} + +# errors in this sub are returned as scalar refs +# a normal IO/GLOB handle is an empty return +# an overloaded object returns its stringified as a scalarfilename + +sub _check_ref { + + my( $handle, $opts ) = @_ ; + +# check if we are reading from a handle (GLOB or IO object) + + if ( eval { $handle->isa( 'GLOB' ) || $handle->isa( 'IO' ) } ) { + +# we have a handle. deal with seeking to it if it is DATA + + my $err = _seek_data_handle( $handle, $opts ) ; + +# return the error string if any + + return \$err if $err ; + +# we have good handle + return ; + } + + eval { require overload } ; + +# return an error if we can't load the overload pragma +# or if the object isn't overloaded + + return \"Bad handle '$handle' is not a GLOB or IO object or overloaded" + if $@ || !overload::Overloaded( $handle ) ; + +# must be overloaded so return its stringified value + + return "$handle" ; +} + +sub _seek_data_handle { + + my( $handle, $opts ) = @_ ; + # store some meta-data about the __DATA__ file handle + $opts->{_is_data} = 0; + $opts->{_data_tell} = 0; + +# DEEP DARK MAGIC. this checks the UNTAINT IO flag of a +# glob/handle. only the DATA handle is untainted (since it is from +# trusted data in the source file). this allows us to test if this is +# the DATA handle and then to do a sysseek to make sure it gets +# slurped correctly. on some systems, the buffered i/o pointer is not +# left at the same place as the fd pointer. this sysseek makes them +# the same so slurping with sysread will work. + + eval{ require B } ; + + if ( $@ ) { + + return <IO->IoFLAGS & 16 ) { + + # we now know we have the data handle. Let's store its original + # location in the file so that we can put it back after the read. + # this is only done for Bugwards-compatibility in some dists such as + # CPAN::Index::API that made use of the oddity where sysread was in use + # before + $opts->{_is_data} = 1; + $opts->{_data_tell} = tell($handle); +# set the seek position to the current tell. + + # unless( sysseek( $handle, tell( $handle ), SEEK_SET ) ) { + # return "read_file '$handle' - sysseek: $!" ; + # } + } + +# seek was successful, return no error string + + return ; +} + +*wf = \&write_file ; + +sub write_file { + my $file_name = shift; + my $opts = (ref $_[0] eq 'HASH') ? shift : {}; + # options we care about: + # append atomic binmode buf_ref err_mode no_clobber perms + + my $fh; + my $no_truncate = 0; + my $orig_filename; + # let's see if we have a stringified object or some sort of handle + # or globref before doing anything else + if (ref($file_name)) { + my $ref_result = _check_ref($file_name, $opts); + if (ref($ref_result)) { + # some error happened while checking for a ref + @_ = ($opts, $ref_result); + goto &_error; + } + if ($ref_result) { + # we have now stringified $file_name from the overloaded obj + $file_name = $ref_result; + } + else { + # we now have a proper handle ref + # make sure we don't call truncate on it + $fh = $file_name; + $no_truncate = 1; + # can't do atomic or permissions on a file handle + delete $opts->{atomic}; + delete $opts->{perms}; + } + } + + # open the file for writing if we were given a filename + unless ($fh) { + $orig_filename = $file_name; + my $perms = defined($opts->{perms}) ? $opts->{perms} : 0666; + # set the mode for the sysopen + my $mode = O_WRONLY | O_CREAT; + $mode |= O_APPEND if $opts->{append}; + $mode |= O_EXCL if $opts->{no_clobber}; + if ($opts->{atomic}) { + # in an atomic write, we must open a new file in the same directory + # as the original to account for ACLs. We must also set the new file + # to the same permissions as the original unless overridden by the + # caller's request to set a specified permission set. + my $dir = File::Spec->rel2abs(File::Basename::dirname($file_name)); + if (!defined($opts->{perms}) && -e $file_name && -f _) { + $perms = 07777 & (stat $file_name)[2]; + } + # we must ensure we're using a good temporary filename (doesn't already + # exist). This is slower, but safer. + { + local $^W = 0; # AYFKM + (undef, $file_name) = tempfile('.tempXXXXX', DIR => $dir, OPEN => 0); + } + } + $fh = local *FH; + unless (sysopen($fh, $file_name, $mode, $perms)) { + @_ = ($opts, "write_file '$file_name' - sysopen: $!"); + goto &_error; + } + } + # we now have an open file handle as well as data to write to that handle + if (my $binmode = $opts->{binmode}) { + binmode($fh, $binmode); + } + + # get the data to print to the file + # get the buffer ref - it depends on how the data is passed in + # after this if/else $buf_ref will have a scalar ref to the data + my $buf_ref; + my $data_is_ref = 0; + if (ref($opts->{buf_ref}) eq 'SCALAR') { + # a scalar ref passed in %opts has the data + # note that the data was passed by ref + $buf_ref = $opts->{buf_ref}; + $data_is_ref = 1; + } + elsif (ref($_[0]) eq 'SCALAR') { + # the first value in @_ is the scalar ref to the data + # note that the data was passed by ref + $buf_ref = shift; + $data_is_ref = 1; + } + elsif (ref($_[0]) eq 'ARRAY') { + # the first value in @_ is the array ref to the data so join it. + ${$buf_ref} = join '', @{$_[0]}; + } + else { + # good old @_ has all the data so join it. + ${$buf_ref} = join '', @_; + } + + # seek and print + seek($fh, 0, SEEK_END) if $opts->{append}; + print {$fh} ${$buf_ref}; + truncate($fh, tell($fh)) unless $no_truncate; + close($fh); + + if ($opts->{atomic} && !rename($file_name, $orig_filename)) { + @_ = ($opts, "write_file '$file_name' - rename: $!"); + goto &_error; + } + + return 1; +} + +# this is for backwards compatibility with the previous File::Slurp module. +# write_file always overwrites an existing file +*overwrite_file = \&write_file ; + +# the current write_file has an append mode so we use that. this +# supports the same API with an optional second argument which is a +# hash ref of options. + +sub append_file { + +# get the optional opts hash ref + my $opts = $_[1] ; + if ( ref $opts eq 'HASH' ) { + +# we were passed an opts ref so just mark the append mode + + $opts->{append} = 1 ; + } + else { + +# no opts hash so insert one with the append mode + + splice( @_, 1, 0, { append => 1 } ) ; + } + +# magic goto the main write_file sub. this overlays the sub without touching +# the stack or @_ + + goto &write_file +} + +# prepend data to the beginning of a file + +sub prepend_file { + + my $file_name = shift ; + +#print "FILE $file_name\n" ; + + my $opts = ( ref $_[0] eq 'HASH' ) ? shift : {} ; + +# delete unsupported options + + my @bad_opts = + grep $_ ne 'err_mode' && $_ ne 'binmode', keys %{$opts} ; + + delete @{$opts}{@bad_opts} ; + + my $prepend_data = shift ; + $prepend_data = '' unless defined $prepend_data ; + $prepend_data = ${$prepend_data} if ref $prepend_data eq 'SCALAR' ; + +#print "PRE [$prepend_data]\n" ; + + my $err_mode = delete $opts->{err_mode} ; + $opts->{ err_mode } = 'croak' ; + $opts->{ scalar_ref } = 1 ; + + my $existing_data = eval { read_file( $file_name, $opts ) } ; + + if ( $@ ) { + + @_ = ( { err_mode => $err_mode }, + "prepend_file '$file_name' - read_file: $!" ) ; + goto &_error ; + } + +#print "EXIST [$$existing_data]\n" ; + + $opts->{atomic} = 1 ; + my $write_result = + eval { write_file( $file_name, $opts, + $prepend_data, $$existing_data ) ; + } ; + + if ( $@ ) { + + @_ = ( { err_mode => $err_mode }, + "prepend_file '$file_name' - write_file: $!" ) ; + goto &_error ; + } + + return $write_result ; +} + +# edit a file as a scalar in $_ + +*ef = \&edit_file ; + +sub edit_file(&$;$) { + + my( $edit_code, $file_name, $opts ) = @_ ; + $opts = {} unless ref $opts eq 'HASH' ; + +# my $edit_code = shift ; +# my $file_name = shift ; +# my $opts = ( ref $_[0] eq 'HASH' ) ? shift : {} ; + +#print "FILE $file_name\n" ; + +# delete unsupported options + + my @bad_opts = + grep $_ ne 'err_mode' && $_ ne 'binmode', keys %{$opts} ; + + delete @{$opts}{@bad_opts} ; + +# keep the user err_mode and force croaking on internal errors + + my $err_mode = delete $opts->{err_mode} ; + $opts->{ err_mode } = 'croak' ; + +# get a scalar ref for speed and slurp the file into a scalar + + $opts->{ scalar_ref } = 1 ; + my $existing_data = eval { read_file( $file_name, $opts ) } ; + + if ( $@ ) { + + @_ = ( { err_mode => $err_mode }, + "edit_file '$file_name' - read_file: $!" ) ; + goto &_error ; + } + +#print "EXIST [$$existing_data]\n" ; + + my( $edited_data ) = map { $edit_code->(); $_ } $$existing_data ; + + $opts->{atomic} = 1 ; + my $write_result = + eval { write_file( $file_name, $opts, $edited_data ) } ; + + if ( $@ ) { + + @_ = ( { err_mode => $err_mode }, + "edit_file '$file_name' - write_file: $!" ) ; + goto &_error ; + } + + return $write_result ; +} + +*efl = \&edit_file_lines ; + +sub edit_file_lines(&$;$) { + + my( $edit_code, $file_name, $opts ) = @_ ; + $opts = {} unless ref $opts eq 'HASH' ; + +# my $edit_code = shift ; +# my $file_name = shift ; +# my $opts = ( ref $_[0] eq 'HASH' ) ? shift : {} ; + +#print "FILE $file_name\n" ; + +# delete unsupported options + + my @bad_opts = + grep $_ ne 'err_mode' && $_ ne 'binmode', keys %{$opts} ; + + delete @{$opts}{@bad_opts} ; + +# keep the user err_mode and force croaking on internal errors + + my $err_mode = delete $opts->{err_mode} ; + $opts->{ err_mode } = 'croak' ; + +# get an array ref for speed and slurp the file into lines + + $opts->{ array_ref } = 1 ; + my $existing_data = eval { read_file( $file_name, $opts ) } ; + + if ( $@ ) { + + @_ = ( { err_mode => $err_mode }, + "edit_file_lines '$file_name' - read_file: $!" ) ; + goto &_error ; + } + +#print "EXIST [$$existing_data]\n" ; + + my @edited_data = map { $edit_code->(); $_ } @$existing_data ; + + $opts->{atomic} = 1 ; + my $write_result = + eval { write_file( $file_name, $opts, @edited_data ) } ; + + if ( $@ ) { + + @_ = ( { err_mode => $err_mode }, + "edit_file_lines '$file_name' - write_file: $!" ) ; + goto &_error ; + } + + return $write_result ; +} + +# basic wrapper around opendir/readdir + +sub read_dir { + + my $dir = shift ; + my $opts = ( ref $_[0] eq 'HASH' ) ? shift : { @_ } ; + +# this handle will be destroyed upon return + + local(*DIRH); + +# open the dir and handle any errors + + unless ( opendir( DIRH, $dir ) ) { + + @_ = ( $opts, "read_dir '$dir' - opendir: $!" ) ; + goto &_error ; + } + + my @dir_entries = readdir(DIRH) ; + + @dir_entries = grep( $_ ne "." && $_ ne "..", @dir_entries ) + unless $opts->{'keep_dot_dot'} ; + + if ( $opts->{'prefix'} ) { + + $_ = File::Spec->catfile($dir, $_) for @dir_entries; + } + + return @dir_entries if wantarray ; + return \@dir_entries ; +} + +# error handling section +# +# all the error handling uses magic goto so the caller will get the +# error message as if from their code and not this module. if we just +# did a call on the error code, the carp/croak would report it from +# this module since the error sub is one level down on the call stack +# from read_file/write_file/read_dir. + + +my %err_func = ( + 'carp' => \&carp, + 'croak' => \&croak, +) ; + +sub _error { + + my( $opts, $err_msg ) = @_ ; + +# get the error function to use + + my $func = $err_func{ $opts->{'err_mode'} || 'croak' } ; + +# if we didn't find it in our error function hash, they must have set +# it to quiet and we don't do anything. + + return unless $func ; + +# call the carp/croak function + + $func->($err_msg) if $func ; + +# return a hard undef (in list context this will be a single value of +# undef which is not a legal in-band value) + + return undef ; +} + +1; +__END__ + +=head1 NAME + +File::Slurp - Simple and Efficient Reading/Writing/Modifying of Complete Files + +=head1 SYNOPSIS + + use File::Slurp; + + # read in a whole file into a scalar + my $text = read_file('/path/file'); + + # read in a whole file into an array of lines + my @lines = read_file('/path/file'); + + # write out a whole file from a scalar + write_file('/path/file', $text); + + # write out a whole file from an array of lines + write_file('/path/file', @lines); + + # Here is a simple and fast way to load and save a simple config file + # made of key=value lines. + my %conf = read_file('/path/file') =~ /^(\w+)=(.*)$/mg; + write_file('/path/file', {atomic => 1}, map "$_=$conf{$_}\n", keys %conf); + + # insert text at the beginning of a file + prepend_file('/path/file', $text); + + # in-place edit to replace all 'foo' with 'bar' in file + edit_file { s/foo/bar/g } '/path/file'; + + # in-place edit to delete all lines with 'foo' from file + edit_file_lines sub { $_ = '' if /foo/ }, '/path/file'; + + # read in a whole directory of file names (skipping . and ..) + my @files = read_dir('/path/to/dir'); + +=head1 DESCRIPTION + +This module provides subs that allow you to read or write entire files +with one simple call. They are designed to be simple to use, have +flexible ways to pass in or get the file contents and to be very +efficient. There is also a sub to read in all the files in a +directory. + +=head2 WARNING - PENDING DOOM + +Although you technically I, do NOT use this module to work on file handles, +pipes, sockets, standard IO, or the C handle. These are +features implemented long ago that just really shouldn't be abused here. + +Be warned: this activity will lead to inaccurate encoding/decoding of data. + +All further mentions of actions on the above have been removed from this +documentation and that feature set will likely be deprecated in the future. + +In other words, if you don't have a filename to pass, consider using the +standard C<< do { local $/; <$fh> } >>, or +L/L for working with C<__DATA__>. + +=head1 FUNCTIONS + +L implements the following functions. + +=head2 append_file + + use File::Slurp qw(append_file write_file); + my $res = append_file('/path/file', "Some text"); + # same as + my $res = write_file('/path/file', {append => 1}, "Some text"); + +The C function is simply a synonym for the +L function, but ensures that the C option is +set. + +=head2 edit_file + + use File::Slurp qw(edit_file); + # perl -0777 -pi -e 's/foo/bar/g' /path/file + edit_file { s/foo/bar/g } '/path/file'; + edit_file sub { s/foo/bar/g }, '/path/file'; + sub replace_foo { s/foo/bar/g } + edit_file \&replace_foo, '/path/file'; + +The C function reads in a file into C<$_>, executes a code block that +should modify C<$_>, and then writes C<$_> back to the file. The C +function reads in the entire file and calls the code block one time. It is +equivalent to the C<-pi> command line options of Perl but you can call it from +inside your program and not have to fork out a process. + +The first argument to C is a code block or a code reference. The +code block is not followed by a comma (as with C and C) but a code +reference is followed by a comma. + +The next argument is the filename. + +The next argument(s) is either a hash reference or a flattened hash, +C<< key => value >> pairs. The options are passed through to the +L function. All options are described there. +Only the C and C options are supported. The call to +L has the C option set so you will always +have a consistent file. + +=head2 edit_file_lines + + use File::Slurp qw(edit_file_lines); + # perl -pi -e '$_ = "" if /foo/' /path/file + edit_file_lines { $_ = '' if /foo/ } '/path/file'; + edit_file_lines sub { $_ = '' if /foo/ }, '/path/file'; + sub delete_foo { $_ = '' if /foo/ } + edit_file \&delete_foo, '/path/file'; + +The C function reads each line of a file into C<$_>, and +executes a code block that should modify C<$_>. It will then write C<$_> back +to the file. It is equivalent to the C<-pi> command line options of Perl but +you can call it from inside your program and not have to fork out a process. + +The first argument to C is a code block or a code reference. +The code block is not followed by a comma (as with C and C) but a +code reference is followed by a comma. + +The next argument is the filename. + +The next argument(s) is either a hash reference or a flattened hash, +C<< key => value >> pairs. The options are passed through to the +L function. All options are described there. +Only the C and C options are supported. The call to +L has the C option set so you will always +have a consistent file. + +=head2 ef + + use File::Slurp qw(ef); + # perl -0777 -pi -e 's/foo/bar/g' /path/file + ef { s/foo/bar/g } '/path/file'; + ef sub { s/foo/bar/g }, '/path/file'; + sub replace_foo { s/foo/bar/g } + ef \&replace_foo, '/path/file'; + +The C function is simply a synonym for the L +function. + +=head2 efl + + use File::Slurp qw(efl); + # perl -pi -e '$_ = "" if /foo/' /path/file + efl { $_ = '' if /foo/ } '/path/file'; + efl sub { $_ = '' if /foo/ }, '/path/file'; + sub delete_foo { $_ = '' if /foo/ } + efl \&delete_foo, '/path/file'; + +The C function is simply a synonym for the L +function. + +=head2 overwrite_file + + use File::Slurp qw(overwrite_file); + my $res = overwrite_file('/path/file', "Some text"); + +The C function is simply a synonym for the +L function. + +=head2 prepend_file + + use File::Slurp qw(prepend_file); + prepend_file('/path/file', $header); + prepend_file('/path/file', \@lines); + prepend_file('/path/file', { binmode => ':raw'}, $bin_data); + + # equivalent to: + use File::Slurp qw(read_file write_file); + my $content = read_file('/path/file'); + my $new_content = "hahahaha"; + write_file('/path/file', $new_content . $content); + +The C function is the opposite of L as +it writes new contents to the beginning of the file instead of the end. It is a +combination of L and L. It +works by first using C to slurp in the file and then calling +C with the new data and the existing file data. + +The first argument to C is the filename. + +The next argument(s) is either a hash reference or a flattened hash, +C<< key => value >> pairs. The options are passed through to the +L function. All options are described there. + +Only the C and C options are supported. The +C call has the C option set so you will always have +a consistent file. + +=head2 read_dir + + use File::Slurp qw(read_dir); + my @files = read_dir('/path/to/dir'); + # all files, even the dots + my @files = read_dir('/path/to/dir', keep_dot_dot => 1); + # keep the full file path + my @paths = read_dir('/path/to/dir', prefix => 1); + # scalar context + my $files_ref = read_dir('/path/to/dir'); + +This function returns a list of the filenames in the supplied directory. In +list context, an array is returned, in scalar context, an array reference is +returned. + +The first argument is the path to the directory to read. + +The next argument(s) is either a hash reference or a flattened hash, +C<< key => value >> pairs. The following options are available: + +=over + +=item + +err_mode + +The C option has three possible values: C, C, or the +default, C. In C mode, all errors will be silent. In C mode, +all errors will be emitted as warnings. And, in C mode, all errors will +be emitted as exceptions. Take a look at L or +L to see how to catch exceptions. + +=item + +keep_dot_dot + +The C option is a boolean option, defaulted to false (C<0>). +Setting this option to true (C<1>) will also return the C<.> and C<..> files +that are removed from the file list by default. + +=item + +prefix + +The C option is a boolean option, defaulted to false (C<0>). +Setting this option to true (C<1>) add the directory as a prefix to the file. +The directory and the filename are joined using C<< File::Spec->catfile() >> to +ensure the proper directory separator is used for your OS. See L. + +=back + +=head2 read_file + + use File::Slurp qw(read_file); + my $text = read_file('/path/file'); + my $bin = read_file('/path/file', { binmode => ':raw' }); + my @lines = read_file('/path/file'); + my $lines_ref = read_file('/path/file', array_ref => 1); + my $lines_ref = [ read_file('/path/file') ]; + + # or we can read into a buffer: + my $buffer; + read_file('/path/file', buf_ref => \$buffer); + + # or we can set the block size for the read + my $text_ref = read_file('/path/file', blk_size => 10_000_000, array_ref => 1); + + # or we can get a scalar reference + my $text_ref = read_file('/path/file', scalar_ref => 1); + +This function reads in an entire file and returns its contents to the +caller. In scalar context it returns the entire file as a single +scalar. In list context it will return a list of lines (using the +current value of C<$/> as the separator, including support for paragraph +mode when it is set to C<''>). + +The first argument is the path to the file to be slurped in. + +The next argument(s) is either a hash reference or a flattened hash, +C<< key => value >> pairs. The following options are available: + +=over + +=item + +array_ref + +The C option is a boolean option, defaulted to false (C<0>). Setting +this option to true (C<1>) will only have relevance if the C function +is called in scalar context. When true, the C function will return +a reference to an array of the lines in the file. + +=item + +binmode + +The C option is a string option, defaulted to empty (C<''>). If you +set the C option, then its value is passed to a call to C on +the opened handle. You can use this to set the file to be read in binary mode, +utf8, etc. See C for more. + +=item + +blk_size + +You can use this option to set the block size used when slurping from +an already open handle (like C<\*STDIN>). It defaults to 1MB. + +=item + +buf_ref + +The C option can be used in conjunction with any of the other options. +You can use this option to pass in a scalar reference and the slurped +file contents will be stored in the scalar. This saves an extra copy of +the slurped file and can lower RAM usage vs returning the file. It is +usually the fastest way to read a file into a scalar. + +=item + +chomp + +The C option is a boolean option, defaulted to false (C<0>). Setting +this option to true (C<1>) will cause each line to have its contents Ced. +This option works in list context or in scalar context with the C +option. + +=item + +err_mode + +The C option has three possible values: C, C, or the +default, C. In C mode, all errors will be silent. In C mode, +all errors will be emitted as warnings. And, in C mode, all errors will +be emitted as exceptions. Take a look at L or +L to see how to catch exceptions. + +=item + +scalar_ref + +The C option is a boolean option, defaulted to false (C<0>). It only +has meaning in scalar context. The return value will be a scalar reference to a +string which is the contents of the slurped file. This will usually be faster +than returning the plain scalar. It will also save memory as it will not make a +copy of the file to return. + +=back + +=head2 rf + + use File::Slurp qw(rf); + my $text = rf('/path/file'); + +The C function is simply a synonym for the L +function. + +=head2 slurp + + use File::Slurp qw(slurp); + my $text = slurp('/path/file'); + +The C function is simply a synonym for the L +function. + +=head2 wf + + use File::Slurp qw(wf); + my $res = wf('/path/file', "Some text"); + + +The C function is simply a synonym for the +L function. + +=head2 write_file + + use File::Slurp qw(write_file); + write_file('/path/file', @data); + write_file('/path/file', {append => 1}, @data); + write_file('/path/file', {binmode => ':raw'}, $buffer); + write_file('/path/file', \$buffer); + write_file('/path/file', $buffer); + write_file('/path/file', \@lines); + write_file('/path/file', @lines); + + # binmode + write_file('/path/file', {binmode => ':raw'}, @data); + write_file('/path/file', {binmode => ':utf8'}, $utf_text); + + # buffered + write_file('/path/file', {buf_ref => \$buffer}); + write_file('/path/file', \$buffer); + write_file('/path/file', $buffer); + + # append + write_file('/path/file', {append => 1}, @data); + + # no clobbering + write_file('/path/file', {no_clobber => 1}, @data); + +This function writes out an entire file in one call. By default C +returns C<1> upon successfully writing the file or C if it encountered +an error. You can change how errors are handled with the C option. + +The first argument to C is the filename. + +The next argument(s) is either a hash reference or a flattened hash, +C<< key => value >> pairs. The following options are available: + +=over + +=item + +append + +The C option is a boolean option, defaulted to false (C<0>). Setting +this option to true (C<1>) will cause the data to be be written at the end of +the current file. Internally this sets the C mode flag C. + +The L function sets this option by default. + +=item + +atomic + +The C option is a boolean option, defaulted to false (C<0>). Setting +this option to true (C<1>) will cause the file to be be written to in an +atomic fashion. A temporary file name is created using L. +After the file is closed it is renamed to the original file name +(and C is an atomic operation on most OSes). If the program using +this were to crash in the middle of this, then the temporary file could +be left behind. + +=item + +binmode + +The C option is a string option, defaulted to empty (C<''>). If you +set the C option, then its value is passed to a call to C on +the opened handle. You can use this to set the file to be read in binary mode, +utf8, etc. See C for more. + +=item + +buf_ref + +The C option is used to pass in a scalar reference which has the +data to be written. If this is set then any data arguments (including +the scalar reference shortcut) in C<@_> will be ignored. + +=item + +err_mode + +The C option has three possible values: C, C, or the +default, C. In C mode, all errors will be silent. In C mode, +all errors will be emitted as warnings. And, in C mode, all errors will +be emitted as exceptions. Take a look at L or +L to see how to catch exceptions. + + +=item + +no_clobber + +The C option is a boolean option, defaulted to false (C<0>). Setting +this option to true (C<1>) will ensure an that existing file will not be +overwritten. + +=item + +perms + +The C option sets the permissions of newly-created files. This value +is modified by your process's C and defaults to C<0666> (same as +C). + +NOTE: this option is new as of File::Slurp version 9999.14. + +=back + +=head1 EXPORT + +These are exported by default or with + + use File::Slurp qw(:std); + # read_file write_file overwrite_file append_file read_dir + +These are exported with + + use File::Slurp qw(:edit); + # edit_file edit_file_lines + +You can get all subs in the module exported with + + use File::Slurp qw(:all); + +=head1 SEE ALSO + +=over + +=item * + +L - Provides a straightforward set of functions for the most +common tasks of reading/writing text and binary files. + +=item * + +L - Lightweight and comprehensive file handling, including simple +methods for reading, writing, and editing text and binary files. + +=item * + +L - Similar to Path::Tiny for the L toolkit, always works in +bytes. + +=back + +=head1 AUTHOR + +Uri Guttman, > + +=head1 COPYRIGHT & LICENSE + +Copyright (c) 2003 Uri Guttman. All rights reserved. + +This program is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. + +=cut diff --git a/src/perllib/JSON.pm b/src/perllib/JSON.pm new file mode 100644 index 0000000..d44c6b4 --- /dev/null +++ b/src/perllib/JSON.pm @@ -0,0 +1,1844 @@ +package JSON; + + +use strict; +use Carp (); +use Exporter; +BEGIN { @JSON::ISA = 'Exporter' } + +@JSON::EXPORT = qw(from_json to_json jsonToObj objToJson encode_json decode_json); + +BEGIN { + $JSON::VERSION = '4.10'; + $JSON::DEBUG = 0 unless (defined $JSON::DEBUG); + $JSON::DEBUG = $ENV{ PERL_JSON_DEBUG } if exists $ENV{ PERL_JSON_DEBUG }; +} + +my %RequiredVersion = ( + 'JSON::PP' => '2.27203', + 'JSON::XS' => '2.34', +); + +# XS and PP common methods + +my @PublicMethods = qw/ + ascii latin1 utf8 pretty indent space_before space_after relaxed canonical allow_nonref + allow_blessed convert_blessed filter_json_object filter_json_single_key_object + shrink max_depth max_size encode decode decode_prefix allow_unknown +/; + +my @Properties = qw/ + ascii latin1 utf8 indent space_before space_after relaxed canonical allow_nonref + allow_blessed convert_blessed shrink max_depth max_size allow_unknown +/; + +my @XSOnlyMethods = qw//; # Currently nothing + +my @PublicMethodsSince4_0 = qw/allow_tags/; +my @PropertiesSince4_0 = qw/allow_tags/; + +my @PPOnlyMethods = qw/ + indent_length sort_by + allow_singlequote allow_bignum loose allow_barekey escape_slash as_nonblessed +/; # JSON::PP specific + + +# used in _load_xs and _load_pp ($INSTALL_ONLY is not used currently) +my $_INSTALL_DONT_DIE = 1; # When _load_xs fails to load XS, don't die. +my $_ALLOW_UNSUPPORTED = 0; +my $_UNIV_CONV_BLESSED = 0; + + +# Check the environment variable to decide worker module. + +unless ($JSON::Backend) { + $JSON::DEBUG and Carp::carp("Check used worker module..."); + + my $backend = exists $ENV{PERL_JSON_BACKEND} ? $ENV{PERL_JSON_BACKEND} : 1; + + if ($backend eq '1') { + $backend = 'JSON::XS,JSON::PP'; + } + elsif ($backend eq '0') { + $backend = 'JSON::PP'; + } + elsif ($backend eq '2') { + $backend = 'JSON::XS'; + } + $backend =~ s/\s+//g; + + my @backend_modules = split /,/, $backend; + while(my $module = shift @backend_modules) { + if ($module =~ /JSON::XS/) { + _load_xs($module, @backend_modules ? $_INSTALL_DONT_DIE : 0); + } + elsif ($module =~ /JSON::PP/) { + _load_pp($module); + } + elsif ($module =~ /JSON::backportPP/) { + _load_pp($module); + } + else { + Carp::croak "The value of environmental variable 'PERL_JSON_BACKEND' is invalid."; + } + last if $JSON::Backend; + } +} + + +sub import { + my $pkg = shift; + my @what_to_export; + my $no_export; + + for my $tag (@_) { + if ($tag eq '-support_by_pp') { + if (!$_ALLOW_UNSUPPORTED++) { + JSON::Backend::XS + ->support_by_pp(@PPOnlyMethods) if ($JSON::Backend->is_xs); + } + next; + } + elsif ($tag eq '-no_export') { + $no_export++, next; + } + elsif ( $tag eq '-convert_blessed_universally' ) { + my $org_encode = $JSON::Backend->can('encode'); + eval q| + require B; + local $^W; + no strict 'refs'; + *{"${JSON::Backend}\::encode"} = sub { + # only works with Perl 5.18+ + local *UNIVERSAL::TO_JSON = sub { + my $b_obj = B::svref_2object( $_[0] ); + return $b_obj->isa('B::HV') ? { %{ $_[0] } } + : $b_obj->isa('B::AV') ? [ @{ $_[0] } ] + : undef + ; + }; + $org_encode->(@_); + }; + | if ( !$_UNIV_CONV_BLESSED++ ); + next; + } + push @what_to_export, $tag; + } + + return if ($no_export); + + __PACKAGE__->export_to_level(1, $pkg, @what_to_export); +} + + +# OBSOLETED + +sub jsonToObj { + my $alternative = 'from_json'; + if (defined $_[0] and UNIVERSAL::isa($_[0], 'JSON')) { + shift @_; $alternative = 'decode'; + } + Carp::carp "'jsonToObj' will be obsoleted. Please use '$alternative' instead."; + return JSON::from_json(@_); +}; + +sub objToJson { + my $alternative = 'to_json'; + if (defined $_[0] and UNIVERSAL::isa($_[0], 'JSON')) { + shift @_; $alternative = 'encode'; + } + Carp::carp "'objToJson' will be obsoleted. Please use '$alternative' instead."; + JSON::to_json(@_); +}; + + +# INTERFACES + +sub to_json ($@) { + if ( + ref($_[0]) eq 'JSON' + or (@_ > 2 and $_[0] eq 'JSON') + ) { + Carp::croak "to_json should not be called as a method."; + } + my $json = JSON->new; + + if (@_ == 2 and ref $_[1] eq 'HASH') { + my $opt = $_[1]; + for my $method (keys %$opt) { + $json->$method( $opt->{$method} ); + } + } + + $json->encode($_[0]); +} + + +sub from_json ($@) { + if ( ref($_[0]) eq 'JSON' or $_[0] eq 'JSON' ) { + Carp::croak "from_json should not be called as a method."; + } + my $json = JSON->new; + + if (@_ == 2 and ref $_[1] eq 'HASH') { + my $opt = $_[1]; + for my $method (keys %$opt) { + $json->$method( $opt->{$method} ); + } + } + + return $json->decode( $_[0] ); +} + + + +sub true { $JSON::true } + +sub false { $JSON::false } + +sub boolean { + # might be called as method or as function, so pop() to get the last arg instead of shift() to get the first + pop() ? $JSON::true : $JSON::false +} + +sub null { undef; } + + +sub require_xs_version { $RequiredVersion{'JSON::XS'}; } + +sub backend { + my $proto = shift; + $JSON::Backend; +} + +#*module = *backend; + + +sub is_xs { + return $_[0]->backend->is_xs; +} + + +sub is_pp { + return $_[0]->backend->is_pp; +} + + +sub pureperl_only_methods { @PPOnlyMethods; } + + +sub property { + my ($self, $name, $value) = @_; + + if (@_ == 1) { + my %props; + for $name (@Properties) { + my $method = 'get_' . $name; + if ($name eq 'max_size') { + my $value = $self->$method(); + $props{$name} = $value == 1 ? 0 : $value; + next; + } + $props{$name} = $self->$method(); + } + return \%props; + } + elsif (@_ > 3) { + Carp::croak('property() can take only the option within 2 arguments.'); + } + elsif (@_ == 2) { + if ( my $method = $self->can('get_' . $name) ) { + if ($name eq 'max_size') { + my $value = $self->$method(); + return $value == 1 ? 0 : $value; + } + $self->$method(); + } + } + else { + $self->$name($value); + } + +} + + + +# INTERNAL + +sub __load_xs { + my ($module, $opt) = @_; + + $JSON::DEBUG and Carp::carp "Load $module."; + my $required_version = $RequiredVersion{$module} || ''; + + eval qq| + use $module $required_version (); + |; + + if ($@) { + if (defined $opt and $opt & $_INSTALL_DONT_DIE) { + $JSON::DEBUG and Carp::carp "Can't load $module...($@)"; + return 0; + } + Carp::croak $@; + } + $JSON::BackendModuleXS = $module; + return 1; +} + +sub _load_xs { + my ($module, $opt) = @_; + __load_xs($module, $opt) or return; + + my $data = join("", ); # this code is from Jcode 2.xx. + close(DATA); + eval $data; + JSON::Backend::XS->init($module); + + return 1; +}; + + +sub __load_pp { + my ($module, $opt) = @_; + + $JSON::DEBUG and Carp::carp "Load $module."; + my $required_version = $RequiredVersion{$module} || ''; + + eval qq| use $module $required_version () |; + + if ($@) { + if ( $module eq 'JSON::PP' ) { + $JSON::DEBUG and Carp::carp "Can't load $module ($@), so try to load JSON::backportPP"; + $module = 'JSON::backportPP'; + local $^W; # if PP installed but invalid version, backportPP redefines methods. + eval qq| require $module |; + } + Carp::croak $@ if $@; + } + $JSON::BackendModulePP = $module; + return 1; +} + +sub _load_pp { + my ($module, $opt) = @_; + __load_pp($module, $opt); + + JSON::Backend::PP->init($module); +}; + +# +# Helper classes for Backend Module (PP) +# + +package JSON::Backend::PP; + +sub init { + my ($class, $module) = @_; + + # name may vary, but the module should (always) be a JSON::PP + + local $^W; + no strict qw(refs); # this routine may be called after JSON::Backend::XS init was called. + *{"JSON::decode_json"} = \&{"JSON::PP::decode_json"}; + *{"JSON::encode_json"} = \&{"JSON::PP::encode_json"}; + *{"JSON::is_bool"} = \&{"JSON::PP::is_bool"}; + + $JSON::true = ${"JSON::PP::true"}; + $JSON::false = ${"JSON::PP::false"}; + + push @JSON::Backend::PP::ISA, 'JSON::PP'; + push @JSON::ISA, $class; + $JSON::Backend = $class; + $JSON::BackendModule = $module; + my $version = ${"$class\::VERSION"} = $module->VERSION; + $version =~ s/_//; + if ($version < 3.99) { + push @XSOnlyMethods, qw/allow_tags get_allow_tags/; + } else { + push @Properties, 'allow_tags'; + } + + for my $method (@XSOnlyMethods) { + *{"JSON::$method"} = sub { + Carp::carp("$method is not supported by $module $version."); + $_[0]; + }; + } + + return 1; +} + +sub is_xs { 0 }; +sub is_pp { 1 }; + +# +# To save memory, the below lines are read only when XS backend is used. +# + +package JSON; + +1; +__DATA__ + + +# +# Helper classes for Backend Module (XS) +# + +package JSON::Backend::XS; + +sub init { + my ($class, $module) = @_; + + local $^W; + no strict qw(refs); + *{"JSON::decode_json"} = \&{"$module\::decode_json"}; + *{"JSON::encode_json"} = \&{"$module\::encode_json"}; + *{"JSON::is_bool"} = \&{"$module\::is_bool"}; + + $JSON::true = ${"$module\::true"}; + $JSON::false = ${"$module\::false"}; + + push @JSON::Backend::XS::ISA, $module; + push @JSON::ISA, $class; + $JSON::Backend = $class; + $JSON::BackendModule = $module; + ${"$class\::VERSION"} = $module->VERSION; + + if ( $module->VERSION < 3 ) { + eval 'package JSON::PP::Boolean'; + push @{"$module\::Boolean::ISA"}, qw(JSON::PP::Boolean); + } + + for my $method (@PPOnlyMethods) { + *{"JSON::$method"} = sub { + Carp::carp("$method is not supported by $module."); + $_[0]; + }; + } + + return 1; +} + +sub is_xs { 1 }; +sub is_pp { 0 }; + +sub support_by_pp { + my ($class, @methods) = @_; + + JSON::__load_pp('JSON::PP'); + + local $^W; + no strict qw(refs); + + for my $method (@methods) { + my $pp_method = JSON::PP->can($method) or next; + *{"JSON::$method"} = sub { + if (!$_[0]->isa('JSON::PP')) { + my $xs_self = $_[0]; + my $pp_self = JSON::PP->new; + for (@Properties) { + my $getter = "get_$_"; + $pp_self->$_($xs_self->$getter); + } + $_[0] = $pp_self; + } + $pp_method->(@_); + }; + } + + $JSON::DEBUG and Carp::carp("set -support_by_pp mode."); +} + +1; +__END__ + +=head1 NAME + +JSON - JSON (JavaScript Object Notation) encoder/decoder + +=head1 SYNOPSIS + + use JSON; # imports encode_json, decode_json, to_json and from_json. + + # simple and fast interfaces (expect/generate UTF-8) + + $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; + $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; + + # OO-interface + + $json = JSON->new->allow_nonref; + + $json_text = $json->encode( $perl_scalar ); + $perl_scalar = $json->decode( $json_text ); + + $pretty_printed = $json->pretty->encode( $perl_scalar ); # pretty-printing + +=head1 DESCRIPTION + +This module is a thin wrapper for L-compatible modules with a few +additional features. All the backend modules convert a Perl data structure +to a JSON text and vice versa. This module uses L by default, +and when JSON::XS is not available, falls back on L, which is +in the Perl core since 5.14. If JSON::PP is not available either, this +module then falls back on JSON::backportPP (which is actually JSON::PP +in a different .pm file) bundled in the same distribution as this module. +You can also explicitly specify to use L, a fork of +JSON::XS by Reini Urban. + +All these backend modules have slight incompatibilities between them, +including extra features that other modules don't support, but as long as you +use only common features (most important ones are described below), migration +from backend to backend should be reasonably easy. For details, see each +backend module you use. + +=head1 CHOOSING BACKEND + +This module respects an environmental variable called C +when it decides a backend module to use. If this environmental variable is +not set, it tries to load JSON::XS, and if JSON::XS is not available, it +falls back on JSON::PP, and then JSON::backportPP if JSON::PP is not available +either. + +If you always don't want it to fall back on pure perl modules, set the +variable like this (C may be C, C and the likes, +depending on your environment): + + > export PERL_JSON_BACKEND=JSON::XS + +If you prefer Cpanel::JSON::XS to JSON::XS, then: + + > export PERL_JSON_BACKEND=Cpanel::JSON::XS,JSON::XS,JSON::PP + +You may also want to set this variable at the top of your test files, in order +not to be bothered with incompatibilities between backends (you need to wrap +this in C, and set before actually C-ing JSON module, as it decides +its backend as soon as it's loaded): + + BEGIN { $ENV{PERL_JSON_BACKEND}='JSON::backportPP'; } + use JSON; + +=head1 USING OPTIONAL FEATURES + +There are a few options you can set when you C this module. +These historical options are only kept for backward compatibility, +and should not be used in a new application. + +=over + +=item -support_by_pp + + BEGIN { $ENV{PERL_JSON_BACKEND} = 'JSON::XS' } + + use JSON -support_by_pp; + + my $json = JSON->new; + # escape_slash is for JSON::PP only. + $json->allow_nonref->escape_slash->encode("/"); + +With this option, this module loads its pure perl backend along with +its XS backend (if available), and lets the XS backend to watch if you set +a flag only JSON::PP supports. When you do, the internal JSON::XS object +is replaced with a newly created JSON::PP object with the setting copied +from the XS object, so that you can use JSON::PP flags (and its slower +C/C methods) from then on. In other words, this is not +something that allows you to hook JSON::XS to change its behavior while +keeping its speed. JSON::XS and JSON::PP objects are quite different +(JSON::XS object is a blessed scalar reference, while JSON::PP object is +a blessed hash reference), and can't share their internals. + +To avoid needless overhead (by copying settings), you are advised not +to use this option and just to use JSON::PP explicitly when you need +JSON::PP features. + +=item -convert_blessed_universally + + use JSON -convert_blessed_universally; + + my $json = JSON->new->allow_nonref->convert_blessed; + my $object = bless {foo => 'bar'}, 'Foo'; + $json->encode($object); # => {"foo":"bar"} + +JSON::XS-compatible backend modules don't encode blessed objects by +default (except for their boolean values, which are typically blessed +JSON::PP::Boolean objects). If you need to encode a data structure +that may contain objects, you usually need to look into the structure +and replace objects with alternative non-blessed values, or enable +C and provide a C method for each object's +(base) class that may be found in the structure, in order to let the +methods replace the objects with whatever scalar values the methods +return. + +If you need to serialise data structures that may contain arbitrary +objects, it's probably better to use other serialisers (such as +L or L for example), but if you do want to use +this module for that purpose, C<-convert_blessed_universally> option +may help, which tweaks C method of the backend to install +C method (locally) before encoding, so that +all the objects that don't have their own C method can +fall back on the method in the C namespace. Note that you +still need to enable C flag to actually encode +objects in a data structure, and C method +installed by this option only converts blessed hash/array references +into their unblessed clone (including private keys/values that are +not supposed to be exposed). Other blessed references will be +converted into null. + +This feature is experimental and may be removed in the future. + +=item -no_export + +When you don't want to import functional interfaces from a module, you +usually supply C<()> to its C statement. + + use JSON (); # no functional interfaces + +If you don't want to import functional interfaces, but you also want to +use any of the above options, add C<-no_export> to the option list. + + # no functional interfaces, while JSON::PP support is enabled. + use JSON -support_by_pp, -no_export; + +=back + +=head1 FUNCTIONAL INTERFACE + +This section is taken from JSON::XS. C and C +are exported by default. + +This module also exports C and C for backward +compatibility. These are slower, and may expect/generate different stuff +from what C and C do, depending on their +options. It's better just to use Object-Oriented interfaces than using +these two functions. + +=head2 encode_json + + $json_text = encode_json $perl_scalar + +Converts the given Perl data structure to a UTF-8 encoded, binary string +(that is, the string contains octets only). Croaks on error. + +This function call is functionally identical to: + + $json_text = JSON->new->utf8->encode($perl_scalar) + +Except being faster. + +=head2 decode_json + + $perl_scalar = decode_json $json_text + +The opposite of C: expects an UTF-8 (binary) string and tries +to parse that as an UTF-8 encoded JSON text, returning the resulting +reference. Croaks on error. + +This function call is functionally identical to: + + $perl_scalar = JSON->new->utf8->decode($json_text) + +Except being faster. + +=head2 to_json + + $json_text = to_json($perl_scalar[, $optional_hashref]) + +Converts the given Perl data structure to a Unicode string by default. +Croaks on error. + +Basically, this function call is functionally identical to: + + $json_text = JSON->new->encode($perl_scalar) + +Except being slower. + +You can pass an optional hash reference to modify its behavior, but +that may change what C expects/generates (see +C for details). + + $json_text = to_json($perl_scalar, {utf8 => 1, pretty => 1}) + # => JSON->new->utf8(1)->pretty(1)->encode($perl_scalar) + +=head2 from_json + + $perl_scalar = from_json($json_text[, $optional_hashref]) + +The opposite of C: expects a Unicode string and tries +to parse it, returning the resulting reference. Croaks on error. + +Basically, this function call is functionally identical to: + + $perl_scalar = JSON->new->decode($json_text) + +You can pass an optional hash reference to modify its behavior, but +that may change what C expects/generates (see +C for details). + + $perl_scalar = from_json($json_text, {utf8 => 1}) + # => JSON->new->utf8(1)->decode($json_text) + +=head2 JSON::is_bool + + $is_boolean = JSON::is_bool($scalar) + +Returns true if the passed scalar represents either JSON::true or +JSON::false, two constants that act like C<1> and C<0> respectively +and are also used to represent JSON C and C in Perl strings. + +See L, below, for more information on how JSON values are mapped to +Perl. + +=head1 COMMON OBJECT-ORIENTED INTERFACE + +This section is also taken from JSON::XS. + +The object oriented interface lets you configure your own encoding or +decoding style, within the limits of supported formats. + +=head2 new + + $json = JSON->new + +Creates a new JSON::XS-compatible backend object that can be used to de/encode JSON +strings. All boolean flags described below are by default I +(with the exception of C, which defaults to I since +version C<4.0>). + +The mutators for flags all return the backend object again and thus calls can +be chained: + + my $json = JSON->new->utf8->space_after->encode({a => [1,2]}) + => {"a": [1, 2]} + +=head2 ascii + + $json = $json->ascii([$enable]) + + $enabled = $json->get_ascii + +If C<$enable> is true (or missing), then the C method will not +generate characters outside the code range C<0..127> (which is ASCII). Any +Unicode characters outside that range will be escaped using either a +single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, +as per RFC4627. The resulting encoded JSON text can be treated as a native +Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string, +or any other superset of ASCII. + +If C<$enable> is false, then the C method will not escape Unicode +characters unless required by the JSON syntax or other flags. This results +in a faster and more compact format. + +See also the section I later in this document. + +The main use for this flag is to produce JSON texts that can be +transmitted over a 7-bit channel, as the encoded JSON texts will not +contain any 8 bit characters. + + JSON->new->ascii(1)->encode([chr 0x10401]) + => ["\ud801\udc01"] + +=head2 latin1 + + $json = $json->latin1([$enable]) + + $enabled = $json->get_latin1 + +If C<$enable> is true (or missing), then the C method will encode +the resulting JSON text as latin1 (or iso-8859-1), escaping any characters +outside the code range C<0..255>. The resulting string can be treated as a +latin1-encoded JSON text or a native Unicode string. The C method +will not be affected in any way by this flag, as C by default +expects Unicode, which is a strict superset of latin1. + +If C<$enable> is false, then the C method will not escape Unicode +characters unless required by the JSON syntax or other flags. + +See also the section I later in this document. + +The main use for this flag is efficiently encoding binary data as JSON +text, as most octets will not be escaped, resulting in a smaller encoded +size. The disadvantage is that the resulting JSON text is encoded +in latin1 (and must correctly be treated as such when storing and +transferring), a rare encoding for JSON. It is therefore most useful when +you want to store data structures known to contain binary data efficiently +in files or databases, not when talking to other JSON encoders/decoders. + + JSON->new->latin1->encode (["\x{89}\x{abc}"] + => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) + +=head2 utf8 + + $json = $json->utf8([$enable]) + + $enabled = $json->get_utf8 + +If C<$enable> is true (or missing), then the C method will encode +the JSON result into UTF-8, as required by many protocols, while the +C method expects to be handled an UTF-8-encoded string. Please +note that UTF-8-encoded strings do not contain any characters outside the +range C<0..255>, they are thus useful for bytewise/binary I/O. In future +versions, enabling this option might enable autodetection of the UTF-16 +and UTF-32 encoding families, as described in RFC4627. + +If C<$enable> is false, then the C method will return the JSON +string as a (non-encoded) Unicode string, while C expects thus a +Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs +to be done yourself, e.g. using the Encode module. + +See also the section I later in this document. + +Example, output UTF-16BE-encoded JSON: + + use Encode; + $jsontext = encode "UTF-16BE", JSON->new->encode ($object); + +Example, decode UTF-32LE-encoded JSON: + + use Encode; + $object = JSON->new->decode (decode "UTF-32LE", $jsontext); + +=head2 pretty + + $json = $json->pretty([$enable]) + +This enables (or disables) all of the C, C and +C (and in the future possibly more) flags in one call to +generate the most readable (or most compact) form possible. + +=head2 indent + + $json = $json->indent([$enable]) + + $enabled = $json->get_indent + +If C<$enable> is true (or missing), then the C method will use a multiline +format as output, putting every array member or object/hash key-value pair +into its own line, indenting them properly. + +If C<$enable> is false, no newlines or indenting will be produced, and the +resulting JSON text is guaranteed not to contain any C. + +This setting has no effect when decoding JSON texts. + +=head2 space_before + + $json = $json->space_before([$enable]) + + $enabled = $json->get_space_before + +If C<$enable> is true (or missing), then the C method will add an extra +optional space before the C<:> separating keys from values in JSON objects. + +If C<$enable> is false, then the C method will not add any extra +space at those places. + +This setting has no effect when decoding JSON texts. You will also +most likely combine this setting with C. + +Example, space_before enabled, space_after and indent disabled: + + {"key" :"value"} + +=head2 space_after + + $json = $json->space_after([$enable]) + + $enabled = $json->get_space_after + +If C<$enable> is true (or missing), then the C method will add an extra +optional space after the C<:> separating keys from values in JSON objects +and extra whitespace after the C<,> separating key-value pairs and array +members. + +If C<$enable> is false, then the C method will not add any extra +space at those places. + +This setting has no effect when decoding JSON texts. + +Example, space_before and indent disabled, space_after enabled: + + {"key": "value"} + +=head2 relaxed + + $json = $json->relaxed([$enable]) + + $enabled = $json->get_relaxed + +If C<$enable> is true (or missing), then C will accept some +extensions to normal JSON syntax (see below). C will not be +affected in any way. I. I suggest only to use this option to +parse application-specific files written by humans (configuration files, +resource files etc.) + +If C<$enable> is false (the default), then C will only accept +valid JSON texts. + +Currently accepted extensions are: + +=over 4 + +=item * list items can have an end-comma + +JSON I array elements and key-value pairs with commas. This +can be annoying if you write JSON texts manually and want to be able to +quickly append elements, so this extension accepts comma at the end of +such items not just between them: + + [ + 1, + 2, <- this comma not normally allowed + ] + { + "k1": "v1", + "k2": "v2", <- this comma not normally allowed + } + +=item * shell-style '#'-comments + +Whenever JSON allows whitespace, shell-style comments are additionally +allowed. They are terminated by the first carriage-return or line-feed +character, after which more white-space and comments are allowed. + + [ + 1, # this comment not allowed in JSON + # neither this one... + ] + +=back + +=head2 canonical + + $json = $json->canonical([$enable]) + + $enabled = $json->get_canonical + +If C<$enable> is true (or missing), then the C method will output JSON objects +by sorting their keys. This is adding a comparatively high overhead. + +If C<$enable> is false, then the C method will output key-value +pairs in the order Perl stores them (which will likely change between runs +of the same script, and can change even within the same run from 5.18 +onwards). + +This option is useful if you want the same data structure to be encoded as +the same JSON text (given the same overall settings). If it is disabled, +the same hash might be encoded differently even if contains the same data, +as key-value pairs have no inherent ordering in Perl. + +This setting has no effect when decoding JSON texts. + +This setting has currently no effect on tied hashes. + +=head2 allow_nonref + + $json = $json->allow_nonref([$enable]) + + $enabled = $json->get_allow_nonref + +Unlike other boolean options, this option is enabled by default beginning +with version C<4.0>. + +If C<$enable> is true (or missing), then the C method can convert a +non-reference into its corresponding string, number or null JSON value, +which is an extension to RFC4627. Likewise, C will accept those JSON +values instead of croaking. + +If C<$enable> is false, then the C method will croak if it isn't +passed an arrayref or hashref, as JSON texts must either be an object +or array. Likewise, C will croak if given something that is not a +JSON object or array. + +Example, encode a Perl scalar as JSON value with enabled C, +resulting in an invalid JSON text: + + JSON->new->allow_nonref->encode ("Hello, World!") + => "Hello, World!" + +=head2 allow_unknown + + $json = $json->allow_unknown ([$enable]) + + $enabled = $json->get_allow_unknown + +If C<$enable> is true (or missing), then C will I throw an +exception when it encounters values it cannot represent in JSON (for +example, filehandles) but instead will encode a JSON C value. Note +that blessed objects are not included here and are handled separately by +c. + +If C<$enable> is false (the default), then C will throw an +exception when it encounters anything it cannot encode as JSON. + +This option does not affect C in any way, and it is recommended to +leave it off unless you know your communications partner. + +=head2 allow_blessed + + $json = $json->allow_blessed([$enable]) + + $enabled = $json->get_allow_blessed + +See L for details. + +If C<$enable> is true (or missing), then the C method will not +barf when it encounters a blessed reference that it cannot convert +otherwise. Instead, a JSON C value is encoded instead of the object. + +If C<$enable> is false (the default), then C will throw an +exception when it encounters a blessed object that it cannot convert +otherwise. + +This setting has no effect on C. + +=head2 convert_blessed + + $json = $json->convert_blessed([$enable]) + + $enabled = $json->get_convert_blessed + +See L for details. + +If C<$enable> is true (or missing), then C, upon encountering a +blessed object, will check for the availability of the C method +on the object's class. If found, it will be called in scalar context and +the resulting scalar will be encoded instead of the object. + +The C method may safely call die if it wants. If C +returns other blessed objects, those will be handled in the same +way. C must take care of not causing an endless recursion cycle +(== crash) in this case. The name of C was chosen because other +methods called by the Perl core (== not by the user of the object) are +usually in upper case letters and to avoid collisions with any C +function or method. + +If C<$enable> is false (the default), then C will not consider +this type of conversion. + +This setting has no effect on C. + +=head2 allow_tags (since version 3.0) + + $json = $json->allow_tags([$enable]) + + $enabled = $json->get_allow_tags + +See L for details. + +If C<$enable> is true (or missing), then C, upon encountering a +blessed object, will check for the availability of the C method on +the object's class. If found, it will be used to serialise the object into +a nonstandard tagged JSON value (that JSON decoders cannot decode). + +It also causes C to parse such tagged JSON values and deserialise +them via a call to the C method. + +If C<$enable> is false (the default), then C will not consider +this type of conversion, and tagged JSON values will cause a parse error +in C, as if tags were not part of the grammar. + +=head2 boolean_values (since version 4.0) + + $json->boolean_values([$false, $true]) + + ($false, $true) = $json->get_boolean_values + +By default, JSON booleans will be decoded as overloaded +C<$JSON::false> and C<$JSON::true> objects. + +With this method you can specify your own boolean values for decoding - +on decode, JSON C will be decoded as a copy of C<$false>, and JSON +C will be decoded as C<$true> ("copy" here is the same thing as +assigning a value to another variable, i.e. C<$copy = $false>). + +This is useful when you want to pass a decoded data structure directly +to other serialisers like YAML, Data::MessagePack and so on. + +Note that this works only when you C. You can set incompatible +boolean objects (like L), but when you C a data structure +with such boolean objects, you still need to enable C +(and add a C method if necessary). + +Calling this method without any arguments will reset the booleans +to their default values. + +C will return both C<$false> and C<$true> values, or +the empty list when they are set to the default. + +=head2 filter_json_object + + $json = $json->filter_json_object([$coderef]) + +When C<$coderef> is specified, it will be called from C each +time it decodes a JSON object. The only argument is a reference to +the newly-created hash. If the code references returns a single scalar +(which need not be a reference), this value (or rather a copy of it) is +inserted into the deserialised data structure. If it returns an empty +list (NOTE: I C, which is a valid scalar), the original +deserialised hash will be inserted. This setting can slow down decoding +considerably. + +When C<$coderef> is omitted or undefined, any existing callback will +be removed and C will not change the deserialised hash in any +way. + +Example, convert all JSON objects into the integer 5: + + my $js = JSON->new->filter_json_object(sub { 5 }); + # returns [5] + $js->decode('[{}]'); + # returns 5 + $js->decode('{"a":1, "b":2}'); + +=head2 filter_json_single_key_object + + $json = $json->filter_json_single_key_object($key [=> $coderef]) + +Works remotely similar to C, but is only called for +JSON objects having a single key named C<$key>. + +This C<$coderef> is called before the one specified via +C, if any. It gets passed the single value in the JSON +object. If it returns a single value, it will be inserted into the data +structure. If it returns nothing (not even C but the empty list), +the callback from C will be called next, as if no +single-key callback were specified. + +If C<$coderef> is omitted or undefined, the corresponding callback will be +disabled. There can only ever be one callback for a given key. + +As this callback gets called less often then the C +one, decoding speed will not usually suffer as much. Therefore, single-key +objects make excellent targets to serialise Perl objects into, especially +as single-key JSON objects are as close to the type-tagged value concept +as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not +support this in any way, so you need to make sure your data never looks +like a serialised Perl hash. + +Typical names for the single object key are C<__class_whatever__>, or +C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even +things like C<__class_md5sum(classname)__>, to reduce the risk of clashing +with real hashes. + +Example, decode JSON objects of the form C<< { "__widget__" => } >> +into the corresponding C<< $WIDGET{} >> object: + + # return whatever is in $WIDGET{5}: + JSON + ->new + ->filter_json_single_key_object (__widget__ => sub { + $WIDGET{ $_[0] } + }) + ->decode ('{"__widget__": 5') + + # this can be used with a TO_JSON method in some "widget" class + # for serialisation to json: + sub WidgetBase::TO_JSON { + my ($self) = @_; + + unless ($self->{id}) { + $self->{id} = ..get..some..id..; + $WIDGET{$self->{id}} = $self; + } + + { __widget__ => $self->{id} } + } + +=head2 max_depth + + $json = $json->max_depth([$maximum_nesting_depth]) + + $max_depth = $json->get_max_depth + +Sets the maximum nesting level (default C<512>) accepted while encoding +or decoding. If a higher nesting level is detected in JSON text or a Perl +data structure, then the encoder and decoder will stop and croak at that +point. + +Nesting level is defined by number of hash- or arrayrefs that the encoder +needs to traverse to reach a given point or the number of C<{> or C<[> +characters without their matching closing parenthesis crossed to reach a +given character in a string. + +Setting the maximum depth to one disallows any nesting, so that ensures +that the object is only a single hash/object or array. + +If no argument is given, the highest possible setting will be used, which +is rarely useful. + +See L for more info on why this is useful. + +=head2 max_size + + $json = $json->max_size([$maximum_string_size]) + + $max_size = $json->get_max_size + +Set the maximum length a JSON text may have (in bytes) where decoding is +being attempted. The default is C<0>, meaning no limit. When C +is called on a string that is longer then this many bytes, it will not +attempt to decode the string but throw an exception. This setting has no +effect on C (yet). + +If no argument is given, the limit check will be deactivated (same as when +C<0> is specified). + +See L for more info on why this is useful. + +=head2 encode + + $json_text = $json->encode($perl_scalar) + +Converts the given Perl value or data structure to its JSON +representation. Croaks on error. + +=head2 decode + + $perl_scalar = $json->decode($json_text) + +The opposite of C: expects a JSON text and tries to parse it, +returning the resulting simple scalar or reference. Croaks on error. + +=head2 decode_prefix + + ($perl_scalar, $characters) = $json->decode_prefix($json_text) + +This works like the C method, but instead of raising an exception +when there is trailing garbage after the first JSON object, it will +silently stop parsing there and return the number of characters consumed +so far. + +This is useful if your JSON texts are not delimited by an outer protocol +and you need to know where the JSON text ends. + + JSON->new->decode_prefix ("[1] the tail") + => ([1], 3) + +=head1 ADDITIONAL METHODS + +The following methods are for this module only. + +=head2 backend + + $backend = $json->backend + +Since 2.92, C method returns an abstract backend module used currently, +which should be JSON::Backend::XS (which inherits JSON::XS or Cpanel::JSON::XS), +or JSON::Backend::PP (which inherits JSON::PP), not to monkey-patch the actual +backend module globally. + +If you need to know what is used actually, use C, instead of string comparison. + +=head2 is_xs + + $boolean = $json->is_xs + +Returns true if the backend inherits JSON::XS or Cpanel::JSON::XS. + +=head2 is_pp + + $boolean = $json->is_pp + +Returns true if the backend inherits JSON::PP. + +=head2 property + + $settings = $json->property() + +Returns a reference to a hash that holds all the common flag settings. + + $json = $json->property('utf8' => 1) + $value = $json->property('utf8') # 1 + +You can use this to get/set a value of a particular flag. + +=head2 boolean + + $boolean_object = JSON->boolean($scalar) + +Returns $JSON::true if $scalar contains a true value, $JSON::false otherwise. +You can use this as a full-qualified function (C). + +=head1 INCREMENTAL PARSING + +This section is also taken from JSON::XS. + +In some cases, there is the need for incremental parsing of JSON +texts. While this module always has to keep both JSON text and resulting +Perl data structure in memory at one time, it does allow you to parse a +JSON stream incrementally. It does so by accumulating text until it has +a full JSON object, which it then can decode. This process is similar to +using C to see if a full JSON object is available, but +is much more efficient (and can be implemented with a minimum of method +calls). + +This module will only attempt to parse the JSON text once it is sure it +has enough text to get a decisive result, using a very simple but +truly incremental parser. This means that it sometimes won't stop as +early as the full parser, for example, it doesn't detect mismatched +parentheses. The only thing it guarantees is that it starts decoding as +soon as a syntactically valid JSON text has been seen. This means you need +to set resource limits (e.g. C) to ensure the parser will stop +parsing in the presence if syntax errors. + +The following methods implement this incremental parser. + +=head2 incr_parse + + $json->incr_parse( [$string] ) # void context + + $obj_or_undef = $json->incr_parse( [$string] ) # scalar context + + @obj_or_empty = $json->incr_parse( [$string] ) # list context + +This is the central parsing function. It can both append new text and +extract objects from the stream accumulated so far (both of these +functions are optional). + +If C<$string> is given, then this string is appended to the already +existing JSON fragment stored in the C<$json> object. + +After that, if the function is called in void context, it will simply +return without doing anything further. This can be used to add more text +in as many chunks as you want. + +If the method is called in scalar context, then it will try to extract +exactly I JSON object. If that is successful, it will return this +object, otherwise it will return C. If there is a parse error, +this method will croak just as C would do (one can then use +C to skip the erroneous part). This is the most common way of +using the method. + +And finally, in list context, it will try to extract as many objects +from the stream as it can find and return them, or the empty list +otherwise. For this to work, there must be no separators (other than +whitespace) between the JSON objects or arrays, instead they must be +concatenated back-to-back. If an error occurs, an exception will be +raised as in the scalar context case. Note that in this case, any +previously-parsed JSON texts will be lost. + +Example: Parse some JSON arrays/objects in a given string and return +them. + + my @objs = JSON->new->incr_parse ("[5][7][1,2]"); + +=head2 incr_text + + $lvalue_string = $json->incr_text + +This method returns the currently stored JSON fragment as an lvalue, that +is, you can manipulate it. This I works when a preceding call to +C in I successfully returned an object. Under +all other circumstances you must not call this function (I mean it. +although in simple tests it might actually work, it I fail under +real world conditions). As a special exception, you can also call this +method before having parsed anything. + +That means you can only use this function to look at or manipulate text +before or after complete JSON objects, not while the parser is in the +middle of parsing a JSON object. + +This function is useful in two cases: a) finding the trailing text after a +JSON object or b) parsing multiple JSON objects separated by non-JSON text +(such as commas). + +=head2 incr_skip + + $json->incr_skip + +This will reset the state of the incremental parser and will remove +the parsed text from the input buffer so far. This is useful after +C died, in which case the input buffer and incremental parser +state is left unchanged, to skip the text parsed so far and to reset the +parse state. + +The difference to C is that only text until the parse error +occurred is removed. + +=head2 incr_reset + + $json->incr_reset + +This completely resets the incremental parser, that is, after this call, +it will be as if the parser had never parsed anything. + +This is useful if you want to repeatedly parse JSON objects and want to +ignore any trailing data, which means you have to reset the parser after +each successful decode. + +=head1 MAPPING + +Most of this section is also taken from JSON::XS. + +This section describes how the backend modules map Perl values to JSON values and +vice versa. These mappings are designed to "do the right thing" in most +circumstances automatically, preserving round-tripping characteristics +(what you put in comes out as something equivalent). + +For the more enlightened: note that in the following descriptions, +lowercase I refers to the Perl interpreter, while uppercase I +refers to the abstract Perl language itself. + +=head2 JSON -> PERL + +=over 4 + +=item object + +A JSON object becomes a reference to a hash in Perl. No ordering of object +keys is preserved (JSON does not preserver object key ordering itself). + +=item array + +A JSON array becomes a reference to an array in Perl. + +=item string + +A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON +are represented by the same codepoints in the Perl string, so no manual +decoding is necessary. + +=item number + +A JSON number becomes either an integer, numeric (floating point) or +string scalar in perl, depending on its range and any fractional parts. On +the Perl level, there is no difference between those as Perl handles all +the conversion details, but an integer may take slightly less memory and +might represent more values exactly than floating point numbers. + +If the number consists of digits only, this module will try to represent +it as an integer value. If that fails, it will try to represent it as +a numeric (floating point) value if that is possible without loss of +precision. Otherwise it will preserve the number as a string value (in +which case you lose roundtripping ability, as the JSON number will be +re-encoded to a JSON string). + +Numbers containing a fractional or exponential part will always be +represented as numeric (floating point) values, possibly at a loss of +precision (in which case you might lose perfect roundtripping ability, but +the JSON number will still be re-encoded as a JSON number). + +Note that precision is not accuracy - binary floating point values cannot +represent most decimal fractions exactly, and when converting from and to +floating point, this module only guarantees precision up to but not including +the least significant bit. + +=item true, false + +These JSON atoms become C and C, +respectively. They are overloaded to act almost exactly like the numbers +C<1> and C<0>. You can check whether a scalar is a JSON boolean by using +the C function. + +=item null + +A JSON null atom becomes C in Perl. + +=item shell-style comments (C<< # I >>) + +As a nonstandard extension to the JSON syntax that is enabled by the +C setting, shell-style comments are allowed. They can start +anywhere outside strings and go till the end of the line. + +=item tagged values (C<< (I)I >>). + +Another nonstandard extension to the JSON syntax, enabled with the +C setting, are tagged values. In this implementation, the +I must be a perl package/class name encoded as a JSON string, and the +I must be a JSON array encoding optional constructor arguments. + +See L, below, for details. + +=back + + +=head2 PERL -> JSON + +The mapping from Perl to JSON is slightly more difficult, as Perl is a +truly typeless language, so we can only guess which JSON type is meant by +a Perl value. + +=over 4 + +=item hash references + +Perl hash references become JSON objects. As there is no inherent +ordering in hash keys (or JSON objects), they will usually be encoded +in a pseudo-random order. This module can optionally sort the hash keys +(determined by the I flag), so the same data structure will +serialise to the same JSON text (given same settings and version of +the same backend), but this incurs a runtime overhead and is only rarely useful, +e.g. when you want to compare some JSON text against another for equality. + +=item array references + +Perl array references become JSON arrays. + +=item other references + +Other unblessed references are generally not allowed and will cause an +exception to be thrown, except for references to the integers C<0> and +C<1>, which get turned into C and C atoms in JSON. You can +also use C and C to improve readability. + + encode_json [\0,JSON::true] # yields [false,true] + +=item JSON::true, JSON::false, JSON::null + +These special values become JSON true and JSON false values, +respectively. You can also use C<\1> and C<\0> directly if you want. + +=item blessed objects + +Blessed objects are not directly representable in JSON, but C +allows various ways of handling objects. See L, +below, for details. + +=item simple scalars + +Simple Perl scalars (any scalar that is not a reference) are the most +difficult objects to encode: this module will encode undefined scalars as +JSON C values, scalars that have last been used in a string context +before encoding as JSON strings, and anything else as number value: + + # dump as number + encode_json [2] # yields [2] + encode_json [-3.0e17] # yields [-3e+17] + my $value = 5; encode_json [$value] # yields [5] + + # used as string, so dump as string + print $value; + encode_json [$value] # yields ["5"] + + # undef becomes null + encode_json [undef] # yields [null] + +You can force the type to be a string by stringifying it: + + my $x = 3.1; # some variable containing a number + "$x"; # stringified + $x .= ""; # another, more awkward way to stringify + print $x; # perl does it for you, too, quite often + +You can force the type to be a number by numifying it: + + my $x = "3"; # some variable containing a string + $x += 0; # numify it, ensuring it will be dumped as a number + $x *= 1; # same thing, the choice is yours. + +You can not currently force the type in other, less obscure, ways. Tell me +if you need this capability (but don't forget to explain why it's needed +:). + +Since version 2.91_01, JSON::PP uses a different number detection logic +that converts a scalar that is possible to turn into a number safely. +The new logic is slightly faster, and tends to help people who use older +perl or who want to encode complicated data structure. However, this may +results in a different JSON text from the one JSON::XS encodes (and +thus may break tests that compare entire JSON texts). If you do +need the previous behavior for better compatibility or for finer control, +set PERL_JSON_PP_USE_B environmental variable to true before you +C JSON. + +Note that numerical precision has the same meaning as under Perl (so +binary to decimal conversion follows the same rules as in Perl, which +can differ to other languages). Also, your perl interpreter might expose +extensions to the floating point numbers of your platform, such as +infinities or NaN's - these cannot be represented in JSON, and it is an +error to pass those in. + +JSON.pm backend modules trust what you pass to C method +(or C function) is a clean, validated data structure with +values that can be represented as valid JSON values only, because it's +not from an external data source (as opposed to JSON texts you pass to +C or C, which JSON backends consider tainted and +don't trust). As JSON backends don't know exactly what you and consumers +of your JSON texts want the unexpected values to be (you may want to +convert them into null, or to stringify them with or without +normalisation (string representation of infinities/NaN may vary +depending on platforms), or to croak without conversion), you're advised +to do what you and your consumers need before you encode, and also not +to numify values that may start with values that look like a number +(including infinities/NaN), without validating. + +=back + +=head2 OBJECT SERIALISATION + +As JSON cannot directly represent Perl objects, you have to choose between +a pure JSON representation (without the ability to deserialise the object +automatically again), and a nonstandard extension to the JSON syntax, +tagged values. + +=head3 SERIALISATION + +What happens when this module encounters a Perl object depends on the +C, C and C settings, which +are used in this order: + +=over 4 + +=item 1. C is enabled and the object has a C method. + +In this case, C creates a tagged JSON value, using a nonstandard +extension to the JSON syntax. + +This works by invoking the C method on the object, with the first +argument being the object to serialise, and the second argument being the +constant string C to distinguish it from other serialisers. + +The C method can return any number of values (i.e. zero or +more). These values and the package/classname of the object will then be +encoded as a tagged JSON value in the following format: + + ("classname")[FREEZE return values...] + +e.g.: + + ("URI")["http://www.google.com/"] + ("MyDate")[2013,10,29] + ("ImageData::JPEG")["Z3...VlCg=="] + +For example, the hypothetical C C method might use the +objects C and C members to encode the object: + + sub My::Object::FREEZE { + my ($self, $serialiser) = @_; + + ($self->{type}, $self->{id}) + } + +=item 2. C is enabled and the object has a C method. + +In this case, the C method of the object is invoked in scalar +context. It must return a single scalar that can be directly encoded into +JSON. This scalar replaces the object in the JSON text. + +For example, the following C method will convert all L +objects to JSON strings when serialised. The fact that these values +originally were L objects is lost. + + sub URI::TO_JSON { + my ($uri) = @_; + $uri->as_string + } + +=item 3. C is enabled. + +The object will be serialised as a JSON null value. + +=item 4. none of the above + +If none of the settings are enabled or the respective methods are missing, +this module throws an exception. + +=back + +=head3 DESERIALISATION + +For deserialisation there are only two cases to consider: either +nonstandard tagging was used, in which case C decides, +or objects cannot be automatically be deserialised, in which +case you can use postprocessing or the C or +C callbacks to get some real objects our of +your JSON. + +This section only considers the tagged value case: a tagged JSON object +is encountered during decoding and C is disabled, a parse +error will result (as if tagged values were not part of the grammar). + +If C is enabled, this module will look up the C method +of the package/classname used during serialisation (it will not attempt +to load the package as a Perl module). If there is no such method, the +decoding will fail with an error. + +Otherwise, the C method is invoked with the classname as first +argument, the constant string C as second argument, and all the +values from the JSON array (the values originally returned by the +C method) as remaining arguments. + +The method must then return the object. While technically you can return +any Perl scalar, you might have to enable the C setting to +make that work in all cases, so better return an actual blessed reference. + +As an example, let's implement a C function that regenerates the +C from the C example earlier: + + sub My::Object::THAW { + my ($class, $serialiser, $type, $id) = @_; + + $class->new (type => $type, id => $id) + } + + +=head1 ENCODING/CODESET FLAG NOTES + +This section is taken from JSON::XS. + +The interested reader might have seen a number of flags that signify +encodings or codesets - C, C and C. There seems to be +some confusion on what these do, so here is a short comparison: + +C controls whether the JSON text created by C (and expected +by C) is UTF-8 encoded or not, while C and C only +control whether C escapes character values outside their respective +codeset range. Neither of these flags conflict with each other, although +some combinations make less sense than others. + +Care has been taken to make all flags symmetrical with respect to +C and C, that is, texts encoded with any combination of +these flag values will be correctly decoded when the same flags are used +- in general, if you use different flag settings while encoding vs. when +decoding you likely have a bug somewhere. + +Below comes a verbose discussion of these flags. Note that a "codeset" is +simply an abstract set of character-codepoint pairs, while an encoding +takes those codepoint numbers and I them, in our case into +octets. Unicode is (among other things) a codeset, UTF-8 is an encoding, +and ISO-8859-1 (= latin 1) and ASCII are both codesets I encodings at +the same time, which can be confusing. + +=over 4 + +=item C flag disabled + +When C is disabled (the default), then C/C generate +and expect Unicode strings, that is, characters with high ordinal Unicode +values (> 255) will be encoded as such characters, and likewise such +characters are decoded as-is, no changes to them will be done, except +"(re-)interpreting" them as Unicode codepoints or Unicode characters, +respectively (to Perl, these are the same thing in strings unless you do +funny/weird/dumb stuff). + +This is useful when you want to do the encoding yourself (e.g. when you +want to have UTF-16 encoded JSON texts) or when some other layer does +the encoding for you (for example, when printing to a terminal using a +filehandle that transparently encodes to UTF-8 you certainly do NOT want +to UTF-8 encode your data first and have Perl encode it another time). + +=item C flag enabled + +If the C-flag is enabled, C/C will encode all +characters using the corresponding UTF-8 multi-byte sequence, and will +expect your input strings to be encoded as UTF-8, that is, no "character" +of the input string must have any value > 255, as UTF-8 does not allow +that. + +The C flag therefore switches between two modes: disabled means you +will get a Unicode string in Perl, enabled means you get an UTF-8 encoded +octet/binary string in Perl. + +=item C or C flags enabled + +With C (or C) enabled, C will escape characters +with ordinal values > 255 (> 127 with C) and encode the remaining +characters as specified by the C flag. + +If C is disabled, then the result is also correctly encoded in those +character sets (as both are proper subsets of Unicode, meaning that a +Unicode string with all character values < 256 is the same thing as a +ISO-8859-1 string, and a Unicode string with all character values < 128 is +the same thing as an ASCII string in Perl). + +If C is enabled, you still get a correct UTF-8-encoded string, +regardless of these flags, just some more characters will be escaped using +C<\uXXXX> then before. + +Note that ISO-8859-1-I strings are not compatible with UTF-8 +encoding, while ASCII-encoded strings are. That is because the ISO-8859-1 +encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I being +a subset of Unicode), while ASCII is. + +Surprisingly, C will ignore these flags and so treat all input +values as governed by the C flag. If it is disabled, this allows you +to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of +Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings. + +So neither C nor C are incompatible with the C flag - +they only govern when the JSON output engine escapes a character or not. + +The main use for C is to relatively efficiently store binary data +as JSON, at the expense of breaking compatibility with most JSON decoders. + +The main use for C is to force the output to not contain characters +with values > 127, which means you can interpret the resulting string +as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and +8-bit-encoding, and still get the same data structure back. This is useful +when your channel for JSON transfer is not 8-bit clean or the encoding +might be mangled in between (e.g. in mail), and works because ASCII is a +proper subset of most 8-bit and multibyte encodings in use in the world. + +=back + +=head1 BACKWARD INCOMPATIBILITY + +Since version 2.90, stringification (and string comparison) for +C and C has not been overloaded. It shouldn't +matter as long as you treat them as boolean values, but a code that +expects they are stringified as "true" or "false" doesn't work as +you have expected any more. + + if (JSON::true eq 'true') { # now fails + + print "The result is $JSON::true now."; # => The result is 1 now. + +And now these boolean values don't inherit JSON::Boolean, either. +When you need to test a value is a JSON boolean value or not, use +C function, instead of testing the value inherits +a particular boolean class or not. + +=head1 BUGS + +Please report bugs on backend selection and additional features +this module provides to RT or GitHub issues for this module: + +L + +L + +As for bugs on a specific behavior, please report to the author +of the backend module you are using. + +As for new features and requests to change common behaviors, please +ask the author of JSON::XS (Marc Lehmann, Eschmorp[at]schmorp.deE) +first, by email (important!), to keep compatibility among JSON.pm +backends. + +=head1 SEE ALSO + +L, L, L for backends. + +L, an alternative that prefers Cpanel::JSON::XS. + +C(L) + +RFC7159 (L) + +RFC8259 (L) + +=head1 AUTHOR + +Makamaka Hannyaharamitu, Emakamaka[at]cpan.orgE + +JSON::XS was written by Marc Lehmann Eschmorp[at]schmorp.deE + +The release of this new version owes to the courtesy of Marc Lehmann. + +=head1 CURRENT MAINTAINER + +Kenichi Ishigaki, Eishigaki[at]cpan.orgE + +=head1 COPYRIGHT AND LICENSE + +Copyright 2005-2013 by Makamaka Hannyaharamitu + +Most of the documentation is taken from JSON::XS by Marc Lehmann + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + +=cut + diff --git a/src/perllib/JSON/backportPP.pm b/src/perllib/JSON/backportPP.pm new file mode 100644 index 0000000..6870697 --- /dev/null +++ b/src/perllib/JSON/backportPP.pm @@ -0,0 +1,3256 @@ +package # This is JSON::backportPP + JSON::PP; + +# JSON-2.0 + +use 5.005; +use strict; + +use Exporter (); +BEGIN { @JSON::backportPP::ISA = ('Exporter') } + +use overload (); +use JSON::backportPP::Boolean; + +use Carp (); +#use Devel::Peek; + +$JSON::backportPP::VERSION = '4.12'; + +@JSON::PP::EXPORT = qw(encode_json decode_json from_json to_json); + +# instead of hash-access, i tried index-access for speed. +# but this method is not faster than what i expected. so it will be changed. + +use constant P_ASCII => 0; +use constant P_LATIN1 => 1; +use constant P_UTF8 => 2; +use constant P_INDENT => 3; +use constant P_CANONICAL => 4; +use constant P_SPACE_BEFORE => 5; +use constant P_SPACE_AFTER => 6; +use constant P_ALLOW_NONREF => 7; +use constant P_SHRINK => 8; +use constant P_ALLOW_BLESSED => 9; +use constant P_CONVERT_BLESSED => 10; +use constant P_RELAXED => 11; + +use constant P_LOOSE => 12; +use constant P_ALLOW_BIGNUM => 13; +use constant P_ALLOW_BAREKEY => 14; +use constant P_ALLOW_SINGLEQUOTE => 15; +use constant P_ESCAPE_SLASH => 16; +use constant P_AS_NONBLESSED => 17; + +use constant P_ALLOW_UNKNOWN => 18; +use constant P_ALLOW_TAGS => 19; + +use constant OLD_PERL => $] < 5.008 ? 1 : 0; +use constant USE_B => $ENV{PERL_JSON_PP_USE_B} || 0; +use constant CORE_BOOL => defined &builtin::is_bool; + +my $invalid_char_re; + +BEGIN { + $invalid_char_re = "["; + for my $i (0 .. 0x01F, 0x22, 0x5c) { # '/' is ok + $invalid_char_re .= quotemeta chr utf8::unicode_to_native($i); + } + + $invalid_char_re = qr/$invalid_char_re]/; +} + +BEGIN { + if (USE_B) { + require B; + } +} + +BEGIN { + my @xs_compati_bit_properties = qw( + latin1 ascii utf8 indent canonical space_before space_after allow_nonref shrink + allow_blessed convert_blessed relaxed allow_unknown + allow_tags + ); + my @pp_bit_properties = qw( + allow_singlequote allow_bignum loose + allow_barekey escape_slash as_nonblessed + ); + + # Perl version check, Unicode handling is enabled? + # Helper module sets @JSON::PP::_properties. + if ( OLD_PERL ) { + my $helper = $] >= 5.006 ? 'JSON::backportPP::Compat5006' : 'JSON::backportPP::Compat5005'; + eval qq| require $helper |; + if ($@) { Carp::croak $@; } + } + + for my $name (@xs_compati_bit_properties, @pp_bit_properties) { + my $property_id = 'P_' . uc($name); + + eval qq/ + sub $name { + my \$enable = defined \$_[1] ? \$_[1] : 1; + + if (\$enable) { + \$_[0]->{PROPS}->[$property_id] = 1; + } + else { + \$_[0]->{PROPS}->[$property_id] = 0; + } + + \$_[0]; + } + + sub get_$name { + \$_[0]->{PROPS}->[$property_id] ? 1 : ''; + } + /; + } + +} + + + +# Functions + +my $JSON; # cache + +sub encode_json ($) { # encode + ($JSON ||= __PACKAGE__->new->utf8)->encode(@_); +} + + +sub decode_json { # decode + ($JSON ||= __PACKAGE__->new->utf8)->decode(@_); +} + +# Obsoleted + +sub to_json($) { + Carp::croak ("JSON::PP::to_json has been renamed to encode_json."); +} + + +sub from_json($) { + Carp::croak ("JSON::PP::from_json has been renamed to decode_json."); +} + + +# Methods + +sub new { + my $class = shift; + my $self = { + max_depth => 512, + max_size => 0, + indent_length => 3, + }; + + $self->{PROPS}[P_ALLOW_NONREF] = 1; + + bless $self, $class; +} + + +sub encode { + return $_[0]->PP_encode_json($_[1]); +} + + +sub decode { + return $_[0]->PP_decode_json($_[1], 0x00000000); +} + + +sub decode_prefix { + return $_[0]->PP_decode_json($_[1], 0x00000001); +} + + +# accessor + + +# pretty printing + +sub pretty { + my ($self, $v) = @_; + my $enable = defined $v ? $v : 1; + + if ($enable) { # indent_length(3) for JSON::XS compatibility + $self->indent(1)->space_before(1)->space_after(1); + } + else { + $self->indent(0)->space_before(0)->space_after(0); + } + + $self; +} + +# etc + +sub max_depth { + my $max = defined $_[1] ? $_[1] : 0x80000000; + $_[0]->{max_depth} = $max; + $_[0]; +} + + +sub get_max_depth { $_[0]->{max_depth}; } + + +sub max_size { + my $max = defined $_[1] ? $_[1] : 0; + $_[0]->{max_size} = $max; + $_[0]; +} + + +sub get_max_size { $_[0]->{max_size}; } + +sub boolean_values { + my $self = shift; + if (@_) { + my ($false, $true) = @_; + $self->{false} = $false; + $self->{true} = $true; + if (CORE_BOOL) { + BEGIN { CORE_BOOL and warnings->unimport(qw(experimental::builtin)) } + if (builtin::is_bool($true) && builtin::is_bool($false) && $true && !$false) { + $self->{core_bools} = !!1; + } + else { + delete $self->{core_bools}; + } + } + } else { + delete $self->{false}; + delete $self->{true}; + delete $self->{core_bools}; + } + return $self; +} + +sub core_bools { + my $self = shift; + my $core_bools = defined $_[0] ? $_[0] : 1; + if ($core_bools) { + $self->{true} = !!1; + $self->{false} = !!0; + $self->{core_bools} = !!1; + } + else { + $self->{true} = $JSON::PP::true; + $self->{false} = $JSON::PP::false; + $self->{core_bools} = !!0; + } + return $self; +} + +sub get_core_bools { + my $self = shift; + return !!$self->{core_bools}; +} + +sub unblessed_bool { + my $self = shift; + return $self->core_bools(@_); +} + +sub get_unblessed_bool { + my $self = shift; + return $self->get_core_bools(@_); +} + +sub get_boolean_values { + my $self = shift; + if (exists $self->{true} and exists $self->{false}) { + return @$self{qw/false true/}; + } + return; +} + +sub filter_json_object { + if (defined $_[1] and ref $_[1] eq 'CODE') { + $_[0]->{cb_object} = $_[1]; + } else { + delete $_[0]->{cb_object}; + } + $_[0]->{F_HOOK} = ($_[0]->{cb_object} or $_[0]->{cb_sk_object}) ? 1 : 0; + $_[0]; +} + +sub filter_json_single_key_object { + if (@_ == 1 or @_ > 3) { + Carp::croak("Usage: JSON::PP::filter_json_single_key_object(self, key, callback = undef)"); + } + if (defined $_[2] and ref $_[2] eq 'CODE') { + $_[0]->{cb_sk_object}->{$_[1]} = $_[2]; + } else { + delete $_[0]->{cb_sk_object}->{$_[1]}; + delete $_[0]->{cb_sk_object} unless %{$_[0]->{cb_sk_object} || {}}; + } + $_[0]->{F_HOOK} = ($_[0]->{cb_object} or $_[0]->{cb_sk_object}) ? 1 : 0; + $_[0]; +} + +sub indent_length { + if (!defined $_[1] or $_[1] > 15 or $_[1] < 0) { + Carp::carp "The acceptable range of indent_length() is 0 to 15."; + } + else { + $_[0]->{indent_length} = $_[1]; + } + $_[0]; +} + +sub get_indent_length { + $_[0]->{indent_length}; +} + +sub sort_by { + $_[0]->{sort_by} = defined $_[1] ? $_[1] : 1; + $_[0]; +} + +sub allow_bigint { + Carp::carp("allow_bigint() is obsoleted. use allow_bignum() instead."); + $_[0]->allow_bignum; +} + +############################### + +### +### Perl => JSON +### + + +{ # Convert + + my $max_depth; + my $indent; + my $ascii; + my $latin1; + my $utf8; + my $space_before; + my $space_after; + my $canonical; + my $allow_blessed; + my $convert_blessed; + + my $indent_length; + my $escape_slash; + my $bignum; + my $as_nonblessed; + my $allow_tags; + + my $depth; + my $indent_count; + my $keysort; + + + sub PP_encode_json { + my $self = shift; + my $obj = shift; + + $indent_count = 0; + $depth = 0; + + my $props = $self->{PROPS}; + + ($ascii, $latin1, $utf8, $indent, $canonical, $space_before, $space_after, $allow_blessed, + $convert_blessed, $escape_slash, $bignum, $as_nonblessed, $allow_tags) + = @{$props}[P_ASCII .. P_SPACE_AFTER, P_ALLOW_BLESSED, P_CONVERT_BLESSED, + P_ESCAPE_SLASH, P_ALLOW_BIGNUM, P_AS_NONBLESSED, P_ALLOW_TAGS]; + + ($max_depth, $indent_length) = @{$self}{qw/max_depth indent_length/}; + + $keysort = $canonical ? sub { $a cmp $b } : undef; + + if ($self->{sort_by}) { + $keysort = ref($self->{sort_by}) eq 'CODE' ? $self->{sort_by} + : $self->{sort_by} =~ /\D+/ ? $self->{sort_by} + : sub { $a cmp $b }; + } + + encode_error("hash- or arrayref expected (not a simple scalar, use allow_nonref to allow this)") + if(!ref $obj and !$props->[ P_ALLOW_NONREF ]); + + my $str = $self->object_to_json($obj); + + $str .= "\n" if ( $indent ); # JSON::XS 2.26 compatible + + return $str; + } + + + sub object_to_json { + my ($self, $obj) = @_; + my $type = ref($obj); + + if($type eq 'HASH'){ + return $self->hash_to_json($obj); + } + elsif($type eq 'ARRAY'){ + return $self->array_to_json($obj); + } + elsif ($type) { # blessed object? + if (blessed($obj)) { + + return $self->value_to_json($obj) if ( $obj->isa('JSON::PP::Boolean') ); + + if ( $allow_tags and $obj->can('FREEZE') ) { + my $obj_class = ref $obj || $obj; + $obj = bless $obj, $obj_class; + my @results = $obj->FREEZE('JSON'); + if ( @results and ref $results[0] ) { + if ( refaddr( $obj ) eq refaddr( $results[0] ) ) { + encode_error( sprintf( + "%s::FREEZE method returned same object as was passed instead of a new one", + ref $obj + ) ); + } + } + return '("'.$obj_class.'")['.join(',', @results).']'; + } + + if ( $convert_blessed and $obj->can('TO_JSON') ) { + my $result = $obj->TO_JSON(); + if ( defined $result and ref( $result ) ) { + if ( refaddr( $obj ) eq refaddr( $result ) ) { + encode_error( sprintf( + "%s::TO_JSON method returned same object as was passed instead of a new one", + ref $obj + ) ); + } + } + + return $self->object_to_json( $result ); + } + + return "$obj" if ( $bignum and _is_bignum($obj) ); + + if ($allow_blessed) { + return $self->blessed_to_json($obj) if ($as_nonblessed); # will be removed. + return 'null'; + } + encode_error( sprintf("encountered object '%s', but neither allow_blessed, convert_blessed nor allow_tags settings are enabled (or TO_JSON/FREEZE method missing)", $obj) + ); + } + else { + return $self->value_to_json($obj); + } + } + else{ + return $self->value_to_json($obj); + } + } + + + sub hash_to_json { + my ($self, $obj) = @_; + my @res; + + encode_error("json text or perl structure exceeds maximum nesting level (max_depth set too low?)") + if (++$depth > $max_depth); + + my ($pre, $post) = $indent ? $self->_up_indent() : ('', ''); + my $del = ($space_before ? ' ' : '') . ':' . ($space_after ? ' ' : ''); + + for my $k ( _sort( $obj ) ) { + if ( OLD_PERL ) { utf8::decode($k) } # key for Perl 5.6 / be optimized + push @res, $self->string_to_json( $k ) + . $del + . ( ref $obj->{$k} ? $self->object_to_json( $obj->{$k} ) : $self->value_to_json( $obj->{$k} ) ); + } + + --$depth; + $self->_down_indent() if ($indent); + + return '{}' unless @res; + return '{' . $pre . join( ",$pre", @res ) . $post . '}'; + } + + + sub array_to_json { + my ($self, $obj) = @_; + my @res; + + encode_error("json text or perl structure exceeds maximum nesting level (max_depth set too low?)") + if (++$depth > $max_depth); + + my ($pre, $post) = $indent ? $self->_up_indent() : ('', ''); + + for my $v (@$obj){ + push @res, ref($v) ? $self->object_to_json($v) : $self->value_to_json($v); + } + + --$depth; + $self->_down_indent() if ($indent); + + return '[]' unless @res; + return '[' . $pre . join( ",$pre", @res ) . $post . ']'; + } + + sub _looks_like_number { + my $value = shift; + if (USE_B) { + my $b_obj = B::svref_2object(\$value); + my $flags = $b_obj->FLAGS; + return 1 if $flags & ( B::SVp_IOK() | B::SVp_NOK() ) and !( $flags & B::SVp_POK() ); + return; + } else { + no warnings 'numeric'; + # if the utf8 flag is on, it almost certainly started as a string + return if utf8::is_utf8($value); + # detect numbers + # string & "" -> "" + # number & "" -> 0 (with warning) + # nan and inf can detect as numbers, so check with * 0 + return unless length((my $dummy = "") & $value); + return unless 0 + $value eq $value; + return 1 if $value * 0 == 0; + return -1; # inf/nan + } + } + + sub value_to_json { + my ($self, $value) = @_; + + return 'null' if(!defined $value); + + my $type = ref($value); + + if (!$type) { + BEGIN { CORE_BOOL and warnings->unimport('experimental::builtin') } + if (CORE_BOOL && builtin::is_bool($value)) { + return $value ? 'true' : 'false'; + } + elsif (_looks_like_number($value)) { + return $value; + } + return $self->string_to_json($value); + } + elsif( blessed($value) and $value->isa('JSON::PP::Boolean') ){ + return $$value == 1 ? 'true' : 'false'; + } + else { + if ((overload::StrVal($value) =~ /=(\w+)/)[0]) { + return $self->value_to_json("$value"); + } + + if ($type eq 'SCALAR' and defined $$value) { + return $$value eq '1' ? 'true' + : $$value eq '0' ? 'false' + : $self->{PROPS}->[ P_ALLOW_UNKNOWN ] ? 'null' + : encode_error("cannot encode reference to scalar"); + } + + if ( $self->{PROPS}->[ P_ALLOW_UNKNOWN ] ) { + return 'null'; + } + else { + if ( $type eq 'SCALAR' or $type eq 'REF' ) { + encode_error("cannot encode reference to scalar"); + } + else { + encode_error("encountered $value, but JSON can only represent references to arrays or hashes"); + } + } + + } + } + + + my %esc = ( + "\n" => '\n', + "\r" => '\r', + "\t" => '\t', + "\f" => '\f', + "\b" => '\b', + "\"" => '\"', + "\\" => '\\\\', + "\'" => '\\\'', + ); + + + sub string_to_json { + my ($self, $arg) = @_; + + $arg =~ s/(["\\\n\r\t\f\b])/$esc{$1}/g; + $arg =~ s/\//\\\//g if ($escape_slash); + + # On ASCII platforms, matches [\x00-\x08\x0b\x0e-\x1f] + $arg =~ s/([^\n\t\c?[:^cntrl:][:^ascii:]])/'\\u00' . unpack('H2', $1)/eg; + + if ($ascii) { + $arg = JSON_PP_encode_ascii($arg); + } + + if ($latin1) { + $arg = JSON_PP_encode_latin1($arg); + } + + if ($utf8) { + utf8::encode($arg); + } + + return '"' . $arg . '"'; + } + + + sub blessed_to_json { + my $reftype = reftype($_[1]) || ''; + if ($reftype eq 'HASH') { + return $_[0]->hash_to_json($_[1]); + } + elsif ($reftype eq 'ARRAY') { + return $_[0]->array_to_json($_[1]); + } + else { + return 'null'; + } + } + + + sub encode_error { + my $error = shift; + Carp::croak "$error"; + } + + + sub _sort { + defined $keysort ? (sort $keysort (keys %{$_[0]})) : keys %{$_[0]}; + } + + + sub _up_indent { + my $self = shift; + my $space = ' ' x $indent_length; + + my ($pre,$post) = ('',''); + + $post = "\n" . $space x $indent_count; + + $indent_count++; + + $pre = "\n" . $space x $indent_count; + + return ($pre,$post); + } + + + sub _down_indent { $indent_count--; } + + + sub PP_encode_box { + { + depth => $depth, + indent_count => $indent_count, + }; + } + +} # Convert + + +sub _encode_ascii { + join('', + map { + chr($_) =~ /[[:ascii:]]/ ? + chr($_) : + $_ <= 65535 ? + sprintf('\u%04x', $_) : sprintf('\u%x\u%x', _encode_surrogates($_)); + } unpack('U*', $_[0]) + ); +} + + +sub _encode_latin1 { + join('', + map { + $_ <= 255 ? + chr($_) : + $_ <= 65535 ? + sprintf('\u%04x', $_) : sprintf('\u%x\u%x', _encode_surrogates($_)); + } unpack('U*', $_[0]) + ); +} + + +sub _encode_surrogates { # from perlunicode + my $uni = $_[0] - 0x10000; + return ($uni / 0x400 + 0xD800, $uni % 0x400 + 0xDC00); +} + + +sub _is_bignum { + $_[0]->isa('Math::BigInt') or $_[0]->isa('Math::BigFloat'); +} + + + +# +# JSON => Perl +# + +my $max_intsize; + +BEGIN { + my $checkint = 1111; + for my $d (5..64) { + $checkint .= 1; + my $int = eval qq| $checkint |; + if ($int =~ /[eE]/) { + $max_intsize = $d - 1; + last; + } + } +} + +{ # PARSE + + my %escapes = ( # by Jeremy Muhlich + b => "\b", + t => "\t", + n => "\n", + f => "\f", + r => "\r", + '\\' => '\\', + '"' => '"', + '/' => '/', + ); + + my $text; # json data + my $at; # offset + my $ch; # first character + my $len; # text length (changed according to UTF8 or NON UTF8) + # INTERNAL + my $depth; # nest counter + my $encoding; # json text encoding + my $is_valid_utf8; # temp variable + my $utf8_len; # utf8 byte length + # FLAGS + my $utf8; # must be utf8 + my $max_depth; # max nest number of objects and arrays + my $max_size; + my $relaxed; + my $cb_object; + my $cb_sk_object; + + my $F_HOOK; + + my $allow_bignum; # using Math::BigInt/BigFloat + my $singlequote; # loosely quoting + my $loose; # + my $allow_barekey; # bareKey + my $allow_tags; + + my $alt_true; + my $alt_false; + + sub _detect_utf_encoding { + my $text = shift; + my @octets = unpack('C4', $text); + return 'unknown' unless defined $octets[3]; + return ( $octets[0] and $octets[1]) ? 'UTF-8' + : (!$octets[0] and $octets[1]) ? 'UTF-16BE' + : (!$octets[0] and !$octets[1]) ? 'UTF-32BE' + : ( $octets[2] ) ? 'UTF-16LE' + : (!$octets[2] ) ? 'UTF-32LE' + : 'unknown'; + } + + sub PP_decode_json { + my ($self, $want_offset); + + ($self, $text, $want_offset) = @_; + + ($at, $ch, $depth) = (0, '', 0); + + if ( !defined $text or ref $text ) { + decode_error("malformed JSON string, neither array, object, number, string or atom"); + } + + my $props = $self->{PROPS}; + + ($utf8, $relaxed, $loose, $allow_bignum, $allow_barekey, $singlequote, $allow_tags) + = @{$props}[P_UTF8, P_RELAXED, P_LOOSE .. P_ALLOW_SINGLEQUOTE, P_ALLOW_TAGS]; + + ($alt_true, $alt_false) = @$self{qw/true false/}; + + if ( $utf8 ) { + $encoding = _detect_utf_encoding($text); + if ($encoding ne 'UTF-8' and $encoding ne 'unknown') { + require Encode; + Encode::from_to($text, $encoding, 'utf-8'); + } else { + utf8::downgrade( $text, 1 ) or Carp::croak("Wide character in subroutine entry"); + } + } + else { + utf8::encode( $text ); + } + + $len = length $text; + + ($max_depth, $max_size, $cb_object, $cb_sk_object, $F_HOOK) + = @{$self}{qw/max_depth max_size cb_object cb_sk_object F_HOOK/}; + + if ($max_size > 1) { + use bytes; + my $bytes = length $text; + decode_error( + sprintf("attempted decode of JSON text of %s bytes size, but max_size is set to %s" + , $bytes, $max_size), 1 + ) if ($bytes > $max_size); + } + + white(); # remove head white space + + decode_error("malformed JSON string, neither array, object, number, string or atom") unless defined $ch; # Is there a first character for JSON structure? + + my $result = value(); + + if ( !$props->[ P_ALLOW_NONREF ] and !ref $result ) { + decode_error( + 'JSON text must be an object or array (but found number, string, true, false or null,' + . ' use allow_nonref to allow this)', 1); + } + + Carp::croak('something wrong.') if $len < $at; # we won't arrive here. + + my $consumed = defined $ch ? $at - 1 : $at; # consumed JSON text length + + white(); # remove tail white space + + return ( $result, $consumed ) if $want_offset; # all right if decode_prefix + + decode_error("garbage after JSON object") if defined $ch; + + $result; + } + + + sub next_chr { + return $ch = undef if($at >= $len); + $ch = substr($text, $at++, 1); + } + + + sub value { + white(); + return if(!defined $ch); + return object() if($ch eq '{'); + return array() if($ch eq '['); + return tag() if($ch eq '('); + return string() if($ch eq '"' or ($singlequote and $ch eq "'")); + return number() if($ch =~ /[0-9]/ or $ch eq '-'); + return word(); + } + + sub string { + my $utf16; + my $is_utf8; + + ($is_valid_utf8, $utf8_len) = ('', 0); + + my $s = ''; # basically UTF8 flag on + + if($ch eq '"' or ($singlequote and $ch eq "'")){ + my $boundChar = $ch; + + OUTER: while( defined(next_chr()) ){ + + if($ch eq $boundChar){ + next_chr(); + + if ($utf16) { + decode_error("missing low surrogate character in surrogate pair"); + } + + utf8::decode($s) if($is_utf8); + + return $s; + } + elsif($ch eq '\\'){ + next_chr(); + if(exists $escapes{$ch}){ + $s .= $escapes{$ch}; + } + elsif($ch eq 'u'){ # UNICODE handling + my $u = ''; + + for(1..4){ + $ch = next_chr(); + last OUTER if($ch !~ /[0-9a-fA-F]/); + $u .= $ch; + } + + # U+D800 - U+DBFF + if ($u =~ /^[dD][89abAB][0-9a-fA-F]{2}/) { # UTF-16 high surrogate? + $utf16 = $u; + } + # U+DC00 - U+DFFF + elsif ($u =~ /^[dD][c-fC-F][0-9a-fA-F]{2}/) { # UTF-16 low surrogate? + unless (defined $utf16) { + decode_error("missing high surrogate character in surrogate pair"); + } + $is_utf8 = 1; + $s .= JSON_PP_decode_surrogates($utf16, $u) || next; + $utf16 = undef; + } + else { + if (defined $utf16) { + decode_error("surrogate pair expected"); + } + + my $hex = hex( $u ); + if ( chr $u =~ /[[:^ascii:]]/ ) { + $is_utf8 = 1; + $s .= JSON_PP_decode_unicode($u) || next; + } + else { + $s .= chr $hex; + } + } + + } + else{ + unless ($loose) { + $at -= 2; + decode_error('illegal backslash escape sequence in string'); + } + $s .= $ch; + } + } + else{ + + if ( $ch =~ /[[:^ascii:]]/ ) { + unless( $ch = is_valid_utf8($ch) ) { + $at -= 1; + decode_error("malformed UTF-8 character in JSON string"); + } + else { + $at += $utf8_len - 1; + } + + $is_utf8 = 1; + } + + if (!$loose) { + if ($ch =~ $invalid_char_re) { # '/' ok + if (!$relaxed or $ch ne "\t") { + $at--; + decode_error(sprintf "invalid character 0x%X" + . " encountered while parsing JSON string", + ord $ch); + } + } + } + + $s .= $ch; + } + } + } + + decode_error("unexpected end of string while parsing JSON string"); + } + + + sub white { + while( defined $ch ){ + if($ch eq '' or $ch =~ /\A[ \t\r\n]\z/){ + next_chr(); + } + elsif($relaxed and $ch eq '/'){ + next_chr(); + if(defined $ch and $ch eq '/'){ + 1 while(defined(next_chr()) and $ch ne "\n" and $ch ne "\r"); + } + elsif(defined $ch and $ch eq '*'){ + next_chr(); + while(1){ + if(defined $ch){ + if($ch eq '*'){ + if(defined(next_chr()) and $ch eq '/'){ + next_chr(); + last; + } + } + else{ + next_chr(); + } + } + else{ + decode_error("Unterminated comment"); + } + } + next; + } + else{ + $at--; + decode_error("malformed JSON string, neither array, object, number, string or atom"); + } + } + else{ + if ($relaxed and $ch eq '#') { # correctly? + pos($text) = $at; + $text =~ /\G([^\n]*(?:\r\n|\r|\n|$))/g; + $at = pos($text); + next_chr; + next; + } + + last; + } + } + } + + + sub array { + my $a = $_[0] || []; # you can use this code to use another array ref object. + + decode_error('json text or perl structure exceeds maximum nesting level (max_depth set too low?)') + if (++$depth > $max_depth); + + next_chr(); + white(); + + if(defined $ch and $ch eq ']'){ + --$depth; + next_chr(); + return $a; + } + else { + while(defined($ch)){ + push @$a, value(); + + white(); + + if (!defined $ch) { + last; + } + + if($ch eq ']'){ + --$depth; + next_chr(); + return $a; + } + + if($ch ne ','){ + last; + } + + next_chr(); + white(); + + if ($relaxed and $ch eq ']') { + --$depth; + next_chr(); + return $a; + } + + } + } + + $at-- if defined $ch and $ch ne ''; + decode_error(", or ] expected while parsing array"); + } + + sub tag { + decode_error('malformed JSON string, neither array, object, number, string or atom') unless $allow_tags; + + next_chr(); + white(); + + my $tag = value(); + return unless defined $tag; + decode_error('malformed JSON string, (tag) must be a string') if ref $tag; + + white(); + + if (!defined $ch or $ch ne ')') { + decode_error(') expected after tag'); + } + + next_chr(); + white(); + + my $val = value(); + return unless defined $val; + decode_error('malformed JSON string, tag value must be an array') unless ref $val eq 'ARRAY'; + + if (!eval { $tag->can('THAW') }) { + decode_error('cannot decode perl-object (package does not exist)') if $@; + decode_error('cannot decode perl-object (package does not have a THAW method)'); + } + $tag->THAW('JSON', @$val); + } + + sub object { + my $o = $_[0] || {}; # you can use this code to use another hash ref object. + my $k; + + decode_error('json text or perl structure exceeds maximum nesting level (max_depth set too low?)') + if (++$depth > $max_depth); + next_chr(); + white(); + + if(defined $ch and $ch eq '}'){ + --$depth; + next_chr(); + if ($F_HOOK) { + return _json_object_hook($o); + } + return $o; + } + else { + while (defined $ch) { + $k = ($allow_barekey and $ch ne '"' and $ch ne "'") ? bareKey() : string(); + white(); + + if(!defined $ch or $ch ne ':'){ + $at--; + decode_error("':' expected"); + } + + next_chr(); + $o->{$k} = value(); + white(); + + last if (!defined $ch); + + if($ch eq '}'){ + --$depth; + next_chr(); + if ($F_HOOK) { + return _json_object_hook($o); + } + return $o; + } + + if($ch ne ','){ + last; + } + + next_chr(); + white(); + + if ($relaxed and $ch eq '}') { + --$depth; + next_chr(); + if ($F_HOOK) { + return _json_object_hook($o); + } + return $o; + } + + } + + } + + $at-- if defined $ch and $ch ne ''; + decode_error(", or } expected while parsing object/hash"); + } + + + sub bareKey { # doesn't strictly follow Standard ECMA-262 3rd Edition + my $key; + while($ch =~ /[\$\w[:^ascii:]]/){ + $key .= $ch; + next_chr(); + } + return $key; + } + + + sub word { + my $word = substr($text,$at-1,4); + + if($word eq 'true'){ + $at += 3; + next_chr; + return defined $alt_true ? $alt_true : $JSON::PP::true; + } + elsif($word eq 'null'){ + $at += 3; + next_chr; + return undef; + } + elsif($word eq 'fals'){ + $at += 3; + if(substr($text,$at,1) eq 'e'){ + $at++; + next_chr; + return defined $alt_false ? $alt_false : $JSON::PP::false; + } + } + + $at--; # for decode_error report + + decode_error("'null' expected") if ($word =~ /^n/); + decode_error("'true' expected") if ($word =~ /^t/); + decode_error("'false' expected") if ($word =~ /^f/); + decode_error("malformed JSON string, neither array, object, number, string or atom"); + } + + + sub number { + my $n = ''; + my $v; + my $is_dec; + my $is_exp; + + if($ch eq '-'){ + $n = '-'; + next_chr; + if (!defined $ch or $ch !~ /\d/) { + decode_error("malformed number (no digits after initial minus)"); + } + } + + # According to RFC4627, hex or oct digits are invalid. + if($ch eq '0'){ + my $peek = substr($text,$at,1); + if($peek =~ /^[0-9a-dfA-DF]/){ # e may be valid (exponential) + decode_error("malformed number (leading zero must not be followed by another digit)"); + } + $n .= $ch; + next_chr; + } + + while(defined $ch and $ch =~ /\d/){ + $n .= $ch; + next_chr; + } + + if(defined $ch and $ch eq '.'){ + $n .= '.'; + $is_dec = 1; + + next_chr; + if (!defined $ch or $ch !~ /\d/) { + decode_error("malformed number (no digits after decimal point)"); + } + else { + $n .= $ch; + } + + while(defined(next_chr) and $ch =~ /\d/){ + $n .= $ch; + } + } + + if(defined $ch and ($ch eq 'e' or $ch eq 'E')){ + $n .= $ch; + $is_exp = 1; + next_chr; + + if(defined($ch) and ($ch eq '+' or $ch eq '-')){ + $n .= $ch; + next_chr; + if (!defined $ch or $ch =~ /\D/) { + decode_error("malformed number (no digits after exp sign)"); + } + $n .= $ch; + } + elsif(defined($ch) and $ch =~ /\d/){ + $n .= $ch; + } + else { + decode_error("malformed number (no digits after exp sign)"); + } + + while(defined(next_chr) and $ch =~ /\d/){ + $n .= $ch; + } + + } + + $v .= $n; + + if ($is_dec or $is_exp) { + if ($allow_bignum) { + require Math::BigFloat; + return Math::BigFloat->new($v); + } + } else { + if (length $v > $max_intsize) { + if ($allow_bignum) { # from Adam Sussman + require Math::BigInt; + return Math::BigInt->new($v); + } + else { + return "$v"; + } + } + } + + return $is_dec ? $v/1.0 : 0+$v; + } + + # Compute how many bytes are in the longest legal official Unicode + # character + my $max_unicode_length = do { + BEGIN { $] >= 5.006 and require warnings and warnings->unimport('utf8') } + chr 0x10FFFF; + }; + utf8::encode($max_unicode_length); + $max_unicode_length = length $max_unicode_length; + + sub is_valid_utf8 { + + # Returns undef (setting $utf8_len to 0) unless the next bytes in $text + # comprise a well-formed UTF-8 encoded character, in which case, + # return those bytes, setting $utf8_len to their count. + + my $start_point = substr($text, $at - 1); + + # Look no further than the maximum number of bytes in a single + # character + my $limit = $max_unicode_length; + $limit = length($start_point) if $limit > length($start_point); + + # Find the number of bytes comprising the first character in $text + # (without having to know the details of its internal representation). + # This loop will iterate just once on well-formed input. + while ($limit > 0) { # Until we succeed or exhaust the input + my $copy = substr($start_point, 0, $limit); + + # decode() will return true if all bytes are valid; false + # if any aren't. + if (utf8::decode($copy)) { + + # Is valid: get the first character, convert back to bytes, + # and return those bytes. + $copy = substr($copy, 0, 1); + utf8::encode($copy); + $utf8_len = length $copy; + return substr($start_point, 0, $utf8_len); + } + + # If it didn't work, it could be that there is a full legal character + # followed by a partial or malformed one. Narrow the window and + # try again. + $limit--; + } + + # Failed to find a legal UTF-8 character. + $utf8_len = 0; + return; + } + + + sub decode_error { + my $error = shift; + my $no_rep = shift; + my $str = defined $text ? substr($text, $at) : ''; + my $mess = ''; + my $type = 'U*'; + + if ( OLD_PERL ) { + my $type = $] < 5.006 ? 'C*' + : utf8::is_utf8( $str ) ? 'U*' # 5.6 + : 'C*' + ; + } + + for my $c ( unpack( $type, $str ) ) { # emulate pv_uni_display() ? + my $chr_c = chr($c); + $mess .= $chr_c eq '\\' ? '\\\\' + : $chr_c =~ /[[:print:]]/ ? $chr_c + : $chr_c eq '\a' ? '\a' + : $chr_c eq '\t' ? '\t' + : $chr_c eq '\n' ? '\n' + : $chr_c eq '\r' ? '\r' + : $chr_c eq '\f' ? '\f' + : sprintf('\x{%x}', $c) + ; + if ( length $mess >= 20 ) { + $mess .= '...'; + last; + } + } + + unless ( length $mess ) { + $mess = '(end of string)'; + } + + Carp::croak ( + $no_rep ? "$error" : "$error, at character offset $at (before \"$mess\")" + ); + + } + + + sub _json_object_hook { + my $o = $_[0]; + my @ks = keys %{$o}; + + if ( $cb_sk_object and @ks == 1 and exists $cb_sk_object->{ $ks[0] } and ref $cb_sk_object->{ $ks[0] } ) { + my @val = $cb_sk_object->{ $ks[0] }->( $o->{$ks[0]} ); + if (@val == 0) { + return $o; + } + elsif (@val == 1) { + return $val[0]; + } + else { + Carp::croak("filter_json_single_key_object callbacks must not return more than one scalar"); + } + } + + my @val = $cb_object->($o) if ($cb_object); + if (@val == 0) { + return $o; + } + elsif (@val == 1) { + return $val[0]; + } + else { + Carp::croak("filter_json_object callbacks must not return more than one scalar"); + } + } + + + sub PP_decode_box { + { + text => $text, + at => $at, + ch => $ch, + len => $len, + depth => $depth, + encoding => $encoding, + is_valid_utf8 => $is_valid_utf8, + }; + } + +} # PARSE + + +sub _decode_surrogates { # from perlunicode + my $uni = 0x10000 + (hex($_[0]) - 0xD800) * 0x400 + (hex($_[1]) - 0xDC00); + my $un = pack('U*', $uni); + utf8::encode( $un ); + return $un; +} + + +sub _decode_unicode { + my $un = pack('U', hex shift); + utf8::encode( $un ); + return $un; +} + +# +# Setup for various Perl versions (the code from JSON::PP58) +# + +BEGIN { + + unless ( defined &utf8::is_utf8 ) { + require Encode; + *utf8::is_utf8 = *Encode::is_utf8; + } + + if ( !OLD_PERL ) { + *JSON::PP::JSON_PP_encode_ascii = \&_encode_ascii; + *JSON::PP::JSON_PP_encode_latin1 = \&_encode_latin1; + *JSON::PP::JSON_PP_decode_surrogates = \&_decode_surrogates; + *JSON::PP::JSON_PP_decode_unicode = \&_decode_unicode; + + if ($] < 5.008003) { # join() in 5.8.0 - 5.8.2 is broken. + package # hide from PAUSE + JSON::PP; + require subs; + subs->import('join'); + eval q| + sub join { + return '' if (@_ < 2); + my $j = shift; + my $str = shift; + for (@_) { $str .= $j . $_; } + return $str; + } + |; + } + } + + + sub JSON::PP::incr_parse { + local $Carp::CarpLevel = 1; + ( $_[0]->{_incr_parser} ||= JSON::PP::IncrParser->new )->incr_parse( @_ ); + } + + + sub JSON::PP::incr_skip { + ( $_[0]->{_incr_parser} ||= JSON::PP::IncrParser->new )->incr_skip; + } + + + sub JSON::PP::incr_reset { + ( $_[0]->{_incr_parser} ||= JSON::PP::IncrParser->new )->incr_reset; + } + + eval q{ + sub JSON::PP::incr_text : lvalue { + $_[0]->{_incr_parser} ||= JSON::PP::IncrParser->new; + + if ( $_[0]->{_incr_parser}->{incr_pos} ) { + Carp::croak("incr_text cannot be called when the incremental parser already started parsing"); + } + $_[0]->{_incr_parser}->{incr_text}; + } + } if ( $] >= 5.006 ); + +} # Setup for various Perl versions (the code from JSON::PP58) + + +############################### +# Utilities +# + +BEGIN { + eval 'require Scalar::Util'; + unless($@){ + *JSON::PP::blessed = \&Scalar::Util::blessed; + *JSON::PP::reftype = \&Scalar::Util::reftype; + *JSON::PP::refaddr = \&Scalar::Util::refaddr; + } + else{ # This code is from Scalar::Util. + # warn $@; + eval 'sub UNIVERSAL::a_sub_not_likely_to_be_here { ref($_[0]) }'; + *JSON::PP::blessed = sub { + local($@, $SIG{__DIE__}, $SIG{__WARN__}); + ref($_[0]) ? eval { $_[0]->a_sub_not_likely_to_be_here } : undef; + }; + require B; + my %tmap = qw( + B::NULL SCALAR + B::HV HASH + B::AV ARRAY + B::CV CODE + B::IO IO + B::GV GLOB + B::REGEXP REGEXP + ); + *JSON::PP::reftype = sub { + my $r = shift; + + return undef unless length(ref($r)); + + my $t = ref(B::svref_2object($r)); + + return + exists $tmap{$t} ? $tmap{$t} + : length(ref($$r)) ? 'REF' + : 'SCALAR'; + }; + *JSON::PP::refaddr = sub { + return undef unless length(ref($_[0])); + + my $addr; + if(defined(my $pkg = blessed($_[0]))) { + $addr .= bless $_[0], 'Scalar::Util::Fake'; + bless $_[0], $pkg; + } + else { + $addr .= $_[0] + } + + $addr =~ /0x(\w+)/; + local $^W; + #no warnings 'portable'; + hex($1); + } + } +} + + +# shamelessly copied and modified from JSON::XS code. + +$JSON::PP::true = do { bless \(my $dummy = 1), "JSON::PP::Boolean" }; +$JSON::PP::false = do { bless \(my $dummy = 0), "JSON::PP::Boolean" }; + +sub is_bool { + if (blessed $_[0]) { + return ( + $_[0]->isa("JSON::PP::Boolean") + or $_[0]->isa("Types::Serialiser::BooleanBase") + or $_[0]->isa("JSON::XS::Boolean") + ); + } + elsif (CORE_BOOL) { + BEGIN { CORE_BOOL and warnings->unimport('experimental::builtin') } + return builtin::is_bool($_[0]); + } + return !!0; +} + +sub true { $JSON::PP::true } +sub false { $JSON::PP::false } +sub null { undef; } + +############################### + +package # hide from PAUSE + JSON::PP::IncrParser; + +use strict; + +use constant INCR_M_WS => 0; # initial whitespace skipping +use constant INCR_M_STR => 1; # inside string +use constant INCR_M_BS => 2; # inside backslash +use constant INCR_M_JSON => 3; # outside anything, count nesting +use constant INCR_M_C0 => 4; +use constant INCR_M_C1 => 5; +use constant INCR_M_TFN => 6; +use constant INCR_M_NUM => 7; + +$JSON::backportPP::IncrParser::VERSION = '1.01'; + +sub new { + my ( $class ) = @_; + + bless { + incr_nest => 0, + incr_text => undef, + incr_pos => 0, + incr_mode => 0, + }, $class; +} + + +sub incr_parse { + my ( $self, $coder, $text ) = @_; + + $self->{incr_text} = '' unless ( defined $self->{incr_text} ); + + if ( defined $text ) { + $self->{incr_text} .= $text; + } + + if ( defined wantarray ) { + my $max_size = $coder->get_max_size; + my $p = $self->{incr_pos}; + my @ret; + { + do { + unless ( $self->{incr_nest} <= 0 and $self->{incr_mode} == INCR_M_JSON ) { + $self->_incr_parse( $coder ); + + if ( $max_size and $self->{incr_pos} > $max_size ) { + Carp::croak("attempted decode of JSON text of $self->{incr_pos} bytes size, but max_size is set to $max_size"); + } + unless ( $self->{incr_nest} <= 0 and $self->{incr_mode} == INCR_M_JSON ) { + # as an optimisation, do not accumulate white space in the incr buffer + if ( $self->{incr_mode} == INCR_M_WS and $self->{incr_pos} ) { + $self->{incr_pos} = 0; + $self->{incr_text} = ''; + } + last; + } + } + + unless ( $coder->get_utf8 ) { + utf8::decode( $self->{incr_text} ); + } + + my ($obj, $offset) = $coder->PP_decode_json( $self->{incr_text}, 0x00000001 ); + push @ret, $obj; + use bytes; + $self->{incr_text} = substr( $self->{incr_text}, $offset || 0 ); + $self->{incr_pos} = 0; + $self->{incr_nest} = 0; + $self->{incr_mode} = 0; + last unless wantarray; + } while ( wantarray ); + } + + if ( wantarray ) { + return @ret; + } + else { # in scalar context + return defined $ret[0] ? $ret[0] : undef; + } + } +} + + +sub _incr_parse { + my ($self, $coder) = @_; + my $text = $self->{incr_text}; + my $len = length $text; + my $p = $self->{incr_pos}; + +INCR_PARSE: + while ( $len > $p ) { + my $s = substr( $text, $p, 1 ); + last INCR_PARSE unless defined $s; + my $mode = $self->{incr_mode}; + + if ( $mode == INCR_M_WS ) { + while ( $len > $p ) { + $s = substr( $text, $p, 1 ); + last INCR_PARSE unless defined $s; + if ( ord($s) > ord " " ) { + if ( $s eq '#' ) { + $self->{incr_mode} = INCR_M_C0; + redo INCR_PARSE; + } else { + $self->{incr_mode} = INCR_M_JSON; + redo INCR_PARSE; + } + } + $p++; + } + } elsif ( $mode == INCR_M_BS ) { + $p++; + $self->{incr_mode} = INCR_M_STR; + redo INCR_PARSE; + } elsif ( $mode == INCR_M_C0 or $mode == INCR_M_C1 ) { + while ( $len > $p ) { + $s = substr( $text, $p, 1 ); + last INCR_PARSE unless defined $s; + if ( $s eq "\n" ) { + $self->{incr_mode} = $self->{incr_mode} == INCR_M_C0 ? INCR_M_WS : INCR_M_JSON; + last; + } + $p++; + } + next; + } elsif ( $mode == INCR_M_TFN ) { + last INCR_PARSE if $p >= $len && $self->{incr_nest}; + while ( $len > $p ) { + $s = substr( $text, $p++, 1 ); + next if defined $s and $s =~ /[rueals]/; + last; + } + $p--; + $self->{incr_mode} = INCR_M_JSON; + + last INCR_PARSE unless $self->{incr_nest}; + redo INCR_PARSE; + } elsif ( $mode == INCR_M_NUM ) { + last INCR_PARSE if $p >= $len && $self->{incr_nest}; + while ( $len > $p ) { + $s = substr( $text, $p++, 1 ); + next if defined $s and $s =~ /[0-9eE.+\-]/; + last; + } + $p--; + $self->{incr_mode} = INCR_M_JSON; + + last INCR_PARSE unless $self->{incr_nest}; + redo INCR_PARSE; + } elsif ( $mode == INCR_M_STR ) { + while ( $len > $p ) { + $s = substr( $text, $p, 1 ); + last INCR_PARSE unless defined $s; + if ( $s eq '"' ) { + $p++; + $self->{incr_mode} = INCR_M_JSON; + + last INCR_PARSE unless $self->{incr_nest}; + redo INCR_PARSE; + } + elsif ( $s eq '\\' ) { + $p++; + if ( !defined substr($text, $p, 1) ) { + $self->{incr_mode} = INCR_M_BS; + last INCR_PARSE; + } + } + $p++; + } + } elsif ( $mode == INCR_M_JSON ) { + while ( $len > $p ) { + $s = substr( $text, $p++, 1 ); + if ( $s eq "\x00" ) { + $p--; + last INCR_PARSE; + } elsif ( $s =~ /^[\t\n\r ]$/) { + if ( !$self->{incr_nest} ) { + $p--; # do not eat the whitespace, let the next round do it + last INCR_PARSE; + } + next; + } elsif ( $s eq 't' or $s eq 'f' or $s eq 'n' ) { + $self->{incr_mode} = INCR_M_TFN; + redo INCR_PARSE; + } elsif ( $s =~ /^[0-9\-]$/ ) { + $self->{incr_mode} = INCR_M_NUM; + redo INCR_PARSE; + } elsif ( $s eq '"' ) { + $self->{incr_mode} = INCR_M_STR; + redo INCR_PARSE; + } elsif ( $s eq '[' or $s eq '{' ) { + if ( ++$self->{incr_nest} > $coder->get_max_depth ) { + Carp::croak('json text or perl structure exceeds maximum nesting level (max_depth set too low?)'); + } + next; + } elsif ( $s eq ']' or $s eq '}' ) { + if ( --$self->{incr_nest} <= 0 ) { + last INCR_PARSE; + } + } elsif ( $s eq '#' ) { + $self->{incr_mode} = INCR_M_C1; + redo INCR_PARSE; + } + } + } + } + + $self->{incr_pos} = $p; + $self->{incr_parsing} = $p ? 1 : 0; # for backward compatibility +} + + +sub incr_text { + if ( $_[0]->{incr_pos} ) { + Carp::croak("incr_text cannot be called when the incremental parser already started parsing"); + } + $_[0]->{incr_text}; +} + + +sub incr_skip { + my $self = shift; + $self->{incr_text} = substr( $self->{incr_text}, $self->{incr_pos} ); + $self->{incr_pos} = 0; + $self->{incr_mode} = 0; + $self->{incr_nest} = 0; +} + + +sub incr_reset { + my $self = shift; + $self->{incr_text} = undef; + $self->{incr_pos} = 0; + $self->{incr_mode} = 0; + $self->{incr_nest} = 0; +} + +############################### + + +1; +__END__ +=pod + +=head1 NAME + +JSON::PP - JSON::XS compatible pure-Perl module. + +=head1 SYNOPSIS + + use JSON::PP; + + # exported functions, they croak on error + # and expect/generate UTF-8 + + $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; + $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; + + # OO-interface + + $json = JSON::PP->new->ascii->pretty->allow_nonref; + + $pretty_printed_json_text = $json->encode( $perl_scalar ); + $perl_scalar = $json->decode( $json_text ); + + # Note that JSON version 2.0 and above will automatically use + # JSON::XS or JSON::PP, so you should be able to just: + + use JSON; + + +=head1 DESCRIPTION + +JSON::PP is a pure perl JSON decoder/encoder, and (almost) compatible to much +faster L written by Marc Lehmann in C. JSON::PP works as +a fallback module when you use L module without having +installed JSON::XS. + +Because of this fallback feature of JSON.pm, JSON::PP tries not to +be more JavaScript-friendly than JSON::XS (i.e. not to escape extra +characters such as U+2028 and U+2029, etc), +in order for you not to lose such JavaScript-friendliness silently +when you use JSON.pm and install JSON::XS for speed or by accident. +If you need JavaScript-friendly RFC7159-compliant pure perl module, +try L, which is derived from L web +framework and is also smaller and faster than JSON::PP. + +JSON::PP has been in the Perl core since Perl 5.14, mainly for +CPAN toolchain modules to parse META.json. + +=head1 FUNCTIONAL INTERFACE + +This section is taken from JSON::XS almost verbatim. C +and C are exported by default. + +=head2 encode_json + + $json_text = encode_json $perl_scalar + +Converts the given Perl data structure to a UTF-8 encoded, binary string +(that is, the string contains octets only). Croaks on error. + +This function call is functionally identical to: + + $json_text = JSON::PP->new->utf8->encode($perl_scalar) + +Except being faster. + +=head2 decode_json + + $perl_scalar = decode_json $json_text + +The opposite of C: expects an UTF-8 (binary) string and tries +to parse that as an UTF-8 encoded JSON text, returning the resulting +reference. Croaks on error. + +This function call is functionally identical to: + + $perl_scalar = JSON::PP->new->utf8->decode($json_text) + +Except being faster. + +=head2 JSON::PP::is_bool + + $is_boolean = JSON::PP::is_bool($scalar) + +Returns true if the passed scalar represents either JSON::PP::true or +JSON::PP::false, two constants that act like C<1> and C<0> respectively +and are also used to represent JSON C and C in Perl strings. + +On perl 5.36 and above, will also return true when given one of perl's +standard boolean values, such as the result of a comparison. + +See L, below, for more information on how JSON values are mapped to +Perl. + +=head1 OBJECT-ORIENTED INTERFACE + +This section is also taken from JSON::XS. + +The object oriented interface lets you configure your own encoding or +decoding style, within the limits of supported formats. + +=head2 new + + $json = JSON::PP->new + +Creates a new JSON::PP object that can be used to de/encode JSON +strings. All boolean flags described below are by default I +(with the exception of C, which defaults to I since +version C<4.0>). + +The mutators for flags all return the JSON::PP object again and thus calls can +be chained: + + my $json = JSON::PP->new->utf8->space_after->encode({a => [1,2]}) + => {"a": [1, 2]} + +=head2 ascii + + $json = $json->ascii([$enable]) + + $enabled = $json->get_ascii + +If C<$enable> is true (or missing), then the C method will not +generate characters outside the code range C<0..127> (which is ASCII). Any +Unicode characters outside that range will be escaped using either a +single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, +as per RFC4627. The resulting encoded JSON text can be treated as a native +Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string, +or any other superset of ASCII. + +If C<$enable> is false, then the C method will not escape Unicode +characters unless required by the JSON syntax or other flags. This results +in a faster and more compact format. + +See also the section I later in this document. + +The main use for this flag is to produce JSON texts that can be +transmitted over a 7-bit channel, as the encoded JSON texts will not +contain any 8 bit characters. + + JSON::PP->new->ascii(1)->encode([chr 0x10401]) + => ["\ud801\udc01"] + +=head2 latin1 + + $json = $json->latin1([$enable]) + + $enabled = $json->get_latin1 + +If C<$enable> is true (or missing), then the C method will encode +the resulting JSON text as latin1 (or iso-8859-1), escaping any characters +outside the code range C<0..255>. The resulting string can be treated as a +latin1-encoded JSON text or a native Unicode string. The C method +will not be affected in any way by this flag, as C by default +expects Unicode, which is a strict superset of latin1. + +If C<$enable> is false, then the C method will not escape Unicode +characters unless required by the JSON syntax or other flags. + +See also the section I later in this document. + +The main use for this flag is efficiently encoding binary data as JSON +text, as most octets will not be escaped, resulting in a smaller encoded +size. The disadvantage is that the resulting JSON text is encoded +in latin1 (and must correctly be treated as such when storing and +transferring), a rare encoding for JSON. It is therefore most useful when +you want to store data structures known to contain binary data efficiently +in files or databases, not when talking to other JSON encoders/decoders. + + JSON::PP->new->latin1->encode (["\x{89}\x{abc}"] + => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) + +=head2 utf8 + + $json = $json->utf8([$enable]) + + $enabled = $json->get_utf8 + +If C<$enable> is true (or missing), then the C method will encode +the JSON result into UTF-8, as required by many protocols, while the +C method expects to be handled an UTF-8-encoded string. Please +note that UTF-8-encoded strings do not contain any characters outside the +range C<0..255>, they are thus useful for bytewise/binary I/O. In future +versions, enabling this option might enable autodetection of the UTF-16 +and UTF-32 encoding families, as described in RFC4627. + +If C<$enable> is false, then the C method will return the JSON +string as a (non-encoded) Unicode string, while C expects thus a +Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs +to be done yourself, e.g. using the Encode module. + +See also the section I later in this document. + +Example, output UTF-16BE-encoded JSON: + + use Encode; + $jsontext = encode "UTF-16BE", JSON::PP->new->encode ($object); + +Example, decode UTF-32LE-encoded JSON: + + use Encode; + $object = JSON::PP->new->decode (decode "UTF-32LE", $jsontext); + +=head2 pretty + + $json = $json->pretty([$enable]) + +This enables (or disables) all of the C, C and +C (and in the future possibly more) flags in one call to +generate the most readable (or most compact) form possible. + +=head2 indent + + $json = $json->indent([$enable]) + + $enabled = $json->get_indent + +If C<$enable> is true (or missing), then the C method will use a multiline +format as output, putting every array member or object/hash key-value pair +into its own line, indenting them properly. + +If C<$enable> is false, no newlines or indenting will be produced, and the +resulting JSON text is guaranteed not to contain any C. + +This setting has no effect when decoding JSON texts. + +The default indent space length is three. +You can use C to change the length. + +=head2 space_before + + $json = $json->space_before([$enable]) + + $enabled = $json->get_space_before + +If C<$enable> is true (or missing), then the C method will add an extra +optional space before the C<:> separating keys from values in JSON objects. + +If C<$enable> is false, then the C method will not add any extra +space at those places. + +This setting has no effect when decoding JSON texts. You will also +most likely combine this setting with C. + +Example, space_before enabled, space_after and indent disabled: + + {"key" :"value"} + +=head2 space_after + + $json = $json->space_after([$enable]) + + $enabled = $json->get_space_after + +If C<$enable> is true (or missing), then the C method will add an extra +optional space after the C<:> separating keys from values in JSON objects +and extra whitespace after the C<,> separating key-value pairs and array +members. + +If C<$enable> is false, then the C method will not add any extra +space at those places. + +This setting has no effect when decoding JSON texts. + +Example, space_before and indent disabled, space_after enabled: + + {"key": "value"} + +=head2 relaxed + + $json = $json->relaxed([$enable]) + + $enabled = $json->get_relaxed + +If C<$enable> is true (or missing), then C will accept some +extensions to normal JSON syntax (see below). C will not be +affected in anyway. I. I suggest only to use this option to +parse application-specific files written by humans (configuration files, +resource files etc.) + +If C<$enable> is false (the default), then C will only accept +valid JSON texts. + +Currently accepted extensions are: + +=over 4 + +=item * list items can have an end-comma + +JSON I array elements and key-value pairs with commas. This +can be annoying if you write JSON texts manually and want to be able to +quickly append elements, so this extension accepts comma at the end of +such items not just between them: + + [ + 1, + 2, <- this comma not normally allowed + ] + { + "k1": "v1", + "k2": "v2", <- this comma not normally allowed + } + +=item * shell-style '#'-comments + +Whenever JSON allows whitespace, shell-style comments are additionally +allowed. They are terminated by the first carriage-return or line-feed +character, after which more white-space and comments are allowed. + + [ + 1, # this comment not allowed in JSON + # neither this one... + ] + +=item * C-style multiple-line '/* */'-comments (JSON::PP only) + +Whenever JSON allows whitespace, C-style multiple-line comments are additionally +allowed. Everything between C and C<*/> is a comment, after which +more white-space and comments are allowed. + + [ + 1, /* this comment not allowed in JSON */ + /* neither this one... */ + ] + +=item * C++-style one-line '//'-comments (JSON::PP only) + +Whenever JSON allows whitespace, C++-style one-line comments are additionally +allowed. They are terminated by the first carriage-return or line-feed +character, after which more white-space and comments are allowed. + + [ + 1, // this comment not allowed in JSON + // neither this one... + ] + +=item * literal ASCII TAB characters in strings + +Literal ASCII TAB characters are now allowed in strings (and treated as +C<\t>). + + [ + "Hello\tWorld", + "HelloWorld", # literal would not normally be allowed + ] + +=back + +=head2 canonical + + $json = $json->canonical([$enable]) + + $enabled = $json->get_canonical + +If C<$enable> is true (or missing), then the C method will output JSON objects +by sorting their keys. This is adding a comparatively high overhead. + +If C<$enable> is false, then the C method will output key-value +pairs in the order Perl stores them (which will likely change between runs +of the same script, and can change even within the same run from 5.18 +onwards). + +This option is useful if you want the same data structure to be encoded as +the same JSON text (given the same overall settings). If it is disabled, +the same hash might be encoded differently even if contains the same data, +as key-value pairs have no inherent ordering in Perl. + +This setting has no effect when decoding JSON texts. + +This setting has currently no effect on tied hashes. + +=head2 allow_nonref + + $json = $json->allow_nonref([$enable]) + + $enabled = $json->get_allow_nonref + +Unlike other boolean options, this opotion is enabled by default beginning +with version C<4.0>. + +If C<$enable> is true (or missing), then the C method can convert a +non-reference into its corresponding string, number or null JSON value, +which is an extension to RFC4627. Likewise, C will accept those JSON +values instead of croaking. + +If C<$enable> is false, then the C method will croak if it isn't +passed an arrayref or hashref, as JSON texts must either be an object +or array. Likewise, C will croak if given something that is not a +JSON object or array. + +Example, encode a Perl scalar as JSON value without enabled C, +resulting in an error: + + JSON::PP->new->allow_nonref(0)->encode ("Hello, World!") + => hash- or arrayref expected... + +=head2 allow_unknown + + $json = $json->allow_unknown([$enable]) + + $enabled = $json->get_allow_unknown + +If C<$enable> is true (or missing), then C will I throw an +exception when it encounters values it cannot represent in JSON (for +example, filehandles) but instead will encode a JSON C value. Note +that blessed objects are not included here and are handled separately by +c. + +If C<$enable> is false (the default), then C will throw an +exception when it encounters anything it cannot encode as JSON. + +This option does not affect C in any way, and it is recommended to +leave it off unless you know your communications partner. + +=head2 allow_blessed + + $json = $json->allow_blessed([$enable]) + + $enabled = $json->get_allow_blessed + +See L for details. + +If C<$enable> is true (or missing), then the C method will not +barf when it encounters a blessed reference that it cannot convert +otherwise. Instead, a JSON C value is encoded instead of the object. + +If C<$enable> is false (the default), then C will throw an +exception when it encounters a blessed object that it cannot convert +otherwise. + +This setting has no effect on C. + +=head2 convert_blessed + + $json = $json->convert_blessed([$enable]) + + $enabled = $json->get_convert_blessed + +See L for details. + +If C<$enable> is true (or missing), then C, upon encountering a +blessed object, will check for the availability of the C method +on the object's class. If found, it will be called in scalar context and +the resulting scalar will be encoded instead of the object. + +The C method may safely call die if it wants. If C +returns other blessed objects, those will be handled in the same +way. C must take care of not causing an endless recursion cycle +(== crash) in this case. The name of C was chosen because other +methods called by the Perl core (== not by the user of the object) are +usually in upper case letters and to avoid collisions with any C +function or method. + +If C<$enable> is false (the default), then C will not consider +this type of conversion. + +This setting has no effect on C. + +=head2 allow_tags + + $json = $json->allow_tags([$enable]) + + $enabled = $json->get_allow_tags + +See L for details. + +If C<$enable> is true (or missing), then C, upon encountering a +blessed object, will check for the availability of the C method on +the object's class. If found, it will be used to serialise the object into +a nonstandard tagged JSON value (that JSON decoders cannot decode). + +It also causes C to parse such tagged JSON values and deserialise +them via a call to the C method. + +If C<$enable> is false (the default), then C will not consider +this type of conversion, and tagged JSON values will cause a parse error +in C, as if tags were not part of the grammar. + +=head2 boolean_values + + $json->boolean_values([$false, $true]) + + ($false, $true) = $json->get_boolean_values + +By default, JSON booleans will be decoded as overloaded +C<$JSON::PP::false> and C<$JSON::PP::true> objects. + +With this method you can specify your own boolean values for decoding - +on decode, JSON C will be decoded as a copy of C<$false>, and JSON +C will be decoded as C<$true> ("copy" here is the same thing as +assigning a value to another variable, i.e. C<$copy = $false>). + +This is useful when you want to pass a decoded data structure directly +to other serialisers like YAML, Data::MessagePack and so on. + +Note that this works only when you C. You can set incompatible +boolean objects (like L), but when you C a data structure +with such boolean objects, you still need to enable C +(and add a C method if necessary). + +Calling this method without any arguments will reset the booleans +to their default values. + +C will return both C<$false> and C<$true> values, or +the empty list when they are set to the default. + +=head2 core_bools + + $json->core_bools([$enable]); + +If C<$enable> is true (or missing), then C, will produce standard +perl boolean values. Equivalent to calling: + + $json->boolean_values(!!1, !!0) + +C will return true if this has been set. On perl 5.36, it will +also return true if the boolean values have been set to perl's core booleans +using the C method. + +The methods C and C are provided as aliases +for compatibility with L. + +=head2 filter_json_object + + $json = $json->filter_json_object([$coderef]) + +When C<$coderef> is specified, it will be called from C each +time it decodes a JSON object. The only argument is a reference to +the newly-created hash. If the code references returns a single scalar +(which need not be a reference), this value (or rather a copy of it) is +inserted into the deserialised data structure. If it returns an empty +list (NOTE: I C, which is a valid scalar), the original +deserialised hash will be inserted. This setting can slow down decoding +considerably. + +When C<$coderef> is omitted or undefined, any existing callback will +be removed and C will not change the deserialised hash in any +way. + +Example, convert all JSON objects into the integer 5: + + my $js = JSON::PP->new->filter_json_object(sub { 5 }); + # returns [5] + $js->decode('[{}]'); + # returns 5 + $js->decode('{"a":1, "b":2}'); + +=head2 filter_json_single_key_object + + $json = $json->filter_json_single_key_object($key [=> $coderef]) + +Works remotely similar to C, but is only called for +JSON objects having a single key named C<$key>. + +This C<$coderef> is called before the one specified via +C, if any. It gets passed the single value in the JSON +object. If it returns a single value, it will be inserted into the data +structure. If it returns nothing (not even C but the empty list), +the callback from C will be called next, as if no +single-key callback were specified. + +If C<$coderef> is omitted or undefined, the corresponding callback will be +disabled. There can only ever be one callback for a given key. + +As this callback gets called less often then the C +one, decoding speed will not usually suffer as much. Therefore, single-key +objects make excellent targets to serialise Perl objects into, especially +as single-key JSON objects are as close to the type-tagged value concept +as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not +support this in any way, so you need to make sure your data never looks +like a serialised Perl hash. + +Typical names for the single object key are C<__class_whatever__>, or +C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even +things like C<__class_md5sum(classname)__>, to reduce the risk of clashing +with real hashes. + +Example, decode JSON objects of the form C<< { "__widget__" => } >> +into the corresponding C<< $WIDGET{} >> object: + + # return whatever is in $WIDGET{5}: + JSON::PP + ->new + ->filter_json_single_key_object (__widget__ => sub { + $WIDGET{ $_[0] } + }) + ->decode ('{"__widget__": 5') + + # this can be used with a TO_JSON method in some "widget" class + # for serialisation to json: + sub WidgetBase::TO_JSON { + my ($self) = @_; + + unless ($self->{id}) { + $self->{id} = ..get..some..id..; + $WIDGET{$self->{id}} = $self; + } + + { __widget__ => $self->{id} } + } + +=head2 shrink + + $json = $json->shrink([$enable]) + + $enabled = $json->get_shrink + +If C<$enable> is true (or missing), the string returned by C will +be shrunk (i.e. downgraded if possible). + +The actual definition of what shrink does might change in future versions, +but it will always try to save space at the expense of time. + +If C<$enable> is false, then JSON::PP does nothing. + +=head2 max_depth + + $json = $json->max_depth([$maximum_nesting_depth]) + + $max_depth = $json->get_max_depth + +Sets the maximum nesting level (default C<512>) accepted while encoding +or decoding. If a higher nesting level is detected in JSON text or a Perl +data structure, then the encoder and decoder will stop and croak at that +point. + +Nesting level is defined by number of hash- or arrayrefs that the encoder +needs to traverse to reach a given point or the number of C<{> or C<[> +characters without their matching closing parenthesis crossed to reach a +given character in a string. + +Setting the maximum depth to one disallows any nesting, so that ensures +that the object is only a single hash/object or array. + +If no argument is given, the highest possible setting will be used, which +is rarely useful. + +See L for more info on why this is useful. + +=head2 max_size + + $json = $json->max_size([$maximum_string_size]) + + $max_size = $json->get_max_size + +Set the maximum length a JSON text may have (in bytes) where decoding is +being attempted. The default is C<0>, meaning no limit. When C +is called on a string that is longer then this many bytes, it will not +attempt to decode the string but throw an exception. This setting has no +effect on C (yet). + +If no argument is given, the limit check will be deactivated (same as when +C<0> is specified). + +See L for more info on why this is useful. + +=head2 encode + + $json_text = $json->encode($perl_scalar) + +Converts the given Perl value or data structure to its JSON +representation. Croaks on error. + +=head2 decode + + $perl_scalar = $json->decode($json_text) + +The opposite of C: expects a JSON text and tries to parse it, +returning the resulting simple scalar or reference. Croaks on error. + +=head2 decode_prefix + + ($perl_scalar, $characters) = $json->decode_prefix($json_text) + +This works like the C method, but instead of raising an exception +when there is trailing garbage after the first JSON object, it will +silently stop parsing there and return the number of characters consumed +so far. + +This is useful if your JSON texts are not delimited by an outer protocol +and you need to know where the JSON text ends. + + JSON::PP->new->decode_prefix ("[1] the tail") + => ([1], 3) + +=head1 FLAGS FOR JSON::PP ONLY + +The following flags and properties are for JSON::PP only. If you use +any of these, you can't make your application run faster by replacing +JSON::PP with JSON::XS. If you need these and also speed boost, +you might want to try L, a fork of JSON::XS by +Reini Urban, which supports some of these (with a different set of +incompatibilities). Most of these historical flags are only kept +for backward compatibility, and should not be used in a new application. + +=head2 allow_singlequote + + $json = $json->allow_singlequote([$enable]) + $enabled = $json->get_allow_singlequote + +If C<$enable> is true (or missing), then C will accept +invalid JSON texts that contain strings that begin and end with +single quotation marks. C will not be affected in any way. +I. I suggest only to use this option to +parse application-specific files written by humans (configuration +files, resource files etc.) + +If C<$enable> is false (the default), then C will only accept +valid JSON texts. + + $json->allow_singlequote->decode(qq|{"foo":'bar'}|); + $json->allow_singlequote->decode(qq|{'foo':"bar"}|); + $json->allow_singlequote->decode(qq|{'foo':'bar'}|); + +=head2 allow_barekey + + $json = $json->allow_barekey([$enable]) + $enabled = $json->get_allow_barekey + +If C<$enable> is true (or missing), then C will accept +invalid JSON texts that contain JSON objects whose names don't +begin and end with quotation marks. C will not be affected +in any way. I. I suggest only to use this option to +parse application-specific files written by humans (configuration +files, resource files etc.) + +If C<$enable> is false (the default), then C will only accept +valid JSON texts. + + $json->allow_barekey->decode(qq|{foo:"bar"}|); + +=head2 allow_bignum + + $json = $json->allow_bignum([$enable]) + $enabled = $json->get_allow_bignum + +If C<$enable> is true (or missing), then C will convert +big integers Perl cannot handle as integer into L +objects and convert floating numbers into L +objects. C will convert C and C +objects into JSON numbers. + + $json->allow_nonref->allow_bignum; + $bigfloat = $json->decode('2.000000000000000000000000001'); + print $json->encode($bigfloat); + # => 2.000000000000000000000000001 + +See also L. + +=head2 loose + + $json = $json->loose([$enable]) + $enabled = $json->get_loose + +If C<$enable> is true (or missing), then C will accept +invalid JSON texts that contain unescaped [\x00-\x1f\x22\x5c] +characters. C will not be affected in any way. +I. I suggest only to use this option to +parse application-specific files written by humans (configuration +files, resource files etc.) + +If C<$enable> is false (the default), then C will only accept +valid JSON texts. + + $json->loose->decode(qq|["abc + def"]|); + +=head2 escape_slash + + $json = $json->escape_slash([$enable]) + $enabled = $json->get_escape_slash + +If C<$enable> is true (or missing), then C will explicitly +escape I (solidus; C) characters to reduce the risk of +XSS (cross site scripting) that may be caused by C<< >> +in a JSON text, with the cost of bloating the size of JSON texts. + +This option may be useful when you embed JSON in HTML, but embedding +arbitrary JSON in HTML (by some HTML template toolkit or by string +interpolation) is risky in general. You must escape necessary +characters in correct order, depending on the context. + +C will not be affected in any way. + +=head2 indent_length + + $json = $json->indent_length($number_of_spaces) + $length = $json->get_indent_length + +This option is only useful when you also enable C or C. + +JSON::XS indents with three spaces when you C (if requested +by C or C), and the number cannot be changed. +JSON::PP allows you to change/get the number of indent spaces with these +mutator/accessor. The default number of spaces is three (the same as +JSON::XS), and the acceptable range is from C<0> (no indentation; +it'd be better to disable indentation by C) to C<15>. + +=head2 sort_by + + $json = $json->sort_by($code_ref) + $json = $json->sort_by($subroutine_name) + +If you just want to sort keys (names) in JSON objects when you +C, enable C option (see above) that allows you to +sort object keys alphabetically. + +If you do need to sort non-alphabetically for whatever reasons, +you can give a code reference (or a subroutine name) to C, +then the argument will be passed to Perl's C built-in function. + +As the sorting is done in the JSON::PP scope, you usually need to +prepend C to the subroutine name, and the special variables +C<$a> and C<$b> used in the subrontine used by C function. + +Example: + + my %ORDER = (id => 1, class => 2, name => 3); + $json->sort_by(sub { + ($ORDER{$JSON::PP::a} // 999) <=> ($ORDER{$JSON::PP::b} // 999) + or $JSON::PP::a cmp $JSON::PP::b + }); + print $json->encode([ + {name => 'CPAN', id => 1, href => 'http://cpan.org'} + ]); + # [{"id":1,"name":"CPAN","href":"http://cpan.org"}] + +Note that C affects all the plain hashes in the data structure. +If you need finer control, C necessary hashes with a module that +implements ordered hash (such as L and L). +C and C don't affect the key order in Cd +hashes. + + use Hash::Ordered; + tie my %hash, 'Hash::Ordered', + (name => 'CPAN', id => 1, href => 'http://cpan.org'); + print $json->encode([\%hash]); + # [{"name":"CPAN","id":1,"href":"http://cpan.org"}] # order is kept + +=head1 INCREMENTAL PARSING + +This section is also taken from JSON::XS. + +In some cases, there is the need for incremental parsing of JSON +texts. While this module always has to keep both JSON text and resulting +Perl data structure in memory at one time, it does allow you to parse a +JSON stream incrementally. It does so by accumulating text until it has +a full JSON object, which it then can decode. This process is similar to +using C to see if a full JSON object is available, but +is much more efficient (and can be implemented with a minimum of method +calls). + +JSON::PP will only attempt to parse the JSON text once it is sure it +has enough text to get a decisive result, using a very simple but +truly incremental parser. This means that it sometimes won't stop as +early as the full parser, for example, it doesn't detect mismatched +parentheses. The only thing it guarantees is that it starts decoding as +soon as a syntactically valid JSON text has been seen. This means you need +to set resource limits (e.g. C) to ensure the parser will stop +parsing in the presence if syntax errors. + +The following methods implement this incremental parser. + +=head2 incr_parse + + $json->incr_parse( [$string] ) # void context + + $obj_or_undef = $json->incr_parse( [$string] ) # scalar context + + @obj_or_empty = $json->incr_parse( [$string] ) # list context + +This is the central parsing function. It can both append new text and +extract objects from the stream accumulated so far (both of these +functions are optional). + +If C<$string> is given, then this string is appended to the already +existing JSON fragment stored in the C<$json> object. + +After that, if the function is called in void context, it will simply +return without doing anything further. This can be used to add more text +in as many chunks as you want. + +If the method is called in scalar context, then it will try to extract +exactly I JSON object. If that is successful, it will return this +object, otherwise it will return C. If there is a parse error, +this method will croak just as C would do (one can then use +C to skip the erroneous part). This is the most common way of +using the method. + +And finally, in list context, it will try to extract as many objects +from the stream as it can find and return them, or the empty list +otherwise. For this to work, there must be no separators (other than +whitespace) between the JSON objects or arrays, instead they must be +concatenated back-to-back. If an error occurs, an exception will be +raised as in the scalar context case. Note that in this case, any +previously-parsed JSON texts will be lost. + +Example: Parse some JSON arrays/objects in a given string and return +them. + + my @objs = JSON::PP->new->incr_parse ("[5][7][1,2]"); + +=head2 incr_text + + $lvalue_string = $json->incr_text + +This method returns the currently stored JSON fragment as an lvalue, that +is, you can manipulate it. This I works when a preceding call to +C in I successfully returned an object. Under +all other circumstances you must not call this function (I mean it. +although in simple tests it might actually work, it I fail under +real world conditions). As a special exception, you can also call this +method before having parsed anything. + +That means you can only use this function to look at or manipulate text +before or after complete JSON objects, not while the parser is in the +middle of parsing a JSON object. + +This function is useful in two cases: a) finding the trailing text after a +JSON object or b) parsing multiple JSON objects separated by non-JSON text +(such as commas). + +=head2 incr_skip + + $json->incr_skip + +This will reset the state of the incremental parser and will remove +the parsed text from the input buffer so far. This is useful after +C died, in which case the input buffer and incremental parser +state is left unchanged, to skip the text parsed so far and to reset the +parse state. + +The difference to C is that only text until the parse error +occurred is removed. + +=head2 incr_reset + + $json->incr_reset + +This completely resets the incremental parser, that is, after this call, +it will be as if the parser had never parsed anything. + +This is useful if you want to repeatedly parse JSON objects and want to +ignore any trailing data, which means you have to reset the parser after +each successful decode. + +=head1 MAPPING + +Most of this section is also taken from JSON::XS. + +This section describes how JSON::PP maps Perl values to JSON values and +vice versa. These mappings are designed to "do the right thing" in most +circumstances automatically, preserving round-tripping characteristics +(what you put in comes out as something equivalent). + +For the more enlightened: note that in the following descriptions, +lowercase I refers to the Perl interpreter, while uppercase I +refers to the abstract Perl language itself. + +=head2 JSON -> PERL + +=over 4 + +=item object + +A JSON object becomes a reference to a hash in Perl. No ordering of object +keys is preserved (JSON does not preserve object key ordering itself). + +=item array + +A JSON array becomes a reference to an array in Perl. + +=item string + +A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON +are represented by the same codepoints in the Perl string, so no manual +decoding is necessary. + +=item number + +A JSON number becomes either an integer, numeric (floating point) or +string scalar in perl, depending on its range and any fractional parts. On +the Perl level, there is no difference between those as Perl handles all +the conversion details, but an integer may take slightly less memory and +might represent more values exactly than floating point numbers. + +If the number consists of digits only, JSON::PP will try to represent +it as an integer value. If that fails, it will try to represent it as +a numeric (floating point) value if that is possible without loss of +precision. Otherwise it will preserve the number as a string value (in +which case you lose roundtripping ability, as the JSON number will be +re-encoded to a JSON string). + +Numbers containing a fractional or exponential part will always be +represented as numeric (floating point) values, possibly at a loss of +precision (in which case you might lose perfect roundtripping ability, but +the JSON number will still be re-encoded as a JSON number). + +Note that precision is not accuracy - binary floating point values cannot +represent most decimal fractions exactly, and when converting from and to +floating point, JSON::PP only guarantees precision up to but not including +the least significant bit. + +When C is enabled, big integer values and any numeric +values will be converted into L and L +objects respectively, without becoming string scalars or losing +precision. + +=item true, false + +These JSON atoms become C and C, +respectively. They are overloaded to act almost exactly like the numbers +C<1> and C<0>. You can check whether a scalar is a JSON boolean by using +the C function. + +=item null + +A JSON null atom becomes C in Perl. + +=item shell-style comments (C<< # I >>) + +As a nonstandard extension to the JSON syntax that is enabled by the +C setting, shell-style comments are allowed. They can start +anywhere outside strings and go till the end of the line. + +=item tagged values (C<< (I)I >>). + +Another nonstandard extension to the JSON syntax, enabled with the +C setting, are tagged values. In this implementation, the +I must be a perl package/class name encoded as a JSON string, and the +I must be a JSON array encoding optional constructor arguments. + +See L, below, for details. + +=back + + +=head2 PERL -> JSON + +The mapping from Perl to JSON is slightly more difficult, as Perl is a +truly typeless language, so we can only guess which JSON type is meant by +a Perl value. + +=over 4 + +=item hash references + +Perl hash references become JSON objects. As there is no inherent +ordering in hash keys (or JSON objects), they will usually be encoded +in a pseudo-random order. JSON::PP can optionally sort the hash keys +(determined by the I flag and/or I property), so +the same data structure will serialise to the same JSON text (given +same settings and version of JSON::PP), but this incurs a runtime +overhead and is only rarely useful, e.g. when you want to compare some +JSON text against another for equality. + +=item array references + +Perl array references become JSON arrays. + +=item other references + +Other unblessed references are generally not allowed and will cause an +exception to be thrown, except for references to the integers C<0> and +C<1>, which get turned into C and C atoms in JSON. You can +also use C and C to improve +readability. + + to_json [\0, JSON::PP::true] # yields [false,true] + +=item JSON::PP::true, JSON::PP::false + +These special values become JSON true and JSON false values, +respectively. You can also use C<\1> and C<\0> directly if you want. + +=item JSON::PP::null + +This special value becomes JSON null. + +=item blessed objects + +Blessed objects are not directly representable in JSON, but C +allows various ways of handling objects. See L, +below, for details. + +=item simple scalars + +Simple Perl scalars (any scalar that is not a reference) are the most +difficult objects to encode: JSON::PP will encode undefined scalars as +JSON C values, scalars that have last been used in a string context +before encoding as JSON strings, and anything else as number value: + + # dump as number + encode_json [2] # yields [2] + encode_json [-3.0e17] # yields [-3e+17] + my $value = 5; encode_json [$value] # yields [5] + + # used as string, so dump as string + print $value; + encode_json [$value] # yields ["5"] + + # undef becomes null + encode_json [undef] # yields [null] + +You can force the type to be a JSON string by stringifying it: + + my $x = 3.1; # some variable containing a number + "$x"; # stringified + $x .= ""; # another, more awkward way to stringify + print $x; # perl does it for you, too, quite often + # (but for older perls) + +You can force the type to be a JSON number by numifying it: + + my $x = "3"; # some variable containing a string + $x += 0; # numify it, ensuring it will be dumped as a number + $x *= 1; # same thing, the choice is yours. + +You can not currently force the type in other, less obscure, ways. + +Since version 2.91_01, JSON::PP uses a different number detection logic +that converts a scalar that is possible to turn into a number safely. +The new logic is slightly faster, and tends to help people who use older +perl or who want to encode complicated data structure. However, this may +results in a different JSON text from the one JSON::XS encodes (and +thus may break tests that compare entire JSON texts). If you do +need the previous behavior for compatibility or for finer control, +set PERL_JSON_PP_USE_B environmental variable to true before you +C JSON::PP (or JSON.pm). + +Note that numerical precision has the same meaning as under Perl (so +binary to decimal conversion follows the same rules as in Perl, which +can differ to other languages). Also, your perl interpreter might expose +extensions to the floating point numbers of your platform, such as +infinities or NaN's - these cannot be represented in JSON, and it is an +error to pass those in. + +JSON::PP (and JSON::XS) trusts what you pass to C method +(or C function) is a clean, validated data structure with +values that can be represented as valid JSON values only, because it's +not from an external data source (as opposed to JSON texts you pass to +C or C, which JSON::PP considers tainted and +doesn't trust). As JSON::PP doesn't know exactly what you and consumers +of your JSON texts want the unexpected values to be (you may want to +convert them into null, or to stringify them with or without +normalisation (string representation of infinities/NaN may vary +depending on platforms), or to croak without conversion), you're advised +to do what you and your consumers need before you encode, and also not +to numify values that may start with values that look like a number +(including infinities/NaN), without validating. + +=back + +=head2 OBJECT SERIALISATION + +As JSON cannot directly represent Perl objects, you have to choose between +a pure JSON representation (without the ability to deserialise the object +automatically again), and a nonstandard extension to the JSON syntax, +tagged values. + +=head3 SERIALISATION + +What happens when C encounters a Perl object depends on the +C, C, C and C +settings, which are used in this order: + +=over 4 + +=item 1. C is enabled and the object has a C method. + +In this case, C creates a tagged JSON value, using a nonstandard +extension to the JSON syntax. + +This works by invoking the C method on the object, with the first +argument being the object to serialise, and the second argument being the +constant string C to distinguish it from other serialisers. + +The C method can return any number of values (i.e. zero or +more). These values and the paclkage/classname of the object will then be +encoded as a tagged JSON value in the following format: + + ("classname")[FREEZE return values...] + +e.g.: + + ("URI")["http://www.google.com/"] + ("MyDate")[2013,10,29] + ("ImageData::JPEG")["Z3...VlCg=="] + +For example, the hypothetical C C method might use the +objects C and C members to encode the object: + + sub My::Object::FREEZE { + my ($self, $serialiser) = @_; + + ($self->{type}, $self->{id}) + } + +=item 2. C is enabled and the object has a C method. + +In this case, the C method of the object is invoked in scalar +context. It must return a single scalar that can be directly encoded into +JSON. This scalar replaces the object in the JSON text. + +For example, the following C method will convert all L +objects to JSON strings when serialised. The fact that these values +originally were L objects is lost. + + sub URI::TO_JSON { + my ($uri) = @_; + $uri->as_string + } + +=item 3. C is enabled and the object is a C or C. + +The object will be serialised as a JSON number value. + +=item 4. C is enabled. + +The object will be serialised as a JSON null value. + +=item 5. none of the above + +If none of the settings are enabled or the respective methods are missing, +C throws an exception. + +=back + +=head3 DESERIALISATION + +For deserialisation there are only two cases to consider: either +nonstandard tagging was used, in which case C decides, +or objects cannot be automatically be deserialised, in which +case you can use postprocessing or the C or +C callbacks to get some real objects our of +your JSON. + +This section only considers the tagged value case: a tagged JSON object +is encountered during decoding and C is disabled, a parse +error will result (as if tagged values were not part of the grammar). + +If C is enabled, C will look up the C method +of the package/classname used during serialisation (it will not attempt +to load the package as a Perl module). If there is no such method, the +decoding will fail with an error. + +Otherwise, the C method is invoked with the classname as first +argument, the constant string C as second argument, and all the +values from the JSON array (the values originally returned by the +C method) as remaining arguments. + +The method must then return the object. While technically you can return +any Perl scalar, you might have to enable the C setting to +make that work in all cases, so better return an actual blessed reference. + +As an example, let's implement a C function that regenerates the +C from the C example earlier: + + sub My::Object::THAW { + my ($class, $serialiser, $type, $id) = @_; + + $class->new (type => $type, id => $id) + } + + +=head1 ENCODING/CODESET FLAG NOTES + +This section is taken from JSON::XS. + +The interested reader might have seen a number of flags that signify +encodings or codesets - C, C and C. There seems to be +some confusion on what these do, so here is a short comparison: + +C controls whether the JSON text created by C (and expected +by C) is UTF-8 encoded or not, while C and C only +control whether C escapes character values outside their respective +codeset range. Neither of these flags conflict with each other, although +some combinations make less sense than others. + +Care has been taken to make all flags symmetrical with respect to +C and C, that is, texts encoded with any combination of +these flag values will be correctly decoded when the same flags are used +- in general, if you use different flag settings while encoding vs. when +decoding you likely have a bug somewhere. + +Below comes a verbose discussion of these flags. Note that a "codeset" is +simply an abstract set of character-codepoint pairs, while an encoding +takes those codepoint numbers and I them, in our case into +octets. Unicode is (among other things) a codeset, UTF-8 is an encoding, +and ISO-8859-1 (= latin 1) and ASCII are both codesets I encodings at +the same time, which can be confusing. + +=over 4 + +=item C flag disabled + +When C is disabled (the default), then C/C generate +and expect Unicode strings, that is, characters with high ordinal Unicode +values (> 255) will be encoded as such characters, and likewise such +characters are decoded as-is, no changes to them will be done, except +"(re-)interpreting" them as Unicode codepoints or Unicode characters, +respectively (to Perl, these are the same thing in strings unless you do +funny/weird/dumb stuff). + +This is useful when you want to do the encoding yourself (e.g. when you +want to have UTF-16 encoded JSON texts) or when some other layer does +the encoding for you (for example, when printing to a terminal using a +filehandle that transparently encodes to UTF-8 you certainly do NOT want +to UTF-8 encode your data first and have Perl encode it another time). + +=item C flag enabled + +If the C-flag is enabled, C/C will encode all +characters using the corresponding UTF-8 multi-byte sequence, and will +expect your input strings to be encoded as UTF-8, that is, no "character" +of the input string must have any value > 255, as UTF-8 does not allow +that. + +The C flag therefore switches between two modes: disabled means you +will get a Unicode string in Perl, enabled means you get an UTF-8 encoded +octet/binary string in Perl. + +=item C or C flags enabled + +With C (or C) enabled, C will escape characters +with ordinal values > 255 (> 127 with C) and encode the remaining +characters as specified by the C flag. + +If C is disabled, then the result is also correctly encoded in those +character sets (as both are proper subsets of Unicode, meaning that a +Unicode string with all character values < 256 is the same thing as a +ISO-8859-1 string, and a Unicode string with all character values < 128 is +the same thing as an ASCII string in Perl). + +If C is enabled, you still get a correct UTF-8-encoded string, +regardless of these flags, just some more characters will be escaped using +C<\uXXXX> then before. + +Note that ISO-8859-1-I strings are not compatible with UTF-8 +encoding, while ASCII-encoded strings are. That is because the ISO-8859-1 +encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I being +a subset of Unicode), while ASCII is. + +Surprisingly, C will ignore these flags and so treat all input +values as governed by the C flag. If it is disabled, this allows you +to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of +Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings. + +So neither C nor C are incompatible with the C flag - +they only govern when the JSON output engine escapes a character or not. + +The main use for C is to relatively efficiently store binary data +as JSON, at the expense of breaking compatibility with most JSON decoders. + +The main use for C is to force the output to not contain characters +with values > 127, which means you can interpret the resulting string +as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and +8-bit-encoding, and still get the same data structure back. This is useful +when your channel for JSON transfer is not 8-bit clean or the encoding +might be mangled in between (e.g. in mail), and works because ASCII is a +proper subset of most 8-bit and multibyte encodings in use in the world. + +=back + +=head1 BUGS + +Please report bugs on a specific behavior of this module to RT or GitHub +issues (preferred): + +L + +L + +As for new features and requests to change common behaviors, please +ask the author of JSON::XS (Marc Lehmann, Eschmorp[at]schmorp.deE) +first, by email (important!), to keep compatibility among JSON.pm backends. + +Generally speaking, if you need something special for you, you are advised +to create a new module, maybe based on L, which is smaller and +written in a much cleaner way than this module. + +=head1 SEE ALSO + +The F command line utility for quick experiments. + +L, L, and L for faster alternatives. +L and L for easy migration. + +L and L for older perl users. + +RFC4627 (L) + +RFC7159 (L) + +RFC8259 (L) + +=head1 AUTHOR + +Makamaka Hannyaharamitu, Emakamaka[at]cpan.orgE + +=head1 CURRENT MAINTAINER + +Kenichi Ishigaki, Eishigaki[at]cpan.orgE + +=head1 COPYRIGHT AND LICENSE + +Copyright 2007-2016 by Makamaka Hannyaharamitu + +Most of the documentation is taken from JSON::XS by Marc Lehmann + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + +=cut diff --git a/src/perllib/JSON/backportPP/Boolean.pm b/src/perllib/JSON/backportPP/Boolean.pm new file mode 100644 index 0000000..08228b1 --- /dev/null +++ b/src/perllib/JSON/backportPP/Boolean.pm @@ -0,0 +1,44 @@ +package # This is JSON::backportPP + JSON::PP::Boolean; + +use strict; +require overload; +local $^W; +overload::unimport('overload', qw(0+ ++ -- fallback)); +overload::import('overload', + "0+" => sub { ${$_[0]} }, + "++" => sub { $_[0] = ${$_[0]} + 1 }, + "--" => sub { $_[0] = ${$_[0]} - 1 }, + fallback => 1, +); + +$JSON::backportPP::Boolean::VERSION = '4.12'; + +1; + +__END__ + +=head1 NAME + +JSON::PP::Boolean - dummy module providing JSON::PP::Boolean + +=head1 SYNOPSIS + + # do not "use" yourself + +=head1 DESCRIPTION + +This module exists only to provide overload resolution for Storable and similar modules. See +L for more info about this class. + +=head1 AUTHOR + +This idea is from L written by Marc Lehmann + +=head1 LICENSE + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + +=cut + diff --git a/src/perllib/JSON/backportPP/Compat5005.pm b/src/perllib/JSON/backportPP/Compat5005.pm new file mode 100644 index 0000000..139990e --- /dev/null +++ b/src/perllib/JSON/backportPP/Compat5005.pm @@ -0,0 +1,131 @@ +package # This is JSON::backportPP + JSON::backportPP5005; + +use 5.005; +use strict; + +my @properties; + +$JSON::PP5005::VERSION = '1.10'; + +BEGIN { + + sub utf8::is_utf8 { + 0; # It is considered that UTF8 flag off for Perl 5.005. + } + + sub utf8::upgrade { + } + + sub utf8::downgrade { + 1; # must always return true. + } + + sub utf8::encode { + } + + sub utf8::decode { + } + + *JSON::PP::JSON_PP_encode_ascii = \&_encode_ascii; + *JSON::PP::JSON_PP_encode_latin1 = \&_encode_latin1; + *JSON::PP::JSON_PP_decode_surrogates = \&_decode_surrogates; + *JSON::PP::JSON_PP_decode_unicode = \&_decode_unicode; + + # missing in B module. + sub B::SVp_IOK () { 0x01000000; } + sub B::SVp_NOK () { 0x02000000; } + sub B::SVp_POK () { 0x04000000; } + + $INC{'bytes.pm'} = 1; # dummy +} + + + +sub _encode_ascii { + join('', map { $_ <= 127 ? chr($_) : sprintf('\u%04x', $_) } unpack('C*', $_[0]) ); +} + + +sub _encode_latin1 { + join('', map { chr($_) } unpack('C*', $_[0]) ); +} + + +sub _decode_surrogates { # from http://homepage1.nifty.com/nomenclator/unicode/ucs_utf.htm + my $uni = 0x10000 + (hex($_[0]) - 0xD800) * 0x400 + (hex($_[1]) - 0xDC00); # from perlunicode + my $bit = unpack('B32', pack('N', $uni)); + + if ( $bit =~ /^00000000000(...)(......)(......)(......)$/ ) { + my ($w, $x, $y, $z) = ($1, $2, $3, $4); + return pack('B*', sprintf('11110%s10%s10%s10%s', $w, $x, $y, $z)); + } + else { + Carp::croak("Invalid surrogate pair"); + } +} + + +sub _decode_unicode { + my ($u) = @_; + my ($utf8bit); + + if ( $u =~ /^00([89a-f][0-9a-f])$/i ) { # 0x80-0xff + return pack( 'H2', $1 ); + } + + my $bit = unpack("B*", pack("H*", $u)); + + if ( $bit =~ /^00000(.....)(......)$/ ) { + $utf8bit = sprintf('110%s10%s', $1, $2); + } + elsif ( $bit =~ /^(....)(......)(......)$/ ) { + $utf8bit = sprintf('1110%s10%s10%s', $1, $2, $3); + } + else { + Carp::croak("Invalid escaped unicode"); + } + + return pack('B*', $utf8bit); +} + + +sub JSON::PP::incr_text { + $_[0]->{_incr_parser} ||= JSON::PP::IncrParser->new; + + if ( $_[0]->{_incr_parser}->{incr_parsing} ) { + Carp::croak("incr_text can not be called when the incremental parser already started parsing"); + } + + $_[0]->{_incr_parser}->{incr_text} = $_[1] if ( @_ > 1 ); + $_[0]->{_incr_parser}->{incr_text}; +} + + +1; +__END__ + +=pod + +=head1 NAME + +JSON::PP5005 - Helper module in using JSON::PP in Perl 5.005 + +=head1 DESCRIPTION + +JSON::PP calls internally. + +=head1 AUTHOR + +Makamaka Hannyaharamitu, Emakamaka[at]cpan.orgE + + +=head1 COPYRIGHT AND LICENSE + +Copyright 2007-2012 by Makamaka Hannyaharamitu + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + +=cut + diff --git a/src/perllib/JSON/backportPP/Compat5006.pm b/src/perllib/JSON/backportPP/Compat5006.pm new file mode 100644 index 0000000..7736fd8 --- /dev/null +++ b/src/perllib/JSON/backportPP/Compat5006.pm @@ -0,0 +1,173 @@ +package # This is JSON::backportPP + JSON::backportPP56; + +use 5.006; +use strict; + +my @properties; + +$JSON::PP56::VERSION = '1.08'; + +BEGIN { + + sub utf8::is_utf8 { + my $len = length $_[0]; # char length + { + use bytes; # byte length; + return $len != length $_[0]; # if !=, UTF8-flagged on. + } + } + + + sub utf8::upgrade { + ; # noop; + } + + + sub utf8::downgrade ($;$) { + return 1 unless ( utf8::is_utf8( $_[0] ) ); + + if ( _is_valid_utf8( $_[0] ) ) { + my $downgrade; + for my $c ( unpack( "U*", $_[0] ) ) { + if ( $c < 256 ) { + $downgrade .= pack("C", $c); + } + else { + $downgrade .= pack("U", $c); + } + } + $_[0] = $downgrade; + return 1; + } + else { + Carp::croak("Wide character in subroutine entry") unless ( $_[1] ); + 0; + } + } + + + sub utf8::encode ($) { # UTF8 flag off + if ( utf8::is_utf8( $_[0] ) ) { + $_[0] = pack( "C*", unpack( "C*", $_[0] ) ); + } + else { + $_[0] = pack( "U*", unpack( "C*", $_[0] ) ); + $_[0] = pack( "C*", unpack( "C*", $_[0] ) ); + } + } + + + sub utf8::decode ($) { # UTF8 flag on + if ( _is_valid_utf8( $_[0] ) ) { + utf8::downgrade( $_[0] ); + $_[0] = pack( "U*", unpack( "U*", $_[0] ) ); + } + } + + + *JSON::PP::JSON_PP_encode_ascii = \&_encode_ascii; + *JSON::PP::JSON_PP_encode_latin1 = \&_encode_latin1; + *JSON::PP::JSON_PP_decode_surrogates = \&JSON::PP::_decode_surrogates; + *JSON::PP::JSON_PP_decode_unicode = \&JSON::PP::_decode_unicode; + + unless ( defined &B::SVp_NOK ) { # missing in B module. + eval q{ sub B::SVp_NOK () { 0x02000000; } }; + } + +} + + + +sub _encode_ascii { + join('', + map { + $_ <= 127 ? + chr($_) : + $_ <= 65535 ? + sprintf('\u%04x', $_) : sprintf('\u%x\u%x', JSON::PP::_encode_surrogates($_)); + } _unpack_emu($_[0]) + ); +} + + +sub _encode_latin1 { + join('', + map { + $_ <= 255 ? + chr($_) : + $_ <= 65535 ? + sprintf('\u%04x', $_) : sprintf('\u%x\u%x', JSON::PP::_encode_surrogates($_)); + } _unpack_emu($_[0]) + ); +} + + +sub _unpack_emu { # for Perl 5.6 unpack warnings + return !utf8::is_utf8($_[0]) ? unpack('C*', $_[0]) + : _is_valid_utf8($_[0]) ? unpack('U*', $_[0]) + : unpack('C*', $_[0]); +} + + +sub _is_valid_utf8 { + my $str = $_[0]; + my $is_utf8; + + while ($str =~ /(?: + ( + [\x00-\x7F] + |[\xC2-\xDF][\x80-\xBF] + |[\xE0][\xA0-\xBF][\x80-\xBF] + |[\xE1-\xEC][\x80-\xBF][\x80-\xBF] + |[\xED][\x80-\x9F][\x80-\xBF] + |[\xEE-\xEF][\x80-\xBF][\x80-\xBF] + |[\xF0][\x90-\xBF][\x80-\xBF][\x80-\xBF] + |[\xF1-\xF3][\x80-\xBF][\x80-\xBF][\x80-\xBF] + |[\xF4][\x80-\x8F][\x80-\xBF][\x80-\xBF] + ) + | (.) + )/xg) + { + if (defined $1) { + $is_utf8 = 1 if (!defined $is_utf8); + } + else { + $is_utf8 = 0 if (!defined $is_utf8); + if ($is_utf8) { # eventually, not utf8 + return; + } + } + } + + return $is_utf8; +} + + +1; +__END__ + +=pod + +=head1 NAME + +JSON::PP56 - Helper module in using JSON::PP in Perl 5.6 + +=head1 DESCRIPTION + +JSON::PP calls internally. + +=head1 AUTHOR + +Makamaka Hannyaharamitu, Emakamaka[at]cpan.orgE + + +=head1 COPYRIGHT AND LICENSE + +Copyright 2007-2012 by Makamaka Hannyaharamitu + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + +=cut + diff --git a/src/perllib/Web_CAT/Indicators/ProgressTracker.pm b/src/perllib/Web_CAT/Indicators/ProgressTracker.pm index 69cb223..1aafd00 100644 --- a/src/perllib/Web_CAT/Indicators/ProgressTracker.pm +++ b/src/perllib/Web_CAT/Indicators/ProgressTracker.pm @@ -531,7 +531,7 @@ sub collect_indicators $self->set_indicator('ias', $avg); } # itc: increasing test classes - $self->set_indicator('itc', $totals{'test'}->{'classes'}); + $self->set_indicator('isc', $totals{'test'}->{'classes'}); } diff --git a/src/plugin-rulesets/basic.xml b/src/plugin-rulesets/basic.xml index f65c357..cfa6ede 100644 --- a/src/plugin-rulesets/basic.xml +++ b/src/plugin-rulesets/basic.xml @@ -11,12 +11,12 @@ rulesets/java/basic.xml ruleset. - - @@ -24,60 +24,63 @@ learn how to override equals() before they know anything about the hashCode() method. --> - + - - - + + + + + + - - + - + - - - - - + - - + - - + + diff --git a/src/plugin-rulesets/design.xml b/src/plugin-rulesets/design.xml index 4962342..bc19748 100644 --- a/src/plugin-rulesets/design.xml +++ b/src/plugin-rulesets/design.xml @@ -23,15 +23,15 @@ (i.e. return !okay;)."/> --> - - "/> - @@ -60,7 +60,7 @@ - @@ -76,12 +76,12 @@ - - @@ -96,7 +96,7 @@ @@ -126,12 +126,12 @@ - - @@ -150,7 +150,7 @@ - @@ -158,14 +158,14 @@ - - diff --git a/src/plugin-rulesets/empty.xml b/src/plugin-rulesets/empty.xml index 7d8d9da..50dfc7f 100644 --- a/src/plugin-rulesets/empty.xml +++ b/src/plugin-rulesets/empty.xml @@ -11,7 +11,7 @@ rulesets/java/empty.xml ruleset. - - - - - - - - - - - + - - - - - - diff --git a/src/plugin-rulesets/imports.xml b/src/plugin-rulesets/imports.xml index 4eaca77..27c022f 100644 --- a/src/plugin-rulesets/imports.xml +++ b/src/plugin-rulesets/imports.xml @@ -10,24 +10,7 @@ alternate messages from the main PMD rulesets/java/imports.xml ruleset. - - - - - - - + diff --git a/src/plugin-rulesets/junit.xml b/src/plugin-rulesets/junit.xml index 63248a3..f242205 100644 --- a/src/plugin-rulesets/junit.xml +++ b/src/plugin-rulesets/junit.xml @@ -1,45 +1,40 @@ + xmlns="http://pmd.sf.net/ruleset/2.0.0" +> - - These rules deal with different problems that can occur with JUnit - tests. This version of the ruleset includes alternate messages - from the main PMD rulesets/java/design.xml ruleset. - + + These rules deal with different problems that can occur with JUnit + tests. This version of the ruleset includes alternate messages + from the main PMD rulesets/java/design.xml ruleset. + - - + - - - - - - - - - - - - + + + + + diff --git a/src/plugin-rulesets/migrated.xml b/src/plugin-rulesets/migrated.xml new file mode 100644 index 0000000..c7609d2 --- /dev/null +++ b/src/plugin-rulesets/migrated.xml @@ -0,0 +1,409 @@ + + + + + This Ruleset contains rules that were previously + handled by CheckStyle, but have since been migrated to PMD. + + + + + + Prevent unnecessarily long lines in source code. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Prevent long literals that end with a lowercase 'l', which can be easily confused with the digit '1'. + + + + + + + + + + Enforces required Javadocs on package-private-or-more-visible types, + methods, constructors, and non-private fields, and validates required + Javadoc tags. + + 3 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enforces consistent indentation using spaces. Tab characters are not + allowed in indentation, and the number of leading spaces on each line must be a multiple of the indent size. + + 3 + + + + + + + + + + + Enforces consistent whitespace around operators, keywords, braces, + delimiters, generic type angle brackets, method/constructor parentheses, + prefix/postfix unary operators, and dot access. + + 3 + + + + + Enforces that a right curly brace is alone on its physical line + and that each physical line contains at most one statement. + + 3 + + + + + + + + + > + + + + + + + + + Prevent "Write a description here" + + + + + + + + + + + + + + + Prevent "Replace this comment with your own" + + + + + + + + + + + + + + + Prevent "@author Partner's name" + + + + + + + + + + + + + + + Prevent "@author your username" + + + + + + + + + + + + + + + + Prevent "@version place the date here" + + + + + + + + + + + + + + + + + Enforce Java-style array declarations (e.g. int[] x; instead of int x[];). + + + + + + + + + + /> + + + + + + + + + + + Prevent method parameters and local variables from having the same name as a field in the same class. + + + + + + + + + + + + + + + + + Enforce that fields have appropriate visibility modifiers. + + + + + + + + + + + + + + Enforce that fields have appropriate visibility modifiers. + + + + + + + + diff --git a/src/plugin-rulesets/naming.xml b/src/plugin-rulesets/naming.xml index 1720ddc..3042e6f 100644 --- a/src/plugin-rulesets/naming.xml +++ b/src/plugin-rulesets/naming.xml @@ -36,13 +36,13 @@ - - diff --git a/src/plugin-rulesets/strictexception.xml b/src/plugin-rulesets/strictexception.xml index 6d7b4f5..a6b8dbc 100644 --- a/src/plugin-rulesets/strictexception.xml +++ b/src/plugin-rulesets/strictexception.xml @@ -22,26 +22,26 @@ - - - diff --git a/src/plugin-rulesets/strings.xml b/src/plugin-rulesets/strings.xml index aa9299d..b455e96 100644 --- a/src/plugin-rulesets/strings.xml +++ b/src/plugin-rulesets/strings.xml @@ -13,7 +13,7 @@ - - - + - - - - - + @@ -57,5 +55,6 @@ rules. + diff --git a/src/pmd/README.md b/src/pmd/README.md index acaee73..459e926 100644 --- a/src/pmd/README.md +++ b/src/pmd/README.md @@ -3,6 +3,6 @@ Jars in this folder are used to provide the current version of PMD used by the plugin. -The current version used is: 6.26.0 +The current version used is: 7.21.0 -https://github.com/pmd/pmd/releases/download/pmd_releases%2F6.26.0/pmd-bin-6.26.0.zip \ No newline at end of file +https://github.com/pmd/pmd/releases/download/pmd_releases/7.21.0/pmd-dist-7.21.0-bin.zip diff --git a/src/pmd/pmd-apex-jorje-6.26.0.pom b/src/pmd/pmd-apex-jorje-6.26.0.pom deleted file mode 100644 index 7d4bba1..0000000 --- a/src/pmd/pmd-apex-jorje-6.26.0.pom +++ /dev/null @@ -1,139 +0,0 @@ - - - 4.0.0 - pmd-apex-jorje - PMD Apex Jorje Parser Library - pom - - - net.sourceforge.pmd - pmd - 6.26.0 - ../ - - - - 8 - 2020-06-04-ba31c0 - - - - - - org.codehaus.mojo - build-helper-maven-plugin - 3.0.0 - - - attach-apex-jorje - package - - attach-artifact - - - - - ${basedir}/repo/apex/apex-jorje-lsp-minimized/${apex.jorje.version}/apex-jorje-lsp-minimized-${apex.jorje.version}.jar - jar - lib - - - - - - - - - - - - cglib - cglib - 3.2.0 - - - ch.qos.logback - logback-classic - 1.2.3 - - - ch.qos.logback - logback-core - 1.2.3 - - - com.google.code.findbugs - jsr305 - 3.0.2 - - - com.google.code.gson - gson - 2.7 - - - com.google.errorprone - error_prone_annotations - 2.1.3 - - - com.google.guava - guava - - - com.google.j2objc - j2objc-annotations - 1.1 - - - org.antlr - antlr-runtime - - - org.antlr - stringtemplate - 3.2.1 - - - org.apache.commons - commons-lang3 - 3.0 - - - org.codehaus.mojo - animal-sniffer-annotations - 1.14 - - - org.openjdk.jol - jol-core - 0.4 - - - org.slf4j - slf4j-api - 1.7.20 - - - org.yaml - snakeyaml - 1.26 - - - aopalliance - aopalliance - 1.0 - - - javax.inject - javax.inject - 1 - - - org.ow2.asm - asm - 5.0.3 - runtime - - -