Documenting iteration protocol. Rearranging parse.py methods. Some typographic changes.

git-svn-id: http://css-py.googlecode.com/svn/trunk@7 255e942d-184c-0410-a885-59fc1719c42d

Author: ijoshua

css/__init__.py

@@ -1,5 +1,22 @@
 # -*- coding: utf-8 -*-
-# CSS package
-# Author: Joshua E Cook <jcook at particleweb dot com>
+'''
+CSS package
+Author: Joshua E Cook <jcook at particleweb dot com>
+
+Examples:
+
+from css.parse import parse
+
+data = """p { color: red; font-size: 12pt }
+p:first-letter { color: green; font-size: 200% }
+p:first-line { color: blue }"""
+
+for rule in parse(data):
+    print rule
+    # or do something with each rule
+
+'''
+
+__all__ = ('csslex', 'cssyacc', 'css', 'serialize', 'parse')
+
 
-__all__ = ('csslex', 'cssyacc','css', 'serialize')

css/css.py

@@ -12,6 +12,9 @@
            'Media', 'Import', 'Stylesheet')
 
 class SyntaxObject(object):
+    '''
+    An abstract type of syntactic construct.
+    '''
     def __str__(self):
         return self.datum(str)
 
@@ -145,6 +148,9 @@ def datum(self, serializer):
 class Ruleset(SyntaxObject):
     '''
     A list of declarations for a given list of selectors.
+
+    When iterating, yields each of its declarations in order of
+    their appearance.
     '''
     def __init__(self, selectors, declarations=None):
         self.selectors = selectors
@@ -188,6 +194,9 @@ class Page(SyntaxObject):
     A @page rule statement containing a list of declarations.
     
     The rule may have a pseudo-page specifer like :left or :right.
+
+    When iterating, yields each of its declarations in order of
+    their appearance.
     '''
     def __init__(self, declarations=None, pseudo_page=None):
         self.declarations = declarations or list()
@@ -216,6 +225,9 @@ def datum(self, serializer):
 class Media(SyntaxObject):
     '''
     An @media rule statement containing a list of rulesets.
+
+    When iterating, yields each of its rulesets in order of
+    their appearance.
     '''
     def __init__(self, media_types, rulesets=None):
         self.media_types = media_types
@@ -268,6 +280,9 @@ class Stylesheet(SyntaxObject):
     
     May have an optional list of import rules and an optional 
     character set specification.
+
+    When iterating, yields each of its rules, including @import 
+    and @charset rules, in order of their appearance.
     '''
     def __init__(self, statements, imports=None, charset=None):
         self.statements = statements

css/parse.py

@@ -4,7 +4,6 @@
 from urllib2 import urlopen
 from codecs import EncodedFile
 import css, csslex, cssyacc
-from serialize import serialize
 from uri import uri
 
 __all__ = ('parse','export')
@@ -14,26 +13,26 @@ def parse(data):
     parser.lexer = csslex.lex()
     return parser.parse(data, debug=True)
 
-def export(stylesheet):
-    if stylesheet.charset:
-        print serialize(stylesheet.charset, unicode)
-
-    for i in stylesheet.imports:
-        url = i.source
+def export(base, stylesheet, recursive=False):
+    def recur(rule):
+        url = rule.source
         if isinstance(url, css.Uri):
             url = url.url
-            importuri = uri.resolve(fileuri, url)
-            importfile = urlopen(importuri)
-            export(parse(importfile.read()))
+        url = uri.resolve(base, url)
+        export(base, parse(urlopen(url).read()))
+
+    for rule in stylesheet:
+        if recursive and isinstance(rule, css.Import):
+            recur(rule)
+        else:
+            print rule.datum(unicode)
 
-    for s in stylesheet.statements:
-        print serialize(s, unicode)
 
 def main(fileuri, options):
     inputfile = urlopen(fileuri)
 
     stylesheet = parse(inputfile.read())
-    export(stylesheet)
+    export(fileuri, stylesheet)
 
 
 if '__main__' == __name__:

