ENH: Added base structure for foamHelp utility

This commit is contained in:
andy
2012-08-16 14:36:53 +01:00
parent a9e8caa979
commit 7627c08ea8
6 changed files with 734 additions and 0 deletions

View File

@ -0,0 +1,242 @@
/*---------------------------------------------------------------------------*\
========= |
\\ / F ield | OpenFOAM: The Open Source CFD Toolbox
\\ / O peration |
\\ / A nd | Copyright (C) 2012 OpenCFD Ltd.
\\/ M anipulation |
-------------------------------------------------------------------------------
License
This file is part of OpenFOAM.
OpenFOAM is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
\*---------------------------------------------------------------------------*/
#include "doxygenXmlParser.H"
#include "wordRe.H"
// * * * * * * * * * * * * * * * * Constructors * * * * * * * * * * * * * * //
Foam::doxygenXmlParser::doxygenXmlParser
(
const fileName& fName,
const string& startTag,
const string& searchStr,
const bool exactMatch
)
:
dictionary(dictionary::null)
{
IFstream is(fName);
char c;
// skip forward to entry name
skipForward(is, startTag);
while (is.get(c))
{
if (c == '<')
{
// if in block, read block name
string blockName = "";
string params = "";
bool readingParam = false;
while (is.get(c) && c != '>')
{
if (c == ' ')
{
readingParam = true;
}
else
{
if (readingParam)
{
params = params + c;
}
else
{
blockName = blockName + c;
}
}
}
if (blockName == '/' + startTag)
{
break;
}
if ((blockName == "compound") && (params == "kind=\"file\""))
{
// keep entry
word name = "";
fileName path = "";
word fName = "";
bool foundName = false;
bool foundPath = false;
bool foundFName = false;
bool earlyExit = false;
while (!foundName || !foundPath || !foundFName)
{
word entryName;
getEntry<word>(is, entryName);
if (entryName == "name")
{
getValue<word>(is, name);
if (wordRe(".*.H", wordRe::DETECT).match(name))
{
foundName = true;
}
else
{
// not interested in this compound
break;
}
}
else if (entryName == "path")
{
getValue<fileName>(is, path);
// filter path on regExp
if (wordRe(searchStr, wordRe::DETECT).match(path))
{
foundPath = true;
}
else
{
// not interested in this compound
break;
}
}
else if (entryName == "filename")
{
getValue<word>(is, fName);
foundFName = true;
}
else
{
skipBlock(is, entryName);
}
}
if (foundPath && !earlyExit)
{
word tName(path.components().last());
// only insert if type is not already known
// NOTE: not ideal for cases where there are multiple types
// but contained within different namespaces
// preferentially take exact match if it exists
if (exactMatch && (tName + ".H") == name)
{
dictionary dict(dictionary::null);
dict.add("name", name);
dict.add("filename", fName + ".html");
dict.add("path", path);
this->add(tName, dict);
}
else if
(
!exactMatch
&& !found(tName)
&& wordRe(".*" + tName + ".*", wordRe::DETECT).match(name)
)
{
dictionary dict(dictionary::null);
dict.add("name", name);
dict.add("filename", fName + ".html");
dict.add("path", path);
this->add(tName, dict);
}
}
// skip remanining entries
skipBlock(is, blockName);
}
else
{
skipBlock(is, blockName);
}
}
}
}
// * * * * * * * * * * * * * * * Member Functions * * * * * * * * * * * * * //
void Foam::doxygenXmlParser::skipBlock(IFstream& is, const word blockName) const
{
// recurse to move forward in 'is' until come across </blockName>
string closeName = "";
// fast-forward until we reach a '<'
char c;
while (is.get(c) && c != '<')
{}
// check to see if this is a closing block
if (is.get(c) && c == '/')
{
while (is.get(c) && c != '>')
{
closeName += c;
}
if (closeName == blockName)
{
// finished reading block
return;
}
else
{
skipBlock(is, blockName);
}
}
else
{
skipBlock(is, blockName);
}
}
void Foam::doxygenXmlParser::skipForward(IFstream& is, const word blockName) const
{
// recurse to move forward in 'is' until come across <blockName>
// fast-forward until we reach a '<'
char c;
while (is.get(c) && c != '<')
{}
string entryName = "";
while (is.get(c) && c != '>')
{
entryName = entryName + c;
}
if (entryName == blockName)
{
return;
}
else
{
skipForward(is, blockName);
}
}
// ************************************************************************* //

View File

