diff options
| author | Ulf Magnusson <ulfalizer@gmail.com> | 2017-11-09 11:43:13 +0100 |
|---|---|---|
| committer | Ulf Magnusson <ulfalizer@gmail.com> | 2017-11-09 11:43:13 +0100 |
| commit | 395c2db0e9761def8eb992e3e8068ba2d3ab179c (patch) | |
| tree | 7b14ac791dbf9d4b9354f1c6149444e090068309 /kconfiglib.py | |
| parent | 8c978ee0b9c0f7f8406f58d24478a73330512056 (diff) | |
| parent | 4bffd653148d6fa1c8e626872ae4f445e2b0a24c (diff) | |
Make Kconfiglib 2 official
Merge in the 'kconfiglib-2-backup' branch.
Diffstat (limited to 'kconfiglib.py')
| -rw-r--r-- | kconfiglib.py | 6464 |
1 files changed, 3435 insertions, 3029 deletions
diff --git a/kconfiglib.py b/kconfiglib.py index 186c931..487d57d 100644 --- a/kconfiglib.py +++ b/kconfiglib.py @@ -1,1320 +1,1114 @@ -# This is Kconfiglib, a Python library for scripting, debugging, and extracting -# information from Kconfig-based configuration systems. To view the -# documentation, run -# -# $ pydoc kconfiglib -# -# or, if you prefer HTML, -# -# $ pydoc -w kconfiglib -# -# The examples/ subdirectory contains examples, to be run with e.g. -# -# $ make scriptconfig SCRIPT=Kconfiglib/examples/print_tree.py -# -# Look in testsuite.py for the test suite. - """ -Kconfiglib is a Python library for scripting and extracting information from -Kconfig-based configuration systems. Features include the following: +Overview +======== - - Symbol values and properties can be looked up and values assigned - programmatically. - - .config files can be read and written. - - Expressions can be evaluated in the context of a Kconfig configuration. - - Relations between symbols can be quickly determined, such as finding all - symbols that reference a particular symbol. - - Highly compatible with the scripts/kconfig/*conf utilities. The test suite - automatically compares outputs between Kconfiglib and the C implementation - for a large number of cases. +Kconfiglib is a Python 2/3 library for scripting and extracting information +from Kconfig configuration systems. It can be used for the following, among +other things: -For the Linux kernel, scripts are run using + - Programmatically get and set symbol values - $ make scriptconfig [ARCH=<arch>] SCRIPT=<path to script> [SCRIPT_ARG=<arg>] + allnoconfig.py and allyesconfig.py examples are provided, automatically + verified to produce identical output to the standard 'make allnoconfig' and + 'make allyesconfig'. -Using the 'scriptconfig' target ensures that required environment variables -(SRCARCH, ARCH, srctree, KERNELVERSION, etc.) are set up correctly. + - Read and write .config files -Scripts receive the name of the Kconfig file to load in sys.argv[1]. As of -Linux 4.1.0-rc5, this is always "Kconfig" from the kernel top-level directory. -If an argument is provided with SCRIPT_ARG, it appears as sys.argv[2]. + The generated .config files are character-for-character identical to what + the C implementation would generate (except for the header comment). The + test suite relies on this, as it compares the generated files. -To get an interactive Python prompt with Kconfiglib preloaded and a Config -object 'c' created, run + - Inspect symbols - $ make iscriptconfig [ARCH=<arch>] + Printing a symbol gives output which could be fed back into a Kconfig parser + to redefine it***. The printing function (__str__()) is implemented with + public APIs, meaning you can fetch just whatever information you need as + well. -Kconfiglib supports both Python 2 and Python 3. For (i)scriptconfig, the Python -interpreter to use can be passed in PYTHONCMD, which defaults to 'python'. PyPy -works well too, and might give a nice speedup for long-running jobs. + A helpful __repr__() is implemented on all objects too, also implemented + with public APIs. -The examples/ directory contains short example scripts, which can be run with -e.g. + ***Choice symbols get their parent choice as a dependency, which shows up as + e.g. 'prompt "choice symbol" if <choice>' when printing the symbol. This + could easily be worked around if 100% reparsable output is needed. - $ make scriptconfig SCRIPT=Kconfiglib/examples/print_tree.py + - Inspect expressions -or + Expressions use a simple tuple-based format that can be processed manually + if needed. Expression printing and evaluation functions are provided, + implemented with public APIs. - $ make scriptconfig SCRIPT=Kconfiglib/examples/help_grep.py SCRIPT_ARG=kernel + - Inspect the menu tree -testsuite.py contains the test suite. See the top of the script for how to run -it. + The underlying menu tree is exposed, including submenus created implicitly + from symbols depending on preceding symbols. This can be used e.g. to + implement menuconfig-like functionality. See the menuconfig.py example. -Credits: Written by Ulf "Ulfalizer" Magnusson -Send bug reports, suggestions and other feedback to ulfalizer a.t Google's -email service. Don't wrestle with internal APIs. Tell me what you need and I -might add it in a safe way as a client API instead.""" +Here are some other features: -import os -import platform -import re -import sys + - Single-file implementation -# File layout: -# -# Public classes -# Public functions -# Internal classes -# Internal functions -# Public global constants -# Internal global constants + The entire library is contained in this file. -# Line length: 79 columns + - Runs unmodified under both Python 2 and Python 3 -# -# Public classes -# + The code mostly uses basic Python features and has no third-party + dependencies. The most advanced things used are probably @property and + __slots__. -class Config(object): + - Robust and highly compatible with the standard Kconfig C tools - """Represents a Kconfig configuration, e.g. for i386 or ARM. This is the - set of symbols and other items appearing in the configuration together with - their values. Creating any number of Config objects -- including for - different architectures -- is safe; Kconfiglib has no global state.""" + The test suite automatically compares output from Kconfiglib and the C tools + by diffing the generated .config files for the real kernel Kconfig and + defconfig files, for all ARCHes. - # - # Public interface - # + This currently involves comparing the output for 36 ARCHes and 498 defconfig + files (or over 18000 ARCH/defconfig combinations in "obsessive" test suite + mode). All tests are expected to pass. - def __init__(self, filename="Kconfig", base_dir=None, print_warnings=True, - print_undef_assign=False): - """Creates a new Config object, representing a Kconfig configuration. - Raises Kconfig_Syntax_Error on syntax errors. - - filename (default: "Kconfig"): The base Kconfig file of the - configuration. For the Linux kernel, you'll probably want "Kconfig" - from the top-level directory, as environment variables will make - sure the right Kconfig is included from there - (arch/<architecture>/Kconfig). If you are using Kconfiglib via 'make - scriptconfig', the filename of the base base Kconfig file will be in - sys.argv[1]. - - base_dir (default: None): The base directory relative to which 'source' - statements within Kconfig files will work. For the Linux kernel this - should be the top-level directory of the kernel tree. $-references - to existing environment variables will be expanded. - - If None (the default), the environment variable 'srctree' will be - used if set, and the current directory otherwise. 'srctree' is set - by the Linux makefiles to the top-level kernel directory. A default - of "." would not work with an alternative build directory. - - print_warnings (default: True): Set to True if warnings related to this - configuration should be printed to stderr. This can be changed later - with Config.set_print_warnings(). It is provided as a constructor - argument since warnings might be generated during parsing. - - print_undef_assign (default: False): Set to True if informational - messages related to assignments to undefined symbols should be - printed to stderr for this configuration. Can be changed later with - Config.set_print_undef_assign().""" - - # The set of all symbols, indexed by name (a string) - self._syms = {} - - # The set of all defined symbols in the configuration in the order they - # appear in the Kconfig files. This excludes the special symbols n, m, - # and y as well as symbols that are referenced but never defined. - self._defined_syms = [] - - # The set of all named choices (yes, choices can have names), indexed - # by name (a string) - self._named_choices = {} - - # Lists containing all choices, menus, and comments in the - # configuration - self._choices = [] - self._menus = [] - self._comments = [] + - **Not horribly slow despite being a pure Python implementation** - def register_special_symbol(type_, name, val): - sym = Symbol() - sym._is_special = True - sym._is_defined = True - sym._config = self - sym._name = name - sym._type = type_ - sym._cached_val = val - self._syms[name] = sym - return sym - - # The special symbols n, m and y, used as shorthand for "n", "m" and - # "y" - self._n = register_special_symbol(TRISTATE, "n", "n") - self._m = register_special_symbol(TRISTATE, "m", "m") - self._y = register_special_symbol(TRISTATE, "y", "y") - # DEFCONFIG_LIST uses this - register_special_symbol(STRING, "UNAME_RELEASE", platform.uname()[2]) - - # The symbol with "option defconfig_list" set, containing a list of - # default .config files - self._defconfig_sym = None - - # See Symbol.get_(src)arch() - self._arch = os.environ.get("ARCH") - self._srcarch = os.environ.get("SRCARCH") - - # If you set CONFIG_ in the environment, Kconfig will prefix all - # symbols with its value when saving the configuration, instead of - # using the default, "CONFIG_". - self._config_prefix = os.environ.get("CONFIG_") - if self._config_prefix is None: - self._config_prefix = "CONFIG_" - - # Regular expressions for parsing .config files - self._set_re = re.compile(r"{}(\w+)=(.*)" - .format(self._config_prefix)) - self._unset_re = re.compile(r"# {}(\w+) is not set" - .format(self._config_prefix)) - - self._kconfig_filename = filename - - # See Config.__init__(). We need this for get_defconfig_filename(). - self._srctree = os.environ.get("srctree") - - if base_dir is None: - self._base_dir = "." if self._srctree is None else self._srctree - else: - self._base_dir = os.path.expandvars(base_dir) + The allyesconfig.py example currently runs in about 1.6 seconds on a Core i7 + 2600K (with a warm file cache), where half a second is overhead from 'make + scriptconfig' (see below). - # The 'mainmenu' text - self._mainmenu_text = None + For long-running jobs, PyPy gives a big performance boost. CPython is faster + for short-running jobs as PyPy needs some time to warm up. - # The filename of the most recently loaded .config file - self._config_filename = None - # The textual header of the most recently loaded .config, uncommented - self._config_header = None + - Internals that (mostly) mirror the C implementation - self._print_warnings = print_warnings - self._print_undef_assign = print_undef_assign + While being simpler to understand. - # When parsing properties, we stop on the first (non-empty) - # non-property line. _end_line and _end_line_tokens hold that line and - # its tokens so that we don't have to re-tokenize the line later. This - # isn't just an optimization: We record references to symbols during - # tokenization, so tokenizing twice would cause double registration. - # - # self._end_line doubles as a flag where None means we don't have a - # cached tokenized line. - self._end_line = None - # self.end_line_tokens is set later during parsing - # Parse the Kconfig files - self._top_block = [] - self._parse_file(filename, None, None, None, self._top_block) +Using Kconfiglib on the Linux kernel with the Makefile targets +============================================================== - # Build Symbol._direct_dependents for all symbols - self._build_dep() +For the Linux kernel, a handy interface is provided by the +scripts/kconfig/Makefile patch. It can be applied by running the following +command in the kernel root: - def get_arch(self): - """Returns the value the environment variable ARCH had at the time the - Config instance was created, or None if ARCH was not set. For the - kernel, this corresponds to the architecture being built for, with - values such as "i386" or "mips".""" - return self._arch - - def get_srcarch(self): - """Returns the value the environment variable SRCARCH had at the time - the Config instance was created, or None if SRCARCH was not set. For - the kernel, this corresponds to the particular arch/ subdirectory - containing architecture-specific code.""" - return self._srcarch - - def get_srctree(self): - """Returns the value the environment variable 'srctree' had at the time - the Config instance was created, or None if 'srctree' was not defined. - This variable points to the source directory and is used when building - in a separate directory.""" - return self._srctree - - def get_base_dir(self): - """Returns the base directory relative to which 'source' statements - will work, passed as an argument to Config.__init__().""" - return self._base_dir - - def get_kconfig_filename(self): - """Returns the name of the (base) kconfig file this configuration was - loaded from.""" - return self._kconfig_filename - - def get_config_filename(self): - """Returns the filename of the most recently loaded configuration file, - or None if no configuration has been loaded.""" - return self._config_filename - - def get_config_header(self): - """Returns the (uncommented) textual header of the .config file most - recently loaded with load_config(). Returns None if no .config file has - been loaded or if the most recently loaded .config file has no header. - - The header consists of all lines up to but not including the first line - that either (1) does not begin with "#", or (2) matches - "# CONFIG_FOO is not set".""" - return self._config_header - - def get_mainmenu_text(self): - """Returns the text of the 'mainmenu' statement (with $-references to - symbols replaced by symbol values), or None if the configuration has no - 'mainmenu' statement.""" - return None if self._mainmenu_text is None else \ - self._expand_sym_refs(self._mainmenu_text) - - def get_defconfig_filename(self): - """Returns the name of the defconfig file, which is the first existing - file in the list given in a symbol having 'option defconfig_list' set. - $-references to symbols will be expanded ("$FOO bar" -> "foo bar" if - FOO has the value "foo"). Returns None in case of no defconfig file. - Setting 'option defconfig_list' on multiple symbols ignores the symbols - past the first one (and prints a warning). - - If the environment variable 'srctree' was set when the Config was - created, each defconfig specified with a relative path will be - searched for in $srcdir if it is not found at the specified path (i.e., - if foo/defconfig is not found, $srctree/foo/defconfig will be looked - up). - - WARNING: A wart here is that scripts/kconfig/Makefile sometimes uses - the --defconfig=<defconfig> option when calling the C implementation of - e.g. 'make defconfig'. This option overrides the 'option - defconfig_list' symbol, meaning the result from - get_defconfig_filename() might not match what 'make defconfig' would - use. That probably ought to be worked around somehow, so that this - function always gives the "expected" result.""" - if self._defconfig_sym is None: - return None - for filename, cond_expr in self._defconfig_sym._def_exprs: - if self._eval_expr(cond_expr) != "n": - filename = self._expand_sym_refs(filename) - if os.access(filename, os.R_OK): - return filename - # defconfig not found. If the path is a relative path and - # $srctree is set, we also look in $srctree. - if not os.path.isabs(filename) and self._srctree is not None: - filename = os.path.join(self._srctree, filename) - if os.access(filename, os.R_OK): - return filename + $ wget -qO- https://raw.githubusercontent.com/ulfalizer/Kconfiglib/master/makefile.patch | git am - return None +Please tell me if the patch does not apply. It should be trivial to apply +manually, as it's just a block of text that needs to be inserted near the other +``*conf:`` targets in scripts/kconfig/Makefile. - def get_symbol(self, name): - """Returns the symbol with name 'name', or None if no such symbol - appears in the configuration. An alternative shorthand is conf[name], - where conf is a Config instance, though that will instead raise - KeyError if the symbol does not exist.""" - return self._syms.get(name) +If you do not wish to install Kconfiglib via pip, the Makefile patch is set up +so that you can also just clone Kconfiglib into the kernel root: - def __getitem__(self, name): - """Returns the symbol with name 'name'. Raises KeyError if the symbol - does not appear in the configuration.""" - return self._syms[name] + $ git clone git://github.com/ulfalizer/Kconfiglib.git + $ git am Kconfiglib/makefile.patch - def get_symbols(self, all_symbols=True): - """Returns a list of symbols from the configuration. An alternative for - iterating over all defined symbols (in the order of definition) is +(Warning: The directory name Kconfiglib/ is significant in this case, because +it's added to PYTHONPATH by the new targets in makefile.patch.) - for sym in config: - ... +Look further down for a motivation for the Makefile patch and for instructions +on how you can use Kconfiglib without it. - which relies on Config implementing __iter__() and is equivalent to +The Makefile patch adds the following targets: - for sym in config.get_symbols(False): - ... - all_symbols (default: True): If True, all symbols -- including special - and undefined symbols -- will be included in the result, in an - undefined order. If False, only symbols actually defined and not - merely referred to in the configuration will be included in the - result, and will appear in the order that they are defined within - the Kconfig configuration files.""" - return list(self._syms.values()) if all_symbols else \ - self._defined_syms +make [ARCH=<arch>] iscriptconfig +-------------------------------- - def __iter__(self): - """Convenience function for iterating over the set of all defined - symbols in the configuration, used like +This target gives an interactive Python prompt where a Kconfig instance has +been preloaded and is available in 'kconf'. To change the Python interpreter +used, pass PYTHONCMD=<executable> to make. The default is "python". - for sym in conf: - ... +To get a feel for the API, try evaluating and printing the symbols in +kconf.defined_syms, and explore the MenuNode menu tree starting at +kconf.top_node by following 'next' and 'list' pointers. - The iteration happens in the order of definition within the Kconfig - configuration files. Symbols only referred to but not defined will not - be included, nor will the special symbols n, m, and y. If you want to - include such symbols as well, see config.get_symbols().""" - return iter(self._defined_syms) - - def get_choices(self): - """Returns a list containing all choice statements in the - configuration, in the order they appear in the Kconfig files.""" - return self._choices - - def get_menus(self): - """Returns a list containing all menus in the configuration, in the - order they appear in the Kconfig files.""" - return self._menus - - def get_comments(self): - """Returns a list containing all comments in the configuration, in the - order they appear in the Kconfig files.""" - return self._comments - - def get_top_level_items(self): - """Returns a list containing the items (symbols, menus, choices, and - comments) at the top level of the configuration -- that is, all items - that do not appear within a menu or choice. The items appear in the - same order as within the configuration.""" - return self._top_block +The item contained in a menu node is found in MenuNode.item (note that this can +be one of the constants MENU and COMMENT), and all symbols and choices have a +'nodes' attribute containing their menu nodes (usually only one). Printing a +menu node will print its item, in Kconfig format. - def load_config(self, filename, replace=True): - """Loads symbol values from a file in the familiar .config format. - Equivalent to calling Symbol.set_user_value() to set each of the - values. +If you want to look up a symbol by name, use the kconf.syms dictionary. - "# CONFIG_FOO is not set" within a .config file is treated specially - and sets the user value of FOO to 'n'. The C implementation works the - same way. - filename: The .config file to load. $-references to existing - environment variables will be expanded. For scripts to work even when - an alternative build directory is used with the Linux kernel, you - need to refer to the top-level kernel directory with "$srctree". +make scriptconfig SCRIPT=<script> [SCRIPT_ARG=<arg>] +---------------------------------------------------- - replace (default: True): True if the configuration should replace the - old configuration; False if it should add to it.""" +This target runs the Python script given by the SCRIPT parameter on the +configuration. sys.argv[1] holds the name of the top-level Kconfig file +(currently always "Kconfig" in practice), and sys.argv[2] holds the SCRIPT_ARG +argument, if given. - # Put this first so that a missing file doesn't screw up our state - filename = os.path.expandvars(filename) - line_feeder = _FileFeed(filename) +See the examples/ subdirectory for example scripts. - self._config_filename = filename - # - # Read header - # +Using Kconfiglib without the Makefile targets +============================================= - if not self._is_header_line(line_feeder.peek_next()): - self._config_header = None - else: - # Kinda inefficient, but this is an unlikely hotspot - self._config_header = "" - while self._is_header_line(line_feeder.peek_next()): - self._config_header += line_feeder.get_next()[1:] - # Makes c.write_config(".config", c.get_config_header()) preserve - # the header exactly. We also handle weird cases like a .config - # file with just "# foo" and no trailing newline in it (though we - # would never generate that ourselves), hence the slight - # awkwardness. - if self._config_header.endswith("\n"): - self._config_header = self._config_header[:-1] +The make targets are only needed for a trivial reason: The Kbuild makefiles +export environment variables which are referenced inside the Kconfig files (via +'option env="ENV_VARIABLE"'). - # - # Read assignments. Hotspot for some workloads. - # +In practice, the only variables referenced (as of writing, and for many years) +are ARCH, SRCARCH, and KERNELVERSION. To run Kconfiglib without the Makefile +patch, do this: - if replace: - # This invalidates all symbols as a side effect - self.unset_user_values() - else: - self._invalidate_all() + $ ARCH=x86 SRCARCH=x86 KERNELVERSION=`make kernelversion` python + >>> import kconfiglib + >>> kconf = kconfiglib.Kconfig() # filename defaults to "Kconfig" - # Small optimization - set_re_match = self._set_re.match - unset_re_match = self._unset_re.match +Search the top-level Makefile for "Additional ARCH settings" to see other +possibilities for ARCH and SRCARCH. Kconfiglib will print a warning if an unset +environment variable is referenced inside the Kconfig files. - while 1: - line = line_feeder.get_next() - if line is None: - return - - line = line.rstrip() - - set_match = set_re_match(line) - if set_match: - name, val = set_match.groups() - if name not in self._syms: - self._warn_undef_assign_load( - name, val, line_feeder.filename, line_feeder.linenr) - continue - sym = self._syms[name] +Gotcha +****** - if sym._type == STRING and val.startswith('"'): - if len(val) < 2 or val[-1] != '"': - self._warn("malformed string literal", - line_feeder.filename, - line_feeder.linenr) - continue - # Strip quotes and remove escapings. The unescaping - # procedure should be safe since " can only appear as \" - # inside the string. - val = val[1:-1].replace('\\"', '"') \ - .replace("\\\\", "\\") - - if sym._is_choice_sym: - user_mode = sym._parent._user_mode - if user_mode is not None and user_mode != val: - self._warn("assignment to {} changes mode of " - 'containing choice from "{}" to "{}".' - .format(name, val, user_mode), - line_feeder.filename, - line_feeder.linenr) +It's important to set $SRCARCH even if you don't care about values and only +want to extract information from Kconfig files, because the top-level Makefile +does this (as of writing): - else: - unset_match = unset_re_match(line) - if not unset_match: - continue + source "arch/$SRCARCH/Kconfig" - name = unset_match.group(1) - if name not in self._syms: - self._warn_undef_assign_load( - name, val, line_feeder.filename, line_feeder.linenr) - continue +If $SRCARCH is not set, this expands to "arch//Kconfig", and arch/Kconfig +happens to be an existing file, giving something that appears to work but is +actually a truncated configuration. The available symbols will differ depending +on the arch as well. - sym = self._syms[name] - val = "n" - # Done parsing the assignment. Set the value. +Intro to symbol values +====================== - if sym._user_val is not None: - self._warn('{} set more than once. Old value: "{}", new ' - 'value: "{}".' - .format(name, sym._user_val, val), - line_feeder.filename, line_feeder.linenr) +Kconfiglib has the same assignment semantics as the C implementation. - sym._set_user_value_no_invalidate(val, True) +Any symbol can be assigned a value by the user (via Kconfig.load_config() or +Symbol.set_value()), but this user value is only respected if the symbol is +visible, which corresponds to it (currently) being visible in the menuconfig +interface. - def write_config(self, filename, header=None): - """Writes out symbol values in the familiar .config format. +Symbols without prompts are never visible (setting a user value on them is +pointless). For symbols with prompts, the visibility of the symbol is +determined by the condition on the prompt. - Kconfiglib makes sure the format matches what the C implementation - would generate, down to whitespace. This eases testing. +Dependencies from parents and 'if'/'depends on' are propagated to properties, +including prompts, so these two configurations are logically equivalent: - filename: The filename under which to save the configuration. +(1) - header (default: None): A textual header that will appear at the - beginning of the file, with each line commented out automatically. - Does not need to include a trailing newline. None means no - header.""" + menu "menu" + depends on A - # Symbol._already_written is set to True when _add_config_strings() is - # called on a symbol, so that symbols defined in multiple locations - # only get one .config entry. We reset it prior to writing out a new - # .config. It only needs to be reset for defined symbols, because - # undefined symbols will never have _add_config_strings() called on - # them (because they do not appear in the block structure rooted at - # _top_block). - # - # The C implementation reuses _write_to_conf for this, but we cache - # _write_to_conf together with the value and don't invalidate cached - # values when writing .config files, so that won't work. - for sym in self._defined_syms: - sym._already_written = False + if B - # Build configuration. Avoiding string concatenation is worthwhile at - # least for PyPy. - config_strings = [] - add_fn = config_strings.append - for item in self._top_block: - item._add_config_strings(add_fn) + config FOO + tristate "foo" if D + default y + depends on C - with open(filename, "w") as f: - # Write header - if header is not None: - f.writelines(["#" + line - for line in (header + "\n").splitlines(True)]) - # Write configuration - f.writelines(config_strings) - - def eval(self, s): - """Returns the value of the expression 's' -- where 's' is represented - as a string -- in the context of the configuration. Raises - Kconfig_Syntax_Error if syntax errors are detected in 's'. - - For example, if FOO and BAR are tristate symbols at least one of which - has the value "y", then config.eval("y && (FOO || BAR)") => "y" - - This function always yields a tristate value. To get the value of - non-bool, non-tristate symbols, use Symbol.get_value(). - - The result of this function is consistent with how evaluation works for - conditional expressions in the configuration as well as in the C - implementation. "m" and m are rewritten as '"m" && MODULES' and 'm && - MODULES', respectively, and a result of "m" will get promoted to "y" if - we're running without modules. - - Syntax checking is somewhat lax, partly to be compatible with lax - parsing in the C implementation.""" - return self._eval_expr(self._parse_expr(self._tokenize(s, True), - None, # Current symbol/choice - s, - None, # filename - None, # linenr - True)) # transform_m - - def unset_user_values(self): - """Resets the values of all symbols, as if Config.load_config() or - Symbol.set_user_value() had never been called.""" - - # set_user_value() already rejects undefined symbols, and they don't - # need to be invalidated (because their value never changes), so we can - # just iterate over defined symbols. - - for sym in self._defined_syms: - # We're iterating over all symbols already, so no need for symbols - # to invalidate their dependent symbols - sym._unset_user_value_no_recursive_invalidate() - - def set_print_warnings(self, print_warnings): - """Determines whether warnings related to this configuration (for - things like attempting to assign illegal values to symbols with - Symbol.set_user_value()) should be printed to stderr. - - print_warnings: True if warnings should be printed.""" - self._print_warnings = print_warnings - - def set_print_undef_assign(self, print_undef_assign): - """Determines whether informational messages related to assignments to - undefined symbols should be printed to stderr for this configuration. - - print_undef_assign: If True, such messages will be printed.""" - self._print_undef_assign = print_undef_assign + endif - def __str__(self): - """Returns a string containing various information about the Config.""" - return _lines("Configuration", - "File : " + - self._kconfig_filename, - "Base directory : " + - self._base_dir, - "Value of $ARCH at creation time : " + - ("(not set)" - if self._arch is None - else self._arch), - "Value of $SRCARCH at creation time : " + - ("(not set)" - if self._srcarch is None - else self._srcarch), - "Value of $srctree at creation time : " + - ("(not set)" - if self._srctree is None - else self._srctree), - "Most recently loaded .config : " + - ("(no .config loaded)" - if self._config_filename is None - else self._config_filename), - "Print warnings : " + - str(self._print_warnings), - "Print assignments to undefined symbols : " + - str(self._print_undef_assign)) + endmenu - # - # Private methods - # +(2) - # - # Kconfig parsing - # + menu "menu" + depends on A - def _parse_file(self, filename, parent, deps, visible_if_deps, block): - """Parses the Kconfig file 'filename'. Appends the Items in the file - (and any file it sources) to the list passed in the 'block' parameter. - See _parse_block() for the meaning of the parameters.""" - self._parse_block(_FileFeed(filename), None, parent, deps, - visible_if_deps, block) + config FOO + tristate "foo" if A && B && C && D + default y if A && B && C - def _parse_block(self, line_feeder, end_marker, parent, deps, - visible_if_deps, block): - """Parses a block, which is the contents of either a file or an if, - menu, or choice statement. Appends the Items to the list passed in the - 'block' parameter. + endmenu - line_feeder: A _FileFeed instance feeding lines from a file. The - Kconfig language is line-based in practice. +In this example, A && B && C && D (the prompt condition) needs to be non-n for +FOO to be visible (assignable). If the value is m, the symbol can only be +assigned the value m. The visibility sets an upper bound on the value that can +be assigned by the user, and any higher user value will be truncated down. - end_marker: The token that ends the block, e.g. _T_ENDIF ("endif") for - ifs. None for files. +'default' properties are independent of the visibility, though a 'default' will +often get the same condition as the prompt due to dependency propagation. +'default' properties are used if the symbol is not visible or has no user +value. - parent: The enclosing menu or choice, or None if we're at the top - level. +Symbols with no (active) user value and no (active) 'default' default to n for +bool/tristate symbols, and to the empty string for other symbols. - deps: Dependencies from enclosing menus, choices and ifs. +'select' works similarly to symbol visibility, but sets a lower bound on the +value of the symbol. The lower bound is determined by the value of the +select*ing* symbol. 'select' does not respect visibility, so non-visible +symbols can be forced to a particular (minimum) value by a select as well. - visible_if_deps (default: None): 'visible if' dependencies from - enclosing menus. +For non-bool/tristate symbols, it only matters whether the visibility is n or +non-n: m visibility acts the same as y visibility. - block: The list to add items to.""" +Conditions on 'default' and 'select' work in mostly intuitive ways. If the +condition is n, the 'default' or 'select' is disabled. If it is m, the +'default' or 'select' value (the value of the selecting symbol) is truncated +down to m. - while 1: - # See the _end_line description in Config.__init__() - if self._end_line is not None: - line = self._end_line - tokens = self._end_line_tokens - self._end_line = None - else: - line = line_feeder.get_next() - if line is None: - if end_marker is not None: - raise Kconfig_Syntax_Error("Unexpected end of file " + - line_feeder.filename) - return +When writing a configuration with Kconfig.write_config(), only symbols that are +visible, have an (active) default, or are selected will get written out (note +that this includes all symbols that would accept user values). Kconfiglib +matches the .config format produced by the C implementations down to the +character. This eases testing. - tokens = self._tokenize(line, False, line_feeder.filename, - line_feeder.linenr) +In Kconfiglib, the set of (currently) assignable values for a bool/tristate +symbol appear in Symbol.assignable. For other symbol types, just check if +sym.visibility is non-0 (non-n). - t0 = tokens.get_next() - if t0 is None: - continue - # Cases are ordered roughly by frequency, which speeds things up a - # bit +Intro to the menu tree +====================== - # This also handles 'menuconfig'. See the comment in the token - # definitions. - if t0 == _T_CONFIG: - # The tokenizer will automatically allocate a new Symbol object - # for any new names it encounters, so we don't need to worry - # about that here. - sym = tokens.get_next() +The menu structure, as seen in e.g. menuconfig, is represented by a tree of +MenuNode objects. The top node of the configuration corresponds to an implicit +top-level menu, the title of which is shown at the top in the standard +menuconfig interface. (The title with variables expanded is available in +Kconfig.mainmenu_text in Kconfiglib.) - # Symbols defined in multiple places get the parent of their - # first definition. However, for symbols whose parents are - # choice statements, the choice statement takes precedence. - if not sym._is_defined or isinstance(parent, Choice): - sym._parent = parent - sym._is_defined = True +The top node is found in Kconfig.top_node. From there, you can visit child menu +nodes by following the 'list' pointer, and any following menu nodes by +following the 'next' pointer. Usually, a non-None 'list' pointer indicates a +menu or Choice, but menu nodes for symbols can sometimes have a non-None 'list' +pointer too due to submenus created implicitly from dependencies. - self._parse_properties(line_feeder, sym, deps, visible_if_deps) +MenuNode.item is either a Symbol or a Choice object, or one of the constants +MENU and COMMENT. The prompt of the menu node (which also holds the text for +menus and comments) can be found in MenuNode.prompt. For Symbol and Choice, +MenuNode.help holds the help text (if any, otherwise None). - self._defined_syms.append(sym) - block.append(sym) +Note that prompts and help texts for symbols and choices are stored in the menu +node. This makes it possible to define a symbol in multiple locations with a +different prompt or help text in each location. - elif t0 == _T_SOURCE: - kconfig_file = tokens.get_next() - exp_kconfig_file = self._expand_sym_refs(kconfig_file) - - # Hack: Avoid passing on a "./" prefix in the common case of - # 'base_dir' defaulting to ".", just to give less awkward - # results from e.g. get_def/ref_locations(). Maybe this could - # be handled in a nicer way. - if self._base_dir == ".": - filename = exp_kconfig_file - else: - filename = os.path.join(self._base_dir, exp_kconfig_file) - - if not os.path.exists(filename): - raise IOError( - '{}:{}: sourced file "{}" (expands to "{}") not ' - "found. Perhaps base_dir (argument to " - 'Config.__init__(), currently "{}") is set to the ' - "the wrong value. Also note that e.g. $FOO in a " - "'source' statement does not refer to the " - "environment variable FOO, but rather to the Kconfig " - "symbol FOO (which would commonly have " - "'option env=\"FOO\"' in its definition)." - .format(line_feeder.filename, line_feeder.linenr, - kconfig_file, exp_kconfig_file, - self._base_dir)) - - # Add items to the same block - self._parse_file(filename, parent, deps, visible_if_deps, - block) - - elif t0 == end_marker: - # We have reached the end of the block - return +This organization mirrors the C implementation. MenuNode is called +'struct menu' there, but I thought "menu" was a confusing name. - elif t0 == _T_IF: - # If statements are treated as syntactic sugar for adding - # dependencies to enclosed items and do not have an explicit - # object representation. - - dep_expr = self._parse_expr(tokens, None, line, - line_feeder.filename, - line_feeder.linenr, True) - # Add items to the same block - self._parse_block(line_feeder, _T_ENDIF, parent, - _make_and(dep_expr, deps), - visible_if_deps, block) +The list of menu nodes for a Symbol or Choice can be found in the +Symbol/Choice.nodes attribute. - elif t0 == _T_COMMENT: - comment = Comment() - comment._config = self - comment._parent = parent - comment._filename = line_feeder.filename - comment._linenr = line_feeder.linenr - comment._text = tokens.get_next() +It is possible to give a Choice a name and define it in multiple locations, +hence why Choice.nodes is a list. In practice, you're unlikely to ever see a +choice defined in more than one location. I don't think I've even seen a named +choice outside of the test suite. - self._parse_properties(line_feeder, comment, deps, - visible_if_deps) - self._comments.append(comment) - block.append(comment) +Intro to expressions +==================== - elif t0 == _T_MENU: - menu = Menu() - menu._config = self - menu._parent = parent - menu._filename = line_feeder.filename - menu._linenr = line_feeder.linenr - menu._title = tokens.get_next() - - self._parse_properties(line_feeder, menu, deps, - visible_if_deps) - - # This needs to go before _parse_block() so that we get the - # proper menu ordering in the case of nested menus - self._menus.append(menu) - # Parse contents and put Items in menu._block - self._parse_block(line_feeder, _T_ENDMENU, menu, - menu._menu_dep, - _make_and(visible_if_deps, - menu._visible_if_expr), - menu._block) - - block.append(menu) +Expressions can be evaluated with the expr_value() function and printed with +the expr_str() function (these are used internally as well). Evaluating an +expression always yields a tristate value, where n, m, and y are represented as +0, 1, and 2, respectively. - elif t0 == _T_CHOICE: - name = tokens.get_next() - if name is None: - choice = Choice() - self._choices.append(choice) - else: - # Named choice - choice = self._named_choices.get(name) - if choice is None: - choice = Choice() - choice._name = name - self._named_choices[name] = choice - self._choices.append(choice) +The following table should help you figure out how expressions are represented. +A, B, C, ... are symbols (Symbol instances), NOT is the kconfiglib.NOT +constant, etc. - choice._config = self - choice._parent = parent +Expression Representation +---------- -------------- +A A +"A" A (constant symbol) +!A (NOT, A) +A && B (AND, A, B) +A && B && C (AND, A, (AND, B, C)) +A || B (OR, A, B) +A || (B && C && D) (OR, A, (AND, B, (AND, C, D))) +A = B (EQUAL, A, B) +A != "foo" (UNEQUAL, A, foo (constant symbol)) +A && B = C && D (AND, A, (AND, (EQUAL, B, C), D)) +n Kconfig.n (constant symbol) +m Kconfig.m (constant symbol) +y Kconfig.y (constant symbol) +"y" Kconfig.y (constant symbol) - choice._def_locations.append((line_feeder.filename, - line_feeder.linenr)) +Strings like "foo" in 'default "foo"' or 'depends on SYM = "foo"' are +represented as constant symbols, so the only values that appear in expressions +are symbols***. This mirrors the C implementation. - self._parse_properties(line_feeder, choice, deps, - visible_if_deps) +***For choice symbols, the parent Choice will appear in expressions as well, +but it's usually invisible as the value interfaces of Symbol and Choice are +identical. This mirrors the C implementation and makes different choice modes +"just work". - # Parse contents and put Items in choice._block - self._parse_block(line_feeder, _T_ENDCHOICE, choice, deps, - visible_if_deps, choice._block) +Manual evaluation examples: - choice._determine_actual_symbols() + - The value of A && B is min(A.tri_value, B.tri_value) - # If no type is specified for the choice, its type is that of - # the first choice item with a specified type - if choice._type == UNKNOWN: - for item in choice._actual_symbols: - if item._type != UNKNOWN: - choice._type = item._type - break + - The value of A || B is max(A.tri_value, B.tri_value) - # Each choice item of UNKNOWN type gets the type of the choice - for item in choice._actual_symbols: - if item._type == UNKNOWN: - item._type = choice._type + - The value of !A is 2 - A.tri_value - block.append(choice) + - The value of A = B is 2 (y) if A.str_value == B.str_value, and 0 (n) + otherwise. Note that str_value is used here instead of tri_value. - elif t0 == _T_MAINMENU: - text = tokens.get_next() - if self._mainmenu_text is not None: - self._warn("overriding 'mainmenu' text. " - 'Old value: "{}", new value: "{}".' - .format(self._mainmenu_text, text), - line_feeder.filename, line_feeder.linenr) - self._mainmenu_text = text + For constant (as well as undefined) symbols, str_value matches the name of + the symbol. This mirrors the C implementation and explains why + 'depends on SYM = "foo"' above works as expected. - else: - _parse_error(line, "unrecognized construct", - line_feeder.filename, line_feeder.linenr) - - def _parse_cond(self, tokens, stmt, line, filename, linenr): - """Parses an optional 'if <expr>' construct and returns the parsed - <expr>, or None if the next token is not _T_IF.""" - return self._parse_expr(tokens, stmt, line, filename, linenr, True) \ - if tokens.check(_T_IF) else None - - def _parse_val_and_cond(self, tokens, stmt, line, filename, linenr): - """Parses '<expr1> if <expr2>' constructs, where the 'if' part is - optional. Returns a tuple containing the parsed expressions, with - None as the second element if the 'if' part is missing.""" - return (self._parse_expr(tokens, stmt, line, filename, linenr, False), - self._parse_cond(tokens, stmt, line, filename, linenr)) - - def _parse_properties(self, line_feeder, stmt, deps, visible_if_deps): - """Parsing of properties for symbols, menus, choices, and comments. - Takes care of propagating dependencies from enclosing menus and ifs.""" - - # In case the symbol is defined in multiple locations, we need to - # remember what prompts, defaults, selects, implies, and ranges are new - # for this definition, as "depends on" should only apply to the local - # definition. - new_prompt = None - new_def_exprs = [] - new_selects = [] - new_implies = [] - new_ranges = [] - - # Dependencies from 'depends on' statements - depends_on_expr = None +n/m/y are automatically converted to the corresponding constant symbols +"n"/"m"/"y" (Kconfig.n/m/y) during parsing. - while 1: - line = line_feeder.get_next() - if line is None: - break +Kconfig.const_syms is a dictionary like Kconfig.syms but for constant symbols. - filename = line_feeder.filename - linenr = line_feeder.linenr +If a condition is missing (e.g., <cond> when the 'if <cond>' is removed from +'default A if <cond>'), it is actually Kconfig.y. The standard __str__() +functions just avoid printing 'if y' conditions to give cleaner output. - tokens = self._tokenize(line, False, filename, linenr) - t0 = tokens.get_next() - if t0 is None: - continue +Feedback +======== - # Cases are ordered roughly by frequency, which speeds things up a - # bit +Send bug reports, suggestions, and questions to ulfalizer a.t Google's email +service, or open a ticket on the GitHub page. +""" +import errno +import os +import platform +import re +import sys - if t0 == _T_DEPENDS: - if not tokens.check(_T_ON): - _parse_error(line, 'expected "on" after "depends"', - filename, linenr) +# File layout: +# +# Public classes +# Public functions +# Internal functions +# Public global constants +# Internal global constants - depends_on_expr = \ - _make_and(depends_on_expr, - self._parse_expr(tokens, stmt, line, filename, - linenr, True)) +# Line length: 79 columns - elif t0 == _T_HELP: - # Find first non-blank (not all-space) line and get its - # indentation - line = line_feeder.next_nonblank() - if line is None: - stmt._help = "" - break - indent = _indentation(line) - if indent == 0: - # If the first non-empty lines has zero indent, there is no - # help text - stmt._help = "" - line_feeder.unget() - break +# +# Public classes +# - # The help text goes on till the first non-empty line with less - # indent - help_lines = [_deindent(line, indent)] - while 1: - line = line_feeder.get_next() - if line is None or \ - (not line.isspace() and _indentation(line) < indent): - stmt._help = "".join(help_lines) - break - help_lines.append(_deindent(line, indent)) +class Kconfig(object): + """ + Represents a Kconfig configuration, e.g. for x86 or ARM. This is the set of + symbols, choices, and menu nodes appearing in the configuration. Creating + any number of Kconfig objects (including for different architectures) is + safe. Kconfiglib doesn't keep any global state. + + The following attributes are available. They should be treated as + read-only, and some are implemented through @property magic. + + syms: + A dictionary with all symbols in the configuration, indexed by name. Also + includes all symbols that are referenced in expressions but never + defined, except for constant (quoted) symbols. + + const_syms: + A dictionary like 'syms' for constant (quoted) symbols. + + named_choices: + A dictionary like 'syms' for named choices (choice FOO). This is for + completeness. I've never seen a named choice outside of the test suite. + + defined_syms: + A list with all defined symbols, in the same order as they appear in the + Kconfig files. Provided as a convenience. + + n/m/y: + The predefined constant symbols n/m/y. Also available in const_syms. + + modules: + The Symbol instance for the modules symbol. Currently hardcoded to + MODULES, which is backwards compatible. Kconfiglib will warn if + 'option modules' is set on some other symbol. Tell me if you need proper + 'option modules' support. + + 'modules' is never None. If the MODULES symbol is not explicitly defined, + its tri_value will be 0 (n), as expected. + + A simple way to enable modules is to do 'kconf.modules.set_value(2)' + (provided the MODULES symbol is defined and visible). Modules are + disabled by default in the kernel Kconfig files as of writing, though + nearly all defconfig files enable them (with 'CONFIG_MODULES=y'). + + defconfig_list: + The Symbol instance for the 'option defconfig_list' symbol, or None if no + defconfig_list symbol exists. The defconfig filename derived from this + symbol can be found in Kconfig.defconfig_filename. + + defconfig_filename: + The filename given by the defconfig_list symbol. This is taken from the + first 'default' with a satisfied condition where the specified file + exists (can be opened for reading). If a defconfig file foo/defconfig is + not found and $srctree was set when the Kconfig was created, + $srctree/foo/defconfig is looked up as well. + + References to Kconfig symbols ("$FOO") in the 'default' properties of the + defconfig_filename symbol are are expanded before the file is looked up. + + 'defconfig_filename' is None if either no defconfig_list symbol exists, + or if the defconfig_list symbol has no 'default' with a satisfied + condition that specifies a file that exists. + + Gotcha: scripts/kconfig/Makefile might pass --defconfig=<defconfig> to + scripts/kconfig/conf when running e.g. 'make defconfig'. This option + overrides the defconfig_list symbol, meaning defconfig_filename might not + always match what 'make defconfig' would use. + + top_node: + The menu node (see the MenuNode class) of the implicit top-level menu. + Acts as the root of the menu tree. + + mainmenu_text: + The prompt (title) of the top_node menu, with Kconfig variable references + ("$FOO") expanded. Defaults to "Linux Kernel Configuration" (like in the + C tools). Can be changed with the 'mainmenu' statement (see + kconfig-language.txt). + + srctree: + The value of the $srctree environment variable when the configuration was + loaded, or None if $srctree wasn't set. Kconfig and .config files are + looked up relative to $srctree if they are not found in the base path + (unless absolute paths are used). This is used to support out-of-tree + builds. The C tools use this environment variable in the same way. + + Changing $srctree after creating the Kconfig instance has no effect. Only + the value when the configuration is loaded matters. This avoids surprises + if multiple configurations are loaded with different values for $srctree. + + config_prefix: + The value of the $CONFIG_ environment variable when the configuration was + loaded. This is the prefix used (and expected) in .config files. Defaults + to "CONFIG_". Used in the same way in the C tools. + + Like for srctree, only the value of $CONFIG_ when the configuration is + loaded matters. + """ + __slots__ = ( + "_choices", + "_print_undef_assign", + "_print_warnings", + "_set_re_match", + "_unset_re_match", + "_warn_no_prompt", + "config_prefix", + "const_syms", + "defconfig_list", + "defined_syms", + "m", + "modules", + "n", + "named_choices", + "srctree", + "syms", + "top_node", + "y", + + # Parsing-related + "_parsing_kconfigs", + "_reuse_line", + "_file", + "_filename", + "_linenr", + "_filestack", + "_line", + "_tokens", + "_tokens_i", + "_has_tokens", + ) - if line is None: - break + # + # Public interface + # - line_feeder.unget() + def __init__(self, filename="Kconfig", warn=True): + """ + Creates a new Kconfig object by parsing Kconfig files. Raises + KconfigSyntaxError on syntax errors. Note that Kconfig files are not + the same as .config files (which store configuration symbol values). + + filename (default: "Kconfig"): + The base Kconfig file. For the Linux kernel, you'll want "Kconfig" + from the top-level directory, as environment variables will make sure + the right Kconfig is included from there (arch/$SRCARCH/Kconfig as of + writing). + + If you are using Kconfiglib via 'make scriptconfig', the filename of + the base base Kconfig file will be in sys.argv[1]. It's currently + always "Kconfig" in practice. + + The $srctree environment variable is used to look up Kconfig files if + set. See the class documentation. + + warn (default: True): + True if warnings related to this configuration should be printed to + stderr. This can be changed later with + Kconfig.enable/disable_warnings(). It is provided as a constructor + argument since warnings might be generated during parsing. + """ + self.srctree = os.environ.get("srctree") + + self.config_prefix = os.environ.get("CONFIG_") + if self.config_prefix is None: + self.config_prefix = "CONFIG_" + + # Regular expressions for parsing .config files, with the get() method + # assigned directly as a small optimization (microscopic in this case, + # but it's consistent with the other regexes) + self._set_re_match = re.compile(r"{}(\w+)=(.*)" + .format(self.config_prefix)).match + self._unset_re_match = re.compile(r"# {}(\w+) is not set" + .format(self.config_prefix)).match + + self._print_warnings = warn + self._print_undef_assign = False + + self.syms = {} + self.const_syms = {} + self.defined_syms = [] + self.named_choices = {} + # Used for quickly invalidating all choices + self._choices = [] - elif t0 == _T_SELECT: - if not isinstance(stmt, Symbol): - _parse_error(line, "only symbols can select", filename, - linenr) + for nmy in "n", "m", "y": + sym = Symbol() + sym.kconfig = self + sym.name = nmy + sym.is_constant = True + sym.orig_type = TRISTATE + sym._cached_tri_val = STR_TO_TRI[nmy] + + self.const_syms[nmy] = sym + + self.n = self.const_syms["n"] + self.m = self.const_syms["m"] + self.y = self.const_syms["y"] + + # Make n/m/y well-formed symbols + for nmy in "n", "m", "y": + sym = self.const_syms[nmy] + sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n + + # This is used to determine whether previously unseen symbols should be + # registered. They shouldn't be if we parse expressions after parsing, + # as part of Kconfig.eval_string(). + self._parsing_kconfigs = True + + self.modules = self._lookup_sym("MODULES") + self.defconfig_list = None + + # The only predefined symbol besides n/m/y. DEFCONFIG_LIST uses this as + # of writing. + uname_sym = self._lookup_const_sym("UNAME_RELEASE") + uname_sym.orig_type = STRING + # env_var doubles as the SYMBOL_AUTO flag from the C implementation, so + # just set it to something. The naming breaks a bit here. + uname_sym.env_var = "<uname release>" + uname_sym.defaults.append( + (self._lookup_const_sym(platform.uname()[2]), self.y)) + self.syms["UNAME_RELEASE"] = uname_sym + + self.top_node = MenuNode() + self.top_node.kconfig = self + self.top_node.item = MENU + self.top_node.visibility = self.y + self.top_node.prompt = ("Linux Kernel Configuration", self.y) + self.top_node.parent = None + self.top_node.dep = self.y + self.top_node.filename = filename + self.top_node.linenr = 1 - new_selects.append( - (tokens.get_next(), - self._parse_cond(tokens, stmt, line, filename, linenr))) + # Parse the Kconfig files - elif t0 == _T_IMPLY: - if not isinstance(stmt, Symbol): - _parse_error(line, "only symbols can imply", filename, - linenr) + # These implement a single line of "unget" for the parser + self._reuse_line = False + self._has_tokens = False - new_implies.append( - (tokens.get_next(), - self._parse_cond(tokens, stmt, line, filename, linenr))) + # Keeps track of the location in the parent Kconfig files. Kconfig + # files usually source other Kconfig files. + self._filestack = [] - elif t0 in (_T_BOOL, _T_TRISTATE, _T_INT, _T_HEX, _T_STRING): - stmt._type = _TOKEN_TO_TYPE[t0] - if tokens.peek_next() is not None: - new_prompt = self._parse_val_and_cond(tokens, stmt, line, - filename, linenr) + # The current parsing location + self._filename = filename + self._linenr = 0 - elif t0 == _T_DEFAULT: - new_def_exprs.append( - self._parse_val_and_cond( - tokens, stmt, line, filename, linenr)) + self._file = self._open(filename) - elif t0 in (_T_DEF_BOOL, _T_DEF_TRISTATE): - stmt._type = _TOKEN_TO_TYPE[t0] - if tokens.peek_next() is not None: - new_def_exprs.append( - self._parse_val_and_cond(tokens, stmt, line, filename, - linenr)) + self._parse_block(None, # end_token + self.top_node, # parent + self.y, # visible_if_deps + self.top_node) # prev_node + self.top_node.list = self.top_node.next + self.top_node.next = None - elif t0 == _T_PROMPT: - # 'prompt' properties override each other within a single - # definition of a symbol, but additional prompts can be added - # by defining the symbol multiple times; hence 'new_prompt' - # instead of 'prompt'. - new_prompt = self._parse_val_and_cond(tokens, stmt, line, - filename, linenr) + self._parsing_kconfigs = False - elif t0 == _T_RANGE: - new_ranges.append( - (tokens.get_next(), - tokens.get_next(), - self._parse_cond(tokens, stmt, line, filename, linenr))) + # Do various post-processing of the menu tree + _finalize_tree(self.top_node) - elif t0 == _T_OPTION: - if tokens.check(_T_ENV) and tokens.check(_T_EQUAL): - env_var = tokens.get_next() + # Build Symbol._dependents for all symbols + self._build_dep() - stmt._is_special = True - stmt._is_from_env = True + self._warn_no_prompt = False - if env_var not in os.environ: - self._warn("the symbol {} references the non-existent " - "environment variable {} and will get the " - "empty string as its value. If you're " - "using Kconfiglib via " - "'make (i)scriptconfig', it should have " - "set up the environment correctly for you. " - "If you still got this message, that " - "might be an error, and you should email " - "ulfalizer a.t Google's email service.""" - .format(stmt._name, env_var), - filename, linenr) - - stmt._cached_val = "" - else: - stmt._cached_val = os.environ[env_var] + @property + def mainmenu_text(self): + """ + See the class documentation. + """ + return self._expand_syms(self.top_node.prompt[0]) - elif tokens.check(_T_DEFCONFIG_LIST): - if self._defconfig_sym is None: - self._defconfig_sym = stmt - else: - self._warn("'option defconfig_list' set on multiple " - "symbols ({0} and {1}). Only {0} will be " - "used." - .format(self._defconfig_sym._name, - stmt._name)) + @property + def defconfig_filename(self): + """ + See the class documentation. + """ + if not self.defconfig_list: + return None - elif tokens.check(_T_MODULES): - # To reduce warning spam, only warn if 'option modules' is - # set on some symbol that isn't MODULES, which should be - # safe. I haven't run into any projects that make use - # modules besides the kernel yet, and there it's likely to - # keep being called "MODULES". - if stmt._name != "MODULES": - self._warn("the 'modules' option is not supported. " - "Let me know if this is a problem for you; " - "it shouldn't be that hard to implement. " - "(Note that modules are still supported -- " - "Kconfiglib just assumes the symbol name " - "MODULES, like older versions of the C " - "implementation did when 'option modules' " - "wasn't used.)", - filename, linenr) + for filename, cond in self.defconfig_list.defaults: + if expr_value(cond): + try: + with self._open(self._expand_syms(filename.str_value)) as f: + return f.name + except IOError: + continue - elif tokens.check(_T_ALLNOCONFIG_Y): - if not isinstance(stmt, Symbol): - _parse_error(line, - "the 'allnoconfig_y' option is only " - "valid for symbols", - filename, linenr) - stmt._allnoconfig_y = True + return None - else: - _parse_error(line, "unrecognized option", filename, linenr) + def load_config(self, filename, replace=True): + """ + Loads symbol values from a file in the .config format. Equivalent to + calling Symbol.set_value() to set each of the values. - elif t0 == _T_VISIBLE: - if not tokens.check(_T_IF): - _parse_error(line, 'expected "if" after "visible"', - filename, linenr) - if not isinstance(stmt, Menu): - _parse_error(line, - "'visible if' is only valid for menus", - filename, linenr) - - stmt._visible_if_expr = \ - _make_and(stmt._visible_if_expr, - self._parse_expr(tokens, stmt, line, filename, - linenr, True)) + "# CONFIG_FOO is not set" within a .config file sets the user value of + FOO to n. The C tools work the same way. - elif t0 == _T_OPTIONAL: - if not isinstance(stmt, Choice): - _parse_error(line, - '"optional" is only valid for choices', - filename, - linenr) - stmt._optional = True + filename: + The file to load. Respects $srctree if set (see the class + documentation). - else: - # See the _end_line description in Config.__init__() - self._end_line = line - tokens.unget_all() - self._end_line_tokens = tokens - break + replace (default: True): + True if all existing user values should be cleared before loading the + .config. + """ + # Disable the warning about assigning to symbols without prompts. This + # is normal and expected within a .config file. + self._warn_no_prompt = False + + # This stub only exists to make sure _warn_no_prompt gets reenabled + try: + self._load_config(filename, replace) + finally: + self._warn_no_prompt = True + + def _load_config(self, filename, replace): + with self._open(filename) as f: + if replace: + # If we're replacing the configuration, keep track of which + # symbols and choices got set so that we can unset the rest + # later. This avoids invalidating everything and is a tiny bit + # faster in the test suite. The main benefit though is that + # invalidation must be rock solid for it to work, making it a + # good test. + + for sym in self.defined_syms: + sym._was_set = False + + for choice in self._choices: + choice._was_set = False + + # Small optimizations + set_re_match = self._set_re_match + unset_re_match = self._unset_re_match + syms = self.syms + + for linenr, line in enumerate(f, 1): + # The C tools ignore trailing whitespace + line = line.rstrip() + + set_match = set_re_match(line) + if set_match: + name, val = set_match.groups() + if name not in syms: + self._warn_undef_assign_load(name, val, filename, + linenr) + continue - # Done parsing properties. Now add the new - # prompts/defaults/selects/implies/ranges, with dependencies - # propagated. + sym = syms[name] + if not sym.nodes: + self._warn_undef_assign_load(name, val, filename, + linenr) + continue - # Save original dependencies from enclosing menus and ifs - stmt._deps_from_containing = deps + if sym.orig_type in (BOOL, TRISTATE): + # The C implementation only checks the first character + # to the right of '=', for whatever reason + if not ((sym.orig_type == BOOL and + val.startswith(("n", "y"))) or \ + (sym.orig_type == TRISTATE and + val.startswith(("n", "m", "y")))): + self._warn("'{}' is not a valid value for the {} " + "symbol {}. Assignment ignored." + .format(val, TYPE_TO_STR[sym.orig_type], + sym.name)) + continue + + # We represent tristate values as 0, 1, 2 + val = STR_TO_TRI[val[0]] + + if sym.choice and val: + # During .config loading, we infer the mode of the + # choice from the kind of values that are assigned + # to the choice symbols + + prev_mode = sym.choice.user_value + if prev_mode is not None and prev_mode != val: + self._warn("both m and y assigned to symbols " + "within the same choice", + filename, linenr) + + # Set the choice's mode + # TODO: this causes redundant invalidation + sym.choice.set_value(val) + + elif sym.orig_type == STRING: + string_match = _conf_string_re_match(val) + if not string_match: + self._warn("Malformed string literal in " + "assignment to {}. Assignment ignored." + .format(sym.name), + filename, linenr) + continue + + val = unescape(string_match.group(1)) - # The parent deps + the 'depends on' deps. This is also used to - # implicitly create menus when a symbol depends on the previous symbol, - # hence the name. In the C implementation, it's the dependency of a - # menu "node". - stmt._menu_dep = _make_and(deps, depends_on_expr) + else: + unset_match = unset_re_match(line) + if not unset_match: + continue - if isinstance(stmt, (Menu, Comment)): - # For display purposes - stmt._orig_deps = depends_on_expr - else: - # Symbol or Choice + name = unset_match.group(1) + if name not in syms: + self._warn_undef_assign_load(name, "n", filename, + linenr) + continue - if isinstance(stmt, Symbol): - stmt._direct_deps = _make_or(stmt._direct_deps, stmt._menu_dep) + sym = syms[name] + if sym.orig_type not in (BOOL, TRISTATE): + continue - # Propagate dependencies to prompts - if new_prompt is not None: - prompt, cond_expr = new_prompt + val = 0 - # Propagate 'visible if' and 'depends on' - cond_expr = _make_and(_make_and(cond_expr, visible_if_deps), - depends_on_expr) + # Done parsing the assignment. Set the value. - # Version without parent dependencies, for display - stmt._orig_prompts.append((prompt, cond_expr)) + if sym._was_set: + # Use strings for tristate values in the warning + if sym.orig_type in (BOOL, TRISTATE): + display_val = TRI_TO_STR[val] + display_user_val = TRI_TO_STR[sym.user_value] + else: + display_val = val + display_user_val = sym.user_value - # This is what we actually use for evaluation - stmt._prompts.append((prompt, _make_and(cond_expr, deps))) + self._warn('{} set more than once. Old value: "{}", new ' + 'value: "{}".' + .format(name, display_user_val, display_val), + filename, linenr) - # Propagate dependencies to defaults - for val_expr, cond_expr in new_def_exprs: - # Version without parent dependencies, for display - stmt._orig_def_exprs.append( - (val_expr, _make_and(cond_expr, depends_on_expr))) + sym.set_value(val) - # This is what we actually use for evaluation - stmt._def_exprs.append( - (val_expr, _make_and(cond_expr, stmt._menu_dep))) + if replace: + # If we're replacing the configuration, unset the symbols that + # didn't get set - # Propagate dependencies to ranges - for low, high, cond_expr in new_ranges: - # Version without parent dependencies, for display - stmt._orig_ranges.append( - (low, high, _make_and(cond_expr, depends_on_expr))) + for sym in self.defined_syms: + if not sym._was_set: + sym.unset_value() - # This is what we actually use for evaluation - stmt._ranges.append( - (low, high, _make_and(cond_expr, stmt._menu_dep))) + for choice in self._choices: + if not choice._was_set: + choice.unset_value() - # Handle selects - for target, cond_expr in new_selects: - # Used for display - stmt._orig_selects.append( - (target, _make_and(cond_expr, depends_on_expr))) + def write_config(self, filename, + header="# Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib)\n"): + r""" + Writes out symbol values in the .config format. - # Modify the dependencies of the selected symbol - target._rev_dep = \ - _make_or(target._rev_dep, - _make_and(stmt, _make_and(cond_expr, - stmt._menu_dep))) + filename: + Self-explanatory. - # Handle implies - for target, cond_expr in new_implies: - # Used for display - stmt._orig_implies.append( - (target, _make_and(cond_expr, depends_on_expr))) + header (default: "# Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib)\n"): + Text that will be inserted verbatim at the beginning of the file. You + would usually want each line to start with '#' to make it a comment, + and include a final terminating newline. + """ + with open(filename, "w") as f: + f.write(header) + f.writelines(self._get_config_strings()) - # Modify the dependencies of the implied symbol - target._weak_rev_dep = \ - _make_or(target._weak_rev_dep, - _make_and(stmt, _make_and(cond_expr, - stmt._menu_dep))) + def eval_string(self, s): + """ + Returns the tristate value of the expression 's', represented as 0, 1, + and 2 for n, m, and y, respectively. Raises KconfigSyntaxError if + syntax errors are detected in 's'. Warns if undefined symbols are + referenced. + + As an example, if FOO and BAR are tristate symbols at least one of + which has the value y, then config.eval_string("y && (FOO || BAR)") + returns 2 (y). + + To get the string value of non-bool/tristate symbols, use + Symbol.str_value. eval_string() always returns a tristate value, and + all non-bool/tristate symbols have the tristate value 0 (n). + + The expression parsing is consistent with how parsing works for + conditional ('if ...') expressions in the configuration, and matches + the C implementation. m is rewritten to 'm && MODULES', so + eval_string("m") will return 0 (n) unless modules are enabled. + """ + # The parser is optimized to be fast when parsing Kconfig files (where + # an expression can never appear at the beginning of a line). We have + # to monkey-patch things a bit here to reuse it. - def _parse_expr(self, feed, cur_item, line, filename, linenr, transform_m): - """Parses an expression from the tokens in 'feed' using a simple - top-down approach. The result has the form - '(<operator> <operand 1> <operand 2>)' where <operator> is e.g. - kconfiglib._AND. If there is only one operand (i.e., no && or ||), then - the operand is returned directly. This also goes for subexpressions. + self._filename = None - As an example, A && B && (!C || D == 3) is represented as the tuple - structure (_AND, A, (_AND, B, (_OR, (_NOT, C), (_EQUAL, D, 3)))), with - the Symbol objects stored directly in the expression. + self._line = "if " + s + self._tokenize() + # Remove the "if " to avoid giving confusing error messages + self._line = s + # Remove the T_IF token + del self._tokens[0] - feed: _Feed instance containing the tokens for the expression. + return expr_value(self._parse_expr(True)) # transform_m - cur_item: The item (Symbol, Choice, Menu, or Comment) currently being - parsed, or None if we're not parsing an item. Used for recording - references to symbols. + def unset_values(self): + """ + Resets the user values of all symbols, as if Kconfig.load_config() or + Symbol.set_value() had never been called. + """ + self._warn_no_prompt = False + try: + # set_value() already rejects undefined symbols, and they don't + # need to be invalidated (because their value never changes), so we + # can just iterate over defined symbols + for sym in self.defined_syms: + sym.unset_value() + + for choice in self._choices: + choice.unset_value() + finally: + self._warn_no_prompt = True + + def enable_warnings(self): + """ + See Kconfig.__init__(). + """ + self._print_warnings = True - line: The line containing the expression being parsed. + def disable_warnings(self): + """ + See Kconfig.__init__(). + """ + self._print_warnings = False - filename: The file containing the expression. None when using - Config.eval(). + def enable_undef_warnings(self): + """ + Enables warnings for assignments to undefined symbols. Printed to + stderr. Disabled by default since they tend to be spammy for Kernel + configurations (and mostly suggests cleanups). + """ + self._print_undef_assign = True - linenr: The line number containing the expression. None when using - Config.eval(). + def disable_undef_warnings(self): + """ + See enable_undef_assign(). + """ + self._print_undef_assign = False - transform_m (default: False): Determines if 'm' should be rewritten to - 'm && MODULES'. See the Config.eval() docstring.""" + def __repr__(self): + """ + Returns a string with information about the Kconfig object when it is + evaluated on e.g. the interactive Python prompt. + """ + return "<{}>".format(", ".join(( + "configuration with {} symbols".format(len(self.syms)), + 'main menu prompt "{}"'.format(self.mainmenu_text), + "srctree not set" if self.srctree is None else + 'srctree "{}"'.format(self.srctree), + 'config symbol prefix "{}"'.format(self.config_prefix), + "warnings " + ("enabled" if self._print_warnings else "disabled"), + "undef. symbol assignment warnings " + + ("enabled" if self._print_undef_assign else "disabled"), + ))) - # Grammar: - # - # expr: and_expr ['||' expr] - # and_expr: factor ['&&' and_expr] - # factor: <symbol> ['='/'!='/'<'/... <symbol>] - # '!' factor - # '(' expr ')' - # - # It helps to think of the 'expr: and_expr' case as a single-operand OR - # (no ||), and of the 'and_expr: factor' case as a single-operand AND - # (no &&). Parsing code is always a bit tricky. + # + # Private methods + # - # Mind dump: parse_factor() and two nested loops for OR and AND would - # work as well. The straightforward implementation there gives a - # (op, (op, (op, A, B), C), D) parse for A op B op C op D. Representing - # expressions as (op, [list of operands]) instead goes nicely with that - # version, but is wasteful for short expressions and complicates - # expression evaluation and other code that works on expressions (more - # complicated code likely offsets any performance gain from less - # recursion too). If we also try to optimize the list representation by - # merging lists when possible (e.g. when ANDing two AND expressions), - # we end up allocating a ton of lists instead of reusing expressions, - # which is bad. - and_expr = self._parse_and_expr(feed, cur_item, line, filename, - linenr, transform_m) + # + # File reading + # - # Return 'and_expr' directly if we have a "single-operand" OR. - # Otherwise, parse the expression on the right and make an _OR node. - # This turns A || B || C || D into - # (_OR, A, (_OR, B, (_OR, C, D))). - return and_expr \ - if not feed.check(_T_OR) else \ - (_OR, and_expr, self._parse_expr(feed, cur_item, line, filename, - linenr, transform_m)) + def _open(self, filename): + """ + First tries to open 'filename', then '$srctree/filename' if $srctree + was set when the configuration was loaded. + """ + try: + return open(filename) + except IOError as e: + if not os.path.isabs(filename) and self.srctree is not None: + filename = os.path.join(self.srctree, filename) + try: + return open(filename) + except IOError as e2: + # This is needed for Python 3, because e2 is deleted after + # the try block: + # + # https://docs.python.org/3/reference/compound_stmts.html#the-try-statement + e = e2 + + raise IOError( + "Could not open '{}' ({}: {}). Perhaps the $srctree " + "environment variable (which was {}) is set incorrectly. Note " + "that the current value of $srctree is saved when the Kconfig " + "instance is created (for consistency and to cleanly " + "separate instances)." + .format(filename, errno.errorcode[e.errno], e.strerror, + "unset" if self.srctree is None else + '"{}"'.format(self.srctree))) + + def _enter_file(self, filename): + """ + Jumps to the beginning of a sourced Kconfig file, saving the previous + position and file object. + """ + self._filestack.append((self._file, self._filename, self._linenr)) + try: + self._file = self._open(filename) + except IOError as e: + # Extend the error message a bit in this case + raise IOError( + "{}:{}: {} Also note that e.g. $FOO in a 'source' " + "statement does not refer to the environment " + "variable FOO, but rather to the Kconfig Symbol FOO " + "(which would commonly have 'option env=\"FOO\"' in " + "its definition)." + .format(self._filename, self._linenr, e.message)) + + self._filename = filename + self._linenr = 0 + + def _leave_file(self): + """ + Returns from a Kconfig file to the file that sourced it. + """ + self._file.close() + self._file, self._filename, self._linenr = self._filestack.pop() - def _parse_and_expr(self, feed, cur_item, line, filename, linenr, - transform_m): + def _next_line(self): + """ + Returns the next line in the current file, or the empty string at EOF + (like the standard readline() function). + """ + # This provides a single line of "unget" if _reuse_line is set to True + if not self._reuse_line: + self._line = self._file.readline() + self._linenr += 1 - factor = self._parse_factor(feed, cur_item, line, filename, linenr, - transform_m) + self._reuse_line = False - # Return 'factor' directly if we have a "single-operand" AND. - # Otherwise, parse the right operand and make an _AND node. This turns - # A && B && C && D into (_AND, A, (_AND, B, (_AND, C, D))). - return factor \ - if not feed.check(_T_AND) else \ - (_AND, factor, self._parse_and_expr(feed, cur_item, line, - filename, linenr, - transform_m)) + # Handle line joining + while self._line.endswith("\\\n"): + self._line = self._line[:-2] + self._file.readline() + self._linenr += 1 - def _parse_factor(self, feed, cur_item, line, filename, linenr, - transform_m): - token = feed.get_next() + return self._line - if isinstance(token, (Symbol, str)): - # Plain symbol or relation + def _next_line_no_join(self): + """ + Used for help texts, which don't do line joining. + """ + self._line = self._file.readline() + self._linenr += 1 + return self._line - next_token = feed.peek_next() - if next_token not in _TOKEN_TO_RELATION: - # Plain symbol - # For conditional expressions ('depends on <expr>', - # '... if <expr>', etc.), "m" and m are rewritten to - # "m" && MODULES. - if transform_m and (token is self._m or token == "m"): - return (_AND, "m", self._lookup_sym("MODULES")) + # + # Tokenization + # - return token + def _lookup_sym(self, name): + """ + Fetches the symbol 'name' from the symbol table, creating and + registering it if it does not exist. If '_parsing_configs' is False, it + means we're in eval_string(), and new symbols won't be registered. + """ + if name in self.syms: + return self.syms[name] - # Relation - return (_TOKEN_TO_RELATION[feed.get_next()], - token, - feed.get_next()) + sym = Symbol() + sym.kconfig = self + sym.name = name + sym.is_constant = False + sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n - if token == _T_NOT: - return (_NOT, self._parse_factor(feed, cur_item, line, filename, - linenr, transform_m)) + if self._parsing_kconfigs: + self.syms[name] = sym + else: + self._warn("no symbol {} in configuration".format(name)) - if token == _T_OPEN_PAREN: - expr_parse = self._parse_expr(feed, cur_item, line, filename, - linenr, transform_m) - if not feed.check(_T_CLOSE_PAREN): - _parse_error(line, "missing end parenthesis", filename, linenr) - return expr_parse + return sym - _parse_error(line, "malformed expression", filename, linenr) + def _lookup_const_sym(self, name): + """ + Like _lookup_sym(), for constant (quoted) symbols + """ + if name in self.const_syms: + return self.const_syms[name] - def _tokenize(self, s, for_eval, filename=None, linenr=None): - """Returns a _Feed instance containing tokens derived from the string - 's'. Registers any new symbols encountered (via _lookup_sym()). + sym = Symbol() + sym.kconfig = self + sym.name = name + sym.is_constant = True + sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n - Tries to be reasonably speedy by processing chunks of text via regexes - and string operations where possible. This is a hotspot during parsing. + if self._parsing_kconfigs: + self.const_syms[name] = sym - for_eval: True when parsing an expression for a call to Config.eval(), - in which case we should not treat the first token specially nor - register new symbols.""" + return sym + + def _tokenize(self): + """ + Parses Kconfig._line, putting the tokens in Kconfig._tokens. Registers + any new symbols encountered with _lookup(_const)_sym(). + + Tries to be reasonably speedy by processing chunks of text via regexes + and string operations where possible. This is the biggest hotspot + during parsing. + """ + s = self._line # Tricky implementation detail: While parsing a token, 'token' refers - # to the previous token. See _NOT_REF for why this is needed. + # to the previous token. See _STRING_LEX for why this is needed. - if for_eval: - token = None - tokens = [] + # See comment at _initial_token_re_match definition + initial_token_match = _initial_token_re_match(s) + if not initial_token_match: + self._tokens = (None,) + self._tokens_i = -1 + return - # The current index in the string being tokenized - i = 0 + keyword = _get_keyword(initial_token_match.group(1)) - else: - # See comment at _initial_token_re_match definition - initial_token_match = _initial_token_re_match(s) - if not initial_token_match: - return _Feed(()) - - keyword = _get_keyword(initial_token_match.group(1)) - if keyword == _T_HELP: - # Avoid junk after "help", e.g. "---", being registered as a - # symbol - return _Feed((_T_HELP,)) - if keyword is None: - # We expect a keyword as the first token - _tokenization_error(s, filename, linenr) - - token = keyword - tokens = [keyword] - # The current index in the string being tokenized - i = initial_token_match.end() + if keyword == _T_HELP: + # Avoid junk after "help", e.g. "---", being registered as a + # symbol + self._tokens = (_T_HELP, None) + self._tokens_i = -1 + return + + if keyword is None: + self._parse_error("expected keyword as first token") + + token = keyword + self._tokens = [keyword] + # The current index in the string being tokenized + i = initial_token_match.end() # Main tokenization loop (for tokens past the first one) while i < len(s): @@ -1337,15 +1131,15 @@ class Config(object): # It's a keyword token = keyword - elif token not in _NOT_REF: - # It's a symbol reference - token = self._lookup_sym(name, for_eval) - token._ref_locations.append((filename, linenr)) - - elif token == _T_CONFIG: - # It's a symbol definition - token = self._lookup_sym(name, for_eval) - token._def_locations.append((filename, linenr)) + elif token not in _STRING_LEX: + # It's a non-const symbol... + if name in ("n", "m", "y"): + # ...except we translate n, m, and y into the + # corresponding constant symbols, like the C + # implementation + token = self.const_syms[name] + else: + token = self._lookup_sym(name) else: # It's a case of missing quotes. For example, the @@ -1360,7 +1154,7 @@ class Config(object): token = name else: - # Not an identifier/keyword + # Not keyword/non-const symbol # Note: _id_keyword_match and _initial_token_match strip # trailing whitespace, making it safe to assume s[i] is the @@ -1378,44 +1172,63 @@ class Config(object): if c in "\"'": # String literal/constant symbol if "\\" not in s: - # Fast path: If the string contains no backslashes, we + # Fast path: If the line contains no backslashes, we # can just find the matching quote. + end = s.find(c, i) if end == -1: - _tokenization_error(s, filename, linenr) - token = s[i:end] + self._parse_error("unterminated string") + + val = s[i:end] i = end + 1 else: - # Slow path: This could probably be sped up, but it's a - # very unusual case anyway. + # Slow path for lines with backslashes (very rare, + # performance irrelevant) + quote = c val = "" + while 1: if i >= len(s): - _tokenization_error(s, filename, linenr) + self._parse_error("unterminated string") + c = s[i] if c == quote: break + if c == "\\": if i + 1 >= len(s): - _tokenization_error(s, filename, linenr) + self._parse_error("unterminated string") + val += s[i + 1] i += 2 else: val += c i += 1 + i += 1 - token = val + + # This is the only place where we don't survive with a + # single token of lookback: 'option env="FOO"' does not + # refer to a constant symbol named "FOO". + token = val \ + if token in _STRING_LEX or \ + self._tokens[0] == _T_OPTION else \ + self._lookup_const_sym(val) elif c == "&": - # Invalid characters are ignored - if i >= len(s) or s[i] != "&": continue + # Invalid characters are ignored (backwards-compatible) + if i >= len(s) or s[i] != "&": + continue + token = _T_AND i += 1 elif c == "|": - # Invalid characters are ignored - if i >= len(s) or s[i] != "|": continue + # Invalid characters are ignored (backwards-compatible) + if i >= len(s) or s[i] != "|": + continue + token = _T_OR i += 1 @@ -1435,7 +1248,8 @@ class Config(object): elif c == ")": token = _T_CLOSE_PAREN - elif c == "#": break # Comment + elif c == "#": + break # Very rare elif c == "<": @@ -1454,2085 +1268,2423 @@ class Config(object): token = _T_GREATER else: - # Invalid characters are ignored + # Invalid characters are ignored (backwards-compatible) continue # Skip trailing whitespace while i < len(s) and s[i].isspace(): i += 1 - tokens.append(token) + self._tokens.append(token) - return _Feed(tokens) + # None-terminating token streams makes the token fetching functions + # simpler/faster + self._tokens.append(None) + self._tokens_i = -1 - def _lookup_sym(self, name, for_eval=False): - """Fetches the symbol 'name' from the symbol table, creating and - registering it if it does not exist. If 'for_eval' is True, the symbol - won't be added to the symbol table if it does not exist -- this is for - Config.eval().""" - if name in self._syms: - return self._syms[name] + def _next_token(self): + self._tokens_i += 1 + return self._tokens[self._tokens_i] - new_sym = Symbol() - new_sym._config = self - new_sym._name = name - if for_eval: - self._warn("no symbol {} in configuration".format(name)) - else: - self._syms[name] = new_sym - return new_sym + def _peek_token(self): + return self._tokens[self._tokens_i + 1] - # - # Expression evaluation - # + def _check_token(self, token): + """ + If the next token is 'token', removes it and returns True. + """ + if self._tokens[self._tokens_i + 1] == token: + self._tokens_i += 1 + return True + return False - def _eval_expr(self, expr): - """Evaluates an expression to "n", "m", or "y".""" - - # Handles e.g. an "x if y" condition where the "if y" part is missing. - if expr is None: - return "y" - - res = self._eval_expr_rec(expr) - if res == "m": - # Promote "m" to "y" if we're running without modules. - # - # Internally, "m" is often rewritten to "m" && MODULES by both the - # C implementation and Kconfiglib, which takes care of cases where - # "m" should be demoted to "n" instead. - modules_sym = self._syms.get("MODULES") - if modules_sym is None or modules_sym.get_value() != "y": - return "y" - return res - - def _eval_expr_rec(self, expr): - if isinstance(expr, Symbol): - # Non-bool/tristate symbols are always "n" in a tristate sense, - # regardless of their value - return expr.get_value() if expr._type in (BOOL, TRISTATE) else "n" - - if isinstance(expr, str): - return expr if expr in ("m", "y") else "n" - - if expr[0] == _AND: - ev1 = self._eval_expr_rec(expr[1]) - if ev1 == "n": - return "n" - ev2 = self._eval_expr_rec(expr[2]) - return ev2 if ev1 == "y" else \ - "m" if ev2 != "n" else \ - "n" - - if expr[0] == _OR: - ev1 = self._eval_expr_rec(expr[1]) - if ev1 == "y": - return "y" - ev2 = self._eval_expr_rec(expr[2]) - return ev2 if ev1 == "n" else \ - "y" if ev2 == "y" else \ - "m" - - if expr[0] == _NOT: - ev = self._eval_expr_rec(expr[1]) - return "n" if ev == "y" else \ - "y" if ev == "n" else \ - "m" - - if expr[0] in _RELATIONS: - # Implements <, <=, >, >= comparisons as well. These were added to - # kconfig in 31847b67 (kconfig: allow use of relations other than - # (in)equality). - - # This mirrors the C implementation pretty closely. Perhaps there's - # a more pythonic way to structure this. - - oper, op1, op2 = expr - op1_type, op1_str = _type_and_val(op1) - op2_type, op2_str = _type_and_val(op2) - - # If both operands are strings... - if op1_type == STRING and op2_type == STRING: - # ...then compare them lexicographically - comp = _strcmp(op1_str, op2_str) - else: - # Otherwise, try to compare them as numbers - try: - comp = int(op1_str, _TYPE_TO_BASE[op1_type]) - \ - int(op2_str, _TYPE_TO_BASE[op2_type]) - except ValueError: - # They're not both valid numbers. If the comparison is - # anything but = or !=, return 'n'. Otherwise, reuse - # _strcmp() to check for (in)equality. - if oper not in (_EQUAL, _UNEQUAL): - return "n" - comp = _strcmp(op1_str, op2_str) - - if oper == _EQUAL: res = comp == 0 - elif oper == _UNEQUAL: res = comp != 0 - elif oper == _LESS: res = comp < 0 - elif oper == _LESS_EQUAL: res = comp <= 0 - elif oper == _GREATER: res = comp > 0 - elif oper == _GREATER_EQUAL: res = comp >= 0 - - return "y" if res else "n" - - _internal_error("Internal error while evaluating expression: " - "unknown operation {}.".format(expr[0])) - - def _eval_min(self, e1, e2): - """Returns the minimum value of the two expressions. Equates None with - 'y'.""" - e1_eval = self._eval_expr(e1) - e2_eval = self._eval_expr(e2) - return e1_eval if tri_less(e1_eval, e2_eval) else e2_eval - - def _eval_max(self, e1, e2): - """Returns the maximum value of the two expressions. Equates None with - 'y'.""" - e1_eval = self._eval_expr(e1) - e2_eval = self._eval_expr(e2) - return e1_eval if tri_greater(e1_eval, e2_eval) else e2_eval # - # Dependency tracking (for caching and invalidation) + # Parsing # - def _build_dep(self): - """Populates the Symbol._direct_dependents sets, linking the symbol to - the symbols that immediately depend on it in the sense that changing - the value of the symbol might affect the values of those other symbols. - This is used for caching/invalidation purposes. The calculated sets - might be larger than necessary as we don't do any complicated analysis - of the expressions.""" - - # Adds 'sym' as a directly dependent symbol to all symbols that appear - # in the expression 'e' - def add_expr_deps(expr, sym): - res = [] - _expr_syms(expr, res) - for expr_sym in res: - expr_sym._direct_dependents.add(sym) - - # The directly dependent symbols of a symbol S are: - # - # - Any symbols whose prompts, default values, _rev_dep (select - # condition), _weak_rev_dep (imply condition) or ranges depend on S - # - # - Any symbol that has S as a direct dependency (has S in - # _direct_deps). This is needed to get invalidation right for - # 'imply'. - # - # - Any symbols that belong to the same choice statement as S - # (these won't be included in S._direct_dependents as that makes the - # dependency graph unwieldy, but S._get_dependent() will include - # them) - # - # - Any symbols in a choice statement that depends on S - - # Only calculate _direct_dependents for defined symbols. Undefined - # symbols could theoretically be selected/implied, but it wouldn't - # change their value (they always evaluate to their name), so it's not - # a true dependency. - - for sym in self._defined_syms: - for _, e in sym._prompts: - add_expr_deps(e, sym) - - for v, e in sym._def_exprs: - add_expr_deps(v, sym) - add_expr_deps(e, sym) - - add_expr_deps(sym._rev_dep, sym) - add_expr_deps(sym._weak_rev_dep, sym) - - for l, u, e in sym._ranges: - add_expr_deps(l, sym) - add_expr_deps(u, sym) - add_expr_deps(e, sym) - - add_expr_deps(sym._direct_deps, sym) - - if sym._is_choice_sym: - choice = sym._parent - for _, e in choice._prompts: - add_expr_deps(e, sym) - for _, e in choice._def_exprs: - add_expr_deps(e, sym) - - def _eq_to_sym(self, eq): - """_expr_depends_on() helper. For (in)equalities of the form sym = y/m - or sym != n, returns sym. For other (in)equalities, returns None.""" - relation, left, right = eq - - def transform_y_m_n(item): - if item is self._y: return "y" - if item is self._m: return "m" - if item is self._n: return "n" - return item - - left = transform_y_m_n(left) - right = transform_y_m_n(right) - - # Make sure the symbol (if any) appears to the left - if not isinstance(left, Symbol): - left, right = right, left - if not isinstance(left, Symbol): - return None - if (relation == _EQUAL and right in ("m", "y")) or \ - (relation == _UNEQUAL and right == "n"): - return left - return None + def _make_and(self, e1, e2): + """ + Constructs an AND (&&) expression. Performs trivial simplification. + """ + if e1 is self.y: + return e2 - def _expr_depends_on(self, expr, sym): - """Reimplementation of expr_depends_symbol() from mconf.c. Used to - determine if a submenu should be implicitly created, which influences - what items inside choice statements are considered choice items.""" - if expr is None: - return False + if e2 is self.y: + return e1 - def rec(expr): - if isinstance(expr, str): - return False - if isinstance(expr, Symbol): - return expr is sym + if e1 is self.n or e2 is self.n: + return self.n - if expr[0] in (_EQUAL, _UNEQUAL): - return self._eq_to_sym(expr) is sym - if expr[0] == _AND: - return rec(expr[1]) or rec(expr[2]) - return False + return (AND, e1, e2) - return rec(expr) + def _make_or(self, e1, e2): + """ + Constructs an OR (||) expression. Performs trivial simplification. + """ + if e1 is self.n: + return e2 - def _invalidate_all(self): - # Undefined symbols never change value and don't need to be - # invalidated, so we can just iterate over defined symbols - for sym in self._defined_syms: - sym._invalidate() + if e2 is self.n: + return e1 - # - # Printing and misc. - # + if e1 is self.y or e2 is self.y: + return self.y + + return (OR, e1, e2) + + def _parse_block(self, end_token, parent, visible_if_deps, prev_node): + """ + Parses a block, which is the contents of either a file or an if, menu, + or choice statement. + + end_token: + The token that ends the block, e.g. _T_ENDIF ("endif") for ifs. None + for files. + + parent: + The parent menu node, corresponding to e.g. a menu or Choice. Can + also be a Symbol, due to automatic submenu creation from + dependencies. + + visible_if_deps: + 'visible if' dependencies from enclosing menus. Propagated to Symbol + and Choice prompts. + + prev_node: + The previous menu node. New nodes will be added after this one (by + modifying their 'next' pointer). + + prev_node is reused to parse a list of child menu nodes (for a menu + or Choice): After parsing the children, the 'next' pointer is + assigned to the 'list' pointer to "tilt up" the children above the + node. - def _expand_sym_refs(self, s): - """Expands $-references to symbols in 's' to symbol values, or to the - empty string for undefined symbols.""" + Returns the final menu node in the block (or prev_node if the block is + empty). This allows chaining. + """ while 1: - sym_ref_match = _sym_ref_re_search(s) - if sym_ref_match is None: - return s + # We might already have tokens from parsing a line to check if it's + # a property and discovering it isn't. This is a kind of "unget". + if not self._has_tokens: + # Advance to the next line + if not self._next_line(): + if end_token is not None: + raise KconfigSyntaxError("Unexpected end of file " + + self._filename) - sym = self._syms.get(sym_ref_match.group(1)) + # We have reached the end of the file. Terminate the final + # node and return it. + prev_node.next = None + return prev_node - s = s[:sym_ref_match.start()] + \ - (sym.get_value() if sym is not None else "") + \ - s[sym_ref_match.end():] + self._tokenize() - def _expr_val_str(self, expr, no_value_str="(none)", - get_val_instead_of_eval=False): - """Printing helper. Returns a string with 'expr' and its value. + self._has_tokens = False - no_value_str: String to return when 'expr' is missing (None). + t0 = self._next_token() + if t0 is None: + continue - get_val_instead_of_eval: Assume 'expr' is a symbol or string (constant - symbol) and get its value directly instead of evaluating it to a - tristate value.""" + if t0 in (_T_CONFIG, _T_MENUCONFIG): + # The tokenizer allocates a Symbol objects the first time a + # symbol is seen + sym = self._next_token() - if expr is None: - return no_value_str + node = MenuNode() + node.kconfig = self + node.item = sym + node.help = None + node.list = None + node.parent = parent + node.filename = self._filename + node.linenr = self._linenr + node.is_menuconfig = (t0 == _T_MENUCONFIG) - if get_val_instead_of_eval: - if isinstance(expr, str): - return _expr_to_str(expr) - val = expr.get_value() - else: - val = self._eval_expr(expr) + self._parse_properties(node, visible_if_deps) - return "{} (value: {})".format(_expr_to_str(expr), _expr_to_str(val)) + sym.nodes.append(node) + self.defined_syms.append(sym) - def _get_sym_or_choice_str(self, sc): - """Symbols and choices have many properties in common, so we factor out - common __str__() stuff here. "sc" is short for "symbol or choice".""" + # Tricky Python semantics: This assign prev_node.next before + # prev_node + prev_node.next = prev_node = node - # As we deal a lot with string representations here, use some - # convenient shorthand: - s = _expr_to_str + elif t0 == _T_SOURCE: + self._enter_file(self._expand_syms(self._next_token())) + prev_node = self._parse_block(None, # end_token + parent, + visible_if_deps, + prev_node) + self._leave_file() + + elif t0 == end_token: + # We have reached the end of the block. Terminate the final + # node and return it. + prev_node.next = None + return prev_node - # - # Common symbol/choice properties - # + elif t0 == _T_IF: + node = MenuNode() + node.item = None + node.prompt = None + node.parent = parent + node.filename = self._filename + node.linenr = self._linenr + + # See similar code in _parse_properties() + if isinstance(node.parent.item, Choice): + parent_dep = parent.item + else: + parent_dep = parent.dep - user_val_str = "(no user value)" if sc._user_val is None else \ - s(sc._user_val) + node.dep = self._make_and(parent_dep, self._parse_expr(True)) - # Build prompts string - if not sc._prompts: - prompts_str = " (no prompts)" - else: - prompts_str_rows = [] - for prompt, cond_expr in sc._orig_prompts: - prompts_str_rows.append( - ' "{}"'.format(prompt) - if cond_expr is None else - ' "{}" if {}'.format(prompt, - self._expr_val_str(cond_expr))) - prompts_str = "\n".join(prompts_str_rows) - - # Build locations string - locations_str = "(no locations)" \ - if not sc._def_locations else \ - " ".join(["{}:{}".format(filename, linenr) - for filename, linenr in sc._def_locations]) - - # Build additional-dependencies-from-menus-and-ifs string - additional_deps_str = " " + \ - self._expr_val_str(sc._deps_from_containing, - "(no additional dependencies)") + self._parse_block(_T_ENDIF, + node, # parent + visible_if_deps, + node) # prev_node + node.list = node.next - # - # Symbol-specific stuff - # + prev_node.next = prev_node = node - if isinstance(sc, Symbol): - # Build ranges string - if isinstance(sc, Symbol): - if not sc._orig_ranges: - ranges_str = " (no ranges)" + elif t0 == _T_MENU: + node = MenuNode() + node.kconfig = self + node.item = MENU + node.visibility = self.y + node.parent = parent + node.filename = self._filename + node.linenr = self._linenr + + prompt = self._next_token() + self._parse_properties(node, visible_if_deps) + node.prompt = (prompt, node.dep) + + self._parse_block(_T_ENDMENU, + node, # parent + self._make_and(visible_if_deps, + node.visibility), + node) # prev_node + node.list = node.next + + prev_node.next = prev_node = node + + elif t0 == _T_COMMENT: + node = MenuNode() + node.kconfig = self + node.item = COMMENT + node.list = None + node.parent = parent + node.filename = self._filename + node.linenr = self._linenr + + prompt = self._next_token() + self._parse_properties(node, visible_if_deps) + node.prompt = (prompt, node.dep) + + prev_node.next = prev_node = node + + elif t0 == _T_CHOICE: + name = self._next_token() + if name is None: + choice = Choice() + self._choices.append(choice) else: - ranges_str_rows = [] - for l, u, cond_expr in sc._orig_ranges: - ranges_str_rows.append( - " [{}, {}]".format(s(l), s(u)) - if cond_expr is None else - " [{}, {}] if {}" - .format(s(l), s(u), self._expr_val_str(cond_expr))) - ranges_str = "\n".join(ranges_str_rows) - - # Build default values string - if not sc._orig_def_exprs: - defaults_str = " (no default values)" + # Named choice + choice = self.named_choices.get(name) + if not choice: + choice = Choice() + self._choices.append(choice) + choice.name = name + self.named_choices[name] = choice + + choice.kconfig = self + + node = MenuNode() + node.kconfig = self + node.item = choice + node.help = None + node.parent = parent + node.filename = self._filename + node.linenr = self._linenr + + self._parse_properties(node, visible_if_deps) + self._parse_block(_T_ENDCHOICE, + node, # parent + visible_if_deps, + node) # prev_node + node.list = node.next + + choice.nodes.append(node) + + prev_node.next = prev_node = node + + elif t0 == _T_MAINMENU: + self.top_node.prompt = (self._next_token(), self.y) + self.top_node.filename = self._filename + self.top_node.linenr = self._linenr + else: - defaults_str_rows = [] - for val_expr, cond_expr in sc._orig_def_exprs: - row_str = " " + self._expr_val_str(val_expr, "(none)", - sc._type == STRING) - defaults_str_rows.append(row_str) - defaults_str_rows.append(" Condition: " + - self._expr_val_str(cond_expr)) - defaults_str = "\n".join(defaults_str_rows) - - # Build selects string - if not sc._orig_selects: - selects_str = " (no selects)" + self._parse_error("unrecognized construct") + + def _parse_cond(self): + """ + Parses an optional 'if <expr>' construct and returns the parsed <expr>, + or self.y if the next token is not _T_IF + """ + return self._parse_expr(True) if self._check_token(_T_IF) else self.y + + def _parse_properties(self, node, visible_if_deps): + """ + Parses properties for symbols, menus, choices, and comments. Also takes + care of propagating dependencies from the menu node to the properties + of the item (this mirrors the C tools, though they do it after + parsing). + + node: + The menu node we're parsing properties on. Prompt, help text, + 'depends on', and 'visible if' properties apply to the Menu node, + while the others apply to the contained item. + + visible_if_deps: + 'visible if' dependencies from enclosing menus. Propagated to Symbol + and Choice prompts. + """ + # New properties encountered at this location. A local 'depends on' + # only applies to these, in case a symbol is defined in multiple + # locations. + prompt = None + defaults = [] + selects = [] + implies = [] + ranges = [] + + # Menu node dependencies from 'depends on'. Will get propagated to the + # properties above. + node.dep = self.y + + while 1: + # Advance to the next line + if not self._next_line(): + break + + self._tokenize() + + t0 = self._next_token() + if t0 is None: + continue + + if t0 == _T_DEPENDS: + if not self._check_token(_T_ON): + self._parse_error('expected "on" after "depends"') + + node.dep = self._make_and(node.dep, self._parse_expr(True)) + + elif t0 == _T_HELP: + # Find first non-blank (not all-space) line and get its + # indentation + + while 1: + line = self._next_line_no_join() + if not line or not line.isspace(): + break + + if not line: + node.help = "" + break + + indent = _indentation(line) + if indent == 0: + # If the first non-empty lines has zero indent, there is no + # help text + node.help = "" + self._reuse_line = True # "Unget" the line + break + + # The help text goes on till the first non-empty line with less + # indent + + help_lines = [_deindent(line, indent).rstrip()] + while 1: + line = self._next_line_no_join() + + if not line or \ + (not line.isspace() and _indentation(line) < indent): + node.help = "\n".join(help_lines).rstrip() + "\n" + break + + help_lines.append(_deindent(line, indent).rstrip()) + + if not line: + break + + self._reuse_line = True # "Unget" the line + + elif t0 == _T_SELECT: + if not isinstance(node.item, Symbol): + self._parse_error("only symbols can select") + + selects.append((self._next_token(), self._parse_cond())) + + elif t0 == _T_IMPLY: + if not isinstance(node.item, Symbol): + self._parse_error("only symbols can imply") + + implies.append((self._next_token(), self._parse_cond())) + + elif t0 in (_T_BOOL, _T_TRISTATE, _T_INT, _T_HEX, _T_STRING): + node.item.orig_type = _TOKEN_TO_TYPE[t0] + + if self._peek_token() is not None: + prompt = (self._next_token(), self._parse_cond()) + + elif t0 == _T_DEFAULT: + defaults.append((self._parse_expr(False), self._parse_cond())) + + elif t0 in (_T_DEF_BOOL, _T_DEF_TRISTATE): + node.item.orig_type = _TOKEN_TO_TYPE[t0] + + defaults.append((self._parse_expr(False), self._parse_cond())) + + elif t0 == _T_PROMPT: + # 'prompt' properties override each other within a single + # definition of a symbol, but additional prompts can be added + # by defining the symbol multiple times + prompt = (self._next_token(), self._parse_cond()) + + elif t0 == _T_RANGE: + ranges.append((self._next_token(), + self._next_token(), + self._parse_cond())) + + elif t0 == _T_OPTION: + if self._check_token(_T_ENV) and self._check_token(_T_EQUAL): + env_var = self._next_token() + + node.item.env_var = env_var + + if env_var not in os.environ: + self._warn("'option env=\"{0}\"' on symbol {1} has " + "no effect, because the environment " + "variable {0} is not set" + .format(env_var, node.item.name), + self._filename, self._linenr) + else: + defaults.append( + (self._lookup_const_sym(os.environ[env_var]), + self.y)) + + elif self._check_token(_T_DEFCONFIG_LIST): + if not self.defconfig_list: + self.defconfig_list = node.item + else: + self._warn("'option defconfig_list' set on multiple " + "symbols ({0} and {1}). Only {0} will be " + "used.".format(self.defconfig_list.name, + node.item.name), + self._filename, self._linenr) + + elif self._check_token(_T_MODULES): + # To reduce warning spam, only warn if 'option modules' is + # set on some symbol that isn't MODULES, which should be + # safe. I haven't run into any projects that make use + # modules besides the kernel yet, and there it's likely to + # keep being called "MODULES". + if node.item is not self.modules: + self._warn("the 'modules' option is not supported. " + "Let me know if this is a problem for you, " + "as it wouldn't be that hard to implement. " + "Note that modules are supported -- " + "Kconfiglib just assumes the symbol name " + "MODULES, like older versions of the C " + "implementation did when 'option modules' " + "wasn't used.", + self._filename, self._linenr) + + elif self._check_token(_T_ALLNOCONFIG_Y): + if not isinstance(node.item, Symbol): + self._parse_error("the 'allnoconfig_y' option is only " + "valid for symbols") + + node.item.is_allnoconfig_y = True + + else: + self._parse_error("unrecognized option") + + elif t0 == _T_VISIBLE: + if not self._check_token(_T_IF): + self._parse_error('expected "if" after "visible"') + + node.visibility = \ + self._make_and(node.visibility, self._parse_expr(True)) + + elif t0 == _T_OPTIONAL: + if not isinstance(node.item, Choice): + self._parse_error('"optional" is only valid for choices') + + node.item.is_optional = True + else: - selects_str_rows = [] - for target, cond_expr in sc._orig_selects: - selects_str_rows.append( - " " + target._name - if cond_expr is None else - " {} if {}".format(target._name, - self._expr_val_str(cond_expr))) - selects_str = "\n".join(selects_str_rows) - - # Build implies string - if not sc._orig_implies: - implies_str = " (no implies)" + self._tokens_i = -1 + # Reuse the tokens for the non-property line later + self._has_tokens = True + break + + # Done parsing properties. Now add the new + # prompts/defaults/selects/implies/ranges properties, with dependencies + # from node.dep propagated. + + # First propagate parent dependencies to node.dep + + # If the parent node holds a Choice, we use the Choice itself as the + # parent dependency. This matches the C implementation, and makes sense + # as the value (mode) of the choice limits the visibility of the + # contained choice symbols. Due to the similar interface, Choice works + # as a drop-in replacement for Symbol here. + if isinstance(node.parent.item, Choice): + node.dep = self._make_and(node.dep, node.parent.item) + else: + node.dep = self._make_and(node.dep, node.parent.dep) + + if isinstance(node.item, (Symbol, Choice)): + if isinstance(node.item, Symbol): + # See the class documentation + node.item.direct_dep = \ + self._make_or(node.item.direct_dep, node.dep) + + # Set the prompt, with dependencies propagated + if prompt: + node.prompt = (prompt[0], + self._make_and(self._make_and(prompt[1], + node.dep), + visible_if_deps)) else: - implies_str_rows = [] - for target, cond_expr in sc._orig_implies: - implies_str_rows.append( - " " + target._name - if cond_expr is None else - " {} if {}".format(target._name, - self._expr_val_str(cond_expr))) - implies_str = "\n".join(implies_str_rows) - - res = _lines("Symbol " + - ("(no name)" if sc._name is None else sc._name), - "Type : " + _TYPENAME[sc._type], - "Value : " + s(sc.get_value()), - "User value : " + user_val_str, - "Visibility : " + s(_get_visibility(sc)), - "Is choice item : " + str(sc._is_choice_sym), - "Is defined : " + str(sc._is_defined), - "Is from env. : " + str(sc._is_from_env), - "Is special : " + str(sc._is_special), - "") - if sc._ranges: - res += _lines("Ranges:", ranges_str + "\n") - res += _lines("Prompts:", - prompts_str, - "Default values:", - defaults_str, - "Selects:", - selects_str, - "Implies:", - implies_str, - "Reverse (select-related) dependencies:", - " (no reverse dependencies)" - if sc._rev_dep == "n" - else " " + self._expr_val_str(sc._rev_dep), - "Weak reverse (imply-related) dependencies:", - " (no weak reverse dependencies)" - if sc._weak_rev_dep == "n" - else " " + self._expr_val_str(sc._weak_rev_dep), - "Additional dependencies from enclosing menus " - "and ifs:", - additional_deps_str, - "Locations: " + locations_str) - - return res + node.prompt = None + # Add the new defaults, with dependencies propagated + for val_expr, cond in defaults: + node.item.defaults.append( + (val_expr, self._make_and(cond, node.dep))) + + # Add the new ranges, with dependencies propagated + for low, high, cond in ranges: + node.item.ranges.append( + (low, high, self._make_and(cond, node.dep))) + + # Handle selects + for target, cond in selects: + # Only stored for inspection. Not used during evaluation. + node.item.selects.append( + (target, self._make_and(cond, node.dep))) + + # Modify the dependencies of the selected symbol + target.rev_dep = \ + self._make_or(target.rev_dep, + self._make_and(node.item, + self._make_and(cond, + node.dep))) + + # Handle implies + for target, cond in implies: + # Only stored for inspection. Not used during evaluation. + node.item.implies.append( + (target, self._make_and(cond, node.dep))) + + # Modify the dependencies of the implied symbol + target.weak_rev_dep = \ + self._make_or(target.weak_rev_dep, + self._make_and(node.item, + self._make_and(cond, + node.dep))) + + def _parse_expr(self, transform_m): + """ + Parses an expression from the tokens in Kconfig._tokens using a simple + top-down approach. See the module docs for the expression format. + + transform_m: + True if m should be rewritten to m && MODULES. See the + Kconfig.eval_string() documentation. + """ + # Grammar: # - # Choice-specific stuff + # expr: and_expr ['||' expr] + # and_expr: factor ['&&' and_expr] + # factor: <symbol> ['='/'!='/'<'/... <symbol>] + # '!' factor + # '(' expr ')' # + # It helps to think of the 'expr: and_expr' case as a single-operand OR + # (no ||), and of the 'and_expr: factor' case as a single-operand AND + # (no &&). Parsing code is always a bit tricky. + + # Mind dump: parse_factor() and two nested loops for OR and AND would + # work as well. The straightforward implementation there gives a + # (op, (op, (op, A, B), C), D) parse for A op B op C op D. Representing + # expressions as (op, [list of operands]) instead goes nicely with that + # version, but is wasteful for short expressions and complicates + # expression evaluation and other code that works on expressions (more + # complicated code likely offsets any performance gain from less + # recursion too). If we also try to optimize the list representation by + # merging lists when possible (e.g. when ANDing two AND expressions), + # we end up allocating a ton of lists instead of reusing expressions, + # which is bad. - # Build selected symbol string - sel = sc.get_selection() - sel_str = "(no selection)" if sel is None else sel._name + and_expr = self._parse_and_expr(transform_m) - # Build default values string - if not sc._def_exprs: - defaults_str = " (no default values)" - else: - defaults_str_rows = [] - for sym, cond_expr in sc._orig_def_exprs: - defaults_str_rows.append( - " " + sym._name - if cond_expr is None else - " {} if {}".format(sym._name, - self._expr_val_str(cond_expr))) - defaults_str = "\n".join(defaults_str_rows) - - # Build contained symbols string - names = [sym._name for sym in sc._actual_symbols] - syms_string = " ".join(names) if names else "(empty)" - - return _lines("Choice", - "Name (for named choices): " + - ("(no name)" if sc._name is None else sc._name), - "Type : " + _TYPENAME[sc._type], - "Selected symbol : " + sel_str, - "User value : " + user_val_str, - "Mode : " + s(sc.get_mode()), - "Visibility : " + s(_get_visibility(sc)), - "Optional : " + str(sc._optional), - "Prompts:", - prompts_str, - "Defaults:", - defaults_str, - "Choice symbols:", - " " + syms_string, - "Additional dependencies from enclosing menus and ifs:", - additional_deps_str, - "Locations: " + locations_str) - - def _is_header_line(self, line): - """Returns True is the line could be part of the initial header in a - .config file (which is really just another comment, but can be handy - for storing metadata).""" - return line is not None and line.startswith("#") and \ - not self._unset_re.match(line) + # Return 'and_expr' directly if we have a "single-operand" OR. + # Otherwise, parse the expression on the right and make an OR node. + # This turns A || B || C || D into (OR, A, (OR, B, (OR, C, D))). + return and_expr \ + if not self._check_token(_T_OR) else \ + (OR, and_expr, self._parse_expr(transform_m)) + + def _parse_and_expr(self, transform_m): + factor = self._parse_factor(transform_m) + + # Return 'factor' directly if we have a "single-operand" AND. + # Otherwise, parse the right operand and make an AND node. This turns + # A && B && C && D into (AND, A, (AND, B, (AND, C, D))). + return factor \ + if not self._check_token(_T_AND) else \ + (AND, factor, self._parse_and_expr(transform_m)) + + def _parse_factor(self, transform_m): + token = self._next_token() + + if isinstance(token, Symbol): + # Plain symbol or relation + + next_token = self._peek_token() + if next_token not in _TOKEN_TO_REL: + # Plain symbol + + # For conditional expressions ('depends on <expr>', + # '... if <expr>', etc.), m is rewritten to m && MODULES. + if transform_m and token is self.m: + return (AND, self.m, self.modules) + + return token + + # Relation + return (_TOKEN_TO_REL[self._next_token()], token, + self._next_token()) + + if token == _T_NOT: + return (NOT, self._parse_factor(transform_m)) + + if token == _T_OPEN_PAREN: + expr_parse = self._parse_expr(transform_m) + if not self._check_token(_T_CLOSE_PAREN): + self._parse_error("missing end parenthesis") + + return expr_parse + + self._parse_error("malformed expression") # - # Warnings + # Caching and invalidation # + def _build_dep(self): + """ + Populates the Symbol/Choice._dependents sets, which contain all other + items (symbols and choices) that immediately depend on the item in the + sense that changing the value of the item might affect the value of the + dependent items. This is used for caching/invalidation. + + The calculated sets might be larger than necessary as we don't do any + complex analysis of the expressions. + """ + # Only calculate _dependents for defined symbols. Constant and + # undefined symbols could theoretically be selected/implied, but it + # wouldn't change their value, so it's not a true dependency. + for sym in self.defined_syms: + # Symbols depend on the following: + + # The prompt conditions + for node in sym.nodes: + if node.prompt: + _make_depend_on(sym, node.prompt[1]) + + # The default values and their conditions + for value, cond in sym.defaults: + _make_depend_on(sym, value) + _make_depend_on(sym, cond) + + # The reverse and weak reverse dependencies + _make_depend_on(sym, sym.rev_dep) + _make_depend_on(sym, sym.weak_rev_dep) + + # The ranges along with their conditions + for low, high, cond in sym.ranges: + _make_depend_on(sym, low) + _make_depend_on(sym, high) + _make_depend_on(sym, cond) + + # The direct dependencies. This is usually redundant, as the direct + # dependencies get propagated to properties, but it's needed to get + # invalidation solid for 'imply', which only checks the direct + # dependencies (even if there are no properties to propagate it + # to). + _make_depend_on(sym, sym.direct_dep) + + # In addition to the above, choice symbols depend on the choice + # they're in, but that's handled automatically since the Choice is + # propagated to the conditions of the properties before + # _build_dep() runs. + + for choice in self._choices: + # Choices depend on the following: + + # The prompt conditions + for node in choice.nodes: + if node.prompt: + _make_depend_on(choice, node.prompt[1]) + + # The default symbol conditions + for _, cond in choice.defaults: + _make_depend_on(choice, cond) + + # The choice symbols themselves, because the y mode selection might + # change if a choice symbol's visibility changes + for sym in choice.syms: + # the default selection depends on the symbols + sym._dependents.add(choice) + + def _invalidate_all(self): + # Undefined symbols never change value and don't need to be + # invalidated, so we can just iterate over defined symbols. + # Invalidating constant symbols would break things horribly. + for sym in self.defined_syms: + sym._invalidate() + + for choice in self._choices: + choice._invalidate() + + + # + # .config writing + # + + def _get_config_strings(self): + """ + Returns a list containing all .config strings for the configuration. + """ + # Symbol._already_written is set to True when a symbol config string is + # fetched, so that symbols defined in multiple locations only get one + # .config entry. We reset it prior to writing out a new .config. It + # only needs to be reset for defined symbols, because undefined symbols + # will never be written out (because they do not appear structure + # rooted at Kconfig.top_node). + # + # The C tools reuse _write_to_conf for this, but we cache + # _write_to_conf together with the value and don't invalidate cached + # values when writing .config files, so that won't work. + for sym in self.defined_syms: + sym._already_written = False + + node = self.top_node.list + if not node: + # Empty configuration + return [] + + config_strings = [] + # Small optimization + append = config_strings.append + + while 1: + if isinstance(node.item, Symbol): + sym = node.item + if not sym._already_written: + config_string = sym.config_string + if config_string: + append(config_string) + sym._already_written = True + + elif expr_value(node.dep) and \ + ((node.item == MENU and expr_value(node.visibility)) or + node.item == COMMENT): + + append("\n#\n# {}\n#\n".format(node.prompt[0])) + + # Iterative tree walk using parent pointers + + if node.list: + node = node.list + elif node.next: + node = node.next + else: + while node.parent: + node = node.parent + if node.next: + node = node.next + break + else: + return config_strings + + + # + # Misc. + # + + def _expand_syms(self, s): + """ + Expands $-references to symbols in 's' to symbol values, or to the + empty string for undefined symbols. + """ + while 1: + sym_ref_match = _sym_ref_re_search(s) + if not sym_ref_match: + return s + + sym = self.syms.get(sym_ref_match.group(1)) + + s = s[:sym_ref_match.start()] + \ + (sym.str_value if sym else "") + \ + s[sym_ref_match.end():] + + def _parse_error(self, msg): + if self._filename is None: + loc = "" + else: + loc = "{}:{}: ".format(self._filename, self._linenr) + + raise KconfigSyntaxError( + "{}Couldn't parse '{}': {}".format(loc, self._line.rstrip(), msg)) + def _warn(self, msg, filename=None, linenr=None): - """For printing general warnings.""" + """ + For printing general warnings. + """ if self._print_warnings: _stderr_msg("warning: " + msg, filename, linenr) def _warn_undef_assign(self, msg, filename=None, linenr=None): - """For printing warnings for assignments to undefined variables. We - treat this is a separate category of warnings to avoid spamming lots of - warnings.""" + """ + See the class documentation. + """ if self._print_undef_assign: _stderr_msg("warning: " + msg, filename, linenr) def _warn_undef_assign_load(self, name, val, filename, linenr): - """Special version for load_config().""" + """ + Special version for load_config(). + """ self._warn_undef_assign( 'attempt to assign the value "{}" to the undefined symbol {}' \ .format(val, name), filename, linenr) -class Item(object): - - """Base class for symbols and other Kconfig constructs. Subclasses are - Symbol, Choice, Menu, and Comment.""" - - def is_symbol(self): - """Returns True if the item is a symbol. Short for - isinstance(item, kconfiglib.Symbol).""" - return isinstance(self, Symbol) - - def is_choice(self): - """Returns True if the item is a choice. Short for - isinstance(item, kconfiglib.Choice).""" - return isinstance(self, Choice) - - def is_menu(self): - """Returns True if the item is a menu. Short for - isinstance(item, kconfiglib.Menu).""" - return isinstance(self, Menu) - - def is_comment(self): - """Returns True if the item is a comment. Short for - isinstance(item, kconfiglib.Comment).""" - return isinstance(self, Comment) -class Symbol(Item): +class Symbol(object): + """ + Represents a configuration symbol: - """Represents a configuration symbol - e.g. FOO for + (menu)config FOO + ... - config FOO - ...""" + The following attributes are available. They should be viewed as read-only, + and some are implemented through @property magic (but are still efficient + to access due to internal caching). - # - # Public interface - # + Note: Prompts, help texts, and locations are stored in the Symbol's + MenuNode(s) rather than in the Symbol itself. Check the MenuNode class and + the Symbol.nodes attribute. This organization matches the C tools. - def get_config(self): - """Returns the Config instance this symbol is from.""" - return self._config + name: + The name of the symbol, e.g. "FOO" for 'config FOO'. - def get_name(self): - """Returns the name of the symbol.""" - return self._name + type: + The type of the symbol. One of BOOL, TRISTATE, STRING, INT, HEX, UNKNOWN. + UNKNOWN is for undefined symbols, (non-special) constant symbols, and + symbols defined without a type. - def get_type(self): - """Returns the type of the symbol: one of UNKNOWN, BOOL, TRISTATE, - STRING, HEX, or INT. These are defined at the top level of the module, - so you'd do something like + When running without modules (MODULES having the value n), TRISTATE + symbols magically change type to BOOL. This also happens for symbols + within choices in "y" mode. This matches the C tools, and makes sense for + menuconfig-like functionality. - if sym.get_type() == kconfiglib.STRING: - ...""" - return self._type + orig_type: + The type as given in the Kconfig file, without any magic applied. Used + when printing the symbol. - def get_prompts(self): - """Returns a list of prompts defined for the symbol, in the order they - appear in the configuration files. Returns the empty list for symbols - with no prompt. + str_value: + The value of the symbol as a string. Gives the value for string/int/hex + symbols. For bool/tristate symbols, gives "n", "m", or "y". - This list will have a single entry for the vast majority of symbols - having prompts, but having multiple prompts for a single symbol is - possible through having multiple 'config' entries for it.""" - return [prompt for prompt, _ in self._orig_prompts] + This is the symbol value that's used in relational expressions + (A = B, A != B, etc.) - def get_help(self): - """Returns the help text of the symbol, or None if the symbol has no - help text.""" - return self._help + Gotcha: For int/hex symbols, the exact format of the value must often be + preserved (e.g., when writing a .config file), hence why you can't get it + directly as an int. Do int(int_sym.str_value) or + int(hex_sym.str_value, 16) to get the integer value. - def get_parent(self): - """Returns the menu or choice statement that contains the symbol, or - None if the symbol is at the top level. Note that if statements are - treated as syntactic and do not have an explicit class - representation.""" - return self._parent + tri_value: + The tristate value of the symbol as an integer. One of 0, 1, 2, + representing n, m, y. Always 0 (n) for non-bool/tristate symbols. - def get_def_locations(self): - """Returns a list of (filename, linenr) tuples, where filename (string) - and linenr (int) represent a location where the symbol is defined. For - the vast majority of symbols this list will only contain one element. - For the following Kconfig, FOO would get two entries: the lines marked - with *. + This is the symbol value that's used outside of relation expressions + (A, !A, A && B, A || B). - config FOO * - bool "foo prompt 1" + assignable: + A tuple containing the tristate user values that can currently be + assigned to the symbol (that would be respected), ordered from lowest (0, + representing n) to highest (2, representing y). This corresponds to the + selections available in the menuconfig interface. The set of assignable + values is calculated from the symbol's visibility and selects/implies. - config FOO * - bool "foo prompt 2" - """ - return self._def_locations + Returns the empty set for non-bool/tristate symbols and for symbols with + visibility n. The other possible values are (0, 2), (0, 1, 2), (1, 2), + (1,), and (2,). A (1,) or (2,) result means the symbol is visible but + "locked" to m or y through a select, perhaps in combination with the + visibility. menuconfig represents this as -M- and -*-, respectively. - def get_ref_locations(self): - """Returns a list of (filename, linenr) tuples, where filename (string) - and linenr (int) represent a location where the symbol is referenced in - the configuration. For example, the lines marked by * would be included - for FOO below: + For string/hex/int symbols, check if Symbol.visibility is non-0 (non-n) + instead to determine if the value can be changed. - config A - bool - default BAR || FOO * + Some handy 'assignable' idioms: - config B - tristate - depends on FOO * - default m if FOO * + # Is 'sym' an assignable (visible) bool/tristate symbol? + if sym.assignable: + # What's the highest value it can be assigned? [-1] in Python + # gives the last element. + sym_high = sym.assignable[-1] - if FOO * - config A - bool "A" - endif + # The lowest? + sym_low = sym.assignable[0] - config FOO (definition not included) - bool - """ - return self._ref_locations - - def get_value(self): - """Calculate and return the value of the symbol. See also - Symbol.set_user_value().""" + # Can the symbol be set to at least m? + if sym.assignable[-1] >= 1: + ... - if self._cached_val is not None: - return self._cached_val + # Can the symbol be set to m? + if 1 in sym.assignable: + ... - # As a quirk of Kconfig, undefined symbols get their name as their - # value. This is why things like "FOO = bar" work for seeing if FOO has - # the value "bar". - if self._type == UNKNOWN: - self._cached_val = self._name - return self._name + visibility: + The visibility of the symbol. One of 0, 1, 2, representing n, m, y. See + the module documentation for an overview of symbol values and visibility. - # This will hold the value at the end of the function - val = _DEFAULT_VALUE[self._type] + user_value: + The user value of the symbol. None if no user value has been assigned + (via Kconfig.load_config() or Symbol.set_value()). - vis = _get_visibility(self) + Holds 0, 1, or 2 for bool/tristate symbols, and a string for the other + symbol types. + + WARNING: Do not assign directly to this. It will break things. Use + Symbol.set_value(). + + config_string: + The .config assignment string that would get written out for the symbol + by Kconfig.write_config(). None if no .config assignment would get + written out. In general, visible symbols, symbols with (active) defaults, + and selected symbols get written out. + + nodes: + A list of MenuNodes for this symbol. Will contain a single MenuNode for + most symbols. Undefined and constant symbols have an empty nodes list. + Symbols defined in multiple locations get one node for each location. + + choice: + Holds the parent Choice for choice symbols, and None for non-choice + symbols. Doubles as a flag for whether a symbol is a choice symbol. + + defaults: + List of (default, cond) tuples for the symbol's 'default' properties. For + example, 'default A && B if C || D' is represented as + ((AND, A, B), (OR, C, D)). If no condition was given, 'cond' is + self.kconfig.y. + + Note that 'depends on' and parent dependencies are propagated to + 'default' conditions. + + selects: + List of (symbol, cond) tuples for the symbol's 'select' properties. For + example, 'select A if B && C' is represented as (A, (AND, B, C)). If no + condition was given, 'cond' is self.kconfig.y. + + Note that 'depends on' and parent dependencies are propagated to 'select' + conditions. + + implies: + Like 'selects', for imply. + + ranges: + List of (low, high, cond) tuples for the symbol's 'range' properties. For + example, 'range 1 2 if A' is represented as (1, 2, A). If there is no + condition, 'cond' is self.config.y. + + Note that 'depends on' and parent dependencies are propagated to 'range' + conditions. + + Gotcha: 1 and 2 above will be represented as (undefined) Symbols rather + than plain integers. Undefined symbols get their name as their string + value, so this works out. The C tools work the same way. + + rev_dep: + Reverse dependency expression from other symbols selecting this symbol. + Multiple selections get ORed together. A condition on a select is ANDed + with the selecting symbol. + + For example, if A has 'select FOO' and B has 'select FOO if C', then + FOO's rev_dep will be (OR, A, (AND, B, C)). + + weak_rev_dep: + Like rev_dep, for imply. + + direct_dep: + The 'depends on' dependencies. If a symbol is defined in multiple + locations, the dependencies at each location are ORed together. + + Internally, this is only used to implement 'imply', which only applies if + the implied symbol has expr_value(self.direct_dep) != 0. 'depends on' and + parent dependencies are automatically propagated to the conditions of + properties, so normally it's redundant to check the direct dependencies. + + env_var: + If the Symbol has an 'option env="FOO"' option, this contains the name + ("FOO") of the environment variable. None for symbols that aren't set + from the environment. + + 'option env="FOO"' acts as a 'default' property whose value is the value + of $FOO. + + env_var is set to "<uname release>" for the predefined symbol + UNAME_RELEASE, which holds the 'release' field from uname. + + Symbols with an 'option env' option are never written out to .config + files, even if they are visible. env_var corresponds to a flag called + SYMBOL_AUTO in the C implementation. + + is_allnoconfig_y: + True if the symbol has 'option allnoconfig_y' set on it. This has no + effect internally (except when printing symbols), but can be checked by + scripts. + + is_constant: + True if the symbol is a constant (quoted) symbol. + + kconfig: + The Kconfig instance this symbol is from. + """ + __slots__ = ( + "_already_written", + "_cached_assignable", + "_cached_str_val", + "_cached_tri_val", + "_cached_vis", + "_dependents", + "_was_set", + "_write_to_conf", + "choice", + "defaults", + "direct_dep", + "env_var", + "implies", + "is_allnoconfig_y", + "is_constant", + "kconfig", + "name", + "nodes", + "orig_type", + "ranges", + "rev_dep", + "selects", + "user_value", + "weak_rev_dep", + ) - if self._type in (BOOL, TRISTATE): - if not self._is_choice_sym: - self._write_to_conf = (vis != "n") + # + # Public interface + # - if vis != "n" and self._user_val is not None: - # If the symbol is visible and has a user value, we use - # that - val = self._config._eval_min(self._user_val, vis) + @property + def type(self): + """ + See the class documentation. + """ + if self.orig_type == TRISTATE and \ + ((self.choice and self.choice.tri_value == 2) or + not self.kconfig.modules.tri_value): + return BOOL - else: - # Otherwise, we look at defaults and weak reverse - # dependencies (implies) - - for def_expr, cond_expr in self._def_exprs: - cond_val = self._config._eval_expr(cond_expr) - if cond_val != "n": - self._write_to_conf = True - val = self._config._eval_min(def_expr, cond_val) - break - - # Weak reverse dependencies are only considered if our - # direct dependencies are met - if self._config._eval_expr(self._direct_deps) != "n": - weak_rev_dep_val = \ - self._config._eval_expr(self._weak_rev_dep) - if weak_rev_dep_val != "n": - self._write_to_conf = True - val = self._config._eval_max(val, weak_rev_dep_val) - - # Reverse (select-related) dependencies take precedence - rev_dep_val = self._config._eval_expr(self._rev_dep) - if rev_dep_val != "n": - self._write_to_conf = True - val = self._config._eval_max(val, rev_dep_val) + return self.orig_type - else: - # (bool/tristate) symbol in choice. See _get_visibility() for - # more choice-related logic. + @property + def str_value(self): + """ + See the class documentation. + """ + if self._cached_str_val is not None: + return self._cached_str_val - # Initially - self._write_to_conf = False + if self.orig_type in (BOOL, TRISTATE): + # Also calculates the visibility, so invalidation safe + self._cached_str_val = TRI_TO_STR[self.tri_value] + return self._cached_str_val - if vis != "n": - choice = self._parent - mode = choice.get_mode() + # As a quirk of Kconfig, undefined symbols get their name as their + # string value. This is why things like "FOO = bar" work for seeing if + # FOO has the value "bar". + if self.orig_type == UNKNOWN: + self._cached_str_val = self.name + return self.name - if mode != "n": - self._write_to_conf = True + val = "" + # Warning: See Symbol._rec_invalidate(), and note that this is a hidden + # function call (property magic) + vis = self.visibility - if mode == "y": - val = "y" if choice.get_selection() is self \ - else "n" - elif self._user_val in ("m", "y"): - # mode == "m" here - val = "m" + self._write_to_conf = (vis != 0) - # We need to promote "m" to "y" in two circumstances: - # 1) If our type is boolean - # 2) If our _weak_rev_dep (from IMPLY) is "y" - if val == "m" and \ - (self._type == BOOL or - self._config._eval_expr(self._weak_rev_dep) == "y"): - val = "y" + if self.orig_type in (INT, HEX): + # The C implementation checks the user value against the range in a + # separate code path (post-processing after loading a .config). + # Checking all values here instead makes more sense for us. It + # requires that we check for a range first. - elif self._type in (INT, HEX): - base = _TYPE_TO_BASE[self._type] + base = _TYPE_TO_BASE[self.orig_type] # Check if a range is in effect - for low_expr, high_expr, cond_expr in self._ranges: - if self._config._eval_expr(cond_expr) != "n": + for low_expr, high_expr, cond in self.ranges: + if expr_value(cond): has_active_range = True - low_str = _str_val(low_expr) - high_str = _str_val(high_expr) - - low = int(low_str, base) if \ - _is_base_n(low_str, base) else 0 - high = int(high_str, base) if \ - _is_base_n(high_str, base) else 0 + # The zeros are from the C implementation running strtoll() + # on empty strings + low = int(low_expr.str_value, base) if \ + _is_base_n(low_expr.str_value, base) else 0 + high = int(high_expr.str_value, base) if \ + _is_base_n(high_expr.str_value, base) else 0 break else: has_active_range = False - self._write_to_conf = (vis != "n") - - if vis != "n" and self._user_val is not None and \ - _is_base_n(self._user_val, base) and \ + if vis and self.user_value is not None and \ + _is_base_n(self.user_value, base) and \ (not has_active_range or - low <= int(self._user_val, base) <= high): + low <= int(self.user_value, base) <= high): # If the user value is well-formed and satisfies range # contraints, it is stored in exactly the same form as # specified in the assignment (with or without "0x", etc.) - val = self._user_val + val = self.user_value else: # No user value or invalid user value. Look at defaults. - for val_expr, cond_expr in self._def_exprs: - if self._config._eval_expr(cond_expr) != "n": + for val_expr, cond in self.defaults: + if expr_value(cond): self._write_to_conf = True - # Similarly to above, well-formed defaults are - # preserved as is. Defaults that do not satisfy a range - # constraints are clamped and take on a standard form. - - val = _str_val(val_expr) + val = val_expr.str_value if _is_base_n(val, base): val_num = int(val, base) - if has_active_range: - clamped_val = None + else: + val_num = 0 # strtoll() on empty string + + break + else: + val_num = 0 # strtoll() on empty string + + # This clamping procedure runs even if there's no default + if has_active_range: + clamp = None + if val_num < low: + clamp = low + elif val_num > high: + clamp = high + + if clamp is not None: + # The value is rewritten to a standard form if it is + # clamped + val = str(clamp) \ + if self.orig_type == INT else \ + hex(clamp) + + elif self.orig_type == STRING: + if vis and self.user_value is not None: + # If the symbol is visible and has a user value, use that + val = self.user_value + else: + # Otherwise, look at defaults + for val_expr, cond in self.defaults: + if expr_value(cond): + self._write_to_conf = True + val = val_expr.str_value + break - if val_num < low: - clamped_val = low - elif val_num > high: - clamped_val = high + self._cached_str_val = val + return val - if clamped_val is not None: - val = (hex(clamped_val) - if self._type == HEX else - str(clamped_val)) + @property + def tri_value(self): + """ + See the class documentation. + """ + if self._cached_tri_val is not None: + return self._cached_tri_val - break + if self.orig_type not in (BOOL, TRISTATE): + self._cached_tri_val = 0 + return self._cached_tri_val - else: - # No default kicked in. If there is an active range - # constraint, then the low end of the range is used, - # provided it's > 0, with "0x" prepended as appropriate. - if has_active_range and low > 0: - val = (hex(low) if self._type == HEX else str(low)) + val = 0 + # Warning: See Symbol._rec_invalidate(), and note that this is a hidden + # function call (property magic) + vis = self.visibility + self._write_to_conf = (vis != 0) + + if not self.choice: + # Non-choice symbol - elif self._type == STRING: - self._write_to_conf = (vis != "n") + if vis and self.user_value is not None: + # If the symbol is visible and has a user value, use that + val = min(self.user_value, vis) - if vis != "n" and self._user_val is not None: - val = self._user_val else: - for val_expr, cond_expr in self._def_exprs: - if self._config._eval_expr(cond_expr) != "n": + # Otherwise, look at defaults and weak reverse dependencies + # (implies) + + for default, cond in self.defaults: + cond_val = expr_value(cond) + if cond_val: + val = min(expr_value(default), cond_val) self._write_to_conf = True - val = _str_val(val_expr) break - self._cached_val = val + # Weak reverse dependencies are only considered if our + # direct dependencies are met + weak_rev_dep_val = expr_value(self.weak_rev_dep) + if weak_rev_dep_val and expr_value(self.direct_dep): + val = max(weak_rev_dep_val, val) + self._write_to_conf = True + + # Reverse (select-related) dependencies take precedence + rev_dep_val = expr_value(self.rev_dep) + if rev_dep_val: + val = max(rev_dep_val, val) + self._write_to_conf = True + + # m is promoted to y for (1) bool symbols and (2) symbols with a + # weak_rev_dep (from imply) of y + if val == 1 and \ + (self.type == BOOL or expr_value(self.weak_rev_dep) == 2): + val = 2 + + elif vis == 2: + # Visible choice symbol in y-mode choice. The choice mode limits + # the visibility of choice symbols, so it's sufficient to just + # check the visibility of the choice symbols themselves. + val = 2 if self.choice.selection is self else 0 + + elif vis and self.user_value: + # Visible choice symbol in m-mode choice, with set non-0 user value + val = 1 + + self._cached_tri_val = val return val - def get_user_value(self): - """Returns the value assigned to the symbol in a .config or via - Symbol.set_user_value() (provided the value was valid for the type of - the symbol). Returns None in case of no user value.""" - return self._user_val - - def get_upper_bound(self): - """For string/hex/int symbols and for bool and tristate symbols that - cannot be modified (see is_modifiable()), returns None. - - Otherwise, returns the highest value the symbol can be set to with - Symbol.set_user_value() (that will not be truncated): one of "m" or - "y", arranged from lowest to highest. This corresponds to the highest - value the symbol could be given in e.g. the 'make menuconfig' - interface. - - See also the tri_less*() and tri_greater*() functions, which could come - in handy.""" - if self._type not in (BOOL, TRISTATE): - return None + @property + def assignable(self): + """ + See the class documentation. + """ + if self._cached_assignable is not None: + return self._cached_assignable - # Fast path for the common case - if self._rev_dep == "n": - vis = _get_visibility(self) - return vis if vis != "n" else None + self._cached_assignable = self._get_assignable() + return self._cached_assignable - rev_dep_val = self._config._eval_expr(self._rev_dep) - # A bool selected to "m" gets promoted to "y", pinning it - if rev_dep_val == "m" and self._type == BOOL: - return None - vis = _get_visibility(self) - return vis if tri_greater(vis, rev_dep_val) else None - - def get_lower_bound(self): - """For string/hex/int symbols and for bool and tristate symbols that - cannot be modified (see is_modifiable()), returns None. - - Otherwise, returns the lowest value the symbol can be set to with - Symbol.set_user_value() (that will not be truncated): one of "n" or - "m", arranged from lowest to highest. This corresponds to the lowest - value the symbol could be given in e.g. the 'make menuconfig' - interface. - - See also the tri_less*() and tri_greater*() functions, which could come - in handy.""" - if self._type not in (BOOL, TRISTATE): + @property + def visibility(self): + """ + See the class documentation. + """ + if self._cached_vis is not None: + return self._cached_vis + + self._cached_vis = _get_visibility(self) + return self._cached_vis + + @property + def config_string(self): + """ + See the class documentation. + """ + if self.env_var is not None: + # Corresponds to SYMBOL_AUTO being set in the C implementation return None - rev_dep_val = self._config._eval_expr(self._rev_dep) - # A bool selected to "m" gets promoted to "y", pinning it - if rev_dep_val == "m" and self._type == BOOL: + + # Note: _write_to_conf is determined when the value is calculated. This + # is a hidden function call due to property magic. + val = self.str_value + if not self._write_to_conf: return None - return rev_dep_val if tri_greater(_get_visibility(self), rev_dep_val) \ - else None - def get_assignable_values(self): - """For string/hex/int symbols and for bool and tristate symbols that - cannot be modified (see is_modifiable()), returns the empty list. + if self.orig_type in (BOOL, TRISTATE): + return "{}{}={}\n" \ + .format(self.kconfig.config_prefix, self.name, val) \ + if val != "n" else \ + "# {}{} is not set\n" \ + .format(self.kconfig.config_prefix, self.name) - Otherwise, returns a list containing the user values that can be - assigned to the symbol (that won't be truncated). Usage example: + if self.orig_type in (INT, HEX): + return "{}{}={}\n" \ + .format(self.kconfig.config_prefix, self.name, val) - if "m" in sym.get_assignable_values(): - sym.set_user_value("m") + if self.orig_type == STRING: + # Escape \ and " + return '{}{}="{}"\n' \ + .format(self.kconfig.config_prefix, self.name, escape(val)) - This is basically a more convenient interface to - get_lower/upper_bound() when wanting to test if a particular tristate - value can be assigned.""" - if self._type not in (BOOL, TRISTATE): - return [] - rev_dep_val = self._config._eval_expr(self._rev_dep) - # A bool selected to "m" gets promoted to "y", pinning it - if rev_dep_val == "m" and self._type == BOOL: - return [] - res = ["n", "m", "y"][_TRI_TO_INT[rev_dep_val] : - _TRI_TO_INT[_get_visibility(self)] + 1] - return res if len(res) > 1 else [] - - def get_visibility(self): - """Returns the visibility of the symbol: one of "n", "m" or "y". For - bool and tristate symbols, this is an upper bound on the value users - can set for the symbol. For other types of symbols, a visibility of "n" - means the user value will be ignored. A visibility of "n" corresponds - to not being visible in the 'make *config' interfaces. - - Example (assuming we're running with modules enabled -- i.e., MODULES - set to 'y'): - - # Assume this has been assigned 'n' - config N_SYM - tristate "N_SYM" - - # Assume this has been assigned 'm' - config M_SYM - tristate "M_SYM" - - # Has visibility 'n' - config A - tristate "A" - depends on N_SYM - - # Has visibility 'm' - config B - tristate "B" - depends on M_SYM - - # Has visibility 'y' - config C - tristate "C" - - # Has no prompt, and hence visibility 'n' - config D - tristate - - Having visibility be tri-valued ensures that e.g. a symbol cannot be - set to "y" by the user if it depends on a symbol with value "m", which - wouldn't be safe. - - You should probably look at get_lower/upper_bound(), - get_assignable_values() and is_modifiable() before using this.""" - return _get_visibility(self) - - def get_referenced_symbols(self, refs_from_enclosing=False): - """Returns the set() of all symbols referenced by this item. For - example, the symbol defined by - - config FOO - bool - prompt "foo" if A && B - default C if D - depends on E - select F if G - - references the symbols A through G. - - refs_from_enclosing (default: False): If True, the symbols referenced - by enclosing menus and ifs will be included in the result.""" - res = [] - - for _, cond_expr in self._orig_prompts: - _expr_syms(cond_expr, res) - for val_expr, cond_expr in self._orig_def_exprs: - _expr_syms(val_expr, res) - _expr_syms(cond_expr, res) - for sym, cond_expr in self._orig_selects: - res.append(sym) - _expr_syms(cond_expr, res) - for sym, cond_expr in self._orig_implies: - res.append(sym) - _expr_syms(cond_expr, res) - for low, high, cond_expr in self._orig_ranges: - res.append(low) - res.append(high) - _expr_syms(cond_expr, res) - - if refs_from_enclosing: - _expr_syms(self._deps_from_containing, res) - - # Remove duplicates and return - return set(res) - - def get_selected_symbols(self): - """Returns the set() of all symbols X for which this symbol has a - 'select X' or 'select X if Y' (regardless of whether Y is satisfied or - not). This is a subset of the symbols returned by - get_referenced_symbols().""" - return {sym for sym, _ in self._orig_selects} - - def get_implied_symbols(self): - """Returns the set() of all symbols X for which this symbol has an - 'imply X' or 'imply X if Y' (regardless of whether Y is satisfied or - not). This is a subset of the symbols returned by - get_referenced_symbols().""" - return {sym for sym, _ in self._orig_implies} - - def set_user_value(self, v): - """Sets the user value of the symbol. + _internal_error("Internal error while creating .config: unknown " + 'type "{}".'.format(self.orig_type)) + + def set_value(self, value): + """ + Sets the user value of the symbol. Equal in effect to assigning the value to the symbol within a .config - file. Use get_lower/upper_bound() or get_assignable_values() to find - the range of currently assignable values for bool and tristate symbols; - setting values outside this range will cause the user value to differ - from the result of Symbol.get_value() (be truncated). Values that are - invalid for the type (such as a_bool.set_user_value("foo")) are - ignored, and a warning is emitted if an attempt is made to assign such - a value. - - For any type of symbol, is_modifiable() can be used to check if a user - value will currently have any effect on the symbol, as determined by - its visibility and range of assignable values. Any value that is valid - for the type (bool, tristate, etc.) will end up being reflected in - get_user_value() though, and might have an effect later if conditions - change. To get rid of the user value, use unset_user_value(). - - Any symbols dependent on the symbol are (recursively) invalidated, so - things will just work with regards to dependencies. - - v: The user value to give to the symbol.""" - self._set_user_value_no_invalidate(v, False) - - if self._name == "MODULES": - # Changing MODULES has wide-ranging effects - self._config._invalidate_all() - return + file. For bool and tristate symbols, use the 'assignable' attribute to + check which values can currently be assigned. Setting values outside + 'assignable' will cause Symbol.user_str/tri_value to differ from + Symbol.str/tri_value (be truncated down or up). + + Setting a choice symbol to 2 (y) only updates Choice.user_selection on + the parent choice and not Symbol.user_value itself. This gives the + expected behavior when a choice is switched between different modes. + Choice.user_selection is considered when the choice is in y mode (the + "normal" mode). + + Other symbols that depend (possibly indirectly) on this symbol are + automatically recalculated to reflect the assigned value. + + value: + The user value to give to the symbol. For bool and tristate symbols, + pass 0, 1, 2 for n, m, and y, respectively. For other symbol types, + pass a string. + + Values that are invalid for the type (such as "foo" or 1 (m) for a + BOOL) are ignored and won't be stored in Symbol.user_str/tri_value. + Kconfiglib will print a warning by default for invalid assignments, + and set_value() will return False. + + Returns True if the value is valid for the type of the symbol, and + False otherwise. This only looks at the form of the value. For BOOL and + TRISTATE symbols, check the Symbol.assignable attribute to see what + values are currently in range and would actually be reflected in the + value of the symbol. For other symbol types, check whether the + visibility is non-n. + """ + if value == self.user_value: + # We know the value must be valid if it was successfully set + # previously + self._was_set = True + return True + + # Check if the value is valid for our type + if not ((self.orig_type == BOOL and value in (0, 2) ) or + (self.orig_type == TRISTATE and value in (0, 1, 2) ) or + (self.orig_type == STRING and isinstance(value, str)) or + (self.orig_type == INT and isinstance(value, str) + and _is_base_n(value, 10) ) or + (self.orig_type == HEX and isinstance(value, str) + and _is_base_n(value, 16) + and int(value, 16) >= 0)): + + # Display tristate values as n, m, y in the warning + warning = "the value {} is invalid for {}, which has type {}" \ + .format(TRI_TO_STR[value] if value in (0, 1, 2) else + "'{}'".format(value), + self.name, TYPE_TO_STR[self.orig_type]) + + if self.orig_type in (BOOL, TRISTATE) and value in ("n", "m", "y"): + warning += ' (pass 0, 1, 2 for n, m, y, respectively)' + + self.kconfig._warn(warning) - self._invalidate() - self._invalidate_dependent() - - def unset_user_value(self): - """Resets the user value of the symbol, as if the symbol had never - gotten a user value via Config.load_config() or - Symbol.set_user_value().""" - self._unset_user_value_no_recursive_invalidate() - self._invalidate_dependent() - - def is_modifiable(self): - """Returns True if the value of the symbol could be modified by calling - Symbol.set_user_value(). - - For bools and tristates, this corresponds to the symbol being visible - in the 'make menuconfig' interface and not already being pinned to a - specific value (e.g. because it is selected by another symbol). - - For strings and numbers, this corresponds to just being visible. (See - Symbol.get_visibility().)""" - if self._is_special: return False - if self._type in (BOOL, TRISTATE): - rev_dep_val = self._config._eval_expr(self._rev_dep) - # A bool selected to "m" gets promoted to "y", pinning it - if rev_dep_val == "m" and self._type == BOOL: - return False - return tri_greater(_get_visibility(self), rev_dep_val) - return _get_visibility(self) != "n" - - def is_defined(self): - """Returns False if the symbol is referred to in the Kconfig but never - actually defined.""" - return self._is_defined - - def is_special(self): - """Returns True if the symbol is one of the special symbols n, m, y, or - UNAME_RELEASE, or gets its value from the environment.""" - return self._is_special - - def is_from_environment(self): - """Returns True if the symbol gets its value from the environment.""" - return self._is_from_env - - def has_ranges(self): - """Returns True if the symbol is of type INT or HEX and has ranges that - limit what values it can take on.""" - return bool(self._ranges) - - def is_choice_symbol(self): - """Returns True if the symbol is in a choice statement and is an actual - choice symbol (see Choice.get_symbols()).""" - return self._is_choice_sym - - def is_choice_selection(self): - """Returns True if the symbol is contained in a choice statement and is - the selected item. Equivalent to - - sym.is_choice_symbol() and sym.get_parent().get_selection() is sym""" - return self._is_choice_sym and self._parent.get_selection() is self - - def is_allnoconfig_y(self): - """Returns True if the symbol has the 'allnoconfig_y' option set.""" - return self._allnoconfig_y + + if self.choice and value == 2: + # Remember this as a choice selection only. Makes switching back + # and forth between choice modes work as expected, and makes the + # check for whether the user value is the same as before above + # safe. + self.choice.user_selection = self + self.choice._was_set = True + if self._is_user_assignable(): + self.choice._rec_invalidate() + else: + self.user_value = value + self._was_set = True + if self._is_user_assignable(): + self._rec_invalidate() + + return True + + def unset_value(self): + """ + Resets the user value of the symbol, as if the symbol had never gotten + a user value via Kconfig.load_config() or Symbol.set_value(). + """ + if self.user_value is not None: + self.user_value = None + if self._is_user_assignable(): + self._rec_invalidate() + + def __repr__(self): + """ + Returns a string with information about the symbol (including its name, + value, visibility, and location(s)) when it is evaluated on e.g. the + interactive Python prompt. + """ + fields = [] + + fields.append("symbol " + self.name) + fields.append(TYPE_TO_STR[self.type]) + + for node in self.nodes: + if node.prompt: + fields.append('"{}"'.format(node.prompt[0])) + + # Only add quotes for non-bool/tristate symbols + fields.append("value " + + (self.str_value + if self.orig_type in (BOOL, TRISTATE) else + '"{}"'.format(self.str_value))) + + if not self.is_constant: + # These aren't helpful to show for constant symbols + + if self.user_value is not None: + # Only add quotes for non-bool/tristate symbols + fields.append("user value " + + (TRI_TO_STR[self.user_value] + if self.orig_type in (BOOL, TRISTATE) else + '"{}"'.format(self.user_value))) + + fields.append("visibility " + TRI_TO_STR[self.visibility]) + + if self.choice: + fields.append("choice symbol") + + if self.is_allnoconfig_y: + fields.append("allnoconfig_y") + + if self is self.kconfig.defconfig_list: + fields.append("is the defconfig_list symbol") + + if self.env_var is not None: + fields.append("from environment variable " + self.env_var) + + if self is self.kconfig.modules: + fields.append("is the modules symbol") + + fields.append("direct deps " + + TRI_TO_STR[expr_value(self.direct_dep)]) + + if self.nodes: + for node in self.nodes: + fields.append("{}:{}".format(node.filename, node.linenr)) + else: + if self.is_constant: + fields.append("constant") + else: + fields.append("undefined") + + return "<{}>".format(", ".join(fields)) def __str__(self): - """Returns a string containing various information about the symbol.""" - return self._config._get_sym_or_choice_str(self) + """ + Returns a string representation of the symbol when it is printed, + matching the Kconfig format. Prompts and help texts are included, + though they really belong to the symbol's menu nodes rather than the + symbol itself. + + The output is designed so that feeding it back to a Kconfig parser + redefines the symbol as is. This also works for symbols defined in + multiple locations, where all the definitions are output. See the + module documentation for a small gotcha related to choice symbols. + + An empty string is returned for undefined and constant symbols. + """ + return _sym_choice_str(self) # # Private methods # def __init__(self): - """Symbol constructor -- not intended to be called directly by - Kconfiglib clients.""" - + """ + Symbol constructor -- not intended to be called directly by Kconfiglib + clients. + """ # These attributes are always set on the instance from outside and # don't need defaults: - # _config - # _name # _already_written + # kconfig + # direct_dep + # is_constant + # name + # rev_dep + # weak_rev_dep - self._type = UNKNOWN - self._prompts = [] - self._def_exprs = [] # 'default' properties - self._ranges = [] # 'range' properties (for int and hex) - self._help = None # Help text - self._rev_dep = "n" # Reverse (select-related) dependencies - self._weak_rev_dep = "n" # Weak reverse (imply-related) dependencies - self._parent = None - - self._user_val = None # Value set by user - - # Prompts, default values, ranges, selects, and implies without any - # dependencies from parents propagated to them - self._orig_prompts = [] - self._orig_def_exprs = [] - self._orig_selects = [] - self._orig_implies = [] - self._orig_ranges = [] - - # Dependencies inherited from containing menus and ifs - self._deps_from_containing = None - - # See comment in _parse_properties() - self._menu_dep = None - - # The direct dependencies (inherited + 'depends on', with OR if a - # symbol is defined in multiple locations). This is needed for 'imply' - # support. - self._direct_deps = "n" - - # See Symbol.get_ref/def_locations(). - self._def_locations = [] - self._ref_locations = [] - - # Populated in Config._build_dep() after parsing. Links the symbol to - # the symbols that immediately depend on it (in a caching/invalidation - # sense). The total set of dependent symbols for the symbol (the - # transitive closure) is calculated on an as-needed basis in - # _get_dependent(). - self._direct_dependents = set() + self.orig_type = UNKNOWN + self.defaults = [] + self.selects = [] + self.implies = [] + self.ranges = [] - # Cached values + self.nodes = [] - # Caches the calculated value - self._cached_val = None - # Caches the visibility, which acts as an upper bound on the value - self._cached_visibility = None - # Caches the total list of dependent symbols. Calculated in - # _get_dependent(). - self._cached_deps = None + self.user_value = None - # Flags + # See Kconfig._build_dep() + self._dependents = set() - # Does the symbol have an entry in the Kconfig file? - self._is_defined = False - # Should the symbol get an entry in .config? - self._write_to_conf = False - # This is set to True for "actual" choice symbols; see - # Choice._determine_actual_symbols(). - self._is_choice_sym = False - # Does the symbol get its value in some special way, e.g. from the - # environment or by being one of the special symbols n, m, and y? If - # so, the value is stored in self._cached_val, which is never - # invalidated. - self._is_special = False - # Does the symbol get its value from the environment? - self._is_from_env = False - # Does the symbol have the 'allnoconfig_y' option set? - self._allnoconfig_y = False + # Cached values - def _invalidate(self): - if self._is_special: - # Special symbols never change value and keep their value in - # _cached_val - return + self._cached_str_val = self._cached_tri_val = self._cached_vis = \ + self._cached_assignable = None - if self._is_choice_sym: - self._parent._invalidate() + # Flags - self._cached_val = None - self._cached_visibility = None + self.choice = None + self.env_var = None + self.is_allnoconfig_y = False - def _invalidate_dependent(self): - for sym in self._get_dependent(): - sym._invalidate() + self._was_set = False - def _set_user_value_no_invalidate(self, v, suppress_load_warnings): - """Like set_user_value(), but does not invalidate any symbols. + # Should the symbol get an entry in .config? Calculated along with the + # value. + self._write_to_conf = False - suppress_load_warnings: some warnings are annoying when loading a - .config that can be helpful when manually invoking set_user_value(). - This flag is set to True to suppress such warnings. + def _get_assignable(self): + """ + Worker function for the 'assignable' attribute. + """ + if self.orig_type not in (BOOL, TRISTATE): + return () - Perhaps this could be made optional for load_config() instead.""" + # Warning: See Symbol._rec_invalidate(), and note that this is a hidden + # function call (property magic) + vis = self.visibility - if self._is_special: - if self._is_from_env: - self._config._warn('attempt to assign the value "{}" to the ' - 'symbol {}, which gets its value from the ' - 'environment. Assignment ignored.' - .format(v, self._name)) - else: - self._config._warn('attempt to assign the value "{}" to the ' - 'special symbol {}. Assignment ignored.' - .format(v, self._name)) - return + if not vis: + return () - if not self._is_defined: - filename, linenr = self._ref_locations[0] - self._config._warn_undef_assign( - 'attempt to assign the value "{}" to {}, which is referenced ' - "at {}:{} but never defined. Assignment ignored." - .format(v, self._name, filename, linenr)) - return + rev_dep_val = expr_value(self.rev_dep) - # Check if the value is valid for our type - if not ((self._type == BOOL and v in ("n", "y") ) or - (self._type == TRISTATE and v in ("n", "m", "y")) or - (self._type == STRING ) or - (self._type == INT and _is_base_n(v, 10) ) or - (self._type == HEX and _is_base_n(v, 16) )): - self._config._warn('the value "{}" is invalid for {}, which has ' - "type {}. Assignment ignored." - .format(v, self._name, _TYPENAME[self._type])) - return + if vis == 2: + if self.choice: + return (2,) - if not self._prompts and not suppress_load_warnings: - self._config._warn('assigning "{}" to the symbol {} which lacks ' - 'prompts and thus has visibility "n". The ' - 'assignment will have no effect.' - .format(v, self._name)) + if not rev_dep_val: + if self.type == BOOL or expr_value(self.weak_rev_dep) == 2: + return (0, 2) + return (0, 1, 2) - self._user_val = v + if rev_dep_val == 2: + return (2,) - if self._is_choice_sym and self._type in (BOOL, TRISTATE): - choice = self._parent - if v == "y": - choice._user_val = self - choice._user_mode = "y" - elif v == "m": - choice._user_val = None - choice._user_mode = "m" + # rev_dep_val == 1 - def _unset_user_value_no_recursive_invalidate(self): - self._invalidate() - self._user_val = None + if self.type == BOOL or expr_value(self.weak_rev_dep) == 2: + return (2,) + return (1, 2) - if self._is_choice_sym: - self._parent._unset_user_value() + # vis == 1 - def _add_config_strings(self, add_fn): - if self._already_written: - return + # Must be a tristate here, because bool m visibility gets promoted to y - self._already_written = True + if not rev_dep_val: + return (0, 1) if expr_value(self.weak_rev_dep) != 2 else (0, 2) - # Note: _write_to_conf is determined in get_value() - val = self.get_value() - if not self._write_to_conf: - return + if rev_dep_val == 2: + return (2,) - if self._type in (BOOL, TRISTATE): - add_fn("# {}{} is not set\n".format(self._config._config_prefix, - self._name) - if val == "n" else - "{}{}={}\n".format(self._config._config_prefix, self._name, - val)) + # vis == rev_dep_val == 1 - elif self._type in (INT, HEX): - add_fn("{}{}={}\n".format(self._config._config_prefix, self._name, - val)) + return (1,) - elif self._type == STRING: - # Escape \ and " - add_fn('{}{}="{}"\n' - .format(self._config._config_prefix, self._name, - val.replace("\\", "\\\\").replace('"', '\\"'))) + def _is_user_assignable(self): + """ + Returns True if the symbol has a prompt, meaning a user value might + have an effect on it. Used as an optimization to skip invalidation when + promptless symbols are assigned to (given a user value). - else: - _internal_error("Internal error while creating .config: unknown " - 'type "{}".'.format(self._type)) - - def _get_dependent(self): - """Returns the set of symbols that should be invalidated if the value - of the symbol changes, because they might be affected by the change. - Note that this is an internal API -- it's probably of limited - usefulness to clients.""" - if self._cached_deps is not None: - return self._cached_deps - - # Less readable version of the following, measured to reduce the the - # running time of _get_dependent() on kernel Kconfigs by about 1/3 as - # measured by line_profiler. - # - # res = set(self._direct_dependents) - # for s in self._direct_dependents: - # res |= s._get_dependent() - res = self._direct_dependents | \ - {sym for dep in self._direct_dependents - for sym in dep._get_dependent()} - - if self._is_choice_sym: - # Choice symbols also depend (recursively) on their siblings. The - # siblings are not included in _direct_dependents to avoid - # dependency loops. - for sibling in self._parent._actual_symbols: - if sibling is not self: - res.add(sibling) - res |= sibling._direct_dependents - for s in sibling._direct_dependents: - res |= s._get_dependent() - - self._cached_deps = res - return res - - def _has_auto_menu_dep_on(self, on): - """See Choice._determine_actual_symbols().""" - if not isinstance(self._parent, Choice): - _internal_error("Attempt to determine auto menu dependency for " - "symbol ouside of choice.") - - if not self._prompts: - # If we have no prompt, use the menu dependencies instead (what was - # specified with 'depends on') - return self._menu_dep is not None and \ - self._config._expr_depends_on(self._menu_dep, on) - - for _, cond_expr in self._prompts: - if self._config._expr_depends_on(cond_expr, on): + Prints a warning if the symbol has no prompt. In some contexts (e.g. + when loading a .config files) assignments to promptless symbols are + normal and expected, so the warning can be disabled. + """ + for node in self.nodes: + if node.prompt: return True + if self.kconfig._warn_no_prompt: + self.kconfig._warn(self.name + " has no prompt, meaning user " + "values have no effect on it") return False -class Menu(Item): + def _invalidate(self): + """ + Marks the symbol as needing to be recalculated. + """ + self._cached_str_val = self._cached_tri_val = self._cached_vis = \ + self._cached_assignable = None + + def _rec_invalidate(self): + """ + Invalidates the symbol and all items that (possibly) depend on it. + """ + if self is self.kconfig.modules: + # Invalidating MODULES has wide-ranging effects + self.kconfig._invalidate_all() + else: + self._invalidate() - """Represents a menu statement.""" + for item in self._dependents: + # _cached_vis doubles as a flag that tells us whether 'item' + # has cached values, because it's calculated as a side effect + # of calculating all other (non-constant) cached values. + # + # If item._cached_vis is None, it means there can't be cached + # values on other items that depend on 'item', because if there + # were, some value on 'item' would have been calculated and + # item._cached_vis set as a side effect. It's therefore safe to + # stop the invalidation at symbols with _cached_vis None. + # + # This approach massively speeds up scripts that set a lot of + # values, vs simply invalidating all possibly dependent symbols + # (even when you already have a list of all the dependent + # symbols, because some symbols get huge dependency trees). + # + # This gracefully handles dependency loops too, which is nice + # for choices, where the choice depends on the choice symbols + # and vice versa. + if item._cached_vis is not None: + item._rec_invalidate() + +class Choice(object): + """ + Represents a choice statement: + + choice + ... + endchoice + + The following attributes are available on Choice instances. They should be + treated as read-only, and some are implemented through @property magic (but + are still efficient to access due to internal caching). + + Note: Prompts, help texts, and locations are stored in the Choice's + MenuNode(s) rather than in the Choice itself. Check the MenuNode class and + the Choice.nodes attribute. This organization matches the C tools. + + name: + The name of the choice, e.g. "FOO" for 'choice FOO', or None if the + Choice has no name. I can't remember ever seeing named choices in + practice, but the C tools support them too. + + type: + The type of the choice. One of BOOL, TRISTATE, UNKNOWN. UNKNOWN is for + choices defined without a type where none of the contained symbols have a + type either (otherwise the choice inherits the type of the first symbol + defined with a type). + + When running without modules (CONFIG_MODULES=n), TRISTATE choices + magically change type to BOOL. This matches the C tools, and makes sense + for menuconfig-like functionality. + + orig_type: + The type as given in the Kconfig file, without any magic applied. Used + when printing the choice. + + tri_value: + The tristate value (mode) of the choice. A choice can be in one of three + modes: + + 0 (n) - The choice is disabled and no symbols can be selected. For + visible choices, this mode is only possible for choices with + the 'optional' flag set (see kconfig-language.txt). + + 1 (m) - Any number of choice symbols can be set to m, the rest will + be n. + + 2 (y) - One symbol will be y, the rest n. + + Only tristate choices can be in m mode. The visibility of the choice is + an upper bound on the mode, and the mode in turn is an upper bound on the + visibility of the choice symbols. + + To change the mode, use Choice.set_value(). + + Implementation note: + The C tools internally represent choices as a type of symbol, with + special-casing in many code paths. This is why there is a lot of + similarity to Symbol. The value (mode) of a choice is really just a + normal symbol value, and an implicit reverse dependency forces its + lower bound to m for visible non-optional choices (the reverse + dependency is 'm && <visibility>'). + + Symbols within choices get the choice propagated as a dependency to + their properties. This turns the mode of the choice into an upper bound + on e.g. the visibility of choice symbols, and explains the gotcha + related to printing choice symbols mentioned in the module docstring. + + Kconfiglib uses a separate Choice class only because it makes the code + and interface less confusing (especially in a user-facing interface). + Corresponding attributes have the same name in the Symbol and Choice + classes, for consistency and compatibility. + + assignable: + See the symbol class documentation. Gives the assignable values (modes). + + visibility: + See the Symbol class documentation. Acts on the value (mode). + + selection: + The Symbol instance of the currently selected symbol. None if the Choice + is not in y mode or has no selected symbol (due to unsatisfied + dependencies on choice symbols). + + WARNING: Do not assign directly to this. It will break things. Call + sym.set_value(2) on the choice symbol you want to select instead. + + user_value: + The value (mode) selected by the user through Choice.set_value(). Either + 0, 1, or 2, or None if the user hasn't selected a mode. See + Symbol.user_value. + + WARNING: Do not assign directly to this. It will break things. Use + Choice.set_value() instead. + + user_selection: + The symbol selected by the user (by setting it to y). Ignored if the + choice is not in y mode, but still remembered so that the choice "snaps + back" to the user selection if the mode is changed back to y. This might + differ from 'selection' due to unsatisfied dependencies. + + WARNING: Do not assign directly to this. It will break things. Call + sym.set_value(2) on the choice symbol to be selected instead. + + syms: + List of symbols contained in the choice. + + Gotcha: If a symbol depends on the previous symbol within a choice so + that an implicit menu is created, it won't be a choice symbol, and won't + be included in 'syms'. There are real-world examples of this, and it was + a PITA to support in older versions of Kconfiglib that didn't implement + the menu structure. + + nodes: + A list of MenuNodes for this choice. In practice, the list will probably + always contain a single MenuNode, but it is possible to give a choice a + name and define it in multiple locations (i've never even seen a named + choice though). + + defaults: + List of (symbol, cond) tuples for the choice's 'defaults' properties. For + example, 'default A if B && C' is represented as (A, (AND, B, C)). If + there is no condition, 'cond' is self.config.y. + + Note that 'depends on' and parent dependencies are propagated to + 'default' conditions. + + is_optional: + True if the choice has the 'optional' flag set on it and can be in + n mode. + + kconfig: + The Kconfig instance this choice is from. + """ + __slots__ = ( + "_cached_assignable", + "_cached_selection", + "_cached_vis", + "_dependents", + "_was_set", + "defaults", + "is_constant", + "is_optional", + "kconfig", + "name", + "nodes", + "orig_type", + "syms", + "user_selection", + "user_value", + ) # # Public interface # - def get_config(self): - """Return the Config instance this menu is from.""" - return self._config - - def get_title(self): - """Returns the title text of the menu.""" - return self._title - - def get_parent(self): - """Returns the menu or choice statement that contains the menu, or - None if the menu is at the top level. Note that if statements are - treated as syntactic sugar and do not have an explicit class - representation.""" - return self._parent - - def get_location(self): - """Returns the location of the menu as a (filename, linenr) tuple, - where filename is a string and linenr an int.""" - return (self._filename, self._linenr) - - def get_items(self, recursive=False): - """Returns a list containing the items (symbols, menus, choice - statements and comments) in in the menu, in the same order that the - items appear within the menu. - - recursive (default: False): True if items contained in items within the - menu should be included recursively (preorder).""" - - if not recursive: - return self._block - - res = [] - for item in self._block: - res.append(item) - if isinstance(item, Menu): - res.extend(item.get_items(True)) - elif isinstance(item, Choice): - res.extend(item.get_items()) - return res - - def get_symbols(self, recursive=False): - """Returns a list containing the symbols in the menu, in the same order - that they appear within the menu. - - recursive (default: False): True if symbols contained in items within - the menu should be included recursively.""" - - return [item for item in self.get_items(recursive) if - isinstance(item, Symbol)] - - def get_visibility(self): - """Returns the visibility of the menu. This also affects the visibility - of subitems. See also Symbol.get_visibility().""" - return self._config._eval_expr(self._menu_dep) - - def get_visible_if_visibility(self): - """Returns the visibility the menu gets from its 'visible if' - condition. "y" if the menu has no 'visible if' condition.""" - return self._config._eval_expr(self._visible_if_expr) - - def get_referenced_symbols(self, refs_from_enclosing=False): - """See Symbol.get_referenced_symbols().""" - res = [] - - _expr_syms(self._visible_if_expr, res) - _expr_syms(self._orig_deps - if not refs_from_enclosing else - self._menu_dep, - res) - - # Remove duplicates and return - return set(res) + @property + def type(self): + """ + Returns the type of the choice. See Symbol.type. + """ + if self.orig_type == TRISTATE and not self.kconfig.modules.tri_value: + return BOOL - def __str__(self): - """Returns a string containing various information about the menu.""" - depends_on_str = self._config._expr_val_str(self._orig_deps, - "(no dependencies)") - visible_if_str = self._config._expr_val_str(self._visible_if_expr, - "(no dependencies)") - - additional_deps_str = " " + \ - self._config._expr_val_str(self._deps_from_containing, - "(no additional dependencies)") - - return _lines("Menu", - "Title : " + self._title, - "'depends on' dependencies : " + depends_on_str, - "'visible if' dependencies : " + visible_if_str, - "Additional dependencies from enclosing menus and ifs:", - additional_deps_str, - "Location: {}:{}".format(self._filename, self._linenr)) + return self.orig_type - # - # Private methods - # + @property + def str_value(self): + """ + See the class documentation. + """ + return TRI_TO_STR[self.tri_value] - def __init__(self): - """Menu constructor -- not intended to be called directly by - Kconfiglib clients.""" + @property + def tri_value(self): + """ + See the class documentation. + """ + # This emulates a reverse dependency of 'm && visibility' for + # non-optional choices, which is how the C implementation does it - # These attributes are always set on the instance from outside and - # don't need defaults: - # _config - # _parent - # _filename - # _linenr - # _title - # _deps_from_containing - # _menu_dep + val = 0 if self.is_optional else 1 - # Dependencies specified with 'visible_if' - self._visible_if_expr = None + if self.user_value is not None: + val = max(val, self.user_value) - # Dependency expression without dependencies from enclosing menus and - # ifs propagated - self._orig_deps = None + # Warning: See Symbol._rec_invalidate(), and note that this is a hidden + # function call (property magic) + val = min(val, self.visibility) - # Contained items - self._block = [] + # Promote m to y for boolean choices + return 2 if val == 1 and self.type == BOOL else val - def _add_config_strings(self, add_fn): - if self._config._eval_expr(self._menu_dep) != "n" and \ - self._config._eval_expr(self._visible_if_expr) != "n": - add_fn("\n#\n# {}\n#\n".format(self._title)) + @property + def assignable(self): + """ + See the class documentation. + """ + if self._cached_assignable is not None: + return self._cached_assignable - for item in self._block: - item._add_config_strings(add_fn) + self._cached_assignable = self._get_assignable() + return self._cached_assignable -class Choice(Item): + @property + def visibility(self): + """ + See the class documentation. + """ + if self._cached_vis is not None: + return self._cached_vis - """Represents a choice statement. A choice can be in one of three modes: + self._cached_vis = _get_visibility(self) + return self._cached_vis - "n" - The choice is not visible and no symbols can be selected. + @property + def selection(self): + """ + See the class documentation. + """ + if self._cached_selection is not _NO_CACHED_SELECTION: + return self._cached_selection - "m" - Any number of symbols can be set to "m". The rest will be "n". This - is safe since potentially conflicting options don't actually get - compiled into the kernel simultaneously with "m". + # Warning: See Symbol._rec_invalidate(), and note that this is a hidden + # function call (property magic) + if self.tri_value != 2: + self._cached_selection = None + return None - "y" - One symbol will be "y" while the rest are "n". + # Use the user selection if it's visible + if self.user_selection and self.user_selection.visibility == 2: + self._cached_selection = self.user_selection + return self.user_selection - Only tristate choices can be in "m" mode, and the visibility of the choice - is an upper bound on the mode, so that e.g. a choice that depends on a - symbol with value "m" will be in "m" mode. + # Otherwise, check if we have a default + for sym, cond in self.defaults: + # The default symbol must be visible too + if expr_value(cond) and sym.visibility: + self._cached_selection = sym + return sym - The mode changes automatically when a value is assigned to a symbol within - the choice. + # Otherwise, pick the first visible symbol, if any + for sym in self.syms: + if sym.visibility: + self._cached_selection = sym + return sym - See Symbol.get_visibility() too.""" + # Couldn't find a selection + self._cached_selection = None + return None - # - # Public interface - # + def set_value(self, value): + """ + Sets the user value (mode) of the choice. Like for Symbol.set_value(), + the visibility might truncate the value. Choices without the 'optional' + attribute (is_optional) can never be in n mode, but 0 is still accepted + since it's not a malformed value (though it will have no effect). + + Returns True if the value is valid for the type of the choice, and + False otherwise. This only looks at the form of the value. Check the + Choice.assignable attribute to see what values are currently in range + and would actually be reflected in the mode of the choice. + """ + if value == self.user_value: + # We know the value must be valid if it was successfully set + # previously + self._was_set = True + return True - def get_config(self): - """Returns the Config instance this choice is from.""" - return self._config - - def get_name(self): - """For named choices, returns the name. Returns None for unnamed - choices. No named choices appear anywhere in the kernel Kconfig files - as of Linux 3.7.0-rc8.""" - return self._name - - def get_type(self): - """Returns the type of the choice. See Symbol.get_type().""" - return self._type - - def get_prompts(self): - """Returns a list of prompts defined for the choice, in the order they - appear in the configuration files. Returns the empty list for choices - with no prompt. - - This list will have a single entry for the vast majority of choices - having prompts, but having multiple prompts for a single choice is - possible through having multiple 'choice' entries for it (though I'm - not sure if that ever happens in practice).""" - return [prompt for prompt, _ in self._orig_prompts] - - def get_help(self): - """Returns the help text of the choice, or None if the choice has no - help text.""" - return self._help - - def get_parent(self): - """Returns the menu or choice statement that contains the choice, or - None if the choice is at the top level. Note that if statements are - treated as syntactic sugar and do not have an explicit class - representation.""" - return self._parent - - def get_def_locations(self): - """Returns a list of (filename, linenr) tuples, where filename (string) - and linenr (int) represent a location where the choice is defined. For - the vast majority of choices (all of them as of Linux 3.7.0-rc8) this - list will only contain one element, but its possible for named choices - to be defined in multiple locations.""" - return self._def_locations - - def get_selection(self): - """Returns the symbol selected (either by the user or through - defaults), or None if either no symbol is selected or the mode is not - "y".""" - if self._cached_selection is not None: - if self._cached_selection == _NO_SELECTION: - return None - return self._cached_selection + if not ((self.orig_type == BOOL and value in (0, 2) ) or + (self.orig_type == TRISTATE and value in (0, 1, 2))): + self.kconfig._warn("the value '{}' is invalid for the choice, " + "which has type {}. Assignment ignored" + .format(value, TYPE_TO_STR[self.orig_type])) + return False - if self.get_mode() != "y": - return self._cache_ret(None) + self.user_value = value + self._was_set = True + self._rec_invalidate() - # User choice available? - if self._user_val is not None and \ - _get_visibility(self._user_val) == "y": - return self._cache_ret(self._user_val) + return True - if self._optional: - return self._cache_ret(None) + def unset_value(self): + """ + Resets the user value (mode) and user selection of the Choice, as if + the user had never touched the mode or any of the choice symbols. + """ + if self.user_value is not None or self.user_selection: + self.user_value = self.user_selection = None + self._rec_invalidate() - return self._cache_ret(self.get_selection_from_defaults()) + def __repr__(self): + """ + Returns a string with information about the choice when it is evaluated + on e.g. the interactive Python prompt. + """ + fields = [] - def get_selection_from_defaults(self): - """Like Choice.get_selection(), but acts as if no symbol has been - selected by the user and no 'optional' flag is in effect.""" + fields.append("choice" if self.name is None else \ + "choice " + self.name) + fields.append(TYPE_TO_STR[self.type]) - # Does any 'default SYM [if <cond>]' property apply? - for sym, cond_expr in self._def_exprs: - if (self._config._eval_expr(cond_expr) != "n" and - # Must be visible too - _get_visibility(sym) != "n"): - return sym + for node in self.nodes: + if node.prompt: + fields.append('"{}"'.format(node.prompt[0])) - # Otherwise, pick the first visible symbol - for sym in self._actual_symbols: - if _get_visibility(sym) != "n": - return sym + fields.append("mode " + self.str_value) - # Couldn't find a default - return None + if self.user_value is not None: + fields.append('user mode {}'.format(TRI_TO_STR[self.user_value])) + + if self.selection: + fields.append("{} selected".format(self.selection.name)) + + if self.user_selection: + user_sel_str = "{} selected by user" \ + .format(self.user_selection.name) + + if self.selection is not self.user_selection: + user_sel_str += " (overridden)" + + fields.append(user_sel_str) + + fields.append("visibility " + TRI_TO_STR[self.visibility]) - def get_user_selection(self): - """If the choice is in "y" mode and has a user-selected symbol, returns - that symbol. Otherwise, returns None.""" - return self._user_val - - def get_items(self): - """Gets all items contained in the choice in the same order as within - the configuration ("items" instead of "symbols" since choices and - comments might appear within choices. This only happens in one place as - of Linux 3.7.0-rc8, in drivers/usb/gadget/Kconfig).""" - return self._block - - def get_symbols(self): - """Returns a list containing the choice's symbols. - - A quirk (perhaps a bug) of Kconfig is that you can put items within a - choice that will not be considered members of the choice insofar as - selection is concerned. This happens for example if one symbol within a - choice 'depends on' the symbol preceding it, or if you put non-symbol - items within choices. - - As of Linux 3.7.0-rc8, this seems to be used intentionally in one - place: drivers/usb/gadget/Kconfig. - - This function returns the "proper" symbols of the choice in the order - they appear in the choice, excluding such items. If you want all items - in the choice, use get_items().""" - return self._actual_symbols - - def get_referenced_symbols(self, refs_from_enclosing=False): - """See Symbol.get_referenced_symbols().""" - res = [] - - for _, cond_expr in self._orig_prompts: - _expr_syms(cond_expr, res) - for val_expr, cond_expr in self._orig_def_exprs: - _expr_syms(val_expr, res) - _expr_syms(cond_expr, res) - - if refs_from_enclosing: - _expr_syms(self._deps_from_containing, res) - - # Remove duplicates and return - return set(res) - - def get_visibility(self): - """Returns the visibility of the choice statement: one of "n", "m" or - "y". This acts as an upper limit on the mode of the choice (though bool - choices can only have the mode "y"). See the class documentation for an - explanation of modes.""" - return _get_visibility(self) - - def get_mode(self): - """Returns the mode of the choice. See the class documentation for - an explanation of modes.""" - minimum_mode = "n" if self._optional else "m" - mode = self._user_mode if self._user_mode is not None else minimum_mode - mode = self._config._eval_min(mode, _get_visibility(self)) - - # Promote "m" to "y" for boolean choices - if mode == "m" and self._type == BOOL: - return "y" - - return mode - - def is_optional(self): - """Returns True if the choice has the 'optional' flag set (and so will - default to "n" mode).""" - return self._optional + if self.is_optional: + fields.append("optional") + + for node in self.nodes: + fields.append("{}:{}".format(node.filename, node.linenr)) + + return "<{}>".format(", ".join(fields)) def __str__(self): - """Returns a string containing various information about the choice - statement.""" - return self._config._get_sym_or_choice_str(self) + """ + Returns a string representation of the choice when it is printed, + matching the Kconfig format (though without the contained choice + symbols). Prompts and help texts are included, though they really + belong to the choice's menu nodes rather than the choice itself. + + See Symbol.__str__() as well. + """ + return _sym_choice_str(self) # # Private methods # def __init__(self): - """Choice constructor -- not intended to be called directly by - Kconfiglib clients.""" - + """ + Choice constructor -- not intended to be called directly by Kconfiglib + clients. + """ # These attributes are always set on the instance from outside and # don't need defaults: - # _config - # _parent - # _deps_from_containing - # _actual_symbols (set in _determine_actual_symbols()) + # kconfig + + self.name = None + self.orig_type = UNKNOWN + self.syms = [] + self.defaults = [] - self._name = None # Yes, choices can be named - self._type = UNKNOWN - self._prompts = [] - self._def_exprs = [] # 'default' properties - self._help = None # Help text + self.nodes = [] - self._user_val = None - self._user_mode = None + self.user_value = self.user_selection = None + + # Checked by _make_depend_on(). Just set it to avoid having to + # special-case choices. + self.is_constant = False + # See Kconfig._build_dep() + self._dependents = set() # The prompts and default values without any dependencies from # enclosing menus and ifs propagated - self._orig_prompts = [] - self._orig_def_exprs = [] - - # See Choice.get_def_locations() - self._def_locations = [] + self.defaults = [] # Cached values - self._cached_selection = None - self._cached_visibility = None - - self._optional = False - - # Contained items - self._block = [] - - def _determine_actual_symbols(self): - """If a symbol's visibility depends on the preceding symbol within a - choice, it is no longer viewed as a choice item. (This is quite - possibly a bug, but some things consciously use it... ugh. It stems - from automatic submenu creation.) In addition, it's possible to have - choices and comments within choices, and those shouldn't be considered - choice items either. Only drivers/usb/gadget/Kconfig seems to depend on - any of this. This method computes the "actual" items in the choice and - sets the _is_choice_sym flag on them (retrieved via - is_choice_symbol()). - - Don't let this scare you: an earlier version simply checked for a - sequence of symbols where all symbols after the first appeared in the - 'depends on' expression of the first, and that worked fine. The added - complexity is to be future-proof in the event that - drivers/usb/gadget/Kconfig turns even more sinister. It might very well - be overkilling things (especially if that file is refactored ;).""" - - self._actual_symbols = [] - - # Items might depend on each other in a tree structure, so we need a - # stack to keep track of the current tentative parent - stack = [] - - for item in self._block: - if not isinstance(item, Symbol): - stack = [] - continue + self._cached_vis = self._cached_assignable = None + self._cached_selection = _NO_CACHED_SELECTION - while stack: - if item._has_auto_menu_dep_on(stack[-1]): - # The item should not be viewed as a choice item, so don't - # set item._is_choice_sym - stack.append(item) - break - else: - stack.pop() - else: - item._is_choice_sym = True - self._actual_symbols.append(item) - stack.append(item) - - def _cache_ret(self, selection): - # As None is used to indicate the lack of a cached value we can't use - # that to cache the fact that the choice has no selection. Instead, we - # use the symbolic constant _NO_SELECTION. - if selection is None: - self._cached_selection = _NO_SELECTION - else: - self._cached_selection = selection + self.is_optional = False + + def _get_assignable(self): + """ + Worker function for the 'assignable' attribute. + """ + # Warning: See Symbol._rec_invalidate(), and note that this is a hidden + # function call (property magic) + vis = self.visibility + + if not vis: + return () - return selection + if vis == 2: + if not self.is_optional: + return (2,) if self.type == BOOL else (1, 2) + return (0, 2) if self.type == BOOL else (0, 1, 2) + + # vis == 1 + + return (0, 1) if self.is_optional else (1,) def _invalidate(self): - self._cached_selection = None - self._cached_visibility = None + self._cached_vis = self._cached_assignable = None + self._cached_selection = _NO_CACHED_SELECTION - def _unset_user_value(self): + def _rec_invalidate(self): + """ + See Symbol._rec_invalidate() + """ self._invalidate() - self._user_val = None - self._user_mode = None - def _add_config_strings(self, add_fn): - for item in self._block: - item._add_config_strings(add_fn) + for item in self._dependents: + if item._cached_vis is not None: + item._rec_invalidate() + +class MenuNode(object): + """ + Represents a menu node in the configuration. This corresponds to an entry + in e.g. the 'make menuconfig' interface, though non-visible choices, menus, + and comments also get menu nodes. If a symbol or choice is defined in + multiple locations, it gets one menu node for each location. + + The top-level menu node, corresponding to the implicit top-level menu, is + available in Kconfig.top_node. + + The menu nodes for a Symbol or Choice can be found in the + Symbol/Choice.nodes attribute. Menus and comments are represented as plain + menu nodes, with their text stored in the prompt attribute (prompt[0]). + This mirrors the C implementation. + + The following attributes are available on MenuNode instances. They should + be viewed as read-only. + + item: + Either a Symbol, a Choice, or one of the constants MENU and COMMENT. + Menus and comments are represented as plain menu nodes. Ifs are collapsed + (matching the C implementation) and do not appear in the final menu tree. + + next: + The following menu node. None if there is no following node. + + list: + The first child menu node. None if there are no children. + + Choices and menus naturally have children, but Symbols can also have + children because of menus created automatically from dependencies (see + kconfig-language.txt). + + parent: + The parent menu node. None if there is no parent. + + prompt: + A (string, cond) tuple with the prompt for the menu node and its + conditional expression (which is self.kconfig.y if there is no + condition). None if there is no prompt. + + For symbols and choices, the prompt is stored in the MenuNode rather than + the Symbol or Choice instance. For menus and comments, the prompt holds + the text. + + help: + The help text for the menu node for Symbols and Choices. None if there is + no help text. Always stored in the node rather than the Symbol or Choice. + It is possible to have a separate help text at each location if a symbol + is defined in multiple locations. + + dep: + The 'depends on' dependencies for the menu node, or self.kconfig.y if + there are no dependencies. Parent dependencies are propagated to this + attribute, and this attribute is then in turn propagated to the + properties of symbols and choices. + + If a symbol is defined in multiple locations, only the properties defined + at a particular location get the corresponding MenuNode.dep dependencies + propagated to them. + + visibility: + The 'visible if' dependencies for the menu node (which must represent a + menu), or self.kconfig.y if there are no 'visible if' dependencies. + 'visible if' dependencies are recursively propagated to the prompts of + symbols and choices within the menu. + + is_menuconfig: + True if the symbol for the menu node (it must be a symbol) was defined + with 'menuconfig' rather than 'config' (at this location). This is a hint + on how to display the menu entry (display the children in a separate menu + rather than indenting them). It's ignored internally by Kconfiglib, + except when printing symbols. + + filename/linenr: + The location where the menu node appears. + + kconfig: + The Kconfig instance the menu node is from. + """ + __slots__ = ( + "dep", + "filename", + "help", + "is_menuconfig", + "item", + "kconfig", + "linenr", + "list", + "next", + "parent", + "prompt", + "visibility", + ) + + def __repr__(self): + """ + Returns a string with information about the menu node when it is + evaluated on e.g. the interactive Python prompt. + """ + fields = [] -class Comment(Item): + if isinstance(self.item, Symbol): + fields.append("menu node for symbol " + self.item.name) - """Represents a comment statement.""" + elif isinstance(self.item, Choice): + s = "menu node for choice" + if self.item.name is not None: + s += " " + self.item.name + fields.append(s) - # - # Public interface - # + elif self.item == MENU: + fields.append("menu node for menu") + + elif self.item == COMMENT: + fields.append("menu node for comment") + + elif self.item is None: + fields.append("menu node for if (should not appear in the final " + " tree)") + + else: + raise InternalError("unable to determine type in " + "MenuNode.__repr__()") + + if self.prompt: + fields.append('prompt "{}" (visibility {})' + .format(self.prompt[0], + TRI_TO_STR[expr_value(self.prompt[1])])) - def get_config(self): - """Returns the Config instance this comment is from.""" - return self._config + if isinstance(self.item, Symbol) and self.is_menuconfig: + fields.append("is menuconfig") - def get_text(self): - """Returns the text of the comment.""" - return self._text + fields.append("deps " + TRI_TO_STR[expr_value(self.dep)]) - def get_parent(self): - """Returns the menu or choice statement that contains the comment, or - None if the comment is at the top level. Note that if statements are - treated as syntactic sugar and do not have an explicit class - representation.""" - return self._parent + if self.item == MENU: + fields.append("'visible if' deps " + \ + TRI_TO_STR[expr_value(self.visibility)]) - def get_location(self): - """Returns the location of the comment as a (filename, linenr) tuple, - where filename is a string and linenr an int.""" - return (self._filename, self._linenr) + if isinstance(self.item, (Symbol, Choice)) and self.help is not None: + fields.append("has help") - def get_visibility(self): - """Returns the visibility of the comment. See also - Symbol.get_visibility().""" - return self._config._eval_expr(self._menu_dep) + if self.list: + fields.append("has child") - def get_referenced_symbols(self, refs_from_enclosing=False): - """See Symbol.get_referenced_symbols().""" - res = [] + if self.next: + fields.append("has next") - _expr_syms(self._orig_deps - if not refs_from_enclosing else - self._menu_dep, - res) + fields.append("{}:{}".format(self.filename, self.linenr)) - # Remove duplicates and return - return set(res) + return "<{}>".format(", ".join(fields)) def __str__(self): - """Returns a string containing various information about the - comment.""" - dep_str = self._config._expr_val_str(self._orig_deps, - "(no dependencies)") - - additional_deps_str = " " + \ - self._config._expr_val_str(self._deps_from_containing, - "(no additional dependencies)") - - return _lines("Comment", - "Text: " + self._text, - "Dependencies: " + dep_str, - "Additional dependencies from enclosing menus and ifs:", - additional_deps_str, - "Location: {}:{}".format(self._filename, self._linenr)) + """ + Returns a string representation of the MenuNode, matching the Kconfig + format. - # - # Private methods - # + For Symbol and Choice menu nodes, this function simply calls through to + MenuNode.item.__str__(). For MENU and COMMENT nodes, a Kconfig-like + representation of the menu or comment is returned. + """ + if isinstance(self.item, (Symbol, Choice)): + return self.item.__str__() - # These attributes are always set on the instance from outside and don't - # need defaults: - # _config - # _parent - # _filename - # _linenr - # _text - # _deps_from_containing - # _menu_dep - # _orig_deps - - def _add_config_strings(self, add_fn): - if self._config._eval_expr(self._menu_dep) != "n": - add_fn("\n#\n# {}\n#\n".format(self._text)) - -class Kconfig_Syntax_Error(Exception): - """Exception raised for syntax errors.""" - pass + if self.item in (MENU, COMMENT): + s = ("menu" if self.item == MENU else "comment") + \ + ' "{}"\n'.format(escape(self.prompt[0])) -class Internal_Error(Exception): - """Exception raised for internal errors.""" - pass + if self.dep is not self.kconfig.y: + s += "\tdepends on {}\n".format(expr_str(self.dep)) -# -# Public functions -# + if self.item == MENU and self.visibility is not self.kconfig.y: + s += "\tvisible if {}\n".format(expr_str(self.visibility)) -def tri_less(v1, v2): - """Returns True if the tristate v1 is less than the tristate v2, where "n", - "m" and "y" are ordered from lowest to highest.""" - return _TRI_TO_INT[v1] < _TRI_TO_INT[v2] + return s -def tri_less_eq(v1, v2): - """Returns True if the tristate v1 is less than or equal to the tristate - v2, where "n", "m" and "y" are ordered from lowest to highest.""" - return _TRI_TO_INT[v1] <= _TRI_TO_INT[v2] + # 'if' node. Should never appear in the final tree. + return "if " + expr_str(self.dep) -def tri_greater(v1, v2): - """Returns True if the tristate v1 is greater than the tristate v2, where - "n", "m" and "y" are ordered from lowest to highest.""" - return _TRI_TO_INT[v1] > _TRI_TO_INT[v2] +class KconfigSyntaxError(Exception): + """ + Exception raised for syntax errors. + """ + pass -def tri_greater_eq(v1, v2): - """Returns True if the tristate v1 is greater than or equal to the tristate - v2, where "n", "m" and "y" are ordered from lowest to highest.""" - return _TRI_TO_INT[v1] >= _TRI_TO_INT[v2] +class InternalError(Exception): + """ + Exception raised for internal errors. + """ + pass # -# Internal classes +# Public functions # -class _Feed(object): +def expr_value(expr): + """ + Evaluates the expression 'expr' to a tristate value. Returns 0 (n), 1 (m), + or 2 (y). - """Class for working with sequences in a stream-like fashion; handy for - tokens.""" + 'expr' must be an already-parsed expression from a Symbol, Choice, or + MenuNode property. To evaluate an expression represented as a string, use + Kconfig.eval_string(). - # This would be more helpful on the item classes, but would remove some - # flexibility - __slots__ = ['items', 'length', 'i'] + Passing subexpressions of expressions to this function works as expected. + """ + if not isinstance(expr, tuple): + return expr.tri_value - def __init__(self, items): - self.items = items - self.length = len(self.items) - self.i = 0 + if expr[0] == AND: + v1 = expr_value(expr[1]) + # Short-circuit the n case as an optimization (~5% faster + # allnoconfig.py and allyesconfig.py, as of writing) + return 0 if not v1 else min(v1, expr_value(expr[2])) - def get_next(self): - if self.i >= self.length: - return None - item = self.items[self.i] - self.i += 1 - return item - - def peek_next(self): - return None if self.i >= self.length else self.items[self.i] - - def check(self, token): - """Check if the next token is 'token'. If so, remove it from the token - feed and return True. Otherwise, leave it in and return False.""" - if self.i < self.length and self.items[self.i] == token: - self.i += 1 - return True - return False + if expr[0] == OR: + v1 = expr_value(expr[1]) + # Short-circuit the y case as an optimization + return 2 if v1 == 2 else max(v1, expr_value(expr[2])) - def unget_all(self): - self.i = 0 + if expr[0] == NOT: + return 2 - expr_value(expr[1]) -class _FileFeed(object): + if expr[0] in _RELATIONS: + # Implements <, <=, >, >= comparisons as well. These were added to + # kconfig in 31847b67 (kconfig: allow use of relations other than + # (in)equality). - """Feeds lines from a file. Keeps track of the filename and current line - number. Joins any line ending in \\ with the following line. We need to be - careful to get the line number right in the presence of continuation - lines.""" + # This mirrors the C tools pretty closely. Perhaps there's a more + # pythonic way to structure this. - __slots__ = ['filename', 'lines', 'length', 'linenr'] + oper, op1, op2 = expr - def __init__(self, filename): - self.filename = filename - with open(filename) as f: - # No interleaving of I/O and processing yet. Don't know if it would - # help. - self.lines = f.readlines() - self.length = len(self.lines) - self.linenr = 0 - - def get_next(self): - if self.linenr >= self.length: - return None - line = self.lines[self.linenr] - self.linenr += 1 - while line.endswith("\\\n"): - line = line[:-2] + self.lines[self.linenr] - self.linenr += 1 - return line + # If both operands are strings... + if op1.orig_type == STRING and op2.orig_type == STRING: + # ...then compare them lexicographically + comp = _strcmp(op1.str_value, op2.str_value) + else: + # Otherwise, try to compare them as numbers... + try: + comp = int(op1.str_value, _TYPE_TO_BASE[op1.orig_type]) - \ + int(op2.str_value, _TYPE_TO_BASE[op2.orig_type]) + except ValueError: + # Fall back on a lexicographic comparison if the operands don't + # parse as numbers + comp = _strcmp(op1.str_value, op2.str_value) + + if oper == EQUAL: res = comp == 0 + elif oper == UNEQUAL: res = comp != 0 + elif oper == LESS: res = comp < 0 + elif oper == LESS_EQUAL: res = comp <= 0 + elif oper == GREATER: res = comp > 0 + elif oper == GREATER_EQUAL: res = comp >= 0 + + return 2*res + + _internal_error("Internal error while evaluating expression: " + "unknown operation {}.".format(expr[0])) + +def expr_str(expr): + """ + Returns the string representation of the expression 'expr', as in a Kconfig + file. + + Passing subexpressions of expressions to this function works as expected. + """ + if not isinstance(expr, tuple): + if isinstance(expr, Choice): + if expr.name is not None: + return "<choice {}>".format(expr.name) + return "<choice>" + + # Symbol + + if expr.is_constant: + return '"{}"'.format(escape(expr.name)) + + return expr.name + + if expr[0] == NOT: + if isinstance(expr[1], Symbol): + return "!" + expr_str(expr[1]) + return "!({})".format(expr_str(expr[1])) - def peek_next(self): - linenr = self.linenr - if linenr >= self.length: - return None - line = self.lines[linenr] - while line.endswith("\\\n"): - linenr += 1 - line = line[:-2] + self.lines[linenr] - return line + if expr[0] == AND: + return "{} && {}".format(_format_and_op(expr[1]), + _format_and_op(expr[2])) - def unget(self): - self.linenr -= 1 - while self.lines[self.linenr].endswith("\\\n"): - self.linenr -= 1 + if expr[0] == OR: + return "{} || {}".format(expr_str(expr[1]), expr_str(expr[2])) - def next_nonblank(self): - """Removes lines up to and including the next non-blank (not all-space) - line and returns it. Returns None if there are no more non-blank - lines.""" - while 1: - line = self.get_next() - if line is None or not line.isspace(): - return line + # Relation + return "{} {} {}".format(expr_str(expr[1]), + _REL_TO_STR[expr[0]], + expr_str(expr[2])) + +# escape()/unescape() helpers +_escape_re_sub = re.compile(r'(["\\])').sub +_unescape_re_sub = re.compile(r"\\(.)").sub + +def escape(s): + r""" + Escapes the string 's' in the same fashion as is done for display in + Kconfig format and when writing strings to a .config file. " and \ are + replaced by \" and \\, respectively. + """ + return _escape_re_sub(r"\\\1", s) + +def unescape(s): + r""" + Unescapes the string 's'. \ followed by any character is replaced with just + that character. Used internally when reading .config files. + """ + return _unescape_re_sub(r"\1", s) # # Internal functions # def _get_visibility(sc): - """Symbols and Choices have a "visibility" that acts as an upper bound on - the values a user can set for them, corresponding to the visibility in e.g. + """ + Symbols and Choices have a "visibility" that acts as an upper bound on the + values a user can set for them, corresponding to the visibility in e.g. 'make menuconfig'. This function calculates the visibility for the Symbol - or Choice 'sc' -- the logic is nearly identical.""" - if sc._cached_visibility is None: - vis = "n" - for _, cond_expr in sc._prompts: - vis = sc._config._eval_max(vis, cond_expr) - - if isinstance(sc, Symbol) and sc._is_choice_sym: - choice = sc._parent - if choice._type == TRISTATE and sc._type != TRISTATE and \ - choice.get_mode() != "y": - # Non-tristate choice symbols in tristate choices depend on the - # choice being in mode "y" - vis = "n" - elif sc._type == TRISTATE and vis == "m" and \ - choice.get_mode() == "y": - # Choice symbols with visibility "m" are not visible if the - # choice has mode "y" - vis = "n" - else: - vis = sc._config._eval_min(vis, _get_visibility(choice)) - - # Promote "m" to "y" if we're dealing with a non-tristate - if vis == "m" and sc._type != TRISTATE: - vis = "y" - - sc._cached_visibility = vis - - return sc._cached_visibility - -def _make_and(e1, e2): - """Constructs an _AND (&&) expression. Performs trivial simplification. - Nones equate to 'y'. - - Returns None if e1 == e2 == None, so that ANDing two nonexistent - expressions gives a nonexistent expression.""" - if e1 is None or e1 == "y": - return e2 - if e2 is None or e2 == "y": - return e1 - return (_AND, e1, e2) - -def _make_or(e1, e2): - """Constructs an _OR (||) expression. Performs trivial simplification and - avoids Nones. Nones equate to 'y', which is usually what we want, but needs - to be kept in mind.""" - - # Perform trivial simplification and avoid None's (which - # correspond to y's) - if e1 is None or e2 is None or e1 == "y" or e2 == "y": - return "y" - if e1 == "n": - return e2 - return (_OR, e1, e2) - -def _expr_syms_rec(expr, res): - """_expr_syms() helper. Recurses through expressions.""" - if isinstance(expr, Symbol): - res.append(expr) - elif isinstance(expr, str): - return - elif expr[0] in (_AND, _OR): - _expr_syms_rec(expr[1], res) - _expr_syms_rec(expr[2], res) - elif expr[0] == _NOT: - _expr_syms_rec(expr[1], res) + or Choice 'sc' -- the logic is nearly identical. + """ + vis = 0 + + for node in sc.nodes: + if node.prompt: + vis = max(vis, expr_value(node.prompt[1])) + + if isinstance(sc, Symbol) and sc.choice: + if sc.choice.orig_type == TRISTATE and sc.orig_type != TRISTATE and \ + sc.choice.tri_value != 2: + # Non-tristate choice symbols are only visible in y mode + return 0 + + if sc.orig_type == TRISTATE and vis == 1 and sc.choice.tri_value == 2: + # Choice symbols with m visibility are not visible in y mode + return 0 + + # Promote m to y if we're dealing with a non-tristate. This might lead to + # infinite recursion if something really weird is done with MODULES, but + # it's not a problem in practice. + if vis == 1 and \ + (sc.orig_type != TRISTATE or not sc.kconfig.modules.tri_value): + return 2 + + return vis + +def _make_depend_on(sym, expr): + """ + Adds 'sym' as a dependency to all symbols in 'expr'. Constant symbols in + 'expr' are skipped as they can never change value anyway. + """ + if not isinstance(expr, tuple): + if not expr.is_constant: + expr._dependents.add(sym) + + elif expr[0] in (AND, OR): + _make_depend_on(sym, expr[1]) + _make_depend_on(sym, expr[2]) + + elif expr[0] == NOT: + _make_depend_on(sym, expr[1]) + elif expr[0] in _RELATIONS: - if isinstance(expr[1], Symbol): - res.append(expr[1]) - if isinstance(expr[2], Symbol): - res.append(expr[2]) + if not expr[1].is_constant: + expr[1]._dependents.add(sym) + if not expr[2].is_constant: + expr[2]._dependents.add(sym) + else: _internal_error("Internal error while fetching symbols from an " "expression with token stream {}.".format(expr)) -def _expr_syms(expr, res): - """append()s the symbols in 'expr' to 'res'. Does not remove duplicates.""" - if expr is not None: - _expr_syms_rec(expr, res) - -def _str_val(obj): - """Returns the value of obj as a string. If obj is not a string (constant - symbol), it must be a Symbol.""" - return obj if isinstance(obj, str) else obj.get_value() - def _format_and_op(expr): - """_expr_to_str() helper. Returns the string representation of 'expr', - which is assumed to be an operand to _AND, with parentheses added if - needed.""" - if isinstance(expr, tuple) and expr[0] == _OR: - return "({})".format(_expr_to_str(expr)) - return _expr_to_str(expr) - -def _expr_to_str(expr): - if isinstance(expr, str): - return '"{}"'.format(expr) - - if isinstance(expr, Symbol): - return expr._name - - if expr[0] == _NOT: - if isinstance(expr[1], (str, Symbol)): - return "!" + _expr_to_str(expr[1]) - return "!({})".format(_expr_to_str(expr[1])) - - if expr[0] == _AND: - return "{} && {}".format(_format_and_op(expr[1]), - _format_and_op(expr[2])) - - if expr[0] == _OR: - return "{} || {}".format(_expr_to_str(expr[1]), - _expr_to_str(expr[2])) - - # Relation - return "{} {} {}".format(_expr_to_str(expr[1]), - _RELATION_TO_STR[expr[0]], - _expr_to_str(expr[2])) - -def _type_and_val(obj): - """Helper to hack around the fact that we don't represent plain strings as - Symbols. Takes either a plain string or a Symbol and returns a - (<type>, <value>) tuple.""" - return (obj._type, obj.get_value()) \ - if not isinstance(obj, str) \ - else (STRING, obj) + """ + expr_str() helper. Returns the string representation of 'expr', which is + assumed to be an operand to AND, with parentheses added if needed. + """ + if isinstance(expr, tuple) and expr[0] == OR: + return "({})".format(expr_str(expr)) + return expr_str(expr) def _indentation(line): - """Returns the length of the line's leading whitespace, treating tab stops - as being spaced 8 characters apart.""" + """ + Returns the length of the line's leading whitespace, treating tab stops as + being spaced 8 characters apart. + """ line = line.expandtabs() return len(line) - len(line.lstrip()) def _deindent(line, indent): - """Deindent 'line' by 'indent' spaces.""" + """ + Deindents 'line' by 'indent' spaces. + """ line = line.expandtabs() if len(line) <= indent: return line @@ -3546,37 +3698,291 @@ def _is_base_n(s, n): return False def _strcmp(s1, s2): - """strcmp()-alike that returns -1, 0, or 1.""" + """ + strcmp()-alike that returns -1, 0, or 1. + """ return (s1 > s2) - (s1 < s2) -def _lines(*args): - """Returns a string consisting of all arguments, with newlines inserted - between them.""" - return "\n".join(args) - def _stderr_msg(msg, filename, linenr): if filename is not None: - sys.stderr.write("{}:{}: ".format(filename, linenr)) - sys.stderr.write(msg + "\n") + msg = "{}:{}: {}".format(filename, linenr, msg) -def _tokenization_error(s, filename, linenr): - loc = "" if filename is None else "{}:{}: ".format(filename, linenr) - raise Kconfig_Syntax_Error("{}Couldn't tokenize '{}'" - .format(loc, s.strip())) - -def _parse_error(s, msg, filename, linenr): - loc = "" if filename is None else "{}:{}: ".format(filename, linenr) - raise Kconfig_Syntax_Error("{}Couldn't parse '{}'{}" - .format(loc, s.strip(), - "." if msg is None else ": " + msg)) + sys.stderr.write(msg + "\n") def _internal_error(msg): - raise Internal_Error( + raise InternalError( msg + "\nSorry! You may want to send an email to ulfalizer a.t Google's " "email service to tell me about this. Include the message above and " "the stack trace and describe what you were doing.") +# Printing functions + +def _sym_choice_str(sc): + """ + Symbol/choice __str__() implementation. These have many properties in + common, so it makes sense to handle them together. + """ + lines = [] + + def indent_add(s): + lines.append("\t" + s) + + # We print the prompt(s) and help text(s) too as a convenience, even though + # they're actually part of the MenuNode. If a symbol or choice is defined + # in multiple locations (has more than one MenuNode), we output one + # statement for each location, and print all the properties that belong to + # the symbol/choice itself only at the first location. This gives output + # that would function if fed to a Kconfig parser, even for such + # symbols/choices (choices defined in multiple locations gets a bit iffy + # since they also have child nodes, though I've never seen such a choice). + + if not sc.nodes: + return "" + + for node in sc.nodes: + if isinstance(sc, Symbol): + if node.is_menuconfig: + lines.append("menuconfig " + sc.name) + else: + lines.append("config " + sc.name) + else: + if sc.name is None: + lines.append("choice") + else: + lines.append("choice " + sc.name) + + if node is sc.nodes[0] and sc.orig_type != UNKNOWN: + indent_add(TYPE_TO_STR[sc.orig_type]) + + if node.prompt: + prompt, cond = node.prompt + prompt_str = 'prompt "{}"'.format(escape(prompt)) + if cond is not sc.kconfig.y: + prompt_str += " if " + expr_str(cond) + indent_add(prompt_str) + + if node is sc.nodes[0]: + if isinstance(sc, Symbol): + if sc.is_allnoconfig_y: + indent_add("option allnoconfig_y") + + if sc is sc.kconfig.defconfig_list: + indent_add("option defconfig_list") + + if sc.env_var is not None: + indent_add('option env="{}"'.format(sc.env_var)) + + if sc is sc.kconfig.modules: + indent_add("option modules") + + if isinstance(sc, Symbol): + for low, high, cond in sc.ranges: + range_string = "range {} {}" \ + .format(expr_str(low), expr_str(high)) + if cond is not sc.kconfig.y: + range_string += " if " + expr_str(cond) + indent_add(range_string) + + for default, cond in sc.defaults: + default_string = "default " + expr_str(default) + if cond is not sc.kconfig.y: + default_string += " if " + expr_str(cond) + indent_add(default_string) + + if isinstance(sc, Choice) and sc.is_optional: + indent_add("optional") + + if isinstance(sc, Symbol): + for select, cond in sc.selects: + select_string = "select " + select.name + if cond is not sc.kconfig.y: + select_string += " if " + expr_str(cond) + indent_add(select_string) + + for imply, cond in sc.implies: + imply_string = "imply " + imply.name + if cond is not sc.kconfig.y: + imply_string += " if " + expr_str(cond) + indent_add(imply_string) + + if node.help is not None: + indent_add("help") + for line in node.help.splitlines(): + indent_add(" " + line) + + # Add a blank line if there are more nodes to print + if node is not sc.nodes[-1]: + lines.append("") + + return "\n".join(lines) + "\n" + +# Menu manipulation + +def _expr_depends_on(expr, sym): + """ + Reimplementation of expr_depends_symbol() from mconf.c. Used to + determine if a submenu should be implicitly created. This also influences + which items inside choice statements are considered choice items. + """ + if not isinstance(expr, tuple): + return expr is sym + + if expr[0] in (EQUAL, UNEQUAL): + # Check for one of the following: + # sym = m/y, m/y = sym, sym != n, n != sym + + left, right = expr[1:] + + if right is sym: + left, right = right, left + + if left is not sym: + return False + + return (expr[0] == EQUAL and right is sym.kconfig.m or \ + right is sym.kconfig.y) or \ + (expr[0] == UNEQUAL and right is sym.kconfig.n) + + if expr[0] == AND: + return _expr_depends_on(expr[1], sym) or \ + _expr_depends_on(expr[2], sym) + + return False + +def _has_auto_menu_dep(node1, node2): + """ + Returns True if node2 has an "automatic menu dependency" on node1. If node2 + has a prompt, we check its condition. Otherwise, we look directly at + node2.dep. + """ + if node2.prompt: + return _expr_depends_on(node2.prompt[1], node1.item) + + # If we have no prompt, use the menu node dependencies instead + return _expr_depends_on(node2.dep, node1.item) + +def _check_auto_menu(node): + """ + Looks for menu nodes after 'node' that depend on it. Creates an implicit + menu rooted at 'node' with the nodes as the children if such nodes are + found. The recursive call to _finalize_tree() makes this work recursively. + """ + cur = node + while cur.next and _has_auto_menu_dep(node, cur.next): + _finalize_tree(cur.next) + cur = cur.next + cur.parent = node + + if cur is not node: + node.list = node.next + node.next = cur.next + cur.next = None + +def _flatten(node): + """ + "Flattens" menu nodes without prompts (e.g. 'if' nodes and non-visible + symbols with children from automatic menu creation) so that their children + appear after them instead. This gives a clean menu structure with no + unexpected "jumps" in the indentation. + """ + while node: + if node.list and (not node.prompt or node.prompt[0] == ""): + + last_node = node.list + while 1: + last_node.parent = node.parent + if not last_node.next: + break + last_node = last_node.next + + last_node.next = node.next + node.next = node.list + node.list = None + + node = node.next + +def _remove_ifs(node): + """ + Removes 'if' nodes (which can be recognized by MenuNode.item being None), + which are assumed to already have been flattened. The C implementation + doesn't bother to do this, but we expose the menu tree directly, and it + makes it nicer to work with. + """ + first = node.list + while first and first.item is None: + first = first.next + + cur = first + while cur: + if cur.next and cur.next.item is None: + cur.next = cur.next.next + cur = cur.next + + node.list = first + +def _finalize_choice(node): + """ + Finalizes a choice, marking each symbol whose menu node has the choice as + the parent as a choice symbol, and automatically determining types if not + specified. + """ + choice = node.item + + cur = node.list + while cur: + if isinstance(cur.item, Symbol): + cur.item.choice = choice + choice.syms.append(cur.item) + cur = cur.next + + # If no type is specified for the choice, its type is that of + # the first choice item with a specified type + if choice.orig_type == UNKNOWN: + for item in choice.syms: + if item.orig_type != UNKNOWN: + choice.orig_type = item.orig_type + break + + # Each choice item of UNKNOWN type gets the type of the choice + for sym in choice.syms: + if sym.orig_type == UNKNOWN: + sym.orig_type = choice.orig_type + +def _finalize_tree(node): + """ + Creates implicit menus from dependencies (see kconfig-language.txt), + removes 'if' nodes, and finalizes choices. This pretty closely mirrors + menu_finalize() from the C implementation, though we propagate dependencies + during parsing instead. + """ + # The ordering here gets a bit tricky. It's important to do things in this + # order to have everything work out correctly. + + if node.list: + # The menu node has children. Finalize them. + cur = node.list + while cur: + _finalize_tree(cur) + # Note: _finalize_tree() might have changed cur.next. This is + # expected, so that we jump over e.g. implicitly created submenus. + cur = cur.next + + elif node.item is not None: + # The menu node has no children (yet). See if we can create an implicit + # menu rooted at it (due to menu nodes after it depending on it). + _check_auto_menu(node) + + if node.list: + # We have a node with finalized children. Do final steps to finalize + # this node. + _flatten(node.list) + _remove_ifs(node) + + # Empty choices (node.list None) are possible, so this needs to go outside + if isinstance(node.item, Choice): + _finalize_choice(node) + # # Public global constants # @@ -3591,6 +3997,47 @@ def _internal_error(msg): UNKNOWN ) = range(6) +# Integers representing expression types +( + AND, + OR, + NOT, + EQUAL, + UNEQUAL, + LESS, + LESS_EQUAL, + GREATER, + GREATER_EQUAL, +) = range(9) + +# Integers representing menu and comment menu nodes +( + MENU, + COMMENT, +) = range(2) + +# Converts a symbol/choice type to a string +TYPE_TO_STR = { + UNKNOWN: "unknown", + BOOL: "bool", + TRISTATE: "tristate", + STRING: "string", + HEX: "hex", + INT: "int", +} + +TRI_TO_STR = { + 0: "n", + 1: "m", + 2: "y", +} + +STR_TO_TRI = { + "n": 0, + "m": 1, + "y": 2, +} + # # Internal global constants # @@ -3625,6 +4072,7 @@ def _internal_error(msg): _T_LESS_EQUAL, _T_MAINMENU, _T_MENU, + _T_MENUCONFIG, _T_MODULES, _T_NOT, _T_ON, @@ -3640,10 +4088,10 @@ def _internal_error(msg): _T_TRISTATE, _T_UNEQUAL, _T_VISIBLE, -) = range(43) +) = range(44) -# Keyword to token map. Note that the get() method is assigned directly as a -# small optimization. +# Keyword to token map, with the get() method assigned directly as a small +# optimization _get_keyword = { "allnoconfig_y": _T_ALLNOCONFIG_Y, "bool": _T_BOOL, @@ -3667,13 +4115,7 @@ _get_keyword = { "int": _T_INT, "mainmenu": _T_MAINMENU, "menu": _T_MENU, - - # 'menuconfig' only deals with presentation in the configuration interface - # and doesn't affect evaluation semantics, so treat it the same as - # 'config'. Perhaps some presentation-related support could be added as - # well. - "menuconfig": _T_CONFIG, - + "menuconfig": _T_MENUCONFIG, "modules": _T_MODULES, "on": _T_ON, "option": _T_OPTION, @@ -3687,12 +4129,10 @@ _get_keyword = { "visible": _T_VISIBLE, }.get -# Tokens after which identifier-like lexemes are treated as strings, plus -# _T_CONFIG. This allows us to quickly check if we have a symbol reference (as -# opposed to a definition or something else) when tokenizing. -_NOT_REF = frozenset(( +# Tokens after which identifier-like lexemes are treated as strings. _T_CHOICE +# is included to avoid symbols being registered for named choices. +_STRING_LEX = frozenset(( _T_BOOL, - _T_CONFIG, _T_CHOICE, _T_COMMENT, _T_HEX, @@ -3730,15 +4170,9 @@ _id_keyword_re_match = re.compile(r"([\w./-]+)\s*").match # Regular expression for finding $-references to symbols in strings _sym_ref_re_search = re.compile(r"\$([A-Za-z0-9_]+)").search -# Strings to use for types -_TYPENAME = { - UNKNOWN: "unknown", - BOOL: "bool", - TRISTATE: "tristate", - STRING: "string", - HEX: "hex", - INT: "int", -} +# Matches a valid right-hand side for an assignment to a string symbol in a +# .config file, including escaped characters. Extracts the contents. +_conf_string_re_match = re.compile(r'"((?:[^\\"]|\\.)*)"').match # Token to type mapping _TOKEN_TO_TYPE = { @@ -3751,35 +4185,14 @@ _TOKEN_TO_TYPE = { _T_TRISTATE: TRISTATE, } -# Default values for symbols of different types (the value the symbol gets if -# it is not assigned a user value and none of its 'default' clauses kick in) -_DEFAULT_VALUE = { - BOOL: "n", - TRISTATE: "n", - HEX: "", - INT: "", - STRING: "", -} - -# Indicates that no item is selected in a choice statement -_NO_SELECTION = 0 - -# Integers representing expression types -( - _AND, - _OR, - _NOT, - _EQUAL, - _UNEQUAL, - _LESS, - _LESS_EQUAL, - _GREATER, - _GREATER_EQUAL, -) = range(9) +# Constant representing that there's no cached choice selection. This is +# distinct from a cached None (no selection). We create a unique object (any +# will do) for it so we can test with 'is'. +_NO_CACHED_SELECTION = object() # Used in comparisons. 0 means the base is inferred from the format of the -# string. The entries for BOOL and TRISTATE are a convenience - they should -# never convert to valid numbers. +# string. The entries for BOOL and TRISTATE are an implementation convenience: +# They should never convert to valid numbers. _TYPE_TO_BASE = { BOOL: 0, HEX: 16, @@ -3789,37 +4202,30 @@ _TYPE_TO_BASE = { UNKNOWN: 0, } -# Map from tristate values to integers -_TRI_TO_INT = { - "n": 0, - "m": 1, - "y": 2, -} - _RELATIONS = frozenset(( - _EQUAL, - _UNEQUAL, - _LESS, - _LESS_EQUAL, - _GREATER, - _GREATER_EQUAL, + EQUAL, + UNEQUAL, + LESS, + LESS_EQUAL, + GREATER, + GREATER_EQUAL, )) # Token to relation (=, !=, <, ...) mapping -_TOKEN_TO_RELATION = { - _T_EQUAL: _EQUAL, - _T_GREATER: _GREATER, - _T_GREATER_EQUAL: _GREATER_EQUAL, - _T_LESS: _LESS, - _T_LESS_EQUAL: _LESS_EQUAL, - _T_UNEQUAL: _UNEQUAL, +_TOKEN_TO_REL = { + _T_EQUAL: EQUAL, + _T_GREATER: GREATER, + _T_GREATER_EQUAL: GREATER_EQUAL, + _T_LESS: LESS, + _T_LESS_EQUAL: LESS_EQUAL, + _T_UNEQUAL: UNEQUAL, } -_RELATION_TO_STR = { - _EQUAL: "=", - _GREATER: ">", - _GREATER_EQUAL: ">=", - _LESS: "<", - _LESS_EQUAL: "<=", - _UNEQUAL: "!=", +_REL_TO_STR = { + EQUAL: "=", + GREATER: ">", + GREATER_EQUAL: ">=", + LESS: "<", + LESS_EQUAL: "<=", + UNEQUAL: "!=", } |