css/serialize.py

@@ -15,108 +15,112 @@
 # serialize(), and possibly a new serialize_<type>()
 # method.  (The data types of CSS are finite and the number
 # relatively small, so this should be a rare occassion.)
+# 
+# Each serializer method takes a `printer` argument,
+# which should be a function that returns a serialized
+# value for objects of builtin types.
 
-def serialize(obj, serializer):
+def serialize(obj, printer=str):
     if isinstance(obj, css.Hexcolor):
-        return serialize_Hexcolor(obj, serializer)
+        return serialize_Hexcolor(obj, printer)
     elif isinstance(obj, css.Function):
-        return serialize_Function(obj, serializer)
+        return serialize_Function(obj, printer)
     elif isinstance(obj, css.Uri):
-        return serialize_Uri(obj, serializer)
+        return serialize_Uri(obj, printer)
     elif isinstance(obj, css.String):
-        return serialize_String(obj, serializer)
+        return serialize_String(obj, printer)
     elif isinstance(obj, css.Ident):
-        return serialize_Ident(obj, serializer)
+        return serialize_Ident(obj, printer)
     elif isinstance(obj, css.Term):
-        return serialize_Term(obj, serializer)
+        return serialize_Term(obj, printer)
     elif isinstance(obj, css.Declaration):
-        return serialize_Declaration(obj, serializer)
+        return serialize_Declaration(obj, printer)
     elif isinstance(obj, css.Ruleset):
-        return serialize_Ruleset(obj, serializer)
+        return serialize_Ruleset(obj, printer)
     elif isinstance(obj, css.Charset):
-        return serialize_Charset(obj, serializer)
+        return serialize_Charset(obj, printer)
     elif isinstance(obj, css.Page):
-        return serialize_Page(obj, serializer)
+        return serialize_Page(obj, printer)
     elif isinstance(obj, css.Media):
-        return serialize_Media(obj, serializer)
+        return serialize_Media(obj, printer)
     elif isinstance(obj, css.Import):
-        return serialize_Import(obj, serializer)
+        return serialize_Import(obj, printer)
     elif isinstance(obj, css.Stylesheet):
-        return serialize_Stylesheet(obj, serializer)
+        return serialize_Stylesheet(obj, printer)
     else:
-        return serializer(obj)
+        return printer(obj)
 
-def serialize_Hexcolor(obj, serializer):
-    return serializer('#') + serializer(obj.value)
+def serialize_Hexcolor(obj, printer):
+    return printer('#') + printer(obj.value)
 
-def serialize_Function(obj, serializer):
-    return serializer(obj.name) + serializer('(') + serializer(obj.parameters) + serializer(')')
+def serialize_Function(obj, printer):
+    return printer(obj.name) + printer('(') + printer(obj.parameters) + printer(')')
 
-def serialize_Uri(obj, serializer):
-    return serializer('url(') + serializer(obj.url) + serializer(')')
+def serialize_Uri(obj, printer):
+    return printer('url(') + printer(obj.url) + printer(')')
 
-def serialize_String(obj, serializer):
-    s = serializer(obj.value.replace(u'"', u'\\"'))
-    return serializer('"') + s + serializer('"')
+def serialize_String(obj, printer):
+    s = printer(obj.value.replace(u'"', u'\\"'))
+    return printer('"') + s + printer('"')
 
-def serialize_Ident(obj, serializer):
-    return serializer(obj.name)
+def serialize_Ident(obj, printer):
+    return printer(obj.name)
 
-def serialize_Term(obj, serializer):
-    s = serializer(obj.value)
+def serialize_Term(obj, printer):
+    s = printer(obj.value)
     if obj.unary_operator:
-        s = serializer(obj.unary_operator) + s
+        s = printer(obj.unary_operator) + s
     return s
 
