[Forensics-changes] [yara] 36/407: Update documentation

[Hilko Bengen]

This is an automated email from the git hooks/post-receive script.

bengen pushed a commit to annotated tag v3.3.0
in repository yara.

commit 97ea49c66c3b57cc99a5045e4f17e620abcce0d0
Author: Victor Manuel Alvarez <vmalvarez at virustotal.com>
Date:   Tue Sep 16 15:00:55 2014 +0200

    Update documentation
---
 docs/modules/pe.rst     | 40 +++++++++++++++++++++++++++++++++++++
 docs/writingmodules.rst | 52 +++++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 84 insertions(+), 8 deletions(-)

diff --git a/docs/modules/pe.rst b/docs/modules/pe.rst
index 99a8060..6d864a7 100644
--- a/docs/modules/pe.rst
+++ b/docs/modules/pe.rst
@@ -181,6 +181,27 @@ Reference
 
     *Example:  pe.sections[0].name == ".text"*
 
+.. c:type:: version_info
+
+    Dictionary containing PE's version information. Typical keys are:
+
+        ``Comments``
+        ``CompanyName``
+        ``FileDescription``
+        ``FileVersion``
+        ``InternalName``
+        ``LegalCopyright``
+        ``LegalTrademarks``
+        ``OriginalFilename``
+        ``ProductName``
+        ``ProductVersion``
+
+    For more information refer to:
+
+    http://msdn.microsoft.com/en-us/library/windows/desktop/ms646987(v=vs.85).aspx
+
+    *Example:  pe.version_info["CompanyName"] contains "Microsoft"*
+
 .. c:function:: exports(function_name)
 
     Function returning true if the PE exports *function_name* or
@@ -194,3 +215,22 @@ Reference
     or false otherwise. *dll_name* is case insensitive.
 
     *Example:  pe.imports("kernel32.dll", "WriteProcessMemory")*
+
+.. c:function:: locale(locale_identifier)
+
+    Function returning true if the PE has a resource with the specified locale
+    identifier. Locale identifiers are 16-bit integers and can be found here:
+
+    http://msdn.microsoft.com/en-us/library/windows/desktop/dd318693(v=vs.85).aspx
+
+    *Example: pe.locale(0x0419) // Russian (RU)*
+
+.. c:function:: language(language_identifier)
+
+    Function returning true if the PE has a resource with the specified language
+    identifier. Language identifiers are 8-bit integers and can be found here:
+
+    http://msdn.microsoft.com/en-us/library/windows/desktop/dd318693(v=vs.85).aspx
+
+    *Example: pe.language(0x0A) // Spanish*
+
diff --git a/docs/writingmodules.rst b/docs/writingmodules.rst
index 29289d3..85b139b 100644
--- a/docs/writingmodules.rst
+++ b/docs/writingmodules.rst
@@ -362,6 +362,32 @@ Arrays are zero-based and don't have a fixed size, they will grow as needed
 when you start initializing its values.
 
 
+Dictionaries
+------------
+
+You can also declare dictionaries of integers, strings, or structures::
+
+    begin_declarations;
+
+        declare_integer_dictionary("foo");
+        declare_string_dictionary("bar");
+
+        begin_struct_dictionary("struct_dict");
+
+            declare_integer("baz");
+            declare_string("qux");
+
+        end_struct_dictionary("struct_dict");
+
+    end_declarations;
+
+Individual values in the dictionary are accessed by using a string key::
+
+    foo["somekey"]
+    bar["anotherkey"]
+    struct_dict["k1"].baz
+    struct_dict["k1"].qux
+
 .. _declaring-functions:
 
 Functions
@@ -698,14 +724,24 @@ Then the following statements are all valid:
 
 Those ``%i`` in the field descriptor are replaced by the additional
 integer arguments passed to the function. This work in the same way than
-``printf`` in C programs, but the only format specifier accepted is ``%i``.
-
-If you don't explicitely assign a value to a declared variable or array item it
-will remain in undefined state. That's not a problem at all, and is even useful
-in many cases. For example, if your module parses files from certain format and
-it receives one from a different format, you can safely leave all your
-variables undefined instead of assigning them bogus values that doesn't make
-sense. YARA will handle undefined values in rule conditions as described in
+``printf`` in C programs, but the only format specifiers accepted are ``%i``
+and ``%s``, for integer and string arguments respectively.
+
+The ``%s`` format specifiers is used for assigning values to a certain key
+in a dictionary:
+
+.. code-block:: c
+
+    set_integer(<value>, module, "foo[\"key\"]");
+    set_integer(<value>, module, "foo[%s]", "key");
+    set_string(<value>, module, "bar[%s].baz", "another_key");
+
+If you don't explicitely assign a value to a declared variable, array or
+dictionary item it will remain in undefined state. That's not a problem at all,
+and is even useful in many cases. For example, if your module parses files from
+certain format and it receives one from a different format, you can safely leave
+all your variables undefined instead of assigning them bogus values that doesn't
+make sense. YARA will handle undefined values in rule conditions as described in
 :ref:`using-modules`.
 
 In addition to ``set_integer`` and ``set_string`` functions you have their

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/forensics/yara.git