'\"
.\" (C) Copyright 2001-2004 David A. Wheeler (dwheeler at dwheeler.com)
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
.\" 
.\" David A. Wheeler's website is http://www.dwheeler.com
.\"
.\" Created Mon Jan 08 23:00:00 2001, David A. Wheeler (dwheeler at dwheeler.com)
.\"
.TH SLOCCOUNT 1 "31 July 2004" "SLOCCount" "SLOCCount"
.SH "نام (NAME)"
sloccount \- شمارش خطوط فیزیکی کد مبدأ (SLOC)
.SH "خلاصه دستور (SYNOPSIS)"
.B sloccount
.RB [ --version ]
.RB [ --cached ]
.RB [ --append ]
[ \fB--datadir\fR \fIdirectory\fR ]
.RB [ --follow ]
.RB [ --duplicates ]
.RB [ --crossdups ]
.RB [ --autogen ]
.RB [ --multiproject ]
.RB [ --filecount ]
.RB [ --wide ]
.RB [ --details ]
[ \fB--effort\fR \fIF\fR \fIE\fR ]
[ \fB--schedule\fR \fIF\fR \fIE\fR ]
[ \fB--personcost\fR \fIcost\fR ]
[ \fB--overhead\fR \fIoverhead\fR ]
[ \fB--addlang\fR \fIlanguage\fR ]
[ \fB--addlangall\fR ]
.RB [ -- ]
.I directories
.SH "توضیحات (DESCRIPTION)"
.PP
دستور sloccount تعداد خطوط فیزیکی کد مبدأ (SLOC) موجود در زیرمجموعه‌های دایرکتوری‌های مشخص‌شده را شمارش می‌کند. این ابزار به‌طور خودکار تشخیص می‌دهد که کدام فایل‌ها فایل‌های کد مبدأ هستند و زبان رایانه‌ای به‌کاررفته در هر فایل را نیز به‌صورت خودکار تعیین می‌کند. به‌طور پیش‌فرض، نتایج SLOC را خلاصه کرده و برآوردهای گوناگونی (مانند میزان تلاش و هزینه برای توسعه) ارائه می‌دهد، اما خروجی آن را می‌توان با گزینه‌های مختلف کنترل کرد.
.PP
اگر به sloccount فهرستی از دو یا چند دایرکتوری بدهید، شمارش‌ها بر اساس آن فهرست تفکیک خواهند شد. یک محدودیت مهم وجود دارد: نام‌های پایهٔ (basenames) دایرکتوری‌های ارائه‌شده به‌عنوان پارامتر باید با یکدیگر متفاوت باشند، زیرا از آن نام‌ها برای گروه‌بندی اطلاعات خلاصه استفاده می‌شود. بنابراین، نمی‌توانید دستور \(lqsloccount /usr/src/hello /usr/local/src/hello\(rq را اجرا کنید. این محدودیت فقط بر پارامترهای sloccount اعمال می‌شود \- زیردایرکتوری‌های مشتق‌شده از دایرکتوری‌های بالادست می‌توانند نام پایهٔ یکسانی داشته باشند.
.PP
اگر به sloccount تنها یک دایرکتوری منفرد بدهید، تلاش می‌کند تا به‌طور خودکار تفکیکی منطقی برای مقاصد گزارش‌دهی بیابد (تا گزارشی سودمند تولید کند). در این حالت، اگر دایرکتوری دست‌کم دو زیردایرکتوری داشته باشد، از آن زیردایرکتوری‌ها برای تفکیک گزارش استفاده خواهد شد. اگر این تک دایرکتوری علاوه بر دایرکتوری‌ها شامل فایل‌ها نیز باشد (یا اگر چند فایل را به‌عنوان پارامتر به sloccount بدهید)، آن فایل‌ها به دایرکتوری \(lqtop_dir\(rq اختصاص داده می‌شوند تا بتوانید آن‌ها را از سایر محتویات تشخیص دهید. در نهایت، اگر زیردایرکتوری‌ای به نام \(lqsrc\(rq وجود داشته باشد، آن زیردایرکتوری مجدداً تفکیک می‌شود و پیشوند \(lqsrc_\(rq به تمام زیردایرکتوری‌های بعدی آن اضافه می‌شود. بنابراین، اگر دایرکتوری \(lqX\(rq دارای زیردایرکتوری \(lqsrc\(rq باشد که خود شامل زیردایرکتوری \(lqmodules\(rq است، ابزار sloccount یک شمارش جداگانه برای \(lqsrc_modules\(rq گزارش خواهد کرد.
.PP
ابزار sloccount معمولاً تمام زیرمجموعه‌ها و فرزندان این دایرکتوری‌ها را در نظر می‌گیرد، اگرچه مگر در صورت تعیین خلاف آن، پیوندهای نمادین (symbolic links) را نادیده می‌گیرد.
.PP
دستور sloccount پیشانهٔ (front-end) معمول مجموعه ابزارهایی به نام \(lqSLOCCount\(rq است. توجه داشته باشید که نام کل بسته با حروف بزرگ نوشته می‌شود، در حالی که نام این برنامهٔ پیشانه با حروف کوچک است.
.PP
ابزار sloccount معمولاً برآوردهایی از زمان‌بندی، میزان تلاش و هزینه گزارش می‌دهد، و برای پروژه‌های منفرد، میانگین تعداد توسعه‌دهندگان فعال را نیز تخمین می‌زند. این مقادیر صرفاً برآورد هستند و وحی مُنزل نیستند؛ می‌توانید پارامترهای استفاده‌شده را برای بهبود و دقت بیشتر برآوردها تغییر دهید.


.SH "گزینه‌ها (OPTIONS)"
.TP 12
.BI --version
شماره نسخهٔ SLOCCount را گزارش کرده و بلافاصله خارج می‌شود. این گزینه را نمی‌توان به‌طور مفید با هیچ گزینهٔ دیگری ترکیب کرد.

.TP 12
.BI --cached
محاسبهٔ مجدد انجام نده؛ در عوض، از نتایج کَش‌شده از اجرای قبلی استفاده کن. بدون گزینهٔ \fB--cached\fR یا \fB--append\fR، ابزار sloccount به‌طور خودکار دایرکتوری داده را حذف کرده و مجدداً آن را می‌سازد.

.TP 12
.BI --append
محاسبات قبلی را از دایرکتوری داده حذف نکن؛ در عوض، این تحلیل را به محتویات فعلی دایرکتوری داده اضافه کن.

.TP
.BI --datadir " directory"
داده‌های کَش‌شده را در دایرکتوری دادهٔ مشخص‌شده ذخیره کرده یا از آن استفاده کن؛ مقدار پیش‌فرض \(lq~/.slocdata\(rq است.

.TP
.BI --follow
پیوندهای نمادین را دنبال کن.

.TP
.BI --duplicates
تمام موارد تکراری را شمارش کن. به‌طور معمول، اگر فایل‌ها محتوای یکسانی داشته باشند (که با استفاده از مقادیر درهم‌سازی MD5 مشخص می‌شود)، تنها یکی از آن‌ها شمارش می‌شود.

.TP
.BI --crossdups
موارد تکراری را در صورتی که در بخش‌های متفاوتی از تفکیک رخ دهند شمارش کن. بنابراین، اگر دایرکتوری بالادست شامل پروژه‌های مختلف فراوانی است، و می‌خواهید فایل‌های تکراری در پروژه‌های مختلف در هر پروژه محاسبه شوند، این گزینه را انتخاب کنید.

.TP
.BI --autogen
فایل‌های کد مبدأیی را که به نظر می‌رسد به‌طور خودکار تولید شده‌اند شمارش کن. این فایل‌ها معمولاً نادیده گرفته می‌شوند.

.TP
.BI --multiproject
دایرکتوری‌های مختلف بیانگر پروژه‌های متفاوتی هستند؛ در غیر این صورت، فرض می‌شود تمام کدهای مبدأ متعلق به یک پروژهٔ واحد هستند. این گزینه تعداد کل فایل‌ها یا مقادیر SLOC را تغییر نمی‌دهد، اما بر برآوردهای تلاش و زمان‌بندی اثر می‌گذارد. با ارائهٔ این گزینه، تلاش به‌طور جداگانه برای هر پروژه محاسبه می‌شود (و سپس با هم جمع می‌شود)، و زمان‌بندی برابر با برآورد زمان‌بندی بزرگ‌ترین پروژه خواهد بود.

.TP
.BI --filecount
نمایش تعداد فایل‌ها به جای SLOC.

.TP
.BI --wide
نمایش در قالب \(lqعریض\(rq (جداسازی‌شده با تب).

.TP
.BI --details
نمایش جزئیات، یعنی نتایج به ازای هر فایل کد مبدأ.

.TP
.BI --effort " F E"
تغییر ضریب و توان برای مدل تلاش. میزان تلاش (بر حسب نفر-ماه) به‌صورت F*(SLOC/1000)^E محاسبه می‌شود.

.TP
.BI --schedule " F E"
تغییر ضریب و توان برای مدل زمان‌بندی. زمان‌بندی (بر حسب ماه) به‌صورت F*(effort)^E محاسبه می‌شود.

.TP
.BI --personcost " cost"
تغییر میانگین حقوق سالانه به
.IR cost .

.TP
.BI --overhead " overhead"
تغییر مقدار هزینهٔ بالاسری به
.IR overhead .
هزینهٔ تخمینی به‌صورت effort * personcost * overhead محاسبه می‌شود.

.TP
.BI --addlang " language"
افزودن زبانی که به‌طور پیش‌فرض به‌عنوان یک \(lqزبان\(rq برای گزارش‌دهی شناخته نمی‌شود. در حال حاضر تنها مقادیر مجاز برای language عبارت‌اند از \(lqmakefile\(rq، \(lqsql\(rq و \(lqhtml\(rq. این فایل‌ها معمولاً در شمارش‌های SLOC گنجانده نمی‌شوند، اگرچه مقدار SLOC آن‌ها به‌طور درونی محاسبه شده و در تعداد فایل‌ها نمایش داده می‌شوند. اگر می‌خواهید بیش از یک زبان از این دست را بگنجانید، این کار را با ارسال چندبارهٔ \fB--addlang\fR انجام دهید، مانند: \fB--addlang makefile --addlang sql\fR.

.TP
.BI --addlangall
افزودن تمام زبان‌هایی که به‌طور معمول در گزارش‌های نهایی لحاظ نمی‌شوند.

.SH "نکات (NOTES)"
همانند بسیاری از برنامه‌های دیگری که از گزینه‌های مشابه یونیکس استفاده می‌کنند، دایرکتوری‌هایی که نام آن‌ها با خط تیره (\(lq-\(rq) آغاز می‌شود ممکن است به‌اشتباه به‌عنوان گزینه تفسیر شوند. اگر ممکن است دایرکتوری‌های مورد تجزیه‌وتحلیل با خط تیره شروع شوند، پیش از فهرست کردن دایرکتوری‌ها، از خط تیرهٔ دوتایی (\(lq--\(rq) برای مشخص کردن پایان فهرست گزینه‌ها استفاده کنید.

.SH "گزارش باگ‌ها (BUGS)"
نام فایل‌هایی که خط جدید (newline) در آن‌ها قرار دارد (در دایرکتوری‌ها یا زیرمجموعه‌های آن‌ها) به‌درستی مدیریت نخواهند شد؛ آن‌ها در جاهایی که خط جدید درج شده است به‌صورت نام فایل‌های مجزا تفسیر می‌شوند. یک مهاجم می‌تواند با ایجاد نام فایل‌هایی به شکل /normal/directory ... NEWLINE/dev/zero مانع از کارکرد sloccount شود. چنین نام فایل‌هایی در کد مبدأ بسیار نادر هستند زیرا کار کردن با آن‌ها در سایر ابزارها نیز دردسرساز است. نسخه‌های آیندهٔ sloccount ممکن است برای حل این مشکل، در ساختار درونی خود از نام فایل‌های جداشده با NUL (مانند دستور \-print0 در GNU find) استفاده کنند.
.PP
زبان‌های بسیار دیگری نیز وجود دارند که هنوز توسط SLOCCount پشتیبانی نمی‌شوند.
.PP
ابزار SLOCCount تنها خطوط فیزیکی کد مبدأ را گزارش می‌کند. بسیار سودمند خواهد بود اگر بتواند خطوط منطقی کد و شاید سایر معیارهای متداول مانند معیارهای پیچیدگی مک‌کیب (McCabe) و چگالی پیچیدگی (پیچیدگی/SLOC برای هر تابع یا رویه) را نیز گزارش کند.

.SH "همچنین ببینید (SEE ALSO)"
به وب‌سایت SLOCCount در http://www.dwheeler.com/sloccount مراجعه کنید. توجه داشته باشید که مستندات مفصل‌تر هم در وب‌سایت و هم همراه با بستهٔ SLOCCount در دسترس است.

.SH "نویسندگان (AUTHORS)"
David A. Wheeler (dwheeler@dwheeler.com).