# HG changeset patch # User samer # Date 1326469984 0 # Node ID 546bfd3988b0c070c709a14b71ad1d9801263f02 # Parent 4d183f2855c290071215cd6c95dd7d8662409aac Added unpolished pldoc documentation. diff -r 4d183f2855c2 -r 546bfd3988b0 pldoc/pldoc.sty --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/pldoc/pldoc.sty Fri Jan 13 15:53:04 2012 +0000 @@ -0,0 +1,517 @@ +% SWI-Prolog document-style + +% Test for PDF generation using pdflatex + +\usepackage{ifpdf} +%Old tex versions +%\newif\ifpdf +%\ifx\pdfoutput\undefined +% \pdffalse +%\else +% \pdfoutput=1 +% \pdftrue +%\fi + +% Get hyperrefs to work + +\usepackage{makeidx} +\usepackage{url} + +\ifpdf + \usepackage[pdftex,colorlinks=true,urlcolor=blue]{hyperref} + \pdfcompresslevel=9 +% \pdfcatalog{ +% /PageMode /UseOutLines +% } + \usepackage[pdftex]{graphicx} + \DeclareGraphicsExtensions{.pdf,.jpg,.png} +\else + \usepackage[dvips]{graphicx} + \DeclareGraphicsExtensions{.eps,.ps} +\fi +\graphicspath{{figs/}{./}} + +% Other styles + +\usepackage{a4wide} +\usepackage{longtable} +\usepackage{ifthen} +\usepackage{dcolumn} +\usepackage{calc} +\setlongtables + +\catcode`\^^A=8% downarrow are for subscripts +\catcode`\_=\active +\def_{\ifmmode\else\_\fi} +\def\vobeyspaces{\@vobeyspaces} + +\newcommand{\onlinebreak}{} + +% References + +\newcommand{\secref}[1]{section~\ref{sec:#1}} +\newcommand{\appref}[1]{appendix~\ref{sec:#1}} +\newcommand{\chapref}[1]{chapter~\ref{sec:#1}} +\newcommand{\figref}[1]{figure~\ref{fig:#1}} +\newcommand{\tabref}[1]{table~\ref{tab:#1}} + +\newcommand{\Secref}[1]{Section~\ref{sec:#1}} +\newcommand{\Appref}[1]{Appendix~\ref{sec:#1}} +\newcommand{\Chapref}[1]{Chapter~\ref{sec:#1}} +\newcommand{\Figref}[1]{Figure~\ref{fig:#1}} +\newcommand{\Tabref}[1]{Table~\ref{tab:#1}} + +\newcommand{\tm}{$^{tm}$} + +\newcommand{\reffont}{\tt} +\newcommand{\predref}[2]{% % functor/arity + \mbox{\reffont #1/#2}} +\newcommand{\funcref}[2]{% % functor/arity + \mbox{\reffont #1/#2}} +\newcommand{\dcgref}[2]{% % functor//arity + \mbox{\reffont #1//#2}} +\newcommand{\qpredref}[3]{% % module:functor/arity + \mbox{\reffont #1:#2/#3}} +\newcommand{\qdcgref}[3]{% % module:functor//arity + \mbox{\reffont #1:#2//#3}} +\newcommand{\nopredref}[2]{% % functor/arity (external) + \mbox{\reffont #1/#2}} +\newcommand{\functor}[2]{% % functor/arity (no predicate) + \mbox{\reffont #1/#2}} +\newcommand{\manref}[2]{% % page(n) + \mbox{{\reffont #1(}{\rm #2}{\tt )}}} +\newcommand{\cfuncref}[2]{% % function(Args...) + \mbox{{\reffont #1(}{\it #2}{\tt )}}} +\newcommand{\prologflag}[1]{% + \mbox{\reffont #1}} + +% Descriptions (definitions) of various things +% Note: I do not know where the 1ex comes from. This should fit +% exactly, but appearently some dimension is missing. I suspect +% a space creaping in somewhere. + +\def\@nodescription{false} + +\newcommand{\defentry}[1]{\definition{#1}} +\newcommand{\definition}[1]{% + \onlinebreak% + \ifthenelse{\equal{\@nodescription}{true}}{% + \def\@nodescription{false}% + \makebox[-\leftmargin]{\mbox{}}\makebox[\linewidth+\leftmargin-1ex][l]{\bf #1}\\}{% + \item[{\makebox[\linewidth+\leftmargin-1ex][l]{#1}}]}} +\newcommand{\nodescription}{\def\@nodescription{true}} + +\makeatletter +\def\cmdlineoptionitem{\@ifstar{\@gluedcmdoptitem}{\@cmdoptitem}} +\def\@gluedcmdoptitem#1#2{\definition{\texttt{#1}\var{#2}}} +\def\@cmdoptitem#1#2{\definition{\texttt{#1} \var{#2}}} +\makeatother +\newcommand{\longoptionitem}[2]{% + \ifthenelse{\equal{}{#2}}{% + \definition{-{}-#1}}{% + \definition{-{}-#1={\it #2}}}\ignorespaces} +\newcommand{\longoption}[2]{% + \ifthenelse{\equal{}{#2}}{% + \mbox{\reffont -{}-#1}}{% + \mbox{\reffont -{}-#1={\it #2}}}} + +\newcommand{\traceoption}[3]{% + \definition{{\tt #1} (#2)}#3% + \ignorespaces} +\newcommand{\pleaseoption}[3]{% + \definition{#1 {\it #2} {\rm(default: \it #3)}}% + \ignorespaces} +%\prologflagitem{Name}{Type}{Access} +\newcommand{\prologflagitem}[3]{% + \definition{#1 {\it (#2% + \ifthenelse{\equal{rw}{#3}}{, changeable}{})}}% + \index{flag:#1}\ignorespaces} +\newcommand{\escapeitem}[1]{% + \definition{\Sesc{\tt #1}} + \ignorespaces} +\newcommand{\fmtchar}[1]{% + \item[\tt #1]% + \ignorespaces} + +% \directive{Name}{Arity}{Args} +% \predicate[Attibutes]{Name}{Arity}{Args} +% \function[Attibutes]{Name}{Arity}{Args} +% \infixop{Name}{Left}{Right} +% \prefixop{Name}{Right} +% \infixfunction{Name}{Left}{Right} +% \prefixfunction{Name}{Right} +% \dcg[Attibutes]{Name}{Arity}{Args} +% +% Predicate descriptions. Must appear in a description +% environment. + +\newcommand{\resitem}[1]{% + \defentry{#1}% + \index{#1}\ignorespaces} +\makeatletter +\def\predatt#1{\hfill{\it\footnotesize[#1]}} +\def\predicate{\@ifnextchar[{\@attpredicate}{\@predicate}} +\def\qpredicate{\@ifnextchar[{\@attqpredicate}{\@qpredicate}} +\def\@predicate#1#2#3{% + \ifthenelse{\equal{#2}{0}}{% + \defentry{#1}}{% + \defentry{#1({\it #3})}}% + \index{#1/#2}\ignorespaces} +\def\@attpredicate[#1]#2#3#4{% + \ifthenelse{\equal{#3}{0}}{% + \defentry{#2\predatt{#1}}}{% + \defentry{#2({\it #4})\predatt{#1}}}% + \index{#2/#3}\ignorespaces} +\def\@qpredicate#1#2#3#4{% + \ifthenelse{\equal{#3}{0}}{% + \defentry{#1:#2}}{% + \defentry{#1:#2({\it #4})}}% + \index{#1/#2}\ignorespaces} +\def\@attqpredicate[#1]#2#3#4#5{% + \ifthenelse{\equal{#4}{0}}{% + \defentry{#2:#3\predatt{#1}}}{% + \defentry{#2:#3({\it #5})\predatt{#1}}}% + \index{#2/#3}\ignorespaces} +\def\directive{\@ifnextchar[{\@attdirective}{\@directive}} +\def\@directive#1#2#3{% + \ifthenelse{\equal{#2}{0}}{% + \defentry{:- #1}}{% + \defentry{:- #1({\it #3})}}% + \index{#1/#2}\ignorespaces} +\def\@attdirective[#1]#2#3#4{% + \ifthenelse{\equal{#3}{0}}{% + \defentry{:- #2\predatt{#1}}}{% + \defentry{:- #2({\it #4})\predatt{#1}}}% + \index{#2/#3}\ignorespaces} +\def\dcg{\@ifnextchar[{\@attdcg}{\@dcg}} +\def\@dcg#1#2#3{% + \ifthenelse{\equal{#2}{0}}{% + \defentry{#1}}{% + \defentry{#1({\it #3}) \texttt{//}}}% + \index{#1/#2}\ignorespaces} +\def\@attdcg[#1]#2#3#4{% + \ifthenelse{\equal{#3}{0}}{% + \defentry{#2 \texttt{//}\predatt{#1}}}{% + \defentry{#2({\it #4}) \texttt{//}\predatt{#1}}}% + \index{#2//#3}\ignorespaces} +\def\infixop{\@ifnextchar[{\@attinfixop}{\@infixop}} +\def\@infixop#1#2#3{% + \defentry{{\it #2} #1 {\it #3}}% + \index{#1/2}\ignorespaces} +\def\@attinfixop[#1]#2#3#4{% + \defentry{{\it #3} #2 {\it #4}\predatt{#1}}% + \index{#2/2}\ignorespaces} +\def\prefixop{\@ifnextchar[{\@attprefixop}{\@prefixop}} +\def\@prefixop#1#2{% + \defentry{#1 {\it #2}}% + \index{#1/1}\ignorespaces} +\def\@attprefixop[#1]#2#3{% + \defentry{#2 {\it #3}\predatt{#1}}% + \index{#2/1}\ignorespaces} +\let\function\predicate +\let\infixfunction\infixop +\let\prefixfunction\prefixop +\makeatother + +% \termitem{functor}{Args} +% \infixtermitem{functor}{Left}{Right} +% \prefixtermitem{functor}{Right} +% \postfixtermitem{functor}{Left} +% +% Terms in description lists. Typically used to describe various +% possible values or types for a term. + +\newcommand{\termitem}[2]{% + \ifthenelse{\equal{}{#2}}{% + \definition{#1}}{% + \definition{#1({\it #2})}}\ignorespaces} +\newcommand{\infixtermitem}[3]{% + \definition{{\it #2} #1 {\it #3}}\ignorespaces} +\newcommand{\prefixtermitem}[2]{% + \definition{#1 {\it #2}}\ignorespaces} +\newcommand{\postfixtermitem}[2]{% + \definition{{\it #2} #1}\ignorespaces} + +% \term{functor}{Args} +% \infixterm{functor}{Left}{Right} +% \prefixterm{functor}{Right} +% \postfixterm{functor}{Left} +% +% Terms used in running text. + +\def\term{} +\renewcommand{\term}[2]{% + \ifthenelse{\equal{\protect}{\protect#2}}{% + {\reffont #1}}{% + {\reffont #1}({\it #2})}} +\newcommand{\infixterm}[3]{{\it #2} #1 {\it #3}} +\newcommand{\prefixterm}[2]{#1 {\it #2}} +\newcommand{\postfixterm}[2]{{\it #2} #1} +\newcommand{\errorterm}[2]{\mbox{\tt% + \ifthenelse{\equal{}{#2}}{% + #1}{% + #1(#2)}}} + + +\newcommand{\cfunction}[3]{% + \defentry{{\tt #1} #2{\rm (}{\it #3}{\rm )}}% + \index{#2()}\ignorespaces} +\newcommand{\constructor}[2]{% + \defentry{#1::#1{\rm (}{\it #2}{\rm )}}% + \index{#1::#1()}\ignorespaces} +\newcommand{\destructor}[1]{% + \defentry{#1::\Stilde{}#1{\rm ()}}% + \index{#1::\Stilde{}#1()}\ignorespaces} +\newcommand{\cppcast}[2]{% + \defentry{#1::operator #2{\rm ({\it void})}}% + \index{#1::operator #2()}\ignorespaces} +\newcommand{\cdecl}[2]{{\tt #1} {\em #2}} +\newcommand{\cmacro}[3]{% + \defentry{{\it #1} #2({\it #3})}% + \index{#2()}\ignorespaces} +\newcommand{\constitem}[1]{% + \definition{#1}% + \index{#1}\ignorespaces} +\newcommand{\cglobalvar}[1]{{\tt #1}} +\newcommand{\classitem}[1]{% + \definition{Class #1}% + \index{#1 \string\idxtype{class}}\ignorespaces} +\newcommand{\menuitem}[2]{% + \ifthenelse{\equal{\protect}{\protect#2}}{% + \definition{\textsf #1}}{% + \definition{\textsf #1 ({\it #2})}}% + \index{#1 \string\idxtype{menu}}% + \ignorespaces} + + +% \tag{Keyword} +% +% PlDoc @keyword expansion. \mtag{Keyword} is a multi-valued tag + +\newcommand{\tag}[1]{% + \item[#1]} +\newcommand{\mtag}[1]{% + \item[#1]\mbox{}\\} + +\newcommand{\bnfmeta}[1]{\ifmmode{\langle\mbox{\it #1}\rangle}\else$\langle\mbox{\it #1}\rangle$\fi} +\newcommand{\bnfor}{\ifmmode\mid\else$\mid$\fi} +\newcommand{\isa}{& ::= &} +\newcommand{\ora}{& $\mid$ &} + +\renewcommand{\arg}[1]{\ifmmode\mbox{\em #1}\else{\it #1}\fi} +\newcommand{\class}[1]{{\em #1}\index{#1 \string\idxtype{class}}} +\newcommand{\classs}[1]{{\em #1s}\index{#1 \string\idxtype{class}}} +\newcommand{\demo}[1]{{\sf #1}\index{#1 \string\idxtype{demo}}} +\newcommand{\pllib}[1]{{\texttt{#1}}\index{#1 \string\idxtype{library}}} +\newcommand{\clib}[1]{{\tt #1}\index{#1 \string\idxtype{library}}} +\newcommand{\tool}[1]{{\em #1}\index{#1 \string\idxtype{tool}}} +\newcommand{\menuref}[1]{\textsf{#1}\index{#1 \string\idxtype{menu}}} +\newcommand{\constf}[1]{{\reffont #1}} +\newcommand{\const}[1]{{\tt #1}} +\newcommand{\plflag}[1]{{\tt #1}} +\newcommand{\type}[1]{{\reffont #1}} +\newcommand{\idx}[1]{#1\index{#1}} +\newcommand{\foreseen}[1]{\footnote{#1}} +\newcommand{\metafile}[1]{\mbox{\tt #1}} +\newcommand\file{\begingroup \urlstyle{tt}\Url} +\newcommand\email{\begingroup \urlstyle{tt}\Url} +\newcommand{\env}[1]{\mbox{\tt #1}} +\newcommand{\except}[1]{\mbox{\tt #1}} +\newcommand{\exam}[1]{\mbox{\tt #1}} +\newcommand{\module}[1]{\mbox{\reffont #1}} +\newcommand{\fileext}[1]{\mbox{\texttt{.#1}}} +\newcommand{\option}[1]{\mbox{\tt #1}} +\newcommand{\resource}[1]{\mbox{\reffont #1}} +\newcommand{\cmdlineoption}[1]{\mbox{\tt #1}} +\newcommand{\argoption}[2]{\mbox{\tt #1 \em #2}} +\newcommand{\ctype}[1]{{\texttt{#1}}} +\newcommand{\op}[1]{{\tt #1}} +\newcommand{\program}[1]{\texttt{#1}} +\newcommand{\manpage}[2]{{\bf #1}(#2)} +\newcommand{\chr}[1]{{\tt #1}} +\newcommand{\jargon}[1]{{\em #1}} +\newcommand{\strong}[1]{{\bf #1}} +\newcommand{\texcmd}[1]{{\Sesc}{\tt #1}} +\newcommand{\texenv}[1]{{\tt #1}} +\newcommand{\texmode}[1]{{\tt #1}} +\newcommand{\HTML}[1]{{\bf #1}} +\newcommand{\libdoc}[2]{\section{\pllib{#1}: #2}} +\newcommand{\key}[1]{{\sf #1}} +\newcommand{\menu}[2]{% + {\sf #1}% + \ifthenelse{\equal{#2}{}}{% + }{% + ~(\texttt{#2})}} + +\newcommand\satom{\begingroup \urlstyle{tt}\Url} +\newcommand\fmtseq{\begingroup \urlstyle{tt}\Url} + +\urldef{\Sexe}\satom{#!} % #! +\urldef{\Scgt}\satom{#>} % #> +\urldef{\Scge}\satom{#>=} % #>= +\urldef{\Sclt}\satom{#<} % #< +\urldef{\Scle}\satom{#=<} % #=< +\urldef{\Sceq}\satom{#=} % #= +\urldef{\Scne}\satom{#\=} % #\= +\urldef{\Scnot}\satom{#\} % #\ +\urldef{\Scor}\satom{#\/} % #\/ +\urldef{\Scand}\satom{#/\} % #/\ +\urldef{\Sequiv}\satom{#<=>} % #<=> +\urldef{\Slimpl}\satom{#<=} % #<= +\urldef{\Srimpl}\satom{#=>} % #=> +\urldef{\Slimplies}\satom{#<==} % #<== +\urldef{\Srimplies}\satom{#==>} % #==> +\urldef{\Scequal}\satom{#<==>} % #<==> +\urldef{\Scieq}\satom{#=:=} % #=:= +\urldef{\Scine}\satom{#=\=} % #=\= +\urldef{\Shash}\satom{#} % # +\urldef{\Scut}\satom{!} % ! +\urldef{\Scomma}\satom{,} % , +\urldef{\Sifthen}\satom{->} % -> +\urldef{\Ssoftcut}\satom{*->} % *-> +\urldef{\Sdot}\satom{.} % . +\urldef{\Ssemicolon}\satom{;} % ; +\urldef{\Slt}\satom{<} % < +\urldef{\Sxor}\satom{><} % >< +\urldef{\Seq}\satom{=} % = +\urldef{\Suniv}\satom{=..} % =.. +\urldef{\Saeq}\satom{=:=} % =:= +\urldef{\Sle}\satom{=<} % =< +\urldef{\Sel}\satom{<=} % <= +\urldef{\Sequal}\satom{==} % == +\urldef{\Sstructeq}\satom{=@=} % =@= +\urldef{\Sstructneq}\satom{\=@=} % \=@= +\urldef{\Sane}\satom{=\=} % =\= +\urldef{\Sgt}\satom{>} % > +\urldef{\Sge}\satom{>=} % >= +\urldef{\Stlt}\satom{@<} % @< +\urldef{\Stle}\satom{@=<} % @=< +\urldef{\Stgt}\satom{@>} % @> +\urldef{\Stge}\satom{@>=} % @>= +\urldef{\Snot}\satom{\+} % \+ +\urldef{\Sne}\satom{\=} % \= +\urldef{\Snequal}\satom{\==} % \== +\urldef{\Shat}\satom{^} % ^ +\urldef{\Sbar}\satom{|} % | +\urldef{\Stimes}\satom{*} % * +\urldef{\Spow}\satom{**} % ** +\urldef{\Splus}\satom{+} % + +\urldef{\Sminus}\satom{-} % - +\urldef{\Sdiv}\satom{/} % / +\urldef{\Sidiv}\satom{//} % // +\urldef{\Sand}\satom{/\} % /\ +\urldef{\Slshift}\satom{<<} % << +\urldef{\Srshift}\satom{>>} % >> +\urldef{\Sneg}\satom{\} % \ +\urldef{\Sesc}\satom{\} % \ +\urldef{\Sor}\satom{\/} % \/ +\urldef{\Sdollar}\satom{$} % $ +\urldef{\Squest}\satom{?} % ? +\urldef{\Smodule}\satom{:} % : +\urldef{\Sneck}\satom{:-} % :- +\urldef{\Sdirective}\satom{?-} % ?- +\urldef{\Sdcg}\satom{-->} % --> +\urldef{\Bc}\satom{\c} % \c +\urldef{\Bn}\satom{\n} % \n +\urldef{\Br}\satom{\r} % \r +\urldef{\Bl}\satom{\l} % \l +\urldef{\BB}\satom{\\} % \\ +\urldef{\Stilde}\satom{~} % ~ +\urldef{\Spercent}\satom{%} % % +\urldef{\Shash}\satom{#} % # +\urldef{\Scurl}\satom{{}} % {} +\urldef{\SxXX}\satom{xXX..\} % xXX..\ + +\newcommand{\bug}[1]{\footnote{BUG: #1}} + +\newcommand{\mod}[2]{#1 \mbox{\rm mod} #2} +\newcommand{\rem}[2]{#1 \mbox{\rm rem} #2} +\newcommand{\pow}[2]{{#1}^{#2}} +\newcommand{\bsl}[0]{\Sesc} + +% Index handling + +\newcommand{\idxtype}[1]{{\small\em #1}} + +% Prolog predicate summary + +\newenvironment{summarylist}[1]{\begin{longtable}[l]{#1}}{\end{longtable}} +\newcommand{\predicatesummary}[3]{#1/#2 & #3 \\} +\newcommand{\oppredsummary}[5]{#1/#2 & #5 \\} +\newcommand{\functionsummary}[3]{#1/#2 & #3 \\} +\newcommand{\opfuncsummary}[5]{#1/#2 & #5 \\} +\newcommand{\opsummary}[4]{#3 & #1 & #2 & #4 \\} +\newcommand{\hook}[1]{(hook)} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% CODE environment % +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\usepackage{fancyvrb} +\usepackage{color} + +%\definecolor{codeboxcolor}{rgb}{0.7,0.7,0.7} +\definecolor{codeboxcolor}{rgb}{0.4,0.4,0.4} +\DefineVerbatimEnvironment% + {code}{Verbatim} + {frame=single, + framerule=0.2pt, + rulecolor=\color{codeboxcolor}, + } + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% INCLUDE FIGURES % +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% PostScript figures +% \postscriptfig[width=5in]{label}{Title} + +\makeatletter +\def\postscriptfig{\@ifnextchar[{\@scaledpostscriptfig}{\@postscriptfig}} +\def\@scaledpostscriptfig[#1]#2#3{% + \begin{figure}% + \centerline{\includegraphics[#1]{#2}} + \caption{#3} + \label{fig:#2} + \end{figure}} +\def\@postscriptfig#1#2{% + \begin{figure}% + \centerline{\includegraphics{#1}} + \caption{#2} + \label{fig:#1} + \end{figure}} +\makeatother + +% \begin{tabularlp}{longest-text} + +\newlength{\tabDright} +\newlength{\tabDleft} +\newcommand{\PreserveBackslash}[1]{\let\temp=\\#1\let\\=\temp} +\newcommand{\raggedrightcolumn}{\PreserveBackslash\raggedright\hspace{0pt}} +\newenvironment{tabularlp}[1]% + {\settowidth{\tabDleft}{#1}% + \setlength{\tabDright}{\linewidth-\columnsep*3-\tabDleft}% + \begin{tabular}{|p{\tabDleft}|>{\raggedrightcolumn}p{\tabDright}|}}% + {\end{tabular}} + +% \begin{tags} ... \end{tags} + +\newenvironment{tags}% + {\begin{quote}\begin{description}% + \setlength{\itemsep}{0pt}% + \footnotesize}% + {\end{description}\end{quote}} + + +% \begin{parameters} ... \end{parameters} + +\newenvironment{parameters}% + {\par% + \makebox[\linewidth]{\hfill\footnotesize Parameters} + \begin{tabular*}{\linewidth}{lp{0.7\linewidth}} + \hline}% + {\end{tabular*}} + + diff -r 4d183f2855c2 -r 546bfd3988b0 pldoc/plml.pdf Binary file pldoc/plml.pdf has changed diff -r 4d183f2855c2 -r 546bfd3988b0 pldoc/plml.tex --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/pldoc/plml.tex Fri Jan 13 15:53:04 2012 +0000 @@ -0,0 +1,325 @@ +\documentclass[10pt]{article} +\usepackage{pldoc} +\sloppy +\makeindex + +\begin{document} +% This LaTeX document was generated using the LaTeX backend of PlDoc, +% The SWI-Prolog documentation system + + + +\section{plml: Prolog-Matlab interface} + +\label{sec:plml} + +\begin{tags} + \tag{To be done} +Use mat(I) and tmp(I) as types to include engine Id. + +Clarify relationship between return values and valid Matlab denotation. + +Reshape/2 array representation: reshape([ ... ],Size) +Expression language: arr(Vals,Shape,InnerFunctor) - allows efficient +representation of arrays of arbitrary things. Will require more strict +nested list form. + +Deprecate old array(Vals::Type) and cell(Vals::Type) left-value syntax. + +Remove I from \dcgref{ml_expr}{2} and add to mx type? +\end{tags} + +\paragraph{Types} + +\textbf{ml_eng} - Any atom identifying a Matlab engine. + +\textbf{ml_stmt} - A Matlab statement + +\begin{code} +X;Y :: ml_stmt :- X:ml_stmt, Y:ml_stmt. +X,Y :: ml_stmt :- X:ml_stmt, Y:ml_stmt. +X=Y :: ml_stmt :- X:ml_lval, Y:ml_expr. +hide(X) :: ml_stmt :- X:ml_stmt. +\end{code} + +\begin{code} +ml_expr(A) % A Matlab expression, possibly with multiple return values +ml_loc ---> mat(atom,atom). % Matbase locator +\end{code} + +\paragraph{Matlab expression syntax} + +The Matlab expression syntax adopted by this module allows Prolog terms to represent +or denote Matlab expressions. Let T be the domain of recognised Prolog terms (corresponding to +the type ml_expr), and M be the domain of Matlab expressions written in Matlab syntax. +Then V : T\Sifthen{}M is the valuation function which maps Prolog term X to Matlab expression V[X]. +These are some of the constructs it recognises: + +Constructs valid only in top level statements, not subexpressions: + +\begin{code} +X;Y % |--> V[X]; V[Y] (sequential evaluation hiding first result) +X,Y % |--> V[X], V[Y] (sequential evaluation displaying first result) +X=Y % |--> V[X]=V[Y] (assignment, X must denote a valid left-value) +hide(X) % |--> V[X]; (execute X but hide return value) +\end{code} + +Things that look and work like Matlab syntax (more or less): + +\begin{code} ++X % |--> uplus(V[X]) +-X % |--> uminus(V[X]) +X+Y % |--> plus(V[X],V[Y]) +X-Y % |--> minus(V[X],V[Y]) +X^Y % |--> mpower(V[X],V[Y]) +X*Y % |--> mtimes(V[X],V[Y]) +X/Y % |--> mrdivide(V[X],V[Y]) +X\Y % |--> mldivide(V[X],V[Y]) +X.^Y % |--> power(V[X],V[Y]) +X.*Y % |--> times(V[X],V[Y]) +X./Y % |--> rdivide(V[X],V[Y]) +X.\Y % |--> ldivide(V[X],V[Y]) +X:Y:Z % |--> colon(V[X],V[Y],V[Z]) +X:Z % |--> colon(V[X],V[Z]) +X>Z % |--> gt(V[X],V[Y]) +X>=Z % |--> ge(V[X],V[Y]) +X lt(V[X],V[Y]) +X= le(V[X],V[Y]) +X==Z % |--> eq(V[X],V[Y]) +[X1,X2,...] % |--> [ V[X1], V[X2], ... ] +[X1;X2;...] % |--> [ V[X1]; V[X2]; ... ] +{X1,X2,...} % |--> { V[X1], V[X2], ... } +{X1;X2;...} % |--> { V[X1]; V[X2]; ... } +@X % |--> @V[X] (function handle) +\end{code} + +Things that do not look like Matlab syntax but provide standard Matlab features: + +\begin{code} +'Infinity' % |--> inf (positive infinity) +'Nan' % |--> nan (not a number) +X`` % |--> ctranpose(V[X]) (conjugate transpose, V[X]') +X#Y % |--> getfield(V[X],V[q(Y)]) +X\\Y % |--> @(V[X])V[Y] (same as lambda(X,Y)) +\\Y % |--> @()V[Y] (same as thunk(Y)) +lambda(X,Y) % |--> @(V[X])V[Y] (anonymous function with arguments X) +thunk(Y) % |--> @()V[Y] (anonymous function with no arguments) +vector(X) % |--> horzcat(V[X1],V[X2], ...) +atvector(X) % as vector but assumes elements of X are assumed all atomic +cell(X) % construct 1xN cell array from elements of X +`X % same as q(X) +q(X) % wrap V[X] in single quotes (escaping internal quotes) +qq(X) % wrap V[X] in double quotes (escaping internal double quotes) +tq(X) % wrap TeX expression in single quotes (escape internal quotes) +\end{code} + +Referencing different value representations. + +\begin{code} +mat(X,Y) % denotes a value in the Matbase using a dbload expression +mx(X:mx_blob) % denotes an MX Matlab array in SWI memory +ws(X:ws_blob) % denotes a variable in a Matlab workspace +wsseq(X:ws_blob) % workspace variable containing list as cell array. +\end{code} + +Tricky bits. + +\begin{code} +apply(X,AX) % X must denote a function or array, applied to list of arguments AX. +cref(X,Y) % cell dereference, |--> V[X]{ V[Y1], V[Y2], ... } +arr(Lists) % multidimensional array from nested lists. +arr(Lists,Dims) % multidimensional array from nested lists. +\end{code} + +Things to bypass default formatting + +\begin{code} +noeval(_) % triggers a failure when processed +atom(X) % write atom X as write/1 +term(X) % write term X as write/1 +\(P) % escape and call phrase P directly to generate Matlab string +$(X) % calls pl2ml_hook/2, denotes V[Y] where plml_hook(X,Y). +'$VAR'(N) % gets formatted as p_N where N is assumed to be atomic. +\end{code} + +All other Prolog atoms are written using \predref{write}{1}, while other Prolog terms +are assumed to be calls to Matlab functions named according to the head functor. +Thus V[ $<$head$>$( $<$arg1$>$, $<$arg2$>$, ...) ] = $<$head$>$(V[$<$arg1$>$, V[$<$arg2$>$], ...). + +There are some incompatibilities between Matlab syntax and Prolog syntax, +that is, syntactic structures that Prolog cannot parse correctly: + +\begin{itemize} + \item 'Command line' syntax, ie where a function of string arguments: +"save('x','Y')" can be written as "save x Y" in Matlab, +but in Prolog, you must use function call syntax with quoted arguments: +save(`x,`'Y'). + \item Matlab's postfix transpose operator "x'" must be written using a different +posfix operator "x``" or function call syntax "ctranspose(x)". + \item Matlab cell referencing using braces, as in x\{1,2\} must be written +as "cref(x,1,2)". + \item Field referencing using dot (.), eg x.thing - currently resolved +by using hash (\#) operator, eg x\#thing. + \item Using variables as arrays and indexing them. The problem is that +Prolog doesn't let you write a term with a variable as the head +functor. +\end{itemize} + +\vspace{0.7cm} + +\begin{description} + \predicate[nondet,multifile]{matlab_init}{2}{-Key, -Cmd:ml_expr} +Each user-defined clause of \predref{matlab_init}{2} causes \arg{Cmd} to be executed +whenever a new Matlab session is started. + + \predicate[nondet,multifile]{matlab_path}{2}{-Key, -Path:list(atom)} +Each user-defined clause of \predref{matlab_path}{2} causes the directories in \arg{Path} +to be added to the Matlab path of every new Matlab session. Directories +are relative to the root directory as returned by Matlab function proot. + + \predicate[nondet,multifile]{pl2ml_hook}{2}{+X:term, -Y:ml_expr} +Clauses of \predref{pl2ml_hook}{2} allow for extensions to the Matlab expression +language such that \verb|V[$X] = V[Y]| if \verb$pl2ml_hook(X,Y)$. + + \predicate[det]{ml_open}{3}{+Id:ml_eng, +Host:atom, +Options:list(_)} +\nodescription + \predicate[det]{ml_open}{2}{+Id:ml_eng, +Host:atom} +\nodescription + \predicate[det]{ml_open}{1}{+Id:ml_eng} +Start a Matlab session on the given host. If \arg{Host}=localhost +or the name of the current current host as returned by \predref{hostname}{1}, +then a Matlab process is started directly. Otherwise, it is +started remotely via SSH. \arg{Options} defaults to []. \arg{Host} defaults to +localhost. + +Start a Matlab session on the specified host using default options. +If \arg{Host} is not given, it defaults to localhost. Session will be +associated with the given \arg{Id}, which should be an atom. See \predref{ml_open}{3}. + +Valid options are + +\begin{description} + \termitem{noinit}{} +If present, do not run initialisation commands specified by +\predref{matlab_path}{2} and \predref{matlab_init}{2} clauses. Otherwise, do run them. +\end{description} + +\begin{description} + \termitem{debug}{In, Out} +if present, Matlab is started in a script which captures standard +input and output to files In and Out respectively. + +[What if session is already open and attached to \arg{Id}?] +\end{description} + + \predicate[det]{ml_close}{1}{+Id:ml_eng} +Close Matlab session associated with \arg{Id}. + + \predicate[det]{ml_exec}{2}{+Id:ml_eng, +Expr:ml_expr} +Execute Matlab expression without returning any values. + + \predicate[det]{ml_eval}{4}{+Id:ml_eng, +Expr:ml_expr, +Types:list(type), -Res:list(ml_val)} +Evaluate Matlab expression binding return values to results list \arg{Res}. This new +form uses an explicit output types list, so \arg{Res} can be completely unbound on entry +even when multiple values are required. + + \predicate[semidet]{ml_test}{2}{+Id:ml_eng, +X:ml_expr(bool)} +Succeeds if \arg{X} evaluates to true in Matlab session \arg{Id}. + + \predicate[det]{===}{2}{Y:ml_vals(A), X:ml_expr(A)} +Evaluate Matlab expression \arg{X} as in \predref{ml_eval}{4}, binding one or more return values +to \arg{Y}. If \arg{Y} is unbound or a single ml_val(_), only the first return value is bound. +If \arg{Y} is a list, multiple return values are processed. + + \predicate[det]{??}{1}{X:ml_expr(_)} +Execute Matlab expression \arg{X} as with \predref{ml_exec}{2}, without returning any values. + + \predicate[semidet]{???}{1}{X:ml_expr(bool)} +Evaluate Matlab boolean expression \arg{X} as with \predref{ml_test}{2}. + + \predicate[det]{ml_debug}{1}{+Flag:boolean} +Set or reset debug state. \verb$ml_debug(true)$ causes formatted Matlab +statements to be printed before being sent to Matlab engine. + + \predicate[det]{term_mlstring}{3}{+Id:ml_eng, +X:ml_expr, -Y:list(code)} +Convert term representing Matlab expression to a list of character codes. + + \predicate[det]{term_texatom}{2}{+X:tex_expr, -Y:atom} +Convert term representing TeX expression to a string in atom form. + + \predicate[semidet]{wsvar}{3}{+X:ws_blob(A), -Nm:atom, -Id:ml_eng} +True if \arg{X} is a workspace variable in Matlab session \arg{Id}. +Unifies \arg{Nm} with the name of the Matlab variable. + + \predicate[det]{dropmat}{2}{+Id:ml_id, +Mat:ml_loc} +Deleting MAT file from matbase. + + \predicate[det]{exportmat}{3}{+Id:ml_id, +Mat:ml_loc, +Dir:atom} +Export specified MAT file from matbase to given directory. + + \predicate[nondet]{matbase_mat}{2}{+Id:ml_eng, -X:ml_loc} +Listing mat files actually in matbase at given root directory. + + \predicate[det]{persist_item}{2}{+X:ml_expr(A), -Y:ml_expr(A)} +Convert Matlab expression to persistent form not dependent on +current Matlab workspace or MX arrays in Prolog memory space. +Large values like arrays and structures are saved in the matbase +replaced with matbase locators. Scalar values are converted to +literal numeric values. Character strings are converted to Prolog atoms. +Cell arrays wrapped in the \predref{wsseq}{1} functor are converted to literal +form. + +NB. any side effects are undone on backtracking -- in particular, any +files created in the matbase are deleted. + + \predicate[det]{mhelp}{1}{+Name:atom} +Lookup Matlab help on the given name. Equivalent to executing help(`X). + + \predicate[det]{compileoptions}{2}{+Opts:list(ml_options), -Prefs:ml_expr(options)} +Convert list of option specifiers into a Matlab expression representing +options (ie a struct). Each specifier can be a Name:Value pair, a name +to be looked up in the \predref{optionset}{2} predicate, a nested list of ml_options +compileoptions :: list (optionset \Sbar{} atom:value \Sbar{} struct) \Sifthen{} struct. +NB. option types are as follows: + +\begin{code} +X :: ml_options :- optionset(X,_). +X :: ml_options :- X :: ml_option(_). +X :: ml_options :- X :: list(ml_options). +X :: ml_options :- X :: ml_expr(struct(_)). + +ml_option(A) ---> atom:ml_expr(A). +\end{code} + + \predicate[det]{multiplot}{2}{+Type:ml_plot, +Cmds:list(ml_expr(_))} +\nodescription + \predicate[det]{multiplot}{3}{+Type:ml_plot, +Cmds:list(ml_expr(_)), -Axes:list(ml_val(handle))} +Executes plotting commands in \arg{Cmds} in multiple figures or axes as determined +by \arg{Type}. Valid types are: + +\begin{description} + \termitem{figs}{Range} +Executes each plot in a separate figure, Range must be P..Q where P +and Q are figure numbers. + \termitem{vertical}{} +Executes each plot in a subplot; +subplots are arranged vertically top to bottom in the current figure. + \termitem{horizontal}{} +Executes each plot in a subplot; +subplots are arranged horizontally left to right in the current figure. + \termitem{\Sdot}{Type, [link(Axis)]} +As for multplot type \arg{Type}, but link X or Y axis scales as determined by Axis, +which can be `x, `y, or `xy. +\end{description} + +Three argument form returns a list containing the Matlab handles to axes objects, +one for each plot. + + \predicate[semidet,multifile]{optionset}{2}{+Key:term, -Opts:list(ml_options)} +Extensible predicate for mapping arbitrary terms to a list of options +to be processed by \predref{compileoptions}{2}. +\end{description} + + +\printindex +\end{document}