From fa1f420b62dc3143c749f2777f6f0cd343101b85 Mon Sep 17 00:00:00 2001 From: hut Date: Tue, 11 Oct 2011 20:15:01 +0200 Subject: defaults/apps: added documentation --- ranger/defaults/apps.py | 100 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 83 insertions(+), 17 deletions(-) diff --git a/ranger/defaults/apps.py b/ranger/defaults/apps.py index 90e54bbe..3ec6bff2 100644 --- a/ranger/defaults/apps.py +++ b/ranger/defaults/apps.py @@ -1,22 +1,86 @@ +# -*- coding: utf-8 -*- # Copyright (C) 2009, 2010, 2011 Roman Zimbelmann +# This configuration file is licensed under the same terms as ranger. +# =================================================================== +# This is the configuration file for file type detection and application +# handling. It's all in python; lines beginning with # are comments. # -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. +# You can customize this in the file ~/.config/ranger/apps.py. +# It has the same syntax as this file. In fact, you can just copy this +# file there with `ranger --copy-config=apps' and make your modifications. +# But make sure you update your configs when you update ranger. # -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. +# In order to add application definitions "on top of" the default ones +# in your ~/.config/ranger/apps.py, you should subclass the class defined +# here like this: # -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -""" -This is the default ranger configuration file for filetype detection -and application handling. -""" +# from ranger.defaults.apps import CustomApplications as DefaultApps +# class CustomApplications(DeafultApps): +# +# +# =================================================================== +# This system is based on things called MODES and FLAGS. You can read +# in the man page about them. To remind you, here's a list of all flags. +# An uppercase flag inverts previous flags of the same name. +# s Silent mode. Output will be discarded. +# d Detach the process. (Run in background) +# p Redirect output to the pager +# w Wait for an Enter-press when the process is done +# c Run the current file only, instead of the selection +# +# To implement flags in this file, you could do this: +# context.flags += "d" +# Another example: +# context.flags += "Dw" +# +# To implement modes in this file, you can do something like: +# if context.mode == 1: +# +# elif context.mode == 2: +# +# +# =================================================================== +# The methods are called with a "context" object which provides some +# attributes that transfer information. Relevant attributes are: +# +# mode -- a number, mainly used in determining the action in app_xyz() +# flags -- a string with flags which change the way programs are run +# files -- a list containing files, mainly used in app_xyz +# filepaths -- a list of the paths of each file +# file -- an arbitrary file from that list (or None) +# fm -- the filemanager instance +# popen_kws -- keyword arguments which are directly passed to Popen +# +# =================================================================== +# The return value of the functions should be either: +# 1. A reference to another app, like: +# return self.app_editor(context) +# +# 2. A call to the "either" method, which uses the first program that +# is installed on your system. If none are installed, None is returned. +# return self.either(context, "libreoffice", "soffice", "ooffice") +# +# 3. A tuple of arguments that should be run. +# return "mplayer", "-fs", context.file.path +# If you use lists instead of strings, they will be flattened: +# args = ["-fs", "-shuf"] +# return "mplayer", args, context.filepaths +# "context.filepaths" can, and will often be abbreviated with just "context": +# return "mplayer", context +# +# 4. "None" to indicate that no action was found. +# return None +# +# =================================================================== +# When using the "either" method, ranger determines which program to +# pick by looking at its dependencies. You can set dependencies by +# adding the decorator "depends_on": +# @depends_on("vim") +# def app_vim(self, context): +# .... +# There is a special keyword which you can use as a dependence: "X" +# This ensures that the program will only run when X is running. +# =================================================================== import ranger from ranger.api.apps import * @@ -210,8 +274,10 @@ class CustomApplications(Applications): # return "vim", context # # But this is redundant and ranger does this automatically. However, sometimes -# you want to change some properties like flags or dependencies. Add programs -# that should only run in X this way here: +# you want to change some properties like flags or dependencies. +# The method "generic" defines a generic method for the given programs which +# looks like the one above, but you can add dependencies and flags here. +# Add programs (that are not defined yet) here if they should only run in X: CustomApplications.generic('fceux', 'wine', 'zsnes', deps=['X']) # Add those which should only run in X AND should be detached/forked here: -- cgit 1.4.1-2-gfad0