Declaration of the classes used to define an XML Schema. More...

#include <utility/tag/XMLSchemaGeneration.fwd.hh>
#include <utility/VirtualBase.hh>
#include <utility/type_traits/is_string_constructible.hh>
#include <utility/excn/Exceptions.hh>
#include <functional>
#include <list>
#include <map>
#include <iosfwd>

Classes
class	utility::tag::XMLSchemaType
	class XMLSchemaType represents the name of a defined type that can be used to describe either an XMLElement or an XMLAttribute. It may refer to either a complex type or to a primative type or to a simple type. More...

class	utility::tag::XMLSchemaTopLevelElement
	The XMLSchemaTopLevelElement class signifies a class that could be written out as an XML element, with possible sub-elemets, in an XML schema. When generating a schema, the developer will hand an instance of a class derived from an XMLSchemaTopLevelElement to an XMLSchemaDefinition object. More...

class	utility::tag::XMLSchemaAttribute
	class XMLSchemaAttribute represents what we refer to in Rosetta as an option for a tag. An attribute would reside inside of a tag, such as "scorefxn" in this tag (this XML Element): <MinMover name="min" scorefxn="talaris2014"> More...

class	utility::tag::XMLSchemaRestriction
	class XMLSchemaRestriction describes a refinement on the behavior of existing types. For example, one could define a restriction representing a list of residue indexes separating commas: "15,44,102" and then describe an attribute of a complex type as having to conform to that restriction. An xml-schema validator would be able to say that an input file with "fifteen,fortyfour,onehundredandtwo" did not meet the schema. More...

class	utility::tag::XMLSchemaParticle
	This abstract class is meant to represent either an XMLSChemaElement or an XMLSchemaModelGroup so that the interchangable set of these objects in a ModelGroup can be represented. I may be misusing the term "particle" in the way that it is meant within XML Schema – so the mapping of this term to the term used in XML Schema is probably imperfect. More...

class	utility::tag::XMLSchemaModelGroup
	The ModelGroup covers four XML Schema model groups: xs:sequence, xs:choice, xs:all, and xs:group. A ModelGroup may contain any number of XMLSchemaParticles, interchanging between XMLElements and XMLModelGroups, BUT there are some fairly heavy restrictions on the xs:all model group, marginally enforced by this class and by XMLSchemaComplexType. This class is not exactly a top-level element, in that only xs:group is allowed to appear at the top level, but it is definitely worthwhile for this class to implement the write_definition funciton. More...

class	utility::tag::XMLSchemaComplexType
	class XMLSchemaComplexType represents the definition of the type for an element – that is, the structure of a set of elements with the same name. If an XMLSchemaElement is analogous to a utility::tag::Tag, an XMLSchemaComplexType is analogous to the wiki page describing the valid format for an instance of that Tag. More...

