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
35const 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
50STATIC void mp_help_print_info_about_object(mp_obj_t name_o, mp_obj_t value) {
51 mp_print_str(MP_PYTHON_PRINTER, " ");
52 mp_obj_print(name_o, PRINT_STR);
53 mp_print_str(MP_PYTHON_PRINTER, " -- ");
54 mp_obj_print(value, PRINT_STR);
55 mp_print_str(MP_PYTHON_PRINTER, "\n");
56}
57
58#if MICROPY_PY_BUILTINS_HELP_MODULES
59STATIC void mp_help_add_from_map(mp_obj_t list, const mp_map_t *map) {
60 for (size_t i = 0; i < map->alloc; i++) {
61 if (mp_map_slot_is_filled(map, i)) {
62 mp_obj_list_append(list, map->table[i].key);
63 }
64 }
65}
66
67#if MICROPY_MODULE_FROZEN
68STATIC void mp_help_add_from_names(mp_obj_t list, const char *name) {
69 while (*name) {
70 size_t l = strlen(name);
71 // name should end in '.py' and we strip it off
72 mp_obj_list_append(list, mp_obj_new_str(name, l - 3));
73 name += l + 1;
74 }
75}
76#endif
77
78STATIC void mp_help_print_modules(void) {
79 mp_obj_t list = mp_obj_new_list(0, NULL);
80
81 mp_help_add_from_map(list, &mp_builtin_module_map);
82
83 #if MICROPY_MODULE_FROZEN_STR
84 extern const char mp_frozen_str_names[];
85 mp_help_add_from_names(list, mp_frozen_str_names);
86 #endif
87
88 #if MICROPY_MODULE_FROZEN_MPY
89 extern const char mp_frozen_mpy_names[];
90 mp_help_add_from_names(list, mp_frozen_mpy_names);
91 #endif
92
93 // sort the list so it's printed in alphabetical order
94 mp_obj_list_sort(1, &list, (mp_map_t *)&mp_const_empty_map);
95
96 // print the list of modules in a column-first order
97 #define NUM_COLUMNS (4)
98 #define COLUMN_WIDTH (18)
99 size_t len;
100 mp_obj_t *items;
101 mp_obj_list_get(list, &len, &items);
102 unsigned int num_rows = (len + NUM_COLUMNS - 1) / NUM_COLUMNS;
103 for (unsigned int i = 0; i < num_rows; ++i) {
104 unsigned int j = i;
105 for (;;) {
106 int l = mp_print_str(MP_PYTHON_PRINTER, mp_obj_str_get_str(items[j]));
107 j += num_rows;
108 if (j >= len) {
109 break;
110 }
111 int gap = COLUMN_WIDTH - l;
112 while (gap < 1) {
113 gap += COLUMN_WIDTH;
114 }
115 while (gap--) {
116 mp_print_str(MP_PYTHON_PRINTER, " ");
117 }
118 }
119 mp_print_str(MP_PYTHON_PRINTER, "\n");
120 }
121
122 #if MICROPY_ENABLE_EXTERNAL_IMPORT
123 // let the user know there may be other modules available from the filesystem
124 mp_print_str(MP_PYTHON_PRINTER, "Plus any modules on the filesystem\n");
125 #endif
126}
127#endif
128
129STATIC void mp_help_print_obj(const mp_obj_t obj) {
130 #if MICROPY_PY_BUILTINS_HELP_MODULES
131 if (obj == MP_OBJ_NEW_QSTR(MP_QSTR_modules)) {
132 mp_help_print_modules();
133 return;
134 }
135 #endif
136
137 const mp_obj_type_t *type = mp_obj_get_type(obj);
138
139 // try to print something sensible about the given object
140 mp_print_str(MP_PYTHON_PRINTER, "object ");
141 mp_obj_print(obj, PRINT_STR);
142 mp_printf(MP_PYTHON_PRINTER, " is of type %q\n", type->name);
143
144 mp_map_t *map = NULL;
145 if (type == &mp_type_module) {
146 map = &mp_obj_module_get_globals(obj)->map;
147 } else {
148 if (type == &mp_type_type) {
149 type = MP_OBJ_TO_PTR(obj);
150 }
151 if (type->locals_dict != NULL) {
152 map = &type->locals_dict->map;
153 }
154 }
155 if (map != NULL) {
156 for (uint i = 0; i < map->alloc; i++) {
157 if (map->table[i].key != MP_OBJ_NULL) {
158 mp_help_print_info_about_object(map->table[i].key, map->table[i].value);
159 }
160 }
161 }
162}
163
164STATIC mp_obj_t mp_builtin_help(size_t n_args, const mp_obj_t *args) {
165 if (n_args == 0) {
166 // print a general help message
167 mp_print_str(MP_PYTHON_PRINTER, MICROPY_PY_BUILTINS_HELP_TEXT);
168 } else {
169 // try to print something sensible about the given object
170 mp_help_print_obj(args[0]);
171 }
172
173 return mp_const_none;
174}
175MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mp_builtin_help_obj, 0, 1, mp_builtin_help);
176
177#endif // MICROPY_PY_BUILTINS_HELP
178