1    :  // Copyright 2013 Google Inc. All Rights Reserved.
   2    :  //
   3    :  // Licensed under the Apache License, Version 2.0 (the "License");
   4    :  // you may not use this file except in compliance with the License.
   5    :  // You may obtain a copy of the License at
   6    :  //
   7    :  //     http://www.apache.org/licenses/LICENSE-2.0
   8    :  //
   9    :  // Unless required by applicable law or agreed to in writing, software
  10    :  // distributed under the License is distributed on an "AS IS" BASIS,
  11    :  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    :  // See the License for the specific language governing permissions and
  13    :  // limitations under the License.
  14    :  //
  15    :  // Defines utilities for handling dictionaries of variables and performing
  16    :  // variable expansion. JSON values are used for storage as this is intended
  17    :  // for handling variables in JSON configuration files.
  18    :  
  19    :  #ifndef SYZYGY_PEHACKER_VARIABLES_H_
  20    :  #define SYZYGY_PEHACKER_VARIABLES_H_
  21    :  
  22    :  #include "base/values.h"
  23    :  
  24  m :  namespace pehacker {
  25    :  
  26    :  // Determines if a variable name is valid. Names must be alpha-numeric, and may
  27    :  // also contain the _ character.
  28    :  // @param name The name to evaluate.
  29    :  // @returns true if the given variable name is valid.
  30  m :  bool VariableNameIsValid(const std::string& name);
  31    :  
  32    :  // Converts a variable to a string. This logs an error on failure.
  33    :  // @param value The value to be converted.
  34    :  // @param s The string to be populated.
  35    :  // @returns true on success, false otherwise.
  36  m :  bool ConvertVariableToString(const base::Value& value, std::string* s);
  37    :  
  38    :  // Converts a variable to a JSON-parseable representation of it. This logs an
  39    :  // error on failure.
  40    :  // @param value The value to be converted.
  41    :  // @param s The string to be populated.
  42    :  // @returns true on success, false otherwise.
  43  m :  bool ConvertVariableToJson(const base::Value& value, std::string* s);
  44    :  
  45    :  // Parses a variable, updating a dictionary of variables with its value. This
  46    :  // handles variable directives suffixed to the name of the variable. This logs
  47    :  // an error on failure.
  48    :  //
  49    :  // Variable directive suffixes:
  50    :  //
  51    :  //   %: Default value. If the value doesn't exist in the dictionary, set it with
  52    :  //      the provided value. If it does already exist, ignore the value being
  53    :  //      parsed and keep the existing value.
  54    :  //
  55    :  // @param name The name of the variable.
  56    :  // @param value The parsed value of the variable.
  57    :  // @param value_string The unparsed value of the variable. This will be parsed
  58    :  //     as a JSON encoded string. If that fails, it will be treated as a raw
  59    :  //     string.
  60    :  // @param dict The dictionary in which the variable will be stored.
  61    :  // @returns true on success, false otherwise.
  62  m :  bool ParseVariable(const std::string& name,
  63  m :                     const base::Value& value,
  64  m :                     base::DictionaryValue* dict);
  65  m :  bool ParseVariable(const std::string& name,
  66  m :                     const std::string& value_string,
  67  m :                     base::DictionaryValue* dict);
  68    :  
  69    :  // Merges two dictionaries of variables. The variables names of the source
  70    :  // dictionary will be parsed for variable directives (ie: % for default) value
  71    :  // and handled appropriately. This logs an error on failure.
  72    :  // @param src The source dictionary. Keys in this dictionary may be suffixed
  73    :  //     with variable directives.
  74    :  // @param dst The destination dictionary. Already existing keys in this
  75    :  //     dictionary must not have suffixes, and new keys added will be stripped of
  76    :  //     any suffixes.
  77    :  // @returns true on success, false otherwise.
  78  m :  bool MergeVariables(const base::DictionaryValue& src,
  79  m :                      base::DictionaryValue* dst);
  80    :  
  81    :  // Expands a value using the given dictionary of variables. This logs an error
  82    :  // on failure.
  83    :  // @param variables The variables to use in expansion.
  84    :  // @param value The value to be expanded.
  85    :  // @param expanded The string to be populated with the expanded value. This may
  86    :  //     refer to the same string as |value| for in-place expansion.
  87    :  // @returns true on success, false otherwise.
  88  m :  bool ExpandVariables(const base::DictionaryValue& variables,
  89  m :                       const std::string& value,
  90  m :                       std::string* expanded);
  91    :  
  92  m :  }  // namespace pehacker
  93    :  
  94    :  #endif  // SYZYGY_PEHACKER_VARIABLES_H_