Mercurial Hosting > luan

comparison website/src/m.html.luan @ 1668:ef75d9ad5ce9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
manual work
author Franklin Schmidt <fschmidt@gmail.com>
date Mon, 09 May 2022 23:30:25 -0600
parents c55373c3a0ce
children fdeb1879fe02
comparison
equal deleted inserted replaced
1667:c55373c3a0ce 1668:ef75d9ad5ce9
2360 2360
2361 <p> 2361 <p>
2362 This variable is only a reference to the real table; 2362 This variable is only a reference to the real table;
2363 assignments to this variable do not change the 2363 assignments to this variable do not change the
2364 table used by <a href="#Package.load"><code>Package.load</code></a>. 2364 table used by <a href="#Package.load"><code>Package.load</code></a>.
2365 </p>
2366 <%
2367 end
2368 }
2369 }
2370 }
2371 string_lib = {
2372 title = "String Manipulation"
2373 content = function()
2374 %>
2375 <p>
2376 Include this library by:
2377 </p>
2378 <pre>
2379 local String = require "luan:String.luan"
2380 </pre>
2381
2382 <p>
2383 This library provides generic functions for string manipulation,
2384 such as finding and extracting substrings, and pattern matching.
2385 When indexing a string in Luan, the first character is at position&nbsp;1
2386 (not at&nbsp;0, as in Java).
2387 Indices are allowed to be negative and are interpreted as indexing backwards,
2388 from the end of the string.
2389 Thus, the last character is at position -1, and so on.
2390 </p>
2391 <%
2392 end
2393 subs = {
2394 ["String.char"] = {
2395 title = "<code>String.char (&middot;&middot;&middot;)</code>"
2396 content = function()
2397 %>
2398 <p>
2399 Receives zero or more integers.
2400 Returns a string with length equal to the number of arguments,
2401 in which each character has the internal numerical code equal
2402 to its corresponding argument.
2403 </p>
2404 <%
2405 end
2406 }
2407 ["String.encode"] = {
2408 title = "<code>String.encode (s)</code>"
2409 content = function()
2410 %>
2411 <p>
2412 Encodes argument <code>s</code> into a string that can be placed in quotes so as to return the original value of the string.
2413 </p>
2414 <%
2415 end
2416 }
2417 ["String.find"] = {
2418 title = "<code>String.find (s, pattern [, init [, plain]])</code>"
2419 content = function()
2420 %>
2421 <p>
2422 Looks for the first match of
2423 <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <code>s</code>.
2424 If it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
2425 where this occurrence starts and ends;
2426 otherwise, it returns <b>nil</b>.
2427 A third, optional numerical argument <code>init</code> specifies
2428 where to start the search;
2429 its default value is&nbsp;1 and can be negative.
2430 A value of <b>true</b> as a fourth, optional argument <code>plain</code>
2431 turns off the pattern matching facilities,
2432 so the function does a plain "find substring" operation,
2433 with no characters in <code>pattern</code> being considered magic.
2434 Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
2435 </p>
2436
2437 <p>
2438 If the pattern has captures,
2439 then in a successful match
2440 the captured values are also returned,
2441 after the two indices.
2442 </p>
2443 <%
2444 end
2445 }
2446 ["String.format"] = {
2447 title = "<code>String.format (formatstring, &middot;&middot;&middot;)</code>"
2448 content = function()
2449 %>
2450 <p>
2451 Returns a formatted version of its variable number of arguments
2452 following the description given in its first argument (which must be a string).
2453 The format string follows the same rules as the Java function <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#format(java.lang.String,%20java.lang.Object...)"><code>String.format</code></a> because Luan calls this internally.
2454 </p>
2455
2456 <p>
2457 Note that Java's <code>String.format</code> is too stupid to convert between ints and floats, so you must provide the right kind of number.
2458 </p>
2459 <%
2460 end
2461 }
2462 ["String.gmatch"] = {
2463 title = "<code>String.gmatch (s, pattern)</code>"
2464 content = function()
2465 %>
2466 <p>
2467 Returns an iterator function that,
2468 each time it is called,
2469 returns the next captures from <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>)
2470 over the string <code>s</code>.
2471 If <code>pattern</code> specifies no captures,
2472 then the whole match is produced in each call.
2473 </p>
2474
2475 <p>
2476 As an example, the following loop
2477 will iterate over all the words from string <code>s</code>,
2478 printing one per line:
2479 </p>
2480 <pre>
2481 local s = "hello world from Lua"
2482 for w in String.gmatch(s, [[\w+]]) do
2483 print(w)
2484 end
2485 </pre>
2486
2487 <p>
2488 The next example collects all pairs <code>key=value</code> from the
2489 given string into a table:
2490 </p>
2491 <pre>
2492 local t = {}
2493 local s = "from=world, to=Lua"
2494 for k, v in String.gmatch(s, [[(\w+)=(\w+)]]) do
2495 t[k] = v
2496 end
2497 </pre>
2498
2499 <p>
2500 For this function, a caret '<code>^</code>' at the start of a pattern does not
2501 work as an anchor, as this would prevent the iteration.
2502 </p>
2503 <%
2504 end
2505 }
2506 ["String.gsub"] = {
2507 title = "<code>String.gsub (s, pattern, repl [, n])</code>"
2508 content = function()
2509 %>
2510 <p>
2511 Returns a copy of <code>s</code>
2512 in which all (or the first <code>n</code>, if given)
2513 occurrences of the <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) have been
2514 replaced by a replacement string specified by <code>repl</code>,
2515 which can be a string, a table, or a function.
2516 <code>gsub</code> also returns, as its second value,
2517 the total number of matches that occurred.
2518 The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
2519 </p>
2520
2521 <p>
2522 If <code>repl</code> is a string, then its value is used for replacement.
2523 The character&nbsp;<code>\</code> works as an escape character.
2524 Any sequence in <code>repl</code> of the form <code>$<em>d</em></code>,
2525 with <em>d</em> between 1 and 9,
2526 stands for the value of the <em>d</em>-th captured substring.
2527 The sequence <code>$0</code> stands for the whole match.
2528 </p>
2529
2530 <p>
2531 If <code>repl</code> is a table, then the table is queried for every match,
2532 using the first capture as the key.
2533 </p>
2534
2535 <p>
2536 If <code>repl</code> is a function, then this function is called every time a
2537 match occurs, with all captured substrings passed as arguments,
2538 in order.
2539 </p>
2540
2541 <p>
2542 In any case,
2543 if the pattern specifies no captures,
2544 then it behaves as if the whole pattern was inside a capture.
2545 </p>
2546
2547 <p>
2548 If the value returned by the table query or by the function call
2549 is not <b>nil</b>,
2550 then it is used as the replacement string;
2551 otherwise, if it is <b>nil</b>,
2552 then there is no replacement
2553 (that is, the original match is kept in the string).
2554 </p>
2555
2556 <p>
2557 Here are some examples:
2558 </p>
2559 <pre>
2560 x = String.gsub("hello world", [[(\w+)]], "$1 $1")
2561 --&gt; x="hello hello world world"
2562
2563 x = String.gsub("hello world", [[\w+]], "$0 $0", 1)
2564 --&gt; x="hello hello world"
2565
2566 x = String.gsub("hello world from Luan", [[(\w+)\s*(\w+)]], "$2 $1")
2567 --&gt; x="world hello Luan from"
2568
2569 x = String.gsub("4+5 = $return 4+5$", [[\$(.*?)\$]], function (s)
2570 return load(s)()
2571 end)
2572 --&gt; x="4+5 = 9"
2573
2574 local t = {name="lua", version="5.3"}
2575 x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t)
2576 --&gt; x="lua-5.3.tar.gz"
2577 </pre>
2578 <%
2579 end
2580 }
2581 ["String.lower"] = {
2582 title = "<code>String.lower (s)</code>"
2583 content = function()
2584 %>
2585 <p>
2586 Receives a string and returns a copy of this string with all
2587 uppercase letters changed to lowercase.
2588 All other characters are left unchanged.
2589 </p>
2590 <%
2591 end
2592 }
2593 ["String.match"] = {
2594 title = "<code>String.match (s, pattern [, init])</code>"
2595 content = function()
2596 %>
2597 <p>
2598 Looks for the first <em>match</em> of
2599 <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <code>s</code>.
2600 If it finds one, then <code>match</code> returns
2601 the captures from the pattern;
2602 otherwise it returns <b>nil</b>.
2603 If <code>pattern</code> specifies no captures,
2604 then the whole match is returned.
2605 A third, optional numerical argument <code>init</code> specifies
2606 where to start the search;
2607 its default value is&nbsp;1 and can be negative.
2608 </p>
2609 <%
2610 end
2611 }
2612 ["String.matches"] = {
2613 title = "<code>String.matches (s, pattern)</code>"
2614 content = function()
2615 %>
2616 <p>
2617 Returns a boolean indicating whether the <code>pattern</code> can be found in string <code>s</code>.
2618 This function is equivalent to
2619 </p>
2620 <pre>
2621 return String.match(s,pattern) ~= nil
2622 </pre>
2623 <%
2624 end
2625 }
2626 ["String.regex_quote"] = {
2627 title = "<code>String.regex_quote (s)</code>"
2628 content = function()
2629 %>
2630 <p>
2631 Returns a string which matches the literal string <code>s</code> in a regular expression. This function is simply the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#quote(java.lang.String)"><code>Pattern.quote</code></a>.
2632 </p>
2633 <%
2634 end
2635 }
2636 ["String.rep"] = {
2637 title = "<code>String.rep (s, n [, sep])</code>"
2638 content = function()
2639 %>
2640 <p>
2641 Returns a string that is the concatenation of <code>n</code> copies of
2642 the string <code>s</code> separated by the string <code>sep</code>.
2643 The default value for <code>sep</code> is the empty string
2644 (that is, no separator).
2645 Returns the empty string if <code>n</code> is not positive.
2646 </p>
2647 <%
2648 end
2649 }
2650 ["String.reverse"] = {
2651 title = "<code>String.reverse (s)</code>"
2652 content = function()
2653 %>
2654 <p>
2655 Returns a string that is the string <code>s</code> reversed.
2656 </p>
2657 <%
2658 end
2659 }
2660 ["String.split"] = {
2661 title = "<code>String.split (s, pattern [, limit])</code>"
2662 content = function()
2663 %>
2664 <p>
2665 Splits <code>s</code> using regex <code>pattern</code> and returns the results. If <code>limit</code> is positive, then only returns at most that many results. If <code>limit</code> is zero, then remove trailing empty results.
2666 </p>
2667 <%
2668 end
2669 }
2670 ["String.sub"] = {
2671 title = "<code>String.sub (s, i [, j])</code>"
2672 content = function()
2673 %>
2674 <p>
2675 Returns the substring of <code>s</code> that
2676 starts at <code>i</code> and continues until <code>j</code>;
2677 <code>i</code> and <code>j</code> can be negative.
2678 If <code>j</code> is absent, then it is assumed to be equal to -1
2679 (which is the same as the string length).
2680 In particular,
2681 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
2682 with length <code>j</code>,
2683 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
2684 with length <code>i</code>.
2685 </p>
2686
2687 <p>
2688 If, after the translation of negative indices,
2689 <code>i</code> is less than 1,
2690 it is corrected to 1.
2691 If <code>j</code> is greater than the string length,
2692 it is corrected to that length.
2693 If, after these corrections,
2694 <code>i</code> is greater than <code>j</code>,
2695 the function returns the empty string.
2696 </p>
2697 <%
2698 end
2699 }
2700 ["String.to_binary"] = {
2701 title = "<code>String.to_binary (s)</code>"
2702 content = function()
2703 %>
2704 <p>
2705 Converts a string to a binary by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#getBytes()"><code>String.getBytes</code></a>.
2706 </p>
2707 <%
2708 end
2709 }
2710 ["String.to_number"] = {
2711 title = "<code>String.to_number (s [, base])</code>"
2712 content = function()
2713 %>
2714 <p>
2715 When called with no <code>base</code>,
2716 <code>to_number</code> tries to convert its argument to a number.
2717 If the argument is
2718 a string convertible to a number,
2719 then <code>to_number</code> returns this number;
2720 otherwise, it returns <b>nil</b>.
2721 The conversion of strings can result in integers or floats.
2722 </p>
2723
2724 <p>
2725 When called with <code>base</code>,
2726 then <code>s</code> must be a string to be interpreted as
2727 an integer numeral in that base.
2728 In bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
2729 represents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
2730 with '<code>Z</code>' representing 35.
2731 If the string <code>s</code> is not a valid numeral in the given base,
2732 the function returns <b>nil</b>.
2733 </p>
2734 <%
2735 end
2736 }
2737 ["String.trim"] = {
2738 title = "<code>String.trim (s)</code>"
2739 content = function()
2740 %>
2741 <p>
2742 Removes the leading and trailing whitespace by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#trim()"><code>String.trim</code></a>.
2743 </p>
2744 <%
2745 end
2746 }
2747 ["String.unicode"] = {
2748 title = "<code>String.unicode (s [, i [, j]])</code>"
2749 content = function()
2750 %>
2751 <p>
2752 Returns the internal numerical codes of the characters <code>s[i]</code>,
2753 <code>s[i+1]</code>, ..., <code>s[j]</code>.
2754 The default value for <code>i</code> is&nbsp;1;
2755 the default value for <code>j</code> is&nbsp;<code>i</code>.
2756 These indices are corrected
2757 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
2758 </p>
2759 <%
2760 end
2761 }
2762 ["String.upper"] = {
2763 title = "<code>String.upper (s)</code>"
2764 content = function()
2765 %>
2766 <p>
2767 Receives a string and returns a copy of this string with all
2768 lowercase letters changed to uppercase.
2769 All other characters are left unchanged.
2770 The definition of what a lowercase letter is depends on the current locale.
2771 </p>
2772 <%
2773 end
2774 }
2775 }
2776 }
2777 binary_lib = {
2778 title = "Binary Manipulation"
2779 content = function()
2780 %>
2781 <p>
2782 Include this library by:
2783 </p>
2784 <pre>
2785 local Binary = require "luan:Binary.luan"
2786 </pre>
2787 <%
2788 end
2789 subs = {
2790 ["Binary.binary"] = {
2791 title = "<code>Binary.binary (&middot;&middot;&middot;)</code>"
2792 content = function()
2793 %>
2794 <p>
2795 Receives zero or more bytes (as integers).
2796 Returns a binary with length equal to the number of arguments,
2797 in which each byte has the internal numerical code equal
2798 to its corresponding argument.
2799 </p>
2800 <%
2801 end
2802 }
2803 ["Binary.byte"] = {
2804 title = "<code>Binary.byte (b [, i [, j]])</code>"
2805 content = function()
2806 %>
2807 <p>
2808 Returns the internal numerical codes of the bytes <code>b[i]</code>,
2809 <code>b[i+1]</code>, ..., <code>b[j]</code>.
2810 The default value for <code>i</code> is&nbsp;1;
2811 the default value for <code>j</code> is&nbsp;<code>i</code>.
2812 These indices are corrected
2813 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
2814 </p>
2815 <%
2816 end
2817 }
2818 ["Binary.to_string"] = {
2819 title = "<code>Binary.to_string (b [,charset])</code>"
2820 content = function()
2821 %>
2822 <p>
2823 If <code>charset</code> is not nil then converts the binary <code>b</code> to a string using the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#String(byte[],%20java.lang.String)">String constructor</a>, else makes each byte a char.
2824 </p>
2825 <%
2826 end
2827 }
2828 }
2829 }
2830 table_lib = {
2831 title = "Table Manipulation"
2832 content = function()
2833 %>
2834 <p>
2835 Include this library by:
2836 </p>
2837 <pre>
2838 local Table = require "luan:Table.luan"
2839 </pre>
2840
2841 <p>
2842 This library provides generic functions for table manipulation.
2843 It provides all its functions inside the table <code>Table</code>.
2844 </p>
2845 <%
2846 end
2847 subs = {
2848 ["Table.clear"] = {
2849 title = "<code>Table.clear (tbl)</code>"
2850 content = function()
2851 %>
2852 <p>
2853 Clears the table.
2854 </p>
2855 <%
2856 end
2857 }
2858 ["Table.concat"] = {
2859 title = "<code>Table.concat (list [, sep [, i [, j]]])</code>"
2860 content = function()
2861 %>
2862 <p>
2863 Given a list,
2864 returns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>.
2865 The default value for <code>sep</code> is the empty string,
2866 the default for <code>i</code> is 1,
2867 and the default for <code>j</code> is <code>#list</code>.
2868 If <code>i</code> is greater than <code>j</code>, returns the empty string.
2869 </p>
2870 <%
2871 end
2872 }
2873 ["Table.copy"] = {
2874 title = "<code>Table.copy (tbl [, i [, j]])</code>"
2875 content = function()
2876 %>
2877 <p>
2878 If <code>i</code> is <code>nil</code>, returns a shallow copy of <code>tbl</code>.
2879 Otherwise returns a new table which is a list of the elements <code>tbl[i] &middot;&middot;&middot; tbl[j]</code>.
2880 By default, <code>j</code> is <code>#tbl</code>.
2881 </p>
2882 <%
2883 end
2884 }
2885 ["Table.insert"] = {
2886 title = "<code>Table.insert (list, pos, value)</code>"
2887 content = function()
2888 %>
2889 <p>
2890 Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
2891 shifting up the elements
2892 <code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code>.
2893 </p>
2894 <%
2895 end
2896 }
2897 ["Table.is_empty"] = {
2898 title = "<code>Table.is_empty (tbl)</code>"
2899 content = function()
2900 %>
2901 <%
2902 end
2903 }
2904 ["Table.pack"] = {
2905 title = "<code>Table.pack (&middot;&middot;&middot;)</code>"
2906 content = function()
2907 %>
2908 <p>
2909 Returns a new table with all parameters stored into keys 1, 2, etc.
2910 and with a field "<code>n</code>" with the total number of parameters.
2911 Note that the resulting table may not be a sequence.
2912 </p>
2913 <%
2914 end
2915 }
2916 ["Table.remove"] = {
2917 title = "<code>Table.remove (list, pos)</code>"
2918 content = function()
2919 %>
2920 <p>
2921 Removes from <code>list</code> the element at position <code>pos</code>,
2922 returning the value of the removed element.
2923 When <code>pos</code> is an integer between 1 and <code>#list</code>,
2924 it shifts down the elements
2925 <code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code>
2926 and erases element <code>list[#list]</code>;
2927 The index <code>pos</code> can also be 0 when <code>#list</code> is 0,
2928 or <code>#list + 1</code>;
2929 in those cases, the function erases the element <code>list[pos]</code>.
2930 </p>
2931 <%
2932 end
2933 }
2934 ["Table.size"] = {
2935 title = "<code>Table.size (tbl)</code>"
2936 content = function()
2937 %>
2938 <%
2939 end
2940 }
2941 ["Table.sort"] = {
2942 title = "<code>Table.sort (list [, comp])</code>"
2943 content = function()
2944 %>
2945 <p>
2946 Sorts list elements in a given order, <em>in-place</em>,
2947 from <code>list[1]</code> to <code>list[#list]</code>.
2948 If <code>comp</code> is given,
2949 then it must be a function that receives two list elements
2950 and returns true when the first element must come
2951 before the second in the final order
2952 (so that <code>not comp(list[i+1],list[i])</code> will be true after the sort).
2953 If <code>comp</code> is not given,
2954 then the standard Lua operator <code>&lt;</code> is used instead.
2955 </p>
2956
2957 <p>
2958 The sort algorithm is not stable;
2959 that is, elements considered equal by the given order
2960 may have their relative positions changed by the sort.
2961 </p>
2962 <%
2963 end
2964 }
2965 ["Table.unpack"] = {
2966 title = "<code>Table.unpack (list [, i [, j]])</code>"
2967 content = function()
2968 %>
2969 <p>
2970 Returns the elements from the given list.
2971 This function is equivalent to
2972 </p>
2973 <pre>
2974 return list[i], list[i+1], &middot;&middot;&middot;, list[j]
2975 </pre>
2976
2977 <p>
2978 By default, <code>i</code> is 1 and <code>j</code> is <code>list.n or #list</code>.
2979 </p>
2980 <%
2981 end
2982 }
2983 }
2984 }
2985 number_lib = {
2986 title = "Number Manipulation"
2987 content = function()
2988 %>
2989 <p>
2990 Include this library by:
2991 </p>
2992 <pre>
2993 local Number = require "luan:Number.luan"
2994 </pre>
2995 <%
2996 end
2997 subs = {
2998 ["Number.double"] = {
2999 title = "<code>Number.double (x)</code>"
3000 content = function()
3001 %>
3002 <p>
3003 Returns <code>x</code> as a double.
3004 </p>
3005 <%
3006 end
3007 }
3008 ["Number.float"] = {
3009 title = "<code>Number.float (x)</code>"
3010 content = function()
3011 %>
3012 <p>
3013 Returns <code>x</code> as a float.
3014 </p>
3015 <%
3016 end
3017 }
3018 ["Number.integer"] = {
3019 title = "<code>Number.integer (x)</code>"
3020 content = function()
3021 %>
3022 <p>
3023 If the value <code>x</code> is convertible to an integer,
3024 returns that integer.
3025 Otherwise throws an error.
3026 </p>
3027 <%
3028 end
3029 }
3030 ["Number.long"] = {
3031 title = "<code>Number.long (x)</code>"
3032 content = function()
3033 %>
3034 <p>
3035 If the value <code>x</code> is convertible to an long,
3036 returns that long.
3037 Otherwise throws an error.
3038 </p>
3039 <%
3040 end
3041 }
3042 ["Number.long_to_string"] = {
3043 title = "<code>Number.long_to_string (i, radix)</code>"
3044 content = function()
3045 %>
3046 <p>
3047 Converts long value <code>i</code> to a string by calling <code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Long.html#toString(long,%20int)">Long.toString</a></code>.
3048 </p>
3049 <%
3050 end
3051 }
3052 ["Number.type"] = {
3053 title = "<code>Number.type (x)</code>"
3054 content = function()
3055 %>
3056 <p>
3057 Returns a string for the numeric type of <code>x</code>. Possible return values include "<code>integer</code>", "<code>long</code>", "<code>double</code>", and "<code>float</code>".
2365 </p> 3058 </p>
2366 <% 3059 <%
2367 end 3060 end
2368 } 3061 }
2369 } 3062 }