Add 'snippet' class as a part of the 2.1 spec

Add 'spdx_id', 'name', 'comment', 'copyright', and
'license_comment' to the 'snippet' class.

Signed-off-by: Yash Nisar <[email protected]>

Author: yash-nisar

data/SPDXRdfExample.rdf

@@ -3,6 +3,12 @@
     xmlns:j.0="http://usefulinc.com/ns/doap#"
     xmlns="http://spdx.org/rdf/terms#"
     xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#">
+  <Snippet rdf:about="http://spdx.org/spdxdocs/spdx-example-444504E0-4F89-41D3-9A0C-0305E82C3301#SPDXRef-Snippet">
+    <name>from linux kernel</name>
+    <copyrightText>Copyright 2008-2010 John Smith</copyrightText>
+    <licenseComments>The concluded license was taken from package xyz, from which the snippet was copied into the current file. The concluded license information was found in the COPYING.txt file in package xyz.</licenseComments>
+    <rdfs:comment>This snippet was identified as significant and highlighted in this Apache-2.0 file, when a commercial scanner identified it as being derived from file foo.c in package xyz which is licensed under GPL-2.0-or-later.</rdfs:comment>
+  </Snippet>
   <SpdxDocument rdf:about="http://www.spdx.org/tools#SPDXANALYSIS">
     <creationInfo>
       <CreationInfo>

data/SPDXTagExample.tag

@@ -65,6 +65,12 @@ ArtifactOfProjectHomePage: http://www.openjena.org/
 ArtifactOfProjectURI: UNKNOWN
 FileComment: <text>This file belongs to Jena</text>
 
+## Snippet Information
+SnippetSPDXID: SPDXRef-Snippet
+SnippetLicenseComments: <text>The concluded license was taken from package xyz, from which the snippet was copied into the current file. The concluded license information was found in the COPYING.txt file in package xyz.</text>
+SnippetCopyrightText: <text> Copyright 2008-2010 John Smith </text>
+SnippetComment: <text>This snippet was identified as significant and highlighted in this Apache-2.0 file, when a commercial scanner identified it as being derived from file foo.c in package xyz which is licensed under GPL-2.0-or-later.</text>
+SnippetName: from linux kernel
 
 ## License Information
 LicenseID: LicenseRef-3

spdx/document.py

@@ -196,9 +196,11 @@ class Document(object):
       SPDX license list. Optional, many. Type: ExtractedLicense.
     - reviews: SPDX document review information, Optional zero or more.
       Type: Review.
