V语言11写文档

我就是我 2022-10-10 12:58 95阅读 0赞

类似`go`.从`文档串`中自动生成.`函数/类型/常数`的文档必须放在其上1行.

//清理所有
    fn clearall() { 
    }

注释,必须以`自己名字`开头.多行用多个`单行注释`.注释最好是`现在时`.  
模块简介,应是`模块名`后的第1个注释.`v doc net.http`来生成文档.

# 工具 #

`v fmt 文件.v`格式化`文件`.一次运行,非常便宜,`v fmt -w(每次保存时运行)`约30毫秒.  
拉代码时,`v fmt -w file.v`.  
用`v -profile profile.txt run file.v`来检查性能.产生`性能文件`供你分析.有四列:`调用次数|总时间|平均时间|函数名`.  
`sort -n -k3 profile.txt|tail`这样来按`第3列`排序.  
用秒表显式测试:

import time
    
    fn main() { 
    	sw := time.new_stopwatch({ })
    	println("你好")
    	println("花费: ${sw.elapsed().nanoseconds()}ns")
    }

# 高级主题 #

# 运行时转存表达式 #

用`dump(expr)`转存`表达式`.

fn factorial(n u32) u32 { 
    	if dump(n <= 1) { 
    		return dump(1)
    	}
    	return dump(n * factorial(n - 1))//转存
    }
    
    fn main() { 
    	println(factorial(5))
    }

这样:`v run factorial.v`.`转存`会跟踪`源位置,表达式,表达式的值`.

# 内存不安全代码 #

写低级但高效代码,`V`要求标记出`不安全`的代码.

<table> 
 <thead> 
  <tr> 
   <th align="left"><code>序号</code></th> 
   <th align="left">可能不安全动作</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>1</code></td> 
   <td align="left">指针运算</td> 
  </tr> 
  <tr> 
   <td align="left"><code>2</code></td> 
   <td align="left">指针索引</td> 
  </tr> 
  <tr> 
   <td align="left"><code>3</code></td> 
   <td align="left">从不匹配类型转换为指针</td> 
  </tr> 
  <tr> 
   <td align="left"><code>4</code></td> 
   <td align="left">调用某些<code>free,strlen和strncmp</code>等C函数</td> 
  </tr> 
 </tbody> 
</table>

用`unsafe`来包装它.

//分配未初化2字节并返回到它的引用
    mut p := unsafe {  malloc(2) }
    p[0] = `h` //指针索引,仅在`不安全`块允许
    unsafe { 
        p[0] = `h` // OK
        p[1] = `i`
    }
    p++ //指针算术,仅在`不安全`块允许
    unsafe { 
        p++ // OK
    }
    assert *p == `i`

内存安全的`表达式`不要放在`不安全`块中,这样用`不安全`的原因,就很清晰.不安全块代码中`不应有`安全代码.  
你怀疑程序违反内存安全,可以检查`不安全`块行为.  
`正在进行`中.

# 带引用字段构 #

带引用字段要求显式给`引用字段`赋初值,除非`构`已定义初值.  
未来不支持`零值引用/空针`.现在在注意`置0`是不安全的,会导致`恐慌`.

struct Node { 
    	a &Node
    	b &Node = 0 //自动初化为0,使用时小心
    }
    
    //必须初化引用字段,除非如b一样,已声明
    // Zero (0)没问题,但要小心,是空针.
    foo := Node{ 
    	a: 0
    }
    bar := Node{ 
    	a: &foo
    }
    baz := Node{ 
    	a: 0
    	b: 0
    }
    qux := Node{ 
    	a: &foo
    	b: &bar
    }
    println(baz)
    println(qux)

`sizeof和__offsetof`.前者`sizeof(Type)`按`字节`给定大小,  
后者`__offsetof(Struct, field_name)`像这样给定字段偏移.

struct Foo { 
    	a int
    	b int
    }
    
    assert sizeof(Foo) == 8
    assert __offsetof(Foo, a) == 0
    assert __offsetof(Foo, b) == 4

