qsharp.dtx

% \iffalse meta-comment
%
% Copyright (C) 2018 by Microsoft.
% ---------------------------------------------------------------------------
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Christopher Granade (chgranad@microsoft.com).
%
% This work consists of the files qsharp.dtx and qsharp.ins,
% the derived filebase qsharp.sty, and the associated installer file Install.ps1.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{qsharp.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{qsharp}
%<*package>
    [2019/08/27 v0.9.1908.2701 Updated to 0.9 syntax.]
%</package>
%<*driver>
\documentclass{ltxdoc}
\usepackage[pretty,uselistings]{revquantum}[2015/12/29]
    \lstset{basicstyle=\ttfamily\footnotesize, commentstyle=\rmfamily}
\usepackage{xcolor}
\usepackage{qsharp}
\usepackage{sourcecodepro}
\usepackage[numbers]{natbib}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{qsharp.dtx}
  \PrintChanges
^^A   \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v0.9.1908.2902}{2019/08/29}{Updated to 0.9 syntax.}
% \changes{v0.3.1901.1401}{2019/01/14}{Initial public version.}
% \changes{v0.1}{2018/12/04}{Initial version.}
%
% \DoNotIndex{\newcommand,\newenvironment}
%
% \providecommand*{\url}{\texttt}
% \newcommand{\DescribeColor}[1]{%
%     \DescribeMacro{#1}%
%     {\color{#1} \textbullet}
%
% }
%
% \GetFileInfo{qsharp.dtx}
% \title{The \textsf{qsharp} package}
% \author{Christopher Granade \\ \url{chgranad@microsoft.com}}
% \date{\fileversion~from \filedate}
%
% \maketitle
%
% \section{Introduction}
%
% The \textsf{qsharp} package provides syntax highlighting for the \qs~language \cite{svore2018q}.
%
% \section{Examples}
%
% \begin{lstlisting}[style=QSharp]
%   namespace Example {
%       open Microsoft.Quantum.Intrinsic;
%
%       /// # Summary
%       /// Prepares $(\ket{00} + \ket{11}) / \sqrt{2}$.
%       operation PrepareEntangledPair(left : Qubit, right : Qubit) : Unit
%       is Adj + Ctl {
%           H(left);
%           CNOT(left, right);
%       }
%   }
% \end{lstlisting}
%
% \section{Usage}
%
% For the most part, this package is used through the \textsf{listings} package.
%
% \subsection{\textsf{listings} Integration}
%
% To use this package to typeset \qs~source with \textsf{listings}, use the |language=QSharp| key when using the |{lstlisting}| environment or the |\lstinput| and |\lstverbatim| macros.
% The \textsf{qsharp} package also provides a |style=qsharp| definition with some additional support for including mathematical notation from \qs~comments.
% For example, the source code listing above was generated using the following \LaTeX~code:
%
% \iffalse
% NB: We need to define a new environment type so that we don't have \end{lstlisting}
%     twice in a row.
% \fi
% \lstnewenvironment{lsttexlisting}{\lstset{language=TeX}}{}
% \begin{lsttexlisting}
%   \begin{lstlisting}[style=QSharp]
%       namespace Example {
%           open Microsoft.Quantum.Intrinsic;
%
%           /// # Summary
%           /// Prepares $(\ket{00} + \ket{11}) / \sqrt{2}$.
%           operation PrepareEntangledPair(left : Qubit, right : Qubit) : Unit
%           is Adj + Ctl {
%               H(left);
%               CNOT(left, right);
%           }
%       }
%   \end{lstlisting}
% \end{lsttexlisting}
%
% \subsection{Macros}
%
% \DescribeMacro{\qs}
% This macro provides a shorthand for correctly typesetting \qs.
%
% \StopEventually{}
%
% \section{Implementation}
%
% \iffalse
%<*package>
% \fi
%

%    \begin{macrocode}

\RequirePackage{listings}
\RequirePackage{xcolor}

%    \end{macrocode}

% \subsection{Notation} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% \begin{macro}{\qs}
%    \changes{v0.3.1901.1401}{2019/01/14}{Initial public version.}
%    \begin{macrocode}

\newcommand*{\qs}{Q\#}

%    \end{macrocode}
% \end{macro}

% \subsection{Color Definitions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%    \begin{macrocode}

\definecolor{cud-reddish-purple}{RGB}{204,121,167}
\colorlet{doc-comment}{cud-reddish-purple!60!black}

%    \end{macrocode}

% \subsection{Language Definition} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%    \begin{macrocode}

\makeatletter
\lstdefinelanguage{QSharp}{
    morekeywords={
        namespace,
        open,
        as,
        operation,
        function,
        newtype,
        body,
        adjoint,
        auto,
        distribute,
        self,
        invert,
        intrinsic,
        controlled,
        let,
        set,
        if, 
        elif, 
        else,
        repeat, 
        until,
        fixup,
        while,
        return, 
        fail,
        for,
        in,
        mutable,
        using,
        borrowing,
        within,
        apply,
        is,
        Adj,
        Ctl,
        Adjoint,
        Controlled,
        Qubit, Unit,
        Int, BigInt,
        Double, 
        Bool, 
        String, 
        Pauli, Result,
        Range,
        Zero, One,
        true, false, 
        PauliI, PauliX, PauliY, PauliZ,
        new, 
        not, and, or,        
    },
    % Define built-in intrinsics as second-order keywords.
    morekeywords=[2]{
        H,
        CNOT,
        I,
        X,
        Y,
        Z,
        Message,
        Assert,
        AssertProb,
        CCNOT,
        Exp,
        ExpFrac,
        M,
        Measure,
        R,
        R1,
        R1Frac,
        Random,
        Reset,
        ResetAll,
        RFrac,
        Rx,
        Ry,
        Rz,
        S,SWAP,
        T
    },
    sensitive=true,
    morecomment=[l]{//},
    morecomment=[l][\lst@commentstyle\color{doc-comment}]{///}
}
\makeatother

%    \end{macrocode}
%
% We also provide styles that set options that are commonly useful with \qs.
%
%    \begin{macrocode}

\lstdefinestyle{QSharp}{
    language=QSharp,
    mathescape=true
}

%    \end{macrocode}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% \bibliographystyle{abbrvnat}
% \bibliography{qsharp}

%
% \iffalse
%</package>
% \fi
%
% \Finale
\endinput