+    - snippet: Snippet information. Optional zero or more. Type: Snippet.
     """
 
-    def __init__(self, version=None, data_license=None, comment=None, package=None):
+    def __init__(self, version=None, data_license=None, comment=None,
+                 package=None, snippet=None):
         # avoid recursive impor
         from spdx.creationinfo import CreationInfo
         self.version = version
@@ -208,13 +210,17 @@ def __init__(self, version=None, data_license=None, comment=None, package=None):
         self.package = package
         self.extracted_licenses = []
         self.reviews = []
+        self.snippet = []
 
     def add_review(self, review):
         self.reviews.append(review)
 
     def add_extr_lic(self, lic):
         self.extracted_licenses.append(lic)
 
+    def add_snippet(self, snip):
+        self.snippet.append(snip)
+
     @property
     def files(self):
         return self.package.files
@@ -241,6 +247,7 @@ def validate(self, messages=None):
             and self.validate_package(messages)
             and self.validate_extracted_licenses(messages)
             and self.validate_reviews(messages)
+            and self.validate_snippet(messages)
         )
 
     def validate_version(self, messages=None):
@@ -277,6 +284,15 @@ def validate_reviews(self, messages=None):
             valid = review.validate(messages) and valid
         return valid
 
+    def validate_snippet(self, messages=None):
+        # FIXME: messages should be returned
+        messages = messages if messages is not None else []
+
+        valid = True
+        for snippet in self.snippet:
+            valid = snippet.validate(messages) and valid
+        return valid
+
     def validate_creation_info(self, messages=None):
         # FIXME: messages should be returned
         messages = messages if messages is not None else []

spdx/parsers/lexers/tagvalue.py

@@ -70,6 +70,12 @@ class Lexer(object):
         'LicenseName': 'LICS_NAME',
         'LicenseCrossReference': 'LICS_CRS_REF',
         'LicenseComment': 'LICS_COMMENT',
+        # Snippet
+        'SnippetSPDXID': 'SNIPPET_SPDX_ID',
+        'SnippetName': 'SNIPPET_NAME',
+        'SnippetComment': 'SNIPPET_COMMENT',
+        'SnippetCopyrightText': 'SNIPPET_CR_TEXT',
+        'SnippetLicenseComments': 'SNIPPET_LICS_COMMENT',
         # Common
         'NOASSERTION': 'NO_ASSERT',
         'UNKNOWN': 'UN_KNOWN',
@@ -94,8 +100,9 @@ def t_text_end(self, t):
         r'</text>\s*'
         t.type = 'TEXT'
         t.value = t.lexer.lexdata[
-            t.lexer.text_start:t.lexer.lexpos].strip()
+                  t.lexer.text_start:t.lexer.lexpos]
         t.lexer.lineno += t.value.count('\n')
+        t.value = t.value.strip()
         t.lexer.begin('INITIAL')
         return t
 

spdx/parsers/rdf.py

@@ -47,6 +47,8 @@
     'FILE_SINGLE_LICS': 'File concluded license must be a license url or spdx:noassertion or spdx:none.',
     'REVIEWER_VALUE' : 'Invalid reviewer value \'{0}\' must be Organization, Tool or Person.',
     'REVIEW_DATE' : 'Invalid review date value \'{0}\' must be date in ISO 8601 format.',
+    'SNIPPET_SPDX_ID_VALUE' : 'SPDXID must be "SPDXRef-[idstring]" where [idstring] is a unique string '
+                              'containing letters, numbers, ".", "-".',
 }
 
 
@@ -658,6 +660,49 @@ def p_file_lic_conc(self, f_term, predicate):
             self.more_than_one_error('file {0}'.format(predicate))
 
 
+class SnippetParser(LicenseParser):
+    """
+    Helper class for parsing snippet information.
+    """
+
+    def __init__(self, builder, logger):
+        super(SnippetParser, self).__init__(builder, logger)
+
+    def parse_snippet(self, snippet_term):
+        try:
+            self.builder.create_snippet(self.doc, snippet_term)
+        except SPDXValueError:
+            self.value_error('SNIPPET_SPDX_ID_VALUE', snippet_term)
+
+        for _s, _p, o in self.graph.triples((snippet_term, self.spdx_namespace['name'], None)):
+            try:
+                self.builder.set_snippet_name(self.doc, six.text_type(o))
+            except CardinalityError:
+                self.more_than_one_error('snippetName')
+                break
+
+        for _s, _p, o in self.graph.triples((snippet_term, self.spdx_namespace['licenseComments'], None)):
+            try:
+                self.builder.set_snippet_lic_comment(self.doc, six.text_type(o))
+            except CardinalityError:
+                self.more_than_one_error('licenseComments')
+                break
+
+        for _s, _p, o in self.graph.triples((snippet_term, RDFS.comment, None)):
+            try:
+                self.builder.set_snippet_comment(self.doc, six.text_type(o))
+            except CardinalityError:
+                self.more_than_one_error('comment')
+                break
+
+        for _s, _p, o in self.graph.triples((snippet_term, self.spdx_namespace['copyrightText'], None)):
+            try:
+                self.builder.set_snippet_copyright(self.doc, self.to_special_value(six.text_type(o)))
+            except CardinalityError:
+                self.more_than_one_error('copyrightText')
+                break
+
+
 class ReviewParser(BaseParser):
     """
     Helper class for parsing review information.
@@ -722,7 +767,7 @@ def get_reviewer(self, r_term):
             self.value_error('REVIEWER_VALUE', reviewer_list[0][2])
 
 
-class Parser(PackageParser, FileParser, ReviewParser):
+class Parser(PackageParser, FileParser, SnippetParser, ReviewParser):
     """
     RDF/XML file parser.
     """
@@ -751,6 +796,9 @@ def parse(self, fil):
         for s, _p, o in self.graph.triples((None, self.spdx_namespace['referencesFile'], None)):
             self.parse_file(o)
 
+        for s, _p, o in self.graph.triples((None, RDF.type, self.spdx_namespace['Snippet'])):
+            self.parse_snippet(s)
+
         for s, _p, o in self.graph.triples((None, self.spdx_namespace['reviewed'], None)):
             self.parse_review(o)
 

spdx/parsers/rdfbuilders.py

@@ -305,6 +305,50 @@ def set_file_notice(self, doc, text):
             raise OrderError('File::Notice')
 
 
