diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/XmlConfiguration.pdf | bin | 134992 -> 152157 bytes | |||
-rw-r--r-- | docs/XmlConfiguration.tex | 124 | ||||
-rw-r--r-- | docs/gettingStarted.pdf | bin | 96917 -> 95402 bytes | |||
-rw-r--r-- | docs/gettingStarted.tex | 22 |
4 files changed, 134 insertions, 12 deletions
diff --git a/docs/XmlConfiguration.pdf b/docs/XmlConfiguration.pdf Binary files differindex 343347a..9136232 100644 --- a/docs/XmlConfiguration.pdf +++ b/docs/XmlConfiguration.pdf diff --git a/docs/XmlConfiguration.tex b/docs/XmlConfiguration.tex index 0ccd08d..6f45de2 100644 --- a/docs/XmlConfiguration.tex +++ b/docs/XmlConfiguration.tex @@ -19,7 +19,7 @@ same way you might write a webpage in HTML. We will refer to the XML system here-on-in as `SmootConf'. \textbf{The fastest way to get familiar with SmootConf is simply to look at the XML files in the configuration file. However, if you want a more structured approach to - its feature and sublties this document should do the job.} Without any further ado, lets start looking at + its feature and subtleties this document should do the job.} Without any further ado, lets start looking at how this all works. \section{Declaring a class in SmootConf} The most common thing done is SmootConf is declaring a class -- Class declaration code will @@ -98,4 +98,126 @@ </InputElement> </InputConfiguration> \end{verbatim} + \texttt{InputElement}s live under the broader \texttt{InputConfiguration} tag. Thats all in + terms of basic configuration -- all other features are going to be specific to the + particular class you are declaring (and the class should specify those). However, the + system also offers a lot of features to give you more power and flexibility, as well as + minimizing repeated XML. + \section{XML Inheritance} + SmootConf allows you have XML objects inherit from this other. Think of this as an + X:Include crossed with OO style inheritance, if those are familiar concepts. The most basic + tag of inheritance in SmootConf is the \texttt{InheritsFrom} tag. Here is a quick example + of it in action: + \begin{verbatim} + <Renderer Scale="4"> + <InheritsFrom>renderers/Pygame.xml</InheritsFrom> + </Renderer> + \end{verbatim} + + And the contents of \texttt{renderers/Pygame.xml}: + \begin{verbatim} + <Renderer> + <Class>renderers.PygameRenderer</Class> + <Args> + <Id>pygamerender</Id> + <displaySize>(1300,50)</displaySize> + </Args> + </Renderer> + \end{verbatim} + + The \texttt{InheritsFrom} tag indicates to look in the XML File indicated, parse it, and + recursively merge its tags with the siblings of the \texttt{InheritsFrom} tag. From a high + level, the algorithm works as follows: + + \begin{itemize} + \item For every tag: + \item If the tag is in the inheriter, use that. Otherwise, use the inherited tag. + \item Recurse to children. + \end{itemize} + + SmootConf adds a bit of syntactic sugar that allows you override args in the args dict when + doing inheritance by simply specifying them as attributes of the parent. The example below + comes from a pixel layout config: + \begin{verbatim} + <PixelConfiguration> + <PixelStrip Id="strip1.1" originLocation="(0,0)" Reverse="True"> + <InheritsFrom>layouts/50PixelStrip.xml</InheritsFrom> + </PixelStrip> + <PixelStrip Id="strip1.2" originLocation="(200,0)"> + <InheritsFrom>layouts/50PixelStrip.xml</InheritsFrom> + </PixelStrip> + \end{verbatim} + + The contents of \texttt{layouts/50PixelStrip.xml} are: + \begin{verbatim} + <PixelStrip> + <Class>layouts.LineLayout</Class> + <Args> + <pixelToPixelSpacing>4</pixelToPixelSpacing> + <spacing>4</spacing> + <numPixels>50</numPixels> + </Args> + </PixelStrip> + \end{verbatim} + + A careful reading of the algorithm will reveal some behaviors which are not specified. What if there are + multiple instances of identical sibling tags? The answer is that this is not currently + supported. It may be supported in the future. + + If you want your tags to be added to an inherited config without trying to merge, put them + in an \texttt{APPEND} tag like so: + + \begin{verbatim} + <Behaviors> + <InheritsFrom>behaviors/StockBehaviors.xml</InheritsFrom> + <APPEND> + <Beavhior> + <InheritsFrom>behaviors/SomethingElse.xml</InerhitsFrom> + </Behavior> + <Behavior> + <Class>blah.blah</Class> + <Args> + </Args> + </Behavior> + </APPEND> + </Behaviors> + \end{verbatim} + \section{Variable Bindings} + SmootConf allows developers to reference other variables within the \texttt{<Args>} tag. These + references are dynamic, and are bound for the lifetime of the object and will updated as + their bound values update. Here is an example: + \begin{verbatim} + <Behavior> + <Class>behaviors.SomeClass</Class> + <Args> + <Id>dimming</Id> + <DecayCoefficient>${DecayTime}$*5</DecayCoefficient> + <DecayTime>10</DecayTime> + </Args> + </Behavior> + \end{verbatim} + In this (fake) example, we bind the DecayCoefficient to the value of DecayTime, which allows us to + set decay in a reasonable unit, decoupled from the coefficient required by the behavior + itself. + + Under the hood, this feature is done with lambda functions. When you query arguments on the + object, the lambda gets resolved (look at \texttt{operationscore/SmootCoreObject.py} for the + implementation of this). Because of this, we also have to ability to go 1 layer deeper. + + Let's say you wanted to operate on another dictionary -- say, the current behavior packet or + and args of another behavior. By surrounding your variable in quotes, querying its value + with product a lambda function, which, when given another dictionary, will resolve the + value. + \begin{verbatim} + <Behavior> + <Class>behaviors.SomeClass</Class> + <Args> + <Id>stayinbounds</Id> + <MaxX>100</MaxX> + <OutOfBounds>'${x}$' < ${MaxX}$</OutOfBounds> + </Args> + </Behavior> + \end{verbatim} + If you call \texttt{self['OutOfBounds']}, and pass it a dictionary with a value at key + \texttt{x}, it will return a boolean stating whether or not \texttt{x > MaxX}. \end{document} diff --git a/docs/gettingStarted.pdf b/docs/gettingStarted.pdf Binary files differindex f7f2b8e..4d295f7 100644 --- a/docs/gettingStarted.pdf +++ b/docs/gettingStarted.pdf diff --git a/docs/gettingStarted.tex b/docs/gettingStarted.tex index 67357fe..4d88ace 100644 --- a/docs/gettingStarted.tex +++ b/docs/gettingStarted.tex @@ -8,30 +8,30 @@ \maketitle \section{Repository Access} \begin{itemize} - \item \textbf{Install} Git packages with \emph{sudo apt-get install git-core git-gui git-doc}. Set up your basic git settings \href{http://help.github.com/git-email-settings/}{like so}. + \item \textbf{Install} Git packages with \texttt{sudo apt-get install git-core git-gui git-doc}. Set up your basic git settings \href{http://help.github.com/git-email-settings/}{like so}. \item \textbf{Sign up} for a GitHub account (\href{https://github.com/signup/free}{here}) then ask Russell to add your account as a collaborator to the rcoh/SmootLight code repository. \item \textbf{Connect} to the SmootLight GitHub code repository. Generate SSH keys and upload the public one to GitHub by following the instructions \href{http://help.github.com/linux-key-setup/}{here}. \item \textbf{Clone and branch} the code repository; use \href{http://help.github.com/git-cheat-sheets/}{this cheatsheet} for help as necessary. \end{itemize} \section{Testing on Pygame} \begin{itemize} - \item \textbf{Install} Pygame with \emph{sudo apt-get install python-pygame}. - \item \textbf{Setup} logging by running \emph{./setup.sh}. - \item \textbf{Run} your LightInstallation code with \emph{python LightInstallation.py}. + \item \textbf{Install} Pygame with \texttt{sudo apt-get install python-pygame}. + \item \textbf{Setup} logging by running \texttt{./setup.sh}. + \item \textbf{Run} your LightInstallation code with \texttt{python LightInstallation.py}. \end{itemize} \section{Repository Check In} \begin{itemize} - \item \textbf{Stage} files to be committed with \emph{./ga}. - \item \textbf{Commit} your changes locally with \emph{git commit}. - \item \textbf{Push} your changes to your branch with \emph{git push origin yourbranchname}. + \item \textbf{Stage} files to be committed with \texttt{./ga}. + \item \textbf{Commit} your changes locally with \texttt{git commit}. + \item \textbf{Push} your changes to your branch with \texttt{git push origin yourbranchname}. \item \textbf{Request a pull} to the source repository by following instructions \href{http://help.github.com/pull-requests/}{here}. \item \textbf{Learn more} about working with remote repositories \href{http://help.github.com/remotes/}{here}. \end{itemize} \section{Latex Documentation} \begin{itemize} - \item \textbf{Install} Latex packages to be consistent with current documentation style. I had to run \emph{sudo apt-get install texlive-fonts-recommended texlive-latex-extra} to successfully convert Russell's .tex to pdf. - \item \textbf{Edit} the .tex files with any text editor. I use vim for quick edits and gedit with the Latex plugin for autocompletion and quick previews. Get the Latex plugin with \emph{sudo apt-get install gedit-latex-plugin}. - \item \textbf{Publish to PDF} with \emph{pdflatex yourfile.tex}. - \item \textbf{View PDF} with \emph{evince yourfile.pdf}. + \item \textbf{Install} Latex packages to be consistent with current documentation style. I had to run \texttt{sudo apt-get install texlive-fonts-recommended texlive-latex-extra} to successfully convert Russell's .tex to pdf. + \item \textbf{Edit} the .tex files with any text editor. I use vim for quick edits and gedit with the Latex plugin for autocompletion and quick previews. Get the Latex plugin with \texttt{sudo apt-get install gedit-latex-plugin}. + \item \textbf{Publish to PDF} with \texttt{pdflatex yourfile.tex}. + \item \textbf{View PDF} with \texttt{evince yourfile.pdf}. \end{itemize} \end{document} |