@ -0,0 +1,97 @@
/*---------------------------------------------------------------------------*\
========= |
\\ / F ield | OpenFOAM: The Open Source CFD Toolbox
\\ / O peration |
\\ / A nd | Copyright (C) 2012 OpenCFD Ltd.
\\/ M anipulation |
-------------------------------------------------------------------------------
License
This file is part of OpenFOAM.
OpenFOAM is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
Class
Foam::doxygenXmlParser
Description
SourceFiles
\*---------------------------------------------------------------------------*/
#ifndef doxygenXmlParser_H
#define doxygenXmlParser_H
#include "dictionary.H"
#include "IFstream.H"
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
namespace Foam
{
/*---------------------------------------------------------------------------*\
Class doxygenXmlParser Declaration
\*---------------------------------------------------------------------------*/
class doxygenXmlParser
:
public dictionary
{
public:
//- Construct from components
doxygenXmlParser
(
const fileName& fName,
const string& startTag,
const string& searchStr,
const bool exactMatch
);
// Member functions
//- Skip past a block
void skipBlock(IFstream& is, const word blockName) const;
//- Skip forward to block
void skipForward(IFstream& is, const word blockName) const;
//- Return the entry
template<class Type>
void getEntry(IFstream& is, Type& entry) const;
//- Return the entry value
template<class Type>
void getValue(IFstream& is, Type& entry) const;
};
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
} // End namespace Foam
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
#ifdef NoRepository
#include "doxygenXmlParserTemplates.C"
#endif
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
#endif
// ************************************************************************* //

View File

@ -0,0 +1,67 @@
/*---------------------------------------------------------------------------*\
========= |
\\ / F ield | OpenFOAM: The Open Source CFD Toolbox
\\ / O peration |
\\ / A nd | Copyright (C) 2012 OpenCFD Ltd.
\\/ M anipulation |
-------------------------------------------------------------------------------
License
This file is part of OpenFOAM.
OpenFOAM is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
\*---------------------------------------------------------------------------*/
#include "doxygenXmlParser.H"
// * * * * * * * * * * * * * * * Member Functions * * * * * * * * * * * * * //
template<class Type>
void Foam::doxygenXmlParser::getEntry(IFstream& is, Type& entry) const
{
char c;
while (is.get(c) && c != '<')
{}
entry = "";
if (is.get(c) && c == '/')
{
return;
}
else
{
entry = entry + c;
}
while (is.get(c) && c != '>')
{
entry = entry + c;
}
}
template<class Type>
void Foam::doxygenXmlParser::getValue(IFstream& is, Type& entry) const
{
char c;
entry = "";
while (is.get(c) && c != '<')
{
entry = entry + c;
}
}
// ************************************************************************* //

View File

@ -0,0 +1,148 @@
/*---------------------------------------------------------------------------*\
========= |
\\ / F ield | OpenFOAM: The Open Source CFD Toolbox
\\ / O peration |
\\ / A nd | Copyright (C) 2012 OpenCFD Ltd.
\\/ M anipulation |
-------------------------------------------------------------------------------
License
This file is part of OpenFOAM.
OpenFOAM is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
\*---------------------------------------------------------------------------*/
#include "helpType.H"
#include "doxygenXmlParser.H"
#include "SortableList.H"
// * * * * * * * * * * * * * * Static Data Members * * * * * * * * * * * * * //
namespace Foam
{
defineTypeNameAndDebug(helpType, 0);
defineRunTimeSelectionTable(helpType, dictionary);
}
// * * * * * * * * * * * * Protected Member Functions * * * * * * * * * * * //
void Foam::helpType::displayDoc
(
const word& className,
const string& searchStr,
const bool exactMatch
) const
{
const dictionary& docDict = debug::controlDict().subDict("Documentation");
List<fileName> docDirs(docDict.lookup("doxyDocDirs"));
label i = -1;
forAll(docDirs, dirI)
{
if (isDir(docDirs[dirI].expand()))
{
i = dirI;
break;
}
}
if (i != -1)
{
Info<< "Found doxygen help in " << docDirs[i].c_str() << nl << endl;
string docBrowser = getEnv("FOAM_DOC_BROWSER");
if (docBrowser.empty())
{
docDict.lookup("docBrowser") >> docBrowser;
}
doxygenXmlParser parser
(
docDirs[i]/"../DTAGS",
"tagfile",
searchStr,
exactMatch
);
if (debug)
{
Info<< parser;
}
if (parser.found(className))
{
fileName docFile
(
docDirs[i]/parser.subDict(className).lookup("filename")
);
// can use FOAM_DOC_BROWSER='application file://%f' if required
docBrowser.replaceAll("%f", docFile);
fileName classFolder(parser.subDict(className).lookup("path"));
word classFile(parser.subDict(className).lookup("name"));
Info<< "Showing documentation for type " << className << nl << endl;
Info<< "Source file: " << classFolder.c_str() << classFile << nl
<< endl;
system(docBrowser);
}
else
{
FatalErrorIn
(
"void Foam::helpType::displayDoc(const word, const string)"
)
<< "No help for type " << className << " found."
<< " Valid options include:"
<< SortableList<word>(parser.toc())
<< exit(FatalError);
}
}
else
{
Info<< "No Doxygen sources found under search paths: "
<< docDirs << endl;
}
}
// * * * * * * * * * * * * * * * * Constructors * * * * * * * * * * * * * * //
Foam::helpType::helpType()
{}
// * * * * * * * * * * * * * * * * Destructor * * * * * * * * * * * * * * * //
Foam::helpType::~helpType()
{}
// * * * * * * * * * * * * * * * Member Functions * * * * * * * * * * * * * //
void Foam::helpType::init()
{
argList::addOption
(
"browse",
"word",
"display documentation for boundary condition in browser"
);
}
// ************************************************************************* //