+class SnippetBuilder(tagvaluebuilders.SnippetBuilder):
+
+    def __init__(self):
+        super(SnippetBuilder, self).__init__()
+
+    def set_snippet_lic_comment(self, doc, lic_comment):
+        """Sets the snippet's license comment.
+        Raises OrderError if no snippet previously defined.
+        Raises CardinalityError if already set.
+        """
+        self.assert_snippet_exists()
+        if not self.snippet_lic_comment_set:
+            self.snippet_lic_comment_set = True
+            doc.snippet[-1].license_comment = lic_comment
+        else:
+            CardinalityError('Snippet::licenseComments')
+
+    def set_snippet_comment(self, doc, comment):
+        """
+        Sets general comments about the snippet.
+        Raises OrderError if no snippet previously defined.
+        Raises CardinalityError if comment already set.
+        """
+        self.assert_snippet_exists()
+        if not self.snippet_comment_set:
+            self.snippet_comment_set = True
+            doc.snippet[-1].comment = comment
+            return True
+        else:
+            raise CardinalityError('Snippet::comment')
+
+    def set_snippet_copyright(self, doc, copyright):
+        """Sets the snippet's copyright text.
+        Raises OrderError if no snippet previously defined.
+        Raises CardinalityError if already set.
+        """
+        self.assert_snippet_exists()
+        if not self.snippet_copyright_set:
+            self.snippet_copyright_set = True
+            doc.snippet[-1].copyright = copyright
+        else:
+            raise CardinalityError('Snippet::copyrightText')
+
+
 class ReviewBuilder(tagvaluebuilders.ReviewBuilder):
 
     def __init__(self):
@@ -325,7 +369,8 @@ def add_review_comment(self, doc, comment):
             raise OrderError('ReviewComment')
 
 
-class Builder(DocBuilder, EntityBuilder, CreationInfoBuilder, PackageBuilder, FileBuilder, ReviewBuilder):
+class Builder(DocBuilder, EntityBuilder, CreationInfoBuilder, PackageBuilder, FileBuilder,
+              SnippetBuilder, ReviewBuilder):
 
     def __init__(self):
         super(Builder, self).__init__()

spdx/parsers/tagvalue.py

@@ -82,6 +82,12 @@
     'LICS_COMMENT_VALUE' : 'LicenseComment must be free form text, line: {0}',
     'LICS_CRS_REF_VALUE' : 'LicenseCrossReference must be uri as single line of text, line: {0}',
     'PKG_CPY_TEXT_VALUE' : 'Package copyright text must be free form text, line: {0}',
+    'SNIP_SPDX_ID_VALUE' : 'SPDXID must be "SPDXRef-[idstring]" where [idstring] is a unique string '
+                           'containing letters, numbers, ".", "-".',
+    'SNIPPET_NAME_VALUE' : 'SnippetName must be a single line of text, line: {0}',
+    'SNIP_COMMENT_VALUE' : 'SnippetComment must be free form text, line: {0}',
+    'SNIP_COPYRIGHT_VALUE' : 'SnippetCopyrightText must be one of NOASSERTION, NONE or free form text, line: {0}',
+    'SNIP_LICS_COMMENT_VALUE' : 'SnippetLicenseComments must be free form text, line: {0}',
 }
 
 
@@ -143,6 +149,11 @@ def p_attrib(self, p):
                   | file_contrib
                   | file_dep
                   | file_artifact
+                  | snip_spdx_id
+                  | snip_name
+                  | snip_comment
+                  | snip_cr_text
+                  | snip_lic_comment
                   | extr_lic_id
                   | extr_lic_text
                   | extr_lic_name
@@ -990,6 +1001,124 @@ def p_package_name_1(self, p):
         msg = ERROR_MESSAGES['PACKAGE_NAME_VALUE'].format(p.lineno(1))
         self.logger.log(msg)
 
