Commits

Dmitri Lebedev committed 0104638 Draft

more quick tour

  • Participants
  • Parent commits 71f473b

Comments (0)

Files changed (2)

docs/source/tour.rst

 	from fsquass import Fs
 	Fs('/home .bashrc') - Fs('~/.bashrc')  # similar to jQuery.not()
 
-File sets are iterable and consist of :py:class:`File <fsquass.__init__.File>` or :py:class:`Dir <fsquass.__init__.Dir>` instances:
+File sets are iterable and consist of :py:class:`File <fsquass.__init__.File>` or :py:class:`Dir <fsquass.__init__.Dir>` instances. They also can generate strings:
 
 .. code-block:: python
 
 	for project in Fs('~/projects/*'):
-		print project.path
+		print project
+
+	for path in Fs('~/projects/*'):  # a generator of string paths
+		print path
 
 .. _syntax:
 
 
 	/etc/hosts;~/.my_hosts;~/test.txt
 
+Put a backslash to a colon if it's a part of a name::
+
+	strange\;name1;strange\;name2
+
 .. _shell-patterns:
 
 Shell Patterns
 | ``[!seq]`` | matches any character not in *seq* |
 +------------+------------------------------------+
 
+.. _set-operations:
+
+Set Operations
+--------------
+
+:py:class:`Fs <fsquass.__init__.Fs>` inherits from :py:class:`set` and suspports all the set methods.
+
+.. code-block:: python
+
+	Fs('./*.py') | Fs('./*.pyc')  # union
+	Fs('. {*.rst,*.txt}') - Fs('./build *.txt')  # not
+	Fs('*.py') & Fs('__*__.py')  # intersection
+	Fs('*.py') ^ Fs('__*__.py')  # xor (union not intersection)
+
+:py:func:`filter <fsquass.__init__.Fs.filter>` is just like interection, but is faster since it doesn't search files on disk.
+
+.. code-block:: python
+
+	Fs('*.py').filter('__*__.py')
+
+.. _traversing:
+
+Traversing
+----------
+
+Having one set of files you can generate another set relative of it:
+
+.. code-block:: python
+
+	# find Python scripts and then their parent folders that start with 'django'
+	django_projects = Fs('~/projcets *.py').parents('django*')
+
+	# inside those find __init__.py at top level
+	django_projects.children('__init__.py')
+
+	# or at any depth
+	django_projects.find('. __init__.py')
+
+	# find doc roots inside them, by relative path (no recursive search)
+	django_projects.find('docs/source/index.*')
+
+	django_projects.siblings()
+
+.. _manipulation:
+
+Files Manipulation
+------------------
+
+Currently :py:class:`Fs <fsquass.__init__.Fs>` supports
+
+* :py:func:`linkTo <fsquass.__init__.Fs.linkTo>`
+* :py:func:`symlinkTo <fsquass.__init__.Fs.symlinkTo>`

fsquass/__init__.py

 		"""
 		Matches ``item.basename`` against *subpattern*.
 
-		* ``subpattern`` - string containing text or unix-like masks ``?``, ``*``.
+		* ``subpattern`` - string containing text or unix-like patterns ``?``, ``*``.
 		* ``item`` - a :py:class:`File` instance.
 		"""
 		pseudo_classes = escaped_split(':', subpattern)
 		"""
 		return path.basename(self.path)
 
-	def children(self, mask=None):
+	def children(self, pattern=None):
 		"""
 		Returns an Fs of child nodes. Makes sense in Dir only, but put here for compatibility.
 		"""
 		if not path.isdir(self.path):
 			raise ValueError(_('path %s is not a directory') % self.path)
 
-	def children(self, mask=None):
+	def children(self, pattern=None):
 		try:
 			filenames = os.listdir(self.path)
 		except OSError:
 			return Fs()
 		t = partial(path.join, self.path)
-		return Fs(map(File, map(t, filenames))).filter(mask)
+		return Fs(map(File, map(t, filenames))).filter(pattern)
 
 	def open(self, *args, **kwargs):
 		raise TypeError(_("Directories can't be opened like files"))