3 * \file InsetCommandParams.h
4 * This file is part of LyX, the document processor.
5 * Licence details can be found in the file COPYING.
7 * \author Angus Leeming
11 * Full author contact details are available in file CREDITS.
14 #ifndef INSETCOMMANDPARAMS_H
15 #define INSETCOMMANDPARAMS_H
17 #include "InsetCode.h"
19 #include "support/docstring.h"
32 /// Types of parameters
33 /// WARNING: LATEX_KV_* `parameters' aren't really parameters at all
34 /// but merely markers for where the keyval-type parameters should
35 /// appear in the LaTeX output. ParamInfo::hasParam(name) therefore
36 /// returns FALSE if the corresponding `parameter' is of type
38 /// It is assumed here that there is exactly one argument that accepts
39 /// the key=value pairs.
41 LATEX_OPTIONAL, /// normal optional argument
42 LATEX_REQUIRED, /// normal required argument
43 LATEX_KV_OPTIONAL, /// optional argument that uses keyval
44 LATEX_KV_REQUIRED, /// required argument that uses keyval
45 LATEX_KEY, /// a key to be used with keyval argument
46 LYX_INTERNAL /// a parameter used internally by LyX
50 // No parameter may be named "preview", because that is a required
51 // flag for all commands.
54 ParamData(std::string const &, ParamType);
56 std::string name() const { return name_; }
58 ParamType type() const { return type_; }
59 /// whether this is a key for use with keyval
61 { return type_ == LATEX_KEY; }
62 /// whether this is an optional LaTeX argument
63 inline bool isOptional() const;
64 /// whether this is a keyval argument
65 inline bool isKeyValArg() const;
67 //presently unused but perhaps useful at some point
68 /// whether this is a required LaTeX argument
69 bool isRequired() const
70 { return type_ == ParamInfo::LATEX_REQUIRED ||
71 type_ == ParamInfo::LATEX_KV_REQUIRED; }
72 /// whether this is a LaTeX argument
73 inline bool isLaTeXArgument() const
74 { return isOptional() || isRequired(); }
77 bool operator==(ParamData const &) const;
79 bool operator!=(ParamData const & rhs) const
80 { return !(*this == rhs); }
88 /// adds a new parameter
89 void add(std::string const & name, ParamType type);
91 bool empty() const { return info_.empty(); }
93 size_t size() const { return info_.size(); }
95 typedef std::vector<ParamData>::const_iterator const_iterator;
97 const_iterator const begin() const { return info_.begin(); }
99 const_iterator const end() const { return info_.end(); }
100 /// \return true if name corresponds to a parameter of some sort.
101 /// \return false if the parameter does not exist at all of it it
102 /// corresponds to a `parameter' of type LATEX_KV_*; these do not
103 /// really represent parameters but just argument places.
104 bool hasParam(std::string const & name) const;
106 ParamData const & operator[](std::string const & name) const;
108 bool operator==(ParamInfo const &) const;
111 std::vector<ParamData> info_;
115 class InsetCommandParams {
117 /// Construct parameters for inset of type \p code.
118 explicit InsetCommandParams(InsetCode code);
119 /// Construct parameters for inset of type \p code with
120 /// command name \p cmdName.
121 explicit InsetCommandParams(InsetCode code,
122 std::string const & cmdName);
124 std::string insetType() const;
126 InsetCode code() const { return insetCode_; }
129 /// Parse the command
131 void write(std::ostream &) const;
132 /// Build the complete LaTeX command
133 docstring const getCommand() const;
134 /// Return the command name
135 std::string const & getCmdName() const { return cmdName_; }
136 /// Set the name to \p n. This must be a known name. All parameters
137 /// are cleared except those that exist also in the new command.
138 /// What matters here is the parameter name, not position.
139 void setCmdName(std::string const & n);
140 /// FIXME Would be better removed, but is used in BufferView.cpp in
141 /// ways that make removal hard.
142 docstring const getFirstNonOptParam() const;
143 /// get parameter \p name
144 /// WARNING: You cannot access LATEX_KV_* arguments in this way.
145 /// LyX will assert if you attempt to do so.
146 docstring const & operator[](std::string const & name) const;
147 /// set parameter \p name
148 /// WARNING: You cannot access LATEX_KV_* arguments in this way.
149 /// LyX will assert if you attempt to do so.
150 docstring & operator[](std::string const & name);
152 bool preview() const { return preview_; }
154 void preview(bool p) { preview_ = p; }
155 /// Clear the values of all parameters
158 static bool isCompatibleCommand(InsetCode code, std::string const & s);
162 /// Get information for inset type \p code.
163 /// Returns 0 if the inset is not known.
164 static ParamInfo const & findInfo(InsetCode code);
165 /// Get information for \p code and command \p cmdName.
166 /// Returns 0 if the combination is not known.
167 /// Don't call this without first making sure the command name is
168 /// acceptable to the inset.
169 static ParamInfo const & findInfo(InsetCode code,
170 std::string const & cmdName);
172 std::string getDefaultCmd(InsetCode);
174 docstring makeKeyValArgument() const;
175 /// checks whether we need to write an empty optional parameter
176 /// \return true if a non-empty optional parameter follows ci
177 bool writeEmptyOptional(ParamInfo::const_iterator ci) const;
178 /// Description of all command properties
180 /// what kind of inset we're the parameters for
181 InsetCode insetCode_;
182 /// The name of this command as it appears in .lyx and .tex files
183 std::string cmdName_;
185 // if we need to allow more than one value for a parameter, this
186 // could be made a multimap. it may be that the only thing that
187 // would then need changing is operator[].
188 typedef std::map<std::string, docstring> ParamMap;
189 /// The parameters, by name.
194 friend bool operator==(InsetCommandParams const &,
195 InsetCommandParams const &);
199 bool operator==(InsetCommandParams const &, InsetCommandParams const &);
201 bool operator!=(InsetCommandParams const &, InsetCommandParams const &);