[KSS-checkins] r49278 - kukit/kss.base/trunk/kss/base

[reebalazs at codespeak.net]

Author: reebalazs
Date: Sun Dec  2 15:42:34 2007
New Revision: 49278

Modified:
   kukit/kss.base/trunk/kss/base/plugin.txt
   kukit/kss.base/trunk/kss/base/selectors.py
   kukit/kss.base/trunk/kss/base/selectors.txt
Log:
Make selectors have a type on class

Modified: kukit/kss.base/trunk/kss/base/plugin.txt
==============================================================================
--- kukit/kss.base/trunk/kss/base/plugin.txt	(original)
+++ kukit/kss.base/trunk/kss/base/plugin.txt	Sun Dec  2 15:42:34 2007
@@ -29,8 +29,9 @@
   >>> from kss.base.selectors import Selector
 
   >>> class silly(Selector):
-  ...         def __init__(self, value):
-  ...             super(silly, self).__init__('example-silly', value)
+  ...     type = 'example-silly'
+  ...     def __init__(self, value):
+  ...         self.value = value
 
 
   >>> class ExamplePlugin(Plugin):

Modified: kukit/kss.base/trunk/kss/base/selectors.py
==============================================================================
--- kukit/kss.base/trunk/kss/base/selectors.py	(original)
+++ kukit/kss.base/trunk/kss/base/selectors.py	Sun Dec  2 15:42:34 2007
@@ -1,28 +1,37 @@
 from kss.base.registry import Registry
 
 class Selector(object):
-    def __init__(self, type, value):
-        self.type = type
-        self.value = value
+    """A base for selectors. Plugins that implement this, need
+    to implement __init__ themselves, and set type as a string.
 
+    Currently only the 'type' and 'value' attribute gets marshalled,
+    but this may change in later implementations.
+    """
+    type = None
+    value = ''
+    def __init__(self):
+        raise Exception, 'Unimplemented'
     def __str__(self):
         return "%s('%s')" % (self.type, self.value)
 
 class css(Selector):
+    type = 'css'
     def __init__(self, value):
-        super(css, self).__init__('css', value)
+        self.value = value
 
 class htmlid(Selector):
+    type = 'htmlid'
     def __init__(self, value):
-        super(htmlid, self).__init__('htmlid', value)
+        self.value = value
 
 class samenode(Selector):
+    type = 'samenode'
     def __init__(self):
-        super(samenode, self).__init__('samenode', '')
+        pass
 
 class parentnode(Selector):
+    type = 'parentnode'
     def __init__(self, value):
-        super(parentnode, self).__init__('parentnode', value)
-
+        self.value = value
 
 selectors = Registry()

Modified: kukit/kss.base/trunk/kss/base/selectors.txt
==============================================================================
--- kukit/kss.base/trunk/kss/base/selectors.txt	(original)
+++ kukit/kss.base/trunk/kss/base/selectors.txt	Sun Dec  2 15:42:34 2007
@@ -2,21 +2,27 @@
 =========
 
 The selector is responsible for finding the nodes on which to operate.
-Selectors are executed on the client. They need a name and an optional
-parameter.
+Selectors are executed on the client. Most of them has a single parameter.
 
 A base class is provided for all selectors.
 
   >>> from kss.base.selectors import Selector
-  >>> selector = Selector('type', 'value')
 
-The selector now has a type and value property.
-
-  >>> selector.type
-  'type'
-
-  >>> selector.value
-  'value'
+The base class cannot be instantiated in itself. We will show later,
+how a plugin can subclass it to create a new selector type and 
+register it.
+
+  >>> Selector()
+  Traceback (most recent call last):
+  ...
+  Exception: Unimplemented
+
+XXX Jeroen, I removed the possibility for use an unregistered selector for
+two reasons:
+1. we need the type present on the class already.
+2. There is no code that possibly could use it anyway, so nothing
+   could break for now.
+XXX Please delete this part to acknowledge...
 
 Standard selectors
 ------------------
@@ -26,6 +32,13 @@
 
   >>> from kss.base.selectors import css, htmlid
 
+The selector classes have a type parameter defined on the class.
+
+  >>> css.type
+  'css'
+  >>> htmlid.type
+  'htmlid'
+
 They both need a value to operate on.
 
   >>> selector = css('div.main a')
@@ -45,6 +58,8 @@
 action. Also note that it does not accept any arguments.
 
   >>> from kss.base.selectors import samenode
+  >>> samenode.type
+  'samenode'
   >>> selector = samenode()
   >>> selector.type
   'samenode'
@@ -56,12 +71,55 @@
 grandparents).
 
   >>> from kss.base.selectors import parentnode
+  >>> parentnode.type
+  'parentnode'
   >>> selector = parentnode('a')
   >>> selector.type
   'parentnode'
   >>> selector.value
   'a'
 
+Selectors registered by plugins
+-------------------------------
+
+Suppose a plugin registers a new selector. It must overwrite
+type, and __init__ (if it needs to have a value parameter).
+The type of the selector should always be in namespace-name
+notation. Only the core selectors stand without a namespace.
+
+  >>> from kss.base.selectors import Selector
+  >>> class MyFunkySelector(Selector):
+  ...     type = 'mynamespace-funky'
+  ...     def __init__(self, value):
+  ...         self.value = value
+
+We will use this class to create selector instances. In real
+life, the plugin would register this class now with the plugin
+registry, and the commandset code would look up the class from
+the registry. However, we test the registration somewhere
+else, and just use the class as it is for now:
+
+  >>> selector_class = MyFunkySelector
+
+Noe let's instantiate the selector:
+
+  >>> selector = selector_class('Selector value')
+
+The selector now has a type and value property.
+
+  >>> selector.type
+  'mynamespace-funky'
+
+  >>> selector.value
+  'Selector value'
+
+XXX Implementation remark:
+
+  Currently only the "value" property will be considered to
+  be marshalled to the client. So, selectors must have their
+  parameter stored as "value" for now.
+
+
 String representation
 ---------------------
 
@@ -69,8 +127,8 @@
 
 !TODO: Fix lower casing of string representation
 
-  >>> print Selector('type', 'value')
-  type('value')
+  >>> print MyFunkySelector('value')
+  mynamespace-funky('value')
 
   >>> print css('div.content')
   css('div.content')