Giddy::Collection - A Giddy collection.
version 0.013_001
my $coll = $db->get_collection('articles');
This class represents Giddy collections, which are directories holding documents in the database. Collections are hierarchical in Giddy (see Giddy::Manual for more information).
You will find most of your interaction with the Giddy database are performed on this class' objects. The class provides methods for finding documents, creating documents, updating documents, removing documents, iterating over query results, etc.
Giddy::Role::DocumentLoader
Giddy::Role::DocumentMatcher
Giddy::Role::DocumentStorer
Giddy::Role::DocumentUpdater
The relative path of the collection. Defaults to the empty string (''), which is the root directory of the database. Never has a starting slash.
The Giddy::Database object the collection belongs to. Required.
Holds a boolean value indicating whether the collection exists in the database index (i.e. has already been staged and commited), or isn't (i.e. a new one). Automatically calculated.
An integer representing the current location of the iterator in the results array. Not to be used externally.
Searches the collection for documents that match the provided query. If no query is given, every document in the collection will be matched. See "FINDING DOCUMENTS" in Giddy::Manual for more information on queries.
Searches the collection for documents (more correctly "a document") whos name equals $name. This is a shortcut for find({ _name => $name }, $options).
$name
find({ _name => $name }, $options)
Searches the collection for documents whose name matches the regular expression provided. This is a shortcut for find({ _name => qr/some_regex/ }, $options.
find({ _name => qr/some_regex/ }, $options
All version of the method return a Giddy::Collection::InMemory object, which inherits from this class.
Searching just by name (either for equality or with a regex) is much faster than searching by other attributes, as Giddy isn't forced to load and deserialize every document.
In any of the above versions of the method, if you don't provide a query, or provide an empty string or empty hash-ref, every document in the collection will be matched.
You can also pass a hash-ref of options. Currently, only the 'skip_binary' option is available. If provided with a true value, binary attributes of documents will be ignored. See "BINARY ATTRIBUTES" in Giddy::Manual for info on binary attributes.
Same as calling find($query, $options)->first().
find($query, $options)->first()
Finds documents whose file contents (including attribute names and database YAML structure) match all (or any, depending on \%options) of the provided strings. This is much faster than using find() as it simply uses the git grep command, but is obviously less useful.
\%options
find()
git grep
The only option supported is 'or'. If passed with a true value, documents that have at least one of the provided strings will be matched. Otherwise only documents that have all strings are matched.
If the strings array is empty, all documents in the collection will match.
Finds documents whose file contents (including attribute names and database YAML structure) match the provided string. If string is empty, all documents in the collection will match.
Both methods return a Giddy::Collection::InMemory object.
Same as calling grep( $string(s), $options)->first.
grep( $string(s), $options)->first
Creates a new document in the collection. You must provide a name for the document (keep in mind that the name will be the document's file/directory's name, so try not to use fancy characters), and a hash-ref of the document's attributes. This hash-ref doesn't have to be flat, attributes can be nestable (i.e. they can have array and hash references themselves).
If $attributes has the '_body' key, the document created will be a document file. Otherwise a document directory will be created. See "CREATING DOCUMENTS" in Giddy::Manual for more information on documents.
$attributes
Returns the path of the document created relative to the database root directory (including a starting slash). Croaks if a document or a sub-collection named $name already exists in the collection.
Inserts a series of documents one after another. Returns a list with the names of all documents created. If even one document cannot be created (mostly since a similarly named document/collection already exists), none will be created.
Performs a query on the collection, and updates the first document found according to the update object (\%object above). You must provide a query, but this can be an empty string or hash-ref, in which case all documents in the collection will be matched. An options hash-ref can be provided, with any of the following options:
\%object
skip_binary - See "BINARY ATTRIBUTES" for info.
multiple - Update all documents you find, not just the first one.
upsert - If you don't find any document that matches the query, create one
Returns a hash-ref with two keys: 'n' - with the number of documents updated (0 if none) and 'docs' - an array-ref with the names of all documents updated (empty if none).
See "UPDATING DOCUMENTS" in Giddy::Manual for more information on updating.
Performs a query on the collection, and removes every document matched. If a query is not provided (or if empty string or hash-ref), every document in the collection is removed. If you pass an options hash-ref with the 'just_one' key holding a true value, only one document will be removed (the first matched, if any).
Returns the number of documents in the collection.
Sorts the collection's documents. If $order isn't provided, documents will be sorted alphabetically by name (documents are already sorted by name by default, so this is only useful for re-sorting).
$order
$order can be any of the following:
An ordered Tie::IxHash object.
An even-numbered array-ref (such as [ 'attr1' => 1, 'attr2' => -1 ]).
[ 'attr1' => 1, 'attr2' => -1 ]
Of course we are sorting by attributes, so you can still use the '_name' attribute in $order. When you give an attribute a positive true value, it will be sorted ascendingly. When you give a negative value, it will be sorted descendingly. So, for example:
$coll->sort([ 'birth_date' => -1, '_name' => 1 ])
Will sort the documents in the collection descendingly by the 'birth_date' attribute, and then ascendingly by the document's name.
Documents that miss any attributes from the $order object always lean towards the end. If, for example, $order is [ date => 1 ], then the documents will be sorted ascendingly by the 'date' attribute, and all documents that don't have the 'date' attribute will propagate to the end.
[ date => 1 ]
Returns an array of all the documents in the collection (after loading).
Returns a true value if the iterator hasn't reached the last of the documents (and thus next() can be called).
next()
Returns the document currently pointed to by the iterator, and increases the iterator to point to the next document.
Resets to iterator to point to the first document.
Returns the first document in the collection (or undef if none exist), regardless of the iterator's current position (which will not change).
undef
Returns the last document in the collection (or undef if none exist), regardless of the iterator's current position (which will not change).
Returns a Giddy::Collection object tied to the parent collection of the collection. If this method is called on the root collection, undef will be returned.
Returns a Giddy::Collection object tied to a child-collection named $name. If the collection does not exist, it will be created. If $name exists in the collection, but isn't a child collection, this method will croak. $name must not start with a slash.
Returns a list of all the static-file directories in the collection (if any).
Returns a Giddy::StaticDirectory object for a directory of static files named $name, residing in the collection's directory. If the directory does not exist, it will be created and marked as a static directory with an empty '.static' file. If the directory exists but is not a static directory (or a file named $name exists), this method will croak.
Removes the collection from the database. Will not work (and croak) on the root collection. Every document and sub-collection in the collection will be removed. This method is not available on Giddy::Collection::InMemory objects.
The following methods are only to be used internally.
Returns a sorted Tie::IxHash object of all documents in the collection.
Returns an internal path created by joining the collection's path and everything in @names with '/' as a separator. If the collection is the root collection (and thus has the empty path) than this method will behave correctly and not return a string that starts with a slash.
@names
Ido Perlmuter, <ido at ido50.net>
<ido at ido50.net>
Please report any bugs or feature requests to bug-giddy at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Giddy. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-giddy at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Giddy::Collection
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Giddy
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Giddy
CPAN Ratings
http://cpanratings.perl.org/d/Giddy
Search CPAN
http://search.cpan.org/dist/Giddy/
Copyright 2011 Ido Perlmuter.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
To install Giddy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Giddy
CPAN shell
perl -MCPAN -e shell install Giddy
For more information on module installation, please visit the detailed CPAN module installation guide.