aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGravatar rcoh <rcoh@mit.edu>2011-02-17 18:51:46 -0500
committerGravatar rcoh <rcoh@mit.edu>2011-02-17 18:51:46 -0500
commit53c18ac308d90329cb0b9fbedd45194971785b85 (patch)
tree48539b7f3fd2f0f2cb0e659c50656f6d1cfba5c4
parente3d0104e43efbb3724d4156f06310bd915307581 (diff)
Adding gettingStarted docs and improving XmlConfiguration docs.
-rw-r--r--docs/XmlConfiguration.pdfbin134992 -> 152157 bytes
-rw-r--r--docs/XmlConfiguration.tex124
-rw-r--r--docs/gettingStarted.pdfbin96917 -> 95402 bytes
-rw-r--r--docs/gettingStarted.tex22
4 files changed, 134 insertions, 12 deletions
diff --git a/docs/XmlConfiguration.pdf b/docs/XmlConfiguration.pdf
index 343347a..9136232 100644
--- a/docs/XmlConfiguration.pdf
+++ b/docs/XmlConfiguration.pdf
Binary files differ
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}$' &lt; ${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
index f7f2b8e..4d295f7 100644
--- a/docs/gettingStarted.pdf
+++ b/docs/gettingStarted.pdf
Binary files differ
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}