upd readme and add basic filtering

Author: jacook

README.md

@@ -2,4 +2,71 @@
 
 A module for easily creating and modifying nginx serverblock configurations in Python (including comments!).
 
-Work in progress.
+### Examples
+
+Create an nginx serverblock and save it to file:
+
+    >>> import nginx
+    >>> c = nginx.Conf()
+    >>> u = nginx.Upstream('php',
+    ...     nginx.Key('server', 'unix:/tmp/php-fcgi.socket')
+    ...	)
+    >>> c.add(u)
+    >>> s = nginx.Server()
+    >>> s.add(
+    ...     nginx.Key('listen', '80'),
+    ...     nginx.Comment('Yes, python-nginx can read/write comments!'),
+    ...     nginx.Key('server_name', 'localhost 127.0.0.1'),
+    ...     nginx.Key('root', '/srv/http'),
+    ...     nginx.Key('index', 'index.php'),
+    ...     nginx.Location('= /robots.txt',
+    ...          nginx.Key('allow', 'all'),
+    ...          nginx.Key('log_not_found', 'off'),
+    ...          nginx.Key('access_log', 'off')
+    ...     )
+    ...     nginx.Location('~ \.php$',
+    ...          nginx.Key('include', 'fastcgi.conf'),
+    ...          nginx.Key('fastcgi_intercept_errors', 'on'),
+    ...          nginx.Key('fastcgi_pass', 'php')
+    ...     )
+    ... )
+    >>> c.add(s)
+    >>> nginx.dumpf(c, '/etc/nginx/sites-available/mysite')
+
+Load an nginx serverblock from a file:
+
+    >>> import nginx
+    >>> c = nginx.loadf('/etc/nginx/sites-available/testsite')
+    >>> c.all()
+    [<main.Server object at 0x7f1ed4573890>]
+    >>> c.servers[0].all()
+    [<main.Comment object at 0x7f1ed45736d0>, <main.Key object at 0x7f1ed4573750>, <main.Key object at 0x7f1ed4573790>, <main.Location object at 0x7f1ed4573850>]
+    >>> c.as_dict()
+    {'conf': [{'server': [{'#': 'This is a test comment'}, {'server_name': 'localhost'}, {'root': '/srv/http'}, {'location /': [{'allow': 'all'}]}]}]}
+
+Format an nginx serverblock into a string (change the amount of spaces (or tabs) for each indentation level by modifying `nginx.INDENT` first):
+
+    >>> c.all()
+    [<main.Server object at 0x7f1ed4573890>]
+    >>> c.as_block()
+    ['server {\n', '    # This is a test comment\n', '    server_name localhost;\n', '    root /srv/http;\n', '\n    location / {\n', '        allow all;\n', '    }\n\n', '}\n']
+
+Find where you put your keys:
+
+    >>> import nginx
+    >>> c = nginx.loadf('/etc/nginx/sites-available/testsite')
+    >>> c.filter('Server')
+    [<main.Server object at 0x7f1ed4573890>]
+    >>> c.filter('Server')[0].filter('Key', 'root')
+    [<main.Key object at 0x7f1ed4573790>]
+    >>> c.filter('Server')[0].filter('Location')
+    [<main.Location object at 0x7f1ed4573850>]
+
+Or just get everything by its type:
+
+    >>> import nginx
+    >>> c = nginx.loadf('/etc/nginx/sites-available/testsite')
+    >>> c.servers
+    [<main.Server object at 0x7f1ed4573890>]
+    >>> c.servers[0].keys
+    [<main.Key object at 0x7f1ed4573750>, <main.Key object at 0x7f1ed4573790>]

main.py

@@ -18,6 +18,15 @@ def remove(self, *args):
 		self.upd()
 		return self.blocks
 
+	def filter(self, btype='', name=''):
+		flist = []
+		for x in self.blocks:
+			if name and isinstance(x, Key) and x.name == name:
+				flist.append(x)
+			elif not name and btype and x.__class__.__name__ == btype:
+				flist.append(x)
+		return flist
+
 	def upd(self):
 		svr = []
 		for x in self.blocks:
@@ -34,6 +43,9 @@ def as_list(self):
 			ret.append(x.as_list())
 		return ret
 
+	def as_dict(self):
+		return {'conf': [x.as_dict() for x in self.blocks]}
+
 	def as_block(self):
 		ret = []
 		for x in self.blocks:
@@ -63,6 +75,15 @@ def remove(self, *args):
 		self.upd()
 		return self.blocks
 
+	def filter(self, btype='', name=''):
+		flist = []
+		for x in self.blocks:
+			if name and isinstance(x, Key) and x.name == name:
+				flist.append(x)
+			elif not name and btype and x.__class__.__name__ == btype:
+				flist.append(x)
+		return flist
+
 	def upd(self):
 		l, c, k = [], [], []
 		for x in self.blocks:
@@ -83,6 +104,9 @@ def as_list(self):
 			ret.append(x.as_list())
 		return ['server', '', ret]
 
+	def as_dict(self):
+		return {'server': [x.as_dict() for x in self.blocks]}
+
 	def as_block(self):
 		ret = []
 		ret.append('server {\n')
@@ -135,6 +159,9 @@ def as_list(self):
 			ret.append(x.as_list())
 		return [self.name, self.value, ret]
 
+	def as_dict(self):
+		return {self.name+' '+self.value: [x.as_dict() for x in self.blocks]}
+
 	def as_block(self):
 		ret = []
 		ret.append(self.name + ' ' + self.value + ' {\n')
@@ -155,6 +182,9 @@ def __init__(self, comment):
 	def as_list(self):
 		return [self.comment]
 
+	def as_dict(self):
+		return {'#': self.comment}
+
 	def as_block(self):
 		return '# ' + self.comment + '\n'
 
@@ -197,6 +227,9 @@ def __init__(self, name, value):
 	def as_list(self):
 		return [self.name, self.value]
 
+	def as_dict(self):
+		return {self.name: self.value}
+
 	def as_block(self):
 		return self.name + ' ' + self.value + ';\n'