More documentation.

libsrc/ffdec_lib/src/com/jpexs/decompiler/flash/IdentifiersDeobfuscation.java

@@ -25,49 +25,90 @@ import com.jpexs.decompiler.flash.tags.base.PlaceObjectTypeTag;
 import com.jpexs.decompiler.graph.DottedChain;
 import com.jpexs.helpers.Cache;
 import com.jpexs.helpers.Helper;
-import java.util.ArrayList;
-import java.util.HashMap;
-import java.util.HashSet;
-import java.util.List;
-import java.util.Map;
-import java.util.Random;
+
+import java.util.*;
 import java.util.regex.Pattern;
 
 /**
- *
+ * Identifiers deobfuscation.
  * @author JPEXS
  */
 public class IdentifiersDeobfuscation {
 
+    /**
+     * Random number generator.
+     */
     private static final Random rnd = new Random();
 
+    /**
+     * Default size of random string.
+     */
     private final int DEFAULT_FOO_SIZE = 10;
 
+    /**
+     * All variable names.
+     */
     public HashSet<String> allVariableNamesStr = new HashSet<>();
 
+    /**
+     * Type counts.
+     */
     private final HashMap<String, Integer> typeCounts = new HashMap<>();
 
+    /**
+     * AS2 name cache.
+     */
     private static final Cache<String, String> as2NameCache = Cache.getInstance(false, true, "as2_ident", true);
 
+    /**
+     * AS3 name cache.
+     */
     private static final Cache<String, String> as3NameCache = Cache.getInstance(false, true, "as3_ident", true);
 
+    /**
+     * Valid first characters.
+     */
     public static final String VALID_FIRST_CHARACTERS = "\\p{Lu}\\p{Ll}\\p{Lt}\\p{Lm}\\p{Lo}_$";
 
+    /**
+     * Valid next characters.
+     */
     public static final String VALID_NEXT_CHARACTERS = VALID_FIRST_CHARACTERS + "\\p{Nl}\\p{Mn}\\p{Mc}\\p{Nd}\\p{Pc}";
 
+    /**
+     * Valid name pattern.
+     */
     private static final Pattern VALID_NAME_PATTERN = Pattern.compile("^[a-zA-Z_\\$][a-zA-Z0-9_\\$]*$");
 
+    /**
+     * Identifier pattern.
+     */
     private static final Pattern IDENTIFIER_PATTERN = Pattern.compile("^[" + VALID_FIRST_CHARACTERS + "][" + VALID_NEXT_CHARACTERS + "]*$");
 
+    /**
+     * Valid name pattern with dot.
+     */
     private static final Pattern VALID_NAME_PATTERN_DOT = Pattern.compile("^[a-zA-Z_\\$][a-zA-Z0-9_.\\$]*$");
 
+    /**
+     * Identifier pattern with dot.
+     */
     private static final Pattern IDENTIFIER_PATTERN_DOT = Pattern.compile("^[" + VALID_FIRST_CHARACTERS + "][" + VALID_NEXT_CHARACTERS + ".]*$");
 
+    /**
+     * Random name generator characters.
+     */
     public static final String FOO_CHARACTERS = "bcdfghjklmnpqrstvwz";
 
+    /**
+     * Random name generator join characters.
+     */
     public static final String FOO_JOIN_CHARACTERS = "aeiouy";
 
-    // http://help.adobe.com/en_US/AS2LCR/Flash_10.0/help.html?content=00000477.html
+    /**
+     * Reserved words in AS2.
+     * http://help.adobe.com/en_US/AS2LCR/Flash_10.0/help.html?content=00000477.html
+     */
     public static final String[] reservedWordsAS2 = {
         // is "add" really a keyword? documentation says yes, but I can create "add" variable in CS6...
         // "add",
@@ -99,7 +140,10 @@ public class IdentifiersDeobfuscation {
         "typeof", "undefined", "var", "void", "while", "with"
     };
 
-    // http://www.adobe.com/devnet/actionscript/learning/as3-fundamentals/syntax.html
+    /**
+     * Reserved words in AS3.
+     * http://www.adobe.com/devnet/actionscript/learning/as3-fundamentals/syntax.html
+     */
     public static final String[] reservedWordsAS3 = {
         "as", "break", "case", "catch", "class", "const", "continue", "default", "delete", "do", "else",
         "extends", "false", "finally", "for", "function", "if", "implements", "import", "in", "instanceof",
@@ -111,7 +155,9 @@ public class IdentifiersDeobfuscation {
         "void", "while", "with"
     };
 
-    // TODO, why do we have 2 different list? Moved from AVM2Deobfuscation
+    /**
+     * TODO, why do we have 2 different list? Moved from AVM2Deobfuscation
+     */
     public static final String[] reservedWordsAS3_2 = {
         "as", "break", "case", "catch", "class", "const", "continue", "default", "delete", "do", "each", "else",
         "extends", "false", "finally", "for", "function", "get", "if", "implements", "import", "in", "instanceof",
@@ -119,9 +165,16 @@ public class IdentifiersDeobfuscation {
         "return", "set", "super", "switch", "this", "throw", "true", "try", "typeof", "use", "var", /*"void",*/ "while",
         "with", "dynamic", "default", "final", "in", "static"};
 
-    //syntactic keywords - can be used as identifiers, but that have special meaning in certain contexts
+    /**
+     * Syntactic keywords - can be used as identifiers, but that have special meaning in certain contexts
+     */
     public static final String[] syntacticKeywordsAS3 = {"each", "get", "set", "namespace", "include", "dynamic", "final", "native", "override", "static"};
 
+    /**
+     * Checks if string is reserved word.
+     * @param s String
+     * @param as3 Is ActionScript3
+     */
     public static boolean isReservedWord(String s, boolean as3) {
         if (s == null) {
             return false;
@@ -136,7 +189,11 @@ public class IdentifiersDeobfuscation {
         return false;
     }
 
-    // TODO: Why do we need this method???
+    /**
+     * TODO: Why do we need this method???
+     * @param s String
+     * @return True if string is reserved word
+     */
     public static boolean isReservedWord2(String s) {
         if (s == null) {
             return false;
@@ -151,6 +208,12 @@ public class IdentifiersDeobfuscation {
         return false;
     }
 
+    /**
+     * Generates random string.
+     * @param firstUppercase First character uppercase
+     * @param rndSize Random size
+     * @return Random string
+     */
     public static String fooString(boolean firstUppercase, int rndSize) {
         int len = 3 + rnd.nextInt(rndSize - 3);
         StringBuilder sb = new StringBuilder(len);
@@ -170,6 +233,14 @@ public class IdentifiersDeobfuscation {
         return sb.toString();
     }
 
+    /**
+     * Deobfuscates instance names.
+     * @param as3 Is ActionScript3
+     * @param namesMap Names map
+     * @param renameType Rename type
+     * @param tags Tags
+     * @param selected Preselected names
+     */
     public void deobfuscateInstanceNames(boolean as3, HashMap<DottedChain, DottedChain> namesMap, RenameType renameType, Iterable<Tag> tags, Map<DottedChain, DottedChain> selected) {
         for (Tag t : tags) {
             if (t instanceof DefineSpriteTag) {
@@ -197,6 +268,15 @@ public class IdentifiersDeobfuscation {
         }
     }
 
+    /**
+     * Deobfuscates package names.
+     * @param as3 Is ActionScript3
+     * @param pkg Package
+     * @param namesMap Names map
+     * @param renameType Rename type
+     * @param selected Preselected names
+     * @return Deobfuscated package
+     */
     public DottedChain deobfuscatePackage(boolean as3, DottedChain pkg, HashMap<DottedChain, DottedChain> namesMap, RenameType renameType, Map<DottedChain, DottedChain> selected) {
         if (namesMap.containsKey(pkg)) {
             return namesMap.get(pkg);
@@ -221,6 +301,15 @@ public class IdentifiersDeobfuscation {
         return null;
     }
 
+    /**
+     * Deobfuscates name with package.
+     * @param as3 Is ActionScript3
+     * @param n Name
+     * @param namesMap Names map
+     * @param renameType Rename type
+     * @param selected Preselected names
+     * @return Deobfuscated name
+     */
     public String deobfuscateNameWithPackage(boolean as3, String n, HashMap<DottedChain, DottedChain> namesMap, RenameType renameType, Map<DottedChain, DottedChain> selected) {
         DottedChain nChain = DottedChain.parseNoSuffix(n);
         DottedChain pkg = nChain.getWithoutLast();
@@ -251,6 +340,12 @@ public class IdentifiersDeobfuscation {
         return null;
     }
 
+    /**
+     * Checks if string is valid slash path.
+     * @param s String
+     * @param exceptions Exceptions
+     * @return True if string is valid slash path
+     */
     private static boolean isValidSlashPath(String s, String... exceptions) {
         String[] slashParts = s.split("\\/");
         if (s.isEmpty()) {
@@ -274,6 +369,12 @@ public class IdentifiersDeobfuscation {
         return true;
     }
 
+    /**
+     * Checks if string is valid name with slash.
+     * @param s String
+     * @param exceptions Exceptions
+     * @return True if string is valid name with slash
+     */
     public static boolean isValidNameWithSlash(String s, String... exceptions) {
         if (s.contains(":")) {
             String[] pathVar = s.split(":");
@@ -291,6 +392,13 @@ public class IdentifiersDeobfuscation {
         }
     }
 
+    /**
+     * Checks if string is valid name with dot.
+     * @param as3 Is ActionScript3
+     * @param s String
+     * @param exceptions Exceptions
+     * @return True if string is valid name with dot
+     */
     public static boolean isValidNameWithDot(boolean as3, String s, String... exceptions) {
         for (String e : exceptions) {
             if (e.equals(s)) {
@@ -313,6 +421,13 @@ public class IdentifiersDeobfuscation {
         return false;
     }
 
+    /**
+     * Checks if string is valid name.
+     * @param as3 Is ActionScript3
+     * @param s String
+     * @param exceptions Exceptions
+     * @return True if string is valid name
+     */
     public static boolean isValidName(boolean as3, String s, String... exceptions) {
         for (String e : exceptions) {
             if (e.equals(s)) {
@@ -335,6 +450,17 @@ public class IdentifiersDeobfuscation {
         return false;
     }
 
+    /**
+     * Deobfuscates name.
+     * @param as3 Is ActionScript3
+     * @param s String
+     * @param firstUppercase First character uppercase
+     * @param usageType Usage type
+     * @param namesMap Names map
+     * @param renameType Rename type
+     * @param selected Preselected names
+     * @return Deobfuscated name
+     */
     public String deobfuscateName(boolean as3, String s, boolean firstUppercase, String usageType, HashMap<DottedChain, DottedChain> namesMap, RenameType renameType, Map<DottedChain, DottedChain> selected) {
         if (usageType == null) {
             usageType = "name";
@@ -380,6 +506,12 @@ public class IdentifiersDeobfuscation {
         return null;
     }
 
+    /**
+     * Appends obfuscated identifier.
+     * @param s String
+     * @param writer Writer
+     * @return Writer
+     */
     public static GraphTextWriter appendObfuscatedIdentifier(String s, GraphTextWriter writer) {
         writer.append("\u00A7");
         escapeOIdentifier(s, writer);
@@ -387,7 +519,7 @@ public class IdentifiersDeobfuscation {
     }
 
     /**
-     * Ensures identifier is valid and if not, uses paragraph syntax
+     * Ensures identifier is valid and if not, uses paragraph syntax.
      *
      * @param as3 Is ActionScript3
      * @param s Identifier
@@ -426,6 +558,12 @@ public class IdentifiersDeobfuscation {
         return ret;
     }
 
+    /**
+     * Escapes obfuscated identifier.
+     * @param s String
+     * @param writer Writer
+     * @return Writer
+     */
     public static GraphTextWriter escapeOIdentifier(String s, GraphTextWriter writer) {
         for (int i = 0; i < s.length(); i++) {
             char c = s.charAt(i);
@@ -465,6 +603,11 @@ public class IdentifiersDeobfuscation {
         return writer;
     }
 
+    /**
+     * Escapes obfuscated identifier.
+     * @param s String
+     * @return Escaped string
+     */
     public static String escapeOIdentifier(String s) {
         StringBuilder ret = new StringBuilder(s.length());
         for (int i = 0; i < s.length(); i++) {
@@ -505,6 +648,9 @@ public class IdentifiersDeobfuscation {
         return ret.toString();
     }
 
+    /**
+     * Clears cache.
+     */
     public static void clearCache() {
         as2NameCache.clear();
         as3NameCache.clear();