-def serialize_Declaration(obj, serializer):
-    s = serialize_Ident(obj.property, serializer) 
-    s += serializer(':') + serializer(obj.value)
+def serialize_Declaration(obj, printer):
+    s = serialize_Ident(obj.property, printer) 
+    s += printer(':') + printer(obj.value)
     if obj.important:
-        s += serializer(' !important')
+        s += printer(' !important')
     return s
 
-def serialize_Ruleset(obj, serializer):
-    s = serialize_Selector_group(obj.selectors, serializer)
-    s += serialize_Declaration_block(obj.declarations, serializer)
+def serialize_Ruleset(obj, printer):
+    s = serialize_Selector_group(obj.selectors, printer)
+    s += serialize_Declaration_block(obj.declarations, printer)
     return s
 
-def serialize_Charset(obj, serializer):
-    return serializer('@charset ') + serializer(obj.encoding) + serializer(';')
+def serialize_Charset(obj, printer):
+    return printer('@charset ') + printer(obj.encoding) + printer(';')
 
-def serialize_Page(obj, serializer):
-    s = serializer('@page')
+def serialize_Page(obj, printer):
+    s = printer('@page')
     if obj.pseudo_page:
-        s += serialize_Pseudo(obj.pseudo_page, serializer)
-    s += serialize_Declaration_block(obj.declarations, serializer)
+        s += serialize_Pseudo(obj.pseudo_page, printer)
+    s += serialize_Declaration_block(obj.declarations, printer)
     return s
 
-def serialize_Media(obj, serializer):
-    s = serializer('@media ')
-    s += serializer(',').join((serializer(x) for x in obj.media_types))
-    s += serializer('{') + serializer('\n').join([serialize_Ruleset(x, serializer) for x in obj.rulesets]) + serializer('}')
+def serialize_Media(obj, printer):
+    s = printer('@media ')
+    s += printer(',').join((printer(x) for x in obj.media_types))
+    s += printer('{') + printer('\n').join([serialize_Ruleset(x, printer) for x in obj.rulesets]) + printer('}')
     return s
 
-def serialize_Import(obj, serializer):
-    s = serializer('@import ') + serialize(obj.source, serializer)
+def serialize_Import(obj, printer):
+    s = printer('@import ') + serialize(obj.source, printer)
     if obj.media_types:
-        s += serializer(' ') + serializer(',').join((serializer(x) for x in obj.media_types))
-    s += serializer(';')
+        s += printer(' ') + printer(',').join((printer(x) for x in obj.media_types))
+    s += printer(';')
     return s
 
-def serialize_Stylesheet(obj, serializer):
-    s = serializer('')
+def serialize_Stylesheet(obj, printer):
+    s = printer('')
     if obj.charset:
-        s += serialize_Charset(obj.charset, serializer) + serializer('\n')
+        s += serialize_Charset(obj.charset, printer) + printer('\n')
     if obj.imports:
-        s += serializer('\n').join((serialize_Import(x, serializer) for x in obj.imports)) + serializer('\n')
-    s += serializer('\n').join((serialize(x, serializer) for x in obj.statements))
+        s += printer('\n').join((serialize_Import(x, printer) for x in obj.imports)) + printer('\n')
+    s += printer('\n').join((serialize(x, printer) for x in obj.statements))
     return s
 
-def serialize_Pseudo(obj, serializer):
-    return serializer(':') + serialize_Ident(obj, serializer)
+def serialize_Pseudo(obj, printer):
+    return printer(':') + serialize_Ident(obj, printer)
 
-def serialize_Selector_group(selectors, serializer):
-    return serializer(',').join((serializer(x) for x in selectors))
+def serialize_Selector_group(selectors, printer):
+    return printer(',').join((printer(x) for x in selectors))
 
-def serialize_Declaration_block(declarations, serializer):
-    return serializer('{') + serializer(';').join((serialize_Declaration(x, serializer) for x in declarations)) + serializer('}')
+def serialize_Declaration_block(declarations, printer):
+    return printer('{') + printer(';').join((serialize_Declaration(x, printer) for x in declarations)) + printer('}')