class	utility::tag::XMLSchemaElement
	An XMLSchema element, e.g. the FixbbMover "tag" <FixbbMover name="fixbb" task_operations="ex1,ex2"> or the And element which contains a sub-element: <And><Chain id="A"></And>. An element can be defined with an unnamed complex type in-line, or it can say that its type is that of a complex type defined elsewhere. (In XML naming a tag is a single block beginning with "<" and ending with ">", so both "<And>" and "</And>" are tags. The block between the opening and closing tags is called an element. The utility::tag::Tag class represents a complete Element, and not simply the opening or closing tag of an element. This is certainly confusing. More...

class	utility::tag::XMLSchemaDefinition
	The XMLSchemaDefinition class's purpose is to collect all of the elements that go into an XML Schema, to filter out the elements that are repeated (e.g. a restriction such as the "int_cslist" given in the description for XMLSchemaRestriction above may be reported twice to the XMLSchemaDefinition by several attributes that rely upon it), to detect non-identical duplicates that have the same name, and to write out the elements that it has been handed into a single string. The XMLSchemaDefinition is intended to be passed between static functions / non-class-member functions as a container for the XML Schema representations that these functions define. Such functions will always take an XMLSchemaDefinition reference as one of their input parameters. It is perfectly legitimate / recommended for one XML-schema-defining function that relies on a complexType or restriction that it does not itself define to pass its input XMLSchemaDefinition to the function that does define that complexType or restriction. More...

class	utility::tag::XMLSchemaSimpleSubelementList
	The XMLSchemaSimpleSubelementList class defines an interface that can be used by those wishing to define a complexType that contains sub-elements. The structure of the XML Schema for the sub-elements will determined by how this list is given to the XMLSchemaComplexTypeGenerator. "simple" subelements are those which themselves contain no subelements (but may contain attributes). Also allowed are subelements that refer to previously-defined complexTypes or those that refer to previously defined xs:groups. More...

struct	utility::tag::XMLSchemaSimpleSubelementList::ElementSummary

class	utility::tag::XMLSchemaComplexTypeGenerator
	The XMLComplexTypeSchemaGenerator is used to define the schema for a complex type as they typically occurr in Rosetta. More...

class	utility::tag::XMLSchemaRepeatableCTNode

Namespaces
	utility
	unresizable vector whose size is known at compile time, which may be allocated on the stack, and which indexes from 0.

	utility::tag

Enumerations
enum	utility::tag::XMLSchemaCommonType { utility::tag::xsct_none , utility::tag::xsct_int_cslist , utility::tag::xsct_string_cslist , utility::tag::xsct_int_wsslist , utility::tag::xsct_nnegative_int_cslist , utility::tag::xsct_nnegative_int_wsslist , utility::tag::xsct_real , utility::tag::xsct_real_cslist , utility::tag::xsct_real_cslist_w_ws , utility::tag::xsct_real_wsslist , utility::tag::xsct_bool_cslist , utility::tag::xsct_bool_wsslist , utility::tag::xsct_positive_integer_cslist , utility::tag::xsct_positive_integer_wsslist , utility::tag::xsct_non_negative_integer , utility::tag::xsct_positive_integer , utility::tag::xsct_rosetta_bool , utility::tag::xsct_rosetta_autobool , utility::tag::xsct_residue_number , utility::tag::xsct_residue_number_cslist , utility::tag::xsct_refpose_enabled_residue_number , utility::tag::xsct_refpose_enabled_residue_number_cslist , utility::tag::xsct_char , utility::tag::xsct_minimizer_type , utility::tag::xsct_size_cs_pair , utility::tag::xsct_chain_cslist , utility::tag::xsct_dssp_string , utility::tag::xsct_canonical_res_char , utility::tag::xsct_packer_palette , utility::tag::xsct_task_operation , utility::tag::xsct_task_operation_comma_separated_list , utility::tag::xsct_pose_cached_task_operation }
	An enum listing lots of commonly-used simple types so they don't have to be added manually in lots of places. If you create an XMLSchemaType using this enum, then the corresponding restriction will be added to the XMLSchemaDefintion automatically. More...

Functions
char	utility::tag::string_contains_gt_lt_or_ampersand (std::string const &s)
	Check if given string contain any of '<>&' and if so return found character. If no character is found return 0. More...

std::string	utility::tag::residue_number_string ()

std::string	utility::tag::real_regex_pattern ()

std::string	utility::tag::refpose_enabled_residue_number_string ()

std::string	utility::tag::name_for_common_type (XMLSchemaCommonType common_type)

std::ostream &	utility::tag::operator<< (std::ostream &os, XMLSchemaCommonType common_type)

std::string	utility::tag::chr_chains_nonrepeated ()

AttributeList &	utility::tag::operator+ (AttributeList &attributes, XMLSchemaAttribute const &attribute_to_append)

void	utility::tag::indent_w_spaces (int indentation, std::ostream &os)

std::string	utility::tag::restriction_type_name (XMLSchemaRestrictionType type)

std::ostream &	utility::tag::operator<< (std::ostream &os, XMLSchemaRestrictionType type)

std::string	utility::tag::xs_model_group_name (XMLSchemaModelGroupType xsmgt)

std::ostream &	utility::tag::operator<< (std::ostream &os, XMLSchemaModelGroupType type)

XMLSchemaRestriction	utility::tag::integer_range_restriction (std::string const &name, int lower_inclusive, int upper_inclusive)
	Convenience function for defining an inclusive range restriction. More...

XMLSchemaAttribute	utility::tag::optional_name_attribute (std::string const &description="")
	This function creates an attribute named "name" of type xs_string that is optional; naming is not always required – it is not even mostly required. This is probably the function you need; very few classes actually need to have a name – the name is often only used by the function reading in the name, but there are reasonable times when a Mover, e.g. could go nameless – for instance, in the fixbb_jd3 application, a PackRotamersMover can be given as a subtag of the <Job> tag. In this case, the PackRotamersMover doesn't need to be given a name. More...

XMLSchemaAttribute	utility::tag::required_name_attribute (std::string const &description="")
	This function creates an attribute named "name" of type xs_string that is required; naming is not always required – it is not even mostly required. This function is probably not what you need. Use with care. See comments for the "optional_name_attribute" function above. More...

void	utility::tag::append_name_and_attributes_to_complex_type (AttributeList const &attributes, XMLSchemaComplexType &type_definition)
	append an attribute of "name" with type "xs:string" along with the other attributes in the input attribute list to the input complex type. More...

void	utility::tag::append_required_name_and_attributes_to_complex_type (AttributeList const &attributes, XMLSchemaComplexType &type_definition)
	append a required attribute of "name" with type "xs:string" along with the other attributes in the input attribute list to the input complex type. More...

bool	utility::tag::attribute_w_name_in_attribute_list (std::string const &attname, AttributeList const &attlist)
	check whether an attribute with name attname already exists in AttributeList attlist to avoid collisions More...

Detailed Description

Declaration of the classes used to define an XML Schema.

A Brief Overview of XML Schema and how it will be used in Rosetta:

XML Schema describes the structure of an XML file. The objects that appear in the angle-brackets are called "Elements", e.g.

is an element. (aka "Tags" in Rosetta speak). The structure of the elements can be described by types and these types can be user defined, e.g. the two elements:

<MinMover name="minmover1" scorefxn="talaris2014"/>, and

could both be described as two instances that have the same type. At least the way that they are used in rosetta, element types almost universally fall into the XML Schema category of "complex types." Complex types can contain "attributes" (e.g. the "name" and "scorefxn" attributes, ) and they can also contain sub-elements organized into blocks of "model groups" (sequence, choice, all & group). Attributes (aka "options" in Rosetta speak) are usually described by simple types, and XML Schema defines many of them by default, (e.g. "string" and "integer" types); they can also be described by "restrictions" to existing types, e.g. you could define a type that is a string composed of integers separated by commas (e.g. "1,34,42").

In a picture:

/// XMLSchemaElement --> XMLSchemaComplexType --> XMLSchemaAttribute --> XMLSchemaType --> Primative Type
///                 \--> XMLSchemaType       \--> XMLSchemaModelGroup                  \--> Restriction --> Primative Type
///                                                         \----> XMLSchemaElement
///                                                          \---> XMLSchemaModelGroup
///

The chunk of XMLSchema that would describe the MinMover element above would
look like this: (If you thought XML was verbose, you will be overwhemed by
XML Schema!)

\verbatim

/// <xs:complexType name="MinMoverType" mixed="True"> /// <xs:attribute name="name" type="xs:string"/> /// <xs:attribute name="scorefxn" type="xs:string"/> /// </xs:complexType> /// /// <xs:element name="MinMover" type="MinMoverType"/> ///

In a XMLSchema, you can define restrictions and complex types as free standing
blocks, and these blocks can be given in any order.  Somewhere in the XMLSchema,
there needs to be a free-standing XML schema element, and this element will be
interpretted as the root of a tree so that an "order" can be discerned from what
is otherwise a jumble of types.

The way I envision schemas being defined in Rosetta is that an "XMLSchemaDefinition"
object is passed around between static methods of classes that are seeking to define
the grammar of their definitions, and other non-member utility functions (e.g. one that
defines the comma-separated-integer-list XMLRestriction), and that perhaps these utility
functions are called multiple times (with the XMLSchemaDefinition ignoring duplicate
definitions). After every class has described the structure of its organization, the
XMLSchemaDefinition can be written to a file.  Ideally, the construction of an XML schema
will not require the instantiation of any of the classes described in the XSD; e.g.
to describe the schema of the MinMover, the MoverFactory will ask the MinMoverCreator
for its XSD, which will defer to a static method of the MinMover. There would be no
need to actually instantiate a MinMover in this process.

One note about the way we use XML in rosetta:
When most people use XML, they embed information between two tags, e.g.
\code{.xml}
<FirstName> Andrew </FirstName>
\endcode
and we instead embed all our information as attributes (aka options) within
a single tag, e.g.
\code{.xml}
<FirstName value="Andrew"/>
\endcode
So our XML is a little funny. Instead of storing data between two tags, we ignore
everything outside of a tag.  This is allowed in XML, and so we can still used
XML Schema to describe our XML files.  In order to do so, we have to use the
feature of describing complex types where we describe the tags as "mixed". See

http://www.w3schools.com/xml/schema_complex_mixed.asp

The XMLSchemaComplexType implemented here describes all complex types as mixed;
this may not be appropriate for non-Rosetta XML.

@author Andrew Leaver-Fay (aleaverfay@gmail.com)
@author Vikram K. Mulligan (vmullig@uw.edu) -- Added human-readable XML schema output.
@author Sergey Lyskov, optimization

Classes

Namespaces

Enumerations

Functions

Detailed Description