从`V`调用`C`:

#flag -lsqlite3
    #include "sqlite3.h"
    ...C系接口...
    //https://www.sqlite.org/quickstart.html,示例
    fn my_callback(arg voidptr, howmany int, cvalues &&char, cnames &&char) int { 
    	unsafe { 
    		for i in 0 .. howmany { 
    			print("| ${cstring_to_vstring(cnames[i])}: ${cstring_to_vstring(cvalues[i]):20} ")
    		}
    	}
    	println("|")
    	return 0
    }
    
    fn main() { 
    	db := &C.sqlite3(0) 
    	C.sqlite3_open(c"users.db", &db)
    	query := "select count(*) from users"
    	stmt := &C.sqlite3_stmt(0)
    	C.sqlite3_prepare_v2(db, &char(query.str), -1, &stmt, 0)
    	C.sqlite3_step(stmt)
    	nr_users := C.sqlite3_column_int(stmt, 0)
    	C.sqlite3_finalize(stmt)
    	println("数据库中有$nr_users用户.")
    	//
    	error_msg := &char(0)
    	query_all_users := "select * from users"
    	rc := C.sqlite3_exec(db, &char(query_all_users.str), my_callback, voidptr(7), &error_msg)
    	if rc != C.SQLITE_OK { 
    		eprintln(unsafe {  cstring_to_vstring(error_msg) })
    		C.sqlite3_free(error_msg)
    	}
    	C.sqlite3_close(db)
    }

`flag`,传递`C`编译标志.在`V`文件开头.

<table> 
 <thead> 
  <tr> 
   <th align="left"><code>标志</code></th> 
   <th align="left">意思</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>-I</code></td> 
   <td align="left">包含路径</td> 
  </tr> 
  <tr> 
   <td align="left"><code>-l</code></td> 
   <td align="left">库名</td> 
  </tr> 
  <tr> 
   <td align="left"><code>-L</code></td> 
   <td align="left">C库搜索路径</td> 
  </tr> 
  <tr> 
   <td align="left"><code>-D</code></td> 
   <td align="left">编译时变量</td> 
  </tr> 
 </tbody> 
</table>

不同目标用不同标志:可用有:`linux,darwin,freebsd,及windows`  
每个标志,必须单独一行:

#flag linux -lsdl2
    #flag linux -Ivig
    #flag linux -DCIMGUI_DEFINE_ENUMS_AND_STRUCTS=1
    #flag linux -DIMGUI_DISABLE_OBSOLETE_FUNCTIONS=1
    #flag linux -DIMGUI_IMPL_API=

控制台中,你可用`-cflags`来传递自定义标志,用`-cc`来改`编译器`,如`-cc gcc-9 -cflags -fsanitize=thread`.  
可在`终端`中定义`VFLAGS`来存储`-cc`与`-cflags`标志,避免重复定义他们.

# 属性 #

在`函数/构/枚`声明前,作用于该`声明`.

//调用时,过时警告
    [deprecated]
    fn old_function() { 
    }
    
    //自定义消息
    [deprecated: "用新 new_function() 替代"]
    fn legacy_function() { }
    
    //会内联该函数 
    [inline]
    fn inlined_function() { 
    }
    
    //构在堆中分配只能用作引用
    [heap]
    struct Window { 
    }
    
    //如果标志为假,则不编译
    // 用`v -d flag`
    [if debug]
    fn foo() { 
    }
    
    fn bar() { 
    	foo() //未传递`-d debug`,则不调用
    }
    
    //函数返回前,垃集不释放内存 
    [keep_args_alive]
    fn C.my_external_function(voidptr, int, voidptr) int
    
    //必须在不安全块,
    [unsafe]
    fn risky_business() { 
    	//检查代码及前条件
    	unsafe { 
    		// 不检查,指针算术,访问联,调用`不安全`
    		// 最好最小化不安全块代码
    	}
    	//仍检查这里
    }
    
    //本函数,手动释放,程序员负责
    [manualfree]
    fn custom_allocations() { 
    }
    
    //C互操作,C方式
    [typedef]
    struct C.Foo { 
    }
    
    // 传递Win32 API回调
    [windows_stdcall]
    fn C.DefWindowProc(hwnd int, msg int, lparam int, wparam int)
    
    //导入gg,ui图形库时,图窗占优势,不创建控制台
    //有效禁止`打印行`语句,显式创建控制台,仅在`主`前有效.
    [console]
    fn main() { 
    }

