hgbook
changeset 461:67d34d8b6ba0
translated up to the "writing an in-process hook" section
author | Javier Rojas <jerojasro@devnull.li> |
---|---|
date | Tue Dec 23 12:57:21 2008 -0500 (2008-12-23) |
parents | 622faa5f5bb8 |
children | 5389bef3a95b |
files | es/hook.tex |
line diff
1.1 --- a/es/hook.tex Sun Dec 21 23:07:13 2008 -0500 1.2 +++ b/es/hook.tex Tue Dec 23 12:57:21 2008 -0500 1.3 @@ -383,79 +383,89 @@ 1.4 no le importa el desempeño (el caso de la mayoría de los ganchos), es 1.5 perfectamente admisible un guión de línea de comandos. 1.6 1.7 -\subsection{Hook parameters} 1.8 +\subsection{Parámetros para ganchos} 1.9 \label{sec:hook:param} 1.10 1.11 -Mercurial calls each hook with a set of well-defined parameters. In 1.12 -Python, a parameter is passed as a keyword argument to your hook 1.13 -function. For an external program, a parameter is passed as an 1.14 -environment variable. 1.15 - 1.16 -Whether your hook is written in Python or as a shell script, the 1.17 -hook-specific parameter names and values will be the same. A boolean 1.18 -parameter will be represented as a boolean value in Python, but as the 1.19 -number 1 (for ``true'') or 0 (for ``false'') as an environment 1.20 -variable for an external hook. If a hook parameter is named 1.21 -\texttt{foo}, the keyword argument for a Python hook will also be 1.22 -named \texttt{foo}, while the environment variable for an external 1.23 -hook will be named \texttt{HG\_FOO}. 1.24 - 1.25 -\subsection{Hook return values and activity control} 1.26 - 1.27 -A hook that executes successfully must exit with a status of zero if 1.28 -external, or return boolean ``false'' if in-process. Failure is 1.29 -indicated with a non-zero exit status from an external hook, or an 1.30 -in-process hook returning boolean ``true''. If an in-process hook 1.31 -raises an exception, the hook is considered to have failed. 1.32 - 1.33 -For a hook that controls whether an activity can proceed, zero/false 1.34 -means ``allow'', while non-zero/true/exception means ``deny''. 1.35 - 1.36 -\subsection{Writing an external hook} 1.37 - 1.38 -When you define an external hook in your \hgrc\ and the hook is run, 1.39 -its value is passed to your shell, which interprets it. This means 1.40 -that you can use normal shell constructs in the body of the hook. 1.41 - 1.42 -An executable hook is always run with its current directory set to a 1.43 -repository's root directory. 1.44 - 1.45 -Each hook parameter is passed in as an environment variable; the name 1.46 -is upper-cased, and prefixed with the string ``\texttt{HG\_}''. 1.47 - 1.48 -With the exception of hook parameters, Mercurial does not set or 1.49 -modify any environment variables when running a hook. This is useful 1.50 -to remember if you are writing a site-wide hook that may be run by a 1.51 -number of different users with differing environment variables set. 1.52 -In multi-user situations, you should not rely on environment variables 1.53 -being set to the values you have in your environment when testing the 1.54 -hook. 1.55 - 1.56 -\subsection{Telling Mercurial to use an in-process hook} 1.57 - 1.58 -The \hgrc\ syntax for defining an in-process hook is slightly 1.59 -different than for an executable hook. The value of the hook must 1.60 -start with the text ``\texttt{python:}'', and continue with the 1.61 -fully-qualified name of a callable object to use as the hook's value. 1.62 - 1.63 -The module in which a hook lives is automatically imported when a hook 1.64 -is run. So long as you have the module name and \envar{PYTHONPATH} 1.65 -right, it should ``just work''. 1.66 - 1.67 -The following \hgrc\ example snippet illustrates the syntax and 1.68 -meaning of the notions we just described. 1.69 +Mercurial llama cada gancho con un conjunto de paŕametros bien 1.70 +definidos. En Python, un parámetro se pasa como argumento de palabra 1.71 +clave a su función de gancho. Para un programa externo, los parámetros 1.72 +son pasados como variables de entornos. 1.73 + 1.74 +Sin importar si su gancho está escrito en Python o como guión de línea 1.75 +de comandos, los nombres y valores de los parámetros específicos de 1.76 +los ganchos serán los mismos. Un parámetro booleano será representado 1.77 +como un valor booleano en Python, pero como el número 1 (para 1.78 +``verdadero'') o 0 (para falso) en una variable de entorno para un 1.79 +gancho externo. Si un parámetro se llama \texttt{foo}, el argumento de 1.80 +palabra clave para un gancho en Python también se llamará 1.81 +\texttt{foo}, mientras que la variable de entorno para un gancho 1.82 +externo se llamará \texttt{HG\_FOO}. 1.83 + 1.84 +\subsection{Valores de retorno de ganchos y control de actividades} 1.85 + 1.86 +Un gancho que se ejecuta exitosamente debe terminar con un código de 1.87 +salida de cero, si es externo, o retornar el valor booleano 1.88 +``falso'', si es interno. Un fallo se indica con un código de salida 1.89 +diferente de cero desde un gancho externo, o un valor de retorno 1.90 +booleano ``verdadero''. Si un gancho interno genera una excepción, se 1.91 +considera que el gancho ha fallado. 1.92 + 1.93 +Para los ganchos que controlan si una actividad puede continuar o no, 1.94 +cero/falso quiere decir ``permitir'', mientras que 1.95 +% TODO me suena mejor "no permitir" que "denegar" 1.96 +no-cero/verdadero/excepción quiere decir ``no permitir''. 1.97 + 1.98 +\subsection{Escribir un gancho externo} 1.99 + 1.100 +Cuando usted define un gancho externo en su fichero \hgrc\ y el mismo 1.101 +es ejecutado, dicha definición pasa a su intérprete de comandos, que 1.102 +hace la interpretación correspondiente. Esto significa que usted puede 1.103 +usar elementos normales del intérprete en el cuerpo del gancho. 1.104 + 1.105 +Un gancho ejecutable siempre es ejecutado con su directorio actual 1.106 +fijado al directorio raíz del repositorio. 1.107 + 1.108 +Cada parámetro para el gancho es pasado como una variable de entorno; 1.109 +el nombre está en mayúsculas, y tiene como prefijo la cadena 1.110 +``\texttt{HG\_}''. 1.111 + 1.112 +Con la excepción de los parámetros para los ganchos, Mercurial no 1.113 +define o modifica ninguna variable de entorno al ejecutar un gancho. 1.114 +Es útil recordar esto al escribir un gancho global que podría ser 1.115 +ejecutado por varios usuarios con distintas variables de entorno 1.116 +fijadas. En situaciones con múltiples usuarios, usted no debería 1.117 +asumir la existencia de ninguna variable de entorno, ni que sus 1.118 +valores sean los mismos que tenían cuando usted probó el gancho en su 1.119 +ambiente de trabajo. 1.120 + 1.121 +\subsection{Indicar a Mercurial que use un gancho interno} 1.122 + 1.123 +La sintaxis para definir un gancho interno en el fichero \hgrc\ es 1.124 +ligeramente diferente de la usada para un gancho externo. El valor del 1.125 +gancho debe comenzar con el texto ``\texttt{python:}'', y continuar 1.126 +con el nombre completamente cualificado de un objeto invocable que se 1.127 +usará como el valor del gancho. 1.128 + 1.129 +El módulo en que vive un gancho es importado automáticamente cuando se 1.130 +ejecuta un gancho. Siempre que usted tenga el nombre del módulo y la 1.131 +variable de entorno \envar{PYTHONPATH} ajustada adecuadamente, todo 1.132 +debería funcionar sin problemas. 1.133 + 1.134 +El siguiente fragmento de ejemplo de un fichero \hgrc\ ilustra la 1.135 +sintaxis y significado de los conceptos que acabamos de describir. 1.136 \begin{codesample2} 1.137 [hooks] 1.138 commit.example = python:mymodule.submodule.myhook 1.139 \end{codesample2} 1.140 -When Mercurial runs the \texttt{commit.example} hook, it imports 1.141 -\texttt{mymodule.submodule}, looks for the callable object named 1.142 -\texttt{myhook}, and calls it. 1.143 - 1.144 -\subsection{Writing an in-process hook} 1.145 - 1.146 -The simplest in-process hook does nothing, but illustrates the basic 1.147 -shape of the hook API: 1.148 +Cuando Mercurial ejecuta el gancho \texttt{commit.example}, importa 1.149 +\texttt{mymodule.submodule}, busca el objeto invocable llamado 1.150 +\texttt{myhook}, y lo invoca (llama). 1.151 + 1.152 +\subsection{Escribir un gancho interno} 1.153 + 1.154 +El gancho interno más sencillo no hace nada, pero ilustra la 1.155 +estructura básica de la API\footnote{\emph{Application Progamming 1.156 +Interface}, Interfaz para Programación de Aplicaciones} para ganchos: 1.157 \begin{codesample2} 1.158 def myhook(ui, repo, **kwargs): 1.159 pass