beginning the --browse tool

CHANGELOG

@@ -15,7 +15,7 @@ Version 3.0
 
 	-f, +f and -q may be unargumented if that are at the end of the command line.
 
-	ponysay-tool is introduced, it can be used to edit, remove and copy pony meta data.
+	ponysay-tool is introduced, it can be used to edit, remove and copy pony meta data, and more.
 
 	ponysay-tool --kms generates all kmsponies for the current TTY palette.
 

completion/ponysay-tool

@@ -19,4 +19,12 @@
 	
 	(argumented (option --metadata) (complete --metadata) (arg PONYDIR) (files -d *) (desc 'Generate pony metadata collection file for a directory'))
 	
+	(argumented (option -b --browse) (complete --browse) (arg PONYDIR) (files -d *) (desc 'Browse ponies in a directory')
+
+	(argumented (options -r --restrict) (complete --restrict) (arg RESTRICTION) (suggest -r) (files -0) (desc 'Metadata based restriction for --browse'))
+	
+	
+	(suggestion -r (verbatim kind=KIND group=GROUP coat=COAT eye=EYE mane=MANE aura=AURA)
+	)
+	
 )

manuals/ponysay.texinfo

@@ -1137,6 +1137,7 @@ its purpose is to provide tools to ponysay relevant actions that is not printing
 * Editing metadata::        Editing the metadata in a pony file.
 * Metadata collections::    Generate pony metadata collection files.
 * Dimension files::         Generate pony dimension files.
+* Pony browsing::           Browse ponies or find a pony based on metadata.
 @end menu
 
 
@@ -1329,6 +1330,18 @@ the contain optimised information about the widths, heigths and heights with pri
 without the balloon, respectively, for each pony the the directory.
 
 
+@node Pony browsing
+@section Pony browsing
+@cindex pony browsing
+@cindex browse ponies
+@opindex @option{-b}
+@opindex @option{--browse}
+@opindex @option{-r}
+@opindex @option{--restrict}
+
+TODO...
+
+
 
 @node Limitations
 @chapter Limitations
@@ -2805,7 +2818,7 @@ and @file{~/.config/ponysay/ponysayrc} as well as the global fallback @file{/etc
 @item
 @option{-f}, @option{+f} and @option{-q} may be unargumented if that are at the end of the command line.
 @item
-@command{ponysay-tool} is introduced, it can be used to edit, remove and copy pony meta data.
+@command{ponysay-tool} is introduced, it can be used to edit, remove and copy pony meta data, and more.
 @item
 @command{ponysay-tool --kms} generates all kmsponies for the current TTY palette.
 @item

ponysay-tool.py

@@ -901,6 +901,7 @@ if __name__ == '__main__':
                        '%s %s' % (usage_program, '--edit-stash \033[33mPONY-FILE\033[39m > \033[33mSTASH-FILE\033[39m'),
                        '%s %s' % (usage_program, '--edit-apply \033[33mPONY-FILE\033[39m < \033[33mSTASH-FILE\033[39m'),
                        '%s %s' % (usage_program, '(--dimensions | --metadata) \033[33mPONY-DIR\033[39m'),
+                       '%s %s' % (usage_program, '--browse \033[33mPONY-DIR\033[39m [-r \033[33mRESTRICTION\033[39m]*'),
                       ])
     
     usage = usage.replace('\033[', '\0')
@@ -916,15 +917,17 @@ if __name__ == '__main__':
                      usage       = usage,
                      longdescription = None)
     
-    opts.add_argumentless(['-h', '--help'],                         help = 'Print this help message.')
+    opts.add_argumentless(['-h', '--help'],                          help = 'Print this help message.')
-    opts.add_argumentless(['-v', '--version'],                      help = 'Print the version of the program.')
+    opts.add_argumentless(['-v', '--version'],                       help = 'Print the version of the program.')
-    opts.add_argumentless(['--kms'],                                help = 'Generate all kmsponies for the current TTY palette')
+    opts.add_argumentless(['--kms'],                                 help = 'Generate all kmsponies for the current TTY palette')
-    opts.add_argumented(  ['--dimensions'],     arg = 'PONY-DIR',   help = 'Generate pony dimension file for a directory')
+    opts.add_argumented(  ['--dimensions'],     arg = 'PONY-DIR',    help = 'Generate pony dimension file for a directory')
-    opts.add_argumented(  ['--metadata'],       arg = 'PONY-DIR',   help = 'Generate pony metadata collection file for a directory')
+    opts.add_argumented(  ['--metadata'],       arg = 'PONY-DIR',    help = 'Generate pony metadata collection file for a directory')
-    opts.add_argumented(  ['--edit'],           arg = 'PONY-FILE',  help = 'Edit a pony file\'s metadata')
+    opts.add_argumented(  ['-b', '--browse'],   arg = 'PONY-DIR',    help = 'Browse ponies in a directory')
-    opts.add_argumented(  ['--edit-rm'],        arg = 'PONY-FILE',  help = 'Remove metadata from a pony file')
+    opts.add_argumented(  ['-r', '--restrict'], arg = 'RESTRICTION', help = 'Metadata based restriction for --browse')
-    opts.add_argumented(  ['--edit-apply'],     arg = 'PONY-FILE',  help = 'Apply metadata from stdin to a pony file')
+    opts.add_argumented(  ['--edit'],           arg = 'PONY-FILE',   help = 'Edit a pony file\'s metadata')
-    opts.add_argumented(  ['--edit-stash'],     arg = 'PONY-FILE',  help = 'Print applyable metadata from a pony file')
+    opts.add_argumented(  ['--edit-rm'],        arg = 'PONY-FILE',   help = 'Remove metadata from a pony file')
+    opts.add_argumented(  ['--edit-apply'],     arg = 'PONY-FILE',   help = 'Apply metadata from stdin to a pony file')
+    opts.add_argumented(  ['--edit-stash'],     arg = 'PONY-FILE',   help = 'Print applyable metadata from a pony file')
     
     '''
     Whether at least one unrecognised option was used