允许`goto`跳至标签.要求`不安全`,要尽量少用.

# 交叉编译 #

`v -os windows ./v -os linux .`目前不支持`macOS`.

# 热加载 #

module main
    
    import time
    import os
    
    [live]
    fn print_message() { 
    	println("运行本程序时修改")
    }
    
    fn main() { 
    	for { 
    		print_message()
    		time.sleep(500 * time.millisecond)
    	}
    }

`v -live message.v`.目前,运行程序时不能修改`类型`.

# 转换C到V #

#include "stdio.h"
    
    int main() { 
    	for (int i = 0; i < 10; i++) { 
    		printf("你好,世界\n");
    	}
            return 0;
    }//转成下面
    fn main() { 
    	for i := 0; i < 10; i++ { 
    		println("你好,世界")
    	}
    }

`C库中`生成`包装器`:`v wrapper c_code/libsodium/src/libsodium`.优秀`C`代码,可转译至`V`.

<table> 
 <thead> 
  <tr> 
   <th align="left"><code>序号</code></th> 
   <th align="left">好处</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>1</code></td> 
   <td align="left">用1种语言开发代码,更安全,更容易</td> 
  </tr> 
  <tr> 
   <td align="left"><code>2</code></td> 
   <td align="left">交叉编译更简单</td> 
  </tr> 
  <tr> 
   <td align="left"><code>3</code></td> 
   <td align="left">不需要各种标志</td> 
  </tr> 
 </tbody> 
</table>

# 内联汇编 #

a := 100
    b := 20
    mut c := 0
    asm amd64 { 
        mov eax, a
        add eax, b
        mov c, eax
        ; =r (c) as c // output
        ; r (a) as a // input
          r (b) as b
    }
    println("a: $a") // 100
    println("b: $b") // 20
    println("c: $c") // 120

有限操作符重载:

struct Vec { 
    	x int
    	y int
    }
    
    fn (a Vec) str() string { 
    	return "{$a.x, $a.y}"
    }
    
    fn (a Vec) + (b Vec) Vec { 
    	return Vec{ a.x + b.x, a.y + b.y}
    }
    
    fn (a Vec) - (b Vec) Vec { 
    	return Vec{ a.x - b.x, a.y - b.y}
    }
    
    fn main() { 
    	a := Vec{ 2, 3}
    	b := Vec{ 4, 5}
    	mut c := Vec{ 1, 2}
    	println(a + b) // "{6, 8}"
    	println(a - b) // "{-2, -2}"
    	c += a
    	println(c) // "{3, 5}"
    }

用来改进`可读性`,为了`安全性/维护性`,限制:

<table> 
 <thead> 
  <tr> 
   <th align="left"><code>序号</code></th> 
   <th align="left">限制</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>1</code></td> 
   <td align="left">仅能重载<code>+,-,*,/,%,&lt;,&gt;,==,!=,&lt;=,&gt;=</code></td> 
  </tr> 
  <tr> 
   <td align="left"><code>2</code></td> 
   <td align="left">编译器重载<code>==/!=</code>,但你可覆盖</td> 
  </tr> 
  <tr> 
   <td align="left"><code>3</code></td> 
   <td align="left">禁止<code>符号</code>函数中调用其他函数</td> 
  </tr> 
  <tr> 
   <td align="left"><code>4</code></td> 
   <td align="left">符号函数,不能修改参数</td> 
  </tr> 
  <tr> 
   <td align="left"><code>5</code></td> 
   <td align="left">用<code>&lt;/==</code>时,必须返回<code>极</code>.</td> 
  </tr> 
  <tr> 
   <td align="left"><code>6</code></td> 
   <td align="left">定义了<code>==和&lt;</code>后,自动生成<code>!=,&gt;,&lt;=及&gt;=</code></td> 
  </tr> 
  <tr> 
   <td align="left"><code>7</code></td> 
   <td align="left">两边参数类型必须相同</td> 
  </tr> 
  <tr> 
   <td align="left"><code>8</code></td> 
   <td align="left">定义操作符时,自动生成<code>*=,+=,/=</code>,且必须返回相同类型</td> 
  </tr> 
 </tbody> 
