usr_share_grml/zsh/functions/Lookup/Backends/LOOKUP_be_leo

   1 ### vim:ft=zsh:foldmethod=marker
   2 ## dict.leo.org search backend for lookup
   3 ## Copyright: 2009, Frank Terbeck <ft@bewatermyfriend.org>
   4 ##
   5 ## This was the first non-trivial backend for lookup. Therefore,
   6 ## it contains some guidelines on how to write backends and what they
   7 ## are expected to do.
   8 ##
   9 ## For consistency in usage among different backends, please try
  10 ## to follow the general style of this one.
  11 ##
  12
  13 # This should be the first thing a backend does.
  14 # It makes sure a backend function is not run directly by a user, but
  15 # only via lookup(), lu() or _lookup().
  16 LOOKUP_guard || return 1
  17
  18 # This check is required and it should be the second thing the backend does.
  19 # If $lookup_describe is not empty, only print a short description
  20 # of what the backend does. Without a newline at the end!
  21 [[ -n ${lookup_describe} ]] &&
  22     printf '%s' 'translations via dict.leo.org' &&
  23     return 0
  24
  25 # declare variables. Assume warncreateglobal is enabled.
  26 local lang lookup_context
  27 local -a comp_args
  28 local -A opts supported_langs interface_lang
  29
  30 # For the actual query string, always use QUERY and make it 'local -x'!
  31 # Parts of the lookup system depend on $QUERY to be declared like this!
  32 local -x QUERY
  33
  34 supported_langs=(
  35     ende    'english german'
  36     frde    'french german'
  37     esde    'spanish german'
  38     itde    'italian german'
  39     chde    'chinese german'
  40 )
  41
  42 # To find out the current context string you can use the LOOKUP_context()
  43 # function like this. Please don't use $context or $curcontext to store
  44 # the result (that may clash with compsys). If you use lookup_context
  45 # you cannot go wrong. For modifying the local-part of the context, see
  46 # the comment in the LOOKUP_context file.
  47 lookup_context="$(LOOKUP_context)"
  48
  49 # Lookup backends should be self-documenting.
  50 # You need to provide a function that prints a useful message that helps
  51 # the user use the backend.
  52 # DO NOT hardcode the name of the function. Always use LOOKUP_help_${backend}
  53 # and guard its definition by 'LOOKUP_guard -fd LOOKUP_help_${backend}' just
  54 # like it is done here.
  55 LOOKUP_guard -fd LOOKUP_help_${backend} ||
  56 function LOOKUP_help_${backend}() {
  57     LOOKUP_guard || return 1
  58            #-80characters-----------------------------------------------------------------#
  59     printf 'usage: %s [-l lang] <query>\n' ${backend}
  60     printf '  -l <lang>     specify a language definition string\n'
  61     printf '\nAvailable language definition strings:\n'
  62     for lang in ${(k)supported_langs} ; do
  63         printf '%6s   - %s\n' ${lang} ${supported_langs[$lang]}
  64     done
  65     printf '\n Makes dictionary lookups via dict.leo.org.\n\n'
  66     printf ' Default language code: ende (german <-> english).\n'
  67     printf ' The interface language used by the website defaults to: en\n'
  68     printf '\n These can be modified via the '\''default-lang'\'' and '\''interface-lang'\''\n'
  69     printf ' styles in this context: %s\n\n' ${lookup_context}
  70     printf 'Examples:\n'
  71     printf ' %% zstyle '\'':lookup:*:%s:*'\'' default-lang   frde\n' ${backend}
  72     printf ' %% zstyle '\'':lookup:*:%s:*'\'' interface-lang de\n\n' ${backend}
  73     printf ' %% lookup %s sugar\n' ${backend}
  74     printf ' %% lookup %s -l frde Zucker\n\n' ${backend}
  75 }
  76
  77 # This call must be here, too. Just after you defined the help function.
  78 # It handles the global -h option of lookup correctly.
  79 LOOKUP_help && return 0
  80
  81 # This test is needed, too.
  82 # Backends are supposed to bring there own completion.
  83 if [[ -n ${lookup_complete} ]] ; then
  84     # During development, you can just put a
  85     #return 0
  86     # here. That will disable completion for the backend and
  87     # prevent breakage for other backends.
  88
  89     # completion sub-functions should be called:
  90     # __lookup_${backend}_<completion_feature>()
  91     # Again, DO NOT hardcode the name. Use ${backend}!
  92     # guard their definition by checking the $functions[] entry
  93     # that belongs to your sub-function.
  94     LOOKUP_guard -fd __lookup_${backend}_supported_langs ||
  95     function __lookup_${backend}_supported_langs() {
  96         local l
  97         local -a ls
  98
  99         ls=()
 100         for l in ${(k)supported_langs}; do
 101             ls+=("$l:${supported_langs[$l]}")
 102         done
 103         _describe -t leo_langs 'supported languages' ls
 104     }
 105
 106     comp_args=(
 107         '-l[set languages]:supported languages:__lookup_'${backend}'_supported_langs'
 108         '*:dict.leo.org query:true'
 109     )
 110
 111     _arguments -s -w -A '-*' ${comp_args} && return 0
 112     _message 'dict.leo.org query'
 113
 114     return 0
 115     # end of completion code #
 116 fi
 117
 118 # parse possible options of the backend.
 119 # 'LOOKUP_parseopts' is the recommended way of doing that.
 120 # See the top of that function's file for an explained example.
 121 # Since LOOKUP_parseopts() returns its findings via $opt[] and $args[], you
 122 # should *never* use variables of those names in your backends.
 123 lu_parseopts_args=( l string )
 124 LOOKUP_parseopts "$@" || return 1
 125 lang=${opts[-l]}
 126
 127 # all configuration should be done via zstyle. The context should always be
 128 # the result of what LOOKUP_context() tells us (see the $lookup_context comment
 129 # earlier, too). Also set reasonable defaults.
 130 if [[ -z ${lang} ]] ; then
 131     zstyle -s "${lookup_context}" default-lang lang || lang='ende'
 132 fi
 133
 134 zstyle -s "${lookup_context}" interface-lang interface_lang || interface_lang='en'
 135
 136 # If applicable, use the remaining arguments as QUERY.
 137 # If the backend used LOOKUP_parseopts() before, the remaining arguments
 138 # are in $args[]. If not, they can be assigned like this:
 139 #   QUERY="$*"
 140 #
 141 # Since we do use LOOKUP_parseopts(), we'll do it like this:
 142 QUERY="${args[*]}"
 143
 144 # Call LOOKUP_query_handler() to support the -Q and -q options of lookup.
 145 # This should also be called like this in every case, as this supports
 146 # a return value from handler functions that indicates unrecoverable errors.
 147 # If you want to support return values from handlers, use the
 148 # $lookup_communicate[] hash, which is meant to be used for that. It can
 149 # also be used to get additional information into the handler.
 150 # See LOOKUP_be_letssingit for an example.
 151 LOOKUP_query_handler || return 1
 152
 153 # Do appropriate error checking and give usage information
 154 # if the query is empty.
 155 if [[ -z ${(Mk)supported_langs:#$lang} ]] ; then
 156     printf 'Unknown language definition: '\''%s'\''.\n\n' ${lang}
 157     # Clear out $QUERY, so we get the usage message below.
 158     QUERY=''
 159 fi
 160 if [[ -z ${QUERY} ]] ; then
 161     # -f means, "display the help text, no matter what."
 162     LOOKUP_help -f
 163     return 1
 164 fi
 165
 166 # You may also put in hooks into your backend. You don't need to though. :)
 167 # To do so, use the LOOKUP_hook function. The first argument should be a name
 168 # for the hook. That will adjust the local-part of the context to that name.
 169 # If you don't want that, use -- as the first argument. Then the context
 170 # remains unchanged.
 171 # The rest of the arguments are handed over to the hook function unchanged.
 172 # There is no convention as to what arguments should be provided or whether
 173 # $lookup_communicate[] should be used. Everything is possible; just make
 174 # sure you document your hooks properly in the help function earlier.
 175 #
 176 # A sample hook call may look like this:
 177 #LOOKUP_hook "pre-encode" $QUERY $lang $interface_lang
 178
 179 # Use LOOKUP_encode() for proper url encoding of the QUERY.
 180 # Since, QUERY is the most common use case of LOOKUP_encode, it has
 181 # a special option to handle that variable.
 182 # For other variables you want to encode, do:
 183 #   foo="$(LOOKUP_encode ${foo})"
 184 LOOKUP_encode -q
 185
 186 # Use our browser wrapper to open the URI, it'll handle everything just right.
 187 LOOKUP_browser "http://dict.leo.org?lang=${interface_lang}&lp=${lang}&search=${QUERY}"
 188
 189 # Explicitly return $?.
 190 return $?