LCOV - code coverage report
Current view: top level - py - builtinhelp.c (source / functions) Hit Total Coverage
Test: unix_coverage_v1.19.1-724-gfb7d21153.info Lines: 67 67 100.0 %
Date: 2022-12-01 09:37:31 Functions: 6 6 100.0 %
Branches: 27 30 90.0 %

           Branch data     Line data    Source code
       1                 :            : /*
       2                 :            :  * This file is part of the MicroPython project, http://micropython.org/
       3                 :            :  *
       4                 :            :  * The MIT License (MIT)
       5                 :            :  *
       6                 :            :  * Copyright (c) 2013-2016 Damien P. George
       7                 :            :  *
       8                 :            :  * Permission is hereby granted, free of charge, to any person obtaining a copy
       9                 :            :  * of this software and associated documentation files (the "Software"), to deal
      10                 :            :  * in the Software without restriction, including without limitation the rights
      11                 :            :  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
      12                 :            :  * copies of the Software, and to permit persons to whom the Software is
      13                 :            :  * furnished to do so, subject to the following conditions:
      14                 :            :  *
      15                 :            :  * The above copyright notice and this permission notice shall be included in
      16                 :            :  * all copies or substantial portions of the Software.
      17                 :            :  *
      18                 :            :  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
      19                 :            :  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
      20                 :            :  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
      21                 :            :  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
      22                 :            :  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
      23                 :            :  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
      24                 :            :  * THE SOFTWARE.
      25                 :            :  */
      26                 :            : 
      27                 :            : #include <stdio.h>
      28                 :            : #include <string.h>
      29                 :            : 
      30                 :            : #include "py/builtin.h"
      31                 :            : #include "py/objmodule.h"
      32                 :            : 
      33                 :            : #if MICROPY_PY_BUILTINS_HELP
      34                 :            : 
      35                 :            : const char mp_help_default_text[] =
      36                 :            :     "Welcome to MicroPython!\n"
      37                 :            :     "\n"
      38                 :            :     "For online docs please visit http://docs.micropython.org/\n"
      39                 :            :     "\n"
      40                 :            :     "Control commands:\n"
      41                 :            :     "  CTRL-A        -- on a blank line, enter raw REPL mode\n"
      42                 :            :     "  CTRL-B        -- on a blank line, enter normal REPL mode\n"
      43                 :            :     "  CTRL-C        -- interrupt a running program\n"
      44                 :            :     "  CTRL-D        -- on a blank line, exit or do a soft reset\n"
      45                 :            :     "  CTRL-E        -- on a blank line, enter paste mode\n"
      46                 :            :     "\n"
      47                 :            :     "For further help on a specific object, type help(obj)\n"
      48                 :            : ;
      49                 :            : 
      50                 :         72 : STATIC void mp_help_print_info_about_object(mp_obj_t name_o, mp_obj_t value) {
      51                 :         72 :     mp_print_str(MP_PYTHON_PRINTER, "  ");
      52                 :         72 :     mp_obj_print(name_o, PRINT_STR);
      53                 :         72 :     mp_print_str(MP_PYTHON_PRINTER, " -- ");
      54                 :         72 :     mp_obj_print(value, PRINT_STR);
      55                 :         72 :     mp_print_str(MP_PYTHON_PRINTER, "\n");
      56                 :         72 : }
      57                 :            : 
      58                 :            : #if MICROPY_PY_BUILTINS_HELP_MODULES
      59                 :          4 : STATIC void mp_help_add_from_map(mp_obj_t list, const mp_map_t *map) {
      60         [ +  + ]:        152 :     for (size_t i = 0; i < map->alloc; i++) {
      61         [ +  - ]:        148 :         if (mp_map_slot_is_filled(map, i)) {
      62                 :        148 :             mp_obj_list_append(list, map->table[i].key);
      63                 :            :         }
      64                 :            :     }
      65                 :          4 : }
      66                 :            : 
      67                 :            : #if MICROPY_MODULE_FROZEN
      68                 :          4 : STATIC void mp_help_add_from_names(mp_obj_t list, const char *name) {
      69         [ +  + ]:         44 :     while (*name) {
      70                 :         40 :         size_t len = strlen(name);
      71                 :            :         // name should end in '.py' and we strip it off
      72                 :         40 :         mp_obj_list_append(list, mp_obj_new_str(name, len - 3));
      73                 :         40 :         name += len + 1;
      74                 :            :     }
      75                 :          4 : }
      76                 :            : #endif
      77                 :            : 
      78                 :          4 : STATIC void mp_help_print_modules(void) {
      79                 :          4 :     mp_obj_t list = mp_obj_new_list(0, NULL);
      80                 :            : 
      81                 :          4 :     mp_help_add_from_map(list, &mp_builtin_module_map);
      82                 :            : 
      83                 :            :     #if MICROPY_MODULE_FROZEN
      84                 :          4 :     extern const char mp_frozen_names[];
      85                 :          4 :     mp_help_add_from_names(list, mp_frozen_names);
      86                 :            :     #endif
      87                 :            : 
      88                 :            :     // sort the list so it's printed in alphabetical order
      89                 :          4 :     mp_obj_list_sort(1, &list, (mp_map_t *)&mp_const_empty_map);
      90                 :            : 
      91                 :            :     // print the list of modules in a column-first order
      92                 :            :     #define NUM_COLUMNS (4)
      93                 :            :     #define COLUMN_WIDTH (18)
      94                 :          4 :     size_t len;
      95                 :          4 :     mp_obj_t *items;
      96                 :          4 :     mp_obj_list_get(list, &len, &items);
      97                 :          4 :     unsigned int num_rows = (len + NUM_COLUMNS - 1) / NUM_COLUMNS;
      98         [ +  + ]:         52 :     for (unsigned int i = 0; i < num_rows; ++i) {
      99                 :            :         unsigned int j = i;
     100                 :        188 :         for (;;) {
     101                 :        188 :             int l = mp_print_str(MP_PYTHON_PRINTER, mp_obj_str_get_str(items[j]));
     102                 :        188 :             j += num_rows;
     103         [ +  + ]:        188 :             if (j >= len) {
     104                 :            :                 break;
     105                 :            :             }
     106                 :        140 :             int gap = COLUMN_WIDTH - l;
     107         [ +  + ]:        148 :             while (gap < 1) {
     108                 :          8 :                 gap += COLUMN_WIDTH;
     109                 :            :             }
     110         [ +  + ]:       1644 :             while (gap--) {
     111                 :       1504 :                 mp_print_str(MP_PYTHON_PRINTER, " ");
     112                 :            :             }
     113                 :            :         }
     114                 :         48 :         mp_print_str(MP_PYTHON_PRINTER, "\n");
     115                 :            :     }
     116                 :            : 
     117                 :            :     #if MICROPY_ENABLE_EXTERNAL_IMPORT
     118                 :            :     // let the user know there may be other modules available from the filesystem
     119                 :          4 :     mp_print_str(MP_PYTHON_PRINTER, "Plus any modules on the filesystem\n");
     120                 :            :     #endif
     121                 :          4 : }
     122                 :            : #endif
     123                 :            : 
     124                 :         20 : STATIC void mp_help_print_obj(const mp_obj_t obj) {
     125                 :            :     #if MICROPY_PY_BUILTINS_HELP_MODULES
     126         [ +  + ]:         20 :     if (obj == MP_OBJ_NEW_QSTR(MP_QSTR_modules)) {
     127                 :          4 :         mp_help_print_modules();
     128                 :          4 :         return;
     129                 :            :     }
     130                 :            :     #endif
     131                 :            : 
     132                 :         16 :     const mp_obj_type_t *type = mp_obj_get_type(obj);
     133                 :            : 
     134                 :            :     // try to print something sensible about the given object
     135                 :         16 :     mp_print_str(MP_PYTHON_PRINTER, "object ");
     136                 :         16 :     mp_obj_print(obj, PRINT_STR);
     137                 :         16 :     mp_printf(MP_PYTHON_PRINTER, " is of type %q\n", type->name);
     138                 :            : 
     139                 :         16 :     mp_map_t *map = NULL;
     140         [ +  + ]:         16 :     if (type == &mp_type_module) {
     141                 :          4 :         map = &mp_obj_module_get_globals(obj)->map;
     142                 :            :     } else {
     143         [ +  + ]:         12 :         if (type == &mp_type_type) {
     144                 :          4 :             type = MP_OBJ_TO_PTR(obj);
     145                 :            :         }
     146         [ +  + ]:         12 :         if (MP_OBJ_TYPE_HAS_SLOT(type, locals_dict)) {
     147                 :          8 :             map = &MP_OBJ_TYPE_GET_SLOT(type, locals_dict)->map;
     148                 :            :         }
     149                 :            :     }
     150         [ +  - ]:         12 :     if (map != NULL) {
     151         [ +  + ]:         84 :         for (uint i = 0; i < map->alloc; i++) {
     152                 :         72 :             mp_obj_t key = map->table[i].key;
     153                 :         72 :             if (key != MP_OBJ_NULL
     154                 :            :                 #if MICROPY_MODULE_ATTR_DELEGATION
     155                 :            :                 // MP_MODULE_ATTR_DELEGATION_ENTRY entries have MP_QSTRnull as qstr key.
     156         [ +  - ]:         72 :                 && key != MP_OBJ_NEW_QSTR(MP_QSTRnull)
     157                 :            :                 #endif
     158                 :            :                 ) {
     159                 :         72 :                 mp_help_print_info_about_object(key, map->table[i].value);
     160                 :            :             }
     161                 :            :         }
     162                 :            :     }
     163                 :            : }
     164                 :            : 
     165                 :         24 : STATIC mp_obj_t mp_builtin_help(size_t n_args, const mp_obj_t *args) {
     166         [ +  + ]:         24 :     if (n_args == 0) {
     167                 :            :         // print a general help message
     168                 :          4 :         mp_print_str(MP_PYTHON_PRINTER, MICROPY_PY_BUILTINS_HELP_TEXT);
     169                 :            :     } else {
     170                 :            :         // try to print something sensible about the given object
     171                 :         20 :         mp_help_print_obj(args[0]);
     172                 :            :     }
     173                 :            : 
     174                 :         24 :     return mp_const_none;
     175                 :            : }
     176                 :            : MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mp_builtin_help_obj, 0, 1, mp_builtin_help);
     177                 :            : 
     178                 :            : #endif // MICROPY_PY_BUILTINS_HELP

Generated by: LCOV version 1.15-5-g462f71d