</table>

# 编译时反射 #

允许你对任何数据格式创建序化器.`V`有编译时`if/for`.

// TODO: 未完全实现
    
    struct User { 
        name string
        age  int
    }
    
    // T应仅传递构名
    fn decode<T>(data string) T { 
        mut result := T{ }
        // 编译时`for`循环
        // T.fields给出字段元数据类型数组
        $for field in T.fields { 
            $if field.typ is string { 
                // $(string_expr)产生标识符
                result.$(field.name) = get_string(data, field.name)
            } $else $if field.typ is int { 
                result.$(field.name) = get_int(data, field.name)
            }
        }
        return result
    }
    
    // `decode<User>` 生成:
    fn decode_User(data string) User { 
        mut result := User{ }
        result.name = get_string(data, "name")
        result.age = get_int(data, "age")
        return result
    }

# 优化 #

用`-prod`编译时,如果给定`提示`,还可`进一步`优化:

<table> 
 <thead> 
  <tr> 
   <th align="left"><code>属性</code></th> 
   <th align="left">意思</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>[inline]</code></td> 
   <td align="left">内联</td> 
  </tr> 
  <tr> 
   <td align="left"><code>[direct_array_access]</code></td> 
   <td align="left">转为C数组操作来直接访问,省略检查边界,但<code>不安全</code>.</td> 
  </tr> 
  <tr> 
   <td align="left"><code>if _likely_(bool expression) { </code></td> 
   <td align="left">该分支很可能真</td> 
  </tr> 
  <tr> 
   <td align="left"><code>if _unlikely_(bool expression) { </code></td> 
   <td align="left">很可能假</td> 
  </tr> 
 </tbody> 
</table>

编译时伪变量,编译时替换,`类似宏`.

<table> 
 <thead> 
  <tr> 
   <th align="left"><code>伪变量</code></th> 
   <th align="left">意思</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>@FN</code></td> 
   <td align="left">当前函数名</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@METHOD</code></td> 
   <td align="left">用<code>ReceiverType.MethodName</code>来替换,方法</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@MOD</code></td> 
   <td align="left">模块名</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@STRUCT</code></td> 
   <td align="left">构名</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@FILE</code></td> 
   <td align="left">源码文件路径</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@LINE</code></td> 
   <td align="left">行号,串表示</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@COLUMN</code></td> 
   <td align="left">列号</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@VEXE</code></td> 
   <td align="left">V编译器路径</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@VEXEROOT</code></td> 
   <td align="left">V编译器路径根,</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@VHASH</code></td> 
   <td align="left">V编译器的哈希</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@VMOD_FILE</code></td> 
   <td align="left">最近<code>v.mod</code>内容</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@VMODROOT</code></td> 
   <td align="left">最近<code>v.mod</code>根目录</td> 
  </tr> 
 </tbody> 
</table>

`调试/记录/跟踪`时有用:

eprintln("file: " + @FILE + " | line: " + @LINE + " | fn: " + @MOD + "." + @FN)
    //或嵌入版本号
    import v.vmod
    vm := vmod.decode( @VMOD_FILE ) or {  panic(err.msg) }
    eprintln("$vm.name $vm.version\n $vm.description")
    //后面为环境特殊变量