No Description
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

jsh_standard.tex 10KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230
  1. %----------------------------------------------------------------------------------------
  2. % DOCUMENT CONFIGURATION
  3. %----------------------------------------------------------------------------------------
  4. \documentclass[twoside]{article}
  5. \usepackage{lipsum} % Package to generate dummy text throughout this template
  6. \usepackage[sc]{mathpazo} % Use the Palatino font
  7. \usepackage[T1]{fontenc} % Use 8-bit encoding that has 256 glyphs
  8. \linespread{1.05} % Line spacing - Palatino needs more space between lines
  9. \usepackage{microtype} % Slightly tweak font spacing for aesthetics
  10. \usepackage[hmarginratio=1:1,top=24mm,left=16mm,bottom=24mm,columnsep=20pt]{geometry} % Document margins
  11. \usepackage{multicol} % Used for the two-column layout of the document
  12. \usepackage[hang, small,labelfont=bf,up,textfont=it,up]{caption} % Custom captions under/above floats in tables or figures
  13. \usepackage{booktabs} % Horizontal rules in tables
  14. \usepackage{float} % Required for tables and figures in the multi-column environment - they need to be placed in specific locations with the [H] (e.g. \begin{table}[H])
  15. \usepackage{hyperref} % For hyperlinks in the PDF
  16. \usepackage{lettrine} % The lettrine is the first enlarged letter at the beginning of the text
  17. \usepackage{paralist} % Used for the compactitem environment which makes bullet points with less space between them
  18. \usepackage{abstract} % Allows abstract customization
  19. \renewcommand{\abstractnamefont}{\normalfont\bfseries} % Set the "Abstract" text to bold
  20. \renewcommand{\abstracttextfont}{\normalfont\small\itshape} % Set the abstract itself to small italic text
  21. \usepackage{titlesec} % Allows customization of titles
  22. \renewcommand\thesection{\Roman{section}} % Roman numerals for the sections
  23. \renewcommand\thesubsection{\Roman{subsection}} % Roman numerals for subsections
  24. \titleformat{\section}[block]{\large\scshape\centering}{\thesection.}{1em}{} % Change the look of the section titles
  25. \titleformat{\subsection}[block]{\large}{\thesubsection.}{1em}{} % Change the look of the section titles
  26. \usepackage{fancyhdr} % Headers and footers
  27. \pagestyle{fancy} % All pages have headers and footers
  28. \fancyhead{} % Blank out the default header
  29. \fancyfoot{} % Blank out the default footer
  30. %\fancyhead[C]{Running title $\bullet$ November 2012 $\bullet$ Vol. XXI, No. 1} % Custom header text
  31. \fancyfoot[RO,LE]{\thepage} % Custom footer text
  32. \newcommand{\code}[1]{\texttt{#1}}
  33. %----------------------------------------------------------------------------------------
  34. % TITLE SECTION
  35. %----------------------------------------------------------------------------------------
  36. \title{\vspace{-15mm}\fontsize{24pt}{10pt}\selectfont\textbf{Standards for Input and Output in the Augmented Unix Userland}} % Article title
  37. \author{
  38. \large
  39. \textsc{Sam Abradi, Ian Naval, Fredric Silberberg}\\[2mm] % Your name
  40. \normalsize Worcester Polytechnic Institute \\ % Your institution
  41. \normalsize \{\href{mailto:stabradi@wpi.edu}{stabradi},\href{mailto:ianaval@wpi.edu}{ianaval},\href{mailto:fbsilberberg@wpi.edu}{fbsilberberg}\}@wpi.edu % Your email address
  42. \vspace{-5mm}
  43. }
  44. \date{}
  45. %----------------------------------------------------------------------------------------
  46. \begin{document}
  47. \maketitle % Insert title
  48. \thispagestyle{fancy} % All pages have headers and footers
  49. %----------------------------------------------------------------------------------------
  50. % ABSTRACT
  51. %----------------------------------------------------------------------------------------
  52. \begin{abstract}
  53. \noindent The Augmented Unix Userland includes a set of standards to which all modified utility programs must adhere. This document outlines these guidelines and provides detailed explanations for each standard.
  54. \end{abstract}
  55. %----------------------------------------------------------------------------------------
  56. % ARTICLE CONTENTS
  57. %----------------------------------------------------------------------------------------
  58. \begin{multicols}{2} % Two-column layout throughout the main article text
  59. \section{Background}
  60. [Insert general introduction and talking about how we need to define some terminology such as streams, substreams and the tributary utility]
  61. \subsection{Streams}
  62. We are taking the traditional concept of streams and sending updates from program to program in frames. This allows us to easily enable parallel processing by turning standard input and output into constant streams of data instead of having to buffer all of the output from one program, wait for it to finish, and then pass it along to the next program. We do this by having the output of a program be an array of output blocks, each with its own StdOut and StdErr. These are arrays themselves, and each named object becomes a substream. In the example below, the StdOut stream would have a substream called processes, and each element of the stream would be passed as the frame comes.
  63. \subsection{Tributary Utilty}
  64. This format allows us to define a new utility tentatively called ``tributary'' that allows you to query substreams from the toplevel standard output format. For example, running it with the query "stdout" is basically equivalent to ``echo''. But if we query for the ``processes'' subfield using the syntax ``stdout>processes'', then we can pull out all the values corresponding to the objects containing a ``processes'' key in StdOut. Think of it as grep for JSON but built around the concept of using keys and values to navigate output.
  65. \section{Standards}
  66. [Insert details about the standardized format]
  67. Things to note:
  68. \begin{compactitem}
  69. \item All output must be standard JSON as defined by RFC 7159.
  70. \item The top-level JSON value must be a standard JSON array as defined in section 5 of RFC 7159.
  71. \item The elements of the top level array (henceforth called JSH frames) must be standard JSON objects as defined in section 4 of RFC 7159.
  72. \item JSH frames must contain two members whose names are ``StdOut'' and ``StdErr'' and whose values are standard JSON arrays.
  73. \item A top-level JSH stream is an array of standard JSON values. The concatenation of arrays from the JSH frames constitute the elements of a top-level JSH stream. Only the arrays whose associated names are the same across all frames.
  74. \item A substream is an array of standard JSON values. A substream has a parent stream and an associated name. The substreams elements are derived by iterating over the elements of the parent stream. For each element of the parent stream, the following process is applied. If the element is an array, then its values are concatenated to the substream. If the element is an object and contains a value corresponding to the substream's associated name, then that value is added to the substream. If the element is neither an object nor an array, then the element itself is added to the substream.
  75. \end{compactitem}
  76. \subsection{Tributary Selectors}
  77. We also decided that any valid JSON key name is a valid key for a substream selector. However, if the name contains a space character, a ">", or a single quotation mark symbol, we require that the entire key be surrounded with quotation marks. Using single quotation marks within the selector requires that they be escaped with a backslash.
  78. \section{Examples and Use Cases}
  79. \subsection{Example: ps}
  80. For example, the program \code{ps}'s output could look like either Figure~\ref{fig:psSingleFrame} or Figure~\ref{fig:psMultipleFrame}. Both forms of output are equivalent.
  81. \begin{figure}[H]
  82. \begin{verbatim}
  83. [{
  84. "StdOut": [
  85. {"processes":
  86. {"pid": 1, "name": "init"}},
  87. {"processes":
  88. {"pid": 2, "name": "bash"}},
  89. {"processes":
  90. {"pid": 3, "name": "ps"}}
  91. ],
  92. "StdErr": []
  93. }]\end{verbatim}
  94. \caption{Sample Output of ps with a Single Frame}
  95. \label{fig:psSingleFrame}
  96. \end{figure}
  97. \begin{figure}[H]
  98. \begin{verbatim}
  99. [{
  100. "StdOut": [
  101. {"processes":
  102. {"pid": 1, "name": "init"}},
  103. {"processes":
  104. {"pid": 2, "name": "bash"}}
  105. ],
  106. "StdErr": []
  107. },
  108. {
  109. "StdOut": [
  110. {"processes":
  111. {"pid": 3, "name": "ps"}}
  112. ],
  113. "StdErr": []
  114. }]\end{verbatim}
  115. \caption{Sample Output of ps with Multiple Frames}
  116. \label{fig:psMultipleFrame}
  117. \end{figure}
  118. \begin{figure}[H]
  119. \begin{verbatim}
  120. $ ps | tributary "stdout>processes"
  121. [{
  122. "StdOut": [
  123. {"pid": 1, "name": "init"},
  124. {"pid": 2, "name": "bash"},
  125. {"pid": 3, "name": "ps"}
  126. ],
  127. "StdErr": []
  128. }]\end{verbatim}
  129. \caption{Sample Output of ps Piped to Tributary}
  130. \label{fig:psWithTributary}
  131. \end{figure}
  132. In future weeks, we will probably hide the details of using the tributary program with special syntax in our new shell language.
  133. \begin{figure}[H]
  134. \begin{verbatim}
  135. $ nonstandard_ls
  136. [{
  137. "StdOut": [
  138. {
  139. "foo": {
  140. "files": [{"name": ____}]
  141. }
  142. }
  143. ],
  144. "StdErr": []
  145. }]
  146. \end{verbatim}
  147. \caption{Sample Output of Nonstandard ls}
  148. \label{fig:nonstandardLs}
  149. \end{figure}
  150. \begin{figure}[H]
  151. \begin{verbatim}
  152. [{
  153. "StdOut": [
  154. {
  155. "files": [{"name": ____}, ...]
  156. }
  157. ],
  158. "Stderr": []
  159. }]
  160. \end{verbatim}
  161. \caption{Expected Input Template for Standard Cat}
  162. \label{fig:expectedInputForStandardCat}
  163. \end{figure}
  164. Piping out the nonstandard format of ls through the \code{tributary} program would allow the user to normalize the data by simply typing ``\code{nonstandard\_ls | tributary "stdout>foo" | cat}.''
  165. \section{Using Tributary to Standardize Output}
  166. While there is a tentatively defined format for all of our first party utilities, the expectation is that others will also use our output format when writing new utilities and may not always follow the spec to the letter. If some third party application nests some kernel of standardized output within fields that are unknown to any of the standard utilities, using our tributary function will enable users to easily access that standard info, and essentially peel it out into its own stream.
  167. \cite{jsonRFC}
  168. % REFERENCE LIST
  169. %----------------------------------------------------------------------------------------
  170. \begin{thebibliography}{99} % Bibliography - this is intentionally simple in this template
  171. \bibitem[RFC 7159]{jsonRFC}
  172. T. Bray, Ed.
  173. \newblock The JavaScript Object Notation (JSON) Data Interchange Format.
  174. \newblock Internet Engineering Task Force (IETF).
  175. \end{thebibliography}
  176. %----------------------------------------------------------------------------------------
  177. \end{multicols}
  178. \end{document}