+    def p_snip_spdx_id(self, p):
+        """snip_spdx_id : SNIPPET_SPDX_ID LINE"""
+        try:
+            if six.PY2:
+                value = p[2].decode(encoding='utf-8')
+            else:
+                value = p[2]
+            self.builder.create_snippet(self.document, value)
+        except SPDXValueError:
+            self.error = True
+            msg = ERROR_MESSAGES['SNIP_SPDX_ID_VALUE'].format(p.lineno(2))
+            self.logger.log(msg)
+
+    def p_snip_spdx_id_1(self, p):
+        """snip_spdx_id : SNIPPET_SPDX_ID error"""
+        self.error = True
+        msg = ERROR_MESSAGES['SNIP_SPDX_ID_VALUE'].format(p.lineno(1))
+        self.logger.log(msg)
+
+    def p_snippet_name(self, p):
+        """snip_name : SNIPPET_NAME LINE"""
+        try:
+            if six.PY2:
+                value = p[2].decode(encoding='utf-8')
+            else:
+                value = p[2]
+            self.builder.set_snippet_name(self.document, value)
+        except OrderError:
+            self.order_error('SnippetName', 'SnippetSPDXID', p.lineno(1))
+        except CardinalityError:
+            self.more_than_one_error('SnippetName', p.lineno(1))
+
+    def p_snippet_name_1(self, p):
+        """snip_name : SNIPPET_NAME error"""
+        self.error = True
+        msg = ERROR_MESSAGES['SNIPPET_NAME_VALUE'].format(p.lineno(1))
+        self.logger.log(msg)
+
+    def p_snippet_comment(self, p):
+        """snip_comment : SNIPPET_COMMENT TEXT"""
+        try:
+            if six.PY2:
+                value = p[2].decode(encoding='utf-8')
+            else:
+                value = p[2]
+            self.builder.set_snippet_comment(self.document, value)
+        except OrderError:
+            self.order_error('SnippetComment', 'SnippetSPDXID', p.lineno(1))
+        except SPDXValueError:
+            self.error = True
+            msg = ERROR_MESSAGES['SNIP_COMMENT_VALUE'].format(p.lineno(2))
+            self.logger.log(msg)
+        except CardinalityError:
+            self.more_than_one_error('SnippetComment', p.lineno(1))
+
+    def p_snippet_comment_1(self, p):
+        """snip_comment : SNIPPET_COMMENT error"""
+        self.error = True
+        msg = ERROR_MESSAGES['SNIP_COMMENT_VALUE'].format(p.lineno(1))
+        self.logger.log(msg)
+
+    def p_snippet_cr_text(self, p):
+        """snip_cr_text : SNIPPET_CR_TEXT snip_cr_value"""
+        try:
+            self.builder.set_snippet_copyright(self.document, p[2])
+        except OrderError:
+            self.order_error('SnippetCopyrightText', 'SnippetSPDXID', p.lineno(1))
+        except SPDXValueError:
+            self.error = True
+            msg = ERROR_MESSAGES['SNIP_COPYRIGHT_VALUE'].format(p.lineno(2))
+            self.logger.log(msg)
+        except CardinalityError:
+            self.more_than_one_error('SnippetCopyrightText', p.lineno(1))
+
+    def p_snippet_cr_text_1(self, p):
+        """snip_cr_text : SNIPPET_CR_TEXT error"""
+        self.error = True
+        msg = ERROR_MESSAGES['SNIP_COPYRIGHT_VALUE'].format(p.lineno(1))
+        self.logger.log(msg)
+
+    def p_snippet_cr_value_1(self, p):
+        """snip_cr_value : TEXT"""
+        if six.PY2:
+            p[0] = p[1].decode(encoding='utf-8')
+        else:
+            p[0] = p[1]
+
+    def p_snippet_cr_value_2(self, p):
+        """snip_cr_value : NONE"""
+        p[0] = utils.SPDXNone()
+
+    def p_snippet_cr_value_3(self, p):
+        """snip_cr_value : NO_ASSERT"""
+        p[0] = utils.NoAssert()
+
+    def p_snippet_lic_comment(self, p):
+        """snip_lic_comment : SNIPPET_LICS_COMMENT TEXT"""
+        try:
+            if six.PY2:
+                value = p[2].decode(encoding='utf-8')
+            else:
+                value = p[2]
+            self.builder.set_snippet_lic_comment(self.document, value)
+        except OrderError:
+            self.order_error('SnippetLicenseComments', 'SnippetSPDXID', p.lineno(1))
+        except SPDXValueError:
+            self.error = True
+            msg = ERROR_MESSAGES['SNIP_LICS_COMMENT_VALUE'].format(p.lineno(2))
+            self.logger.log(msg)
+        except CardinalityError:
+            self.more_than_one_error('SnippetLicenseComments', p.lineno(1))
+
+    def p_snippet_lic_comment_1(self, p):
+        """snip_lic_comment : SNIPPET_LICS_COMMENT error"""
+        self.error = True
+        msg = ERROR_MESSAGES['SNIP_LICS_COMMENT_VALUE'].format(p.lineno(1))
+        self.logger.log(msg)
+
     def p_reviewer_1(self, p):
         """reviewer : REVIEWER entity"""
         self.builder.add_reviewer(self.document, p[2])