CTAN
Comprehensive TeX Archive Network

Direc­tory support/texosquery

README.md

tex­os­query

Cross-plat­form Java ap­pli­ca­tion to query OS in­for­ma­tion de­signed for use in 's shell es­cape mech­a­nism.

The ap­pli­ca­tion can query the fol­low­ing:

  • lo­cale in­for­ma­tion
  • de­fault file en­cod­ing
  • cur­rent work­ing di­rec­tory
  • user home di­rec­tory
  • tem­po­rary di­rec­tory
  • OS name, arch and ver­sion
  • Cur­rent date and time in PDF for­mat (for for­mats that don't pro­vide \pdfcreationdate)
  • Date-time stamp of a file in PDF for­mat (for for­mats that don't pro­vide \pdffilemoddate)
  • Size of a file in bytes (for for­mats that don't pro­vide \pdffilesize)
  • Con­tents of a di­rec­tory (cap­tured as a list)
  • Direc­tory con­tents fil­tered by reg­u­lar ex­pres­sion (cap­tured as a list)
  • URI of a file
  • Canon­i­cal path of a file

All paths use a for­ward slash as di­rec­tory di­vider so re­sults can be used, for ex­am­ple, in com­mands like \includegraphics.

There are files pro­vided for easy ac­cess in doc­u­ments:

  • texosquery.tex : generic code
  • texosquery.sty : pack­age

This pro­vides the com­mand \TeXOSQuery to run texosquery us­ing 's shell es­cape mech­a­nism and cap­ture the re­sult in a con­trol se­quence. The cat­e­gory code of most of 's de­fault spe­cial char­ac­ters (and some other po­ten­tially prob­lem­atic char­ac­ters) is tem­porar­ily changed to 12 while read­ing the re­sult. Some of the texosquery out­put con­tains short markup com­mands (such as \wrp) which are in­ter­nally con­verted within \TeXOSQuery.

Im­por­tant Notes

The code uses a piped shell es­cape to cap­ture the re­sult from texosquery. This means that you must have the piped shell es­cape en­abled to make use of this fea­ture. MiK users need the --enable-pipes op­tion on the com­mand line to en­able this. The al­ter­na­tive is to run texosquery out­side of and cap­ture the out­put in a tem­po­rary file, which can then be read us­ing \TeXOSQueryFromFile.

You need to cor­rectly set up the con­fig­u­ra­tion file texosquery.cfg to match your sys­tem. The pack­age man­agers can't do this for you au­to­mat­i­cally. Copy the file to ei­ther your TEXMFHOME or TEXMFLOCAL tree to pre­vent it from be­ing over­writ­ten by sub­se­quent up­dates.

texosquery-jre8 is on the re­stricted list for Live 2017. To take ad­van­tage of this, you must have at least Java 8 in­stalled and edit the texosquery.cfg file to:

\def\TeXOSInvokerName{texosquery-jre8}
\TeXOSQueryAllowRestricted

(Note that the sec­ond line above has been un­com­mented.)

Note that due to 's se­cu­rity mea­sures, quotes can't be used in the re­stricted mode's shell es­cape. This means that if you need to pass a file name con­tain­ing a space as an ar­gu­ment to texosquery, you'll have to use the un­re­stricted mode.

In­stal­la­tion

In­stal­la­tion is best done us­ing your pack­age man­ager. Man­ual in­stal­la­tion in­struc­tions are de­scribed be­low. For more de­tail, see the doc­u­men­ta­tion.

Com­pil­ing the Doc­u­men­ta­tion

To com­pile the doc­u­men­ta­tion:

pdflatex texosquery.dtx
makeglossaries texosquery
makeindex -s gglo.ist -t texosquery.glg -o texosquery.gls texosquery.glo
pdflatex texosquery.dtx
makeindex -s gind.ist texosquery.idx
pdflatex texosquery.dtx
pdflatex texosquery.dtx

Ex­tract­ing the Files

Ex­cept for the .jar files, the texosquery files are all bun­dled in­side texosquery.dtx with the ex­trac­tion com­mands pro­vided in texosquery.ins. To ex­tract all the files do:

tex texosquery.ins

The .sh files are bash scripts for Unix-like users. Th­ese will need to be set to ex­e­cutable us­ing chmod. I rec­om­mend that you also re­move the .sh ex­ten­sion. Win­dows users can deleted these files.

The .batch files are batch scripts for Win­dows users. Unix-like users can delete these files. Th­ese files are given the ex­ten­sion .batch as on Win­dows doesn't al­low the cre­ation of .bat files. The ex­ten­sion will need to be changed to .bat af­ter the files have been ex­tracted.

In­stalling the Ap­pli­ca­tion

In the fol­low­ing, re­place TEXMF with the path to your TEXMF di­rec­tory. You can find your home TEXMF di­rec­tory us­ing

kpsewhich -var-value=TEXMFHOME

There are now three Java ap­pli­ca­tions pro­vided by this pack­age:

  • texosquery.jar (re­quires at least Java 7)
  • texosquery-jre8.jar (re­quires at least Java 8)
  • texosquery-jre5.jar (re­quires at least Java 5)

(See the "Se­cu­rity" sec­tion be­low.)

There are cor­re­spond­ing bash scripts for Unix-like users (the .sh ex­ten­sion added by texosquery.ins should be re­moved and the files made ex­e­cutable):

  • texosquery
  • texosquery-jre8
  • texosquery-jre5

There are also cor­re­spond­ing batch scripts for Win­dows users (the .batch ex­ten­sion cre­ated by the .ins file should be changed to .bat):

  • texosquery.bat
  • texosquery-jre8.bat
  • texosquery-jre5.bat

Each script uses kpsewhich to find the cor­re­spond­ing .jar file and runs it.

Put the .jar files in TEXMF/scripts/texosquery/ and the bash or .bat files some­where on your path. You may or may not need to re­fresh the database.

To test the in­stal­la­tion, run

texosquery -v

in the com­mand prompt or ter­mi­nal. (Also try with texosquery-jre8 and texosquery-jre5.)

If suc­cess­ful, it should show the ver­sion num­ber.

In­stalling the Code

The .tex, .cfg and .sty files should all be ex­tracted from texosquery.dtx with tex texosquery.ins as de­scribed above.

  • Move texosquery.tex to TEXMF/tex/generic/texosquery/
  • Move texosquery.cfg to TEXMF/tex/generic/texosquery/
  • Move texosquery.sty to TEXMF/tex/latex/texosquery/
  • Move texosquery.pdf to TEXMF/doc/generic/texosquery/

The texosquery.cfg file al­lows you to spec­ify which ap­pli­ca­tion you want to use. First check which ver­sion of the Java Run­time En­vi­ron­ment (JRE) you have in­stalled:

java -version

This should dis­play the ver­sion in­for­ma­tion. (For ex­am­ple, "1.8.0_92")

If the ver­sion num­ber starts with 1.8 ("Java 8"), then you can use texosquery-jre8.jar. This is the full ap­pli­ca­tion. You can use texosquery or texosquery-jre5 as well, but there's less lo­cale sup­port with them. The texosquery-jre8 bash script and texosquery-jre8.bat batch script in­vokes Java with -Djava.locale.providers=CLDR,JRE.

If Win­dows users have sim­ply been sup­plied with an ex­e­cutable ver­sions of the texosquery-jre8.jar file (texosquery-jre8.exe) then you'll have to set the JAVA_TOOL_OPTIONS en­vi­ron­ment vari­able in­stead.

This java.locale.providers set­ting al­lows Java to ac­cess lo­cale in­for­ma­tion from the [Uni­code Com­mon Lo­cale Data Re­pos­i­tory (CLDR)](http://cldr.uni­code.org/) in­stalled on their sys­tem. The pend­ing Java 9 should in­clude this by de­fault, so this will only be rel­e­vant to Java 8. Ear­lier ver­sions of Java (7 or be­low) don't have this op­tion, which lim­its the lo­cale sup­port to that which is na­tively pro­vided by the JRE. Note that Java 7 and ear­lier ver­sions have reached their end of life and are now dep­re­cated.

If the ver­sion in­for­ma­tion starts with 1.7 ("Java 7"), then you can use texosquery.jar. This is the de­fault ap­pli­ca­tion and pro­vides most of the func­tions of the full ap­pli­ca­tion, but there's less lo­cale sup­port. You can also use the even more lim­ited texosquery-jre5, but you can't use texosquery-jre8, so you can't take ad­van­tage of the CLDR.

If the ver­sion in­for­ma­tion starts with 1.5 ("Java 5") or 1.6 ("Java 6"), then you can only use texosquery-jre5. The lo­cale sup­port is sig­nif­i­cantly re­duced in this case and there's no sup­port for lan­guage scripts.

Once you have de­ter­mined which ap­pli­ca­tion you want to use, edit the texosquery.cfg so that \TeXOSInvokerName is de­fined to the ap­pro­pri­ate in­vo­ca­tion. For ex­am­ple, with Java 8:

\def\TeXOSInvokerName{texosquery-jre8}

or with Java 5 or 6:

\def\TeXOSInvokerName{texosquery-jre5}

(bash users will have to add the .sh ex­ten­sion if it hasn't been re­moved, as per the above in­struc­tions.)

Ex­am­ples:

Plain :

% arara: pdftex: {shell: on}
\input texosquery

\TeXOSQuery{\result}{-b}
IEFT BCP 47 language tag: \result.

\TeXOSQueryLocale{\result}
POSIX locale: \result.

\TeXOSQueryCwd{\result}
cwd: {\tt \result}.

\TeXOSQueryNow{\result}
now: \result.

\TeXOSQueryFileDate{\result}{\jobname.tex}
file date: \result.

\TeXOSQueryFileSize{\result}{\jobname.tex}
file size: \result bytes.

\bye

:

% arara: pdflatex: {shell: on}
\documentclass{article}

\usepackage{texosquery}
\usepackage{etoolbox}

\begin{document}

\TeXOSQuery{\result}{-b}
IEFT BCP 47 language tag: \result.

\TeXOSQueryLocale{\result}
POSIX locale: \result.

\TeXOSQueryCwd{\result}
cwd: \texttt{\result}.

\TeXOSQueryNow{\result}
now: \result.

\TeXOSQueryFileDate{\result}{\jobname.tex}
file date: \result.

\TeXOSQueryFileSize{\result}{\jobname.tex}
file size: \result bytes.

\TeXOSQueryFilterFileList{\result}{,}{.+\string\.(png|jpg)}{.}
All jpg and png files in current directory:

\renewcommand{\do}[1]{\texttt{#1}.\par}
\expandafter\docsvlist\expandafter{\result}

\end{document}

For a full list of avail­able com­mands, see the doc­u­men­ta­tion (texosquery.pdf).

Trou­bleshoot­ing

If some­thing goes wrong with the call to texosquery, the con­trol se­quence will be set to empty. If this hap­pens, here are the steps to di­ag­nose the prob­lem:

  1. Check the log file for any lines start­ing with TeXOSQuery: For ex­am­ple: TeXOSQuery: texosquery-jre8 --pdfnow If found, this means that the dry run mode was on and the shell es­cape wasn't used. En­sure that the shell es­cape is en­abled when you build the doc­u­ment.

2. If the log file con­tains (|texosquery op­tions) then the shell es­cape was used but texosquery re­turned an empty value. In this case, copy the part be­tween (| and ) and paste it into a com­mand prompt or ter­mi­nal but in­sert --debug at the start of the op­tions list. For ex­am­ple, if the log file con­tains (|texosquery-jre8 --cwd) then run

texosquery-jre8 --debug --cwd

This should now dis­play an er­ror mes­sage ex­plain­ing the prob­lem. (For ex­am­ple, read ac­cess for­bid­den or file not found or a se­cu­rity ex­cep­tion.)

Se­cu­rity

As from ver­sion 1.2, all vari­ants of texosquery (JRE5, 7 and 8) obey Live's openin_any set­ting. Any of the ac­tions that in­volve read­ing file in­for­ma­tion won't work if read ac­cess is for­bid­den by openin_any or by the op­er­at­ing sys­tem. MiK doesn't use the openin_any set­ting, so if not set texosquery will as­sume a (any).

In ad­di­tion to obey­ing openin_any, the file list­ing ac­tions (such as --list) for the JRE7 and 8 vari­ants also pro­hibit list­ing the con­tents out­side of the cur­rent work­ing di­rec­tory's path. This means that you can't, for ex­am­ple, list the con­tents of .. (the cur­rent work­ing di­rec­tory's par­ent) nor can you try walk­ing the en­tire file sys­tem. The --walk ac­tion ad­di­tion­ally won't de­scend hid­den di­rec­to­ries. This ex­tra re­stric­tion is de­signed to pre­vent ma­li­cious code from try­ing to use texosquery to look around your fil­ing sys­tem.

The Java 5 ver­sion texosquery-jre5 is the least se­cure and doesn't have this ad­di­tional re­stric­tion on the file list­ing ac­tions. How­ever, it still obeys openin_any. The --walk ac­tion is not avail­able with texosquery-jre5.

Ex­am­ples:

texosquery-jre8 --debug --walk ',' '.*' /

This ac­tion is for­bid­den:

texosquery-jre8: Can't walk directory: /

Chang­ing / to . is al­lowed, but not for texosquery-jre5:

texosquery-jre5 --debug --walk ',' '.*' .

re­turns:

texosquery-jre5: walk requires at least JRE 7 version

With openin_any=a, the --userhome ac­tion is usu­ally al­lowed (de­pends on the op­er­at­ing sys­tem and Java's se­cu­rity man­ager).

texosquery-jre8 --debug --userhome

re­turns

\fslh home\fslh nlct

(which \TeXOSQuery con­verts to /home/nlct.)

How­ever, un­less this also hap­pens to be the cur­rent work­ing di­rec­tory, it's not pos­si­ble to ob­tain a file list­ing:

texosquery-jre8 --debug --list ',' /home/nlct

re­turns

texosquery-jre8: Unable to list contents of: /home/nlct
texosquery-jre8: Listing outside cwd path not permitted: /home/nlct

Source code

The Java source is in the .java files and the man­i­fest for each .jar file is Manifest*.txt (Manifest-jre8.txt for texosquery-jre8 etc). As­sum­ing the fol­low­ing di­rec­tory struc­ture:

java/TeXOSQuery.java
java/TeXOSQueryJRE5.java
java/TeXOSQueryJRE7.java
java/TeXOSQueryJRE8.java
java/QueryAction.java
java/QueryActionType.java
java/FileSortType.java
java/FileSortComparator.java
java/FileListType.java
java/FileWalkVisitor.java
java/Manifest-jre5.txt
java/Manifest-jre7.txt
java/Manifest-jre8.txt
classes/com/dickimawbooks/texosquery/

Then to cre­ate texosquery-jre8.jar, do (for JDK ver­sion 1.8):

cd java 
javac -d ../classes TeXOSQuery.java QueryAction.java QueryActionType.java TeXOSQueryJRE8.java FileSortType.java FileSortComparator.java FileListType.java FileWalkVisitor.java
cd ../classes
jar cmf ../java/Manifest-jre8.txt ../texosquery-jre8.jar com/dickimawbooks/texosquery/*.class

Sim­i­larly for the other .jar files, re­plac­ing 8 with 7 or 5. (The Java 7 ver­sion should re­ally be texosquery-jre7.jar, but is sim­ply named texosquery.jar in the dis­tri­bu­tion for back­ward com­pat­i­bil­ity rea­sons. If you com­pile the code, the .jar name is your choice.)


Source on GitHub: https://github.com/nlct/tex­os­query

Author Home Page: http://www.dicki­maw-books.com/

Li­cense: LPPL 1.3+

Down­load the con­tents of this pack­age in one zip archive (763.0k).

tex­os­query – Cross-plat­form Java ap­pli­ca­tion to query OS in­for­ma­tion

This pack­age pro­vides a cross-plat­form Java ap­pli­ca­tion to query OS in­for­ma­tion de­signed for use in ’s shell es­cape mech­a­nism.

The ap­pli­ca­tion can query the fol­low­ing:

  • lo­cale and code­set
  • cur­rent work­ing di­rec­tory
  • user home di­rec­tory
  • tem­po­rary di­rec­tory
  • OS name, arch and ver­sion
  • Cur­rent date and time in PDF for­mat (for for­mats that don’t pro­vide \pdfcre­ation­date)
  • Date-time stamp of a file in PDF for­mat (for for­mats that don't pro­vide \pdf­file­mod­date)
  • Size of a file in bytes (for for­mats that don’t pro­vide \pdf­file­size)
  • Con­tents of a di­rec­tory (cap­tured as a list)
  • Direc­tory con­tents fil­tered by reg­u­lar ex­pres­sion (cap­tured as a list)
  • URI of a file
  • Canon­i­cal path of a file

All paths use a for­ward slash as di­rec­tory di­vider so re­sults can be used, for ex­am­ple, in com­mands like \in­clude­graph­ics.

There are files pro­vided for easy ac­cess in doc­u­ments:

  • tex­os­query.tex: generic code
  • tex­os­query.sty: pack­age

This pro­vides com­mands to run tex­os­query us­ing ’s shell es­cape mech­a­nism and cap­ture the re­sult in a con­trol se­quence. The cat­e­gory code of most of ’s de­fault spe­cial char­ac­ters (and some other po­ten­tially prob­lem­atic char­ac­ters) is tem­porar­ily changed to 12 while read­ing the re­sult.

Pack­agetex­os­query
Re­pos­i­toryhttps://github.com/nlct/tex­os­query
Ver­sion1.6 2017-06-20
Li­cense The Project Public Li­cense 1.3
Main­tainer Ni­cola Tal­bot
Con­tained inTeX Live as tex­os­query
MiKTeX as tex­os­query
Topics os-level sup­port fa­cil­i­ties for
...
Guest Book Sitemap Contact Contact Author