View File

@ -0,0 +1,115 @@
/*---------------------------------------------------------------------------*\
========= |
\\ / F ield | OpenFOAM: The Open Source CFD Toolbox
\\ / O peration |
\\ / A nd | Copyright (C) 2012 OpenCFD Ltd.
\\/ M anipulation |
-------------------------------------------------------------------------------
License
This file is part of OpenFOAM.
OpenFOAM is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
Class
Foam::helpType
Description
Base class for foam help classes
SourceFiles
helpType.C
helpTypeNew.C
\*---------------------------------------------------------------------------*/
#ifndef helpType_H
#define helpType_H
#include "runTimeSelectionTables.H"
#include "autoPtr.H"
#include "argList.H"
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
namespace Foam
{
// forward declaration of classes
class fvMesh;
/*---------------------------------------------------------------------------*\
Class helpType Declaration
\*---------------------------------------------------------------------------*/
class helpType
{
protected:
//- Display the help documentation in a browser
void displayDoc
(
const word& className,
const string& searchStr,
const bool exactMatch
) const;
public:
//- Runtime type information
TypeName("helpType");
// Declare runtime constructor selection table
declareRunTimeSelectionTable
(
autoPtr,
helpType,
dictionary,
(),
()
);
//- Constructor
helpType();
//- Selector
static autoPtr<helpType> New(const word& helpTypeName);
//- Destructor
virtual ~helpType();
// Member Functions
//- Initialise - typically setting static variables,
// e.g. command line arguments
virtual void init();
//- Execute the help
virtual void execute(const argList& args, const fvMesh& mesh) = 0;
};
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
} // End namespace Foam
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
#endif
// ************************************************************************* //

View File

@ -0,0 +1,65 @@
/*---------------------------------------------------------------------------*\
========= |
\\ / F ield | OpenFOAM: The Open Source CFD Toolbox
\\ / O peration |
\\ / A nd | Copyright (C) 2012 OpenCFD Ltd.
\\/ M anipulation |
-------------------------------------------------------------------------------
License
This file is part of OpenFOAM.
OpenFOAM is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
\*---------------------------------------------------------------------------*/
#include "helpType.H"
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
Foam::autoPtr<Foam::helpType> Foam::helpType::New
(
const word& helpTypeName
)
{
Info<< "Selecting helpType " << helpTypeName << endl;
dictionaryConstructorTable::iterator cstrIter =
dictionaryConstructorTablePtr_->find(helpTypeName);
if (cstrIter == dictionaryConstructorTablePtr_->end())
{
// special treatment for -help
// exit without stack trace
if (helpTypeName == "-help")
{
FatalErrorIn("helpType::New()")
<< "Valid helpType selections are:" << nl
<< dictionaryConstructorTablePtr_->sortedToc() << nl
<< exit(FatalError);
}
else
{
FatalErrorIn("helpType::New()")
<< "Unknown helpType type " << helpTypeName << nl
<< "Valid helpType selections are:" << nl
<< dictionaryConstructorTablePtr_->sortedToc() << nl
<< abort(FatalError);
}
}
return autoPtr<helpType>(cstrIter()());
}
// ************************************************************************* //