From 61cb697bf097609bff0bdde5bfee5da0f985a0d6 Mon Sep 17 00:00:00 2001
From: Adam Wardynski <award@.(win7-laptop)>
Date: Mon, 9 May 2011 13:15:19 +0200
Subject: [PATCH] Moar comments for WcclFile.
---
libwccl/wcclfile.h | 245 +++++++++++++++++++++++++++++++++++++++------
1 file changed, 217 insertions(+), 28 deletions(-)
diff --git a/libwccl/wcclfile.h b/libwccl/wcclfile.h
index a3c4e4c..e012b58 100644
--- a/libwccl/wcclfile.h
+++ b/libwccl/wcclfile.h
@@ -32,104 +32,274 @@ class WcclFile
public:
WcclFile(const Corpus2::Tagset& tagset, const std::string& search_path);
- //
+ /////////////////////
// Untyped and typed operator sections: @X:"sectioname" ( op1; op2 )
- //
+ /////////////////////
+
+ /**
+ * @returns All untyped sections from the WCCL file: @"name" ( anyop0; ...; anyopN )
+ */
const std::vector<boost::shared_ptr<UntypedOpSequence> >& untyped_sections();
+ /**
+ * @returns All sections of given type T from the WCCL file: @T:"name" ( op<T>0; ...; op<T>N )
+ */
template<class T>
const typename std::vector<boost::shared_ptr<OpSequence<T> > >& sections();
+ /**
+ * @returns True if the WCCL file contains untyped section of given name.
+ * False otherwise.
+ */
bool has_untyped_section(const std::string& name) const;
+ /**
+ * @returns True if the WCCL file contains section of given name and type T.
+ * False otherwise.
+ */
template<class T>
bool has_section(const std::string& name) const;
+ /**
+ * @returns Names of all untyped sections in this WCCL file, in the order they
+ * were found in the file.
+ */
std::vector<std::string> untyped_section_names() const;
+ /**
+ * @returns Names of all sections of given type T from this WCCL file, in the
+ * order they were found in the file.
+ */
template<class T>
std::vector<std::string> section_names() const;
+ /**
+ * @returns Untyped section of given name.
+ * @throws InvalidArgument if there is no untyped section of given name.
+ */
UntypedOpSequence& get_untyped_section(const std::string& name);
+ /**
+ * @returns Untyped section of given name (const).
+ * @throws InvalidArgument if there is no untyped section of given name.
+ */
const UntypedOpSequence& get_untyped_section(const std::string& name) const;
+ /**
+ * @returns Section of given name and type T.
+ * @throws InvalidArgument if there is no section of given name and type T.
+ */
template<class T>
OpSequence<T>& get_section(const std::string& name);
+ /**
+ * @returns Section of given name and type T (const).
+ * @throws InvalidArgument if there is no section of given name and type T.
+ */
template<class T>
const OpSequence<T>& get_section(const std::string& name) const;
-
+ /**
+ * @returns Shared pointer to an untyped section of the given name.
+ * @throws InvalidArgument if there is no untyped section of given name.
+ */
boost::shared_ptr<UntypedOpSequence> get_untyped_section_ptr(const std::string& name);
+ /**
+ * @returns Shared pointer to an untyped section of the given name (const).
+ * @throws InvalidArgument if there is no untyped section of given name.
+ */
boost::shared_ptr<const UntypedOpSequence> get_untyped_section_ptr(const std::string& name) const;
+ /**
+ * @returns Shared pointer to a section of the given name and type T.
+ * @throws InvalidArgument if there is no section of given name and type T.
+ */
template<class T>
boost::shared_ptr<OpSequence<T> > get_section_ptr(const std::string& name);
+ /**
+ * @returns Shared pointer to a section of the given name and type T (const).
+ * @throws InvalidArgument if there is no section of given name and type T.
+ */
template<class T>
boost::shared_ptr<const OpSequence<T> > get_section_ptr(const std::string& name) const;
-
+ /**
+ * @returns Operator from an untyped section of given name, present at given index.
+ * @note Index is zero-based and default is 0 (no idx given = the first operator in the sequence).
+ * @throws InvalidArgument if there is no untyped section of given name or if idx is out of range.
+ */
FunctionalOperator& get_untyped_op(const std::string& name, size_t idx = 0);
+ /**
+ * @returns Operator from an untyped section of given name, present at given index (const).
+ * @note Index is zero-based and default is 0 (no idx given = the first operator in the sequence).
+ * @throws InvalidArgument if there is no untyped section of given name or if idx is out of range.
+ */
const FunctionalOperator& get_untyped_op(const std::string& name, size_t idx = 0) const;
+ /**
+ * @returns Operator from a section of given name and type T, present at given index.
+ * @note Index is zero-based and default is 0 (no idx given = the first operator in the sequence).
+ * @throws InvalidArgument if there is no section of given name and type T or if idx is out of range.
+ */
template<class T>
Operator<T>& get_op(const std::string& name, size_t idx = 0);
+ /**
+ * @returns Operator from a section of given name and type T, present at given index (const).
+ * @note Index is zero-based and default is 0 (no idx given = the first operator in the sequence).
+ * @throws InvalidArgument if there is no section of given name and type T or if idx is out of range.
+ */
template<class T>
const Operator<T>& get_op(const std::string& name, size_t idx = 0) const;
-
+ /**
+ * @returns Shared pointer to an operator from an untyped section of given name, present at given index.
+ * @note Index is zero-based and default is 0 (no idx given = the first operator in the sequence).
+ * @throws InvalidArgument if there is no untyped section of given name or if idx is out of range.
+ */
boost::shared_ptr<FunctionalOperator> get_untyped_op_ptr(const std::string& name, size_t idx = 0);
+ /**
+ * @returns Shared pointer to an operator from an untyped section of given name, present at given index (const).
+ * @note Index is zero-based and default is 0 (no idx given = the first operator in the sequence).
+ * @throws InvalidArgument if there is no untyped section of given name or if idx is out of range.
+ */
boost::shared_ptr<const FunctionalOperator> get_untyped_op_ptr(const std::string& name, size_t idx = 0) const;
+ /**
+ * @returns Shared pointer to an operator from a section of given name and type T, present at given index.
+ * @note Index is zero-based and default is 0 (no idx given = the first operator in the sequence).
+ * @throws InvalidArgument if there is no section of given name and type T, or if idx is out of range.
+ */
template<class T>
boost::shared_ptr<Operator<T> > get_op_ptr(const std::string& name, size_t idx = 0);
+ /**
+ * @returns Shared pointer to an operator from a section of given name and type T, present at given index (const).
+ * @note Index is zero-based and default is 0 (no idx given = the first operator in the sequence).
+ * @throws InvalidArgument if there is no section of given name and type T, or if idx is out of range.
+ */
template<class T>
boost::shared_ptr<const Operator<T> > get_op_ptr(const std::string& name, size_t idx = 0) const;
+ /**
+ * @returns Vector of all name-operator pairs from untyped sections, in the order they were found in the file.
+ * @note Generated names of operators are derived from section name they are contained within,
+ * suffixed with hyphen and zero-based index. E.g. the first operator in section named "seq"
+ * will have name "seq-0", second operator's name will be "seq-1" etc.
+ */
UntypedOpSequence::name_op_v_t gen_name_untyped_op_pairs();
+ /**
+ * @returns Vector of all name-operator pairs from untyped sections, in the order they were found in the file (const).
+ * @note Generated names of operators are derived from section name they are contained within,
+ * suffixed with hyphen and zero-based index. E.g. the first operator in section named "seq"
+ * will have name "seq-0", second operator's name will be "seq-1" etc.
+ */
UntypedOpSequence::name_op_v_c_t gen_name_untyped_op_pairs() const;
+ /**
+ * @returns Vector of all name-operator pairs from sections of given type T, in the order they were found in the file.
+ * @note Generated names of operators are derived from section name they are contained within,
+ * suffixed with hyphen and zero-based index. E.g. the first operator in section named "seq"
+ * will have name "seq-0", second operator's name will be "seq-1" etc.
+ */
template<class T>
typename OpSequence<T>::name_op_v_t gen_name_op_pairs();
+ /**
+ * @returns Vector of all name-operator pairs from sections of given type T, in the order they were found in the file (const).
+ * @note Generated names of operators are derived from section name they are contained within,
+ * suffixed with hyphen and zero-based index. E.g. the first operator in section named "seq"
+ * will have name "seq-0", second operator's name will be "seq-1" etc.
+ */
template<class T>
typename OpSequence<T>::name_op_v_c_t gen_name_op_pairs() const;
+ /**
+ * @returns Vector of all name-operator pairs from all sections of the file (both typed and untyped),
+ * in the order they were found in the file.
+ * @note Generated names of operators are derived from section name they are contained within,
+ * suffixed with hyphen and zero-based index. E.g. the first operator in section named "seq"
+ * will have name "seq-0", second operator's name will be "seq-1" etc.
+ */
FunctionalOpSequence::name_op_v_t gen_all_op_pairs();
+ /**
+ * @returns Vector of all name-operator pairs from all sections of the file (both typed and untyped),
+ * in the order they were found in the file (const).
+ * @note Generated names of operators are derived from section name they are contained within,
+ * suffixed with hyphen and zero-based index. E.g. the first operator in section named "seq"
+ * will have name "seq-0", second operator's name will be "seq-1" etc.
+ */
FunctionalOpSequence::name_op_v_c_t gen_all_op_pairs() const;
- void add_untyped_section(const boost::shared_ptr<UntypedOpSequence>& section);
- void add_untyped_section(const boost::shared_ptr<const UntypedOpSequence>& section);
- void add_untyped_section(const UntypedOpSequence& section);
- template<class T>
- void add_section(const boost::shared_ptr<OpSequence<T> >& section);
- template<class T>
- void add_section(const boost::shared_ptr<const OpSequence<T> >& section);
- template<class T>
- void add_section(const OpSequence<T>& section);
-
- //
+
+ ///////////////////////////
// Lexicons, import sections: import("path", "name")
- //
- void import_lexicon(const boost::shared_ptr<Lexicon>& lexicon);
+ ///////////////////////////
+
+ /**
+ * @returns True if there is an imported Lexicon of given name. False otherwise.
+ */
bool has_lexicon(const std::string& name) const;
+ /**
+ * @returns True if there are any Lexicons imported.
+ */
bool has_lexicons() const;
+ /**
+ * @returns Shared pointer to a Lexicon of given name (const).
+ * @throws InvalidArgument if there is no Lexicon of given name imported.
+ */
boost::shared_ptr<const Lexicon> get_lexicon_ptr(const std::string& name) const;
+ /**
+ * @returns Lexicon of given name (const).
+ * @throws InvalidArgument if there is no Lexicon of given name imported.
+ */
const Lexicon& get_lexicon(const std::string& name) const;
+ /**
+ * @returns Shared pointer to collection of all imported Lexicons (const).
+ */
boost::shared_ptr<const Lexicons> get_lexicons_ptr() const;
+ /**
+ * @returns Collection of all imported Lexicons (const).
+ */
const Lexicons& get_lexicons() const;
-
- //
+
+ ///////////////////////////
// Tag rules section: tag_rules ( rule1; rule2 )
- //
- bool has_tag_rules() const;
+ ///////////////////////////
- void set_tag_rules(const boost::shared_ptr<TagRuleSequence>& tag_rules);
+ /**
+ * @returns True if this WcclFile has tag_rules section. False otherwise.
+ */
+ bool has_tag_rules() const;
+ /**
+ * @returns The tag rules section from this WCCL file.
+ * @throws WcclError if there is no tag rules section.
+ */
const TagRuleSequence& get_tag_rules() const;
+ /**
+ * @returns The tag rules section from this WCCL file.
+ * @throws WcclError if there is no tag rules section.
+ */
boost::shared_ptr<TagRuleSequence> get_tag_rules_ptr();
+ /**
+ * @returns The tag rules section from this WCCL file (const).
+ * @throws WcclError if there is no tag rules section.
+ */
boost::shared_ptr<const TagRuleSequence> get_tag_rules_ptr() const;
- //
+ ///////////////////////////
// Match rules section: match_rules ( apply1; apply2 )
- //
+ ///////////////////////////
+
+ /**
+ * @returns True if this WcclFile has match_rules section. False otherwise.
+ */
bool has_match_rules() const;
- void set_match_rules(const boost::shared_ptr<MatchRuleSequence>& match_rules);
+ /**
+ * @returns The match rules section from this WCCL file.
+ * @throws WcclError if there is no match_rules section.
+ */
const MatchRuleSequence& get_match_rules() const;
+ /**
+ * @returns The match rules section from this WCCL file.
+ * @throws WcclError if there is no match_rules section.
+ */
boost::shared_ptr<MatchRuleSequence> get_match_rules_ptr();
+ /**
+ * @returns The match rules section from this WCCL file (const).
+ * @throws WcclError if there is no match_rules section.
+ */
boost::shared_ptr<const MatchRuleSequence> get_match_rules_ptr() const;
- //
+ ///////////////////////////
// Miscelaneous
- //
+ ///////////////////////////
friend std::ostream& operator<<(std::ostream& ostream, const WcclFile& wccl_file);
std::string to_string() const;
@@ -137,6 +307,25 @@ public:
const PwrNlp::PathSearcher<Wccl::FileNotFound> path() const { return path_; }
PwrNlp::PathSearcher<Wccl::FileNotFound> path() { return path_; }
+ ///////////////////////////
+ // Internal parser-related methods to add sections.
+ ///////////////////////////
+ void add_untyped_section(const boost::shared_ptr<UntypedOpSequence>& section);
+ void add_untyped_section(const boost::shared_ptr<const UntypedOpSequence>& section);
+ void add_untyped_section(const UntypedOpSequence& section);
+ template<class T>
+ void add_section(const boost::shared_ptr<OpSequence<T> >& section);
+ template<class T>
+ void add_section(const boost::shared_ptr<const OpSequence<T> >& section);
+ template<class T>
+ void add_section(const OpSequence<T>& section);
+
+ void import_lexicon(const boost::shared_ptr<Lexicon>& lexicon);
+
+ void set_tag_rules(const boost::shared_ptr<TagRuleSequence>& tag_rules);
+
+ void set_match_rules(const boost::shared_ptr<MatchRuleSequence>& match_rules);
+
private:
std::ostream& write_to(std::ostream& ostream) const;
std::vector<boost::shared_ptr<FunctionalOpSequence> > all_sections_;
--
GitLab